feat: 完善 SAM2.1 模型选择与标注工作流

- 后端 SAM2 引擎新增 sam2.1_hiera_tiny、sam2.1_hiera_small、sam2.1_hiera_base_plus、sam2.1_hiera_large 四个变体定义，并按变体维护 checkpoint/config、image predictor、video predictor、加载状态、错误信息和真实状态回报。

- 后端 SAM registry 仅暴露当前产品启用的 SAM2.1 变体，保留 sam2 作为 tiny 兼容别名，拒绝 sam3 产品入口，并把 point、box、interactive、auto、propagate 都分发到所选 SAM2.1 变体。

- 后端默认配置和下载脚本切换到 SAM2.1 checkpoint 命名，支持 legacy SAM2 checkpoint fallback，并在状态消息中标出 fallback 使用情况。

- 前端全局 AI 模型状态新增 SAM2.1 tiny/small/base+/large 类型和默认 tiny，API 请求默认携带 sam2.1_hiera_tiny，AI 页面提供模型变体选择和所选模型状态展示。

- AI 智能分割页移除当前产品不使用的 SAM3/文本提示入口，保留正向点、反向点、框选和参数开关；AI 页只展示本页生成的候选 mask，并支持遮罩清晰度调节、候选 mask 上继续加正/反点、清空本页候选、推送到工作区编辑。

- 工作区和 Canvas 补强 SAM2 交互式细化链路：框选后正/反点继续细化同一个候选 mask，反向点请求启用背景过滤，空结果会移除被否定候选；AI 推送到工作区后保留选中态和未保存 draft mask。

- 工作区标注保存闭环补强：未保存 mask 可归档保存，dirty saved mask 可更新，保存后用后端 saved annotation 替换已提交 draft，清空/删除已保存 mask 时同步后端删除。

- Dashboard 任务进度区改为展示 queued、running、success、failed、cancelled 最近任务，处理中统计只计算 queued/running，并保留近期完成记录。

- 时间轴在顶部时间进度条和底部缩略图导航轴之间新增已编辑帧标记带，基于当前项目帧内 masks 标出已有编辑/标注的帧，并支持点击标记跳转。

- 前端测试覆盖 SAM2.1 变体选择、模型状态徽标、AI 页候选隔离、遮罩透明度、候选上追加正/反点、推送工作区保留选择、Canvas 交互式细化、VideoWorkspace 传播/保存、Dashboard 进度和时间轴已编辑帧标记。

- 后端测试覆盖 SAM2.1 变体状态、sam2 alias 兼容、sam3 禁用、semantic 禁用、传播标注保存、Dashboard 最近任务状态和 SAM3 历史测试跳过说明。

- README、AGENTS 和 doc 文档同步当前真实进度，更新 SAM2.1 变体、SAM3 禁用、接口契约、设计冻结、需求冻结、前端元素审计、实施计划、FastAPI docs 说明和测试矩阵。

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

@@ -20,7 +20,7 @@ Word 方案描述的理想系统包含：
 - FastAPI 后端，使用 WebSocket 处理实时交互与任务进度。
 - Celery + Redis 处理视频拆帧等长任务。
 - FFmpeg/OpenCV 解析视频，pydicom 解析医学影像。
-- 本地 CUDA 上的 SAM 3 推理。
+- 本地 CUDA 上的 SAM 推理；当前产品实现启用可选 SAM 2.1 tiny/small/base+/large，SAM 3 因没有文本提示入口而暂时禁用。
 - GT mask 导入后通过距离变换、骨架提取、聚类等算法降维为点区域。
 - 模板库管理分类、颜色和 z-index，用于语义分割遮罩重叠裁决。
 - PostgreSQL 存储项目、帧、模板和点区域数据。
@@ -38,14 +38,14 @@ Word 方案描述的理想系统包含：
 | 视频拆帧 | 已落地 | `backend/services/frame_parser.py`、`backend/routers/media.py` |
 | DICOM 批量导入 | 部分落地 | 上传和解析存在，项目级体验还需完善 |
 | WebSocket 进度 | 已落地 | 拆帧进度写入任务表后发布到 Redis `seg:progress`，FastAPI 广播到 `/ws/progress` |
