← 返回文档总览

编排设计规范（Orchestration / .orch.json）

本文档定义 WeGirlOffice 编排文件（.orch.json）的设计规范与最佳实践。 适用于在插件中编写、评审、演进编排的所有场景。 全文示例均来自真实在用编排：

  • plugins/standard-orch/标准模式.orch.json —— 计划 → 人审 → 执行闭环（Plan-Review-Execute）
  • plugins/standard-orch/PTC 模式.orch.json —— 标准模式的 PTC 变体（节点级 toolMode）
  • plugins/static-site/SEO巡查.orch.json —— MCP 数据采集流水线（业务规则前置 + 结构化回传）

目录

  1. 文件结构契约
  2. 节点两大类：flow 与 config
  3. 三种骨架模式（真实示例拆解）
  4. 变量与模板规范
  5. 边（edges）设计规范
  6. 提示词与工具授权规范
  7. 收尾链与回传 UI
  8. 命名与可读性
  9. 演进策略：复制-定向改造
  10. 发布前自检清单

1. 文件结构契约

每个 .orch.json 必须满足以下顶层结构（formatVersion 2）：

{
  "__type": "agent-orchestration",
  "__formatVersion": 2,
  "__main__": {
    "name": "编排名（中文，见名知义）",
    "nodes": [ /* 见 §2 */ ],
    "edges": [ /* 见 §5 */ ]
  },
  "visibility": "sparkle",
  "sparkleFor": "ai-button 绑定键（可选）"
}

规则：

2. 节点两大类：flow 与 config

编排图里的节点分两类，职责必须分清：

类别 职责 典型 type 数据流
flow 节点 参与主数据流，处理/加工/传递内容 start / input / context / llm / mcp / composite / human / memory / snapshot / tokenMeter / code / output / wegirl-output / end 串联在 start→…→end 主链上
config 节点 提供配置/资源，不加工内容 config / mcp-config / kb-config / comfy-config / checkpointer / memory-storage-* 用边「挂」到消费节点上，不接主链

关键约定：

每个节点的 config.logMode 约定：

3. 三种骨架模式（真实示例拆解）

3.1 骨架 A：计划 → 人审 → 执行闭环（标准模式）

适用：改动不可逆资源（写文件、发消息）前的任务型编排。

start → input → tokenMeter → memLoad → ctx
  ctx ──(planModeEnabled == true)──→ planComposite ──→ review ──┐
  ctx ──(planModeEnabled != true)──→ planExec                   │
  review(approve) ──→ planExec → output → memSave → snapshot → end
  review(revise, count<5) ──→ planComposite（回到规划）

设计要点（全部对应 标准模式.orch.json）：

  1. 规划与执行职责分离：planComposite（composite，cnRef=ReAct 循环）的 agent 只授权只读工具（Read/Grep/Glob/ListDir/Plan），system 明令「禁止 Write/Edit/Shell/SpawnSubagent」；planExec 才持有写能力。最小权限是铁律：能只读规划的阶段绝不给写工具。
  2. 人审节点 human（mode=decision）：varName: "review" 收集决策；counterVar: "reviseCount" + counterMax: 5 限制修订轮数——凡是允许「打回重做」的环，必须配计数上限，否则存在无限修订风险。
  3. 条件边互斥完备：vars.planModeEnabled == true / != true 两条边覆盖全部取值，任何输入都有唯一去路。
  4. 收尾链固定：output → memSave → snapshot → end（见 §7）。
  5. composite 覆盖：cnRef 引用复合编排，overrides 按「节点 id → config 局部覆盖」合并（overrides.agent.system/prompt/outputVar/tools、overrides.loopDetect.maxLoops）。只覆盖差异项，不整段重写。
  6. extraTools 用于在基础工具之外追加（标准模式执行节点追加了 ComfyUIImage）。

3.2 骨架 B：PTC 变体（PTC 模式）

