feat: 完善视频传播、标注编辑和拆帧闭环

- 接入 SAM2 视频传播能力：新增 /api/ai/propagate，支持用当前帧 mask/polygon/bbox 作为 seed，通过 SAM2 video predictor 向前、向后或双向传播，并可保存为真实 annotation。
- 接入 SAM3 video tracker：通过独立 Python 3.12 external worker 调用 SAM3 video predictor/tracker，使用本地 checkpoint 与 bbox seed 执行视频级跟踪，并在模型状态中标记 video_track 能力。
- 完善 SAM 模型分发：sam_registry 按 model_id 明确区分 sam2 propagation 与 sam3 video_track，避免两个模型链路混用。
- 打通前端“传播片段”：VideoWorkspace 使用当前选中 mask 和当前 AI 模型调用后端传播接口，传播结果回写并刷新工作区已保存标注。
- 增强 SAM3 本地 checkpoint 配置：新增 sam3_checkpoint_path 配置和 .env.example 示例，状态检查改为基于本地 checkpoint/独立环境/模型包可用性。
- 完善视频拆帧参数：/api/media/parse 支持 parse_fps、max_frames、target_width，后端任务保存帧时间戳、源帧号和 frame_sequence 元数据。
- 增加运行时 schema 兼容处理：启动时为旧 frames 表补充 timestamp_ms 和 source_frame_number 列，避免旧库升级后缺字段。
- 强化 Canvas 标注编辑：补齐多边形闭合、点工具、顶点拖拽、边中点插入、Delete/Backspace 删除、区域合并和重叠去除等交互。
- 增强语义分类联动：选中 mask 后可通过右侧语义分类树更新标签、颜色和 class metadata，并同步到保存/导出链路。
- 增加关键帧时间轴体验：FrameTimeline 显示具体时间信息，并支持键盘左右方向键切换关键帧。
- 完善 AI 交互分割参数：前端保留正向点、反向点、框选和 interactive prompt 的调用状态，支持 SAM2 细化候选区域与 SAM3 bbox 入口。
- 扩展后端/前端 API 类型：新增 propagateMasks、传播请求/响应 schema，并补齐 annotation、导出、模型状态和任务接口的测试覆盖。
- 更新项目文档：同步 README、AGENTS、接口契约、需求冻结、设计冻结、前端元素审计、实施计划和测试计划，标明真实功能边界与剩余风险。
- 增加测试覆盖：补充 SAM2/SAM3 传播、SAM3 状态、媒体拆帧参数、Canvas 编辑、语义标签切换、时间轴、工作区传播和 API 合约测试。
- 加强仓库安全边界：将 sam3权重/ 加入 .gitignore，避免本地模型权重被误提交。

验证：npm run test:run；pytest backend/tests；npm run lint；npm run build；python -m py_compile；git diff --check。

doc/08-current-design-freeze.md

@@ -19,7 +19,7 @@
 | 模块 | 文件 | 设计职责 |
 |------|------|----------|
 | 应用入口 | `src/App.tsx` | 根据登录状态和 `activeModule` 切换页面 |
-| 全局状态 | `src/store/useStore.ts` | Zustand store，保存项目、帧、模板、mask、工具状态和 mask 撤销/重做历史栈 |
+| 全局状态 | `src/store/useStore.ts` | Zustand store，保存项目、帧、模板、mask、当前选中 mask ids、工具状态和 mask 撤销/重做历史栈 |
 | API 封装 | `src/lib/api.ts` | Axios 客户端、字段映射、AI 响应转换 |
 | 配置 | `src/lib/config.ts` | 推导 API 和 WebSocket 地址 |
 | WebSocket | `src/lib/websocket.ts` | 进度流连接、订阅和重连 |
@@ -30,7 +30,7 @@
 | 工作区 | `src/components/VideoWorkspace.tsx` | 加载帧和模板，组织工具栏、Canvas、本体面板、时间轴 |
 | Canvas | `src/components/CanvasArea.tsx` | 显示帧、缩放平移、点/框提示、渲染 mask |
 | 工具栏 | `src/components/ToolsPalette.tsx` | 切换工具、跳转 AI 页面、触发 mask 撤销/重做 |