-| SAM 推理 | 部分落地 | 后端已有 SAM 2 / SAM 3 选择和真实模型状态接口；SAM 2 已接 video predictor 片段传播；SAM 3 通过独立 Python 3.12 环境桥接，支持文本/框提示和 official video tracker 入口，状态会检查 Python/CUDA/包/本地 checkpoint |
+| SAM 推理 | 部分落地 | 当前产品入口启用 SAM 2.1 tiny/small/base+/large 和真实 GPU/SAM2.1 状态接口；SAM 2.1 已接 point/box/interactive 和 video predictor 片段传播。SAM 3 桥接源码保留，但前端入口和后端 registry 已禁用 |
 | 模板库 | 部分落地 | 分类、颜色、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` 外部环境桥接、`sam3_external_worker.py` 和 `setup_sam3_env.sh`；本机 `sam3` 环境已满足 Python 3.12、PyTorch 2.10/cu128、CUDA/GPU、官方包导入和本地 `sam3权重/sam3.pt` checkpoint 状态检查。官方没有 SAM 3 tiny/small 权重，当前可选最小真实 SAM 权重仍是 SAM 2 tiny；video tracker 入口已接入，真实效果取决于本地 checkpoint 是否兼容 video model。
+- SAM 3：`sam3_engine.py`、`sam3_external_worker.py` 和 `setup_sam3_env.sh` 作为历史实现保留；由于当前系统不给文本提示，前端不再展示 SAM 3，后端 registry 也不暴露 `sam3`。官方没有 SAM 3 tiny/small 权重，当前可选最小真实 SAM 权重仍是 SAM 2.1 tiny。
 - Celery 异步任务队列：已注册 Celery app 和拆帧 worker task，`/api/media/parse` 会创建任务表记录并入队。
 - GT mask 导入：当前已支持二值/多类别 mask 导入，后端会按非零像素值拆分区域，生成 polygon 标注和距离变换 seed point；骨架提取、HDBSCAN 和模板自动映射尚未实现。
 - Mask 到点区域的拓扑降维：当前完成 distance transform seed point 和前端 seed point 拖拽编辑；骨架提取、HDBSCAN 等增强尚未实现。
@@ -55,4 +55,4 @@ Word 方案描述的理想系统包含：
 
 ## 结论
 
-当前项目已经从 UI 原型推进到“可上传、可异步拆帧、可取消/重试任务、可查看失败详情、可实时查看任务进度、可浏览项目帧、可维护模板、可手工绘制、可逐点编辑 polygon、可边中点插点、可多 polygon 子区域编辑、可区域合并/去除、可点/框 AI 推理、可对点/框 prompt 做裁剪推理和背景过滤、可用 SAM 2 / SAM 3 进行视频片段传播、可导入多类别 GT mask、可编辑 seed point、可保存标注、可导出 COCO/语义 mask ZIP、可查看 Dashboard 后端概览”的全栈雏形。下一阶段最重要的是继续补齐 SAM 3 真实视频 tracker smoke test、复杂洞结构编辑和 GT mask 骨架/聚类增强。
+当前项目已经从 UI 原型推进到“可上传、可异步拆帧、可取消/重试任务、可查看失败详情、可实时查看任务进度、可浏览项目帧、可维护模板、可手工绘制、可逐点编辑 polygon、可边中点插点、可多 polygon 子区域编辑、可区域合并/去除、可用可选 SAM 2.1 做点/框 AI 推理、可对点/框 prompt 做裁剪推理和背景过滤、可用 SAM 2.1 进行视频片段传播、可导入多类别 GT mask、可编辑 seed point、可保存标注、可导出 COCO/语义 mask ZIP、可查看 Dashboard 后端概览”的全栈雏形。下一阶段最重要的是继续补齐复杂洞结构编辑、GT mask 骨架/聚类增强和传播任务异步化。

doc/02-current-implementation-map.md

@@ -99,7 +99,7 @@
 ## 当前主要风险点
 
 - 前端 API/WS 地址虽然已支持环境变量和 hostname 推导，但部署时仍需要确认浏览器可访问 `:8000` 后端。
-- AI 语义文本提示在选择 SAM 3 且运行环境满足官方依赖、并具备 Hugging Face gated 权重访问时走 SAM 3；当前状态接口会分别暴露外部 Python 环境、CUDA、包导入和 checkpoint access 是否满足。
+- AI 当前启用 SAM 2.1 tiny/small/base+/large 点/框/interactive 路径；语义文本提示和 SAM 3 产品入口已禁用，`model=sam3` 会被后端拒绝。SAM 3 源码保留但不计入当前可用功能。
 - 工作区顶部“导出 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,7 +30,7 @@
 | 元素 | 状态 | 说明 |
 |------|------|------|
 | WebSocket 连接状态 | 真实可用 | 前端通过 `src/lib/config.ts` 推导或读取 `VITE_WS_PROGRESS_URL`，后端有 `/ws/progress` |
-| 解析队列任务 | 真实可用 | 初始数据来自 `GET /api/dashboard/overview`，按 `processing_tasks` queued/running/failed/cancelled 任务生成 |
+| 任务进度 | 真实可用 | 初始数据来自 `GET /api/dashboard/overview`，按 `processing_tasks` queued/running/success/failed/cancelled 任务生成；统计卡片中的处理中任务数只计算 queued/running |
 | 任务取消 | 真实可用 | 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 和时间 |
@@ -61,13 +61,13 @@
 | 当前项目名 | 真实可用 | 读取 `currentProject.name` |
 | 自动加载项目帧 | 真实可用 | 调用 `GET /api/projects/{id}/frames` |
 | 无帧项目提示 | 真实可用 | 如果 `video_path` 存在但无帧，只提示回到项目库生成帧，不自动创建拆帧任务 |
-| SAM 模型状态徽标 | 真实可用 | 调用 `GET /api/ai/models/status`，显示当前选择的 SAM 2/SAM 3 是否可用 |
-| 已保存标注回显 | 真实可用 | 加载工作区帧后调用 `GET /api/ai/annotations` 并渲染已保存 mask |
+| SAM 模型状态徽标 | 真实可用 | 调用 `GET /api/ai/models/status`，显示当前启用的 SAM 2 与 GPU 状态 |
+| 已保存标注回显 | 真实可用 | 加载工作区帧后调用 `GET /api/ai/annotations` 并渲染已保存 mask；回显时保留当前项目帧里尚未保存的 AI/手工 draft mask，避免从 AI 页推送的候选被覆盖 |
 | “导出 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 或当前帧第一个 mask 作为 seed，调用 `POST /api/ai/propagate`；SAM 2 走 video predictor，SAM 3 走 external video tracker，完成后刷新已保存标注 |
-| “结构化归档保存”按钮 | 真实可用 | 未保存 mask 写入 `POST /api/ai/annotate`；dirty mask 写入 `PATCH /api/ai/annotations/{id}` |
+| “传播片段”按钮 | 真实可用 | 使用当前选中 mask 或当前帧第一个 mask 作为 seed，调用 `POST /api/ai/propagate`；当前启用 SAM 2 video predictor，完成后刷新已保存标注 |
+| “结构化归档保存”按钮 | 真实可用 | 未保存 mask 写入 `POST /api/ai/annotate`；dirty mask 写入 `PATCH /api/ai/annotations/{id}`；保存成功后会重新拉取后端标注，并用 saved annotation 替换本次提交的 draft mask，避免仍显示未保存 |
 
 ## CanvasArea 画布
 
@@ -109,6 +109,7 @@
 | 点击缩略图跳帧 | 真实可用 | 调用 `setCurrentFrame(idx)` |
 | 顶部 range 拖动 | 真实可用 | 改变当前帧 |
 | 具体时间显示 | 真实可用 | 根据项目 `parse_fps/original_fps` 显示当前时间和总时长，格式为 `mm:ss.cc` |
+| 已编辑帧标记带 | 真实可用 | 根据当前项目帧内的 `masks` 计算有编辑/标注的帧，在顶部进度条和缩略图导航轴之间显示标记；点击标记可跳转到对应帧 |
 | 播放/暂停 | 真实可用 | 当前代码按 `parse_fps/original_fps` 推进帧，最多 30fps |
 | 方向键切帧 | 真实可用 | 全局监听左右方向键切到上一帧/下一帧；焦点在 input、textarea、select 或 contentEditable 内时不会拦截 |
 
@@ -127,16 +128,17 @@
 
 | 元素 | 状态 | 说明 |
 |------|------|------|
-| 模型选择 SAM2/SAM3 | 真实可用 | 选择写入 Zustand，`predictMask()` 会把 `model` 传给后端 SAM registry |
-| 正向/反向点 | 真实可用 | 可在当前项目帧上加点并调用 AI 推理接口；SAM 2 框选后会携带原始框和累计正/反点细化同一个候选 mask；SAM 3 选择后会提示点交互需切回 SAM 2 |
-| SAM 3 框选 | 真实可用 | 工作区选择 SAM 3 后可使用框选工具；后端通过官方 `add_geometric_prompt()` 正框执行 SAM 3 几何提示推理 |
-| 语义文本输入 | 部分可用 | 纯文本会以 `semantic` prompt 调用后端；选择 SAM 3 且独立 Python 3.12 环境、CUDA、官方包和本地 checkpoint 均满足时走 SAM 3 文本语义推理，否则状态接口会标明不可用；空文本、失败和 0 mask 返回会显示前端反馈 |
+| SAM 2.1 变体选择 / 模型状态 | 真实可用 | AI 页可选 tiny/small/base+/large，调用 `GET /api/ai/models/status?selected_model=<variant>` 展示所选变体和 GPU 状态；只有本地存在 checkpoint 的变体显示可用 |
+| 正向/反向点 | 真实可用 | 可在当前项目帧上加点并调用 AI 推理接口；AI 页中点击已有候选 mask 时也会继续添加当前正/反向提示点；SAM 2.1 框选后会携带原始框和累计正/反点细化同一个候选 mask |
+| SAM 3 入口 | 当前禁用 | 因当前系统不提供文本提示，前端不再显示 SAM 3 模型选择、文本输入或 SAM 3 框选入口；后端 `model=sam3` 返回不支持 |
+| 语义文本输入 | 当前禁用 | AI 页不再提供文本语义输入；后端收到 `semantic` prompt 会返回 400 |
 | 参数开关 | 真实可用 | `cropMode` 会随 `/api/ai/predict` 发送 `crop_to_prompt`，后端对点/框 prompt 裁剪推理区域并回映射 polygon；`autoDeleteBg` 会发送 `auto_filter_background` 和 `min_score`，后端过滤低分结果和覆盖负向点的结果 |
-| 执行高精度语义分割 | 真实可用 | 使用当前项目帧调用 `/api/ai/predict`；SAM 2 需要点提示且只采用最高分候选，SAM 3 需要文本语义提示；生成结果写入全局 masks 并自动选中，右侧分类树可立即换标签 |
-| 推送至工作区编辑 | 真实可用 | 切回工作区并把工具切到“调整多边形”，保留 AI 页选中的 mask，便于继续调轮廓和归档 |
+| 遮罩清晰度 | 真实可用 | 调节 AI 页候选 mask 的预览透明度，只影响本页显示，不改变 mask 几何、分类或保存数据 |
+| 执行高精度语义分割 | 真实可用 | 使用当前项目帧和所选 SAM 2.1 变体调用 `/api/ai/predict`；SAM 2.1 需要点/框提示且只采用最高分候选；AI 页只渲染本页新生成候选，不显示工作区已有 mask；生成结果写入全局 masks 并自动选中，右侧分类树可立即换标签 |
+| 推送至工作区编辑 | 真实可用 | 切回工作区并把工具切到“调整多边形”，保留 AI 页选中的未保存 mask；工作区回显后端标注时不会覆盖这类 draft mask |
 | 上传替换底图 | Mock / UI-only | 按钮无事件 |
 | 撤销/重做 | 真实可用 | 绑定全局 mask 历史栈 |
-| 清空全体锚点 | 部分可用 | 清空前端 points 和 masks |
+| 清空全体锚点 | 真实可用 | 清空 AI 页提示点和本页生成的候选 mask，不删除工作区已有 mask |
 | 退档推送至工作区重组 | 部分可用 | 只切回工作区，共用 masks store，但没有保存/确认流程 |
 | 背景图 | 部分可用 | 优先显示当前项目帧；没有项目帧时仍回退到 Unsplash 演示图 |
 
@@ -158,4 +160,4 @@
 
 当前前端真实可用的主链路是：登录、Dashboard 后端概览、项目列表、新建项目、上传视频/DICOM、显式生成帧、浏览帧、播放帧、工作区手工绘制、点/框 AI 推理、视频片段传播、GT mask 导入、标注保存/回显、COCO 导出、PNG mask ZIP 导出、模板 CRUD。
 
-当前最主要的 Mock 或未打通链路是：polygon 插点/边编辑增强、真正的文本语义分割、骨架/HDBSCAN 级别的 mask 降维增强、任务历史筛选、项目更多菜单和若干检查面板指标。
+当前最主要的 Mock 或未打通链路是：真正的文本语义分割已因无文本提示入口而暂时禁用；复杂洞结构编辑、骨架/HDBSCAN 级别的 mask 降维增强、任务历史筛选、项目更多菜单和若干检查面板指标仍未落地。

doc/04-api-contracts.md

@@ -39,7 +39,7 @@ Authorization: Bearer <token>
 | `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 的真实运行状态 |
