agent_ops/03.迭代规划/03.进行中与待实施阶段/04A.agent_tool_route/原始文档/02.design_review.md

04A.agent_tool_route 设计评审（二）

评审编号： 02
日期： 2026-08-07
评审对象： 04A.agent_tool_route.md（实施权威）、02.technical_implementation_spec.md、04.runtime_workspace.md、05.technical_implementation_spec.md、运行时与智能体工具.md、lineup-runtime-sdk-architecture.md、app_final_design.md、lineup-ui-surface-protocol.md。
评审方法： 以 04A 主定义与实施规范为当前候选方案，联合对照 04.runtime_workspace 已冻结的实现边界，以及 02.正式方案 中 Runtime / Tool / Inventory / Surface 的正式契约，重点检查协议命名、Inventory 结构、Tool 回程语义与分层责任是否一致。
总体结论： 联合评审确认 04A 的方向正确，仍然是 Adapter 层补齐而不是重写 Runtime；但原稿中有两处会和正式方案产生实现分叉的 P1 冲突：其一，把 Agent Tool 绑定到 client.inventory.payload.applications[].tools，与正式方案“Inventory 同时包含 App、Tool、Surface、Capability，且 Tool 是独立投影”的方向不一致；其二，新增 lineup.v1.miniapp.tool.call，会把正式方案中的统一 Agent Tool 模型拆成第二套 MiniApp 私有调用协议。两项问题均已在本次评审中回填：04A 现改为消费独立 Tool inventory 投影，并以 lineup.v1.tool.invoke 作为正式方案统一 Agent Tool invoke 的当前版本化落地；标准交互兼容入口 lineup.v1.tool.call(choice | confirm | input) 继续保留，但不再承担 Runtime Agent Tool invoke 语义。当前无未解决的 P0～P3 问题，04A 可以继续进入实现或验收准备。

问题清单（Outline）

状态标记：🔴 未解决，必须处理；🟡 已提出修复方向，尚未确认或未回填实施权威；✅ 已解决；⚪ 可延期但必须保留记录。P0～P3 必须在当前迭代处理；P4～P5 可以延期，但必须记录延期原因和重新评估条件。

状态	优先级	编号	问题	当前结论 / 下一步
✅	P1	D04A-03	04A 原稿把 MiniApp Tool 绑定到 client.inventory.payload.applications[].tools，与正式方案中 Inventory 的 App / Tool / Surface / Capability 独立边界不一致。	已确认并回填：applications 继续只表达 App / Surface 可见性；Agent Tool 改为独立 Tool 投影进入 inventory，Hermes Adapter 只消费该最小 Tool 投影。
✅	P1	D04A-04	04A 原稿新增 lineup.v1.miniapp.tool.call，会把正式方案中的统一 Agent Tool 模型拆成第二套 MiniApp 私有调用协议。	已确认并回填：不再引入 miniapp.tool.call；本轮以 lineup.v1.tool.invoke 作为正式方案统一 Agent Tool invoke 的版本化落地。lineup.v1.tool.call 继续仅作为 Interact 标准交互兼容入口。

已确认的一致性

04A 继续服从 04.runtime_workspace 已冻结的 Tool / Runtime 边界

04.runtime_workspace 和其技术实施规范已经冻结：Pomodoro 的 pomodoro.start / pomodoro.interrupt 都是 Runtime 发布给 Agent 的统一 Agent Tool；Runtime 负责 Tool Router、activation、foreground gating、operation 终态和 outbox；MiniApp 只声明 Tool、接收投影、写自己的 session data。
本次联合评审确认，04A 不应重新发明第二套 MiniApp Tool 平面，而应只补 Hermes 如何理解和调用这套已存在的 Runtime Tool 模型。

标准交互与 Agent Tool 仍是两条不同的协议语义

03.sdk_and_coreapp 已经把 lineup.v1.tool.call(choice | confirm | input) 冻结为 Interact 的标准交互兼容入口。
正式方案中的 Agent Tool invoke 则是 Runtime 面向 Agent 的统一工具调用模型。两者都可复用 call_id、receipt、result 等概念，但不能混成同一种“Tool Call”来让实现自行猜测。

lineup-app-server 仍不需要进入本轮语义改造

本次联合评审没有发现必须让 lineup-app-server Go 服务理解 Hermes 私有协议、Inventory Tool 投影或 Tool invoke 语义的证据。
因此，04A 仍然应把改动集中在 Hermes Adapter、Prompt 约束、协议校验与测试证据，不扩大到传输层。

D04A-03：Inventory 把 Tool 塞进 applications[].tools 与正式方案冲突

