8.3 KiB
04A.agent_tool_route 设计评审（一）
评审编号： 01
日期： 2026-08-07
评审对象： 04A.agent_tool_route.md（实施权威）、04.runtime_workspace.md、05.technical_implementation_spec.md、运行时与智能体工具.md、lineup-runtime-sdk-architecture.md。
评审方法： 独立以 04A.agent_tool_route.md 作为唯一实施权威，核对它与 04.runtime_workspace 已冻结的 Tool 调用 / 回程语义是否一致，并检查 Hermes Adapter 新增边界是否足以让协议、实现与验收得到唯一结论。
总体结论： 04A 已成功收敛为 Adapter 层的两个核心目标：一是补齐 applications[].tools 到 lineup.v1.miniapp.tool.call 的 MiniApp Tool 通路，二是把 Hermes 内置审批 / 澄清 / 更新提示等交互收口到 LineUp 协议。评审中确认了两个必须冻结的边界：miniapp.tool.call 不新增第二套专用 result 协议，而是继续复用既有 Agent Tool 回程语义；Hermes clarify 在本轮仅兼容单选、other -> input 和纯文本，multi_select 稳定拒绝。上述决议已回填实施权威，当前无未解决的 P0～P3 问题，设计可进入技术实施规范阶段。
问题清单（Outline）
状态标记：🔴 未解决，必须处理；🟡 已提出修复方向，尚未确认或未回填实施权威；✅ 已解决；⚪ 可延期但必须保留记录。P0～P3 必须在当前迭代处理；P4～P5 可以延期，但必须记录延期原因和重新评估条件。
| 状态 | 优先级 | 编号 | 问题 | 当前结论 / 下一步 |
|---|---|---|---|---|
| ✅ | P1 | D04A-01 | lineup.v1.miniapp.tool.call 已新增请求信封，但主定义未明确它的协议回执、进度和最终业务结果是否复用既有 Agent Tool 回程语义。 |
已确认并回填：不新增 lineup.v1.miniapp.tool.result；miniapp.tool.call 的 receipts / progress / final result 全部继续复用 04.runtime_workspace 已冻结的 Agent Tool 回程语义，并始终以同一 call_id 关联。 |
| ✅ | P2 | D04A-02 | Hermes clarify 已纳入兼容范围，但未说明 multi_select = true 的处理规则，存在实现静默降级或行为分叉风险。 |
已确认并回填：04A 只兼容单选、other -> input 和纯文本澄清；multi_select = true 稳定拒绝，不静默降级成单选或自由文本。 |
已确认的一致性
04A 是 Adapter 补齐，不是重写 Runtime
主定义已经把边界写清：04.runtime_workspace 继续是 Runtime、Lifecycle、Inventory revision、Tool schema 与 Pomodoro 裁决语义的权威；04A 只补齐 Agent / Adapter 如何消费这些事实、如何发起合法调用、以及如何把 Hermes 私有交互收口到 LineUp 协议。
这意味着本轮不应在 Runtime 中新增 Hermes 特判，也不应为 miniapp.tool.call 重新发明一套业务状态机。
lineup-app-server 继续是透明传输层
主定义将 lineup-app-server 明确排除在本轮核心改造范围之外，这与当前代码角色一致：服务端负责消息收发与传输，不承担 lineup.v1 业务语义解析。
因此，本轮实现责任应集中在 Hermes Adapter、Prompt 约束、协议规范化与测试证据，不应让实施误入 Go 服务端语义改造。
Hermes 的平台私有交互兼容责任位于 Adapter 层
主定义已经吸收了飞书模式的关键点：不是让模型生成平台私有协议，也不是让 Runtime 理解 Hermes 私有 prompt kind，而是由 Adapter 把 Hermes 内部审批 / 澄清 / 更新提示转换成 LineUp 标准交互，再把用户回传 resolve 回 Hermes 内部状态。
这条边界对未来 Open Claw 等其他 Agent 平台同样成立，因此本次评审认为该分层方向正确，且应继续保持。
D04A-01：miniapp.tool.call 缺少明确的回程协议归属
已解决（2026-08-07，收敛决议）。 主定义已回填：lineup.v1.miniapp.tool.call 只新增请求信封，不新增 lineup.v1.miniapp.tool.result。与之关联的协议回执、进度和最终业务结果，全部继续复用 04.runtime_workspace 已冻结的 Agent Tool 回程语义，并始终按同一 call_id 相关联。
为什么这是 P1
04.runtime_workspace 已经明确冻结了 Agent Tool 的回程模型：
- 请求被接受后可先收到
accepted / starting等协议回执； - 激活完成后可收到
started或其他受控进度； - 最终只回传一次符合 Tool result schema 的业务结果；
- 同一
call_id的重放返回已持久化的最新回执、进度或最终结果。
但 04A 在新增 lineup.v1.miniapp.tool.call 时，如果只定义请求信封而不定义回程归属，就会出现至少三种实现分叉：
实现 A：为 miniapp.tool.call 再发明一套 miniapp.tool.result
-> Hermes Adapter、Runtime、验收脚本都要多维护一套协议。
实现 B：沿用既有回程语义，但不写进主定义
-> 各模块只能靠口头共识实现，验收口径不唯一。
实现 C：把 MiniApp Tool 的 started / progress 当成最终业务结果
-> 直接破坏 04.runtime_workspace 已冻结的 Tool result 语义。
这会影响 Hermes Adapter 的协议白名单、回程解析、幂等与验收证据，因此必须在实现前冻结。
收敛决议
本轮已确认：
lineup.v1.miniapp.tool.call只负责表达“Agent 要调用某个 MiniApp Tool”；- 不新增
lineup.v1.miniapp.tool.result或其他第二套 MiniApp 专用回程协议； - 该调用的 receipts / progress / final result 全部继续复用
04.runtime_workspace已冻结的 Agent Tool 回程语义； - Hermes Adapter 必须把这些回程都视作“同一条 Tool 调用”的不同阶段，而不是新的协议族。
该结论已回填 04A.agent_tool_route.md 的“协议冻结”和“完成标准”。
D04A-02：clarify 的 multi_select 变体没有唯一处理规则
已解决（2026-08-07，收敛决议）。 主定义已回填：本轮 clarify 只兼容单选、other -> input 和纯文本澄清；若 Hermes 发起 multi_select = true，Adapter 必须稳定拒绝，不得静默降级成单选或自由文本。
为什么这是 P2
Hermes 的 clarify 并不只有一种形态。当前 04A 已决定兼容 clarify，但如果不明确 multi_select 的处理方式，至少会出现以下风险：
实现 A：把 multi_select 静默改成单选
-> 用户损失语义，Agent 得到错误决策结果。
实现 B：改成自由文本输入，让用户自己拼多个选项
-> Host、Adapter 和 Hermes 对返回值结构无法形成唯一约定。
实现 C：某些平台支持，某些平台直接忽略
-> 同一协议在不同 Adapter 上表现不一致，验收不可复现。
这虽然不影响本轮 MiniApp Tool 通路的最小闭环，但会直接影响 Hermes 交互兼容层的实现一致性与验收，因此必须在迭代设计阶段给出唯一规则。
收敛决议
本轮已确认：
clarify的兼容范围冻结为单选choice、other -> input的二段式澄清，以及纯文本输入型澄清；multi_select = true不属于04A的兼容范围；- 若 Hermes 发起该变体，Adapter 必须返回受控 unsupported / not_supported 结果；
- 不允许静默降级、隐式拆分成多轮单选，或把多选伪装成自由文本。
该结论已回填 04A.agent_tool_route.md 的“兼容层上限”“冻结规则”“范围内”和“完成标准”。
评审关闭条件
- D04A-01 与 D04A-02 已回填 04A.agent_tool_route.md；
- 后续
02.technical_implementation_spec.md必须把这两项设计决议继续落到协议解析、白名单、错误码、测试夹具与验收证据； - 本评审未发现需要延期保留的 P4 / P5 事项；后续若出现新的平台私有交互类型，应通过新的评审记录进入，而不是直接扩充
04A主定义； - 本评审结论不替代主定义，实施仍以 04A.agent_tool_route.md 为唯一权威。