+| `getAiModelStatus(selectedModel?)` | `GET /api/ai/models/status` | 对齐 | 返回 GPU 和四个 SAM 2.1 变体状态；`selected_model=sam3` 返回不支持 |
 | `getProjectAnnotations(projectId, frameId?)` | `GET /api/ai/annotations` | 对齐 | 前端加载工作区时用于回显已保存标注 |
 | `saveAnnotation(payload)` | `POST /api/ai/annotate` | 对齐 | 工作区归档保存当前项目未保存 mask |
 | `updateAnnotation(annotationId, payload)` | `PATCH /api/ai/annotations/{annotation_id}` | 对齐 | 工作区归档保存 dirty mask |
@@ -76,8 +76,8 @@ Authorization: Bearer <token>
 | 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 视频片段传播并保存标注 |
+| POST | `/api/ai/predict` | 当前启用 SAM 2 点/框/interactive 推理 |
+| POST | `/api/ai/propagate` | 当前启用 SAM 2 视频片段传播并保存标注 |
 | GET | `/api/ai/models/status` | GPU 和 SAM 模型状态 |
 | POST | `/api/ai/auto` | 自动分割 |
 | POST | `/api/ai/annotate` | 保存 AI 标注 |
@@ -173,7 +173,7 @@ POST /api/media/parse?project_id=1&parse_fps=15&max_frames=120&target_width=960
 ```json
 {
   "image_id": 123,
-  "model": "sam2",
+  "model": "sam2.1_hiera_tiny",
   "prompt_type": "point",
   "prompt_data": {
     "points": [[0.5, 0.5]],
@@ -187,19 +187,19 @@ POST /api/media/parse?project_id=1&parse_fps=15&max_frames=120&target_width=960
 - `point`
 - `box`
 - `interactive`，用于 SAM 2 交互式细化，`prompt_data` 同时携带 `box`、累计 `points` 和 `labels`。
-- `semantic`，选择 `sam3` 时进入 SAM 3 文本语义推理。前端 AI 页面不会再用 SAM 2 发送纯文本 semantic；SAM 2 的交互入口应使用点/框提示。SAM 3 真实可用性由 `/api/ai/models/status` 中的外部环境和本地 checkpoint 状态决定。
+- `semantic` 当前被禁用；由于产品不提供文本提示，前端不会显示语义文本入口，后端收到 semantic 会返回 400。
 
 SAM 2 点提示和 auto fallback 当前只采用最高分候选 mask，避免同一提示下多个备选 mask 被前端叠加显示。
 
 工作区 SAM 2 请求包含反向点时，`CanvasArea` 会发送 `options.auto_filter_background=true` 和 `options.min_score=0.05`；如果负向点过滤后没有可用 polygon，前端会移除当前旧候选 mask 并要求重新框选或添加正向点。
 
-选择 `sam3` 且发送 `box` 时，前端仍传 normalized `[x1, y1, x2, y2]`，后端适配层会转换成官方几何 prompt 的 `[center_x, center_y, width, height]` 正框；当前 SAM 3 不接正/反点修正。
+当前 registry 暴露 `sam2.1_hiera_tiny`、`sam2.1_hiera_small`、`sam2.1_hiera_base_plus`、`sam2.1_hiera_large`，并兼容 `sam2` 作为 tiny 别名；发送 `model=sam3` 会返回 400 Unsupported model。SAM 3 源码文件保留在仓库中，但没有接入当前运行时模型列表。
 
 可选 `options` 字段：
 
 - `crop_to_prompt`：对 point/box/interactive prompt 按锚点或框附近区域裁剪后推理，再把 polygon 回映射到原图坐标。
 - `auto_filter_background`：过滤低分结果，并移除包含负向点的 polygon。
-- `min_score`：配合 `auto_filter_background` 使用的最低置信度阈值；对 SAM 3 semantic 请求也会作为 external worker 的 `confidence_threshold` 传入，避免本地 checkpoint 在默认高阈值下返回 0 个 mask。
+- `min_score`：配合 `auto_filter_background` 使用的最低置信度阈值。
 
 后端响应：
 
@@ -234,7 +234,7 @@ SAM 2 点提示和 auto fallback 当前只采用最高分候选 mask，避免同
 {
   "project_id": 1,
   "frame_id": 123,
-  "model": "sam2",
+  "model": "sam2.1_hiera_tiny",
   "direction": "forward",
   "max_frames": 30,
   "include_source": false,
@@ -250,7 +250,7 @@ SAM 2 点提示和 auto fallback 当前只采用最高分候选 mask，避免同
 }
 ```
 
-`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`。
+SAM 2.1 变体使用对应 video predictor 的 mask seed 传播；`model=sam2` 会兼容归一化为 tiny，`model=sam3` 当前不支持。响应会返回已创建的 `annotations`，保存的 `mask_data.source` 为 `<model_id>_propagation`。
 
 ## 已完成的接口对齐
 
@@ -270,7 +270,7 @@ SAM 2 点提示和 auto fallback 当前只采用最高分候选 mask，避免同
 - `cancelTask()` 已接入 `POST /api/tasks/{taskId}/cancel`。
 - `retryTask()` 已接入 `POST /api/tasks/{taskId}/retry`。
 - `getDashboardOverview()` 已从 `processing_tasks` 聚合解析队列。
-- Dashboard 任务列表已展示 queued/running/failed/cancelled 任务，并可通过 `getTask()` 查看失败详情。
+- Dashboard 任务列表已展示 queued/running/success/failed/cancelled 任务，并可通过 `getTask()` 查看失败详情；`summary.parsing_task_count` 仍只统计 queued/running。
 - 工作区导出按钮已调用 `exportCoco()` / `exportMasks()`，并会先保存未归档 mask。
 - PNG mask ZIP 已包含每帧 `semantic_frame_*.png` 和 `semantic_classes.json`，重叠区域按 zIndex 裁决。
 

doc/05-implementation-plan.md

@@ -16,7 +16,7 @@
 
 剩余边界：
 
