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 骨架/聚类增强。

doc/02-current-implementation-map.md

@@ -71,6 +71,7 @@
 5. Celery worker 下载 MinIO 文件，调用 `frame_parser.py` 拆帧。
 6. worker 把拆出的帧重新上传 MinIO，写入 `frames` 表，并更新任务状态。
 7. 工作区通过 `GET /api/tasks/{id}` 等待任务完成，再通过 `GET /api/projects/{id}/frames` 获取预签名图片 URL。
+8. Dashboard 可通过 `POST /api/tasks/{id}/cancel` 取消 queued/running 任务，通过 `POST /api/tasks/{id}/retry` 重试 failed/cancelled 任务，并用 `GET /api/tasks/{id}` 查看失败详情。
 
 ### 工作区浏览
 
@@ -98,7 +99,7 @@
 ## 当前主要风险点
 
 - 前端 API/WS 地址虽然已支持环境变量和 hostname 推导，但部署时仍需要确认浏览器可访问 `:8000` 后端。
-- AI 语义文本提示在选择 SAM 3 且运行环境满足官方依赖时走 SAM 3；当前环境若不满足会在模型状态中标明不可用。
-- 工作区顶部“导出 JSON 标注集”和“结构化归档保存”已接入导出、标注新增和 dirty 标注更新；清空当前帧遮罩会删除对应后端标注。撤销重做和手工绘制仍未持久化。
-- Dashboard 初始统计、队列和活动日志来自后端聚合接口；解析队列来自 `processing_tasks`，worker 进度通过 Redis `seg:progress` 转发到 WebSocket。
+- AI 语义文本提示在选择 SAM 3 且运行环境满足官方依赖、并具备 Hugging Face gated 权重访问时走 SAM 3；当前状态接口会分别暴露外部 Python 环境、CUDA、包导入和 checkpoint access 是否满足。
+- 工作区顶部“导出 JSON 标注集”“导出 PNG Mask ZIP”“导入 GT Mask”和“结构化归档保存”已接入导出、GT 多类别导入、seed point 回显/编辑、标注新增和 dirty 标注更新；清空当前帧遮罩会删除对应后端标注。手工绘制、polygon 顶点拖动/删除、区域合并/去除和撤销重做已经落到前端 mask 数据结构。
+- Dashboard 初始统计、队列和活动日志来自后端聚合接口；解析队列来自 `processing_tasks`，worker 进度通过 Redis `seg:progress` 转发到 WebSocket。任务取消、重试和失败详情已接入前后端。
 - 后端路由大多未做真实鉴权。

doc/03-frontend-element-audit.md

@@ -30,8 +30,11 @@
 | 元素 | 状态 | 说明 |
 |------|------|------|
 | WebSocket 连接状态 | 真实可用 | 前端通过 `src/lib/config.ts` 推导或读取 `VITE_WS_PROGRESS_URL`，后端有 `/ws/progress` |
-| 解析队列任务 | 真实可用 | 初始数据来自 `GET /api/dashboard/overview`，按 `processing_tasks` queued/running 任务生成 |
-| WebSocket 更新任务 | 真实可用 | Celery worker 更新 `processing_tasks` 后发布 Redis `seg:progress`，FastAPI 广播 progress/complete/error |
+| 解析队列任务 | 真实可用 | 初始数据来自 `GET /api/dashboard/overview`，按 `processing_tasks` queued/running/failed/cancelled 任务生成 |
+| 任务取消 | 真实可用 | queued/running 任务显示取消按钮，调用 `POST /api/tasks/{task_id}/cancel` |
+| 任务重试 | 真实可用 | failed/cancelled 任务显示重试按钮，调用 `POST /api/tasks/{task_id}/retry` 创建新任务 |
+| 失败详情 | 真实可用 | 任务详情按钮调用 `GET /api/tasks/{task_id}`，弹窗展示 error、payload、result、Celery ID 和时间 |
+| WebSocket 更新任务 | 真实可用 | Celery worker 更新 `processing_tasks` 后发布 Redis `seg:progress`，FastAPI 广播 progress/complete/error/cancelled |
 | 项目、任务、标注、系统负载统计 | 真实可用 | 初始数据来自 `GET /api/dashboard/overview`，系统负载按主机 load average 估算 |
 | 近期实时流转记录 | 真实可用 | 初始数据来自任务、项目、标注和模板记录；WebSocket status/complete/error 会继续追加 |
 
@@ -60,6 +63,8 @@
 | SAM 模型状态徽标 | 真实可用 | 调用 `GET /api/ai/models/status`，显示当前选择的 SAM 2/SAM 3 是否可用 |
 | 已保存标注回显 | 真实可用 | 加载工作区帧后调用 `GET /api/ai/annotations` 并渲染已保存 mask |
 | “导出 JSON 标注集”按钮 | 真实可用 | 导出前会保存未归档 mask，然后调用 `exportCoco()` 下载 JSON |
+| “导出 PNG Mask ZIP”按钮 | 真实可用 | 导出前会保存未归档 mask，然后调用 `GET /api/export/{project_id}/masks` 下载 ZIP；后端同时包含单标注 mask、每帧语义融合 mask 和 `semantic_classes.json` |
+| “导入 GT Mask”按钮 | 真实可用 | 选择图片后调用 `POST /api/ai/import-gt-mask`，后端按非零像素值和连通域生成 polygon 标注与距离变换 seed point，再回显到工作区 |
 | “结构化归档保存”按钮 | 真实可用 | 未保存 mask 写入 `POST /api/ai/annotate`；dirty mask 写入 `PATCH /api/ai/annotations/{id}` |
 
 ## CanvasArea 画布
@@ -70,10 +75,13 @@
 | 滚轮缩放 | 真实可用 | 改变 Konva Stage scale |
 | 拖拽平移 | 真实可用 | activeTool 为 `move` 时 Stage draggable |
 | 光标坐标显示 | 真实可用 | 根据 pointer position 计算 |
-| 正向/反向选点 | 部分可用 | UI 能加点，并按当前帧 `frame.id` 调用 `/api/ai/predict`；需点击归档保存才持久化 |
-| 框选 | 部分可用 | UI 能画框，并把框坐标归一化后调用后端推理；需点击归档保存才持久化 |
+| 正向/反向选点 | 真实可用 | UI 能加点，并按当前帧 `frame.id` 调用 `/api/ai/predict`；结果需点击归档保存才持久化 |
+| 框选 | 真实可用 | UI 能画框，并把框坐标归一化后调用后端推理；结果需点击归档保存才持久化 |
 | AI 推理中提示 | 真实可用 | 请求期间会显示 |
