【实现】 Agent Loop 重构 Phase 7：集成验收、正式切换与旧链路清理

[wynxing]

关联 RFC / 架构

• 父架构 RFC：【架构】 重构 NeoCode Agent Loop：Workflow Orchestrator、统一 AgentLoop 与上下文隔离 #721
• 阶段：Phase 7
• 前置依赖：【实现】 Agent Loop 重构 Phase 0：建立任务质量评测基线与迁移护栏 #722、【实现】 Agent Loop 重构 Phase 1：Workflow 领域模型与持久化 #723、【实现】 Agent Loop 重构 Phase 2：提取统一 AgentLoop 执行内核 #724、【实现】 Agent Loop 重构 Phase 3：受约束 DAG 调度与节点级恢复 #725、【实现】 Agent Loop 重构 Phase 4：混合路由、Planner 与并行 Explore #726、【实现】 Agent Loop 重构 Phase 5：节点上下文、Artifact 与缓存抽象 #727、【实现】 Agent Loop 重构 Phase 6：Runtime Event v5、Gateway 与 TUI v2 #728 全部完成并通过各自验收。

目标问题

前序阶段分别落地评测、领域持久化、统一 AgentLoop、Scheduler、路由编排、Context/Artifact 和 v5 客户端链路。本阶段负责将它们集成为唯一生产主链，执行完整质量验收，正式切换入口，并删除旧 runtime.Run 编排、重复子 Agent loop、旧 Scheduler 和 v4 文档，避免长期双轨。

实现设计（How）

• 将 Runtime Run 入口切换为创建或恢复 WorkflowRun，由 Workflow Orchestrator 驱动节点。
• 确认 Gateway/TUI v2、Web 或其他仍受支持客户端全部使用 v5 契约；发布说明明确 TUI v1 停止支持。
• 运行全量 deterministic tests、真实任务评测、故障注入、恢复、race、性能和长任务测试。
• 根据 【实现】 Agent Loop 重构 Phase 0：建立任务质量评测基线与迁移护栏 #722 基线比较复杂任务成功率、错误完成声明、人工介入、token、TTFT、耗时和恢复正确性。
• 删除旧主循环编排分支、runtimeSubAgentEngine 重复闭环、独立 Todo/subagent Scheduler 执行真源、inline spawn_subagent 路径和 v4 协议维护代码。
• 保留仍有效的 Provider、Tool Manager、Context sources、Checkpoint、Hooks、Todo/Plan 用户视图和确定性验收策略。
• 更新 README、架构文档、配置指南、Gateway reference、运维与故障恢复手册。
• 设置数据库与版本回滚边界：正式切换后旧二进制不得接管活动 Workflow。

影响模块：应用装配、Runtime、Gateway、TUI v2、CLI 启动文档、旧代码清理、全部测试与发布说明。

边界与非目标：不在本阶段新增新的编排能力或 provider；不借清理进行无关目录重命名；不修改冻结的 TUI v1 源码。

任务拆解

• 将正式 Run 入口切换到 Workflow Orchestrator，并移除临时单节点 adapter。
• 完成所有受支持客户端的 v5 conformance 检查。
• 运行并归档 【实现】 Agent Loop 重构 Phase 0：建立任务质量评测基线与迁移护栏 #722 全量前后对比报告。
• 执行 provider/tool/persistence/permission/compact/checkpoint 故障注入。
• 执行 Gateway 重启、节点恢复、Execute needs_recovery 和断线重连演练。
• 检查 token、TTFT、内存、SQLite 锁等待和事件存储增长。
• 删除旧 Service.Run 编排分支和重复子 Agent loop。
• 删除旧 Scheduler 执行真源、inline spawn_subagent 和 v4 协议维护路径。
• 更新所有架构、配置、RPC、恢复、发布与 TUI v2 启动文档。
• 形成切换检查表、回滚检查表和发布说明。

测试与验证（Done）

• 正常路径：fast、orchestrated、Plan 审批、Build 自动执行、并行 Explore、Verify/Replan 和 Finalize 端到端通过。
• 边界条件：零工具、单 Explorer、最大并发、最大节点/轮数、预算边界、compact 和旧 Session 新建 Workflow。
• 异常分支：所有统一错误分类均有端到端覆盖，最终只产生一个 stop reason。
• 恢复路径：只读节点重试、写节点不确定状态、checkpoint restore、事件 replay 和客户端重连全部通过。
• 数据一致性：无 succeeded node 缺 Artifact、无重复 sequence、无重复写 receipt、无 stale worker 覆盖。
• 架构边界：无 TUI 直连 Runtime、无 Runtime 工具实现、无 provider 厂商字段向上泄漏。
• 质量门槛：复杂任务成功率高于 【实现】 Agent Loop 重构 Phase 0：建立任务质量评测基线与迁移护栏 #722 基线，错误完成声明和重复写入不增加。
• 工程门槛：go build ./...、go test ./...、race/前端测试通过，新增修改逻辑满足 100% 覆盖目标。
• 清理门槛：旧编排入口、重复 loop、旧 scheduler 真源和 v4 维护代码均无生产引用。

风险与回滚

• 风险：集成切换暴露跨阶段契约不一致。切换前冻结 schema 与事件版本，使用端到端 conformance 阻断发布。
• 风险：删除旧链路后无法局部回退。删除只在所有质量门槛达成后进行，并通过发布版本整体回滚。
• 风险：新数据库存在活动 Workflow 时旧二进制误运行。启动阶段检查 schema/active workflow，旧版本必须 fail-fast。
• 回滚：发布前可恢复到旧 Run 入口；发布后按完整版本回滚数据库备份和二进制，不混用新旧 Runtime 处理同一活动 Workflow。