agent_ops/03.迭代规划/02.已完成阶段/04A.agent_tool_route/原始文档/03.design_review.md

04A.agent_tool_route 联合评审（三）

评审编号： 03
日期： 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、Inventory、Tool invoke、Compatibility Adapter 的条目，重点检查是否仍存在命名分叉、Inventory shape 误读或责任边界回退。
总体结论： 本轮联合评审未发现新的 Runtime / Adapter 架构冲突，04A 继续可以按 Adapter 侧补齐推进；但正式方案文档中还存在两处“历史表述与当前兼容实现并存”的误导点，需要在 04A 文档中明确消歧，否则实现者容易在协议名和 inventory shape 上走回旧分支。两项问题均已在本次评审中回填到 04A 主定义与技术实施规范：一是正式方案中的概念名 tool.invoke 需要在当前实现中统一落到 lineup.v1.tool.invoke；二是较早 client.inventory 示例未展示 tools[]，不能再被当作当前 Tool 投影的权威 shape。当前无未解决的 P0～P3 问题。

问题清单（Outline）

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

状态	优先级	编号	问题	当前结论 / 下一步
✅	P2	D04A-05	正式方案文档同时出现概念名 tool.invoke 与当前兼容信封 lineup.v1.tool.invoke，若 04A 不主动消歧，Adapter 实现、fixture 与验收可能各自使用不同名字。	已回填：04A 明确正式方案中的 tool.invoke 仅表示统一 Agent Tool 概念名；本轮实现、prompt、fixture、验收一律使用 lineup.v1.tool.invoke。
✅	P2	D04A-06	lineup-ui-surface-protocol.md 的较早 client.inventory 示例未包含 tools[]，容易让实现者误以为 04A 的独立 Tool 投影 shape 与正式方案冲突。	已回填：04A 明确 Tool 独立投影的权威来源是 Runtime 正式方案和 04.runtime_workspace；较早 Surface 协议示例只作为 Surface / Capability 最小示意，不再作为 Tool shape 权威。

已确认的一致性

04A 与 04.runtime_workspace 的 Runtime 事实保持一致

04.runtime_workspace 已冻结：Runtime 是 Tool Router、activation、lifecycle、outbox、Tool receipt / progress / final result 的唯一裁决者；Adapter 只做 inventory 绑定、顶层结构校验和 Hermes 私有交互收口。
本次复核没有发现 04A 重新把业务语义拉回 Adapter 或 lineup-app-server 的迹象。

正式方案允许当前实现继续使用 lineup.v1.* 兼容信封

app_final_design.md 已明确：当前 Tauri 实现与 golden fixture 仍使用 lineup.v1.* 类型，Runtime Compatibility Adapter 负责把旧实现映射到新 Runtime 边界。
因此 04A 以 lineup.v1.tool.invoke 作为当前 Adapter 落地，与正式方案并不冲突；真正需要避免的是在当前实现里再并行制造“裸 tool.invoke”第二种 envelope。

Tool 独立投影与较早 Surface inventory 示例不再矛盾

lineup-runtime-sdk-architecture.md 和 app_final_design.md 都已把 Inventory 收敛为同时包含 App、Tool、Surface、Capability，且 Tool 调用必须携带 inventory_revision。
lineup-ui-surface-protocol.md 中未展示 tools[] 的 client.inventory 示例，现应视作较早阶段围绕 Surface / Capability 的最小示意，而不是 04A 当前 Tool 投影的最终 JSON shape。

D04A-05：tool.invoke 概念名与 lineup.v1.tool.invoke 当前信封并存，易造成实现分叉

已解决（2026-08-07，收敛决议）。 04A.agent_tool_route.md 与 02.technical_implementation_spec.md 已补充说明：正式方案中的 tool.invoke / tool.result 若未带前缀，应按统一 Agent Tool 概念名理解；04A 代码、prompt、fixture、验收证据统一采用当前兼容信封 lineup.v1.*。

为什么这是 P2

如果不消歧，至少会出现以下风险：

实现 A：Adapter 代码使用 lineup.v1.tool.invoke
实现 B：测试夹具或 prompt 示例使用裸 tool.invoke
实现 C：验收人员按正式方案字面再补第三套命名解释

这不会推翻 Runtime 架构，但会直接影响自动化测试、联调日志、验收口径和后续迁移路径，因此需要在当前迭代关闭。

收敛决议

1. 当前实现、prompt、fixture、验收证据统一使用 lineup.v1.tool.invoke；
2. 正式方案中的 tool.invoke 只作为“统一 Agent Tool invoke”概念名引用；
3. 若未来正式迁移到去前缀的新 Runtime Envelope，必须先回写正式方案和兼容迁移计划，不能在 04A 期间并行引入第二套可执行名字。

D04A-06：较早 client.inventory 示例未展示 tools[]，容易误导 04A 的 Tool 投影判断

已解决（2026-08-07，收敛决议）。 04A.agent_tool_route.md 与 02.technical_implementation_spec.md 已明确：tools[] 顶层投影的权威来源是 Runtime 正式方案与 04.runtime_workspace 已冻结实现；lineup-ui-surface-protocol.md 中较早示例不再作为 Tool shape 权威。

为什么这是 P2

当前正式方案文档内部其实存在时间差：

• Runtime 架构和最终方案已经收敛到 “Inventory 同时包含 App、Tool、Surface、Capability”；
• 较早 Surface 协议示例仍只展示了 standard_components + applications + capabilities。

如果不明确权威顺序，后续实现者很容易错误得出以下结论：

04A 新增 tools[] = 偏离正式方案

这会直接干扰 Adapter parser、测试夹具、评审判断和后续 Runtime 文档演进。

收敛决议

1. 04A 当前以独立 tools[] 顶层投影为准；
2. applications[] 继续只表达 App / Surface 可见性；
3. 若后续要统一正式方案中的 inventory 示例，应在正式方案文档中统一回填，而不是让 04A 回退到 applications[].tools 或无 tools[] 的旧分支。

评审关闭条件

1. D04A-05 与 D04A-06 已回填 04A.agent_tool_route.md 和 02.technical_implementation_spec.md；
2. 后续代码实现、测试夹具和验收记录必须统一使用 lineup.v1.* 当前兼容信封；
3. 后续若补正式方案文档示例，应把 client.inventory 的 Tool 顶层投影同步回填到正式方案，而不是在 04A 再引入本地例外；
4. 本评审当前无未解决的 P0～P3。