拆分 Agent Host 运行职责

将 durable 取消、失败收口、审批决议和外部结果对账迁入 RuntimeService 把 Host 工具、MCP、Skill 与外部 backend 桥接拆为私有模块并保持公开 API 补充 Runtime 控制测试、依赖反向门禁和架构验收文档
2026-09-09 19:20:54 +08:00
parent 202279c6d9
commit 69fc3d8ca0
15 changed files with 2483 additions and 2126 deletions
@@ -6,6 +6,25 @@

 ## 当前交付

+### Host 控制面拆分（2026-09-09）
+
+- [x] RuntimeService 承接 cancel、无主失败收口、审批决议和 Provider/Tool 对账；Host
+      保持原公开方法并只做错误映射委托。
+- [x] Runtime-only 控制测试 4/4 通过；Host 80/80 单测、workspace 双特性、Clippy 和
+      依赖边界检查通过。
+- [x] 未把 `finish_cancelled`、Engine 执行、checkpoint listener、trace 投影或外部工具桥
+      下沉；这些仍属于 Host 的执行编排职责。
+- [ ] 后续可按职责把 Host 私有实现拆成 execution/checkpoint/external/tools-context 模块，
+      但本轮不改变公开 API 或新增平行装配层。
+
+### Host 工具与上下文物理模块化（2026-09-09）
+
+- [x] `tools.rs`、`mcp.rs`、`context.rs` 已从 `agent-host/src/lib.rs` 移出；根路径公开类型通过显式 re-export 保持兼容。
+- [x] 拆分后 Host 80/80、Runtime control 4/4、workspace 双特性和 Clippy 通过。
+- [x] `external.rs` 已承接 ExternalBackendToolExecutor 与 Codex session metadata sink；公开类型和
+      生命周期合同保持不变。
+- [ ] Engine execution、checkpoint/trace 与 Codex/External backend 仍在根编排层，后续按风险分批拆分。
+
 ### 当前范围与消息一致性验收（2026-09-06）

 - [x] 复现并修复正常完成仍重复保存 assistant/tool-call 的缺陷，删除按最终 phase/末条消息内容去重的推断。
@@ -25,6 +25,33 @@ phase、消息是否相等或最后一条消息判断。正常完成、串行多

 验收必须逐条比较 Engine 消息、Runtime 消息与事件从零重放结果；仅检查最终文本或“包含一个工具消息”不足以验收。

+## Host / Runtime 控制面拆分（2026-09-09）
+
+`agent-runtime-sqlite::RuntimeService` 现在承接不依赖 Engine 或外部适配器的 durable 控制命令：
+`cancel_run`、`fail_unclaimed_run`、`resolve_approval_decision`、`reconcile_provider_result`
+和 `reconcile_tool_result`。这些入口在 Runtime 内完成状态检查、Core reducer 事件构造和 SQLite
+事务调用；Host 只保留同名的兼容/装配委托，因此 CLI 和嵌入方的调用合同不变。
+
+Host 继续拥有 `run_claimed_with_lease`、Engine checkpoint listener、事件 trace 投影、
+Cancellation/heartbeat worker，以及 MCP/Skill/Codex/ExternalBackend 工具桥。这些逻辑依赖
+Engine 或具体适配器，不能下沉到 portable Runtime，也不能反向进入 Core。Runtime 控制面拆分
+不改变 SQLite schema、checkpoint 格式或公开 Host API。
+
+依赖门禁额外检查：Engine 不得依赖 Runtime/Storage/Host/适配器；portable Runtime 不得依赖
+Engine、Host 或 SQLite；SQLite Runtime 只允许装配 portable Runtime 与 SQLite storage，不得
+带入 Engine 或外部适配器。Runtime 控制入口由 `agent-runtime-sqlite/tests/control.rs`
+独立回归，覆盖 queued/active/stale cancel、失败收口和无副作用错误路径。
+
+Host 的适配器桥接随后按私有模块拆分：`tools.rs` 负责 ToolRouter 和 namespace resolver，
+`mcp.rs` 负责 MCP 工具/目录/资源与 prompt 上下文，`context.rs` 负责 Skill 上下文源。
+根 `lib.rs` 只通过显式 `pub use` 保持原有公开类型路径；Engine 执行、checkpoint/trace、
+heartbeat 和 Codex/External backend 生命周期仍在根执行编排中，避免为了文件拆分而改变依赖边界。
+
+当前进一步把 `ExternalBackendToolExecutor` 和 `CodexRuntimeSessionMetadataSink` 移至
+`external.rs`；它们依赖 Runtime 和外部 backend 合同，但不依赖 Engine 执行循环。Codex
+server-request handler 仍留在 Host 根编排，原因是它同时绑定 ToolRouter、ApprovalPolicy
+和版本化 wire。`agent-host` 根模块只导出稳定类型并保留跨模块委托，避免形成第二套公开 API。
+
 ## 当前实现顺序

 1. Core 契约和纯 reducer；
