[REQ-131][CODE] MCP 工具别名碰撞时禁止静默覆盖

[jinjunnn]

Parent

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

Problem

MCP 工具模型别名不是一一映射：当前 McpCatalog.toolName 会把不允许的字符统一替换为下划线，因此同一或不同 server 中的远端名称可能归一化为同一个模型工具名。例如 foo.bar 与 foo_bar 会碰撞；普通 MCP materialization 和 Code Mode 都会写入以该别名为 key 的 Record，后写入者静默覆盖先写入者。

这会让模型看到的工具、用户策略命中的稳定 identity 和最终执行对象发生错位，属于 fail-open 的能力路由缺陷。

Covers

• REQ-131 AC1、AC2、AC3、AC6。

Ground-truth evidence

• packages/opencode/src/mcp/catalog.ts:117-119：非法字符归一化为下划线。
• packages/opencode/src/mcp/index.ts:666-685：按模型别名写入普通 MCP tool record。
• packages/opencode/src/tool/code-mode.ts:120：Code Mode 存在相同的 key 覆盖形态。

Required behavior

• 模型可见别名与 source/server/remote-tool 稳定 identity 保持可验证的一一映射。
• 在批准可逆唯一别名方案前，任何碰撞必须在工具提供给模型或执行前 fail closed；禁止静默覆盖。
• 普通 MCP、V1/V2 registry materialization 与 Code Mode 使用同一碰撞不变量。
• permission、用户三态策略、计费/风险元数据和最终执行均绑定稳定 identity，不能因别名碰撞指向另一工具。

Verification

• 同 server：foo.bar 与 foo_bar。
• 跨 server：不同 canonical server identity 产生相同模型别名。
• server rename/rebind、动态删除/重加及缓存 catalog。
• 普通 MCP 与 Code Mode 均证明无静默覆盖；恢复旧 overwrite 行为时命名测试变红。
• 未能唯一反解的模型别名必须响亮拒绝，且不会触发网络、副作用或费用。

Boundary

MCP catalog/identity、模型工具 materialization、Code Mode 适配与确定性测试；同步更新受影响的 canonical contract/design 文档。

Out of scope

• 工具卡视觉与标题（[REQ-125][DECIDE] 消费稳定 identity，固化全来源工具卡展示方案 #722）。
• Cloud web-search 的已知字面量 ID 漂移（[REQ-223][CODE] 云 web-search 闸改按真实引擎 id 命中 —— 现在盯的 cloud_web_search 引擎从不注册 #650）。
• REQ-131 的完整 Settings/三态策略实现（[REQ-131][DECIDE] 消费稳定 identity，固化全工具三态策略与作用域 #724 批准后另切 CODE）。

[jinjunnn]

实现受阻:三个落点全在 north-star 守卫内,且无收编 ADR —— 未动代码

按票面开工前先跑守卫勘破。结论:本票的修复面 100% 落在 UPSTREAM_PATHS 内、且一个都没被 exclude,按 [[ADR-029]] 不能直接改。故本次未产 PR、未改任何生产文件,把勘破结论与最小可行方案交回。

1. 守卫事实(已实跑,非推断)

packages/opencode 在 UPSTREAM_PATHS 内(alpha-ci.yml:44、scripts/alpha-check.sh:25)。把三个落点各加一行注释后跑真的 scripts/alpha-check.sh:

▶ [1/3] north-star guard (zero upstream edits)
    ✗ upstream files modified/deleted/renamed (fork-sync would conflict):
      packages/opencode/src/mcp/catalog.ts
      packages/opencode/src/mcp/index.ts
      packages/opencode/src/tool/code-mode.ts

现有 exclude 清单里没有这三个文件。而且 [[ADR-035]] 是明文刻意不收编:

云路径的 catalog.ts / code-mode.ts 已 loud,刻意不收编。

alpha-ci.yml:118 与守卫报错文案同口径:「新增收编须自己的 ADR,不得静默加 exclude」。ADR-029 §2 另立明文:不存在 L4「直接编辑同步中的文件」,永不设立。

附带记一个本机验证陷阱:守卫谓词在 zsh 里手抄会假绿 —— zsh 对未加引号的 $UPSTREAM_PATHS 不做分词,pathspec 塌成一个参数、匹配不到任何文件。alpha-check.sh 是 #!/usr/bin/env bash 故本身正确。手抄复现务必用 bash。

2. 票面三条 ground-truth 全部复现(跑的是真模块)

行号与票面逐条一致:catalog.ts:117/119、index.ts:666/684、code-mode.ts:120/124。

真跑 McpCatalog.toolName:

sanitize('foo.bar') = "foo_bar"
sanitize('foo_bar') = "foo_bar"
'_' survives sanitize (it is inside the allowed set) = true

同 server:  [COLLISION] alias="srv_foo_bar"  <- "srv"+"foo.bar" / "srv"+"foo_bar"
跨 server:  [COLLISION] alias="a_b_x"        <- "a.b"+"x"       / "a_b"+"x"
边界歧义:  [COLLISION] alias="foo_bar_baz"  <- "foo"+"bar_baz" / "foo_bar"+"baz"

alias "foo_bar_baz" 的候选 (server, remote) 反解: 2 组 —— 结构性不可逆

3. 顺带勘破出一个票面没写的独立缺陷(建议纳入同一 ADR 射程)

