初始化 agent_ops 文档治理体系
This commit is contained in:
@@ -0,0 +1,116 @@
|
||||
# 04A.agent_tool_route 设计评审（二）
|
||||
|
||||
**评审编号：** 02
|
||||
**日期：** 2026-08-07
|
||||
**评审对象：** [04A.agent_tool_route.md](04A.agent_tool_route.md)（实施权威）、[02.technical_implementation_spec.md](02.technical_implementation_spec.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)、[app_final_design.md](../../设计/02.正式方案/app_final_design.md)、[lineup-ui-surface-protocol.md](../../设计/02.正式方案/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](../../设计/02.正式方案/lineup-ui-surface-protocol.md) 当前把 `applications` 定义为“已启用 app 的 surface 可见性”，不含 Tool；
|
||||
- [lineup-runtime-sdk-architecture.md](../../设计/02.正式方案/lineup-runtime-sdk-architecture.md) 与 [app_final_design.md](../../设计/02.正式方案/app_final_design.md) 明确 Runtime Inventory 同时包含 App、Tool、Surface 与 Capability；
|
||||
- [04.runtime_workspace/05.technical_implementation_spec.md](../04.runtime_workspace/05.technical_implementation_spec.md) 则已经把 Tool 作为从 Registry 独立投影到 Runtime Tool Registry / Agent Inventory 的对象。
|
||||
|
||||
如果 `04A` 继续把 Tool 内嵌进 `applications[].tools`，就会产生三种实现分叉：
|
||||
|
||||
```text
|
||||
实现 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](04A.agent_tool_route.md) 与 [02.technical_implementation_spec.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”拆成以下两套协议：
|
||||
|
||||
```text
|
||||
一套：标准交互兼容入口 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](04A.agent_tool_route.md) 与 [02.technical_implementation_spec.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。
|
||||
Reference in New Issue
Block a user