支持中空mask编辑和传播保洞

- 前端按 polygonRingCounts 维护外圈/内洞 ring 分组，中空 mask 在调整多边形时显示内洞顶点和插点手柄。

- 保存与回显标注时将中空结构拆分为 mask_data.polygons 和 mask_data.holes，导入/普通 mask 共享同一编辑体验。

- 自动传播 seed 携带 holes，SAM 2 seed 栅格化时扣除内洞，避免中空 mask 以实心形式传播。

- 传播结果轮廓提取改为保留层级内洞，并在同步传播和 Celery 传播落库时写回 holes 与 hasHoles。

- 传播 seed 签名纳入 holes，并加固保存结果时 holes 与原始 polygon 索引对齐。

- 补充前端保存/回显、Canvas 内洞编辑和后端 SAM 2 hole 处理测试。

- 更新 AGENTS、接口契约、需求冻结、设计冻结和测试计划文档，移除中空结构未实现的旧描述。

doc/08-current-design-freeze.md

@@ -166,14 +166,14 @@
 2. 用户可以直接修改传播起始帧/结束帧数字框，并可通过工作区顶栏“传播权重”下拉独立选择本次传播使用的 SAM 2.1 tiny/small/base+/large 权重；该入口不提供 SAM2/SAM3 家族切换，默认跟随全局 AI 权重，用户手动选择后不再被 AI 页权重切换覆盖。
 3. `VideoWorkspace` 以当前参考帧为 seed，将起止帧拆成 `backward` 和/或 `forward` 两段；只包含当前帧时不传播。
 4. `VideoWorkspace` 在提交传播前会先调用现有归档保存链路保存当前项目中的 draft/dirty mask，并重新读取 store 中的回显结果；参考帧 seed 因此优先携带稳定的后端 `source_annotation_id`，避免用前端临时 mask id 生成传播结果后，二次传播无法找到旧结果。
-5. `VideoWorkspace` 用 `buildAnnotationPayload()` 把每个 seed mask 转成 normalized polygon、bbox、label、color、class 元数据、`source_mask_id` 和可用时的 `source_annotation_id`；如果 seed mask 是未编辑的自动传播结果，会沿用其原始 `source_annotation_id/source_mask_id/propagation_seed_signature`，让后端把它识别为原传播链的同一个 seed；如果该传播结果被编辑并保存，更新 payload 只保留 lineage，不保留旧签名，使后端按“已修改”路径清理旧结果并重传。对历史或外部写入的 `geometry_smoothing` metadata，payload 仍可透传给后端兼容处理；当前前端平滑应用会直接改写 polygon 几何并移除该参数。
+5. `VideoWorkspace` 用 `buildAnnotationPayload()` 把每个 seed mask 转成 normalized polygon、bbox、label、color、class 元数据、`source_mask_id` 和可用时的 `source_annotation_id`；中空 mask 会按 `metadata.polygonRingCounts` 将外圈写入 `mask_data.polygons`，把与外圈对齐的内洞写入 `mask_data.holes`，传播 seed 同步携带 `holes`；如果 seed mask 是未编辑的自动传播结果，会沿用其原始 `source_annotation_id/source_mask_id/propagation_seed_signature`，让后端把它识别为原传播链的同一个 seed；如果该传播结果被编辑并保存，更新 payload 只保留 lineage，不保留旧签名，使后端按“已修改”路径清理旧结果并重传。对历史或外部写入的 `geometry_smoothing` metadata，payload 仍可透传给后端兼容处理；当前前端平滑应用会直接改写 polygon 几何并移除该参数。
 6. 前端把传播权重 id、每个 seed、每个方向组装成 `steps`，一次调用 `POST /api/ai/propagate/task`，`include_source=false`、`save_annotations=true`；接口先规范化/校验 `model` 字段中的权重 id，再创建 `processing_tasks.task_type=propagate_masks` 并投递 Celery，避免长 HTTP 请求阻塞前端等待。
 7. `VideoWorkspace` 记录返回的 `task_id`，轮询 `GET /api/tasks/{task_id}` 显示任务 message、步骤进度、已处理帧次和已保存区域数；任务运行期间提供取消传播按钮，调用通用 `POST /api/tasks/{task_id}/cancel`。
 8. Celery worker 逐 step 顺序执行传播，避免多个视频 tracker 并发抢占 GPU；每个 step 开始/完成都会写入 `processing_tasks.progress/result/message` 并发布 Redis `seg:progress`，Dashboard 可同步显示。每个 step 开始前，worker 会在本次目标帧段内用 seed 来源 id、传播方向和 seed 签名查找旧传播标注：同权重、签名相同且目标帧都已有结果时跳过该 seed；签名不同、目标帧只部分覆盖或本次使用了其他 SAM 2.1 权重则先删除本次目标帧段内对应方向的旧自动传播标注，再执行新的 video predictor 传播；若历史 seed 签名中包含 `geometry_smoothing`，仍按完整签名参与兼容去重。对旧版本只记录前端临时 `source_mask_id` 的传播标注，worker 会按 label/color/class 做兼容匹配，确保可被后续稳定 `source_annotation_id` 的传播替换；对中间帧人工新增的替代 seed，若缺少旧 source id，worker 仍会用语义信息识别候选旧传播结果，并在写入目标帧新 polygon 前用目标帧 bbox 重叠做二次确认和清理。写入前这层清理不限制旧结果方向，确保 backward 传播可覆盖早先 forward 传播留下的同物体旧 mask。
 9. 后端按项目帧序列截取片段，下载对应帧到临时目录，并写成 `000000.jpg` 这类纯数字文件名；这是 `SAM2VideoPredictor` 对视频帧排序的要求，和项目库中持久化的 `frame_%06d.jpg` 对象名无关。
