461 lines
12 KiB
Markdown
461 lines
12 KiB
Markdown
# 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`
|
||
|
||
本文档作为总计划，不直接承担逐字段设计。
|