-1. SAM 3 已完成独立 Python 3.12 环境安装脚本、外部 worker 桥接、本地 `sam3权重/sam3.pt` checkpoint 状态检查、本地 checkpoint 加载参数接入、单帧文本/框提示和 video tracker API 入口；下一步需要基于真实业务帧验证语义召回质量和视频 tracker 稳定性。
+1. SAM 3 相关源码和安装脚本保留，但当前产品入口已禁用：前端不展示 SAM 3，后端 registry 不暴露 `sam3`，`model=sam3` 请求返回不支持。若后续重新需要文本语义提示，再恢复前端入口、registry、状态接口和对应测试。
 2. 标注删除/更新接口已打通基础能力；逐点几何编辑器已支持顶点拖动/删除、边中点插入和多 polygon 子区域选择编辑，复杂洞结构仍待增强。
 
 ## 阶段 2：打通标注保存（已完成基础闭环）
@@ -136,14 +136,14 @@ Word 方案中的完整版本包含距离变换、骨架提取和聚类。当前
 1. 前端 `propagateMasks()` 已接入 `POST /api/ai/propagate`。
 2. 工作区按钮会把 seed mask 的 normalized polygon、bbox、label、color 和 class 元数据传给后端。
 3. SAM 2 路径使用官方 `SAM2VideoPredictor.add_new_mask()` 和 `propagate_in_video()`。
-4. SAM 3 路径通过 `sam3_external_worker.py` 调用独立 Python 3.12 环境中的官方 `build_sam3_video_predictor()`。
+4. SAM 3 video tracker 路径已从当前产品入口禁用，相关 helper 仅保留作后续恢复参考。
 5. 后端会跳过源帧，把传播结果保存到后续帧 `annotations`，并在完成后由前端刷新回显。
 
 剩余建议：
 
 1. 把传播任务改为异步任务，接入 Dashboard 和 WebSocket 进度。
 2. 前端增加传播方向、帧数和覆盖已有标注策略设置。
-3. 用真实长视频分别做 SAM 2 / SAM 3 tracker smoke test 和质量评估。
+3. 用真实长视频做 SAM 2 tracker smoke test 和质量评估；如果未来恢复 SAM 3，再单独补充 SAM 3 tracker 评估。
 
 ## 阶段 8：清理 UI 文案与 Mock
 

doc/06-fastapi-docs-explained.md

@@ -65,7 +65,7 @@ FastAPI 会根据代码里的路由和 Pydantic schema 自动生成 OpenAPI 描
 - Projects：项目 CRUD、项目帧 CRUD
 - Templates：模板 CRUD
 - Media：上传视频/DICOM、触发拆帧
-- AI：SAM 2 / SAM 3 可选推理、模型状态、自动分割、保存标注
+- AI：当前启用 SAM 2 推理、模型状态、自动分割、保存标注；SAM 3 源码保留但产品入口禁用
 - Export：导出 COCO JSON、导出 PNG masks
 - Health：健康检查
 

doc/07-current-requirements-freeze.md

@@ -29,7 +29,7 @@
 - 未提供项目 ID 上传时，后端自动创建项目。
 - 提供项目 ID 上传时，后端把上传对象关联到该项目。
 - 拆帧接口根据项目 `source_type` 处理视频或 DICOM。
-- 拆帧接口支持 `parse_fps`、`max_frames` 和 `target_width` 参数，用于生成可被 SAM 2 / SAM 3 视频处理复用的标准帧序列。
+- 拆帧接口支持 `parse_fps`、`max_frames` 和 `target_width` 参数，用于生成可被 SAM 2 视频处理复用的标准帧序列。
 - 视频帧使用连续 `frame_%06d.jpg` 命名，默认从 `frame_000000.jpg` 开始，并按 `target_width` 缩放。
 - 拆帧完成后写入 `frames` 记录，并把项目状态设为 `ready`。
 - 每条帧记录包含 `frame_index`、`image_url`、`width`、`height`、`timestamp_ms` 和 `source_frame_number`。
@@ -49,6 +49,7 @@
 - 时间轴支持缩略图点击切帧、range 拖动切帧、键盘左右方向键切帧、播放/暂停顺序推进帧。
 - 播放帧率使用项目 `parse_fps` 或 `original_fps`，限制在 1 到 30 FPS。
 - 时间轴显示当前帧时间和总时长，时间基准使用项目 `parse_fps` 或 `original_fps`，格式为 `mm:ss.cc`。
+- 时间轴在顶部进度条和底部缩略图导航轴之间显示“已编辑”标记带，基于当前项目帧内的 `masks` 标出已有编辑/标注的帧；点击标记可跳转到对应帧。
 
 ## R5 工具栏
 
@@ -71,26 +72,30 @@
 
 ## R6 AI 推理
 
-- 前端可以在 AI 页面选择 `sam2` 或 `sam3`，选择结果存放在全局 store。
-- 前端和工作区通过 `GET /api/ai/models/status` 展示 GPU、SAM 2 和 SAM 3 的真实运行状态。
+- 当前 AI 页面支持选择 `sam2.1_hiera_tiny`、`sam2.1_hiera_small`、`sam2.1_hiera_base_plus`、`sam2.1_hiera_large`；SAM 3 选择、文本输入和相关状态展示已隐藏。
+- 前端和工作区通过 `GET /api/ai/models/status` 展示 GPU 和四个 SAM 2.1 变体的真实运行状态；`selected_model=sam3` 会被后端拒绝。
 - 前端 `predictMask()` 调用 `POST /api/ai/predict`。
 - 前端发送后端契约：`image_id`、`prompt_type`、`prompt_data`、`model`。
 - 点提示传 `{ points, labels }`，正向点 label 为 1，反向点 label 为 0。
+- AI 页面在已有候选 mask 上点击正向/反向选点时，应继续添加提示点，不应被 mask 选择事件拦截。
 - 框选提示传归一化 `[x1, y1, x2, y2]`。
-- 工作区 SAM 2 框选会建立一个候选 mask；后续正向点/反向点会携带原始框和累计点，以 `interactive` prompt 细化并替换同一个候选 mask。
-- 工作区 SAM 2 一旦包含反向点，会随请求启用 `auto_filter_background` 和 `min_score=0.05`；若后端判定反向点排除了当前候选区域并返回空结果，前端会移除旧候选 mask，避免继续显示已被否定的区域。
-- SAM 2 不支持文本语义提示；AI 页面在 SAM 2 下输入纯文本时会提示用户改用点提示或切换 SAM 3，不再回退到自动分割。
-- SAM 2 点提示和 auto fallback 默认只采用一个最高分候选 mask，避免多个候选 mask 作为同一结果重叠显示。
-- AI 页面生成的 SAM 2/SAM 3 mask 会写入全局 `masks`，自动同步到当前项目帧，并写入全局 `selectedMaskIds`；右侧语义分类树可以直接给新生成 mask 换标签。
+- 工作区 SAM 2.1 框选会建立一个候选 mask；后续正向点/反向点会携带原始框和累计点，以 `interactive` prompt 细化并替换同一个候选 mask。
+- 工作区 SAM 2.1 一旦包含反向点，会随请求启用 `auto_filter_background` 和 `min_score=0.05`；若后端判定反向点排除了当前候选区域并返回空结果，前端会移除旧候选 mask，避免继续显示已被否定的区域。
+- SAM 2.1 不支持文本语义提示；当前 AI 页面不提供文本语义输入，必须使用点/框提示。
+- SAM 2.1 点提示和 auto fallback 默认只采用一个最高分候选 mask，避免多个候选 mask 作为同一结果重叠显示。
+- AI 页面只渲染本页新生成的候选 mask；工作区已有手工、保存、传播或 GT 导入 mask 不会自动进入 AI 画布。
+- AI 页面提供“遮罩清晰度”滑杆，调节本页候选 mask 的预览透明度，不改变 mask 几何、分类或保存数据。
+- AI 页面生成的 SAM 2.1 mask 会写入全局 `masks`，自动同步到当前项目帧，并写入全局 `selectedMaskIds`；右侧语义分类树可以直接给新生成 mask 换标签。
+- AI 页“清空全体锚点”只清空本页提示点和本页生成的候选 mask，不删除工作区已有 mask。
 - AI 页面“推送至工作区编辑”会切回工作区并把工具切到“调整多边形”，保留当前选中的 AI mask 以便继续编辑轮廓和归档保存。
