SKILL.md 4.19 KB

Edit Raw Blame History



name: design-dynamic-work-graph
description: |
  跨 Org Agent（Planner/Coder/Validator 共用）的通用方法论：如何把一个目标拆成一张可执行的
  graph_manifest（节点、依赖、每节点自包含提示词），供 work_graph_plan.py::plan_work_graph()
  的通用规划路径驱动、work_graph_orchestrate.py::run_graph() 执行。
version: 1.0.0
tags:


planning
work-graph
orchestration
metadata:
origin: graphlemon-native
related: [G（并行执行）docs/work-graph-parallel-execution-design.md, E docs/todo/dynamic-work-graph-design-skill-design.md]
platforms: [linux, macos, windows]
---

SKILL：design-dynamic-work-graph
适用场景

任务复杂到值得先规划一张图、再按图执行，而不是一次单次调用就能完成（不是所有任务都需要上图——任务很小或孤立时，直接一次调用更合适）。
调用方是 Planner 自身以外的 Org Agent（Coder/Validator），需要为自己的一批子任务生成 graph_manifest。

输出：一个 graph_manifest
{
  "nodes": [
    {"node_id": "...", "depends_on": ["..."], "task_prompt": "..."}
  ],
  "edges": [
    {"from": "...", "to": "...", "edge_type": "zero_token" | "needs_judgment"}
  ]
}


每个节点必须自带 task_prompt：该节点执行时使用的完整、自包含提示词，不依赖调用方另外拼接上下文。这是跟 Planner 自己的 BRD/PRD/SDD/Benchmark 链的关键区别——Planner 的节点类型固定在一个小词表里，下游代码按 artifact_type 查表就能拿到提示词；Coder/Validator 的子任务没有这种固定词表，提示词必须在规划阶段由你自己写清楚。
规则（强制）

节点边界：一个节点 = 一次独立的、有明确输入输出契约的 Work Node 执行（一次 claude -p 调用）。不要把一个连贯的思考过程拆成多个人为的小节点。
如实表达依赖，不要多加：depends_on 只写真正存在数据流动的依赖——下游节点的 task_prompt 真的需要引用上游节点的产出内容，才算依赖。不要为了图看起来更"有序"而人为串行化本来互不依赖的节点：执行引擎（topological_layers()）会把没有依赖关系的节点自动分到同一层并发执行，多余的依赖会白白拖慢总执行时间，还会让"这几个节点该并行"这条信息从图里消失。
edge_type 二选一：


zero_token：纯聚合/规约边，下游不需要 Agent 推理就能处理上游输出（比如"把几份判断汇总计数"）。这类聚合优先用普通代码完成，不要为它专门生成一个节点。
needs_judgment：下游真的需要读懂上游内容、做出判断才能继续（比如"根据 SDD 内容写实现"）。

任务小就不要上图：如果目标本身一次 Work Node 调用就能完成，直接返回一个单节点 graph_manifest（或者告知调用方不需要走图规划路径），不要为了"用上这套机制"强行拆分。
node_id 唯一、可读：用能表达该节点做什么的短标识符（如 test-module-a），不要用无意义的序号。

分解方法

先列出这批子任务里，每一对任务之间是否存在真实的数据流动（"B 的 task_prompt 是否真的需要 A 的产出内容"）。没有则不连边。
对确实存在的依赖，判断是 zero_token 还是 needs_judgment。
为每个节点写出自包含的 task_prompt——假设执行它的 Agent 看不到这次规划的任何上下文，只能看到这一个节点的 task_prompt 和它依赖节点的产出。
检查是否有环（topological_layers() 遇到环会报错）——如果两个节点互相需要对方的产出，说明边界划错了，需要合并成一个节点或重新拆分。

自审清单

[ ] 每个节点都有 task_prompt，且不依赖这次规划对话里才有的隐含上下文。
[ ] 没有为了让图"看起来有序"而添加的虚假 depends_on。
[ ] 没有本来可以用普通代码完成的聚合被写成了一个需要 Agent 推理的节点。
[ ] 图里没有环。
[ ] 如果这批任务本质上一次调用就能做完，没有为了走图机制而强行拆分。