⚠️ 自动镜像 · 此页由 docs-site/scripts/mirror-changelog.mjs 从 ROADMAP/[archived]0.10.x.md 生成，请勿直接编辑此处；改源文件后 pnpm docs:build 会自动同步。

v0.10.x — SAM 3 接入 + ML 工具 UI 重构

状态：草案 / 待对齐。前置依赖：v0.9.x Grounded-SAM-2 已上线，详见 [archived]0.9.x.md；v0.10.0 sam3-backend 容器化已完成。
目标：在 sam3-backend 已就位的前提下，把工作台的 ML 工具 UI 从「单后端 / prompt 按钮写死」重构为 Prompt-first + Capability 协商驱动，为未来 N 个后端共存做架构铺垫；运行时仍维持 每项目 1 个后端绑定（env 控制），避免测试环境显存爆炸。
范围边界：v0.10.x 不做双后端实际并存的运行（路由 / AB 对比 / 自动 fallback 全部推迟到 v0.11+），但 DB schema / 后端 API / 前端 UI 一步到位按 1:N 设计。

0. TL;DR

v0.10.0 ✅ 已完成：sam3-backend 容器化、协议补 exemplar、ProjectSettings 可挂。
v0.10.1 ✅ 已完成：Capability 协商基础设施（/setup JSON Schema + useMLCapabilities + env 限流）。
v0.10.2 ✅ 已完成：Prompt-first ToolDock 重构（4 个独立 AI 工具 + AIToolDrawer + 自研 SchemaForm + Exemplar 入口）。
v0.10.3 ✅ 已完成：1:N 后端管理 UI（配额角标 + 能力列 + LimitModal）+ ADR-0019/0020 + 管理员文档。
v0.10.x 重构方向：原计划的「双 backend 路由 + AB 对比 + 自动 fallback」整体推迟到 v0.11+。本阶段聚焦 ML 工具 UI 重构，让架构有能力承接未来 N 个后端，而不是先把功能做到 N 个再调架构。
核心机制：
- 后端 /setup 用 JSON Schema 自描述能力（supported_prompts / supported_text_outputs / params）
- 前端引入 useMLCapabilities() hook 作为单一事实源
- ToolDock 改 Prompt-first：用户先选交互范式（Point / Box / Text / Exemplar / Auto-Detect），再在工具面板里看到「支持该 prompt 的后端」
- 后端绑定数量由 MAX_ML_BACKENDS_PER_PROJECT env 控制，默认 1（生产可调高）
- UI 按 1:N 形态渲染：列表 + 「+ 添加后端」按钮；env 锁住时点击展示「暂未支持」Modal
切成 3 个里程碑：M1 Capability 协商基础设施 → M2 Prompt-first ToolDock + Exemplar 入口 → M3 1:N 后端管理 UI + 收口
估时 ~3 周。

1. SAM 3 能力盘点（保留作背景）

1.1 模型尺寸（只有一档）

维度	情况
参数规模	仅 848M（无 SAM 2 那种 tiny / large 多档）
checkpoint	~3.2GB
官方仓	`facebook/sam3`（2025-11）+ `facebook/sam3.1`（2026-03，仅 checkpoint）
HuggingFace 拉权重	需 `HF_TOKEN`
社区量化	HF 上有 ~10 个 int8/int4，可降到 ~2GB；精度未官方背书

1.2 能力（vs Grounded-SAM-2）

能力	grounded-sam2 (v0.9.x)	sam3 (v0.10.x)
point prompt	✅	❌
bbox prompt	✅	✅
文本 prompt（找全图实例）	✅ DINO → SAM 2 复合	✅ SAM 3 PCS 单模型一步
exemplar prompt（图像示例）	❌	✅
4060 笔记本可用	✅ 200-500ms	⚠️ FP16 显存 6-7GB
3090 / A100	✅	✅

→ 关键启示：两个后端能力不是子集关系（grounded-sam2 有 point，sam3 有 exemplar）。这正是 Capability 协商存在的必要性。

1.3 软件依赖差异

grounded-sam2：Python 3.10 / PyTorch 2.3 / CUDA 11.8
sam3：Python 3.12 / PyTorch 2.7 / CUDA 12.6
→ 各跑各的容器，不共享镜像