-- 语义文本提示传 `semantic`；选择 `sam3` 且独立 Python 3.12 环境、CUDA、官方包和本地 checkpoint 均满足时走 SAM 3 文本语义推理。
-- SAM 3 支持工作区框选提示；后端把 normalized `[x1, y1, x2, y2]` 转成官方 `add_geometric_prompt()` 需要的 `[center_x, center_y, width, height]` 正框。
-- 当前 SAM 3 前端路径不支持正/反点修正；在工作区用 SAM 3 进行点交互时，前端会提示切回 SAM 2。
+- 工作区加载后端已保存标注时，必须保留当前项目帧里尚未保存的 AI/手工 draft mask，避免 AI 页推送到工作区的候选 mask 被异步回显流程覆盖。
+- 语义文本提示 `semantic` 当前被后端禁用并返回 400。
+- SAM 3 源码和历史测试保留，但不属于当前产品可用功能；前端不再展示 SAM 3 入口，后端 registry 不暴露 `sam3`。
 - 工作区“传播片段”会把当前选中区域或当前帧第一个区域作为 seed，调用 `POST /api/ai/propagate`，默认从当前帧向后传播 30 帧并保存结果标注。
-- `POST /api/ai/propagate` 支持 `model=sam2` 或 `model=sam3`；SAM 2 使用官方 `SAM2VideoPredictor.add_new_mask()` 和 `propagate_in_video()`，SAM 3 通过独立 Python 3.12 helper 调用官方 `build_sam3_video_predictor()` video tracker。
-- 传播结果会写入后续帧 `annotations`，`mask_data.source` 分别标记为 `sam2_propagation` 或 `sam3_propagation`，并保留 label、color 和 class 元数据。
-- AI 页面会对 SAM 3 空文本、推理失败和返回 0 个 mask 的情况显示明确反馈。
-- AI 参数支持 `crop_to_prompt`、`auto_filter_background` 和 `min_score`；点/框 prompt 可以裁剪局部区域推理并回映射结果，背景过滤会移除低分结果和包含负向点的 polygon；SAM 3 semantic 会用 `min_score` 控制 external worker 的置信度阈值。
+- `POST /api/ai/propagate` 当前支持四个 SAM 2.1 变体；兼容 `model=sam2` 并归一化为 tiny。SAM 2.1 使用官方 `SAM2VideoPredictor.add_new_mask()` 和 `propagate_in_video()`。
+- 传播结果会写入后续帧 `annotations`，`mask_data.source` 标记为 `<model_id>_propagation`，并保留 label、color 和 class 元数据。
+- AI 页面会对未放置点提示、后端错误和返回 0 个 mask 的情况显示明确反馈。
+- AI 参数支持 `crop_to_prompt`、`auto_filter_background` 和 `min_score`；点/框 prompt 可以裁剪局部区域推理并回映射结果，背景过滤会移除低分结果和包含负向点的 polygon。
 - 后端返回 `polygons` 和 `scores`。
 - 前端把后端 `polygons` 转成 Konva `pathData`、`segmentation`、`bbox`、`area`。
 - AI 推理结果先存放在前端 store 的 `masks` 中，点击“结构化归档保存”后持久化到后端标注表。
@@ -103,6 +108,7 @@
 - 后端提供 `PATCH /api/ai/annotations/{annotation_id}` 更新已保存标注的 `mask_data`、`points`、`bbox` 和 `template_id`。
 - 后端提供 `DELETE /api/ai/annotations/{annotation_id}` 删除已保存标注。
 - 当前前端“结构化归档保存”会保存当前项目未保存 mask，并会更新已标记为 dirty 的已保存 mask。
+- 保存成功后，前端会重新拉取后端标注，并用后端 saved annotation 替换本次提交的 draft mask；未提交的其他 draft mask 仍保留。
 - 工作区“清空遮罩”会删除当前帧已保存标注，并清空当前帧未保存 mask。
 - 工作区加载项目帧后会查询已保存标注并回显。
 - 工作区支持导入 GT mask 图片，前端调用 `POST /api/ai/import-gt-mask`。
@@ -128,10 +134,10 @@
 
 ## R10 Dashboard 与 WebSocket
 
-- Dashboard 显示基础统计、解析队列和活动日志。
+- Dashboard 显示基础统计、任务进度和活动日志。
 - Dashboard 初始数据来自 `GET /api/dashboard/overview`。
 - 后端聚合项目数、处理中任务数、标注数、帧数、模板数和主机 load average。
-- 解析队列由 `processing_tasks` 中的 queued/running/failed/cancelled 任务生成；活动日志由最近任务、项目、标注和模板记录生成。
+- 任务进度由 `processing_tasks` 中的 queued/running/success/failed/cancelled 任务生成，避免刚完成任务从进度区立即消失；处理中任务数统计只计算 queued/running；活动日志由最近任务、项目、标注和模板记录生成。
 - Dashboard 对 queued/running 任务提供取消按钮，对 failed/cancelled 任务提供重试按钮。
 - Dashboard 任务详情会读取 `GET /api/tasks/{task_id}` 并展示失败 error、payload、result、Celery ID 和时间信息。
 - Dashboard 会连接 `/ws/progress`。

doc/08-current-design-freeze.md

@@ -10,7 +10,7 @@
 
 - React + TypeScript 前端 SPA。
 - FastAPI 后端 API。
-- PostgreSQL、MinIO、Redis、SAM 2 / SAM 3 等外部基础设施。
+- PostgreSQL、MinIO、Redis、SAM 2 等外部基础设施。SAM 3 相关源码保留，但当前产品入口禁用。
 
 开发时前端通过 `server.ts` 启动 Express + Vite middleware；后端通过 `backend/main.py` 启动 FastAPI。前端业务接口主要访问 FastAPI，不依赖 `server.ts` 中保留的旧 mock API。
 
@@ -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,11 +48,11 @@
 | 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 推理、视频传播、模型状态和标注保存 |
 | Export | `backend/routers/export.py` | COCO 和 PNG mask 导出 |
 | 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 状态和推理分发 |
+| SAM 3 | `backend/services/sam3_engine.py`, `backend/services/sam3_external_worker.py`, `backend/setup_sam3_env.sh` | 历史保留的 SAM 3 桥接源码和脚本；当前未接入 registry |
+| SAM Registry | `backend/services/sam_registry.py` | 当前暴露 SAM 2.1 四个变体、GPU 状态和推理分发 |
 
 ## 状态模型
 
@@ -66,7 +66,7 @@
 - `maskHistory` / `maskFuture`：mask 编辑历史栈，用于撤销和重做。
 - `activeModule`：当前页面。
 - `activeTool`：当前工具。
-- `aiModel`：当前选择的 AI 模型，取值为 `sam2` 或 `sam3`。
+- `aiModel`：当前启用的 AI 模型，取值为 `sam2.1_hiera_tiny`、`sam2.1_hiera_small`、`sam2.1_hiera_base_plus` 或 `sam2.1_hiera_large`，默认 `sam2.1_hiera_tiny`。
 
 ## 关键数据流
 
@@ -89,7 +89,7 @@
 
 ### 任务控制
 
-1. Dashboard 从 `GET /api/dashboard/overview` 读取 queued/running/failed/cancelled 任务。
+1. Dashboard 从 `GET /api/dashboard/overview` 读取 queued/running/success/failed/cancelled 任务；queued/running 代表当前进度，success/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。
@@ -101,23 +101,29 @@
 1. `VideoWorkspace` 根据 `currentProject.id` 调用 `getProjectFrames()`。
 2. 若无帧但项目有 `video_path`，显示“尚未生成帧”的状态提示，不自动触发 `parseMedia()`。
 3. 帧数据映射为 store `Frame[]`，包含 `timestampMs` 和 `sourceFrameNumber`，供时间轴和后续视频传播使用。
