[REQ-131][CODE] 设置页新增「工具」节:按来源、服务、单个工具设置停用/询问/允许

[jinjunnn]

工具权限的规则在引擎里已经能生效,但你在应用里找不到地方去设置它。这张票要在设置里加一节「工具」,按本机、Alpha 云端、第三方服务、插件分组列出 AI 能用的每个工具,让你逐个选「停用 / 每次询问 / 允许」,并显示它当前为什么是这个状态。界面稿已经批准。还差一步没摸清:设置界面要从 AI 引擎那边拿到实时的工具清单,传过来的路子要先实地查清楚再定。不做的话,工具权限只能改配置文件来设,对你等于不可用。

Parent

• [REQ-131] 用户可按来源和工具控制模型可调用能力 #723(REQ-131)

方案基线

jinjunnn/alpha-code#724 的 CLOSE_DECIDE §9 第 3 条 + §8 Settings 终局形态。本票正文逐字取自该基线,未新增任何 AC 或准入条件。

依赖

jinjunnn/alpha-code#1128(CODE#1)先落地 —— 本票只消费它提供的 policy inventory/API。

负责(基线原文)

main / preload / renderer Settings、registry-derived grouping、继承 / effective reason、新工具 / rebind、保存与恢复、a11y。

边界(基线原文)

只消费 policy inventory/API;不建第二 identity / UI auth map。

退出条件(基线原文)

Settings 行为 / 视觉基线与交互窄测完成;bin/check 绿。

基线 §8 的终局形态

Settings 从同一 live inventory 分组为「本地 / Alpha Cloud / 第三方 MCP / Plugins」,service 可展开到 tool。

⚠️ 基线 §1 点名:产品的「四类」必须把用户可调用的 host / builtin-v2 映射进「本地工具」,不能当作不存在(host 现含 Code Mode facade、三个 MCP-resource 伪工具、StructuredOutput;builtin-v2 由 core/src/tool/application-tools.ts:45-55 与 core/src/tool/registry.ts:86-109 铸造)。

不进 Settings 的两个窄例外(基线 §2):host::StructuredOutput(用户请求 JSON-schema 响应时的内部必需协议工具,强制 enabled)与 _noop(session/llm/request.ts:165-180,Copilot 历史回放兼容 sentinel)。二者须以无外部副作用的窄测试锁死。

基线 §8 另注:键盘、读屏、light/dark 与保存失败恢复由本票自己验收;工具卡只呈现实际调用结果,不承担授权判决。

⚠️ 含 UI ⇒ 升 Ready 前先过设计稿门

本票有 renderer Settings 面。按 requirement-management:设计稿批准 = 升 Ready 的门。动手前先走 design-loop(读目标仓 docs/design/README.md 定落点、过勘破门、只出该组件的增量帧),已批稿即 UI 类判据的验收基线。

Out of scope(基线 §10)

