修复AI模型不可用状态交互

- AI智能分割页禁用不可用SAM2.1模型变体，并在模型状态未可用时阻止推理请求。

- 分割工作区AI自动推理在提交传播前校验模型状态，所有模型不可用时禁用入口，当前权重不可用时禁用开始传播。

- 传播权重下拉标记并禁用不可用权重，避免提交后无结果的假可用状态。

- 补充AI页和工作区模型不可用回归测试，扩展默认测试状态覆盖四个SAM2.1变体。

- 更新前端元素审计、交互状态机、测试计划和Docker/GPU部署说明。

doc/03-frontend-element-audit.md

@@ -80,7 +80,7 @@
 | 已保存标注回显 | 真实可用 | 加载工作区帧后调用 `GET /api/ai/annotations` 并渲染已保存 mask；回显时保留当前项目帧里尚未保存的 AI/手工 draft mask，避免从 AI 页推送的候选被覆盖 |
 | “分割结果导出”按钮 | 真实可用 | 原“导出 JSON 标注集”和“导出 PNG Mask ZIP”已合并为一个入口；按钮使用 `FileDown` 图标和绿色强调背景，区别于普通灰色操作按钮；点击后可选择整体视频、特定范围帧或当前图片，默认导出范围为当前图片，并勾选导出分开二值 mask、GT_label 黑白图、Pro_label 彩色图和 Mix_label 原图叠加图；选择“特定范围帧”后会进入时间轴范围选择模式，可在播放进度条或视频处理进度条上点击/拖拽选择导出起止帧，也可直接修改起止帧输入框；选择 Mix_label 时可调透明度，默认 0.3，并显示当前/待导出第一帧预览；提交前会保存未归档 mask，然后调用 `GET /api/export/{project_id}/results` 下载 ZIP；浏览器下载名和后端 `Content-Disposition` 均使用 `{项目库项目名}_seg_T_{起始时间戳}-{结束时间戳}_P_{起始项目帧序号}-{结束项目帧序号}.zip`；时间戳格式为 `0h00m00s000ms`，帧序号来自项目抽帧后的 1-based 顺序，不使用原视频帧号；包内固定包含 `annotations_coco.json`、`maskid_GT像素值_类别映射.json` 和 `原始图片/`；选择分开 mask 时包含按帧子目录组织且同类合并的 `分开Mask分割结果/`，选择 GT_label/Pro_label/Mix_label 时分别包含 `GT_label图/`、`Pro_label彩色分割结果/`、`Mix_label重叠覆盖彩色分割结果/`。GT_label 图固定为 8-bit uint8 PNG，背景为 0，语义类别值使用类别真实 maskid，`maskid: 0` 的“待分类”与背景同为 0，Pro_label 中也与背景同为黑色 `[0,0,0]`，缺失 maskid 的旧标注才补下一个可用正整数，正整数 maskid 超出 1-255 会拒绝导出 |
 | “导入 GT Mask”按钮 | 真实可用 | 入口已从工作区顶栏移动到左侧工具栏“重叠区域去除”之后，使用紫色图标底色；选择图片后先弹出导入结果预览和未知 maskid 策略选择，可舍弃未知类别或导入为黑色 `maskid:0` 的“待分类”；随后调用 `POST /api/ai/import-gt-mask`，后端仅支持 8-bit 二值/灰度 maskid 图和 8-bit RGB 三通道完全相同的 `[X,X,X]` maskid 图，不符合 8-bit 灰度/maskid 图要求时返回错误，16-bit/uint16 GT_label 会被拒绝；尺寸不同会自动最近邻拉伸到当前帧，再按类别/连通域生成高精度 polygon 标注，最后回显到工作区；导入 mask 与普通 mask 一样不显示黄色 seed point，并共用拓扑锚点统计、边缘平滑、编辑、分类和保存链路 |
-| 参考帧/起止帧/传播权重/AI自动推理 | 真实可用 | 当前打开帧即参考帧，前端会使用该帧全部 mask 作为 seed；左侧工具栏橡皮擦下方有彩色 AI 大脑图标“AI自动推理”入口，点击后进入时间轴范围选择模式，顶栏才显示独立“传播权重”下拉，可在传播前二次选择 SAM 2.1 tiny/small/base+/large 权重，不提供 SAM2/SAM3 家族切换，不影响 AI 智能分割页的单帧推理权重选择；传播权重下拉使用深色背景和青色文字，避免默认灰底白字不可读；播放进度条和视频处理进度条都可点击/拖拽回填传播起始帧和传播结束帧，顶栏会显示当前传播权重以及相对参考帧的向前/向后帧数，再点击“开始传播”提交；用户也可直接改数字框后点击按钮传播。提交后前端把传播权重 id、seed mask、seed 实例 id、未编辑传播结果的原始 seed 签名和前/后方向步骤提交到 `POST /api/ai/propagate/task`，后端先规范化/校验权重 id，再创建 `processing_tasks` 并由 Celery 执行对应 SAM 2.1 video predictor；同一参考帧多个同类别 seed 会优先按 `source_instance_id/instance_id` 分开传播，语义 `maskid` 只用于类别/导出；worker 会在本次目标帧段内按 seed 来源和几何/语义签名做幂等判断，未改变且目标帧已有结果的 seed 直接跳过，已改变、目标帧只部分覆盖或换权重时会先删除本次目标帧段内同源旧自动传播标注再重新传播；历史或外部 seed 若仍带边缘平滑参数，后端仍按完整签名兼容处理；当前前端平滑应用会直接改写 polygon，因此传播以新几何参与签名；中间帧人工新增/修改同一物体后重新传播时，后端会按语义和目标帧空间重叠清理旧传播结果，写入前清理不受旧结果 `propagation_direction` 限制，避免 backward 重传时与旧 forward mask 重叠；传播中顶栏蓝色进度面板显示任务进度、已处理帧次、删除旧区域数和已保存区域数，同一任务 message 不再同时显示在左侧灰色状态文字里；前端轮询 `GET /api/tasks/{task_id}` 并刷新已保存标注；任务可取消，若完成后 0 个新区域会明确提示没有生成新 mask 或已跳过未改变 mask |
+| 参考帧/起止帧/传播权重/AI自动推理 | 真实可用 | 当前打开帧即参考帧，前端会使用该帧全部 mask 作为 seed；左侧工具栏橡皮擦下方有彩色 AI 大脑图标“AI自动推理”入口，点击后进入时间轴范围选择模式，顶栏才显示独立“传播权重”下拉，可在传播前二次选择 SAM 2.1 tiny/small/base+/large 权重，不提供 SAM2/SAM3 家族切换，不影响 AI 智能分割页的单帧推理权重选择；工作区会读取 `GET /api/ai/models/status`，当所有 SAM 2.1 变体不可用时禁用“AI自动推理”，当所选传播权重不可用时禁用“开始传播”，传播权重下拉中不可用变体也不可选择，避免提交后没有任何推理结果；传播权重下拉使用深色背景和青色文字，避免默认灰底白字不可读；播放进度条和视频处理进度条都可点击/拖拽回填传播起始帧和传播结束帧，顶栏会显示当前传播权重以及相对参考帧的向前/向后帧数，再点击“开始传播”提交；用户也可直接改数字框后点击按钮传播。提交后前端把传播权重 id、seed mask、seed 实例 id、未编辑传播结果的原始 seed 签名和前/后方向步骤提交到 `POST /api/ai/propagate/task`，后端先规范化/校验权重 id，再创建 `processing_tasks` 并由 Celery 执行对应 SAM 2.1 video predictor；同一参考帧多个同类别 seed 会优先按 `source_instance_id/instance_id` 分开传播，语义 `maskid` 只用于类别/导出；worker 会在本次目标帧段内按 seed 来源和几何/语义签名做幂等判断，未改变且目标帧已有结果的 seed 直接跳过，已改变、目标帧只部分覆盖或换权重时会先删除本次目标帧段内同源旧自动传播标注再重新传播；历史或外部 seed 若仍带边缘平滑参数，后端仍按完整签名兼容处理；当前前端平滑应用会直接改写 polygon，因此传播以新几何参与签名；中间帧人工新增/修改同一物体后重新传播时，后端会按语义和目标帧空间重叠清理旧传播结果，写入前清理不受旧结果 `propagation_direction` 限制，避免 backward 重传时与旧 forward mask 重叠；传播中顶栏蓝色进度面板显示任务进度、已处理帧次、删除旧区域数和已保存区域数，同一任务 message 不再同时显示在左侧灰色状态文字里；前端轮询 `GET /api/tasks/{task_id}` 并刷新已保存标注；任务可取消，若完成后 0 个新区域会明确提示没有生成新 mask 或已跳过未改变 mask |
 | 清空片段遮罩 | 已移除 | 顶栏不再提供重复的“清空片段遮罩”；当前帧清空和 DEL 删除只从左侧工具栏或键盘触发，存在传播链时在同一弹窗提供取消/只清当前帧/按帧范围选择/清空所有传播帧 |
 | 保存状态按钮 | 真实可用 | 顶栏按钮按当前项目待保存数量显示为“保存 X 个改动”或“已全部保存”；未保存 mask 写入 `POST /api/ai/annotate`，dirty mask 写入 `PATCH /api/ai/annotations/{id}`；保存成功后会重新拉取后端标注，并用 saved annotation 替换本次提交的 draft mask，避免仍显示未保存 |
 
