ai-workflow/docs/leader-dag-implementation-plan.md

Leader DAG 化实施计划

本文档定义当前 inbox v2 从“leader 输出 chain/task 并即时执行”升级到“更稳定的 DAG planning / gating / replan”模型的落地方案。

目标不是照搬 Astro，而是吸收其中最有价值的五个机制，并严格适配我们现有架构：

• leader 运行在宿主机，内嵌于 inbox server
• worker 运行在 per-chain 容器中
• topic / chain / task / dependency / workflow_run / message 是现有运行时主模型
• 不引入多机器调度，不引入 hosted control plane，不引入新的外部依赖

背景

最近几轮真实回归暴露出两个核心问题：

1. leader 的规划产物还不够稳定，更多是“即时创建 chain/task”，而不是明确的计划对象。
2. worker 失败后的 replan 缺少约束，导致同一个 topic 里反复新建 chain，造成 worktree / container 增生。

这说明当前系统已经具备“可执行”的基本能力，但还缺少“可控规划”的中间层。

本计划把这层能力拆成五个阶段，按顺序落地。

总目标

实施完成后，系统应具备以下能力：

• leader 输出稳定的 planning schema，而不是松散文本
• topic 在执行前先经过 gating，而不是盲目并发起 worker
• 任务优先按 deliverable 和 batch 拆分，而不是隐式退化成角色链
• replan 只能 patch 现有图，不能无限增生 chain
• milestone 成为图中的一等节点，用于收口多分支结果

非目标

本计划不包含以下内容：

• 多机器 / 多 runner 调度
• 容器资源感知调度
• hosted dashboard / cloud relay
• 通用 workflow DSL
• 兼容旧 pool / discovery / fixed-role 路径

---

阶段 1：规划产物标准化

目标

让 leader 的输出从“只够当前 applyLeaderOutput 消费的最小 JSON”升级为稳定的 planning schema。

要解决的问题

• 当前 leader 输出主要服务于即时建链，不利于回放、对比、重规划
• reply_markdown、chains、tasks 混在一起，缺少 plan 元信息
• 缺少 task 的输入、产物、验证、批次、replan 策略等显式字段

产出

新增一个面向 leader 的 planning schema，建议至少包含：

• plan_version
• plan_summary_markdown
• execution_mode
  • clarify
  • plan_only
  • plan_and_start
• chains[]
  • key
  • name
  • purpose
  • reuse_strategy
• tasks[]
  • key
  • chain_key
  • title
  • body_markdown
  • acceptance_markdown
  • deliverables[]
  • depends_on[]
  • verification
  • batch_key
  • replan_policy
• milestones[]
• start_nodes[]
• leader_reply

实现范围

• inbox/internal/app/leaderloop/service.go
  • 扩展 leaderOutput 结构
  • 更新 leaderOutputSchema()
  • 拆出 plan 相关校验函数
• 如有必要，新增：
  • inbox/internal/domain/plan/
  • 或 inbox/internal/domain/workflowplan/

设计要求

• schema 必须可序列化进 workflow_runs.config_snapshot_json 或 command_json
• leader 返回的 plan 必须可重放
• plan 必须允许“仅规划不启动”

验收标准

• leader 输出可以表达：
  • 只澄清
  • 只规划
  • 规划并启动
• 单元测试覆盖：
  • 完整 plan decode
  • 缺字段失败
  • 非法 dependency 失败
  • 非法 start_nodes 失败

风险

• 一次把字段做太多，导致 prompt 不稳定
• schema 改动过大，影响现有 taskexec 和 dashboard 显示

收口策略

• 先新增字段，不立刻让 dashboard 全部消费
• leaderloop 内部先把 schema 校验稳定，再逐步外显

---

阶段 2：前置 Gating 节点

目标

在真正启动 worker 之前，先通过一组 gating task 判断“是否具备执行条件”。

要解决的问题

• 当前 leader 规划后容易直接启动多个 chain
• 一些基础条件没满足时，worker 只会重复失败
• 失败后 leader 再次 replan，进一步放大噪音