-| Mask 渲染 | 部分可用 | 前端会把推理/已保存标注转成 Konva `pathData` 渲染 |
+| 手工多边形/矩形/圆/点/线 | 真实可用 | 多边形点击取点后 Enter 完成；矩形/圆/线拖拽生成 polygon；点工具生成小区域；均写入 `Mask.segmentation`，可归档保存 |
+| Mask 渲染 | 真实可用 | 前端会把推理、手工绘制、GT 导入和已保存标注转成 Konva `pathData` 渲染 |
+| Polygon 逐点编辑 | 真实可用 | 点击 mask 后显示 polygon 顶点；拖动顶点会重算 `pathData/segmentation/bbox/area`，已保存 mask 标为 dirty；选中顶点后 Delete/Backspace 可删点但保留至少三点 |
+| GT seed point 回显/编辑 | 真实可用 | 已保存标注的 `points` 会显示为黄色 seed 点；拖动后标记为 dirty，归档保存会更新后端 |
 | 应用分类 | 真实可用 | 将当前选择的模板分类应用到本帧 mask；已保存 mask 会标为 dirty，归档保存时更新后端 |
 | 清空遮罩 | 真实可用 | 工作区中会删除当前帧已保存标注并清空当前帧本地 mask |
 | 保存状态计数 | 真实可用 | 底部显示已保存、未保存、待更新数量 |
@@ -84,11 +92,11 @@
 | 元素 | 状态 | 说明 |
 |------|------|------|
 | 拖拽/选择 | 真实可用 | 控制 Canvas 是否可拖拽 |
-| 多边形/矩形/圆/点/线 | Mock / UI-only | 只切换 activeTool，没有对应绘制逻辑 |
-| 区域合并/去除 | Mock / UI-only | 只切换 activeTool，没有后端或前端算法 |
+| 多边形/矩形/圆/点/线 | 真实可用 | 切换 activeTool 后由 `CanvasArea` 生成可保存的 polygon mask |
+| 区域合并/去除 | 真实可用 | 选择工具后点击多个 mask，使用 `polygon-clipping` 做 union / difference；合并会保留主 mask 并移除被合并 mask，去除会从主 mask 扣除后续选中 mask |
 | 正向选点/反向选点/框选 | 部分可用 | 会影响 Canvas 交互，并能触发已对齐的 AI 推理接口 |
 | 魔法棒 SAM 触发 | 部分可用 | 切到 AI 页面；不是直接执行推理 |
-| 撤销/重做 | Mock / UI-only | 按钮无事件 |
+| 撤销/重做 | 真实可用 | 绑定 Zustand `maskHistory/maskFuture`，支持工具栏按钮、AI 页按钮和 Canvas Ctrl+Z/Ctrl+Y |
 
 ## FrameTimeline 时间轴
 
@@ -117,10 +125,11 @@
 |------|------|------|
 | 模型选择 SAM2/SAM3 | 真实可用 | 选择写入 Zustand，`predictMask()` 会把 `model` 传给后端 SAM registry |
 | 正向/反向点 | 部分可用 | 可在当前项目帧上加点，并可调用 AI 推理接口 |
-| 语义文本输入 | 部分可用 | 纯文本会以 `semantic` prompt 调用后端；选择 SAM 3 且运行环境满足官方依赖时走 SAM 3 文本语义推理，否则状态接口会标明不可用 |
-| 参数开关 | Mock / UI-only | `cropMode`、`autoDeleteBg` 只改本地状态 |
+| 语义文本输入 | 部分可用 | 纯文本会以 `semantic` prompt 调用后端；选择 SAM 3 且独立 Python 3.12 环境、CUDA、官方包和 Hugging Face gated 权重访问均满足时走 SAM 3 文本语义推理，否则状态接口会标明不可用 |
+| 参数开关 | 真实可用 | `cropMode` 会随 `/api/ai/predict` 发送 `crop_to_prompt`，后端对点/框 prompt 裁剪推理区域并回映射 polygon；`autoDeleteBg` 会发送 `auto_filter_background` 和 `min_score`，后端过滤低分结果和覆盖负向点的结果 |
 | 执行高精度语义分割 | 部分可用 | 使用当前项目帧调用 `/api/ai/predict`；没有当前帧时按钮禁用 |
 | 上传替换底图 | Mock / UI-only | 按钮无事件 |
+| 撤销/重做 | 真实可用 | 绑定全局 mask 历史栈 |
 | 清空全体锚点 | 部分可用 | 清空前端 points 和 masks |
 | 退档推送至工作区重组 | 部分可用 | 只切回工作区，共用 masks store，但没有保存/确认流程 |
 | 背景图 | 部分可用 | 优先显示当前项目帧；没有项目帧时仍回退到 Unsplash 演示图 |
@@ -141,6 +150,6 @@
 
 ## 总体结论
 
-当前前端真实可用的主链路是：登录、Dashboard 后端概览、项目列表、新建项目、上传视频/DICOM、拆帧、浏览帧、播放帧、工作区点/框 AI 推理、标注保存/回显、COCO 导出、模板 CRUD。
+当前前端真实可用的主链路是：登录、Dashboard 后端概览、项目列表、新建项目、上传视频/DICOM、拆帧、浏览帧、播放帧、工作区手工绘制、点/框 AI 推理、GT mask 导入、标注保存/回显、COCO 导出、PNG mask ZIP 导出、模板 CRUD。
 
-当前最主要的 Mock 或未打通链路是：撤销重做、手工几何绘制、GT 导入、mask 降维点区域、真正的文本语义分割和语义优先级融合。
+当前最主要的 Mock 或未打通链路是：polygon 插点/边编辑增强、真正的文本语义分割、骨架/HDBSCAN 级别的 mask 降维增强、任务历史筛选、项目更多菜单和若干检查面板指标。

doc/04-api-contracts.md

@@ -34,6 +34,8 @@ Authorization: Bearer <token>
 | `uploadDicomBatch(files, projectId)` | `POST /api/media/upload/dicom` | 对齐 | multipart form-data |
 | `parseMedia(projectId)` | `POST /api/media/parse?project_id=...` | 对齐 | 创建异步拆帧任务并返回 task |
 | `getTask(taskId)` | `GET /api/tasks/{task_id}` | 对齐 | 查询异步任务状态 |