已解决（2026-08-07，收敛决议）。 04A.agent_tool_route.md 与 02.technical_implementation_spec.md 已回填：Hermes Adapter 不再把 Agent Tool 绑定到 applications[].tools；Inventory 中的 applications 继续只表达 App / Surface 可见性，Tool 改为独立顶层投影发布。

为什么这是 P1

正式方案已经给出清晰方向：

• lineup-ui-surface-protocol.md 当前把 applications 定义为“已启用 app 的 surface 可见性”，不含 Tool；
• lineup-runtime-sdk-architecture.md 与 app_final_design.md 明确 Runtime Inventory 同时包含 App、Tool、Surface 与 Capability；
• 04.runtime_workspace/05.technical_implementation_spec.md 则已经把 Tool 作为从 Registry 独立投影到 Runtime Tool Registry / Agent Inventory 的对象。

如果 04A 继续把 Tool 内嵌进 applications[].tools，就会产生三种实现分叉：

实现 A：Hermes Adapter 按 applications[].tools 解析
  -> 与正式方案中的独立 Tool Inventory 不一致。

实现 B：Runtime 继续按独立 Tool Registry / Inventory 发布
  -> Hermes Adapter 看不到 Tool，退回 revision=none。

实现 C：为适配 Hermes 再改 Runtime Inventory shape
  -> 会反向破坏 04.runtime_workspace 已冻结的 Registry / Tool Router 方向。

这属于会直接导致模块间协议不兼容的 P1。

收敛决议

本轮已确认：

1. applications 继续只承载 App / Surface 可见性；
2. Agent Tool 改为独立 Tool 投影进入 inventory；
3. Hermes Adapter 只保存规划与出站校验所需的最小 Tool 投影；
4. 04A 不要求修改 04.runtime_workspace 已冻结的 Runtime Tool Registry / Agent Inventory 方向。

该结论已回填 04A.agent_tool_route.md 与 02.technical_implementation_spec.md。

D04A-04：miniapp.tool.call 会把统一 Agent Tool 平面拆成两套协议

已解决（2026-08-07，收敛决议）。 04A 主定义与实施规范已回填：不再引入 lineup.v1.miniapp.tool.call，而是以 lineup.v1.tool.invoke 作为正式方案统一 Agent Tool invoke 的当前版本化落地；lineup.v1.tool.call(choice | confirm | input) 继续只承载标准交互兼容入口。

为什么这是 P1

正式方案和 04.runtime_workspace 一直在强调同一个事实：

• Agent Tool 是 Runtime 面向远端 Agent 的统一调用模型；
• Tool invoke、receipt、progress、result、activation_ready 等都属于这条统一调用链；
• choice / confirm / input 是 Interact 标准交互原语，不等于 MiniApp 业务 Tool。

如果 04A 为 MiniApp Tool 新增 lineup.v1.miniapp.tool.call，就会把“统一 Agent Tool”拆成以下两套协议：

一套：标准交互兼容入口 lineup.v1.tool.call
一套：MiniApp 业务 Tool lineup.v1.miniapp.tool.call

这样会直接带来三类分叉风险：

1. Hermes Adapter、Runtime、验收脚本要同时维护两套 Agent Tool 调用语义；
2. 04.runtime_workspace 已冻结的 Tool receipt / progress / result 语义会被误解成“只对 miniapp.tool.call 生效”；
3. 后续非 MiniApp 但仍属于 Runtime Agent Tool 的能力，会不知道该走哪条调用协议。

这同样属于必须在实现前冻结的 P1。

收敛决议

本轮已确认：

1. 不再新增 lineup.v1.miniapp.tool.call；
2. Runtime Agent Tool 统一走 lineup.v1.tool.invoke；
3. lineup.v1.tool.call(choice | confirm | input) 继续只作为 03.sdk_and_coreapp 遗留兼容入口；
4. tool.invoke 的 receipts / progress / final result 继续完全复用 04.runtime_workspace 已冻结的 Agent Tool 回程语义。

这等价于把正式方案中的统一 Agent Tool invoke 模型，在 Adapter 当前实现中落成一个版本化 envelope，而不是再分出一条 MiniApp 私有通路。

评审关闭条件

1. D04A-03 与 D04A-04 已回填 04A.agent_tool_route.md 与 02.technical_implementation_spec.md；
2. 后续实现必须同步更新 Hermes Adapter 的协议常量、Prompt 文案、inventory parser 与测试夹具，避免代码层仍遗留 applications[].tools 或 miniapp.tool.call；
3. 若后续需要修改正式方案中的 Inventory JSON shape 或 Agent Tool invoke 命名，应先回写 02.正式方案，而不是在迭代文档中继续引入第三套局部协议；
4. 本评审未发现需要延期保留的 P4 / P5 事项；当前无未解决 P0～P3。