-| 时间轴 | `src/components/FrameTimeline.tsx` | 帧导航和播放 |
+| 时间轴 | `src/components/FrameTimeline.tsx` | 帧导航、左右方向键切帧、播放和当前/总时长显示 |
 | 本体面板 | `src/components/OntologyInspector.tsx` | 模板选择、分类树、本地自定义分类 |
 | AI 页面 | `src/components/AISegmentation.tsx` | 独立 AI 推理视图，使用当前项目帧 |
 | 模板库 | `src/components/TemplateRegistry.tsx` | 模板 CRUD、分类编辑、导入、排序 |
@@ -48,10 +48,10 @@
 | Projects | `backend/routers/projects.py` | 项目与帧 CRUD |
 | Templates | `backend/routers/templates.py` | 模板 CRUD 和 mapping_rules 打包/解包 |
 | Media | `backend/routers/media.py` | 上传媒体和拆帧 |
-| AI | `backend/routers/ai.py` | SAM 2 / SAM 3 可选推理、模型状态和标注保存 |
+| 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`, `backend/services/sam3_external_worker.py`, `backend/setup_sam3_env.sh` | SAM 3 状态检测、独立 Python 3.12 环境桥接和文本语义推理适配 |
+| SAM 2 | `backend/services/sam2_engine.py` | SAM 2 懒加载、状态检测、点/框/自动推理和视频 mask 传播 |
+| SAM 3 | `backend/services/sam3_engine.py`, `backend/services/sam3_external_worker.py`, `backend/setup_sam3_env.sh` | SAM 3 状态检测、独立 Python 3.12 环境桥接、本地 checkpoint 加载、文本语义推理、正框几何提示和 video tracker 适配 |
 | SAM Registry | `backend/services/sam_registry.py` | 模型选择、GPU 状态和推理分发 |
 
 ## 状态模型
@@ -59,9 +59,10 @@
 前端 store 的核心对象：
 
 - `Project`：项目基本信息、状态、帧数、fps、媒体路径。
-- `Frame`：帧 ID、项目 ID、索引、图片 URL、宽高。
+- `Frame`：帧 ID、项目 ID、索引、图片 URL、宽高、序列时间戳和原视频源帧号。
 - `Template` / `TemplateClass`：模板和分类定义。
 - `Mask`：前端渲染用 mask，包含 `pathData`、`segmentation`、`bbox`、`area`。
+- `selectedMaskIds`：Canvas 当前选中的 mask id 列表，供右侧本体面板对已选区域直接换标签。
 - `maskHistory` / `maskFuture`：mask 编辑历史栈，用于撤销和重做。
 - `activeModule`：当前页面。
 - `activeTool`：当前工具。
@@ -79,9 +80,11 @@
 
 1. `ProjectLibrary` 创建项目。
 2. 上传视频或 DICOM 到 `/api/media/upload` 或 `/api/media/upload/dicom`。
-3. 调用 `/api/media/parse` 创建异步拆帧任务。
-4. Celery worker 执行 FFmpeg/OpenCV/pydicom 拆帧，持续更新 `processing_tasks`，并发布 Redis `seg:progress`。
-5. 刷新项目列表。
+3. 调用 `/api/media/parse` 创建异步拆帧任务；可通过 `parse_fps`、`max_frames` 和 `target_width` 指定标准帧序列参数。
+4. Celery worker 执行 FFmpeg/OpenCV/pydicom 拆帧，视频帧按 `frame_%06d.jpg` 从 `frame_000000.jpg` 连续命名，并按目标宽度缩放。
+5. worker 写入 `frames.timestamp_ms` 和 `frames.source_frame_number`，并在任务 `result.frame_sequence` 中记录 FPS、帧数、时长、尺寸和对象存储前缀。
+6. worker 持续更新 `processing_tasks`，并发布 Redis `seg:progress`。
+7. 刷新项目列表。
 
 ### 任务控制
 
@@ -95,29 +98,43 @@
 
 1. `VideoWorkspace` 根据 `currentProject.id` 调用 `getProjectFrames()`。
 2. 若无帧但项目有 `video_path`，触发 `parseMedia()`，通过 `getTask()` 轮询任务完成后重新取帧。
-3. 帧数据映射为 store `Frame[]`。
+3. 帧数据映射为 store `Frame[]`，包含 `timestampMs` 和 `sourceFrameNumber`，供时间轴和后续视频传播使用。
 4. 当前帧传入 `CanvasArea`。
 
 ### AI 点/框推理
 
 1. 用户在 Canvas 选择正向点、反向点或框选。
 2. `CanvasArea` 读取当前帧 ID 和宽高。
-3. `predictMask()` 归一化坐标并携带当前 `model` 调用 `/api/ai/predict`。
-4. 后端加载帧图片并通过 SAM registry 分发到 SAM 2 或 SAM 3。
-5. 前端把 `polygons` 转为 mask，写入 store。
-6. Canvas 按当前帧过滤并渲染 mask。
-7. 新 mask 会带上当前选择的模板分类元数据，包括 `classId`、`className`、`classZIndex` 和保存状态 `draft`。
-8. 用户点击“结构化归档保存”后，前端将像素 `segmentation` 转成 normalized `mask_data.polygons`；未保存 mask 调用 `POST /api/ai/annotate`，dirty mask 调用 `PATCH /api/ai/annotations/{annotation_id}`。
-9. 工作区加载项目帧后通过 `GET /api/ai/annotations` 取回已保存标注并转成前端 mask。
-10. 工作区“清空遮罩”删除当前帧已保存标注，并清除当前帧本地 mask。
+3. SAM 2 框选会创建一个候选 mask，并记录原始框；后续正向点/反向点会累计到同一候选上。
+4. `predictMask()` 归一化坐标并携带当前 `model` 调用 `/api/ai/predict`；同时有框和点时发送 `interactive` prompt。
+5. 后端加载帧图片并通过 SAM registry 分发到 SAM 2 或 SAM 3。
+6. 前端把 `polygons` 转为 mask；交互式细化会替换同一个候选 mask，而不是新增多个 mask。
+7. Canvas 按当前帧过滤并渲染 mask。
+8. 新 mask 会带上当前选择的模板分类元数据，包括 `classId`、`className`、`classZIndex` 和保存状态 `draft`。
+9. 用户点击“结构化归档保存”后，前端将像素 `segmentation` 转成 normalized `mask_data.polygons`；未保存 mask 调用 `POST /api/ai/annotate`，dirty mask 调用 `PATCH /api/ai/annotations/{annotation_id}`。
+10. 工作区加载项目帧后通过 `GET /api/ai/annotations` 取回已保存标注并转成前端 mask。
+11. 工作区“清空遮罩”删除当前帧已保存标注，并清除当前帧本地 mask。
+
+### 视频片段传播
+
+1. 用户在工作区选中一个当前帧 mask；如果未显式选中，前端使用当前帧第一个 mask。
+2. `VideoWorkspace` 用 `buildAnnotationPayload()` 把 seed mask 转成 normalized polygon、bbox、label、color 和 class 元数据。
+3. 前端调用 `POST /api/ai/propagate`，默认 `direction=forward`、`max_frames=30`、`include_source=false`。
+4. 后端按项目帧序列截取片段，下载对应帧到临时 `frame_%06d.jpg` 目录，保持当前帧在片段中的相对索引。
+5. `model=sam2` 时，`sam2_engine` 使用 `SAM2VideoPredictor.add_new_mask()` 注入 seed mask，再用 `propagate_in_video()` 传播。
+6. `model=sam3` 时，`sam3_engine` 将请求交给 `sam3_external_worker.py`，由独立 Python 3.12 环境调用官方 `build_sam3_video_predictor()`，以 seed bbox 走 video tracker。
+7. 后端把传播返回的 normalized polygon 保存为后续帧 `Annotation`，跳过源帧，`mask_data.source` 记录模型传播来源。
+8. 前端传播完成后重新调用 `GET /api/ai/annotations` 并回显新标注。
 
 ### 手工绘制与历史栈
 
 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()`。