+| `cancelTask(taskId)` | `POST /api/tasks/{task_id}/cancel` | 对齐 | 取消 queued/running 任务，后端写 cancelled 并尝试 revoke Celery |
+| `retryTask(taskId)` | `POST /api/tasks/{task_id}/retry` | 对齐 | 对 failed/cancelled 任务创建新的 queued 重试任务 |
 | `getProjectFrames(projectId)` | `GET /api/projects/{id}/frames` | 对齐 | 后端返回预签名 image_url |
 | `predictMask(payload)` | `POST /api/ai/predict` | 对齐 | 前端发送 `image_id/prompt_type/prompt_data/model`，并把后端 `polygons` 转为 `masks[].pathData` |
 | `getAiModelStatus(selectedModel?)` | `GET /api/ai/models/status` | 对齐 | 返回 GPU、SAM 2、SAM 3 的真实运行状态 |
@@ -41,8 +43,10 @@ Authorization: Bearer <token>
 | `saveAnnotation(payload)` | `POST /api/ai/annotate` | 对齐 | 工作区归档保存当前项目未保存 mask |
 | `updateAnnotation(annotationId, payload)` | `PATCH /api/ai/annotations/{annotation_id}` | 对齐 | 工作区归档保存 dirty mask |
 | `deleteAnnotation(annotationId)` | `DELETE /api/ai/annotations/{annotation_id}` | 对齐 | 工作区清空当前帧已保存标注 |
+| `importGtMask(file, projectId, frameId, templateId?)` | `POST /api/ai/import-gt-mask` | 对齐 | multipart 上传 GT mask，后端按非零像素值/连通域生成 polygon 标注和 seed point |
 | `getDashboardOverview()` | `GET /api/dashboard/overview` | 对齐 | Dashboard 初始统计、队列和活动日志 |
 | `exportCoco(projectId)` | `GET /api/export/{projectId}/coco` | 对齐 | 后端实际是 `GET /api/export/{project_id}/coco` |
+| `exportMasks(projectId)` | `GET /api/export/{projectId}/masks` | 对齐 | 下载单标注 mask、语义融合 mask 和类别映射 ZIP |
 
 ## 后端 FastAPI 接口
 
@@ -69,10 +73,13 @@ Authorization: Bearer <token>
 | POST | `/api/media/parse` | 创建 Celery 拆帧任务 |
 | GET | `/api/tasks` | 查询后台任务列表 |
 | GET | `/api/tasks/{task_id}` | 查询单个后台任务 |
+| POST | `/api/tasks/{task_id}/cancel` | 取消后台任务 |
+| POST | `/api/tasks/{task_id}/retry` | 重试失败或取消的后台任务 |
 | POST | `/api/ai/predict` | SAM 2 / SAM 3 可选推理 |
 | GET | `/api/ai/models/status` | GPU 和 SAM 模型状态 |
 | POST | `/api/ai/auto` | 自动分割 |
 | POST | `/api/ai/annotate` | 保存 AI 标注 |
+| POST | `/api/ai/import-gt-mask` | 导入 GT mask 并生成标注/seed point |
 | GET | `/api/ai/annotations` | 查询项目标注，可选按帧过滤 |
 | PATCH | `/api/ai/annotations/{annotation_id}` | 更新已保存标注 |
 | DELETE | `/api/ai/annotations/{annotation_id}` | 删除已保存标注 |
@@ -143,7 +150,13 @@ Authorization: Bearer <token>
 
 - `point`
 - `box`
-- `semantic`，选择 `sam3` 时进入 SAM 3 文本语义推理；选择 `sam2` 时仍回退到 auto segmentation
+- `semantic`，选择 `sam3` 时进入 SAM 3 文本语义推理；选择 `sam2` 时仍回退到 auto segmentation。SAM 3 真实可用性由 `/api/ai/models/status` 中的外部环境和 checkpoint access 状态决定。
+
+可选 `options` 字段：
+
+- `crop_to_prompt`：对 point/box prompt 按锚点或框附近区域裁剪后推理，再把 polygon 回映射到原图坐标。
+- `auto_filter_background`：过滤低分结果，并移除包含负向点的 polygon。
+- `min_score`：配合 `auto_filter_background` 使用的最低置信度阈值。
 
 后端响应：
 
@@ -181,13 +194,19 @@ Authorization: Bearer <token>
 - `getProjectAnnotations()` 已接入 `GET /api/ai/annotations`。
 - `updateAnnotation()` 已接入 `PATCH /api/ai/annotations/{annotationId}`。
 - `deleteAnnotation()` 已接入 `DELETE /api/ai/annotations/{annotationId}`。
+- `importGtMask()` 已接入 `POST /api/ai/import-gt-mask`，导入后端生成的 polygon 标注、原始 `gt_label_value` 和 seed point。
+- `exportMasks()` 已接入 `GET /api/export/{projectId}/masks`。
 - `parseMedia()` 已改为创建 Celery 后台任务，并返回 `ProcessingTask`。
 - `getTask()` 已接入 `GET /api/tasks/{taskId}`。
+- `cancelTask()` 已接入 `POST /api/tasks/{taskId}/cancel`。
+- `retryTask()` 已接入 `POST /api/tasks/{taskId}/retry`。
 - `getDashboardOverview()` 已从 `processing_tasks` 聚合解析队列。
-- 工作区导出按钮已调用 `exportCoco()`，并会先保存未归档 mask。
+- Dashboard 任务列表已展示 queued/running/failed/cancelled 任务，并可通过 `getTask()` 查看失败详情。
+- 工作区导出按钮已调用 `exportCoco()` / `exportMasks()`，并会先保存未归档 mask。
+- PNG mask ZIP 已包含每帧 `semantic_frame_*.png` 和 `semantic_classes.json`，重叠区域按 zIndex 裁决。
 
 ## 仍需处理的接口问题
 
 - WebSocket 地址已从 `VITE_WS_PROGRESS_URL` 读取，未配置时从 `API_BASE_URL` 推导；部署时仍要确认浏览器能访问该地址。
 - Celery worker 进度会写 PostgreSQL 任务表，同时发布到 Redis `seg:progress`；FastAPI 订阅后广播到 `/ws/progress`。