-10. `model` 为任一 SAM 2.1 权重变体时，`sam2_engine` 使用对应 checkpoint/config 加载 `SAM2VideoPredictor.add_new_mask()` 注入 seed mask，再用 `propagate_in_video()` 传播；`model=sam2` 会在入队时规范化为 tiny，任务 payload/result 会保留规范化后的权重 id；单个 SAM2 video predictor 调用内部暂不提供逐帧流式进度。
+10. `model` 为任一 SAM 2.1 权重变体时，`sam2_engine` 使用对应 checkpoint/config 加载 `SAM2VideoPredictor.add_new_mask()` 注入 seed mask，再用 `propagate_in_video()` 传播；注入 seed 前会把外圈 polygon 栅格化为前景，再按 `holes` 扣除内洞，避免中空参考 mask 以实心形式传播；`model=sam2` 会在入队时规范化为 tiny，任务 payload/result 会保留规范化后的权重 id；单个 SAM2 video predictor 调用内部暂不提供逐帧流式进度。
 11. `model=sam3` 当前不支持；SAM 3 video tracker 代码保留但没有接入产品路径。
-12. 后端把传播返回的 normalized polygon 保存为后续帧 `Annotation`，跳过源帧；如果历史或外部 seed 带 `geometry_smoothing`，保存前仍会用同一平滑参数处理 forward/backward 两个方向的结果：强度先经过缓入曲线映射，低强度使用较小 Chaikin 切角比例和简化阈值，高强度再逐步增加迭代、切角和简化力度；随后按强度对 SAM 密集轮廓做 `approxPolyDP` 去噪简化，再做 Chaikin 平滑，最后二次简化并以平滑后的 polygon 计算 bbox 后落库。当前工作区“应用边缘平滑”会在前端把同传播链对应 mask 直接改写为新的 polygon 并移除 `geometry_smoothing` 参数，因此后续传播通常按新几何本身参与 seed 签名。`mask_data.source` 记录权重传播来源，同时写入 `propagation_seed_key`、`propagation_seed_signature`、`propagation_direction`、`source_annotation_id` 和 `source_mask_id` 供后续幂等传播判断；历史 `geometry_smoothing` 仅在存在时保留用于兼容判断。
+12. 后端把传播返回的 normalized polygon 保存为后续帧 `Annotation`，跳过源帧；传播 mask 轮廓提取使用层级信息保留内洞，外圈写入 `mask_data.polygons`，内洞按外圈对齐写入 `mask_data.holes`，并设置 `metadata.hasHoles` 供前端按中空 mask 回显和编辑；如果历史或外部 seed 带 `geometry_smoothing`，保存前仍会用同一平滑参数处理 forward/backward 两个方向的结果：强度先经过缓入曲线映射，低强度使用较小 Chaikin 切角比例和简化阈值，高强度再逐步增加迭代、切角和简化力度；随后按强度对 SAM 密集轮廓做 `approxPolyDP` 去噪简化，再做 Chaikin 平滑，最后二次简化并以平滑后的 polygon 计算 bbox 后落库。当前工作区“应用边缘平滑”会在前端把同传播链对应 mask 直接改写为新的 polygon 并移除 `geometry_smoothing` 参数，因此后续传播通常按新几何本身参与 seed 签名。`mask_data.source` 记录权重传播来源，同时写入 `propagation_seed_key`、`propagation_seed_signature`、`propagation_direction`、`source_annotation_id` 和 `source_mask_id` 供后续幂等传播判断；历史 `geometry_smoothing` 仅在存在时保留用于兼容判断。
 13. 前端轮询到已创建区域后刷新 `GET /api/ai/annotations` 并回显新标注；任务结束后如果后端返回 0 个新区域，工作区会明确提示没有生成新的 mask，若是未改变 seed 被跳过则提示未改变 mask 已跳过。处理过帧次大于 0 的成功任务会追加一条本地传播历史片段，用于视频处理进度条显示最近传播范围；`annotationToMask()` 会保留传播来源 metadata，供时间轴视频处理进度条显示蓝色传播区段。
 
 ### 手工绘制与历史栈