+3. 多边形工具逐次记录节点，三点后点击首节点或按 Enter 时生成闭合 polygon。
+4. mask path 只在 `move`、`area_merge` 和 `area_remove` 工具下拦截点击；绘制和 AI prompt 工具点击已有 mask 时继续冒泡给 Stage。
+5. 新 mask 写入 `pathData`、像素 `segmentation`、`bbox`、`area` 和当前模板分类元数据。
+6. `addMask()`、`setMasks()`、`updateMask()`、`clearMasks()` 会维护 `maskHistory/maskFuture`。
+7. 工具栏按钮、AI 页按钮和 Canvas Ctrl+Z/Ctrl+Y 调用 `undoMasks()` / `redoMasks()`。
 
 ### Polygon 逐点编辑
 
@@ -126,14 +143,16 @@
 3. 如果 mask 已有 `annotationId`，编辑会把 `saveStatus` 标成 `dirty` 且 `saved=false`。
 4. 归档保存时复用现有 `PATCH /api/ai/annotations/{annotation_id}` 链路，把更新后的 normalized polygon 写回后端。
 5. 选中顶点后 Delete/Backspace 可删除顶点；前端保持 polygon 至少三点。
+6. 未选中具体顶点但选中了 mask 时，Delete/Backspace 从前端 store 删除该 mask；如果包含 `annotationId`，通过工作区回调调用后端删除接口。
 
 ### 区域合并与去除
 
 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 链路。