-- 已保存标注目前支持分类级更新和整帧清空删除；逐点几何编辑器尚未实现。
+- 已保存标注目前支持分类级更新、polygon 顶点拖动、顶点删除、边中点插入、多 polygon 子区域选择编辑后的 PATCH 更新和整帧清空删除；复杂洞结构的专业编辑仍未实现。

doc/05-implementation-plan.md

@@ -16,8 +16,8 @@
 
 剩余边界：
 
-1. SAM 3 真实推理需要独立满足官方 Python 3.12+、PyTorch 2.7+、CUDA 12.6+ 环境。
-2. 标注删除/更新接口已打通基础能力；逐点几何编辑器尚未实现。
+1. SAM 3 已完成独立 Python 3.12 环境安装脚本、外部 worker 桥接和状态检查；真实推理还需要 Hugging Face `facebook/sam3` gated 权重授权通过后执行 smoke test。
+2. 标注删除/更新接口已打通基础能力；逐点几何编辑器已支持顶点拖动/删除、边中点插入和多 polygon 子区域选择编辑，复杂洞结构仍待增强。
 
 ## 阶段 2：打通标注保存（已完成基础闭环）
 
@@ -34,16 +34,22 @@
 剩余建议：
 
 1. 加入保存冲突处理和批量保存错误提示。
-2. 增加逐点几何编辑器，让已保存 mask 的 polygon 本身可以被修改后 PATCH。
+2. 逐点几何编辑器已支持拖动/删除顶点、边中点插入新点和多 polygon 子区域编辑；后续增强为复杂洞结构编辑。
+3. 区域合并/去除已支持基础 union/difference；后续增强为更明确的多选列表、操作预览和冲突确认。
 
-## 阶段 3：接入导出按钮（已完成 COCO JSON）
+## 阶段 3：接入导出按钮（已完成 COCO JSON 和 PNG Mask ZIP）
 
-当前工作区“导出 JSON 标注集”会先保存未归档 mask，再调用 COCO 导出接口。
+当前工作区“导出 JSON 标注集”和“导出 PNG Mask ZIP”都会先保存未归档 mask，再调用后端导出接口。
 
-建议：
+已完成：
 
-1. 增加“导出 PNG Mask ZIP”按钮，调用 `/api/export/{projectId}/masks`。
-2. 无标注时给出更明确的空导出提示。
+1. COCO JSON 调用 `/api/export/{projectId}/coco`。
+2. PNG Mask ZIP 调用 `/api/export/{projectId}/masks`。
+3. ZIP 内保留单标注二值 `mask_*.png`，同时输出 `semantic_frame_*.png` 和 `semantic_classes.json`。
+
+剩余建议：
+
+1. 无标注时给出更明确的空导出提示。
 
 ## 阶段 4：替换 Dashboard mock
 
@@ -52,13 +58,18 @@
 已完成：
 
 - 聚合项目、帧、标注、模板数量和主机 load average。
-- 按 `processing_tasks` queued/running 任务生成解析队列。
+- 按 `processing_tasks` queued/running/failed/cancelled 任务生成解析队列。
 - 按最近任务、项目、标注、模板记录生成活动流。
 
+已完成补充：
+
+1. Dashboard 对 queued/running 任务提供取消按钮。
+2. Dashboard 对 failed/cancelled 任务提供重试按钮。
+3. Dashboard 详情弹窗展示任务 error、payload、result、Celery ID 和时间。
+
 剩余建议：
 
-1. 为任务增加取消、重试和失败详情 UI。
-2. 为 Dashboard 增加任务历史筛选和失败详情入口。
+1. 为 Dashboard 增加任务历史筛选。
 
 ## 阶段 5：异步拆帧和进度
 
@@ -72,44 +83,55 @@ Word 方案中提到 Celery + Redis。当前已经有 Celery app、worker task
 4. worker 写 PostgreSQL 任务进度。
 5. worker 发布 Redis `seg:progress`，FastAPI 广播到 `/ws/progress`。
 
+已完成补充：
+
+1. `POST /api/tasks/{task_id}/cancel` 取消 queued/running 任务，并尝试 revoke Celery。
+2. `POST /api/tasks/{task_id}/retry` 为 failed/cancelled 任务创建新的 queued 任务。
+3. worker 在关键阶段检查 cancelled 状态，避免取消后继续写帧。
+4. Redis/WebSocket 进度事件增加 `cancelled` 类型。
+
+Dashboard 的解析队列现在已经从“项目状态派生”升级为任务表驱动，实时推送也已通过 Redis/WebSocket 打通；剩余重点是任务历史筛选和更细的 worker 中断粒度。
+
+## 阶段 6：GT 导入与点区域（已完成基础增强版）
+
+Word 方案中的完整版本包含距离变换、骨架提取和聚类。当前已经完成基础增强版：导入二值/标签 mask 图片后，后端按非零像素值拆分类别，再按连通域生成 polygon 标注，并用距离变换提取一个正向 seed point。
+
+已完成：
+
+1. 工作区提供“导入 GT Mask”入口。
+2. 前端调用 `POST /api/ai/import-gt-mask` multipart 接口。
+3. 后端按非零像素值拆分多类别 mask。
+4. 后端使用 OpenCV contour 提取每个类别下的连通域。
+5. 后端使用 distance transform 生成 `points` seed。
+6. 导入结果写入 `annotations` 表并回显为工作区 mask。
+7. 前端把 seed point 转为像素坐标显示在 Canvas 上，拖动后会标记标注为 dirty 并可归档保存。
+
 剩余建议：
 
-1. 为任务增加取消、重试和失败详情接口。
-2. 前端 Dashboard 保留轮询兜底，并补充失败详情 UI。
+1. 增加骨架提取和聚类增强。
+2. 为多类别像素值提供模板分类自动映射规则。
 
-Dashboard 的解析队列现在已经从“项目状态派生”升级为任务表驱动，实时推送也已通过 Redis/WebSocket 打通；剩余重点是任务控制。
+## 阶段 7：模板优先级融合（已完成导出侧裁决）
 
-## 阶段 6：GT 导入与点区域
+当前导出 PNG Mask ZIP 时已经按 class/template z-index 做重叠裁决，从低到高覆盖，生成每帧 `semantic_frame_*.png`。
 
