[DECIDE] 固化全来源工具的 registry-derived inventory 与稳定 identity #731

Parents

• [REQ-125] 会话页整页呈现 Alpha 自持体验并抗上游布局漂移 #538（REQ-125，消费方：工具卡展示）
• [REQ-131] 用户可按来源和工具控制模型可调用能力 #723（REQ-131，消费方：用户工具策略）

Decision already made

owner 裁决（2026-07-31）：稳定工具 identity 单独一张 DECIDE，只定一次；展示方案
留在 REQ-125（#722），策略方案留在 REQ-131（#724），两者消费本票产物，不各自
重新定义 identity。

理由：identity 是展示与策略共用的地基。两张 DECIDE 各定一次 = 两份可漂移映射，
正是本 portfolio 明令禁止的形态。

Decision needed

为下列全部工具来源建立一个 registry-derived inventory 与一条稳定 identity：

• 本地内置工具
• Alpha Cloud MCP 工具
• 第三方 MCP 工具
• 插件动态工具

identity 必须由 source / server / remote-tool 事实派生，不得使用展示标题、翻译、
图标、或模型侧拼接别名。

Ground truth that must be honored

• 模型别名今天不是一一映射。 McpCatalog.toolName = sanitize(server)+"_"+sanitize(name)，
  非法字符统一替换为下划线，而下划线本身在允许集内
  （packages/opencode/src/mcp/catalog.ts:117-119）⇒ 同 server（foo.bar vs foo_bar）
  与跨 server 均可碰撞。两处消费点按该别名写入 Record 且静默覆盖：
  packages/opencode/src/mcp/index.ts:684、packages/opencode/src/tool/code-mode.ts:120。
  Code Mode 还会反向拆解已折叠的别名来还原 server/tool
  （code-mode.ts:39-56），无碰撞时也可能拆错。已由 alpha-code#726 单独 fail-closed。
• 权限引擎与目录过滤钩子已经存在，identity 方案必须落在它们之上而不是另起一套：
  三态 allow|ask|deny + wildcard + 合并优先级（packages/opencode/src/permission/index.ts:84-94）；
  config 已接受任意工具名 key（packages/core/src/v1/config/permission.ts:18-36）；
  模型目录过滤钩子在 packages/opencode/src/session/llm/request.ts:208-214；
  V2 同构 packages/core/src/tool/registry.ts:112-113,132-135。
• 内置工具今天不按工具 ID 键控，而是硬编码权限串，且 Permission.disabled 把
  edit|write|apply_patch 折叠成一个单位、把三个 MCP-resource 工具折进 read
  （permission/index.ts:286-296）⇒ "只禁用其中一个"当前不可表达。identity 方案要
  说明这一层怎么处理。
• 执行咽喉不止一个：session/tools.ts:99-133（内置/插件）、:140-385（三个
  MCP-resource 工具各自 execute）、:390-490（MCP）、tool/code-mode.ts:134-186、
  session/llm.ts:130-146（workflow executor）。identity 必须在每一处都能解析到同一
  对象。
• 插件动态工具没有 ask：tool/registry.ts:120-176 把 ctx.ask 透传给插件却自己
  不调，今天只有整工具开/关。
• packages/opencode 在 north-star 守卫的 UPSTREAM_PATHS 内，方案必须说明哪些
  改动落在 alpha 自有表面、哪些需要收编 ADR。

Explicitly out of scope（到不了的状态，不要纳入）

provider-hosted / provider-executed 工具：alpha 侧没有任何地方启用它们
（packages/llm/src/schema/messages.ts:224-232 的 ToolDefinition 无 provider 变体；
protocols/anthropic-messages.ts:514-522、protocols/openai-responses.ts:484-489 只
下发 function tool），只有入站解码存在。"provider 工具的策略必须在构造模型请求前生效"
当前没有可达状态。要不要支持 provider 工具是一张产品票，不是本票的 identity 问题。

Result

在 alpha-code docs/design/ 落 commit-pinned identity baseline：inventory 来源、
identity 构成与反解规则、碰撞处置、与既有 permission/目录过滤钩子的衔接、跨五条执行
路径的解析一致性、以及 alpha 自有 vs 上游表面的边界。

Consumers

• alpha-code#722 —— 展示方案（REQ-125）：卡片字段 allowlist/redactor、不可变来源快照。
• alpha-code#724 —— 策略方案（REQ-131）：三态、作用域、默认值、Settings。

两票各自引用本票产物，不重新定义 identity。

Out of scope

• 展示视觉与 Settings 形态。
• alpha-code#726 的别名碰撞 fail-closed 实现（它是本票的前置修复，不是本票产物）。
• Cloud web-search 既有 ID 漂移（alpha-code#650）。