feat: 建立 SAM2 标注闭环基线

- 打通工作区真实标注闭环：支持手工多边形、矩形、圆形、点区域和线段生成 mask，并可保存、回显、更新和删除后端 annotation。

- 增强 polygon 编辑器：支持顶点拖动、顶点删除、边中点插入、多 polygon 子区域选择编辑，以及区域合并和区域去除。

- 接入 GT mask 导入：后端支持二值/多类别 mask 拆分、contour 转 polygon、distance transform seed point，前端支持导入、回显和 seed point 拖动编辑。

- 完善导出能力：COCO JSON 导出对齐前端，PNG mask ZIP 同时包含单标注 mask、按 zIndex 融合的 semantic_frame 和 semantic_classes.json。

- 打通异步任务管理：新增任务取消、重试、失败详情接口与 Dashboard 控件，worker 支持取消状态检查并通过 Redis/WebSocket 推送 cancelled 事件。

- 对接 Dashboard 后端数据：概览统计、解析队列和实时流转记录从 FastAPI 聚合接口与 WebSocket 更新。

- 增强 AI 推理参数：前端发送 crop_to_prompt、auto_filter_background 和 min_score，后端支持点/框 prompt 局部裁剪推理、结果回映射和负向点/低分过滤。

- 接入 SAM3 基础设施：新增独立 Python 3.12 sam3 环境安装脚本、外部 worker helper、后端桥接和真实 Python/CUDA/包/HF checkpoint access 状态检测。

- 保留 SAM3 授权边界：当前官方 facebook/sam3 gated 权重未授权时状态接口会返回不可用，不伪装成可推理。

- 增强前端状态管理：新增 mask undo/redo 历史栈、AI 模型选择状态、保存状态 dirty/draft/saved 流转和项目状态归一化。

- 更新前端 API 封装：补充 annotation CRUD、GT mask import、mask ZIP export、task cancel/retry/detail、AI runtime status 和 prediction options。

- 更新 UI 控件：ToolsPalette、AISegmentation、VideoWorkspace 和 CanvasArea 接入真实操作、导入导出、撤销重做、任务控制和模型状态。

- 新增 polygon-clipping 依赖，用于前端区域 union/difference 几何运算。

- 完善后端 schemas/status/progress：补充 AI 模型外部状态字段、任务 cancelled 状态和进度事件 payload。

- 补充测试覆盖：新增后端任务控制、SAM3 桥接、GT mask、导出融合、AI options 测试；补充前端 Canvas、Dashboard、VideoWorkspace、ToolsPalette、API 和 store 测试。

- 更新 README、AGENTS 和 doc 文档：冻结当前需求/设计/测试计划，标注真实功能、剩余 Mock、SAM3 授权边界和后续实施顺序。

doc/01-purpose-and-word-summary.md

@@ -38,21 +38,21 @@ Word 方案描述的理想系统包含：
 | 视频拆帧 | 已落地 | `backend/services/frame_parser.py`、`backend/routers/media.py` |
 | DICOM 批量导入 | 部分落地 | 上传和解析存在，项目级体验还需完善 |
 | WebSocket 进度 | 已落地 | 拆帧进度写入任务表后发布到 Redis `seg:progress`，FastAPI 广播到 `/ws/progress` |
