目标问题（Why）
NeoCode 已具备 ReAct 主循环、Plan/Build、Todo DAG、子 Agent、Context Compact、验收、Checkpoint 和 Runtime Event，但编排权分散在 runtime.Run、独立子 Agent loop、Todo Scheduler 和多个控制面组件中。复杂任务缺少统一的多阶段编排、结构化上下文交接和节点级恢复；继续在 runtime.Run 中叠加分支会扩大维护与正确性风险。
本 RFC 的目标是以 Workflow Orchestrator 和统一 AgentLoop 重构编排内核，提高复杂编码任务完成质量，并让每个阶段可观测、可持久化、可恢复、可测试。
现状与边界
- TUI/Gateway：Gateway 是唯一通信边界；现有 v4 事件只能表达线性 Run。目标协议由 TUI v2 消费，TUI v1 冻结目录不修改并停止支持。
- Runtime：
Service.Run 同时承担生命周期、provider、tool、budget、compact、plan、verify、checkpoint 和终止。目标是让 Orchestrator 管节点间流程，AgentLoop 管节点内闭环。
- Provider/Tools：Provider 继续负责厂商适配；模型工具仍统一通过
internal/tools，不得把执行逻辑写入 Orchestrator。
- Session/Context：Session 保留用户可见会话；Workflow、Node、Artifact 和 NodeTranscript 独立持久化。Context 只构建 PromptBundle，不作调度决策。
- 写入边界：Explore、Synthesize、Verify 只读；Execute 是唯一工作区写入者。
关联议题：
核心设计（How）
主流程：
Intake -> Route
|-- Fast: Execute -> Verify -> Finalize
`-- Orchestrated:
Explore[1..N] -> Synthesize/Plan -> Execute -> Verify -> Finalize
| |
| Plan mode approval `-> Replan（有上限）
v
Await Approval
关键设计：
- 混合路由：确定性规则处理明显 fast/orchestrated 场景，其余由无工具 Router 判断；输出非法时按质量优先进入 orchestrated。
- 受约束 DAG：模型只能生成固定类型节点的任务与依赖，不能定义权限、失败策略或任意节点类型。
- 统一 AgentLoop：主 Agent 与子 Agent 共用 provider、tool、budget、compact、stream、usage 和 transcript 闭环。
- 单写者：并行 Explore 只读；Execute 独占工作区写租约，第一版不实现并行 coder 或 worktree 合并。
- Artifact handoff：节点使用结构化 Artifact 交接，不复制父节点完整历史；节点 transcript 与 Session transcript 隔离。
- 节点级恢复：已完成节点不重跑；只读节点可重试；发生写入后中断的 Execute 进入
needs_recovery，结合 checkpoint、tool receipt 和 diff 决策，禁止盲目重放写操作。
- Context 分层：PromptBundle 固定为 role stable、workspace stable、workflow state、node context、turn delta；缓存提示保持 provider-neutral，由 adapter 映射。
- Event v5：事件携带 workflow_id、node_id、event_id 和单调 sequence；Gateway 提供快照、审批、恢复和事件重放 RPC。
- 角色模型配置：Router、Planner、Explorer、Executor、Reviewer 可覆盖 provider/model/thinking，默认继承会话模型。
为什么选择该方案：受约束 DAG 在复杂任务适应性和确定性之间取得平衡；单写者使恢复与回滚可证明；Orchestrator/AgentLoop 分离消除两套 ReAct 实现；Artifact 与节点 transcript 隔离能降低上下文污染并提高缓存前缀稳定性。
数据流、事件流与恢复流
- 数据流：用户输入经 Gateway 创建 Workflow；Orchestrator 选择模板或 Planner DAG；节点由 AgentLoop 执行；Tool Manager 执行工具；Artifact 提供下游输入；accepted Verify 允许 Finalize。
- 事件流：状态与事件在同一事务提交；客户端用 event_id 去重、sequence 检测缺口，重连时先读快照再增量重放。
- 恢复流：启动扫描非终态 Workflow，将遗留 running 标为 interrupted；只读节点重试，写节点审计 checkpoint/receipt/diff 后继续、恢复或等待用户决议。
落地清单（What）
验收标准（Done）
风险与回滚
- 风险：迁移期间存在两套状态来源；通过阶段性单一入口和 Store revision 禁止双写。
- 风险：Planner DAG 不稳定；通过固定 schema、图校验和一次修正调用控制。
- 风险：节点恢复误重放写操作；所有写后中断进入
needs_recovery，禁止自动重放。
- 风险：v5 是 breaking change；先完成 Gateway/TUI v2 conformance，再切换 Runtime，并在发布说明中明确 TUI v1 停止支持。
- 回滚：Phase 1–6 保留入口级回滚到旧 Run；每个 schema migration 使用事务。Phase 7 删除旧链路后按版本整体回滚，不让旧二进制处理活动 Workflow 新状态。
目标问题（Why）
NeoCode 已具备 ReAct 主循环、Plan/Build、Todo DAG、子 Agent、Context Compact、验收、Checkpoint 和 Runtime Event，但编排权分散在
runtime.Run、独立子 Agent loop、Todo Scheduler 和多个控制面组件中。复杂任务缺少统一的多阶段编排、结构化上下文交接和节点级恢复；继续在runtime.Run中叠加分支会扩大维护与正确性风险。本 RFC 的目标是以 Workflow Orchestrator 和统一 AgentLoop 重构编排内核，提高复杂编码任务完成质量，并让每个阶段可观测、可持久化、可恢复、可测试。
现状与边界
Service.Run同时承担生命周期、provider、tool、budget、compact、plan、verify、checkpoint 和终止。目标是让 Orchestrator 管节点间流程，AgentLoop 管节点内闭环。internal/tools，不得把执行逻辑写入 Orchestrator。关联议题：
核心设计（How）
主流程：
关键设计：
needs_recovery，结合 checkpoint、tool receipt 和 diff 决策，禁止盲目重放写操作。为什么选择该方案：受约束 DAG 在复杂任务适应性和确定性之间取得平衡；单写者使恢复与回滚可证明；Orchestrator/AgentLoop 分离消除两套 ReAct 实现；Artifact 与节点 transcript 隔离能降低上下文污染并提高缓存前缀稳定性。
数据流、事件流与恢复流
落地清单（What）
验收标准（Done）
TUI v2 -> Gateway -> Runtime -> Provider / Tool Manager -> Tools，无跨层直连。go build ./...、go test ./...和前端测试通过。风险与回滚
needs_recovery，禁止自动重放。