-4. 当前帧传入 `CanvasArea`。
+4. 工作区调用 `GET /api/ai/annotations` 回显已保存标注时，会替换当前项目帧中的已保存 mask，但保留没有 `annotationId` 的未保存 draft mask；这保证 AI 页推送到工作区的候选 mask 不会被异步回显覆盖，并会在合并完成后恢复仍然存在的已选 mask id。
+5. `CanvasArea` 会把全局 `selectedMaskIds` 中仍存在于当前帧的 id 同步回本地选区，避免帧初始化时的临时清空覆盖 AI 页推送过来的选中态。
+6. `FrameTimeline` 根据当前项目 `frames` 和全局 `masks` 计算有编辑/标注的帧，在进度条与缩略图导航轴之间渲染可点击标记。
+7. 当前帧传入 `CanvasArea`。
 
 ### AI 点/框推理
 
 1. 用户在 Canvas 选择正向点、反向点或框选。
 2. `CanvasArea` 读取当前帧 ID 和宽高。
-3. SAM 2 框选会创建一个候选 mask，并记录原始框；后续正向点/反向点会累计到同一候选上。
+3. SAM 2.1 框选会创建一个候选 mask，并记录原始框；后续正向点/反向点会累计到同一候选上。
 4. `predictMask()` 归一化坐标并携带当前 `model` 调用 `/api/ai/predict`；同时有框和点时发送 `interactive` prompt。
-5. SAM 2 请求中只要存在反向点，`CanvasArea` 会额外发送 `options.auto_filter_background=true` 和 `options.min_score=0.05`，让后端移除低分结果和包含负向点的 polygon。
-6. 后端加载帧图片并通过 SAM registry 分发到 SAM 2 或 SAM 3。
+5. SAM 2.1 请求中只要存在反向点，`CanvasArea` 会额外发送 `options.auto_filter_background=true` 和 `options.min_score=0.05`，让后端移除低分结果和包含负向点的 polygon。
+6. 后端加载帧图片并通过 SAM registry 分发到所选 SAM 2.1 变体；`model=sam2` 会兼容归一化为 tiny，`model=sam3` 会被拒绝。
 7. 前端把 `polygons` 转为 mask；交互式细化会替换同一个候选 mask，而不是新增多个 mask。
-8. 若带反向点的 SAM 2 细化返回空结果，前端会删除当前旧候选 mask 并提示反向点已排除该区域。
-9. Canvas 按当前帧过滤并渲染 mask。
-10. 新 mask 会带上当前选择的模板分类元数据，包括 `classId`、`className`、`classZIndex` 和保存状态 `draft`。
-11. 用户点击“结构化归档保存”后，前端将像素 `segmentation` 转成 normalized `mask_data.polygons`；未保存 mask 调用 `POST /api/ai/annotate`，dirty mask 调用 `PATCH /api/ai/annotations/{annotation_id}`。
-12. 工作区加载项目帧后通过 `GET /api/ai/annotations` 取回已保存标注并转成前端 mask。
-13. 工作区“清空遮罩”删除当前帧已保存标注，并清除当前帧本地 mask。
+8. 若带反向点的 SAM 2.1 细化返回空结果，前端会删除当前旧候选 mask 并提示反向点已排除该区域。
+9. AI 页面只按本页生成的候选 id 渲染 mask，不把工作区已有 mask 带入 AI 画布。
+10. AI 页面候选 mask 的 Path 点击事件会先判断当前工具；正向/反向选点工具下点击 mask 会继续追加提示点，其他工具下才选中 mask。
+11. AI 页面“遮罩清晰度”滑杆只调节候选 mask 的 Konva preview opacity，不写入 `Mask.segmentation`、分类元数据或后端 payload。
+12. Canvas 按当前帧过滤并渲染 mask。
+13. 新 mask 会带上当前选择的模板分类元数据，包括 `classId`、`className`、`classZIndex`、`metadata.source=ai_segmentation` 和保存状态 `draft`。
+14. 用户点击“结构化归档保存”后，前端将像素 `segmentation` 转成 normalized `mask_data.polygons`；未保存 mask 调用 `POST /api/ai/annotate`，dirty mask 调用 `PATCH /api/ai/annotations/{annotation_id}`；保存成功后本次提交的 draft mask id 会从本地保留列表中排除，并由后端 saved annotation 回显替换。
+15. 工作区加载项目帧后通过 `GET /api/ai/annotations` 取回已保存标注并转成前端 mask。
+16. 工作区“清空遮罩”删除当前帧已保存标注，并清除当前帧本地 mask。
 
 ### 视频片段传播
 
@@ -125,8 +131,8 @@
 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。
+5. `model` 为任一 SAM 2.1 变体时，`sam2_engine` 使用对应 checkpoint/config 加载 `SAM2VideoPredictor.add_new_mask()` 注入 seed mask，再用 `propagate_in_video()` 传播。
+6. `model=sam3` 当前不支持；SAM 3 video tracker 代码保留但没有接入产品路径。
 7. 后端把传播返回的 normalized polygon 保存为后续帧 `Annotation`，跳过源帧，`mask_data.source` 记录模型传播来源。
 8. 前端传播完成后重新调用 `GET /api/ai/annotations` 并回显新标注。
 
@@ -180,9 +186,10 @@
 6. `CanvasArea` 把当前选中的 mask id 同步到全局 `selectedMaskIds`；切换工具、切换帧或卸载 Canvas 时会清空选择。
 7. `AISegmentation` 生成 mask 后会写入全局 `masks` 并把生成的 mask id 写入 `selectedMaskIds`；点击 AI 页预览 mask 也会更新 `selectedMaskIds`。
 8. AI 页“推送至工作区编辑”会切换到工作区并把 `activeTool` 设为 `edit_polygon`；`CanvasArea` 初始读取全局 `selectedMaskIds`，让 AI 页选中的 mask 在工作区继续保持选中。
-9. `OntologyInspector` 可以选择具体分类；选择结果进入全局 store，供 `CanvasArea` 和 `AISegmentation` 新建/更新 mask 时使用。
-10. 如果 `selectedMaskIds` 中存在当前 store 的 mask，点击分类时会立即更新这些 mask 的 `templateId`、`classId`、`className`、`classZIndex`、`label` 和 `color`。
-11. 已保存 mask 被重新分类后进入 `dirty` 且 `saved=false`，继续复用工作区归档保存的 PATCH 链路。
+9. 工作区帧/标注异步加载完成后，`hydrateSavedAnnotations()` 会合并本地未保存 draft mask 和后端已保存 mask，不会用后端回显结果直接覆盖整个 `masks` store。
+10. `OntologyInspector` 可以选择具体分类；选择结果进入全局 store，供 `CanvasArea` 和 `AISegmentation` 新建/更新 mask 时使用。
+11. 如果 `selectedMaskIds` 中存在当前 store 的 mask，点击分类时会立即更新这些 mask 的 `templateId`、`classId`、`className`、`classZIndex`、`label` 和 `color`。
+12. 已保存 mask 被重新分类后进入 `dirty` 且 `saved=false`，继续复用工作区归档保存的 PATCH 链路。
 
 ### 导出
 