code-mode.ts:39-56 的 groupByServer 用「最长 server 名前缀」把扁平别名再切回 (server, local)。这是第二次有损变换,即使别名零碰撞也会错。用真的 describeCatalog 跑(两个别名互不碰撞):

输入:server foo 提供远端工具 bar_baz;server foo_bar 提供 other。
真实输出:

- foo_bar (2 tools)
  - tools.foo_bar.baz(input: {}): Promise<unknown>    // remote tool bar_baz
  - tools.foo_bar.other(input: {}): Promise<unknown>  // remote tool other

即:server foo 从目录里整个消失,它的工具被挂到 foo_bar 名下,模型被告知用 tools.foo_bar.baz 调用。第零问(走我们自己的路径到得了吗)= 到得了:两个普通 MCP server 叫 foo 与 foo_bar 而已,无需裸 SQL、无需特殊部署形态。

这条决定了修复面:只在 MCP.tools() 立闸堵不住它,因为 Record<alias, McpTool> 丢掉了 (server, remote) 对。故 AC「Code Mode 与普通 MCP 同一不变量」结构上要求 code-mode.ts 也在射程内。

4. 低级别不可行的勘探证据(ADR-029 §3 要求的那份)

• L0 插件接缝 —— 结构上不可行。 按两条独立轴枚举(packages/plugin/src/index.ts 的 Hooks 接口 + 引擎里真实的 .trigger("...") 调用点)得到的全部工具相关钩子只有:tool.definition(入参 {toolID},只能改 description/parameters)、tool.execute.before/after(入参 {tool: string})。没有任何钩子拿得到「提供给模型之前的工具清单」,也没有任何钩子能拒绝一个工具;且它们收到的 tool 已经是碰撞后的别名,反解不出是哪个远端工具 —— 既晚于 AC 要求的时点,又已丢失判据。
• L0 层装饰 —— 落点在上游。 MCP.node 的组装点是 packages/opencode/src/effect/app-runtime.ts:94 与 .../httpapi/server.ts:250,两个都是上游文件;alpha 侧没有任何地方组装该 layer。即便装饰了,tools() 的输出已是碰撞后结果,被覆盖的那一条已经消失、无法从输出侧察觉。
• 靠 instructions() 兜底 —— 前提为假。 storeClient(index.ts:583-585)只在 server 真的给了 instructions 时才写 s.instructions[name],否则 delete。故无 instructions 的 server 在该表里根本不出现 ⇒ 据此立闸 = 又一个前提为假的闸门。
• 重新 list 一遍 —— 违背 AC。 从 alpha 侧调 McpCatalog.defs(client) 自行重列,是每次 materialization 一次额外网络往返、与缓存 s.defs 存在竞态,且与票面「不触发网络/副作用/费用」相抵。

一条确实可用的好消息:守卫是 --diff-filter=DMR,新增文件不触发(已实测:在 packages/opencode/test/ 下新增文件后谓词为空)。既有先例 packages/opencode/test/tool/alpha-mcp-websearch-gate.test.ts 就是这么落的。⇒ 本票的确定性测试可以全部落在 alpha 自有新文件里,零守卫成本;卡住的只有生产改动。

5. 最小可行方案(按 ADR-029 阶梯,请主 session / owner 裁决)

咽喉点是 MCP.tools()(index.ts:666-686)—— 三个消费者(tool/registry.ts:281 describeCodeMode、session/tools.ts:390 materialization、tool/code-mode.ts:210)全部经它,在此立闸即天然满足 AC「同一不变量」。

方案	射程	代价
A(建议)L2 补丁层	同 B 的三文件,但磁盘保持上游原样、构建时机械施加、施加失败 loud-fail	冲突数仍为 0、保留上游白嫖;代价是多一台 patch 机器 + 上游漂移时要修 patch
B. L3 冻结接管	mcp/catalog.ts(别名函数)+ mcp/index.ts(tools() 建 Record 处)+ tool/code-mode.ts(groupByServer/toolTree)	单向门:放弃这三处的上游白嫖。MCP 是高 churn 面,比 ADR-035 的 websearch 叶子贵得多

射程还可再压:code-mode.ts 其实不需要前缀猜测 —— McpTool 自带 def.name(远端名)与 client,拿 client 对 mcp.clients() 反查即可精确还原 (server, local),不必手写别人的文法。这能把 code-mode 的改动压到 groupByServer 一个函数内。

倾向 A:MCP catalog 是高 churn 区,L3 的「放弃白嫖」代价在这里明显偏贵,而本修复是行为闸而非大面积重写,适合 patch 承载。无论 A 还是 B,都需要一条自己的 ADR(ADR-029 §3:载明触发需求、级别选择理由、守卫/tripwire 形态、回退方案、(L3)放弃白嫖范围)。

6. 我主动没做的事

• 没改任何生产文件,没加 exclude,没碰 alpha-ci.yml / alpha-check.sh —— 静默加 exclude 正是守卫文案点名禁止的。
• 没写 ADR —— 级别选择是 owner 的单向门决策,不是实现方顺手决定的。
• 没写「钉住当前错误行为」的表征测试 —— 那会把缺陷固化成契约,且本票要的是 fail-closed。
• 没碰 #722 / #650 的 out-of-scope 面。
• 用完即清:worktree 与分支已删,主 checkout 未动(另有 session 正占用,进去前已 git status 确认)。