move runtime_workspace and agent_tool_route stages to completed
This commit is contained in:
@@ -0,0 +1,87 @@
|
||||
# 04A.agent_tool_route 联合评审（三）
|
||||
|
||||
**评审编号：** 03
|
||||
**日期：** 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、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](../../设计/02.正式方案/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](../../设计/02.正式方案/lineup-runtime-sdk-architecture.md) 和 [app_final_design.md](../../设计/02.正式方案/app_final_design.md) 都已把 Inventory 收敛为同时包含 App、Tool、Surface、Capability，且 Tool 调用必须携带 `inventory_revision`。
|
||||
[lineup-ui-surface-protocol.md](../../设计/02.正式方案/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
|
||||
|
||||
如果不消歧，至少会出现以下风险：
|
||||
|
||||
```text
|
||||
实现 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`。
|
||||
|
||||
如果不明确权威顺序，后续实现者很容易错误得出以下结论：
|
||||
|
||||
```text
|
||||
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](04A.agent_tool_route.md) 和 [02.technical_implementation_spec.md](02.technical_implementation_spec.md)；
|
||||
2. 后续代码实现、测试夹具和验收记录必须统一使用 `lineup.v1.*` 当前兼容信封；
|
||||
3. 后续若补正式方案文档示例，应把 `client.inventory` 的 Tool 顶层投影同步回填到正式方案，而不是在 `04A` 再引入本地例外；
|
||||
4. 本评审当前无未解决的 P0～P3。
|
||||
Reference in New Issue
Block a user