2. v0.9.x 已就位（复用清单）

资产	复用方式
ML Backend 协议（4 端点 + `context` 结构）	0 改动；`/setup` 字段做向下兼容扩展
`MLBackendClient`（apps/api 侧）	0 改动
工作台 `S` 工具（point / bbox / text 三入口）	重构为 Prompt-first 工具组（详见 M2）
`useInteractiveAI` hook	接入 `useMLCapabilities`；prompt → backend 解析
`apps/_shared/mask_utils/`（mask→polygon）	直接 import
AdminDashboard 健康检查 / 成本卡片	自动接入

3. 架构设计要点

3.1 1:1 绑定约束（env 控制 / schema 1:N）

原则：DB schema 和 API 一步到位按 1:N 设计；运行时上限由 env 控制；当前默认 1。

新增 env：MAX_ML_BACKENDS_PER_PROJECT=1（落地 apps/api/app/core/config.py）
POST /projects/{id}/ml-backends 校验：当前绑定数 ≥ 上限 → 返 409 Conflict + code: "ML_BACKEND_LIMIT_REACHED" + 提示文案
GET /projects/{id} 响应体里透出 ml_backend_limit 给前端
DB schema 不变（ml_backends.project_id 已经允许同 project 多行；当前靠应用层校验防止超限）
同步更新 .env.example + 跑 pnpm docs:gen-env-vars 重生成 dev/reference/env-vars.md

好处：测试环境硬约束防显存爆炸 → 生产/未来放开只改 env，零代码改动。

3.2 Capability 协商：`/setup` JSON Schema 自描述

现状：/setup 返松散 dict，前端未消费 → SAM3 + point 仍能点 → 后端 400。

目标：/setup 标准化为 JSON Schema：

json

{
  "name": "sam3-backend",
  "version": "0.10.0",
  "model_version": "sam3.1",
  "supported_prompts": ["bbox", "text", "exemplar"],
  "supported_text_outputs": ["box", "mask", "both"],
  "params": {
    "type": "object",
    "properties": {
      "box_threshold":  { "type": "number", "minimum": 0, "maximum": 1, "default": 0.25, "title": "Box 置信度阈值" },
      "text_threshold": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.20, "title": "Text 置信度阈值" },
      "sam_variant":    { "type": "string", "enum": ["base", "large"], "default": "base" }
    }
  }
}

前端拿到这份 schema 后：

supported_prompts 决定哪些 prompt 工具可用
params 直接喂给 schema-form 库（如 @rjsf/core 或自研最小实现）自动渲染参数面板
缺字段时前端走兜底（point/bbox/text），日志告警提示后端未升级

3.3 Prompt-first ToolDock

ToolDock 的 AI 工具组按交互范式列，不按模型：

ToolDock（左侧）
  [Box]         普通框
  [Polygon]     普通多边形
  ─────────────  AI 工具组 ─────────────
  [Smart Point]   ⚙  ← 点击工具时，右侧抽屉展开
  [Smart Box]     ⚙
  [Text Prompt]   ⚙
  [Exemplar]      ⚙
  ────────────────────────────────────
  [Hand]

激活 AI 工具时，右侧抽屉显示：

┌─ Smart Point ─────────────────────┐
│ 后端: ▼ grounded-sam2   (只有 1   │
│       项时可隐藏 / 灰显)           │
├───────────────────────────────────┤
│ 参数（由后端 /setup.params 渲染） │
│   置信度阈值: [0.50 ──●────]      │
│   ☐ 转为多边形                    │
├───────────────────────────────────┤
│ 状态: ● Healthy                   │
└───────────────────────────────────┘

后端选择器：能力协商后只列「声明支持该 prompt 的后端」（v0.10.x 阶段只有 1 个，控件保留以稳定 UI 形态）
用户点击不支持的工具时，工具本身在 ToolDock 里置灰并 tooltip 提示「当前项目绑定的后端不支持此交互模式」
prompt-type-first 心智：用户关心怎么交互，不关心模型名

3.4 1:N 后端管理 UI（受 env 限流）

ProjectSettings → ML 后端：