-这是 Word 方案中最复杂的部分，当前完全未实现。
-
-建议拆成小步：
-
-1. 先支持上传二值/多类别 mask。
-2. 后端按类别提取 connected components。
-3. 用 OpenCV distance transform 找正向点。
-4. 暂时不做骨架/HDBSCAN，先生成最小可用点集。
-5. 前端以可拖拽点显示并保存。
-6. 后续再做骨架和聚类增强。
-
-## 阶段 7：模板优先级融合
-
-当前模板有 z-index，但没有真正用于语义冲突裁决。
-
-建议：
+已完成：
 
 1. 标注保存时记录 template class id / name / zIndex。
 2. 导出 mask 时按 zIndex 从低到高覆盖。
-3. 同类 mask 做 union。
+3. 同类语义值在融合图中共享同一个 class value。
 4. 跨类重叠由高 zIndex 覆盖低 zIndex。
 
-这一步完成后，系统才真正符合“语义分割一个像素一个类别”的目标。
+剩余建议：
+
+1. 在前端预览重叠裁决结果。
+2. 对多帧多类导出增加颜色 palette PNG 或可视化 legend。
 
 ## 阶段 8：清理 UI 文案与 Mock
 
 建议统一这些文案和真实能力：
 
 - SAM/GPU 状态已改为 `GET /api/ai/models/status` 驱动。
-- 撤销/重做按钮接历史栈，否则隐藏。
+- 撤销/重做按钮已接全局 mask 历史栈。
 - “重新提取内侧中轴树骨架”接真实接口，否则标为未实现。
 - AI 独立页不要固定 Unsplash 图，应从当前项目帧或上传文件进入。

doc/07-current-requirements-freeze.md

@@ -31,6 +31,9 @@
 - 拆帧完成后写入 `frames` 记录，并把项目状态设为 `ready`。
 - 拆帧接口会创建 `processing_tasks` 记录并投递 Celery worker。
 - 前端可通过 `GET /api/tasks/{task_id}` 查询任务状态。
+- 后端支持 `POST /api/tasks/{task_id}/cancel` 取消 queued/running 任务，写入 `cancelled` 状态并尝试 revoke Celery。
+- 后端支持 `POST /api/tasks/{task_id}/retry` 对 failed/cancelled 任务创建新的 queued 任务。
+- worker 会在关键阶段检查任务是否已取消，取消后停止继续写帧。
 
 ## R4 工作区与帧浏览
 
@@ -46,7 +49,13 @@
 - 工具栏可以切换当前 active tool。
 - 正向点、反向点、框选工具会影响 Canvas 交互。
 - 魔法棒按钮切换到 AI 页面。
-- 多边形、矩形、圆、点、线、合并、去除、撤销、重做当前只提供 UI 状态或占位按钮，不完成真实绘制/算法。
+- 多边形、矩形、圆、点、线工具会在 Canvas 上生成可保存的 polygon mask。
+- 多边形通过点击取点并按 Enter 完成；矩形、圆、线通过拖拽生成；点工具生成小点区域。
+- Canvas 支持点击 mask 进入 polygon 顶点编辑态；拖动顶点会更新 mask 几何并把已保存 mask 标记为 dirty。
+- 顶点编辑态下选中顶点后可用 Delete/Backspace 删除顶点，但不会让 polygon 少于三点。
+- 撤销、重做绑定全局 `maskHistory/maskFuture`，支持工具栏按钮、AI 页按钮和 Canvas 快捷键。
+- 区域合并工具支持多选当前帧 mask，并使用 polygon union 生成合并后的主 mask。
+- 区域去除工具支持多选当前帧 mask，并从第一个选中的主 mask 中扣除后续选中 mask。
 
 ## R6 AI 推理
 
@@ -56,7 +65,8 @@
 - 前端发送后端契约：`image_id`、`prompt_type`、`prompt_data`、`model`。
 - 点提示传 `{ points, labels }`，正向点 label 为 1，反向点 label 为 0。
 - 框选提示传归一化 `[x1, y1, x2, y2]`。
-- 语义文本提示传 `semantic`；选择 `sam3` 且环境满足依赖时走 SAM 3 文本语义推理，选择 `sam2` 时回退到自动分割。
+- 语义文本提示传 `semantic`；选择 `sam3` 且独立 Python 3.12 环境、CUDA、官方包和 Hugging Face gated 权重访问均满足时走 SAM 3 文本语义推理，选择 `sam2` 时回退到自动分割。
+- AI 参数支持 `crop_to_prompt`、`auto_filter_background` 和 `min_score`；点/框 prompt 可以裁剪局部区域推理并回映射结果，背景过滤会移除低分结果和包含负向点的 polygon。
 - 后端返回 `polygons` 和 `scores`。
 - 前端把后端 `polygons` 转成 Konva `pathData`、`segmentation`、`bbox`、`area`。
 - AI 推理结果先存放在前端 store 的 `masks` 中，点击“结构化归档保存”后持久化到后端标注表。
@@ -71,6 +81,9 @@
 - 当前前端“结构化归档保存”会保存当前项目未保存 mask，并会更新已标记为 dirty 的已保存 mask。
 - 工作区“清空遮罩”会删除当前帧已保存标注，并清空当前帧未保存 mask。
 - 工作区加载项目帧后会查询已保存标注并回显。
+- 工作区支持导入 GT mask 图片，前端调用 `POST /api/ai/import-gt-mask`。
+- 后端导入 GT mask 时按非零像素值拆分多类别区域，再按连通域生成 polygon 标注，并通过距离变换写入 seed point。
+- 前端会回显导入标注的 seed point；拖动 seed point 后，已保存标注会变为 dirty，归档保存时会更新后端 `points`。
 
 ## R8 模板库
 
@@ -93,9 +106,12 @@
 - Dashboard 显示基础统计、解析队列和活动日志。
 - Dashboard 初始数据来自 `GET /api/dashboard/overview`。
 - 后端聚合项目数、处理中任务数、标注数、帧数、模板数和主机 load average。
-- 解析队列由 `processing_tasks` 中的 queued/running 任务生成；活动日志由最近任务、项目、标注和模板记录生成。
+- 解析队列由 `processing_tasks` 中的 queued/running/failed/cancelled 任务生成；活动日志由最近任务、项目、标注和模板记录生成。
+- Dashboard 对 queued/running 任务提供取消按钮，对 failed/cancelled 任务提供重试按钮。
+- Dashboard 任务详情会读取 `GET /api/tasks/{task_id}` 并展示失败 error、payload、result、Celery ID 和时间信息。
 - Dashboard 会连接 `/ws/progress`。
 - 收到 progress、complete、error、status 消息时，前端会更新队列或日志。
