# WorkGraph Planning 工具箱

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

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

---

## 1. 读候选骨架（Step 2）

```bash
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）

```bash
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）

```bash
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，别忘）

```bash
mkdir -p workspace
```

然后用文件写入工具写 `workspace/workgraph-plan-<taskId>.md`，六节结构见 `agent.md` Step 5。
**图 + 理由 + 五项校验自查**，三样缺一不可——这是人类事后复核你判断力的唯一线索。

## 5. 提交图（Step 6）

**先写文件**（用文件写入工具写 `/tmp/workgraph-<taskId>.json`，单行紧凑 JSON）：

```jsonc
{"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"}]}
```

**再发送**：

```bash
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"`（默认可省略）\| `"subgraph"`（要再下钻一层图时才用） |
| `edges[].from` / `to` | **用节点名**，不是 id（图还没落库，你手里没有 id） |
| `edges[].condition` | `"success"` \| `"fail"`，必填 |
| `edges[].failReason` | 仅 `fail` 边可带；**省略即为兜底边** |
| `edges[].edgeKind` | `"forward"`（默认可省略）\| `"backward"` |

**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）

引擎用的就是这个函数，你可以先在本地跑一遍：

```bash
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` 约束四） |