+2. 合并/去除模式隐藏 polygon 顶点和边中点编辑手柄，并在右下角显示已选数量；少于两个 mask 时操作按钮禁用。
+3. `CanvasArea` 把 `Mask.segmentation` 转为 `polygon-clipping` 的 MultiPolygon。
+4. `area_merge` 使用 union，更新第一个选中的主 mask，并从前端 store 移除后续被合并 mask；如果被移除 mask 已保存，会调用工作区传入的删除回调删除后端标注。
+5. `area_remove` 使用 difference，从第一个选中的主 mask 中扣除后续选中 mask，扣除对象本身保留；如果 difference 产生内洞，`segmentation` 保留外圈和 hole ring，渲染时使用 even-odd fill。
+6. 结果会重算 `pathData`、`segmentation`、`bbox`、`area`，已保存主 mask 会进入 dirty 状态并复用归档 PATCH 链路；带洞结果的面积按外圈减内洞计算。
 
 ### GT Mask 导入
 
@@ -153,7 +172,10 @@
 3. 保存时调用 `createTemplate()` 或 `updateTemplate()`。
 4. 后端把 `classes`、`rules` 打包进 `mapping_rules`。
 5. 返回时再解包给前端。
-6. `OntologyInspector` 可以选择具体分类；选择结果进入全局 store，供 `CanvasArea` 和 `AISegmentation` 新建/更新 mask 时使用。
+6. `CanvasArea` 把当前选中的 mask id 同步到全局 `selectedMaskIds`；切换工具、切换帧或卸载 Canvas 时会清空选择。
+7. `OntologyInspector` 可以选择具体分类；选择结果进入全局 store，供 `CanvasArea` 和 `AISegmentation` 新建/更新 mask 时使用。
+8. 如果 `selectedMaskIds` 中存在当前 store 的 mask，点击分类时会立即更新这些 mask 的 `templateId`、`classId`、`className`、`classZIndex`、`label` 和 `color`。
+9. 已保存 mask 被重新分类后进入 `dirty` 且 `saved=false`，继续复用工作区归档保存的 PATCH 链路。
 
 ### 导出
 
