# OrgGraph Planning 工具箱

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

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

---

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

```bash
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`** 字段。想一次读完可以：

```bash
for f in system/org-graph-templates/*.json; do echo "=== $f ==="; cat "$f"; done
```

## 2. 读可招角色清单（Step 3）

```bash
node bin/lemon.js company templates
```

输出每行是 `• <id> — <description>`。这是**唯一权威**的"哪些角色能直接招"清单，
模板 JSON 里写的角色名只是建议，必须拿这份清单核实。

## 3. 提交图（Step 6）

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

```jsonc
{"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` 边上不许写（上面第三条边就是空的，那不是漏了）。

**再发送**：

```bash
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"` \| `"fail"`，必填 |
| `edges[].edgeKind` | `"forward"`（默认可省略）\| `"backward"` |
| `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 轮。

**回读确认**：

```bash
curl -s http://localhost:3010/api/company/<公司ID>/org-graph
```

（GET 返回的边用**数字节点 id**，与提交时的角色名不同，属正常。）

## 4. 按拓扑序招聘（Step 7）

```bash
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` 填充——**这是预期行为，继续往下招**。

招完核对人齐：

```bash
curl -s http://localhost:3010/api/company/<公司ID>/status
```

## 5. 关掉自己的心跳（Step 8）

先写 `/tmp/hb-off.json`，内容一行：`{"enabled":false}`，再：

```bash
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 读不到。

```bash
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` | 公司已经建好了，你是被它触发的 |