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/04-api-contracts.md

@@ -32,12 +32,13 @@ Authorization: Bearer <token>
 | `deleteTemplate(id)` | `DELETE /api/templates/{id}` | 对齐 | 模板编辑页使用 |
 | `uploadMedia(file, projectId)` | `POST /api/media/upload` | 对齐 | multipart form-data |
 | `uploadDicomBatch(files, projectId)` | `POST /api/media/upload/dicom` | 对齐 | multipart form-data |
-| `parseMedia(projectId)` | `POST /api/media/parse?project_id=...` | 对齐 | 创建异步拆帧任务并返回 task |
+| `parseMedia(projectId, options?)` | `POST /api/media/parse?project_id=...` | 对齐 | 创建异步拆帧任务并返回 task；支持 `parse_fps`、`max_frames`、`target_width` |
 | `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 |
+| `getProjectFrames(projectId)` | `GET /api/projects/{id}/frames` | 对齐 | 后端返回预签名 image_url，以及 `timestamp_ms`、`source_frame_number` |
 | `predictMask(payload)` | `POST /api/ai/predict` | 对齐 | 前端发送 `image_id/prompt_type/prompt_data/model`，并把后端 `polygons` 转为 `masks[].pathData` |
+| `propagateMasks(payload)` | `POST /api/ai/propagate` | 对齐 | 当前帧 seed mask 向视频片段传播，并保存后续帧标注 |
 | `getAiModelStatus(selectedModel?)` | `GET /api/ai/models/status` | 对齐 | 返回 GPU、SAM 2、SAM 3 的真实运行状态 |
 | `getProjectAnnotations(projectId, frameId?)` | `GET /api/ai/annotations` | 对齐 | 前端加载工作区时用于回显已保存标注 |
 | `saveAnnotation(payload)` | `POST /api/ai/annotate` | 对齐 | 工作区归档保存当前项目未保存 mask |
@@ -70,12 +71,13 @@ Authorization: Bearer <token>
 | DELETE | `/api/templates/{template_id}` | 删除模板 |
 | POST | `/api/media/upload` | 上传视频/图片/DICOM 单文件 |
 | POST | `/api/media/upload/dicom` | 批量上传 DICOM |
-| POST | `/api/media/parse` | 创建 Celery 拆帧任务 |
+| POST | `/api/media/parse` | 创建 Celery 拆帧任务；query 支持 `project_id`、`source_type`、`parse_fps`、`max_frames`、`target_width` |
 | 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 可选推理 |
+| POST | `/api/ai/propagate` | SAM 2 / SAM 3 视频片段传播并保存标注 |
 | GET | `/api/ai/models/status` | GPU 和 SAM 模型状态 |
 | POST | `/api/ai/auto` | 自动分割 |
 | POST | `/api/ai/annotate` | 保存 AI 标注 |
@@ -110,6 +112,25 @@ Authorization: Bearer <token>
 }
 ```
 
+### 创建标准帧序列拆帧任务
+
+```text
+POST /api/media/parse?project_id=1&parse_fps=15&max_frames=120&target_width=960
+```
+
+任务 `payload` 会记录本次拆帧参数；完成后的 `result.frame_sequence` 返回 `original_fps`、`parse_fps`、`frame_count`、`duration_ms`、`target_width`、帧宽高和 MinIO object prefix。每条 `FrameOut` 包含：
+
+```json
+{
+  "frame_index": 0,
+  "image_url": "http://...",
+  "width": 960,
+  "height": 540,
+  "timestamp_ms": 0,
+  "source_frame_number": 0
+}
+```
+
 ### 创建/更新模板
 
 ```json
@@ -150,11 +171,14 @@ Authorization: Bearer <token>
 
 - `point`
 - `box`
-- `semantic`，选择 `sam3` 时进入 SAM 3 文本语义推理；选择 `sam2` 时仍回退到 auto segmentation。SAM 3 真实可用性由 `/api/ai/models/status` 中的外部环境和 checkpoint access 状态决定。
+- `interactive`，用于 SAM 2 交互式细化，`prompt_data` 同时携带 `box`、累计 `points` 和 `labels`。
+- `semantic`，选择 `sam3` 时进入 SAM 3 文本语义推理；选择 `sam2` 时仍回退到 auto segmentation。SAM 3 真实可用性由 `/api/ai/models/status` 中的外部环境和本地 checkpoint 状态决定。
+
+选择 `sam3` 且发送 `box` 时，前端仍传 normalized `[x1, y1, x2, y2]`，后端适配层会转换成官方几何 prompt 的 `[center_x, center_y, width, height]` 正框；当前 SAM 3 不接正/反点修正。
 
 可选 `options` 字段：
 
-- `crop_to_prompt`：对 point/box prompt 按锚点或框附近区域裁剪后推理，再把 polygon 回映射到原图坐标。
+- `crop_to_prompt`：对 point/box/interactive prompt 按锚点或框附近区域裁剪后推理，再把 polygon 回映射到原图坐标。
 - `auto_filter_background`：过滤低分结果，并移除包含负向点的 polygon。
 - `min_score`：配合 `auto_filter_background` 使用的最低置信度阈值。
 
@@ -183,6 +207,32 @@ Authorization: Bearer <token>
 }
 ```
 
+### 视频片段传播请求体
+
+工作区“传播片段”调用：
+
+```json
+{
+  "project_id": 1,
+  "frame_id": 123,
+  "model": "sam2",
+  "direction": "forward",
+  "max_frames": 30,
+  "include_source": false,
+  "save_annotations": true,
+  "seed": {
+    "polygons": [[[0.1, 0.1], [0.3, 0.1], [0.3, 0.3]]],
+    "bbox": [0.1, 0.1, 0.2, 0.2],
+    "label": "胆囊",
+    "color": "#ff0000",
+    "class_metadata": {"id": "c1", "name": "胆囊", "color": "#ff0000", "zIndex": 20},
+    "template_id": 2
+  }
+}
+```
+
+`model=sam2` 使用 SAM 2 video predictor 的 mask seed 传播；`model=sam3` 使用独立 Python 3.12 helper 中的 SAM 3 video tracker，并以 seed bbox 作为初始提示。响应会返回已创建的 `annotations`，保存的 `mask_data.source` 为 `sam2_propagation` 或 `sam3_propagation`。
+
 ## 已完成的接口对齐
 
 - `updateProject()` 已从 `PUT` 改为 `PATCH`。