CMDC Orchestrator

CMDC 多 Agent 编排引擎 — DAG 驱动的 Agent 协作。

cmdc_orchestrator 在 cmdc 之上提供「图驱动」的多 Agent 编排能力：把工作流描述成 DAG（节点 + 边），由执行器按拓扑顺序调度，并把上游节点的输出自动注入到下游节点的 prompt 中。

理论基石参考 Agentic Design Patterns 第 2 / 3 / 7 / 12 / 15 章（路由、并行化、多 Agent 协作、异常处理与恢复、Inter-Agent 通信）。

安装

monorepo 内部通过 path 依赖：

def deps do
  [
    {:cmdc_orchestrator, path: "../cmdc_orchestrator"}
  ]
end

核心概念

概念	说明
Orchestration	一个 DAG（有向无环图），定义节点和依赖
Node	DAG 节点，4 种类型：`:agent` / `:aggregator` / `:router` / `:gate`
Edge	节点间的数据流依赖 `%{from:, to:}`
Run	一次编排执行，按拓扑序调度

节点类型

`:agent`

启动一个 CMDC Agent 执行配置好的 prompt，自动把 dep_results 拼到 prompt 末尾作为「上游节点输出」上下文。

%{
  id: "research",
  type: :agent,
  config: %{
    prompt: "调研 AI Agent 最新进展",
    system_prompt: "你是研究员",
    max_turns: 5
  }
}

`:aggregator`

合并多个上游结果。三种策略："concat" 拼接 / "merge" 合并 map / "vote" 多数投票。

%{id: "merge", type: :aggregator, config: %{strategy: "concat"}}

`:router`

按规则分发到不同分支（v0.2 仅返回 route 标签，不剪枝 DAG；剪枝在 v0.3 实现）。

%{
  id: "classify",
  type: :router,
  config: %{
    strategy: "rule",
    rules: [
      %{pattern: "技术", branch: "tech_branch"},
      %{pattern: "商业", branch: "biz_branch"}
    ]
  }
}

`:gate`

质量检查点，criteria 全部通过才继续，否则中止整个 DAG。

%{id: "review", type: :gate, config: %{criteria: ["accurate", "concise"]}}

使用示例

dag = %CMDCOrchestrator.DAG{
  nodes: [
    %{id: "research", type: :agent, config: %{prompt: "调研 AI Agent"}},
    %{id: "write", type: :agent, config: %{prompt: "写一篇 800 字博客"}},
    %{id: "review", type: :gate, config: %{criteria: ["完整"]}}
  ],
  edges: [
    %{from: "research", to: "write"},
    %{from: "write", to: "review"}
  ]
}

{:ok, results} = CMDCOrchestrator.execute(dag,
  model: "openai:gpt-4o-mini",
  api_key: System.fetch_env!("OPENAI_API_KEY")
)

results["write"]

执行失败时返回结构化错误，方便上层 UI 聚焦失败点：

{:error, %{node_id: "review", reason: "门禁未通过: 完整", completed: %{...}}}

与 CMDC v0.2 的集成

:agent 节点支持透传 cmdc 0.2 的全部 Agent 选项：:user_data / :prompt_mode / :plugins / :tools / :provider / :model 等。未来版本计划接入：

CMDC.SubAgent：用 SubAgent 替代裸 create_agent → 自动获得 user_data 继承、prompt_mode 继承、监督树。
CMDC.Plugin.Builtin.Recovery：节点级 retry / fallback model。
CMDC.monitor/1：把 Agent 进程崩溃转化为结构化 {:cmdc_down, reason, ctx} 事件而非 raw EXIT。

开发

mix deps.get
mix test
mix format --check-formatted
mix compile --warnings-as-errors
mix credo --strict

路线图

v0.2 ✅ 基础 DAG 调度 + 4 种节点类型
v0.3 真并行（拓扑分层 + Task.async_stream）+ Router 真剪枝 + AgentNode Recovery
v0.4 SubAgent 监督树 + DAG 可视化导出 + Plugin 透传

详见 docs/dev/PLANNING.md（如已添加）。

许可

Apache-2.0