展示标题 / 图标 / 卡片 / redactor / 历史回放归 REQ-125(#722 / #879);三态、作用域、持久化、Settings 控制与 catalog/executor 双闸归 REQ-131。不反向消费卡片字段。

复杂度

M(新 UI 结构 + 跨 main/preload/renderer,但只消费既有 API)。

[jinjunnn]

设计稿已批准 —— 本票的 Ready 门已开(2026-08-26)

docs/design/2026-08-25-req131-settings-tool-policy/ status: draft → approved(PR #1145,已合 43c6a0175)。
按 design-loop,已批稿即本票 UI 类 AC 的验收基线。

批准时确认的地面真相变化

#1128 与 #1129 均已合并关闭 ⇒ 设计稿 §3 表里原标「契约,#1129 在途」的三行
(live inventory、「新发现」徽标、无法核验注册的枚举)都已落地,本稿不再有悬空依赖。

§7 两个小裁决(已裁,均在稿内既定范围,不新增 AC)

• Q1 无法核验的注册要不要枚举 → 暴露计数 + 开发者详情内给原因。
  两种失败里,「工具静默消失、用户无从解释」比多一行只读提示贵得多。计数放服务展开区末尾的
  只读提示,原因归开发者详情(沿用 REQ-125「开发者详情默认折叠」的既有裁决),正文不因此变吵。
• Q2 导航命名 → 用「工具」。 「权限」已被通知区现有开关占用,复用会把「这里改了 = 永久」
  与会话内 once/always 两种心智混在一起,而稿子 §4 刚花力气把它们分开。

裁决全文写在设计稿新增的 §8「批准记录」里,票面不重复。

落地要求(来自稿子本身,不是新增)

帧并入 docs/design/current/settings/design.html 的 #set-tools 锚,并新建
docs/design/current/settings/components.md 台账;稿子 §1 记的那条已知漂移
(活稿设置节仍是「仅 通用 + 快捷键」,现役已有第三项「扩展存储」)照旧不在本票修,记进台账即可。

已派 lane。

[jinjunnn]

回 Blocked(2026-08-26)—— 依赖 #1129 补齐,不是没人做

派出去的 lane 在写任何代码之前停下并回报了,这是对的:已批设计稿 §8 里那句
「本稿不再有悬空依赖」是我写错的(只看 #1129 issue 状态为 CLOSED 就下,没读交付物
PR #1135 正文,而它恰好声明了相反的事)。

卡在哪(实读,两条独立检索轴交叉一致)

ToolPolicy 面只有 packages/schema/src/alpha-tool-policy.ts +
packages/opencode/src/permission/alpha-tool-policy{,-store}.ts 三个文件 ——
零 server route · 零 SDK 投影 · 零 preload/main IPC · 零 renderer 消费者;
AlphaToolPolicy 模块外零引用(对照 Permission.node 有 7 处装配点);
执行咽喉 session/tools.ts:86/:128 读的是 Permission.merge(agent.permission, session.permission)
这条 ruleset 轴,不是本票要写的策略文档轴。

⇒ 本票 setRecord 写下的 disabled/ask,目录与执行面今天读不到。
照稿实现 = 面板显示「已停用」而模型照调,正是 #1121 在 Settings 层原样复活。

解除条件(单一,可机器判定)

#1129 关闭(已 reopen,补两件:①票面点名的 dynamic inventory/API;
②策略文档轴如何抵达咽喉)。届时本票的「只消费既有 API」前提才成立。

本票的复杂度要重估

原定 M,前提是「只消费既有 API」——该前提为假。缺口归 #1129 之后,
本票回到 M 是合理的;若最终决定把缺口并进本票,必须重定级为 L 并重走方案基线门。
两条路都合法,但不能一边留着 M 一边做 L 的量。

已批设计稿仍然有效

status: approved 保留 —— 批的是视觉与交互规范(9 型 reason 文案、六个状态帧、
「收紧畅通放宽有闸」、三态控件与徽标/原因三者可不一致),那部分不受影响。
更正记在设计稿 §9(PR #1146)。

[jinjunnn]

Blocked — Owner action, review 2026-09-02.

依赖 ac#1129 补齐 inventory/API 与文档轴接咽喉

[jinjunnn]

#1129 已合(PR #1147)—— 本票的缺口关掉了两件,还剩一跳

ac#1129 交付了:

• dynamic inventory/API:packages/schema/src/alpha-tool-inventory.ts(wire 形状,renderer 可 import)
  • packages/opencode/src/permission/alpha-tool-inventory.ts(AlphaToolInventory.Service.list(),从 live registry 派生);
• 策略文档轴抵达咽喉:permission/alpha-tool-policy-gate.ts,E1–E6 逐个落点,executor 调用时重读。

我独立复核过:门全绿,ui-mac 4506/313/0 与 base 逐字相同;opencode 全量的 13 条红逐条归因为
「base 同样红」或「并发跑门的测量污染」(串行复跑转绿,base 在同一时刻同样红),零回归。

还剩的一跳:引擎 inventory → main/preload/renderer 的传输

AlphaToolInventory.Service.list() 住在引擎(sidecar)进程里。本票的边界是
「只消费 policy inventory/API;不建第二 identity/UI auth map」(基线 §9 CODE#3)——
所以 main 侧不能自己重算一份 inventory,必须从引擎取。

而引擎的 HTTP 注册点是单点:packages/opencode/src/server/routes/instance/httpapi/api.ts
—— 每个 route group 都在那里 import 并注册(实读:ConfigApi/ControlApi/…/PermissionApi 共 20 个)。
它是上游文件,且不在 ADR-033 收编名单里。

⚠️ 注意别被 ADR-043 误导:结构性谓词允许新增的 alpha-* 文件住在 UPSTREAM_PATHS 内,
所以写一个 groups/alpha-tool-inventory.ts 本身不撞门 —— 撞门的是注册它要改 api.ts。

三条候选路线(实读得出,不是推断;供裁决)

路线	要动什么	代价
A. 收编 httpapi/api.ts	ADR-033 名单加一条 + 自己的 ADR	最直接;但 api.ts 是上游高频文件,收编后每次 sync 都要合
B. 挂进已收编的 permission 面	名单里已有 packages/protocol/src/groups/permission.ts 与 packages/server/src/handlers/permission.ts	有先例、面相关(inventory 本就是策略面);需确认 httpapi/groups/permission.ts 是否也必须动
C. main 侧另辟通道	不碰上游	但 main 拿不到引擎的 live registry —— 要么重算(违反本票边界),要么仍需引擎侧出口。大概率是伪选项

我的判断:B 值得先勘破(已有收编先例 + 语义同面),A 是保底,C 多半不成立。
但「扩 ADR-033 白名单」按本 portfolio 的规矩是 owner 级 —— 所以这一跳先递上去,不由我自行扩。

本票状态

保持 Blocked(依赖这一跳)。解除条件已从「#1129 关闭」变成
「传输路线裁决 + 落地」。已批设计稿(status: approved)与 §9 更正不受影响,
视觉/交互/9 型文案/六帧仍是验收基线。