初始化 agent_ops 文档治理体系

2026-08-07 16:56:51 +08:00
commit 10840909ab
75 changed files with 15750 additions and 0 deletions
@@ -0,0 +1,111 @@
+# 04A.agent_tool_route 设计评审（一）
+
+**评审编号：** 01  
+**日期：** 2026-08-07  
+**评审对象：** [04A.agent_tool_route.md](04A.agent_tool_route.md)（实施权威）、[04.runtime_workspace.md](../04.runtime_workspace/04.runtime_workspace.md)、[05.technical_implementation_spec.md](../04.runtime_workspace/05.technical_implementation_spec.md)、[运行时与智能体工具.md](../../设计/02.正式方案/运行时与智能体工具.md)、[lineup-runtime-sdk-architecture.md](../../设计/02.正式方案/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` 时，如果只定义请求信封而不定义回程归属，就会出现至少三种实现分叉：
+
+```text
+实现 A：为 miniapp.tool.call 再发明一套 miniapp.tool.result
+  -> Hermes Adapter、Runtime、验收脚本都要多维护一套协议。
+
+实现 B：沿用既有回程语义，但不写进主定义
+  -> 各模块只能靠口头共识实现，验收口径不唯一。
+
+实现 C：把 MiniApp Tool 的 started / progress 当成最终业务结果
+  -> 直接破坏 04.runtime_workspace 已冻结的 Tool result 语义。
+```
+
+这会影响 Hermes Adapter 的协议白名单、回程解析、幂等与验收证据，因此必须在实现前冻结。
+
+### 收敛决议
+
+本轮已确认：
+
+1. `lineup.v1.miniapp.tool.call` 只负责表达“Agent 要调用某个 MiniApp Tool”；
+2. 不新增 `lineup.v1.miniapp.tool.result` 或其他第二套 MiniApp 专用回程协议；
+3. 该调用的 receipts / progress / final result 全部继续复用 `04.runtime_workspace` 已冻结的 Agent Tool 回程语义；
+4. Hermes Adapter 必须把这些回程都视作“同一条 Tool 调用”的不同阶段，而不是新的协议族。
+
+该结论已回填 [04A.agent_tool_route.md](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` 的处理方式，至少会出现以下风险：
+
+```text
+实现 A：把 multi_select 静默改成单选
+  -> 用户损失语义，Agent 得到错误决策结果。
+
+实现 B：改成自由文本输入，让用户自己拼多个选项
+  -> Host、Adapter 和 Hermes 对返回值结构无法形成唯一约定。
+
+实现 C：某些平台支持，某些平台直接忽略
+  -> 同一协议在不同 Adapter 上表现不一致，验收不可复现。
+```
+
+这虽然不影响本轮 MiniApp Tool 通路的最小闭环，但会直接影响 Hermes 交互兼容层的实现一致性与验收，因此必须在迭代设计阶段给出唯一规则。
+
+### 收敛决议
+
+本轮已确认：
+
+1. `clarify` 的兼容范围冻结为单选 `choice`、`other -> input` 的二段式澄清，以及纯文本输入型澄清；
+2. `multi_select = true` 不属于 `04A` 的兼容范围；
+3. 若 Hermes 发起该变体，Adapter 必须返回受控 unsupported / not_supported 结果；
+4. 不允许静默降级、隐式拆分成多轮单选，或把多选伪装成自由文本。
+
+该结论已回填 [04A.agent_tool_route.md](04A.agent_tool_route.md) 的“兼容层上限”“冻结规则”“范围内”和“完成标准”。
+
+## 评审关闭条件
+
+1. D04A-01 与 D04A-02 已回填 [04A.agent_tool_route.md](04A.agent_tool_route.md)；
+2. 后续 `02.technical_implementation_spec.md` 必须把这两项设计决议继续落到协议解析、白名单、错误码、测试夹具与验收证据；
+3. 本评审未发现需要延期保留的 P4 / P5 事项；后续若出现新的平台私有交互类型，应通过新的评审记录进入，而不是直接扩充 `04A` 主定义；
+4. 本评审结论不替代主定义，实施仍以 [04A.agent_tool_route.md](04A.agent_tool_route.md) 为唯一权威。