@@ -20,6 +20,12 @@ Host 单测另外验证 checkpoint 错 lease 时不推进投影游标、同一 t
 `runtime_states.snapshot_json` 中当前 run 的消息与 CLI 返回的 Engine 消息；Fake 两个用例通过。
 它不再仅凭 completed、最终文本或最少事件数判定持久化正确；真实 Provider 仍仅在显式 opt-in 时调用。

+## Host / Runtime 控制面拆分回归（2026-09-09）
+
+`agent-runtime-sqlite/tests/control.rs` 的 4 个 Runtime-only 测试覆盖 queued/active/stale cancel、
+无主失败收口以及审批/对账错误不写入；Host 80 个单测保持通过。Host 的 Engine 执行和外部适配器
+桥接未搬入 Runtime，避免 Runtime 反向依赖 Engine 或具体 Provider/MCP/Skill/Codex。
+
 这份测试集用于先验证运行时闭环，再接入自己的真实 Provider。测试数据在
 [`../tests/agent-test-set.jsonl`](../tests/agent-test-set.jsonl)，执行器是
 [`../scripts/run-agent-test-set.sh`](../scripts/run-agent-test-set.sh)。
@@ -287,6 +287,24 @@ system/developer 内容固定保留，外部内容标记为不可信。先做确

 ## 当前执行状态

+### Host 控制面拆分（2026-09-09）
+
+- [x] `agent-runtime-sqlite::RuntimeService` 新增 `cancel_run`、`fail_unclaimed_run`、
+      `resolve_approval_decision`、`reconcile_provider_result` 和 `reconcile_tool_result`；
+      新增 4 个 Runtime-only 集成回归，证明 queued/active/stale cancel、失败收口及错误不写入。
+- [x] `agent-host` 的同名入口改为薄委托，删除重复的审批/对账/失败/取消控制逻辑；保留
+      `finish_cancelled`、Engine 执行、checkpoint/trace、heartbeat 和外部工具桥，因为这些
+      依赖 Engine 或具体适配器。
+- [x] 依赖边界脚本新增 Engine、portable Runtime、SQLite Runtime 的反向依赖黑名单；不新增
+      crate、数据库字段或 Cargo.lock 变更。
+- [x] Host 已完成第一批物理模块化：`tools.rs`、`mcp.rs`、`context.rs` 分别承接工具路由/
+      namespace、MCP 桥接和 Skill 上下文；公开类型由根模块显式 re-export，未降低 API 可见性。
+- [x] `external.rs` 已承接通用 ExternalBackendToolExecutor、Codex session metadata sink 及
+      生命周期 helper；根模块只保留 re-export 和装配调用。Host 80/80、Runtime control 4/4、
+      workspace 双特性、两套 Clippy、Rustdoc、fmt、编码、依赖和 diff 门禁通过。
+- [ ] `execution`、`checkpoint`、`external` 仍保留在根文件，后续拆分必须继续维持 Engine glue
+      不进入 Runtime 的边界。
+
 ### 原始范围复核（2026-09-06）

 按用户原始附件及后续明确的 `rust/` workspace / Runtime 分层 / endpoint 配置变更执行。
@@ -14,6 +14,17 @@
 原始范围已纠正：registry、公开许可证、全量 schema、自动 webhook 和跨主机自动调度不作为本期阻塞项。
 总计划仍须按权威计划现状表逐项验收所声明的协议行为与恢复路径；下方历史计数/“未完成”扩张描述不覆盖本节。

+## Host / Runtime 控制面拆分（2026-09-09）
+
+- `agent-runtime-sqlite::RuntimeService` 新增 `cancel_run`、`fail_unclaimed_run`、
+  `resolve_approval_decision`、`reconcile_provider_result` 和 `reconcile_tool_result`；
+  Runtime-only 控制测试 4/4 通过。
+- `AgentHost` 的同名入口改为薄委托，删除重复的 durable 状态判断、reducer 事件构造和对账消息校验；
+  Engine 执行、checkpoint/trace、heartbeat/Cancellation worker、MCP/Skill/Codex 桥接仍留在 Host。
+- 依赖门禁新增 Engine、portable Runtime、SQLite Runtime 的反向依赖黑名单；本次未改 SQLite schema、
+  Cargo.lock 或公开 Host API。定向 Host 80/80 单测、workspace 双特性、Clippy、Rustdoc、fmt、编码和
+  diff 门禁通过。
+
 ## 结论

 截至 2026-09-06，独立 `rust/` workspace 的当前增量闭环通过本地验收：