-| SAM 推理 | 部分落地 | 后端已有 SAM 2 / SAM 3 选择和真实模型状态接口；SAM 3 依赖官方运行环境，当前环境不满足时会标为不可用 |
-| 模板库 | 部分落地 | 分类、颜色、z-index 能存储和编辑；重叠裁决算法未落地 |
-| 标注持久化 | 部分落地 | 后端有 `Annotation` 表，前端已接入新增、回显、分类更新和当前帧删除；逐点几何编辑未落地 |
-| COCO / Mask 导出 | 部分落地 | `backend/routers/export.py`；COCO JSON 前端按钮已接入，PNG mask ZIP 尚未提供前端按钮 |
+| SAM 推理 | 部分落地 | 后端已有 SAM 2 / SAM 3 选择和真实模型状态接口；SAM 3 通过独立 Python 3.12 环境桥接，状态会检查 Python/CUDA/包/HF gated 权重访问 |
+| 模板库 | 部分落地 | 分类、颜色、z-index 能存储和编辑；PNG mask 导出时会按 zIndex 做语义融合裁决，前端预览裁决尚未落地 |
+| 标注持久化 | 部分落地 | 后端有 `Annotation` 表，前端已接入新增、回显、分类更新、当前帧删除、手工绘制、GT mask 导入、seed point 编辑、polygon 顶点拖动/删除、边中点插点和多 polygon 子区域编辑；复杂洞结构编辑未落地 |
+| COCO / Mask 导出 | 已落地基础能力 | `backend/routers/export.py`；COCO JSON 和 PNG mask ZIP 前端按钮均已接入，ZIP 包含单标注 mask、语义融合 mask 和类别映射 |
 
 ## 当前代码尚未落地的目标
 
-- SAM 3：当前已提供 `sam3_engine.py` 适配入口和状态检测；要实际运行仍需安装官方 `facebookresearch/sam3` 依赖并满足 Python 3.12+、PyTorch 2.7+、CUDA 12.6+。
+- SAM 3：当前已提供 `sam3_engine.py` 外部环境桥接、`sam3_external_worker.py` 和 `setup_sam3_env.sh`；本机 `sam3` 环境已满足 Python 3.12、PyTorch 2.10/cu128、CUDA/GPU 和官方包导入。真实推理仍取决于 Hugging Face `facebook/sam3` gated 权重访问授权；官方没有 SAM 3 tiny/small 权重，当前可选最小真实 SAM 权重仍是 SAM 2 tiny。
 - Celery 异步任务队列：已注册 Celery app 和拆帧 worker task，`/api/media/parse` 会创建任务表记录并入队。
-- GT mask 导入：当前前端没有 GT Label 导入入口，后端也没有对应路由。
-- Mask 到点区域的拓扑降维：当前没有距离变换、骨架提取、HDBSCAN 等实现。
-- 类别优先级融合：模板有 z-index，但没有后端融合算法。
-- 撤销/重做：工具栏有按钮，但没有历史栈。
+- GT mask 导入：当前已支持二值/多类别 mask 导入，后端会按非零像素值拆分区域，生成 polygon 标注和距离变换 seed point；骨架提取、HDBSCAN 和模板自动映射尚未实现。
+- Mask 到点区域的拓扑降维：当前完成 distance transform seed point 和前端 seed point 拖拽编辑；骨架提取、HDBSCAN 等增强尚未实现。
+- 类别优先级融合：PNG mask 导出时已按 zIndex 生成语义融合 mask；前端裁决预览尚未实现。
+- 撤销/重做：当前已有全局 mask 历史栈。
 - 结构化归档保存：工作区按钮已调用 `POST /api/ai/annotate` 保存当前未归档 mask，并通过 `PATCH /api/ai/annotations/{id}` 更新 dirty mask。
 
 ## 结论
 
-当前项目已经从 UI 原型推进到“可上传、可异步拆帧、可实时查看任务进度、可浏览项目帧、可维护模板、可点/框 AI 推理、可保存标注、可导出 COCO、可查看 Dashboard 后端概览”的全栈雏形，但离 Word 中描述的完整智能标注系统还有明显差距。下一阶段最重要的是继续补齐手工绘制、撤销重做和真实语义文本分割。
+当前项目已经从 UI 原型推进到“可上传、可异步拆帧、可取消/重试任务、可查看失败详情、可实时查看任务进度、可浏览项目帧、可维护模板、可手工绘制、可逐点编辑 polygon、可边中点插点、可多 polygon 子区域编辑、可区域合并/去除、可点/框 AI 推理、可对点/框 prompt 做裁剪推理和背景过滤、可导入多类别 GT mask、可编辑 seed point、可保存标注、可导出 COCO/语义 mask ZIP、可查看 Dashboard 后端概览”的全栈雏形。下一阶段最重要的是继续补齐 Hugging Face SAM 3 权重授权后的真实语义文本分割 smoke test、复杂洞结构编辑和 GT mask 骨架/聚类增强。