+- 收到 cancelled 消息时，前端会把对应任务标记为已取消。
 - Celery worker 每次更新 `processing_tasks` 后会发布 Redis `seg:progress` 事件，FastAPI 订阅并广播给 `/ws/progress` 客户端。
 - 后端 WebSocket 接收到客户端消息后返回 status heartbeat。
 
@@ -104,7 +120,10 @@
 - 后端支持 `GET /api/export/{project_id}/coco` 导出 COCO JSON。
 - 后端支持 `GET /api/export/{project_id}/masks` 导出 PNG mask ZIP。
 - 当前前端 `exportCoco()` API 封装已对齐后端路径。
+- 当前前端 `exportMasks()` API 封装已对齐后端路径。
 - 工作区“导出 JSON 标注集”按钮已绑定下载事件；导出前会先保存当前未归档 mask。
+- 工作区“导出 PNG Mask ZIP”按钮已绑定下载事件；导出前会先保存当前未归档 mask。
+- PNG mask ZIP 包含单标注二值 mask、按 zIndex 融合后的每帧语义 mask 和 `semantic_classes.json`。
 
 ## R12 配置
 

doc/08-current-design-freeze.md

@@ -19,17 +19,17 @@
 | 模块 | 文件 | 设计职责 |
 |------|------|----------|
 | 应用入口 | `src/App.tsx` | 根据登录状态和 `activeModule` 切换页面 |
-| 全局状态 | `src/store/useStore.ts` | Zustand store，保存项目、帧、模板、mask、工具状态 |
+| 全局状态 | `src/store/useStore.ts` | Zustand store，保存项目、帧、模板、mask、工具状态和 mask 撤销/重做历史栈 |
 | API 封装 | `src/lib/api.ts` | Axios 客户端、字段映射、AI 响应转换 |
 | 配置 | `src/lib/config.ts` | 推导 API 和 WebSocket 地址 |
 | WebSocket | `src/lib/websocket.ts` | 进度流连接、订阅和重连 |
 | 模型状态 | `src/components/ModelStatusBadge.tsx` | 展示 GPU 与当前 SAM 模型真实可用状态 |
 | 登录页 | `src/components/Login.tsx` | 调用登录 API，写入 store |
-| Dashboard | `src/components/Dashboard.tsx` | 展示统计和 WebSocket 进度消息 |
+| Dashboard | `src/components/Dashboard.tsx` | 展示统计、任务控制、失败详情和 WebSocket 进度消息 |
 | 项目库 | `src/components/ProjectLibrary.tsx` | 项目列表、新建、导入视频/DICOM |
 | 工作区 | `src/components/VideoWorkspace.tsx` | 加载帧和模板，组织工具栏、Canvas、本体面板、时间轴 |
 | Canvas | `src/components/CanvasArea.tsx` | 显示帧、缩放平移、点/框提示、渲染 mask |
-| 工具栏 | `src/components/ToolsPalette.tsx` | 切换工具和跳转 AI 页面 |
+| 工具栏 | `src/components/ToolsPalette.tsx` | 切换工具、跳转 AI 页面、触发 mask 撤销/重做 |
 | 时间轴 | `src/components/FrameTimeline.tsx` | 帧导航和播放 |
 | 本体面板 | `src/components/OntologyInspector.tsx` | 模板选择、分类树、本地自定义分类 |
 | AI 页面 | `src/components/AISegmentation.tsx` | 独立 AI 推理视图，使用当前项目帧 |
@@ -51,7 +51,7 @@
 | AI | `backend/routers/ai.py` | SAM 2 / SAM 3 可选推理、模型状态和标注保存 |
 | Export | `backend/routers/export.py` | COCO 和 PNG mask 导出 |
 | SAM 2 | `backend/services/sam2_engine.py` | SAM 2 懒加载、状态检测和点/框/自动推理 |
-| SAM 3 | `backend/services/sam3_engine.py` | SAM 3 状态检测和文本语义推理适配 |
+| SAM 3 | `backend/services/sam3_engine.py`, `backend/services/sam3_external_worker.py`, `backend/setup_sam3_env.sh` | SAM 3 状态检测、独立 Python 3.12 环境桥接和文本语义推理适配 |
 | SAM Registry | `backend/services/sam_registry.py` | 模型选择、GPU 状态和推理分发 |
 
 ## 状态模型
@@ -62,6 +62,7 @@
 - `Frame`：帧 ID、项目 ID、索引、图片 URL、宽高。
 - `Template` / `TemplateClass`：模板和分类定义。
 - `Mask`：前端渲染用 mask，包含 `pathData`、`segmentation`、`bbox`、`area`。
+- `maskHistory` / `maskFuture`：mask 编辑历史栈，用于撤销和重做。
 - `activeModule`：当前页面。
 - `activeTool`：当前工具。
 - `aiModel`：当前选择的 AI 模型，取值为 `sam2` 或 `sam3`。
@@ -82,6 +83,14 @@
 4. Celery worker 执行 FFmpeg/OpenCV/pydicom 拆帧，持续更新 `processing_tasks`，并发布 Redis `seg:progress`。
 5. 刷新项目列表。
 
+### 任务控制
+
+1. Dashboard 从 `GET /api/dashboard/overview` 读取 queued/running/failed/cancelled 任务。
+2. 用户取消任务时，前端调用 `POST /api/tasks/{task_id}/cancel`；后端写入 `cancelled`、设置 `finished_at`，并尝试 `celery_app.control.revoke(..., terminate=True)`。
+3. worker 在下载、解析、上传、写帧等关键阶段刷新任务状态；如果发现 `cancelled`，停止后续写入并发布 cancelled 事件。
+4. 用户重试任务时，前端调用 `POST /api/tasks/{task_id}/retry`；后端基于原任务 `payload` 创建新任务，记录 `retry_of` 并重新投递 Celery。
+5. 用户打开详情时，前端调用 `GET /api/tasks/{task_id}`，弹窗展示 error、payload、result、Celery ID 和时间。
+
 ### 工作区加载
 
 1. `VideoWorkspace` 根据 `currentProject.id` 调用 `getProjectFrames()`。