@@ -210,15 +217,13 @@
 - `deleteAnnotation()` 使用 `DELETE /api/ai/annotations/{annotationId}`。
 - `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 2 是点/框交互式分割模型，不做文本语义分割；AI 页面在 SAM 2 + 纯文本时直接提示用户改用点提示或切换 SAM 3。
-- SAM 2 点提示和 auto fallback 只返回一个最高分候选，避免同一提示产生多个重叠候选 mask。
-- 当前 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` 和负向点过滤结果；SAM 3 semantic 会把正数 `min_score` 传给 external worker 作为 `confidence_threshold`。
-- 后端 `/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 的可用性。
+- 后端 `/api/ai/predict` 当前支持 SAM 2.1 的 point、box、interactive；`semantic` 文本提示禁用并返回 400。
+- SAM 2.1 是点/框交互式分割模型，不做文本语义分割；AI 页面已经移除纯文本输入。
+- SAM 2.1 点提示和 auto fallback 只返回一个最高分候选，避免同一提示产生多个重叠候选 mask。
+- SAM 3 前端入口、后端 registry 入口和状态展示均已禁用；`model=sam3` 会返回不支持。
+- 后端 `/api/ai/predict` 支持可选 `options`：`crop_to_prompt` 会对 point/box/interactive prompt 做局部裁剪推理并回映射 polygon，`auto_filter_background` 会按 `min_score` 和负向点过滤结果。
+- 后端 `/api/ai/propagate` 当前支持所选 SAM 2.1 mask seed 视频传播；当前前端默认向后传播 30 帧并保存结果标注。
+- 后端 `/api/ai/models/status` 返回 GPU 和四个 SAM 2.1 变体的真实运行状态。
 - point prompt 支持旧数组形式和 `{ points, labels }` 对象形式。
 
 ## 外部依赖边界
@@ -235,8 +240,8 @@
 
 以下能力属于当前冻结版本的占位或半可用功能：
 
-- Dashboard 初始快照来自 `GET /api/dashboard/overview`；解析队列由 `processing_tasks` queued/running/failed/cancelled 任务生成。
+- Dashboard 初始快照来自 `GET /api/dashboard/overview`；任务进度区由 `processing_tasks` queued/running/success/failed/cancelled 任务生成，处理中统计只计算 queued/running。
 - 已保存标注支持通过“应用分类”、polygon 顶点拖动/删除、边中点插入、多 polygon 子区域编辑和区域合并/去除进入 dirty 状态并归档更新；选中整块 mask 可用 Delete/Backspace 删除并同步后端；复杂洞结构编辑尚未实现。
-- SAM 3 文本语义分割取决于官方依赖、GPU 运行环境和本地 checkpoint；状态接口会暴露真实可用性，运行时缺失时 `available=false`。
+- SAM 3 文本语义分割已从当前产品路径中禁用；相关源码保留，恢复时需要重新接入前端入口、registry、状态接口和测试。
 - 自定义分类只存在本地组件状态。
 - GT mask 导入已完成多类别像素值拆分、contour、distance transform seed point 和前端 seed point 拖拽编辑；骨架提取、HDBSCAN 聚类和模板自动映射尚未实现。

doc/09-test-plan.md

@@ -17,13 +17,13 @@
 | 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 媒体上传与拆帧 | `src/components/ProjectLibrary.test.tsx`, `backend/tests/test_media.py`, `backend/tests/test_tasks.py` | 视频导入不自动拆帧、显式生成帧 FPS 选择、扩展名校验、自动建项目、关联项目、创建异步任务、标准帧序列参数、帧时间戳/源帧号、任务序列元数据、worker 注册帧、取消任务、重试任务、取消后 worker 停止 |
-| R4 工作区与帧浏览 | `src/components/VideoWorkspace.test.tsx`, `src/components/FrameTimeline.test.tsx` | 加载帧、无帧项目不自动解析并提示生成帧、缩略图/range/左右方向键切帧、播放、按项目 FPS 显示当前/总时长 |
+| R4 工作区与帧浏览 | `src/components/VideoWorkspace.test.tsx`, `src/components/FrameTimeline.test.tsx` | 加载帧、无帧项目不自动解析并提示生成帧、回显已保存标注时保留本地未保存 draft mask、缩略图/range/已编辑帧标记/左右方向键切帧、播放、按项目 FPS 显示当前/总时长 |
 | R5 工具栏 | `src/components/ToolsPalette.test.tsx`, `src/components/CanvasArea.test.tsx`, `src/store/useStore.test.ts` | 工具切换、调整多边形工具、AI 跳转、矩形/圆/线/点/多边形手工 mask 绘制、点工具在已有 mask 上落点、多边形 Enter/首节点闭合、polygon 顶点拖动/删除、边中点插点、双击边界按位置插点、整块 mask 删除、区域合并/去除、内含去除 hole 渲染、合并模式隐藏编辑手柄、撤销/重做历史栈 |
-| R6 AI 推理 | `src/lib/api.test.ts`, `src/components/CanvasArea.test.tsx`, `src/components/AISegmentation.test.tsx`, `src/components/VideoWorkspace.test.tsx`, `src/components/ModelStatusBadge.test.tsx`, `backend/tests/test_ai.py`, `backend/tests/test_sam2_engine.py`, `backend/tests/test_sam3_engine.py` | 点/框/interactive/semantic 契约、SAM 2 纯文本提示拦截、SAM 2 最高分候选去重、SAM 2 框选后正负点细化同一候选 mask、SAM 2 反向点启用背景过滤且空结果移除旧候选、AI 页生成 mask 自动选中并可通过分类树换标签、AI 页推送到工作区编辑保留选择、SAM 2 视频传播、SAM 3 语义文本前端执行路径、SAM 3 semantic 请求级阈值、SAM 3 worker 单 2D mask 转 polygon、SAM 3 工作区框选、SAM 3 video tracker 外部桥接、SAM 3 点交互不支持提示、空文本/空结果反馈、模型选择、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 回显/归一化、项目不存在、帧不存在 |
+| R6 AI 推理 | `src/lib/api.test.ts`, `src/components/CanvasArea.test.tsx`, `src/components/AISegmentation.test.tsx`, `src/components/VideoWorkspace.test.tsx`, `src/components/ModelStatusBadge.test.tsx`, `backend/tests/test_ai.py`, `backend/tests/test_sam2_engine.py` | SAM 2.1 变体选择、点/框/interactive 契约、semantic 禁用、SAM 3 入口隐藏和后端拒绝、SAM 2.1 最高分候选去重、SAM 2.1 框选后正负点细化同一候选 mask、SAM 2.1 反向点启用背景过滤且空结果移除旧候选、AI 页不渲染工作区已有 mask、AI 页可在候选 mask 上继续添加正/反点、AI 页清空只移除本页候选、AI 页遮罩清晰度只改预览 opacity、AI 页生成 mask 自动选中并可通过分类树换标签、AI 页推送到工作区编辑保留选择、SAM 2.1 视频传播、空提示/空结果反馈、GPU/SAM2.1 状态、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` | 保存标注、保存后用后端 saved annotation 替换已提交 draft、加载回显、更新 dirty 标注、清空删除已保存标注、GT mask 多类别导入、seed point 回显/归一化、项目不存在、帧不存在 |
 | R8 模板库 | `src/components/TemplateRegistry.test.tsx`, `src/lib/api.test.ts`, `backend/tests/test_templates.py` | 前端模板加载/新建/编辑/删除、JSON 分类导入、mapping_rules 解包/打包、后端模板 CRUD |
 | R9 本体检查面板 | `src/components/OntologyInspector.test.tsx`, `src/components/CanvasArea.test.tsx`, `src/store/useStore.test.ts` | 模板选择、分类展示、具体分类选择、Canvas 选区同步、点击分类给已选 mask 换标签、自定义分类本地添加 |