典型 gating 场景

• 仓库结构是否存在
• 运行时 provider / auth 是否可用
• 基础 contract / API 边界是否已经明确
• 必要目录 / package manager / root script 是否存在
• topic 是否已具备足够信息，不需要继续澄清

产出

在 planning schema 中加入 gating 语义：

• tasks[].kind
  • gate
  • execution
  • verification
  • milestone
• tasks[].gate_policy
  • hard_stop
  • ask_user
  • leader_replan

实现范围

• leaderloop
  • 在 start_nodes 解析时优先启动 gate task 所在 chain
• taskexec
  • gate task 失败后，不自动放开后续依赖
• dashboard
  • 在 chain/task board 上明确标记 gate 节点

设计要求

• gate 失败时，后续依赖节点保持 draft 或 blocked
• leader 收到 gate 失败后，应优先 patch 计划，而不是起新图
• gate task 的完成结果必须带结构化 failure reason

验收标准

• topic 首轮执行时，能先只启动 1 个 gating chain
• gate 失败后，其余 chain 不启动
• leader 能基于 gate failure 回复用户或 patch 任务

风险

• 如果 gating 太多，会让简单需求变慢

收口策略

• 只保留 2-3 类强 gating
• 其它检查继续留在 worker 内部做普通失败

---

阶段 3：按 Deliverable 与 Batch 拆分

目标

让 leader 优先按产物边界拆 task，而不是退化成“前端链 / 后端链 / 基础链”这类松散角色链。

要解决的问题

• 当前 chain 名称仍然容易被 prompt 驱动成泛化角色链
• 同一链上 task 颗粒度不稳定
• 缺少批处理并行能力

产出

在 leader prompt 和 schema 中强化以下约束：

• task 必须显式描述最终产物
• chain 只是执行容器，不是角色人设
• 可以使用 batch_key 做批次并行

建议的拆分优先级：

1. 先按 deliverable 拆
2. deliverable 太大时，再按 batch 拆
3. 最后才落到实现域（frontend/backend/integration）

示例：

• api-contract
• backend-crud
• frontend-list-create
• frontend-edit-filter
• integration-e2e

而不是默认：

• backend
• frontend
• foundation

实现范围

• leaderloop/buildLeaderPrompt
  • 增加强约束，要求 chain/task 以产物命名
• leaderOutputSchema
  • 增加 deliverables[] 和 batch_key
• dashboard
  • 在 task 卡片中展示 deliverables 与 batch

设计要求

• 同一 batch 内的 task 应能独立并行
• deliverables[] 应该能支持后续 verification 和 merge summary

验收标准

• 相同需求多次规划时，chain/task 命名更稳定
• leader 生成的任务里，至少 80% 有明确 deliverable 字段
• 支持一个 topic 下存在“批量任务 + 聚合 milestone”

风险

• prompt 改得太死，影响 leader 灵活性

收口策略

• 不硬编码固定 chain 名称
• 只强制“必须有 deliverable”，不强制唯一命名模板

---

阶段 4：Replan 只允许 Patch，不允许重建图

目标

把 replan 从“再创建一批 chain/task”改成“在同一张图上 patch 现有节点”。

要解决的问题

• 这次已经真实出现过：
  • worker 失败
  • leader 重规划
  • 同一 topic 新建 chain-2、chain-3、chain-60
  • worktree / container 爆炸增长

核心原则

• topic 进入 execution 后，禁止无边界新增 chain
• replan 默认只能做：
  • 更新已有 chain 状态
  • 在已有 chain 下补 task
  • 调整 dependencies
  • 调整 start_nodes
  • 标记 chain/task 为 superseded / blocked / cancelled

只有在极少数场景下允许新增 chain，例如：

• 用户明确要求增加新的独立工作流分支
• 原图中不存在可复用的产物链
• leader 输出显式 replan_mode = expand_graph

即使允许扩图，也必须通过严格限制：