@@ -102,6 +111,41 @@
 9. 工作区加载项目帧后通过 `GET /api/ai/annotations` 取回已保存标注并转成前端 mask。
 10. 工作区“清空遮罩”删除当前帧已保存标注，并清除当前帧本地 mask。
 
+### 手工绘制与历史栈
+
+1. 用户在 `ToolsPalette` 选择多边形、矩形、圆、点或线工具。
+2. `CanvasArea` 将交互坐标转换成像素 polygon。
+3. 新 mask 写入 `pathData`、像素 `segmentation`、`bbox`、`area` 和当前模板分类元数据。
+4. `addMask()`、`setMasks()`、`updateMask()`、`clearMasks()` 会维护 `maskHistory/maskFuture`。
+5. 工具栏按钮、AI 页按钮和 Canvas Ctrl+Z/Ctrl+Y 调用 `undoMasks()` / `redoMasks()`。
+
+### Polygon 逐点编辑
+
+1. 用户点击 Canvas 上的 mask path 后，`CanvasArea` 记录 `selectedMaskId` 并显示该 mask 第一条 polygon 的顶点控制点。
+2. 拖动顶点后，前端重算 `pathData`、像素 `segmentation`、`bbox`、`area`。
+3. 如果 mask 已有 `annotationId`，编辑会把 `saveStatus` 标成 `dirty` 且 `saved=false`。
+4. 归档保存时复用现有 `PATCH /api/ai/annotations/{annotation_id}` 链路，把更新后的 normalized polygon 写回后端。
+5. 选中顶点后 Delete/Backspace 可删除顶点；前端保持 polygon 至少三点。
+
+### 区域合并与去除
+
+1. 用户选择 `area_merge` 或 `area_remove` 后，点击多个当前帧 mask 组成选择集。
+2. `CanvasArea` 把 `Mask.segmentation` 转为 `polygon-clipping` 的 MultiPolygon。
+3. `area_merge` 使用 union，更新第一个选中的主 mask，并从前端 store 移除后续被合并 mask；如果被移除 mask 已保存，会调用工作区传入的删除回调删除后端标注。
+4. `area_remove` 使用 difference，从第一个选中的主 mask 中扣除后续选中 mask，扣除对象本身保留。
+5. 结果会重算 `pathData`、`segmentation`、`bbox`、`area`，已保存主 mask 会进入 dirty 状态并复用归档 PATCH 链路。
+
+### GT Mask 导入
+
+1. 工作区“导入 GT Mask”选择图片文件。
+2. 前端 `importGtMask()` 以 multipart form-data 调用 `POST /api/ai/import-gt-mask`，携带 `project_id` 和 `frame_id`。
+3. 后端验证项目、帧、模板后使用 OpenCV 读取灰度 mask。
+4. 后端按非零像素值拆分多类别标签。
+5. 后端对每个类别的前景做 contour 提取，每个连通域保存为一个 `Annotation`。
+6. `points` 字段保存距离变换中心 seed point，`mask_data.polygons` 保存 normalized polygon，`mask_data.gt_label_value` 保存原始像素类别值。
+7. 前端重新读取项目标注并回显。
+8. `annotationToMask()` 会把 normalized seed point 转成像素坐标，Canvas 以可拖拽点显示；拖动后 `buildAnnotationPayload()` 会把点再归一化写回后端。
+
 ### 模板管理
 
 1. `TemplateRegistry` 从后端读取模板。
@@ -114,8 +158,10 @@
 ### 导出
 
 1. 后端根据项目、帧、标注和模板生成 COCO JSON。
-2. PNG mask 导出会把 normalized polygon 渲染为二值 mask 并打包 ZIP。
-3. 前端“导出 JSON 标注集”按钮会在导出前保存待归档标注，然后下载 COCO JSON。
+2. PNG mask 导出会把 normalized polygon 渲染为单标注二值 mask。
+3. PNG mask 导出还会按 `mask_data.class.zIndex` 或模板 `z_index` 从低到高覆盖，生成每帧语义融合 mask。
+4. ZIP 内写入 `semantic_classes.json`，记录语义值到类别、颜色和 zIndex 的映射。
+5. 前端“导出 JSON 标注集”和“导出 PNG Mask ZIP”按钮都会在导出前保存待归档标注，然后下载对应文件。
 
 ## 接口契约
 
@@ -123,13 +169,18 @@
 
 - `updateProject()` 使用 `PATCH /api/projects/{id}`。
 - `exportCoco()` 使用 `GET /api/export/{projectId}/coco`。
+- `exportMasks()` 使用 `GET /api/export/{projectId}/masks`。
+- `cancelTask()` 使用 `POST /api/tasks/{taskId}/cancel`。
+- `retryTask()` 使用 `POST /api/tasks/{taskId}/retry`。
 - `predictMask()` 使用 `POST /api/ai/predict`，请求体为 `image_id`、`prompt_type`、`prompt_data`、`model`。
 - `saveAnnotation()` 使用 `POST /api/ai/annotate`。
+- `importGtMask()` 使用 `POST /api/ai/import-gt-mask` multipart form-data。
 - `getProjectAnnotations()` 使用 `GET /api/ai/annotations`。
 - `updateAnnotation()` 使用 `PATCH /api/ai/annotations/{annotationId}`。
 - `deleteAnnotation()` 使用 `DELETE /api/ai/annotations/{annotationId}`。
 - 后端 `/api/ai/predict` 支持 point、box、semantic 三种 prompt_type，并通过 `model` 选择 SAM 2 或 SAM 3。
-- 后端 `/api/ai/models/status` 返回 GPU、SAM 2、SAM 3 的真实运行状态。
+- 后端 `/api/ai/predict` 支持可选 `options`：`crop_to_prompt` 会对 point/box prompt 做局部裁剪推理并回映射 polygon，`auto_filter_background` 会按 `min_score` 和负向点过滤结果。
+- 后端 `/api/ai/models/status` 返回 GPU、SAM 2、SAM 3 的真实运行状态；SAM 3 状态包含外部 Python 环境与 checkpoint access 的可用性。
 - point prompt 支持旧数组形式和 `{ points, labels }` 对象形式。
 
 ## 外部依赖边界
@@ -146,10 +197,8 @@
 
 以下能力属于当前冻结版本的占位或半可用功能：
 
