tools.md 5.79 KB

Edit Raw Blame History


OrgGraph Planning 工具箱
你的全部工作靠五类工具完成：读模板 → 读角色清单 → 提交图 → 招聘 → 关心跳。
按 agent.md 的八步工作流顺序使用。


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


1. 读候选骨架（Step 2）
ls system/org-graph-templates/
cat system/org-graph-templates/dev.json
cat system/org-graph-templates/content.json
cat system/org-graph-templates/ops.json


永远以 ls 的实际结果为准逐个 cat，目录里可能有比上面更多的文件。
选型只看每份的 whenToUse 字段。想一次读完可以：
for f in system/org-graph-templates/*.json; do echo "=== $f ==="; cat "$f"; done

2. 读可招角色清单（Step 3）
node bin/lemon.js company templates


输出每行是 • <id> — <description>。这是唯一权威的"哪些角色能直接招"清单，
模板 JSON 里写的角色名只是建议，必须拿这份清单核实。
3. 提交图（Step 6）
先写文件（用文件写入工具写 /tmp/orggraph-<公司ID>.json，单行紧凑 JSON）：
{"nodes":[{"roleName":"org-planner"},{"roleName":"org-coder"},{"roleName":"org-validator"}],
 "edges":[{"from":"org-planner","to":"org-coder","condition":"success","produces":["prd"]},
          {"from":"org-coder","to":"org-validator","condition":"success","produces":["artifact"],"needs":["prd"]},
          {"from":"org-validator","to":"org-coder","condition":"fail","edgeKind":"backward"}]}


produces / needs 就是 agent.md 约束五那两个键。forward 边上少了它们，
下游 org node 派活时提示词里就没有上游产物的路径 —— 先读约束五再写这份 JSON。
backward 边上不许写（上面第三条边就是空的，那不是漏了）。


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


字段约定：


字段
说明


nodes[].roleName
必填，角色名，同一公司内唯一。也可直接写成字符串 "org-coder"


nodes[].systemAgentId
可省略，省略时默认等于 roleName


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


edges[].condition
"success" \


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


edges[].produces
数据契约：这条边的上游 org node 会交出哪些 kind。见约束五，forward 边基本都要写


edges[].needs
数据契约：下游要吃哪些 kind，而产出方不是紧邻的上游 org node（隔节点中继）。见约束五


kind 取值域（自创会被 rule=schema 打回）：
brd / prd / sdd / acceptance / contract / artifact / log。拿不准用 artifact。

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

回读确认：
curl -s http://localhost:3010/api/company/<公司ID>/org-graph


（GET 返回的边用数字节点 id，与提交时的角色名不同，属正常。）
4. 按拓扑序招聘（Step 7）
node bin/lemon.js company hire --id <公司ID> --role <角色名> --type executor --name "<中文岗位名>"


顺序：先入口节点，再沿 forward 边逐层往下。纯 backward 边指向的节点不需要重复招。
--type 一律用 executor（org node 是执行流上的节点，不是 cxo）。
--name 给人看的中文岗位名，省略时默认等于 --role。
返回 hired_from_template = 模板已存在，走虚拟引用寻址；
走继承分支 = 模板库没有此角色，系统自动从 system/agents/_base/ 继承四段式骨架
再触发 agent-creator 填充——这是预期行为，继续往下招。


招完核对人齐：
curl -s http://localhost:3010/api/company/<公司ID>/status

5. 关掉自己的心跳（Step 8）
先写 /tmp/hb-off.json，内容一行：{"enabled":false}，再：
curl -s -X PUT http://localhost:3010/api/company/<公司ID>/agents/orggraph-planning/heartbeat \
  -H "Content-Type: application/json" -d @/tmp/hb-off.json

6. 落盘规划记录（Step 5，别忘）
落点是公司共享 workspace：提示词开头「运行时坐标」里「你的交付物必须写到」那一行
给的绝对路径（下面记作 $W）。cwd 是会被清理的任务态目录，写相对路径 = org-planner 读不到。
mkdir -p $W


然后用文件写入工具写 $W/orggraph-plan.md，六节结构见 agent.md Step 5。
图 + 理由 + 四项校验自查 + 数据契约自查，四样缺一不可——这是人类事后复核你判断力的唯一线索。


你不该用的工具


别用
为什么


PATCH /api/company/:id/org-graph
增量修改是 HR 的活。你只做一次整体写入


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


node bin/lemon.js company fire
你不辞退任何人


task dispatch 给 innovator 催训练
训练是可选的后置步骤，不在你的工作流里


company create
公司已经建好了，你是被它触发的