-| 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 |
+| 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` | 测试覆盖矩阵 |
@@ -35,14 +35,14 @@
 | R1 | 登录页、默认开发凭证、token 写入、失败提示、后端 401 | `Login.test.tsx`, `test_auth.py` | 已覆盖 |
 | R2 | 项目列表/创建/选择、视频导入、DICOM 导入、后端项目和帧 CRUD | `ProjectLibrary.test.tsx`, `api.test.ts`, `test_projects.py` | 已覆盖 |
 | R3 | 文件类型校验、自动/指定项目上传、视频导入与生成帧分离、显式 FPS 生成帧、视频/DICOM 拆帧任务、`parse_fps/max_frames/target_width`、标准帧序列 metadata、任务查询、取消、重试、worker 取消停止 | `ProjectLibrary.test.tsx`, `test_media.py`, `test_tasks.py` | 已覆盖 |
-| R4 | 工作区加载帧、无帧项目不自动解析、Canvas 底图、缩略图/range/左右方向键切帧、播放、按 FPS 显示时间 | `VideoWorkspace.test.tsx`, `FrameTimeline.test.tsx`, `CanvasArea.test.tsx` | 已覆盖 |
+| R4 | 工作区加载帧、无帧项目不自动解析、后端标注回显保留本地未保存 draft mask、Canvas 底图、缩略图/range/已编辑帧标记/左右方向键切帧、播放、按 FPS 显示时间 | `VideoWorkspace.test.tsx`, `FrameTimeline.test.tsx`, `CanvasArea.test.tsx` | 已覆盖 |
 | R5 | 工具切换、调整多边形入口、AI 跳转、矩形/圆/线/点/多边形绘制、已有 mask 上继续绘制 | `ToolsPalette.test.tsx`, `CanvasArea.test.tsx` | 已覆盖 |
 | R5 | 顶点编辑、边中点插点、双击边界按位置插点、顶点删除、整块删除、撤销/重做、区域合并、区域去除、hole even-odd 渲染 | `CanvasArea.test.tsx`, `useStore.test.ts` | 已覆盖 |
-| R6 | SAM 2 点/框/interactive、SAM 2 纯文本提示拦截、SAM 2 最高分候选去重、AI 页生成 mask 自动选中并可换标签、AI 页推送到工作区编辑保留选择、SAM 2 视频传播、SAM 3 semantic、SAM 3 semantic 请求级阈值、SAM 3 worker 单 2D mask 转 polygon、SAM 3 box、SAM 3 video tracker、SAM 3 不支持点交互时的前端反馈、模型选择、GPU/模型状态、参数 options、polygons 转 mask | `api.test.ts`, `CanvasArea.test.tsx`, `AISegmentation.test.tsx`, `VideoWorkspace.test.tsx`, `ModelStatusBadge.test.tsx`, `test_ai.py`, `test_sam2_engine.py`, `test_sam3_engine.py` | 已覆盖 |
-| R7 | 保存、查询、更新、删除标注、工作区回显、清空已保存标注、GT mask 导入和 seed point 回写 | `VideoWorkspace.test.tsx`, `CanvasArea.test.tsx`, `api.test.ts`, `test_ai.py` | 已覆盖 |
+| R6 | SAM 2.1 变体选择、点/框/interactive、semantic 禁用、SAM 3 入口隐藏和后端拒绝、SAM 2.1 最高分候选去重、AI 页不渲染工作区已有 mask、AI 页可在候选 mask 上继续添加正/反点、AI 页清空只移除本页候选、AI 页遮罩清晰度只改预览 opacity、AI 页生成 mask 自动选中并可换标签、AI 页推送到工作区编辑保留选择、SAM 2.1 视频传播、GPU/模型状态、参数 options、polygons 转 mask | `api.test.ts`, `CanvasArea.test.tsx`, `AISegmentation.test.tsx`, `VideoWorkspace.test.tsx`, `ModelStatusBadge.test.tsx`, `test_ai.py`, `test_sam2_engine.py` | 已覆盖 |
+| R7 | 保存、保存后替换已提交 draft、查询、更新、删除标注、工作区回显、清空已保存标注、GT mask 导入和 seed point 回写 | `VideoWorkspace.test.tsx`, `CanvasArea.test.tsx`, `api.test.ts`, `test_ai.py` | 已覆盖 |
 | R8 | 模板加载、新建、编辑、删除、JSON 分类导入、mapping_rules 映射、后端 CRUD | `TemplateRegistry.test.tsx`, `api.test.ts`, `test_templates.py` | 已覆盖 |
 | R9 | 模板选择、分类展示、分类选择、已选 mask 换标签、自定义本地分类、占位状态 | `OntologyInspector.test.tsx`, `CanvasArea.test.tsx`, `useStore.test.ts` | 已覆盖 |
-| R10 | Dashboard 概览、队列、活动日志、WebSocket progress/complete/error/status/cancelled、取消/重试/详情、连接状态回调、heartbeat | `Dashboard.test.tsx`, `websocket.test.ts`, `test_dashboard.py`, `test_main.py`, `test_progress_events.py`, `test_tasks.py` | 已覆盖 |
+| R10 | Dashboard 概览、任务进度区、最近完成任务保留显示、活动日志、WebSocket progress/complete/error/status/cancelled、取消/重试/详情、连接状态回调、heartbeat | `Dashboard.test.tsx`, `websocket.test.ts`, `test_dashboard.py`, `test_main.py`, `test_progress_events.py`, `test_tasks.py` | 已覆盖 |
 | R11 | COCO/PNG ZIP 导出、导出前保存、路径和 JSON/ZIP 结构、zIndex 融合 | `VideoWorkspace.test.tsx`, `api.test.ts`, `test_export.py` | 已覆盖 |
 | R12 | API/WS 地址 env 优先和 hostname 推导 | `config.test.ts` | 已覆盖 |
 | R13 | 文档测试矩阵与功能点追踪 | `doc/09-test-plan.md` | 已覆盖 |
@@ -50,14 +50,14 @@
 ## 本轮补齐记录
 
 - R5：补充 `CanvasArea.test.tsx` 中圆形和线段手工绘制测试，明确验证 metadata、segmentation、bbox/area 和草稿状态。
-- R6：补充 `AISegmentation.test.tsx` 中 SAM 3 semantic 文本推理测试，验证前端传参和返回 mask 绑定当前语义类别。
+- R6：补充 `AISegmentation.test.tsx` 中 SAM 2.1 变体选择测试，验证前端不展示 SAM 3 入口、选择 small 后请求携带对应模型，且未放置点提示时不发起推理。
 - R6：补充 SAM 2 纯文本提示拦截、SAM 2 多候选只保留最高分、SAM 2 engine 单候选请求测试，避免多个重叠候选 mask 被同时叠加。
 - R6：补充 Canvas 工作区 SAM 2 反向点背景过滤测试，覆盖请求 options 和过滤为空时清除旧候选 mask。
-- R6：补充 SAM 3 空文本、空结果和工作区点交互不支持提示测试，避免前端静默失败。
-- R6：补充 SAM 3 工作区 box prompt 测试和外部 worker box prompt 测试，验证官方 `add_geometric_prompt()` 正框链路。
+- R6：补充 `ModelStatusBadge.test.tsx` 中 SAM 3 不展示测试，避免禁用入口重新出现在前端。
+- R6：补充后端 `selected_model=sam3` 拒绝测试和 semantic 禁用测试，避免后端继续暴露 SAM 3 产品能力。
 - R6：补充 `POST /api/ai/propagate` 后端测试，验证 seed mask 传播结果会保存为后续帧标注并保留 class 元数据。
 - R6：补充 `propagateMasks()` API 封装和 `VideoWorkspace` 传播按钮测试，验证当前选中区域会发送到后端视频传播接口。
-- R6：补充 SAM 3 external video tracker 请求测试，验证主后端会把帧目录、源帧索引、seed bbox 和方向传给独立 Python helper。
+- R6：`backend/tests/test_sam3_engine.py` 已标记跳过，仅作为历史保留实现的参考测试，不计入当前产品功能覆盖。
 - R3：补充 `parseMedia()` 查询参数和后端拆帧任务 payload 测试，验证 `parse_fps`、`max_frames`、`target_width` 会进入任务。
 - R3：补充 worker 注册标准帧序列测试，验证帧 `timestamp_ms`、`source_frame_number` 和 `result.frame_sequence` 元数据。
 - R8：补充 `TemplateRegistry.test.tsx` 中模板编辑、删除测试，验证前端调用真实 API 封装并更新全局 store。