• topic 级 max chain count
• replan iteration limit
• leader 必须解释新增原因

产出

新增 replan 策略字段：

• plan_mode
  • initial
  • patch
  • expand_graph
• replan_reason
• supersedes[]

新增 topic 级保护：

• max_chain_count
• max_replan_count

实现范围

• leaderloop/applyLeaderOutput
  • 默认复用已有 chain
  • 有 existing chains 时禁止无限新建
• taskexec
  • worker failure 回传更结构化的失败原因
• 可能需要：
  • chains / tasks 新状态，例如 superseded

验收标准

• 同一 topic 上重复 worker 失败后，不再出现 chain 数量线性增长
• topic 执行 5 次失败回执后，chain 总量仍保持稳定
• 集成测试覆盖：
  • 初始计划
  • worker 失败
  • leader patch
  • 继续执行

风险

• patch 逻辑比“直接新增”更复杂
• 旧 topic 的脏数据可能影响验证

收口策略

• 先在 leaderloop 内部做强保护
• 旧 topic 不做兼容逻辑，直接清数据

---

阶段 5：Milestone 成为一等节点

目标

把 milestone 从隐式概念提升为图中的正式节点，用来汇聚多分支结果并决定下一步推进。

要解决的问题

• 当前多分支的收口主要靠 leader 自己看消息判断
• 缺少“某几个 task 都完成后，再开始下一阶段”的正式表达

典型 milestone

• Foundation Ready
• API Contract Ready
• Feature Complete
• Ready for Integration
• Ready for User Review

产出

在 planning schema 中加入：

• milestones[]
  • key
  • title
  • depends_on[]
  • summary_markdown
• milestone 可被 start_nodes 和后续 task 依赖引用

实现范围

• leaderloop
  • 允许创建 milestone 节点
  • 在依赖满足时将 milestone 标记为 ready/succeeded
• tasks 或新表
  • 若不新增表，可先将 milestone 作为特殊 task kind 存储
• dashboard
  • graph / board 中区分 milestone 与普通执行 task

设计要求

• milestone 不运行容器
• milestone 只负责聚合前置状态
• milestone 可以成为 integration / verification 的 gating 前提

验收标准

• 一条执行链中可见 milestone 节点
• 多分支完成后 milestone 自动推进
• leader 可以基于 milestone 状态决定是否继续启动 integration

风险

• 如果把 milestone 单独建表，会扩大 schema 变更面

收口策略

• 第一版先把 milestone 存成 task.kind = milestone
• schema 稳定后再决定是否单独抽表

---

推荐实施顺序

严格按下面顺序推进，不要并行乱改：

1. 阶段 1：规划产物标准化
2. 阶段 4：Replan 只允许 Patch
3. 阶段 2：前置 Gating 节点
4. 阶段 3：按 Deliverable 与 Batch 拆分
5. 阶段 5：Milestone 一等节点

原因：

• 阶段 1 先固定 schema
• 阶段 4 先止住增生风险
• 阶段 2 再降低盲目执行
• 阶段 3 再提高任务质量
• 阶段 5 最后做图上的正式汇聚

每阶段的统一交付要求

每个阶段都必须同时完成：

• 领域模型改动
• leaderloop 应用逻辑改动
• 必要的 HTTP / dashboard 暴露
• 单元测试
• 至少一条真实或半真实回归路径

统一验收门槛

全部五阶段完成后，应满足：

• 同一 topic 不再出现失控 chain 增生
• leader 输出稳定 plan schema
• 执行前存在明确 gating
• task 以 deliverable 为核心组织
• 图中存在正式 milestone 节点
• dashboard 能看出“计划 / 执行 / 收口”的结构

建议的实施文档拆分

后续真正进入实现时，建议在 .omx/plans/ 或 docs/ 下继续细分为：

• phase-1-plan-schema.md
• phase-2-gating.md
• phase-3-deliverable-batching.md
• phase-4-replan-patch-only.md
• phase-5-milestones.md

本文档作为总计划，不直接承担逐字段设计。