@@ -173,13 +195,20 @@
 - `cancelTask()` 使用 `POST /api/tasks/{taskId}/cancel`。
 - `retryTask()` 使用 `POST /api/tasks/{taskId}/retry`。
 - `predictMask()` 使用 `POST /api/ai/predict`，请求体为 `image_id`、`prompt_type`、`prompt_data`、`model`。
+- `propagateMasks()` 使用 `POST /api/ai/propagate`，请求体为 `project_id`、`frame_id`、`model`、`seed`、`direction`、`max_frames`。
 - `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/predict` 支持可选 `options`：`crop_to_prompt` 会对 point/box prompt 做局部裁剪推理并回映射 polygon，`auto_filter_background` 会按 `min_score` 和负向点过滤结果。
+- `parseMedia()` 使用 `POST /api/media/parse?project_id=...`，可选 `parse_fps`、`max_frames`、`target_width`，用于生成标准帧序列。
+- `getProjectFrames()` 返回帧图像 URL、宽高、`timestamp_ms` 和 `source_frame_number`。
+- 后端 `/api/ai/predict` 支持 point、box、interactive、semantic 四种 prompt_type，并通过 `model` 选择 SAM 2 或 SAM 3。
+- 当前 SAM 3 暴露 semantic 文本语义推理和 box 几何提示；工作区 Canvas 的点交互会在选择 SAM 3 时显示提示，不再静默失败。
+- SAM 3 box prompt 复用后端 `/api/ai/predict` 的 `box` prompt_type，输入仍是 normalized `[x1, y1, x2, y2]`，引擎适配层会转换为官方 `add_geometric_prompt()` 使用的 `[center_x, center_y, width, height]` 正框。
+- AI 页面选择 SAM 3 时优先发送文本 semantic prompt，不会把正/反点误发送为 SAM 3 point prompt；空文本、后端错误和空结果都会显示反馈消息。
+- 后端 `/api/ai/predict` 支持可选 `options`：`crop_to_prompt` 会对 point/box/interactive prompt 做局部裁剪推理并回映射 polygon，`auto_filter_background` 会按 `min_score` 和负向点过滤结果。
+- 后端 `/api/ai/propagate` 支持 SAM 2 mask seed 视频传播和 SAM 3 external video tracker；当前前端默认向后传播 30 帧并保存结果标注。
 - 后端 `/api/ai/models/status` 返回 GPU、SAM 2、SAM 3 的真实运行状态；SAM 3 状态包含外部 Python 环境与 checkpoint access 的可用性。
 - point prompt 支持旧数组形式和 `{ points, labels }` 对象形式。
 
@@ -198,7 +227,7 @@
 以下能力属于当前冻结版本的占位或半可用功能：
 
 - Dashboard 初始快照来自 `GET /api/dashboard/overview`；解析队列由 `processing_tasks` queued/running/failed/cancelled 任务生成。
-- 已保存标注支持通过“应用分类”、polygon 顶点拖动/删除、边中点插入、多 polygon 子区域编辑和区域合并/去除进入 dirty 状态并归档更新；复杂洞结构编辑尚未实现。
-- SAM 3 文本语义分割取决于官方依赖、GPU 运行环境和 Hugging Face gated 权重授权；状态接口会暴露真实可用性，未授权时 `available=false`。
+- 已保存标注支持通过“应用分类”、polygon 顶点拖动/删除、边中点插入、多 polygon 子区域编辑和区域合并/去除进入 dirty 状态并归档更新；选中整块 mask 可用 Delete/Backspace 删除并同步后端；复杂洞结构编辑尚未实现。
+- SAM 3 文本语义分割取决于官方依赖、GPU 运行环境和本地 checkpoint；状态接口会暴露真实可用性，运行时缺失时 `available=false`。
 - 自定义分类只存在本地组件状态。
 - GT mask 导入已完成多类别像素值拆分、contour、distance transform seed point 和前端 seed point 拖拽编辑；骨架提取、HDBSCAN 聚类和模板自动映射尚未实现。