@@ -208,8 +208,8 @@
 4. 布尔选择态按选择顺序区分角色：第一个选中的主区域使用黄色实线轮廓，后续参与合并/扣除的区域使用红色虚线轮廓；所有已选区域填充透明度保持一致，避免被误解为阴影模式异常。
 5. `CanvasArea` 把 `Mask.segmentation` 转为 `polygon-clipping` 的 MultiPolygon。
 6. `area_merge` 使用 union，更新第一个选中的主 mask，并从前端 store 移除后续被合并 mask；如果被移除 mask 已保存，会调用工作区传入的删除回调删除后端标注；被移除 mask 的同链自动传播结果也会一并删除。
-7. `area_remove` 使用 difference，从第一个选中的主 mask 中扣除后续选中 mask，扣除对象本身保留；如果 difference 产生内洞，`segmentation` 保留外圈和 hole ring，渲染时使用 even-odd fill。
-8. 结果会重算 `pathData`、`segmentation`、`bbox`、`area`，已保存主 mask 会进入 dirty 状态并复用归档 PATCH 链路；带洞结果的面积按外圈减内洞计算。
+7. `area_remove` 使用 difference，从第一个选中的主 mask 中扣除后续选中 mask，扣除对象本身保留；如果 difference 产生内洞，`segmentation` 保留外圈和 hole ring，`metadata.polygonRingCounts` 记录每个 polygon 的 ring 数，渲染时使用 even-odd fill。
+8. 结果会重算 `pathData`、`segmentation`、`bbox`、`area`，已保存主 mask 会进入 dirty 状态并复用归档 PATCH 链路；带洞结果的面积按外圈减内洞计算；进入调整多边形时，外圈和内洞 ring 都会显示顶点和边中点插入手柄，内洞拖动、插点、保存与回显继续保持中空结构。
 
 ### GT Mask 导入
 
@@ -218,7 +218,7 @@
 3. 后端验证项目、帧、模板后使用 OpenCV 读取灰度 mask。
 4. 后端按非零像素值拆分多类别标签。
 5. 后端对每个类别的前景做高精度 contour 提取，每个连通域保存为一个 `Annotation`；轮廓使用未压缩链提取并以较小 `approxPolyDP` epsilon 保留细节，超过点数上限时才逐步增加简化强度或抽样。