@@ -153,7 +153,7 @@
 
 | 元素 | 状态 | 说明 |
 |------|------|------|
-| SAM 2.1 变体选择 / 模型状态 | 真实可用 | AI 页可选 tiny/small/base+/large，调用 `GET /api/ai/models/status?selected_model=<variant>` 展示所选变体和 GPU 状态；只有本地存在 checkpoint 的变体显示可用 |
+| SAM 2.1 变体选择 / 模型状态 | 真实可用 | AI 页可选 tiny/small/base+/large，调用 `GET /api/ai/models/status?selected_model=<variant>` 展示所选变体和 GPU 状态；只有本地存在 checkpoint 且 PyTorch/SAM2 依赖可用的变体显示可用，不可用变体不能点击，执行按钮显示“当前模型不可用”并阻止推理请求 |
 | 正向/反向点 | 真实可用 | 可在当前项目帧上加点并调用 AI 推理接口；AI 页中点击已有候选 mask 时也会继续添加当前正/反向提示点，点击已有提示点会删除该点；SAM 2.1 框选后会携带原始框和累计正/反点细化同一个候选 mask |
 | 边界框选 | 真实可用 | AI 页选择工具后可在画布拖拽蓝色虚线框；执行分割时会随 `/api/ai/predict` 发送 `box`，框选后继续添加正/反点会发送 interactive prompt |
 | AI 画布上下文提示 | 真实可用 | 选择正向点、反向点、边界框选或视口控制时，画布左上角提示点击/拖拽、删除提示点和执行推理的操作方式 |

doc/09-test-plan.md

@@ -19,7 +19,7 @@
 | R3 媒体上传与拆帧 | `src/components/ProjectLibrary.test.tsx`, `src/components/TransientNotice.test.tsx`, `backend/tests/test_media.py`, `backend/tests/test_tasks.py` | 视频导入不自动拆帧、视频/DICOM 上传进度可视化、DICOM 导入显示有效文件数量并在上传后持续显示解析任务进度、显式生成帧/重新生成帧 FPS 选择、重新生成前清空旧帧旧标注旧 mask、视频生成帧入队后轮询解析任务并在成功后自动刷新项目封面、项目卡片显示目标 parse_fps 而非原视频 FPS、扩展名校验、自动建项目、关联项目、创建异步任务、非阻塞自动消失操作提示、标准帧序列参数、帧时间戳/源帧号、任务序列元数据、worker 注册帧、取消任务、重试任务、取消后 worker 停止 |
 | R4 工作区与帧浏览 | `src/components/VideoWorkspace.test.tsx`, `src/components/FrameTimeline.test.tsx` | 加载帧、无帧项目不自动解析并提示生成帧、工作区短状态自动消失、工作区/AI 画布底图默认居中且保留边距、工作区 mask 透明度、回显已保存标注时保留本地未保存 draft mask、选中 mask 后跨帧自动跟随同一传播链结果、左侧工具栏清空遮罩优先作用于当前帧选中 mask/无选中时作用于当前帧全部 mask、无传播链时直接执行、有传播链时可选取消/只清当前帧/按帧范围选择/清空所有传播帧且按范围清空需最终确认、按范围清空或清空所有传播帧遇到人工/AI 标注帧时二次询问并支持保留人工帧、顶栏不显示重复的清空片段遮罩、传播进度存在时任务 message 只显示在蓝色进度面板内且不重复出现在灰色状态文字里、传播链布尔操作按帧范围选择并二次确认、清空/删除前预检后端 annotation id 并跳过本地陈旧 id、删除单个传播 mask 后空帧不保留传播历史颜色、传播权重下拉深色可读配色、自动传播范围选择时显示传播权重和向前/向后帧数、缩略图/range/视频处理进度条、视频处理进度条点击跳帧、人工/AI 标注帧红色竖线和标识点击跳帧、自动传播帧通过 source/lineage metadata 识别为蓝色区段和标识点击跳帧、最近自动传播历史片段同一蓝色系按新旧递进纯色显示，旧记录第 5 次后统一阈值色、当前帧白色贯穿线、传播/布尔/清空范围边界贯穿线、缩略图红/蓝边框、人工/AI 标注帧叠加传播状态时红框优先保留并显示蓝色内描边、当前人工/AI 标注帧青色外框加红色内描边、普通状态不显示传播范围黄色选区、播放进度条和视频处理进度条选择传播/布尔/清空范围、左右方向键切帧、播放、按项目 FPS 显示当前/总时长 |
 | R5 工具栏 | `src/components/ToolsPalette.test.tsx`, `src/components/CanvasArea.test.tsx`, `src/components/VideoWorkspace.test.tsx`, `src/lib/keyboardShortcuts.test.ts`, `src/store/useStore.test.ts` | 工具切换、切换到多边形/矩形/圆会保留旧 mask 选区、有选中 mask 时多边形/矩形/圆/画笔新几何会并入选中 mask 且不要求重叠、无选中 mask 时手工新建 mask 后自动选中新 mask 并显示创建后边界点、Esc 和左侧“取消选中”按钮清空当前 mask 选区和临时绘制状态、工具栏紧凑垂直布局和高度不足时滚动、工具栏低对比滚动条、工具栏外扩滚动条槽位不挤占按钮列、调整多边形工具、AI 跳转、清空遮罩唯一左侧工具栏入口、清空遮罩上方 DEL 删除按钮、橡皮擦下方彩色 AI自动推理入口、Canvas 右下角不再重复显示清空遮罩或应用分类按钮、GT Mask 导入位于清空遮罩分隔线之后且使用紫色底色、工具栏分隔线位于创建圆后、AI自动推理后和清空遮罩后、GT Mask 未知类别导入策略选择、工作区工具栏不展示 AI 正/反点和框选、左侧工具栏不重复撤销/重做、左侧工具栏不展示创建点/创建线段、矩形/圆/多边形手工 mask 绘制且未选分类时默认待分类、普通/导入 polygon mask 不显示黄色 seed point、画笔/橡皮擦尺寸控制、画笔无选中时新建当前类别 mask、画笔/橡皮擦模式下保留当前选中 mask 顶点提示且只读、画笔从图外落笔不创建 mask、靠边画笔生成几何裁剪到当前帧边界内、橡皮擦从选中 mask 扣除、未选中 mask 时画布按语义分类树内部优先级渲染、多边形 Enter/首节点闭合、上下文提示提示 Enter/Esc/首节点闭合且数秒后自动隐藏、polygon 顶点直接拖动/删除、顶点拖拽结束不改变 Canvas 视口、边中点插点、双击边界按位置插点、多 polygon/分离区域全部显示编辑顶点、中空 mask 与中空画笔 mask 内洞 ring 顶点和插点可编辑、整块 mask 删除、DEL 和 Delete/Backspace 删除共用传播链范围确认、同帧传播链分散 mask 点选联动高亮、传播链自动传播 mask 随 seed/传播结果删除、独立 AI 推理 mask 不被误删、区域合并/去除存在传播帧时弹窗选择当前帧/所有传播帧/按帧范围选择、范围确认前重新开始当前帧布尔操作会取消旧顶栏范围请求、区域合并/去除按帧范围同步到对应传播帧且保留传播 metadata、旧传播缺可靠 lineage 时布尔同步只选每个已选 mask 的空间最近对应实例而不批量处理同类其它实例、布尔选择主区域/扣除区域视觉区分和选择顺序提示、内含去除 hole 渲染和 ring 分组保存、合并模式隐藏编辑手柄、工作区顶栏撤销/重做按钮、顶栏撤销/重做图标强调色、撤销/重做快捷键 Ctrl/Cmd+Z、Ctrl/Cmd+Shift+Z、Ctrl/Cmd+Y、物理键码 fallback 和输入框快捷键跳过、撤销/重做历史栈 |