已绑定后端
  ┌────────────────────────────────────┐
  │ ⚙ grounded-sam2  ● Healthy         │
  │   supports: point, bbox, text      │
  │   [测试连接] [编辑] [解绑]          │
  └────────────────────────────────────┘

  [ + 添加后端 ]
       ↓ 点击（当 ml_backend_limit = 1 且已绑 1 个时）
  ┌─ Modal ────────────────────────────┐
  │ 🚧 多后端共存暂未支持              │
  │                                    │
  │ 当前每个项目最多绑定 1 个 ML 后端  │
  │ （受测试环境显存限制）              │
  │                                    │
  │ 如需切换后端，请先解绑当前后端。   │
  │                                    │
  │             [我知道了]              │
  └────────────────────────────────────┘

文案从后端 409 响应取（code + message），不要前端写死
工作台侧的后端选择器始终渲染（哪怕只有一项），形态稳定
将来放开 N：env 调大 + 删 Modal，UI 零改动

3.5 不做的事（推迟到 v0.11+）

❌ 双 backend 真实并存运行（不允许同 project 挂多后端）
❌ apps/api 的 prompt-routing 表（只有 1 个绑定时无需路由）
❌ AB 对比工具
❌ 自动 fallback（一个 backend 挂了切到另一个）
❌ SAM 3 视频 predictor

4. 版本切片

v0.10.0 — sam3-backend 容器化（M0，~5 工作日） ✅ 2026-05-13

plan · CHANGELOG

已完成：sam3-backend 跑通；ProjectSettings 能挂；与 grounded-sam2 互不干扰。详见原 §4.v0.10.0（git 历史）。

v0.10.1 — Capability 协商基础设施（M1，~5 工作日） ✅ 2026-05-14

plan · CHANGELOG

目标：/setup 标准化 + 前端 useMLCapabilities hook 落地；env 限流就位。

后端：

[x] 两个 backend 的 /setup 统一为 §3.2 的 JSON Schema 结构（破坏式升级；params 改成 Draft-07 子集）
[x] apps/api/app/config.py 加 max_ml_backends_per_project（默认 1）
[x] POST /projects/{id}/ml-backends 校验上限，返 409 + detail{code,message,limit,current}
[x] 新增 GET /projects/{id}/ml-backends/{bid}/setup 代理端点 + 30s TTL 进程内缓存（update/delete invalidate）
[x] GET /projects/{id} 响应体加 ml_backend_limit
[x] .env.example 同步 + 手工更新 docs-site/dev/reference/env-vars.md（仓库目前无 gen-env-vars 脚本）
[x] 单测：超限场景 / 边界场景 / setup 代理含缓存 / 跨项目 404 / 下游 502

前端：

[x] 新建 apps/web/src/pages/Workbench/state/useMLCapabilities.ts：通过 apps/api 代理端点拉 backend /setup，对外暴露 prompts / paramsSchema / capability / isPromptSupported(type) / isLoading / isError
[x] 兜底逻辑：/setup 缺 supported_prompts 时回落 ["point","bbox","text"] 并 console.warn；拉取失败返空（=禁用 AI 工具）
[x] 单测：成功 / 兜底 / 错误 / disabled 四分支

验收：

两个后端的 /setup curl 输出符合 schema
前端 hook 在工作台进入时拉到能力数据，DevTools 可查
ProjectSettings 试绑第二个后端 → 后端 409 → 前端不报错（暂未消费，M3 做 UI）

v0.10.2 — Prompt-first ToolDock + Exemplar 入口（M2，~6 工作日） ✅ 2026-05-14

plan · CHANGELOG

目标：ToolDock 改 Prompt-first；不支持的工具置灰；schema-form 参数面板；exemplar 工具上线。

