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。

AGENTS.md

@@ -6,7 +6,7 @@
 
 ## 项目概述
 
-本项目是一个**语义分割系统**（Semantic Segmentation System），当前形态是 React 前端 + FastAPI 后端的全栈 Web 应用，用于视频/DICOM 医学影像上传、服务器端拆帧、交互式 Canvas 标注、GT mask 导入、SAM 2/SAM 3 可选辅助分割、模板分类管理和标注导出。
+本项目是一个**语义分割系统**（Semantic Segmentation System），当前形态是 React 前端 + FastAPI 后端的全栈 Web 应用，用于视频/DICOM 医学影像上传、服务器端拆帧、交互式 Canvas 标注、视频片段传播、GT mask 导入、SAM 2/SAM 3 可选辅助分割、模板分类管理和标注导出。
 
 - **项目名称**: `react-example`（`package.json` 中的 `name`）
 - **前端入口**: `src/main.tsx` → `src/App.tsx`
@@ -39,7 +39,7 @@
 | 缓存 / 队列 Broker | Redis |
 | 后台任务 | Celery worker |
 | 对象存储 | MinIO |
-| AI 推理 | SAM 2 / SAM 3 可选模型 + PyTorch；SAM 3 通过独立 Python 3.12 conda 环境桥接；`GET /api/ai/models/status` 返回真实 GPU/模型/HF 权重访问状态 |
+| AI 推理 | SAM 2 / SAM 3 可选模型 + PyTorch；SAM 3 通过独立 Python 3.12 conda 环境桥接；`GET /api/ai/models/status` 返回真实 GPU/模型/本地 checkpoint 状态 |
 | 视频 / 影像处理 | FFmpeg / OpenCV / pydicom |
 | 运行时 | Node.js ES Modules；Python 3.11 后端环境；可选 `sam3` Python 3.12 conda 环境 |
 
@@ -78,12 +78,12 @@ Seg_Server/
 │   │   ├── projects.py            # /api/projects 与 /api/projects/{id}/frames
 │   │   ├── templates.py           # /api/templates
 │   │   ├── media.py               # /api/media/upload、/upload/dicom、/parse
-│   │   ├── ai.py                  # /api/ai/predict、/models/status、/auto、/annotate
+│   │   ├── ai.py                  # /api/ai/predict、/propagate、/models/status、/auto、/annotate
 │   │   └── export.py              # /api/export/{project_id}/coco、/masks
 │   └── services/
 │       ├── frame_parser.py        # FFmpeg/OpenCV 拆帧、pydicom 读片、帧上传
-│       ├── sam2_engine.py         # SAM 2 懒加载推理封装和 fallback
-│       ├── sam3_engine.py         # SAM 3 状态检测、外部环境桥接与文本语义推理适配器
+│       ├── sam2_engine.py         # SAM 2 单帧推理和 video predictor 传播封装
+│       ├── sam3_engine.py         # SAM 3 状态检测、外部环境桥接、文本语义推理、框选与 video tracker 适配器
 │       ├── sam3_external_worker.py # 独立 sam3 conda 环境中执行的状态/推理 helper
 │       └── sam_registry.py        # SAM 模型选择、GPU 状态与推理分发
 └── src/                           # React 前端
@@ -194,6 +194,7 @@ uvicorn main:app --host 0.0.0.0 --port 8000 --reload
   - `POST /api/tasks/{task_id}/cancel`
   - `POST /api/tasks/{task_id}/retry`
   - `POST /api/ai/predict`
+  - `POST /api/ai/propagate`
   - `GET /api/ai/models/status`
   - `POST /api/ai/auto`
   - `POST /api/ai/annotate`
@@ -219,14 +220,15 @@ uvicorn main:app --host 0.0.0.0 --port 8000 --reload
 1. 登录：`Login.tsx` 调用 `POST /api/auth/login`，默认开发凭证为 `admin / 123456`。
 2. 项目管理：`ProjectLibrary.tsx` 调用项目 API 创建项目、拉取列表。
 3. 上传资源：视频走 `/api/media/upload`；DICOM 批量走 `/api/media/upload/dicom`。
