# system/org-graph-templates/

Org Graph（公司级 workflow）的**骨架模板库**。

每个 `*.json` 是一种公司类型的执行流图起点。建公司时 `orggraph-planning` agent 会 `ls` 本目录、逐个读取、
对照各自的 `whenToUse` 选型，再结合公司目标（company-goal）与 `node bin/lemon.js company templates`
给出的可招角色清单，裁剪 / 替换 / 组合出这家公司真正的 org graph。

> 设计依据：[docs/todo/system-design/27-p2-org-graph.md](../../docs/todo/system-design/27-p2-org-graph.md) §4.6
> 命名规范：[docs/todo/system-design/27-naming-conventions.md](../../docs/todo/system-design/27-naming-conventions.md) §三

**这是起点集合，不是穷举枚举。** 模板不是代码里的 `switch(type)`——加一种公司类型只需往本目录扔一个
JSON 文件，**不改任何代码**。同样，模板里的角色名只是*建议*，`orggraph-planning` 必须核实是否真有可招模板，
没有则走「从 `system/agents/_base/` 元 agent 继承 + `agent-creator` 填充」的分支。

## 当前模板

| 文件 | id | 适用 | 节点链 |
|---|---|---|---|
| `dev.json` | `dev` | 交付可运行代码 | `org-planner → org-coder → org-validator` |
| `content.json` | `content` | 交付给人读/看的内容 | `org-planner → org-writer → org-validator` |
| `ops.json` | `ops` | 让已有系统持续正常运转 | `org-planner → org-monitor → org-validator` |

三张图同构：**规划 → 执行 → 验收**，验收失败回退到执行节点重做。**首尾两个节点在三张图里同名**
（`org-planner` / `org-validator`）——命名轴是「节点在哪一层图里」而不是业务领域，规划与验收本身不分领域，
差异全在中段的执行节点（`org-coder` / `org-writer` / `org-monitor`）。依据 27-NAMING §3.1。

### `org-validator` 的 fail 边怎么画

`org-validator` 判定任务未达成时该退回哪个节点，由它自己 work graph 里的归因节点（`validator-triager`）
产出的 `fail_reason` 决定，引擎按 27-P3/P4 §四.D.2.2 选边：
**先找 `fail_reason` 精确匹配的边 → 无匹配则退到没有 `fail_reason` 的兜底边 → 再无则是死路。**
因此**任何有 `fail` 出边的节点，必须至少留一条不带 `fail_reason` 的兜底边**（写入前校验第 5 项）。

`dev.json` 是唯一画了细分路由的模板：

| 边 | `failReason` | 含义 |
|---|---|---|
| `org-validator → org-planner` | `input_underspecified` | 规划给的约束不够，退回重新规划 |
| `org-validator → org-coder` | *（无，兜底）* | 其余一切情况：带失败上下文退回执行节点重做 |

**为什么 `impl_bug` 没有单独一条边**：三节点图里 `org-validator` 的 fail 边只有两个可选目标，而
`org_graph_edges` 的唯一索引是 `(company_id, from_node_id, to_node_id, condition)`——同一对 (from, to, fail)
只能存在一条边，没法既给 `org-coder` 画一条 `impl_bug` 边、又给它画一条兜底边。
把两者合并是**语义无损**的：`impl_bug` 的回退动作本来就是「该 agent 带 bug context 重做」，与兜底动作完全一致，
合并后 `impl_bug` 只是走了这条兜底边而已。反过来若把兜底放在 `org-planner` 一侧，则会与
`input_underspecified` 撞同一个 `to_node`，且默认行为会变成「一失败就推翻规划重来」，代价和爆炸半径都更大。

至于另外两个归因取值：`infra_flake` 由引擎原地重跑（§四.D.2.1），本就不需要边；`skill_defect` 属于 L4-company，
v1 定案是挂起等人工，也不该有自动边。

`content.json` / `ops.json` 只保留兜底边（`org-validator → 执行节点`，无 `failReason`），
是因为这两类公司暂时还没有稳定可区分的归因取值域——需要时按上表的形状加边即可，加边不改代码。

## 文件格式