[x] 拆原 SamTool 为四个独立工具注册：SmartPointTool / SmartBoxTool / TextPromptTool / ExemplarTool
[x] TOOL_REGISTRY 改造为支持工具的 requiredPrompt 字段；与 useMLCapabilities.isPromptSupported 联动决定置灰
[x] SamSubToolbar.tsx 拆解 → 工具激活时的右侧抽屉（AIToolDrawer.tsx 新建）
[x] AIToolDrawer：后端选择器（1:1 阶段单项 disabled）+ 自研 Schema-form 参数面板（~200 行，覆盖 number/integer/boolean/string enum/string text）+ smart-point 极性切换 + 状态指示
[x] useInteractiveAI 各 run* 接受 extraParams；AIToolDrawer 把 aiToolParams 透传到 /interactive-annotating.context
[x] ExemplarTool：独立工具按钮 + 普通拖框手势（不要求 Shift 修饰键）；backend 不支持时置灰
[x] 新增 runExemplar + samProbe.mode="exemplar"；WorkbenchShell onSamPrompt 按 kind 路由
[x] 能力变化兜底：当前 AI 工具失效时自动回退 hand + toast
[x] S 键改为 ai-cycle，按 isPromptSupported 跳过置灰工具
[x] E2E：annotation.spec 改造 + 新增 2 个用例（grounded-sam2 / sam3 capability 分支）
[x] SchemaForm 单测（number / boolean / enum / deriveDefaults / 空 schema）
[x] 文档：sam-tool.md 重写为 Prompt-first 心智 + Exemplar 章节

验收：

✅ 项目挂 grounded-sam2 → Exemplar 工具置灰，其余三个可用（E2E 覆盖）
✅ 项目挂 sam3 → SmartPoint 工具置灰，其余三个可用（E2E 覆盖）
✅ 参数面板调整后请求体携带新值（aiToolParams → extraParams → context）
✅ 旧 SamSubToolbar.tsx / SamTool.ts 删除，全仓 grep 无引用

v0.10.3 — 1:N 后端管理 UI + 收口（M3，~4 工作日） ✅ 2026-05-14

plan · CHANGELOG

目标：ProjectSettings 改 1:N 形态；env 锁满时弹「暂未支持」Modal；文档 + ADR 收口。

[x] ProjectSettings ML 后端区改 §3.4 列表形态（配额角标 + 能力列 + 禁用态）
[x] 「+ 添加后端」按钮：达上限时禁用 + tooltip；竞态/强行触发时 MlBackendLimitModal 弹出（文案来自 409 响应 + fallback）
[x] ADR-0019（roadmap 原计划编号 0012，仓库已到 0018 故顺延）：「ML 工具 UI 的 Prompt-first 重构与 1:N 架构（env 锁 1:1）」
[x] ADR-0020：「ML Backend Capability 协商协议」—— 记录 /setup JSON Schema 契约
[x] docs-site/dev/reference/ml-backend-protocol.md §/setup 章节（v0.10.1 已重写）—— 链到 ADR-0020 即可，不再重写
[x] docs-site/user-guide/for-annotators/sam-tool.md（v0.10.2 已完成 Prompt-first 心智 + Exemplar 教程，本期不动）
[x] docs-site/user-guide/for-project-admins/ml-backends.md（新）：绑定流程 + 1:1 限制说明 + 解绑 workflow
[x] CHANGELOG v0.10.3 段补齐

验收：

测试环境（env=1）下添加第二个后端 → Modal 弹出
修改 env=2 重启 → 可绑第二个（UI 形态不变，只是不再弹 Modal）
ADR + 协议文档 + 用户文档全部 PR 落地

5. 开放问题

Schema-form 选型：@rjsf/core（~50KB gzipped，功能全）还是自研 ~150 行（仅 number/boolean/enum/string）？倾向自研以避免巨大依赖。
AIToolDrawer 渲染位置：右侧固定抽屉，还是 ToolDock 右侧 Popover？倾向固定抽屉以便参数面板可见性高。
能力变化时已激活的工具如何处理：用户切换项目 / 后端解绑后，当前激活工具变得不支持 —— 自动回落到 Hand 工具，还是弹 Toast 让用户手选？倾向前者 + Toast 提示。
ml_backend_limit 透出位置：放 GET /projects/{id} 还是新独立端点 GET /config/limits？前者更省一次请求，倾向前者。

6. 风险

风险	概率	影响	缓解
Schema-form 自研覆盖不全（边角参数类型）	中	部分参数无法配置	先支持三种核心类型；遇到新类型再扩展，不预设抽象
`useMLCapabilities` 拉 `/setup` 超时阻塞工具激活	中	工具点不动	hook 内置 3s 超时 + 兜底能力声明；后端不可达时全工具置灰
旧 `SamTool` 删除导致历史 url / 教程失效	低	文档失修	M3 文档 sweep 时 grep 全仓 `SamTool` 引用
env 锁绕过（管理员直接改 DB 加行）导致 UI 异常	低	工作台 backend 选择器出现多项	工作台优雅渲染多项；env 锁只挡 API 入口

