README.md 7.38 KB

Edit Raw Blame History


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 §4.6
命名规范：docs/todo/system-design/27-naming-conventions.md §三


这是起点集合，不是穷举枚举。 模板不是代码里的 switch(type)——加一种公司类型只需往本目录扔一个
JSON 文件，不改任何代码。同样，模板里的角色名只是建议，orggraph-planning 必须核实是否真有可招模板，
没有则走「从 system/templates/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），
是因为这两类公司暂时还没有稳定可区分的归因取值域——需要时按上表的形状加边即可，加边不改代码。
文件格式
{
  "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。

加一个新模板

新建 system/org-graph-templates/{id}.json，按上面的格式填。
角色名遵循 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。
避开这 6 个命名冲突 id：agent-creator / digester / evolver / evolver-youtube-crawler /
hunter / innovator。它们在 system/agents/ 与 system/templates/ 下同名但内容可能不同步，
引用了会产生「该读哪份 agent.md」的歧义。
orggraph-planning 这类基础设施 agent 不要出现在图里——它规划图，但自己不是图上的节点。
人工验算 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（否则归因产出图上没有的取值时会落到死路） |


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