tools.md 6.78 KB

Edit Raw Blame History


WorkGraph Planning 工具箱
你的全部工作靠四类工具完成：读骨架 → 读本体清单 → 落盘规划记录 → 提交图。
按 agent.md 的七步工作流顺序使用。你不招人、不建 agent、不执行图。


🚨 发 JSON 的铁律（先读这条，否则你会陷入死循环）
本环境的工具调用在解析带多重双引号的 bash 命令时会崩溃，导致你反复"修格式"直到进程被杀。
任何带 JSON body 的请求，一律先把紧凑单行 JSON 写进 /tmp/*.json 文件，再用 curl -d @文件 发送。
JSON 里不许出现真实换行符，不许内联在 command 参数里。


1. 读候选骨架（Step 2）
ls system/work-graph-templates/
for f in system/work-graph-templates/*.json; do echo "=== $f ==="; cat "$f"; done


永远以 ls 的实际结果为准逐个读，目录里可能有比下表更多的文件。选型只看每份的 whenToUse。


文件
宿主 org node
节点链


planner.json
规划类（org-planner）
brd → prd → sdd → benchmark → validator


executor.json
执行类，单交付物
impl → test → validator


executor-fanout.json
执行类，可并行拆分
split → (impl/test)×N → merge → integration → validator


validator.json
org-validator 专用（强制）
validator-triager → benchmark-validator → testdata-validator


system/work-graph-templates/README.md 有完整的字段说明与占位符清单，规划前值得读一遍。
2. 读可引用的 system agent 本体（Step 3）
node bin/lemon.js company templates
curl -s http://localhost:3010/api/company/<公司ID>/agents


前者是全局可用的 agent 模板（• <id> — <description> 每行一个），后者是这家公司已有的 agent。
这是唯一权威的「哪些本体真的存在」清单——骨架 JSON 里写的 systemAgentId 只是建议，
{{implAgent}} 这类占位符更是必须替换的空位。

找不到理想本体的三条出路见 agent.md Step 3。你不创建 agent，那是 agent-creator 的活。
3. 读上游留下的共享产物（Step 1）
ls -R data/companies/<公司ID>/runs/<rootRunId>/artifacts/


artifacts/ 是 root run 级的任务级共享产物区，跨 org node 只读可见——
goal-benchmark.json / goal-test-data/ / goal-test-script/ 这些验收契约就在这里。


读
写


artifacts/
✅ 任意层级只读
⚠️ 只有你在图里显式标了 writesArtifacts 的节点才有权写


别的节点的 nodes/{其他}/
❌ 禁止
❌


「下游只能看到上游的契约，看不到实现」——别让你画的节点去重造 artifacts/ 里已经有的产物。
4. 落盘规划记录（Step 5，别忘）
mkdir -p workspace


然后用文件写入工具写 workspace/workgraph-plan-<taskId>.md，六节结构见 agent.md Step 5。
图 + 理由 + 五项校验自查，三样缺一不可——这是人类事后复核你判断力的唯一线索。
5. 提交图（Step 6）
先写文件（用文件写入工具写 /tmp/workgraph-<taskId>.json，单行紧凑 JSON）：
{"ownerOrgNodeId":12,"taskId":"T-xxx",
 "nodes":[{"nodeName":"org-coder-impl","systemAgentId":"coder"},
          {"nodeName":"org-coder-test","systemAgentId":"unit-tester"},
          {"nodeName":"org-coder-validator","systemAgentId":"coder-validator"}],
 "edges":[{"from":"org-coder-impl","to":"org-coder-test","condition":"success"},
          {"from":"org-coder-test","to":"org-coder-validator","condition":"success"},
          {"from":"org-coder-test","to":"org-coder-impl","condition":"fail","edgeKind":"backward"},
          {"from":"org-coder-validator","to":"org-coder-impl","condition":"fail","edgeKind":"backward"}]}


再发送：
curl -s -X POST http://localhost:3010/api/company/<公司ID>/work-graphs \
  -H "Content-Type: application/json" \
  -d @/tmp/workgraph-<taskId>.json


字段约定：


字段
说明


ownerOrgNodeId
宿主 org node 在 org_graph_nodes 里的 id，首轮消息会给


goalId / taskId / okrNodeId
三者基数不同、不可混用（27-NAMING §四）：goal 唯一、task 多个、okr 是长周期度量树节点


nodes[].nodeName
必填，图内唯一，带宿主 org node 全名前缀


nodes[].systemAgentId
引用的本体，不带前缀；省略时默认等于 nodeName（几乎总该显式写）


nodes[].nodeKind
"agent_call"（默认可省略）\


edges[].from / to
用节点名，不是 id（图还没落库，你手里没有 id）


edges[].condition
"success" \


edges[].failReason
仅 fail 边可带；省略即为兜底边


edges[].edgeKind
"forward"（默认可省略）\


400 的处理见 agent.md Step 6 的规则对照表：errors[].rule 取值为
acyclic / single-entry / reachable / backward-labeled / fail-fallback-edge / schema / reference。
读懂 → 改图 → 重试，最多 5 轮。

若端点返回 404（引擎侧路由尚未上线）：不要重试、不要绕道写数据库。
把同一份 JSON 原样写到 workspace/workgraph-<taskId>.json，在 Step 7 汇报这个路径。
6. 提交前自查五项校验（可选但强烈建议，省一轮 400）
引擎用的就是这个函数，你可以先在本地跑一遍：
node -e "
const {validateWorkGraph}=require('./server/services/work-graph-db.js');
const t=JSON.parse(require('fs').readFileSync('/tmp/workgraph-<taskId>.json','utf-8'));
console.log(JSON.stringify(validateWorkGraph(t.nodes,t.edges),null,1));"


{"ok":true,"errors":[]} 才提交。这一步只做结构校验，不检查占位符有没有替换干净——
{{implAgent}} 在校验器眼里是个合法字符串，它照样返回 ok。占位符靠你自己看。


你不该用的工具


别用
为什么


POST/PATCH /api/company/:id/org-graph
org graph 是上一层，归 orggraph-planning / HR。你只画 work graph


node bin/lemon.js company hire / fire
你不招人也不辞人。图上的节点是引用已有本体，不是新建员工


直接写 data/ 下的 sqlite / json
绕过五项校验就是把非法图塞进系统


POST /api/graph-runs/:id/{start,next,...}
执行是引擎的活。你交出 workGraphId 就下班


对已落库的 work graph 做任何修改
work graph 生命周期是一次性的，要改就重新规划一张，没有增量补丁


task transition
绝对不要。它是 base 四段式的换阶段命令，与图流转是两层状态机（agent.md 约束四）