```jsonc
{
  "id": "dev",                    // 必填，与文件名同名（不含 .json）
  "label": "开发型公司",           // 必填，给人看的中文名
  "whenToUse": "……",              // 必填，LLM 选型的唯一依据，写清楚适用场景 + 典型信号词 + 与其他模板的区别
  "nodes": ["org-planner", "org-coder", "org-validator"],
  "edges": [
    { "from": "org-planner",   "to": "org-coder",     "condition": "success" },
    { "from": "org-validator", "to": "org-planner",   "condition": "fail",
      "failReason": "input_underspecified", "edgeKind": "backward" },
    { "from": "org-validator", "to": "org-coder",     "condition": "fail", "edgeKind": "backward" }
  ]
}
```

- `condition`：`"success"` | `"fail"`，边的语义是**执行流**（上游出这个结果时流向下游），不是汇报关系。
- `edgeKind`：`"forward"`（默认，可省略）| `"backward"`。**指向拓扑序更早节点的边必须显式标 `backward`**。
- `failReason`：仅 `condition: "fail"` 的边可带，是失败的细分路由键（对应 `org_graph_edges.fail_reason` 列）。
  省略即为该节点的**兜底边**，每个有 fail 出边的节点必须恰好留一条。取值域**不由引擎约束**，
  由图的规划者与对应 validator 约定，推荐取值见 27-P3/P4 §四.D.2.2。

## 加一个新模板

1. 新建 `system/org-graph-templates/{id}.json`，按上面的格式填。
2. **角色名遵循 `org-{职能}`**（27-NAMING §3.1）。org graph 里的每个节点都带 `org-` 前缀，
   **不要按业务领域起前缀**（`code-` / `content-` / `ops-` 这类写法 v0.2 用过，已作废）——领域信息由 company
   本身承载，按领域命名会让 agent 池随「领域数 × 职能数」膨胀。也禁止裸用 `planner` / `coder` / `validator`。
   新公司类型只换中段职能，例如 `org-designer` / `org-researcher`。
   > 节点名 ≠ 本体名：节点叫 `org-validator`，它引用的 system agent 本体也叫 `org-validator`；
   > 但 work graph 里的节点才带父节点前缀（如 `org-coder-validator`），本体则是不带前缀的
   > `coder-validator`。见 27-NAMING §3.2。
3. **元 agent 不入图**：`agent-creator` / `org-innovator` / `innovator-hunt` / `innovator-digest` /
   `innovator-evolver` / `digester-youtube-crawler` / `evolver-youtube-crawler`。
   它们是造 agent / 训练 agent 的元 agent，产出是「一个新本体」而不是「任务的下一步」。
   > 这条的**理由在 2026-08-18 重写过**：原来说的是「这些 id 在 `system/agents/` 与
   > 旧的模板目录下各有一份、内容可能不同步」。28 号改造已合并成唯一注册表，
   > 歧义不存在了；且原清单里 `digester` / `evolver` / `hunter` / `innovator` 四个 id
   > 根本不存在（早已改名）。约束保留、理由与清单订正。
4. `orggraph-planning` 这类基础设施 agent **不要**出现在图里——它规划图，但自己不是图上的节点。
5. 人工验算 27-P2 §3.3 的四项校验（写入 API 也会校验，但模板先自查能省一轮 LLM 重试）：

   | # | 规则 | 怎么自查 |
   |---|---|---|
   | 1 | **无环**（只看 `forward` 边） | 把所有 `backward` 边划掉，剩下的边必须能排出拓扑序 |
   | 2 | **恰好一个入口** | 只数 `forward` 边的入度，入度为 0 的节点必须**恰好一个** |
   | 3 | **全可达** | 从入口沿 forward 边 BFS，必须覆盖 `nodes` 里每一个节点，不许有孤立节点 |
   | 4 | **回退边显式标注** | 任何 `to` 在拓扑序上早于 `from` 的边，必须带 `"edgeKind": "backward"` |
   | 5 | **fail 兜底边** | 有 `fail` 出边的节点，其中必须恰好有一条不带 `failReason`（否则归因产出图上没有的取值时会落到死路） |

6. 自验 JSON 能解析：
   ```bash
   node -e "['dev','content','ops'].forEach(f=>JSON.parse(require('fs').readFileSync('system/org-graph-templates/'+f+'.json','utf-8')))"
   ```