7. 与 ROADMAP.md 的关联

v0.10.x 落地后收掉：

§C.3「Magic Box / Snap」（exemplar prompt 是它的天然实现）→ M2

留给 v0.11+：

双 backend 实际并存（路由 / fallback / AB 对比，env 放开 + 实现 routing 层）
视频 predictor 接入（依赖 <VideoStage> 工作台）
Active Learning（Mode C）
训练闭环（Mode D）

8. 时间预估

切片	估计工时	状态
v0.10.0 sam3-backend 容器化	~5 工作日	✅
v0.10.1 Capability 协商基础设施	~5 工作日	✅
v0.10.2 Prompt-first ToolDock + Exemplar	~6 工作日	✅
v0.10.3 1:N 后端管理 UI + 收口	~4 工作日	✅
剩余合计	0（v0.10.x 全部落地）

Sources

Meta SAM 3 blog: https://ai.meta.com/blog/segment-anything-model-3/
facebookresearch/sam3: https://github.com/facebookresearch/sam3
CVAT 工具 UI（参考）：cvat-ui/src/components/annotation-page/standard-workspace/controls-side-bar/tools-control.tsx
协议契约：docs-site/dev/reference/ml-backend-protocol.md
前置版本：[archived]0.9.x.md（Grounded-SAM-2 落地）

v0.10.x — SAM 3 接入 + ML 工具 UI 重构 ​

0. TL;DR ​

1. SAM 3 能力盘点（保留作背景） ​

1.1 模型尺寸（只有一档） ​

1.2 能力（vs Grounded-SAM-2） ​

1.3 软件依赖差异 ​

2. v0.9.x 已就位（复用清单） ​

3. 架构设计要点 ​

3.1 1:1 绑定约束（env 控制 / schema 1:N） ​

3.2 Capability 协商：/setup JSON Schema 自描述 ​

3.3 Prompt-first ToolDock ​

3.4 1:N 后端管理 UI（受 env 限流） ​

3.5 不做的事（推迟到 v0.11+） ​

4. 版本切片 ​

v0.10.0 — sam3-backend 容器化（M0，~5 工作日） ✅ 2026-05-13 ​

v0.10.1 — Capability 协商基础设施（M1，~5 工作日） ✅ 2026-05-14 ​

v0.10.2 — Prompt-first ToolDock + Exemplar 入口（M2，~6 工作日） ✅ 2026-05-14 ​

v0.10.3 — 1:N 后端管理 UI + 收口（M3，~4 工作日） ✅ 2026-05-14 ​

5. 开放问题 ​

6. 风险 ​

7. 与 ROADMAP.md 的关联 ​

8. 时间预估 ​

Sources ​

v0.10.x — SAM 3 接入 + ML 工具 UI 重构

0. TL;DR

1. SAM 3 能力盘点（保留作背景）

1.1 模型尺寸（只有一档）

1.2 能力（vs Grounded-SAM-2）

1.3 软件依赖差异

2. v0.9.x 已就位（复用清单）

3. 架构设计要点

3.1 1:1 绑定约束（env 控制 / schema 1:N）

3.2 Capability 协商：`/setup` JSON Schema 自描述

3.3 Prompt-first ToolDock

3.4 1:N 后端管理 UI（受 env 限流）

3.5 不做的事（推迟到 v0.11+）

4. 版本切片

v0.10.0 — sam3-backend 容器化（M0，~5 工作日） ✅ 2026-05-13

v0.10.1 — Capability 协商基础设施（M1，~5 工作日） ✅ 2026-05-14

v0.10.2 — Prompt-first ToolDock + Exemplar 入口（M2，~6 工作日） ✅ 2026-05-14

v0.10.3 — 1:N 后端管理 UI + 收口（M3，~4 工作日） ✅ 2026-05-14

5. 开放问题

6. 风险

7. 与 ROADMAP.md 的关联

8. 时间预估

Sources