-| 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、AI 页框选发送 box prompt、AI 页框选后加点发送 interactive prompt、AI 页提示工具上下文提示、AI 页重复执行替换旧候选、SAM 2.1 反向点启用背景过滤且空结果移除旧候选、AI 页不渲染工作区已有 mask、AI 页可在候选 mask 上继续添加正/反点、AI 页可单点删除提示点并删除最近锚点、AI 页可删除选中候选且不删除工作区 mask、AI 页清空只移除本页候选、AI 页参数开关可读性文案且 options 字段不变、AI 页/右侧共享遮罩透明度只改预览 opacity、AI 页生成 mask 自动选中并可通过分类树换标签、AI 页无语义候选禁止推送到工作区并用 error toast 提示、离开 AI 页时清理未分类候选、AI 页推送到工作区编辑保留选择和当前帧、SAM 2.1 视频以当前参考帧全部 mask 和起止帧范围自动传播、同类多实例按来源 id 分开传播、当前参考帧无遮罩提示、传播前只保存参考帧 draft/dirty seed mask、传播前独立选择 SAM 2.1 tiny/small/base+/large 权重、自动传播创建 Celery 任务、传播入队权重 id 规范化/拒绝不支持 id、传播 seed 来源 id/签名和历史平滑 metadata 兼容、中空传播 seed 扣除 holes 后注入 SAM 2 且传播结果保留 holes、历史平滑 seed 保存前对 forward/backward polygon 实际应用边缘平滑并减少密集轮廓点、边缘平滑强度缓入递进曲线、未编辑传播结果作为 seed 时继承原始签名并跳过重复传播、已编辑传播结果保留 lineage 但重算签名并清理旧结果、中间帧人工新增替代 seed 时清理下游同物体旧传播结果、中间帧 backward 传播清理旧 forward 结果、换权重传播先清理旧结果、旧临时 seed id 传播结果兼容清理、传播中轮询任务进度、传播任务取消/重试、传播来源 metadata 回显、空提示/空结果反馈、GPU/SAM2.1 状态、AI 参数 options、局部裁剪推理、背景过滤、状态徽标、坐标归一化、正负点 labels、polygons 转 path、后端 fake registry |
+| 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 变体选择、模型不可用时 AI 页禁用不可用变体和执行按钮、工作区所有变体不可用时禁用 AI自动推理、点/框/interactive 契约、semantic 禁用、SAM 3 入口隐藏和后端拒绝、SAM 2.1 最高分候选去重、SAM 2.1 框选后正负点细化同一候选 mask、AI 页框选发送 box prompt、AI 页框选后加点发送 interactive prompt、AI 页提示工具上下文提示、AI 页重复执行替换旧候选、SAM 2.1 反向点启用背景过滤且空结果移除旧候选、AI 页不渲染工作区已有 mask、AI 页可在候选 mask 上继续添加正/反点、AI 页可单点删除提示点并删除最近锚点、AI 页可删除选中候选且不删除工作区 mask、AI 页清空只移除本页候选、AI 页参数开关可读性文案且 options 字段不变、AI 页/右侧共享遮罩透明度只改预览 opacity、AI 页生成 mask 自动选中并可通过分类树换标签、AI 页无语义候选禁止推送到工作区并用 error toast 提示、离开 AI 页时清理未分类候选、AI 页推送到工作区编辑保留选择和当前帧、SAM 2.1 视频以当前参考帧全部 mask 和起止帧范围自动传播、同类多实例按来源 id 分开传播、当前参考帧无遮罩提示、传播前只保存参考帧 draft/dirty seed mask、传播前独立选择 SAM 2.1 tiny/small/base+/large 权重、自动传播创建 Celery 任务、传播入队权重 id 规范化/拒绝不支持 id、传播 seed 来源 id/签名和历史平滑 metadata 兼容、中空传播 seed 扣除 holes 后注入 SAM 2 且传播结果保留 holes、历史平滑 seed 保存前对 forward/backward polygon 实际应用边缘平滑并减少密集轮廓点、边缘平滑强度缓入递进曲线、未编辑传播结果作为 seed 时继承原始签名并跳过重复传播、已编辑传播结果保留 lineage 但重算签名并清理旧结果、中间帧人工新增替代 seed 时清理下游同物体旧传播结果、中间帧 backward 传播清理旧 forward 结果、换权重传播先清理旧结果、旧临时 seed id 传播结果兼容清理、传播中轮询任务进度、传播任务取消/重试、传播来源 metadata 回显、空提示/空结果反馈、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` | 保存状态按钮“保存 X 个改动/已全部保存”、保存标注、保存后用后端 saved annotation 替换已提交 draft、加载回显、更新 dirty 标注、dirty 本地旧 annotationId 预检缺失时直接重新 POST 创建、预检后 PATCH 404 时重新 POST 创建并回显替换、中空 mask 保存为 `polygons` + `holes` 并可回显为 ring 分组、清空删除已保存标注、GT mask 多类别导入、高精度 GT contour、导入 mask 可直接拓扑统计和边缘平滑、后端 seed point 归一化兼容但前端不显示或拖动、缺失 seed point 的普通 polygon 保存时自动写入代表点、项目不存在、帧不存在 |
 | R8 模板库 | `src/components/TemplateRegistry.test.tsx`, `src/components/TransientNotice.test.tsx`, `src/lib/api.test.ts`, `backend/tests/test_templates.py` | 前端模板加载/新建/编辑/删除、删除模板站内确认、鼠标复制模板为私有副本、所有模板归一化包含黑色 `maskid:0`“待分类”保留类、保留类固定最后且不可删除/拖拽上移、详情页“语义分类树（拖拽调层级）”标题、详情页“编辑模板”按钮和编辑图标、详情页垃圾桶删除 label 且不显示来源标签、编辑弹窗分类编辑不显示旧 category 来源元信息、编辑后详情页刷新、详情页和编辑弹窗拖拽语义层级顺序、拖拽保存 `zIndex` 且不改变 maskid、JSON 分类导入预览、`[[colors],[names]]` 数组格式、`{colors,names}` 对象格式、带前缀/宽松 keys/中文标点粘贴格式、JSON 错误内联提示、保存错误非阻塞提示、mapping_rules 解包/打包、后端模板 CRUD |
 | R9 本体检查面板 | `src/components/OntologyInspector.test.tsx`, `src/components/CanvasArea.test.tsx`, `src/components/VideoWorkspace.test.tsx`, `src/store/useStore.test.ts`, `backend/tests/test_ai.py` | 模板选择、已有 mask 时切换激活模板需确认并清空所有 mask/标注、无 mask 时直接切换、面板标题简化、面板低对比滚动条、工作区遮罩透明度滑杆、分类展示、具体分类选择、无选中 mask 时点击分类只设置后续新建类别且不改已有 mask、模板类别删除后项目旧 mask 回显为 `maskid:0` 待分类、Canvas 选区同步、点击 Canvas mask 后自动聚焦对应语义分类、点击分类给已选 mask 换标签并移动到前端渲染最上层、分类变更同步同一传播链前后帧对应 mask、自定义分类 PATCH 后端模板、目标实例标题显示当前 mask label、隐藏当前选中区域计数、隐藏后端模型置信度、选中 mask 后端拓扑属性分析、拓扑锚点数量按真实 polygon 顶点数显示、分析请求 abort/cancel 静默忽略且旧请求不覆盖新状态、边缘平滑强度防抖预览不标 dirty、应用边缘平滑后将 mask 标记为 dirty、平滑作为实际几何编辑、平滑同步传播链对应 mask、平滑保存时保留传播 lineage 而不把传播帧变成人工/AI 标注帧、平滑撤销/重做、平滑应用后强度归零 |
@@ -38,7 +38,7 @@
 | R4 | 工作区加载帧、无帧项目不自动解析、工作区短状态自动消失、后端标注回显保留本地未保存 draft mask、Canvas/AI 底图居中适配且保留边距、工作区 mask 透明度、选中 mask 后跨帧自动跟随同一传播链结果、左侧工具栏当前帧清空优先作用于选中 mask、无传播链时直接执行、有传播链时可选当前帧/传播所有帧/取消、清空人工/AI 标注帧前二次确认、取消确认不删除、仅自动传播帧不确认、删除单个传播 mask 后空帧不保留传播历史颜色、传播权重下拉深色可读配色、缩略图/range/视频处理进度条、视频处理进度条点击跳帧、人工/AI 标注帧红色竖线和标识点击跳帧、自动传播帧蓝色区段和标识点击跳帧、最近自动传播历史片段同一蓝色系按新旧递进显示，旧记录第 5 次后统一阈值色、当前帧白色贯穿线、传播范围洋红/黄绿色边界贯穿线、缩略图红/蓝边框、人工/AI 标注帧叠加传播状态时红框优先保留并显示蓝色内描边、当前人工/AI 标注帧青色外框加红色内描边、普通状态不显示传播范围黄色选区、播放进度条/视频处理进度条拖拽选择传播范围、Canvas/AI 画布拖拽平移回写 position state、左右方向键切帧、播放、按 FPS 显示时间 | `VideoWorkspace.test.tsx`, `FrameTimeline.test.tsx`, `CanvasArea.test.tsx`, `AISegmentation.test.tsx` | 已覆盖 |
 | R5 | 工具切换、工具栏紧凑滚动布局、低对比滚动条、外扩滚动条槽位、调整多边形入口、清空遮罩唯一左侧入口、Canvas 右下角旧清空/应用分类按钮移除、GT Mask 导入入口位置和紫色底色、工作区工具栏隐藏 AI 正/反点和框选、左侧工具栏不重复撤销/重做、AI 跳转、矩形/圆/线/点/多边形绘制、已有 mask 上继续绘制、多边形和布尔工具上下文提示、Canvas 上下文提示数秒后自动隐藏 | `ToolsPalette.test.tsx`, `CanvasArea.test.tsx` | 已覆盖 |
 | R5 | 顶点直接拖动编辑、顶点拖拽结束不改变 Canvas 视口、边中点插点、双击边界按位置插点、中空 mask 与中空画笔 mask 内洞 ring 顶点和插点可编辑、顶点删除、整块删除、删除传播链自动传播 mask 且保留独立 AI 推理 mask、工作区顶栏撤销/重做按钮、顶栏撤销/重做图标强调色、撤销/重做快捷键 Ctrl/Cmd+Z、Ctrl/Cmd+Shift+Z、Ctrl/Cmd+Y 和 KeyZ/KeyY fallback、区域合并、区域去除、布尔选择主区域黄色实线/扣除区域红色虚线、布尔选择顺序提示、hole even-odd 渲染 | `CanvasArea.test.tsx`, `VideoWorkspace.test.tsx`, `keyboardShortcuts.test.ts`, `useStore.test.ts` | 已覆盖 |
-| R6 | SAM 2.1 变体选择、点/框/interactive、semantic 禁用、SAM 3 入口隐藏和后端拒绝、SAM 2.1 最高分候选去重、AI 页框选/框选后加点、AI 页提示工具上下文提示、AI 页重复执行替换旧候选、AI 页不渲染工作区已有 mask、AI 页可在候选 mask 上继续添加正/反点、AI 页可删除提示点、AI 页可删除选中候选、AI 页清空只移除本页候选、AI 页/右侧共享遮罩透明度只改预览 opacity、AI 页生成 mask 自动选中并可换标签、AI 页无语义候选禁止推送到工作区并用 error toast 提示、离开 AI 页时清理未分类候选、AI 页推送到工作区编辑保留选择和当前帧、SAM 2.1 视频按参考帧全部 mask 和范围自动传播、同类多实例按来源 id 分开传播、当前参考帧无遮罩提示、传播前只保存参考帧 draft/dirty seed mask、传播前独立选择 SAM 2.1 tiny/small/base+/large 权重、自动传播 Celery 任务入队、传播入队权重 id 规范化/拒绝不支持 id、传播 seed 来源 id/签名和历史平滑 metadata 兼容、中空 seed holes 栅格化扣除和传播结果 holes 提取、历史平滑 seed 保存前对 forward/backward polygon 实际应用边缘平滑并减少密集轮廓点、边缘平滑强度缓入递进曲线、未编辑传播结果作为 seed 时继承原始签名并跳过重复传播、已编辑传播结果保留 lineage 但重算签名并清理旧结果、中间帧人工新增替代 seed 时清理下游同物体旧传播结果、中间帧 backward 传播清理旧 forward 结果、换权重传播先清理旧结果、旧临时 seed id 传播结果兼容清理、前端任务轮询进度、传播任务 runner 保存标注和结果权重 id、传播任务重试、传播空结果提示、GPU/模型状态、参数 options、polygons 转 mask | `api.test.ts`, `CanvasArea.test.tsx`, `AISegmentation.test.tsx`, `VideoWorkspace.test.tsx`, `ModelStatusBadge.test.tsx`, `test_ai.py`, `test_tasks.py`, `test_sam2_engine.py` | 已覆盖 |
+| R6 | SAM 2.1 变体选择、模型不可用时 AI 页禁用不可用变体和执行按钮、工作区所有变体不可用时禁用 AI自动推理、点/框/interactive、semantic 禁用、SAM 3 入口隐藏和后端拒绝、SAM 2.1 最高分候选去重、AI 页框选/框选后加点、AI 页提示工具上下文提示、AI 页重复执行替换旧候选、AI 页不渲染工作区已有 mask、AI 页可在候选 mask 上继续添加正/反点、AI 页可删除提示点、AI 页可删除选中候选、AI 页清空只移除本页候选、AI 页/右侧共享遮罩透明度只改预览 opacity、AI 页生成 mask 自动选中并可换标签、AI 页无语义候选禁止推送到工作区并用 error toast 提示、离开 AI 页时清理未分类候选、AI 页推送到工作区编辑保留选择和当前帧、SAM 2.1 视频按参考帧全部 mask 和范围自动传播、同类多实例按来源 id 分开传播、当前参考帧无遮罩提示、传播前只保存参考帧 draft/dirty seed mask、传播前独立选择 SAM 2.1 tiny/small/base+/large 权重、自动传播 Celery 任务入队、传播入队权重 id 规范化/拒绝不支持 id、传播 seed 来源 id/签名和历史平滑 metadata 兼容、中空 seed holes 栅格化扣除和传播结果 holes 提取、历史平滑 seed 保存前对 forward/backward polygon 实际应用边缘平滑并减少密集轮廓点、边缘平滑强度缓入递进曲线、未编辑传播结果作为 seed 时继承原始签名并跳过重复传播、已编辑传播结果保留 lineage 但重算签名并清理旧结果、中间帧人工新增替代 seed 时清理下游同物体旧传播结果、中间帧 backward 传播清理旧 forward 结果、换权重传播先清理旧结果、旧临时 seed id 传播结果兼容清理、前端任务轮询进度、传播任务 runner 保存标注和结果权重 id、传播任务重试、传播空结果提示、GPU/模型状态、参数 options、polygons 转 mask | `api.test.ts`, `CanvasArea.test.tsx`, `AISegmentation.test.tsx`, `VideoWorkspace.test.tsx`, `ModelStatusBadge.test.tsx`, `test_ai.py`, `test_tasks.py`, `test_sam2_engine.py` | 已覆盖 |
 | R7 | 保存状态按钮“保存 X 个改动/已全部保存”、保存、保存后替换已提交 draft、查询、更新、dirty 本地旧 annotationId 的预检缺失直接重新创建和 PATCH 404 重新创建、删除标注、工作区回显、清空已保存标注、GT mask 导入和 seed point 数据兼容、导入 mask 不显示黄色 seed point、高精度 GT contour、导入 mask 拓扑统计和边缘平滑、8-bit 低数值 GT_label 图导入、16-bit/uint16 GT_label 图拒绝、全背景 0 GT_label 图拒绝并保留“没有非背景 maskid 区域”提示、RGB 等通道 maskid 图导入、导入预览、未知 maskid 导入策略、非法彩色 GT mask 拒绝、尺寸不一致自动最近邻拉伸 | `VideoWorkspace.test.tsx`, `CanvasArea.test.tsx`, `api.test.ts`, `test_ai.py` | 已覆盖 |
 | R8 | 模板加载、新建、编辑、删除、删除模板站内确认、鼠标复制模板为私有副本并保留 maskid/颜色/层级/规则、所有模板归一化包含黑色 `maskid:0`“待分类”保留类、保留类固定最后且不可删除/拖拽上移、详情页标题/编辑模板按钮/垃圾桶删 label、编辑弹窗分类编辑不显示旧 category 来源元信息、默认模板“腹腔镜胆囊切除术”和“头颈部CT分割”幂等 seed、头颈部 CT 默认分类名纯中文且不带括号英文翻译、恢复出厂设置保留并权威恢复系统模板、默认模板缺失后重建、默认语义分类树被修改/删减后覆盖恢复、编辑后详情页刷新、详情页和编辑弹窗拖拽语义层级顺序、拖拽保存 `zIndex` 且不改变 maskid、JSON 分类导入预览、数组/对象/常见粘贴格式导入、JSON 错误内联提示、保存错误非阻塞提示、mapping_rules 映射、后端 CRUD | `TemplateRegistry.test.tsx`, `TransientNotice.test.tsx`, `api.test.ts`, `test_templates.py`, `test_admin.py` | 已覆盖 |
 | R9 | 模板选择、面板标题简化、工作区遮罩透明度滑杆、分类展示、分类选择、模板类别删除后项目旧 mask 回显为 `maskid:0` 待分类、分类树拖拽调整内部覆盖顺序且不改变 maskid、拖拽后同步同类 mask 层级并标记待保存、点击 mask 自动聚焦对应分类、已选 mask 换标签并置顶显示、分类变更同步同一传播链前后帧对应 mask、自定义分类写入后端模板、目标实例标题显示当前 mask label、隐藏当前选中区域计数、隐藏后端模型置信度、后端拓扑属性分析、拓扑锚点真实顶点计数、分析请求 abort/cancel 静默忽略且旧请求不覆盖新状态、边缘平滑强度防抖预览、边缘平滑应用后确认 dirty、平滑作为实际几何编辑、平滑同步传播链对应 mask、平滑撤销/重做、平滑应用后强度归零、占位状态 | `OntologyInspector.test.tsx`, `VideoWorkspace.test.tsx`, `CanvasArea.test.tsx`, `useStore.test.ts`, `test_ai.py` | 已覆盖 |

doc/10-installation.md

@@ -27,6 +27,14 @@
 | 视频处理 | FFmpeg |
 | GPU | NVIDIA GPU + CUDA，用于 SAM 2.1 推理；无 GPU 时可 CPU 运行但会很慢 |
 
+Docker GPU 部署还需要宿主机安装 NVIDIA Container Toolkit，并确保以下命令可正常输出 GPU：
+
+```bash
+docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi
+```
+
+如果这里报 `failed to discover GPU vendor from CDI`，说明 Docker 还没有拿到 GPU，即使宿主机 `nvidia-smi` 正常，容器内仍会显示 CPU。
+
 安装系统依赖：
 
 ```bash