PTC 模式.orch.json 是标准模式的最小定向变体，图结构完全相同（start/input/tokenMeter/memory/ctx/review/执行/output/memSave/snapshot/end），只改了两处：

  1. 节点级 toolMode：执行 composite 的 overrides.agent.toolMode: "ptc"，让该节点注入 run_code 程序化工具调用能力（简单操作走原生工具，批量/循环/分支/并发组合走 run_code，await tools.<工具名>(args)）；
  2. system 重写工作方式：把「什么该写成 run_code」的判定标准直接写进提示词——「如果你打算跑的 shell 命令里带了管道/循环/多目标，那就该写成 run_code 程序」；并约定「关键中间结果务必 console 出来，结尾 return 汇总对象」「每次提交带 description」。

设计要点：

3.3 骨架 C：MCP 数据流水线（SEO 巡查）

适用：对接外部系统采集数据 → 分析 → 结构化回传 UI 的周期性业务流水线。

start → input → director(context 业务规则) → gscAnalyze(mcp) → extractTodos(llm) → output(wegirl-output) → end
config ──→ gscConfig(mcp-config, servers=[gsc])

设计要点（全部对应 SEO巡查.orch.json）：

  1. 业务规则前置到 context 节点（id=director）：多账号隔离、配额保护、输出格式全部集中写在 context 模板里，下游节点只做执行——规则一处维护，多个执行节点引用；
  2. MCP 节点收敛调用面：serverRefs: ["gsc"] 限定服务器；maxCalls: 30 硬上限保护外部 API 配额；prefixToolNames: false 保持工具原名；system 里写明「优先/禁止/兜底」三级工具策略（如：禁止预先调 list_sites，仅报错时兜底一次）；
  3. 结构化提取独立成 llm 节点（id=extractTodos）：分析节点输出人类可读报告，另一个 llm 节点专职把报告压成一行 JSON（summary/kpi/pages/todos），system 里给出精确 JSON Schema + 「找不到的数据省略、禁止编造」——分析归分析、结构化归结构化，互不污染；
  4. 回传走 wegirl-output：source: "vars.report"，附 action（回调动作键）、mode/siteUrl/date/requestId 业务字段、todos/reportData（结构化数据，驱动 UI 自动生成待办）；
  5. 幂等参数显式传递：每次工具调用必须携带的 projectPath/account 等隔离参数，在 prompt 与 system 中反复钉死，防模型漏带。

3.4 选型速查

场景 骨架 参考文件
会写文件/发消息的任务执行 A：计划-人审-执行 standard-orch/标准模式
同上 + 批量工具组合提速 B：A 的 PTC 变体 standard-orch/PTC 模式
外部系统数据采集/巡查/回传 C：MCP 流水线 static-site/SEO巡查

4. 变量与模板规范

5. 边（edges）设计规范

  1. 每个非 start 节点必须可达；主链从 start 出发，终点是 end；
  2. 条件边互斥且完备：同一源节点的所有 condition 合起来必须覆盖全部情况（== true / != true；decision == "approve" / == "revise" && counter < max）——用 != 而非枚举反例，避免新增取值时漏边；
  3. config 节点的边只用于「供应」，不出现在主链上（见 §2）；
  4. 修订回边必须带计数条件（vars.reviseCount < 5），并由 human 节点的 counterVar/counterMax 驱动；
  5. 不要为「看起来直观」增加无语义的中间节点；图的可读性靠 id 命名与布局（position 不重叠、主链从左到右、config 区在上方）。

6. 提示词与工具授权规范

每个智能体节点（llm / composite.agent / mcp）的 system + prompt 按此分工：

7. 收尾链与回传 UI

任务型编排的收尾链固定为：

执行节点 → output → memSave → snapshot → end

8. 命名与可读性

9. 演进策略：复制-定向改造

新增编排优先从最接近的存量编排复制，再做最小定向差异：

  1. 复制 → 改 name 与文件名；
  2. 删除用不到的 config 节点及其边（PTC 模式相比标准模式删掉了 comfy-config）；
  3. 只改目标差异点（toolMode / system / 工具白名单 / 骨架节点），图结构能不动就不动；
  4. 改完重跑/试运行一轮，确认聊天流节点顺序、人审计数、收尾链符合预期；
  5. 同步 dist（编排 JSON 改源必同步 dist 才会生效）。

反模式：从零手写一张「看起来类似」的图——id 命名漂移、收尾链缺环、条件边不完备，都是这么引入的。

10. 发布前自检清单