-4. 拆帧入队：前端调用 `/api/media/parse`；后端创建 `ProcessingTask` 并投递 Celery。
-5. worker 执行：Celery worker 用 FFmpeg 优先拆视频帧，失败后用 OpenCV fallback，DICOM 使用 pydicom，并持续更新任务进度。
-6. 帧展示：`VideoWorkspace.tsx` 调用 `/api/projects/{id}/frames`，`CanvasArea.tsx` 和 `FrameTimeline.tsx` 显示当前帧与时间轴缩略图。
-7. 手工标注：`CanvasArea.tsx` 支持多边形、矩形、圆、点区域和线段生成 polygon mask；点击 mask 可拖动/删除 polygon 顶点、通过边中点插入新顶点，并能选择编辑多 polygon mask 的单个子区域；区域合并/去除使用 `polygon-clipping` 做 union/difference；Zustand 维护 `maskHistory/maskFuture` 支持撤销/重做。
-8. AI 分割：前端工具包括正向点、反向点和框选；后端 `ai.py` 期望按 `image_id`、`prompt_type`、`prompt_data`、`model` 和可选 `options` 调用 SAM registry。SAM 2 支持点/框/自动分割；`options.crop_to_prompt` 可对点/框 prompt 做局部裁剪推理并回映射，`options.auto_filter_background` 可按分数和负向点过滤结果；SAM 3 入口支持文本语义推理，主后端会通过 `sam3_external_worker.py` 调用独立 Python 3.12 环境；如果 Python/CUDA/包/Hugging Face gated 权重访问任一条件不满足，会在状态接口中标为不可用。
-9. GT 导入：工作区“导入 GT Mask”调用 `/api/ai/import-gt-mask`；后端按非零像素值和连通域生成 polygon 标注，并用 distance transform 生成 seed point；前端回显 seed point，拖动后可归档更新。
-10. 模板管理：`TemplateRegistry.tsx` 管理分类、颜色和 z-index；`OntologyInspector.tsx` 在工作区显示当前模板分类树。
-11. 导出：后端支持 COCO JSON 和 PNG mask ZIP 导出；PNG ZIP 包含单标注 mask、按 zIndex 融合的语义 mask 和 `semantic_classes.json`。
+4. 拆帧入队：前端调用 `/api/media/parse`；后端创建 `ProcessingTask` 并投递 Celery，接口支持 `parse_fps`、`max_frames` 和 `target_width` 标准帧序列参数。
+5. worker 执行：Celery worker 用 FFmpeg 优先拆视频帧，失败后用 OpenCV fallback，DICOM 使用 pydicom；视频帧按 `frame_%06d.jpg` 连续命名并记录 `timestamp_ms`、`source_frame_number` 和任务 `frame_sequence` 元数据。
+6. 帧展示：`VideoWorkspace.tsx` 调用 `/api/projects/{id}/frames`，`CanvasArea.tsx` 和 `FrameTimeline.tsx` 显示当前帧与时间轴缩略图；前端 `Frame` 会保留后端返回的帧序列时间戳和源帧号。
+7. 手工标注：`CanvasArea.tsx` 支持多边形、矩形、圆、点区域和线段生成 polygon mask；多边形可按 Enter 或点击首节点闭合；绘制工具可在已有 mask 上继续落点；点击 mask 可拖动/删除 polygon 顶点、通过边中点插入新顶点，并能选择编辑多 polygon mask 的单个子区域；选中整块 mask 可用 Delete/Backspace 删除，已保存 mask 会同步后端删除；区域合并/去除会隐藏编辑手柄并显示已选数量，使用 `polygon-clipping` 做 union/difference，内含去除结果用 even-odd 规则渲染 hole；Zustand 维护 `maskHistory/maskFuture` 支持撤销/重做。
+8. AI 分割：前端工具包括正向点、反向点和框选；SAM 2 框选会建立候选 mask，后续正/反点通过 `interactive` prompt 携带原始框和累计点细化同一个候选 mask；后端 `ai.py` 期望按 `image_id`、`prompt_type`、`prompt_data`、`model` 和可选 `options` 调用 SAM registry。SAM 2 支持点/框/interactive/自动分割和 video predictor 传播；`options.crop_to_prompt` 可对点/框/interactive prompt 做局部裁剪推理并回映射，`options.auto_filter_background` 可按分数和负向点过滤结果；SAM 3 入口支持文本语义推理、框选提示和 external video tracker，主后端会通过 `sam3_external_worker.py` 调用独立 Python 3.12 环境，并优先使用 `sam3_checkpoint_path` 指向的本地 `sam3权重/sam3.pt`；如果 Python/CUDA/包/本地 checkpoint 均满足，会在状态接口中标为可用。
+9. 视频片段传播：工作区“传播片段”把当前选中 mask 或当前帧第一个 mask 作为 seed，调用 `POST /api/ai/propagate`；后端按项目帧序列下载片段帧，SAM 2 用 `SAM2VideoPredictor.add_new_mask()` + `propagate_in_video()`，SAM 3 用独立 helper 的官方 `build_sam3_video_predictor()`，并把后续帧结果保存为 `Annotation`。
+10. GT 导入：工作区“导入 GT Mask”调用 `/api/ai/import-gt-mask`；后端按非零像素值和连通域生成 polygon 标注，并用 distance transform 生成 seed point；前端回显 seed point，拖动后可归档更新。
+11. 模板管理：`TemplateRegistry.tsx` 管理分类、颜色和 z-index；`OntologyInspector.tsx` 在工作区显示当前模板分类树。
+12. 导出：后端支持 COCO JSON 和 PNG mask ZIP 导出；PNG ZIP 包含单标注 mask、按 zIndex 融合的语义 mask 和 `semantic_classes.json`。
 
 ---
 
@@ -240,6 +242,7 @@ uvicorn main:app --host 0.0.0.0 --port 8000 --reload
 - 前端 `importGtMask()` 已对齐后端 `/api/ai/import-gt-mask`；工作区“导入 GT Mask”会导入后端生成的多类别标注和 seed point 并回显。
 - 前端 `exportCoco()` 已对齐后端 `/api/export/{project_id}/coco`；前端 `exportMasks()` 已对齐后端 `/api/export/{project_id}/masks`；工作区导出按钮会先保存当前待归档 mask。
 - 工作区“结构化归档保存”按钮已接入 `POST /api/ai/annotate` 和 `PATCH /api/ai/annotations/{id}`；加载工作区时会通过 `GET /api/ai/annotations` 回显已保存标注。
+- 工作区“传播片段”按钮已接入 `POST /api/ai/propagate`；SAM 2 路径使用视频 predictor，SAM 3 路径使用独立 Python helper 的官方 video tracker，完成后刷新后端已保存标注。
 - 工作区“清空遮罩”会调用 `DELETE /api/ai/annotations/{id}` 删除当前帧已保存标注，并清空当前帧本地 mask。
 - 项目状态已统一为 `pending`、`parsing`、`ready`、`error`；前端 `src/lib/api.ts` 会兼容归一化旧库中可能存在的 `Ready`、`Parsing`、`Error`。
 - `server.ts` 仍有旧版 `/api/login`、`/api/projects`、`/api/templates` mock；当前前端真实 API 调用主要走 FastAPI 的 `/api/auth/*`、`/api/projects`、`/api/templates` 等接口。