@@ -68,6 +76,48 @@ cd /home/wkmgc/Desktop/Seg_Server
 
 ---
 
+## 2.1 Docker 最小部署
+
+当前仓库旁的 `/home/wkmgc/Desktop/Seg_Server_Docker` 是最小 Docker 部署目录，包含前端、FastAPI 后端、Celery worker、PostgreSQL、Redis、MinIO、演示视频/DICOM 数据和部署文档。
+
+编辑 `.env`：
+
+```bash
+cd /home/wkmgc/Desktop/Seg_Server_Docker
+cp .env.example .env
+```
+
+关键配置：
+
+```ini
+PUBLIC_HOST=192.168.3.11
+CORS_ORIGINS=["http://192.168.3.11:3000","http://localhost:3000","http://127.0.0.1:3000"]
+SAM_MODELS_DIR=/home/wkmgc/Desktop/Seg_Server/models
+```
+
+`SAM_MODELS_DIR` 会挂载到容器内 `/app/models`。当前后端镜像安装 PyTorch/SAM2 后，只有这里存在 checkpoint 的 SAM 2.1 变体会显示可用；如果没有 NVIDIA Container Toolkit，模型可在 CPU 上可用，但 GPU 状态仍是 CPU。
+
+启动普通容器：
+
+```bash
+docker compose up -d --build
+```
+
+启动 GPU 容器：
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d --build
+```
+
+验证：
+
+```bash
+docker compose ps
+curl http://localhost:8000/health
+```
+
+---
+
 ## 3. 配置 PostgreSQL
 
 默认后端配置来自 `backend/config.py`：

doc/11-frontend-interaction-state-machines.md

@@ -60,7 +60,7 @@
 
 | 模式 | 进入事件 | 顶栏状态 | 时间轴行为 | 确认行为 | 测试 |
 |------|----------|----------|------------|----------|------|
-| `propagation` | 左侧“自动传播” | 显示传播权重、向前/向后帧数和“开始传播” | 拖拽/点击设置传播起止帧 | 保存参考帧 draft/dirty seed，提交 Celery 传播任务 | `VideoWorkspace.test.tsx` |
+| `propagation` | 左侧“AI自动推理” | 显示传播权重、向前/向后帧数和“开始传播” | 拖拽/点击设置传播起止帧 | 先校验当前 SAM 2.1 权重状态；可用才保存参考帧 draft/dirty seed 并提交 Celery 传播任务 | `VideoWorkspace.test.tsx` |
 | `export` | 打开导出菜单并选择“特定范围帧” | 导出菜单保持打开 | 拖拽/点击设置导出起止帧 | “开始导出”保存待归档 mask 后下载 ZIP | `VideoWorkspace.test.tsx` |
 | `boolean` | 区域合并/去除选择“按帧范围选择” | 显示“确认区域合并/确认重叠区域去除” | 拖拽/点击设置布尔操作范围 | 弹最终确认，只同步范围内对应传播帧，保留传播 metadata | `CanvasArea.test.tsx`、`VideoWorkspace.test.tsx` |
 | `clear` | 清空/DEL 选择“按帧范围选择” | 显示“确认清空” | 拖拽/点击设置清空范围 | 弹最终确认；如范围含人工/AI 帧，再询问是否删除这些帧 | `VideoWorkspace.test.tsx` |
@@ -80,6 +80,7 @@
 | `interactive-prompt` | 框选后加点或直接点选 | 发送累计正/负点；负点启用背景过滤 | 空结果移除旧候选 | `AISegmentation.test.tsx` |
 | `candidate-selected` | 推理返回 mask 或点击候选 | 可通过语义树换标签；可删除候选 | 推送工作区、删除候选、重新推理 | `AISegmentation.test.tsx` |
 | `send-blocked` | 候选缺少语义分类时点击推送 | 显示 error toast，不切模块、不改工具 | 选择语义分类 | `AISegmentation.test.tsx` |
+| `model-unavailable` | `/api/ai/models/status` 返回所选 SAM 2.1 变体不可用 | 禁用不可用模型按钮和执行按钮；不调用 `/api/ai/predict` | 后端模型状态恢复可用或切换到可用变体 | `AISegmentation.test.tsx` |
 
 ## 模板与项目确认流
 

src/components/AISegmentation.test.tsx

@@ -26,6 +26,9 @@ describe('AISegmentation', () => {
       gpu: { available: true, device: 'cuda', name: 'RTX 4090', torch_available: true },
       models: [
         { id: 'sam2.1_hiera_tiny', label: 'SAM 2.1 Tiny', available: true, loaded: false, device: 'cuda', supports: ['point', 'box'], message: 'SAM 2.1 Tiny ready', package_available: true, checkpoint_exists: true, python_ok: true, torch_ok: true, cuda_required: false },
+        { id: 'sam2.1_hiera_small', label: 'SAM 2.1 Small', available: true, loaded: false, device: 'cuda', supports: ['point', 'box'], message: 'SAM 2.1 Small ready', package_available: true, checkpoint_exists: true, python_ok: true, torch_ok: true, cuda_required: false },
+        { id: 'sam2.1_hiera_base_plus', label: 'SAM 2.1 Base+', available: true, loaded: false, device: 'cuda', supports: ['point', 'box'], message: 'SAM 2.1 Base+ ready', package_available: true, checkpoint_exists: true, python_ok: true, torch_ok: true, cuda_required: false },
+        { id: 'sam2.1_hiera_large', label: 'SAM 2.1 Large', available: true, loaded: false, device: 'cuda', supports: ['point', 'box'], message: 'SAM 2.1 Large ready', package_available: true, checkpoint_exists: true, python_ok: true, torch_ok: true, cuda_required: false },
       ],
     });
   });
@@ -137,6 +140,26 @@ describe('AISegmentation', () => {
     expect(await screen.findByText('请先放置正/反向提示点或框选区域。')).toBeInTheDocument();
   });
 
+  it('disables unavailable model variants and skips AI inference', async () => {
+    apiMock.getAiModelStatus.mockResolvedValue({
+      selected_model: 'sam2.1_hiera_tiny',
+      gpu: { available: false, device: 'cpu', name: null, torch_available: false },
+      models: [
+        { id: 'sam2.1_hiera_tiny', label: 'SAM 2.1 Tiny', available: false, loaded: false, device: 'cpu', supports: [], message: 'missing PyTorch, sam2 package, checkpoint', package_available: false, checkpoint_exists: false, python_ok: false, torch_ok: false, cuda_required: false },
+        { id: 'sam2.1_hiera_small', label: 'SAM 2.1 Small', available: false, loaded: false, device: 'cpu', supports: [], message: 'missing PyTorch, sam2 package, checkpoint', package_available: false, checkpoint_exists: false, python_ok: false, torch_ok: false, cuda_required: false },
+      ],
+    });
+    render(<AISegmentation onSendToWorkspace={vi.fn()} />);
+
+    expect(await screen.findByText('当前模型不可用')).toBeDisabled();
+    expect(screen.getByRole('button', { name: /tiny/i })).toBeDisabled();
+    fireEvent.click(screen.getByText('正向选点'));
+    fireEvent.click(screen.getByTestId('konva-stage'));
+    fireEvent.click(screen.getByText('当前模型不可用'));
+
+    expect(apiMock.predictMask).not.toHaveBeenCalled();
+  });
+
   it('uses a dragged box prompt for AI page inference without adding a point on click', async () => {
     apiMock.predictMask.mockResolvedValueOnce({ masks: [] });
     render(<AISegmentation onSendToWorkspace={vi.fn()} />);

src/components/AISegmentation.tsx

@@ -65,7 +65,8 @@ export function AISegmentation({ onSendToWorkspace }: AISegmentationProps) {
     const selectedAiMasks = frameMasks.filter((mask) => selectedMaskIds.includes(mask.id));
     const aiMasksToSend = selectedAiMasks.length > 0 ? selectedAiMasks : frameMasks;
     const selectedModelStatus = modelStatus?.models.find((model) => model.id === aiModel);
-    const modelCanInfer = selectedModelStatus?.available ?? true;
+    const modelStatusLoaded = Boolean(modelStatus);
+    const modelCanInfer = modelStatusLoaded && Boolean(selectedModelStatus?.available);
 
     const effectiveTool = storeActiveTool;
 
@@ -245,6 +246,10 @@ export function AISegmentation({ onSendToWorkspace }: AISegmentationProps) {
         setInferenceMessage('请先在项目工作区选择一帧图像。');
         return;
       }
+      if (!modelCanInfer) {
+        setInferenceMessage(selectedModelStatus?.message ? `当前模型不可用：${selectedModelStatus.message}` : '当前模型不可用，请检查 GPU、PyTorch/SAM2 和模型权重。');
+        return;
+      }
 
       const imageWidth = currentFrame.width || image?.naturalWidth || image?.width || 0;
       const imageHeight = currentFrame.height || image?.naturalHeight || image?.height || 0;
@@ -327,7 +332,7 @@ export function AISegmentation({ onSendToWorkspace }: AISegmentationProps) {
       } finally {
         setIsInferencing(false);
       }
-    }, [activeClass, activeTemplateId, aiMaskIds, aiModel, autoDeleteBg, cropMode, currentFrame?.height, currentFrame?.id, currentFrame?.width, image?.height, image?.naturalHeight, image?.naturalWidth, image?.width, masks, points, promptBox, selectedMaskIds, selectedModelStatus?.label, setMasks, setSelectedMaskIds]);
+    }, [activeClass, activeTemplateId, aiMaskIds, aiModel, autoDeleteBg, cropMode, currentFrame?.height, currentFrame?.id, currentFrame?.width, image?.height, image?.naturalHeight, image?.naturalWidth, image?.width, masks, modelCanInfer, points, promptBox, selectedMaskIds, selectedModelStatus?.label, selectedModelStatus?.message, setMasks, setSelectedMaskIds]);
 
     const clearAiLayer = useCallback(() => {
       setPoints([]);
@@ -474,12 +479,17 @@ export function AISegmentation({ onSendToWorkspace }: AISegmentationProps) {
                                 <button
                                   key={option.id}
                                   type="button"
-                                  onClick={() => setAiModel(option.id)}
+                                  onClick={() => {
+                                    if (available) setAiModel(option.id);
+                                  }}
+                                  disabled={!available}
+                                  title={available ? option.label : status?.message || `${option.label} 不可用`}
                                   className={cn(
                                     "h-8 rounded border px-2 text-[10px] uppercase tracking-wider transition-colors flex items-center justify-between",
                                     selected
                                       ? "bg-cyan-500/10 border-cyan-400/40 text-cyan-300"
-                                      : "bg-white/[0.03] border-white/5 text-gray-400 hover:bg-white/5 hover:text-gray-200"
+                                      : "bg-white/[0.03] border-white/5 text-gray-400 hover:bg-white/5 hover:text-gray-200",
+                                    !available && "opacity-45 cursor-not-allowed hover:bg-white/[0.03] hover:text-gray-400"
                                   )}
                                 >
                                   <span>{option.shortLabel}</span>
@@ -584,7 +594,7 @@ export function AISegmentation({ onSendToWorkspace }: AISegmentationProps) {
                         )}
                     >
                         {isInferencing ? <Loader2 size={16} className="animate-spin" /> : <Sparkles size={16} />}
-                        {isInferencing ? '推理中...' : modelCanInfer ? '执行高精度语义分割' : '当前模型不可用'}
+                        {isInferencing ? '推理中...' : modelCanInfer ? '执行高精度语义分割' : modelStatusLoaded ? '当前模型不可用' : '正在读取模型状态'}
                     </button>
                     {inferenceMessage && (
                       <div className="rounded border border-white/10 bg-white/5 px-3 py-2 text-[11px] leading-relaxed text-gray-300">

src/components/VideoWorkspace.test.tsx

@@ -82,6 +82,9 @@ describe('VideoWorkspace', () => {
       gpu: { available: false, device: 'cpu', name: null, torch_available: true },
       models: [
         { id: 'sam2.1_hiera_tiny', label: 'SAM 2.1 Tiny', available: true, loaded: false, device: 'cpu', supports: [], message: 'ready', package_available: true, checkpoint_exists: true, python_ok: true, torch_ok: true, cuda_required: false },
+        { id: 'sam2.1_hiera_small', label: 'SAM 2.1 Small', available: true, loaded: false, device: 'cpu', supports: [], message: 'ready', package_available: true, checkpoint_exists: true, python_ok: true, torch_ok: true, cuda_required: false },
+        { id: 'sam2.1_hiera_base_plus', label: 'SAM 2.1 Base+', available: true, loaded: false, device: 'cpu', supports: [], message: 'ready', package_available: true, checkpoint_exists: true, python_ok: true, torch_ok: true, cuda_required: false },
+        { id: 'sam2.1_hiera_large', label: 'SAM 2.1 Large', available: true, loaded: false, device: 'cpu', supports: [], message: 'ready', package_available: true, checkpoint_exists: true, python_ok: true, torch_ok: true, cuda_required: false },
       ],
     });
     apiMock.analyzeMask.mockResolvedValue({
@@ -1965,6 +1968,29 @@ describe('VideoWorkspace', () => {
     expect(screen.getByTestId('propagation-history-segment')).toHaveAttribute('title', 'SAM 2.1 Tiny 自动传播：第 1-2 帧');
   });
 
+  it('disables workspace AI auto inference when no SAM2 model is available', async () => {
+    apiMock.getAiModelStatus.mockResolvedValue({
+      selected_model: 'sam2.1_hiera_tiny',
+      gpu: { available: false, device: 'cpu', name: null, torch_available: false },
+      models: [
+        { id: 'sam2.1_hiera_tiny', label: 'SAM 2.1 Tiny', available: false, loaded: false, device: 'cpu', supports: [], message: 'missing PyTorch, sam2 package, checkpoint', package_available: false, checkpoint_exists: false, python_ok: false, torch_ok: false, cuda_required: false },
+        { id: 'sam2.1_hiera_small', label: 'SAM 2.1 Small', available: false, loaded: false, device: 'cpu', supports: [], message: 'missing PyTorch, sam2 package, checkpoint', package_available: false, checkpoint_exists: false, python_ok: false, torch_ok: false, cuda_required: false },
+        { id: 'sam2.1_hiera_base_plus', label: 'SAM 2.1 Base+', available: false, loaded: false, device: 'cpu', supports: [], message: 'missing PyTorch, sam2 package, checkpoint', package_available: false, checkpoint_exists: false, python_ok: false, torch_ok: false, cuda_required: false },
+        { id: 'sam2.1_hiera_large', label: 'SAM 2.1 Large', available: false, loaded: false, device: 'cpu', supports: [], message: 'missing PyTorch, sam2 package, checkpoint', package_available: false, checkpoint_exists: false, python_ok: false, torch_ok: false, cuda_required: false },
+      ],
+    });
+    apiMock.getProjectFrames.mockResolvedValueOnce([
+      { id: 10, project_id: 1, frame_index: 0, image_url: '/frame.jpg', width: 640, height: 360 },
+      { id: 11, project_id: 1, frame_index: 1, image_url: '/frame-1.jpg', width: 640, height: 360 },
+    ]);
+
+    render(<VideoWorkspace />);
+    await waitFor(() => expect(useStore.getState().frames).toHaveLength(2));
+    await waitFor(() => expect(screen.getByRole('button', { name: 'AI自动推理' })).toBeDisabled());
+
+    expect(apiMock.queuePropagationTask).not.toHaveBeenCalled();
+  });
+
   it('uses the separately selected propagation weight when queueing propagation', async () => {
     apiMock.getProjectFrames.mockResolvedValueOnce([
       { id: 10, project_id: 1, frame_index: 0, image_url: '/frame.jpg', width: 640, height: 360 },

src/components/VideoWorkspace.tsx

@@ -7,6 +7,7 @@ import {
   cancelTask,
   deleteAnnotation,
   exportSegmentationResults,
+  getAiModelStatus,
   getProjectAnnotations,
   getProjectFrames,
   getTask,
@@ -14,6 +15,7 @@ import {
   importGtMask,
   queuePropagationTask,
   saveAnnotation,
+  type AiRuntimeStatus,
   type SegmentationExportOutput,
   updateAnnotation,
 } from '../lib/api';
@@ -547,6 +549,7 @@ export function VideoWorkspace({ onNavigateToAI }: { onNavigateToAI?: () => void
   const [propagationTaskId, setPropagationTaskId] = useState<number | null>(null);
   const [propagationWeight, setPropagationWeight] = useState<AiModelId>(aiModel || DEFAULT_AI_MODEL_ID);
   const [hasCustomPropagationWeight, setHasCustomPropagationWeight] = useState(false);
+  const [propagationModelStatus, setPropagationModelStatus] = useState<AiRuntimeStatus | null>(null);
   const [propagationHistory, setPropagationHistory] = useState<PropagationHistorySegment[]>([]);
 
   useEffect(() => {
@@ -559,10 +562,33 @@ export function VideoWorkspace({ onNavigateToAI }: { onNavigateToAI?: () => void
     setPropagationHistory([]);
   }, [currentProject?.id]);
 
+  useEffect(() => {
+    let cancelled = false;
+    getAiModelStatus(propagationWeight)
+      .then((status) => {
+        if (!cancelled) setPropagationModelStatus(status);
+      })
+      .catch(() => {
+        if (!cancelled) setPropagationModelStatus(null);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [propagationWeight]);
+
   const propagationWeightLabel = useMemo(
     () => SAM2_MODEL_OPTIONS.find((option) => option.id === propagationWeight)?.label || propagationWeight,
     [propagationWeight],
   );
+  const selectedPropagationModelStatus = useMemo(
+    () => propagationModelStatus?.models.find((model) => model.id === propagationWeight) || null,
+    [propagationModelStatus, propagationWeight],
+  );
+  const propagationModelStatusLoaded = Boolean(propagationModelStatus);
+  const propagationModelCanRun = propagationModelStatusLoaded && Boolean(selectedPropagationModelStatus?.available);
+  const hasAnyPropagationModelAvailable = propagationModelStatus
+    ? propagationModelStatus.models.some((model) => model.available)
+    : true;
   useEffect(() => {
     const handleWorkspaceShortcuts = (event: KeyboardEvent) => {
       const shortcut = getUndoRedoShortcut(event);
@@ -1619,8 +1645,27 @@ export function VideoWorkspace({ onNavigateToAI }: { onNavigateToAI?: () => void
     setHasExplicitPropagationRange(true);
   };
 
+  const ensurePropagationModelAvailable = async () => {
+    try {
+      const status = await getAiModelStatus(propagationWeight);
+      setPropagationModelStatus(status);
+      const selectedStatus = status.models.find((model) => model.id === propagationWeight);
+      if (selectedStatus?.available) return true;
+      setStatusMessage(selectedStatus?.message
+        ? `AI自动推理不可用：${selectedStatus.message}`
+        : 'AI自动推理不可用，请检查 GPU、PyTorch/SAM2 和模型权重。');
+      return false;
+    } catch (err) {
+      console.error('Load AI model status failed:', err);
+      setStatusMessage('AI自动推理不可用：无法读取模型状态，请检查后端服务。');
+      return false;
+    }
+  };
+
   const runAutoPropagate = async () => {
     if (!currentProject?.id || !currentFrame?.id) return;
+    if (!await ensurePropagationModelAvailable()) return;
+
     const initialSeedMasks = useStore.getState().masks.filter((mask) => String(mask.frameId) === String(currentFrame.id));
     if (initialSeedMasks.length === 0) {
       setStatusMessage('当前参考帧无遮罩');
@@ -1915,14 +1960,18 @@ export function VideoWorkspace({ onNavigateToAI }: { onNavigateToAI?: () => void
                   setHasCustomPropagationWeight(true);
                   setPropagationWeight(event.target.value as AiModelId);
                 }}
-                disabled={isPropagating || isSaving || isExporting || isImportingGt}
+                disabled={isPropagating || isSaving || isExporting || isImportingGt || !hasAnyPropagationModelAvailable}
                 className="h-6 w-24 rounded border border-cyan-500/20 bg-[#050809] px-1 text-[10px] text-cyan-100 outline-none focus:border-cyan-400/70 disabled:opacity-40"
               >
-                {SAM2_MODEL_OPTIONS.map((option) => (
+                {SAM2_MODEL_OPTIONS.map((option) => {
-                  <option key={option.id} value={option.id} className="bg-[#050809] text-cyan-100">
+                  const status = propagationModelStatus?.models.find((model) => model.id === option.id);
-                    {option.shortLabel}
+                  const available = status ? status.available : true;
-                  </option>
+                  return (
-                ))}
+                    <option key={option.id} value={option.id} disabled={!available} className="bg-[#050809] text-cyan-100 disabled:text-gray-500">
+                      {available ? option.shortLabel : `${option.shortLabel} 不可用`}
+                    </option>
+                  );
+                })}
               </select>
             </div>
           )}
@@ -2085,10 +2134,10 @@ export function VideoWorkspace({ onNavigateToAI }: { onNavigateToAI?: () => void
           {showPropagationControls && (
             <button
               onClick={handleAutoPropagate}
-              disabled={frames.length === 0 || isSaving || isExporting || isImportingGt || isPropagating}
+              disabled={frames.length === 0 || isSaving || isExporting || isImportingGt || isPropagating || (propagationModelStatusLoaded && !propagationModelCanRun)}
               className="px-4 py-1.5 bg-cyan-500/10 hover:bg-cyan-500/20 border border-cyan-500/25 rounded-md text-xs transition-colors text-cyan-100 disabled:opacity-40 disabled:cursor-not-allowed"
             >
-              {isPropagating ? '传播中...' : '开始传播'}
+              {isPropagating ? '传播中...' : propagationModelStatusLoaded && !propagationModelCanRun ? '模型不可用' : '开始传播'}
             </button>
           )}
           {isPropagationRangeSelecting && (
@@ -2300,7 +2349,7 @@ export function VideoWorkspace({ onNavigateToAI }: { onNavigateToAI?: () => void
           onClearSelection={handleClearSelection}
           onDeleteMasks={handleDeleteSelectedMasks}
           onClearMasks={handleClearCurrentFrameMasks}
-          canAutoPropagate={Boolean(currentProject?.id && currentFrame?.id) && !isSaving && !isExporting && !isImportingGt}
+          canAutoPropagate={Boolean(currentProject?.id && currentFrame?.id) && !isSaving && !isExporting && !isImportingGt && hasAnyPropagationModelAvailable}
           isPropagating={isPropagating}
           canImportGtMask={Boolean(currentProject?.id && currentFrame?.id) && !isSaving && !isExporting && !isPropagating}
           isImportingGtMask={isImportingGt}