-6. `points` 字段可保存距离变换中心 seed point 供数据兼容，`mask_data.polygons` 保存 normalized polygon，`mask_data.gt_label_value` 保存原始像素类别值；导入后的 polygon 与普通 mask 走同一套拓扑锚点统计、边缘平滑、编辑和保存链路。
+6. `points` 字段可保存距离变换中心 seed point 供数据兼容，`mask_data.polygons` 保存 normalized polygon，`mask_data.holes` 保存与外圈对齐的内洞，`mask_data.gt_label_value` 保存原始像素类别值；导入后的 polygon 与普通 mask 走同一套拓扑锚点统计、边缘平滑、编辑和保存链路。
 7. 前端重新读取项目标注并回显。
 8. `annotationToMask()` 仍可把后端 `points` 转成像素坐标保存在 mask 数据中，但 Canvas 不显示 seed point，也不提供拖动；普通 polygon 若没有后端 seed point，保存逻辑可按 polygon 自动计算内部代表点写入，以保持数据兼容。
 
@@ -297,7 +297,7 @@
 以下能力属于当前冻结版本的占位或半可用功能：
 
 - Dashboard 初始快照来自 `GET /api/dashboard/overview`；任务进度区由 `processing_tasks` queued/running/success/failed/cancelled 任务生成，处理中统计只计算 queued/running。
-- 已保存标注支持通过“应用分类”、polygon 顶点拖动/删除、边中点插入、多 polygon 子区域编辑和区域合并/去除进入 dirty 状态并归档更新；选中整块 mask 可用 Delete/Backspace 删除并同步后端，同传播链自动传播结果会随传播 seed/传播结果删除而一并清理，独立 AI 推理/人工 mask 保留；复杂洞结构编辑尚未实现。
+- 已保存标注支持通过“应用分类”、polygon 顶点拖动/删除、边中点插入、多 polygon 子区域编辑、中空 mask 内洞 ring 编辑和区域合并/去除进入 dirty 状态并归档更新；选中整块 mask 可用 Delete/Backspace 删除并同步后端，同传播链自动传播结果会随传播 seed/传播结果删除而一并清理，独立 AI 推理/人工 mask 保留。
 - SAM 3 文本语义分割已从当前产品路径中禁用；相关源码保留，恢复时需要重新接入前端入口、registry、状态接口和测试。
 - 自定义分类通过 `PATCH /api/templates/{id}` 写入当前激活模板的 `mapping_rules.classes`。
 - 选中 mask 后，本体面板的“特定目标实例属性追踪”标题值来自当前 mask 的 `className/label`，不使用全局 active class；面板不再展示长期为 1 的“当前选中区域”计数；面板调用 `POST /api/ai/analyze-mask` 自动显示拓扑锚点数量等属性，`topology_anchor_count` 是真实 polygon 顶点数量，`topology_anchors` 只保留最多 64 个抽样点用于调试展示；`OntologyInspector` 会为分析请求维护递增序号，旧请求返回时不再回写状态，并静默忽略 Axios abort/cancel 错误，避免快速切换、平滑预览或组件卸载时把正常中止误报成失败；不再提供“重新提取拓扑锚点”调试按钮；“边缘平滑强度”滑杆会即时更新数值，但 `POST /api/ai/smooth-mask` 预览请求经过约 220ms 防抖后才发送，返回 polygon 作为临时预览写入当前 mask 显示，预览不改变保存状态；点击“应用边缘平滑”后，前端把平滑 polygon 作为新的实际几何写入当前 mask，并按传播 lineage 同步写入传播链前后对应 mask，相关 mask 标记为 dirty/draft，整次操作通过一次 `setMasks()` 进入撤销/重做历史；应用后不保留 `geometry_smoothing` 参数，平滑强度重置为 0。前端不再展示“后端模型置信度”。