-- Dashboard 初始快照来自 `GET /api/dashboard/overview`；解析队列由 `processing_tasks` queued/running 任务生成。
-- 多边形、矩形、圆、点、线手工绘制未实现。
-- 合并、去除、撤销、重做未实现。
-- 工作区导出 PNG mask ZIP 按钮尚未提供。
-- 已保存标注支持通过“应用分类”进入 dirty 状态并归档更新；暂未提供逐点几何编辑器。
-- SAM 3 文本语义分割取决于官方依赖和 GPU 运行环境；状态接口会暴露真实可用性。
+- Dashboard 初始快照来自 `GET /api/dashboard/overview`；解析队列由 `processing_tasks` queued/running/failed/cancelled 任务生成。
+- 已保存标注支持通过“应用分类”、polygon 顶点拖动/删除、边中点插入、多 polygon 子区域编辑和区域合并/去除进入 dirty 状态并归档更新；复杂洞结构编辑尚未实现。
+- SAM 3 文本语义分割取决于官方依赖、GPU 运行环境和 Hugging Face gated 权重授权；状态接口会暴露真实可用性，未授权时 `available=false`。
 - 自定义分类只存在本地组件状态。
+- GT mask 导入已完成多类别像素值拆分、contour、distance transform seed point 和前端 seed point 拖拽编辑；骨架提取、HDBSCAN 聚类和模板自动映射尚未实现。

doc/09-test-plan.md

@@ -16,15 +16,15 @@
 |------|----------|--------|
 | R1 登录与会话 | `src/components/Login.test.tsx`, `backend/tests/test_auth.py` | 成功登录、失败提示、后端 401 |
 | R2 项目管理 | `src/lib/api.test.ts`, `backend/tests/test_projects.py` | 前端字段映射、PATCH 更新、后端 CRUD、帧列表 |
-| R3 媒体上传与拆帧 | `backend/tests/test_media.py` | 扩展名校验、自动建项目、关联项目、创建异步任务、worker 注册帧 |
+| R3 媒体上传与拆帧 | `backend/tests/test_media.py`, `backend/tests/test_tasks.py` | 扩展名校验、自动建项目、关联项目、创建异步任务、worker 注册帧、取消任务、重试任务、取消后 worker 停止 |
 | R4 工作区与帧浏览 | `src/components/VideoWorkspace.test.tsx`, `src/components/FrameTimeline.test.tsx` | 加载帧、无帧触发解析、切帧、播放 |
-| R5 工具栏 | `src/components/ToolsPalette.test.tsx` | 工具切换、AI 跳转、占位按钮存在 |
-| R6 AI 推理 | `src/lib/api.test.ts`, `src/components/CanvasArea.test.tsx`, `src/components/AISegmentation.test.tsx`, `src/components/ModelStatusBadge.test.tsx`, `backend/tests/test_ai.py` | 点/框/semantic 契约、模型选择、GPU/SAM 状态、状态徽标、坐标归一化、正负点 labels、polygons 转 path、后端 fake registry |
-| R7 标注保存 | `src/components/VideoWorkspace.test.tsx`, `src/components/CanvasArea.test.tsx`, `src/lib/api.test.ts`, `backend/tests/test_ai.py` | 保存标注、加载回显、更新 dirty 标注、清空删除已保存标注、项目不存在、帧不存在 |
+| R5 工具栏 | `src/components/ToolsPalette.test.tsx`, `src/components/CanvasArea.test.tsx`, `src/store/useStore.test.ts` | 工具切换、AI 跳转、手工 mask 绘制、polygon 顶点拖动/删除、区域合并/去除、撤销/重做历史栈 |
+| R6 AI 推理 | `src/lib/api.test.ts`, `src/components/CanvasArea.test.tsx`, `src/components/AISegmentation.test.tsx`, `src/components/ModelStatusBadge.test.tsx`, `backend/tests/test_ai.py`, `backend/tests/test_sam3_engine.py` | 点/框/semantic 契约、模型选择、GPU/SAM 状态、SAM 3 外部 worker 桥接、AI 参数 options、局部裁剪推理、背景过滤、状态徽标、坐标归一化、正负点 labels、polygons 转 path、后端 fake registry |
+| R7 标注保存 | `src/components/VideoWorkspace.test.tsx`, `src/components/CanvasArea.test.tsx`, `src/lib/api.test.ts`, `backend/tests/test_ai.py` | 保存标注、加载回显、更新 dirty 标注、清空删除已保存标注、GT mask 多类别导入、seed point 回显/归一化、项目不存在、帧不存在 |
 | R8 模板库 | `src/lib/api.test.ts`, `backend/tests/test_templates.py` | mapping_rules 解包/打包、模板 CRUD |
 | R9 本体检查面板 | `src/components/OntologyInspector.test.tsx` | 模板选择、分类展示、具体分类选择、自定义分类本地添加 |
-| R10 Dashboard 与 WebSocket | `src/lib/api.test.ts`, `src/lib/websocket.test.ts`, `src/components/Dashboard.test.tsx`, `backend/tests/test_dashboard.py`, `backend/tests/test_main.py`, `backend/tests/test_progress_events.py` | 后端概览接口、任务表驱动队列、Redis 进度事件 payload/发布、地址推导、消息订阅、队列更新、heartbeat |
-| R11 导出 | `src/components/VideoWorkspace.test.tsx`, `src/lib/api.test.ts`, `backend/tests/test_export.py` | COCO 按钮下载、导出前自动保存、COCO 路径、JSON 结构、mask ZIP |
+| R10 Dashboard 与 WebSocket | `src/lib/api.test.ts`, `src/lib/websocket.test.ts`, `src/components/Dashboard.test.tsx`, `backend/tests/test_dashboard.py`, `backend/tests/test_main.py`, `backend/tests/test_progress_events.py`, `backend/tests/test_tasks.py` | 后端概览接口、任务表驱动队列、任务取消/重试/详情、cancelled 事件、Redis 进度事件 payload/发布、地址推导、消息订阅、队列更新、heartbeat |
+| R11 导出 | `src/components/VideoWorkspace.test.tsx`, `src/lib/api.test.ts`, `backend/tests/test_export.py` | COCO/PNG 按钮下载、导出前自动保存、导出路径、JSON 结构、mask ZIP、zIndex 语义融合 |
 | R12 配置 | `src/lib/config.test.ts` | env 优先、hostname 推导、WS 推导 |
 | R13 文档与测试 | `doc/09-test-plan.md` | 测试覆盖矩阵 |