cmdc_orchestrator Changelog

Copy Markdown View Source

本项目遵循 Semantic Versioning 与 Keep a Changelog 规范。

[0.5.0] - 2026-05-31

Run API + 事件账本 + 条件分支接缝 — 在 v0.4 WorkflowSpec 之上补齐 企业 Run Console、Trace Viewer 和 Workflow Designer 初版需要的运行句柄、 RunStore、事件回放、可取消能力和确定性分支语义；仍不承诺跨进程长期恢复, durable resume 留给 v0.6。

Added

  • CMDCOrchestrator.Run / RunState / NodeRun / RunEvent
    • Run 状态覆盖 :queued / :running / :waiting / :succeeded / :failed / :cancelled
    • NodeRun 记录 input snapshot、output data、signal、error、attempts 和时间戳
    • RunEvent 默认裁剪 prompt / chunk / result 等大字段
  • CMDCOrchestrator.RunStore behaviour 与 RunStore.ETS
    • 覆盖 save/load/update/list run、append/list event、upsert/list/update node run
    • ETS 后端用于开发和测试,不引入 Ecto / Oban
  • 异步 Run API
    • start_run/2
    • await_run/2
    • status/2
    • cancel/3
    • events/2
    • run_sync/2
  • Run event ledger
    • run.started
    • run.completed
    • run.failed
    • run.cancelled
    • orchestrator.node.started
    • orchestrator.node.completed
    • orchestrator.node.failed
    • orchestrator.node.skipped
  • CMDCOrchestrator.Nodes.ConditionNode
    • 支持 eq / neq / gt / gte / lt / lte / contains / not_contains / is_truthy / is_falsy
    • 返回 "true" / "false" signal
    • dry_run/2 会真实求值 condition,但不触发 Tool / Agent 副作用
  • 通用 signal-driven edge
    • EdgeSpec 新增 :signal / :when,并保持旧 :branch 兼容
    • Executor 按上游节点 output signal 选择下游边
  • output_key context merge
    • 节点输出可写入 Run.context_data
    • downstream condition 可用 {{metric.score}} 读取上游 output_key

Changed

  • CMDCOrchestrator.Application 新增 Run TaskSupervisor 与 Registry,用于异步 run 生命周期管理。
  • WorkflowSpec.dry_run/2 报告新增节点 signal、status 和更可解释的 final_context。
  • cmdc_orchestrator 版本提升到 0.5.0。

Tested

  • 91 个测试全部通过,新增覆盖 RunStore、Run API、cancel、event replay、 condition/signal edge、output_key context merge 和 dry_run v2。

[0.4.0] - 2026-05-31

WorkflowSpec + 产品化接缝 — cmdc_orchestrator 从短任务 DAG 执行器 升级为企业 AgentOps Workflow Runtime 的配置与事件底座；旧 %DAG{} / execute/2 用法保持兼容。

Added

  • CMDCOrchestrator.WorkflowSpec / NodeSpec / EdgeSpec
    • 支持 schema_version、workflow_id、version、mode、nodes、 edges、policies、metadata
    • validate/1 覆盖 node id 唯一、edge 引用、DAG 环路、router branch、 节点 preflight、孤岛节点 warning 和不可持久化配置
    • dry_run/2 返回无副作用执行路径和模拟 final_context
    • to_dag/1 把 WorkflowSpec 适配回旧 %CMDCOrchestrator.DAG{}
  • CMDCOrchestrator.Node behaviour 与 CMDCOrchestrator.Node.Registry
    • 内置节点统一声明 schema/0、preflight/2、execute/3、 serializable?/0
    • Executor 改为 registry 分发,支持应用配置注册自定义节点
  • CMDCOrchestrator.Nodes.ToolNode
    • 支持 tool_name + agent_opts[:tool_registry] 调用已注册 CMDC.Tool
    • 支持 {{node_id.field}} 从上游结果渲染 args
    • 工具失败返回结构化 reason
  • CMDCOrchestrator.Nodes.EvalGateNode
    • 支持本地阈值检查,也可委托外部 gate_module.check/2
    • 适合 RAG preset / AgentSpec / Workflow 发布门禁
  • CMDCOrchestrator.Templates
    • 提供 contract_review、order_delay_diagnosis、ticket_triage、 rag_release_gate、debate_review 五套 JSON-ready 模板
  • Telemetry 事件

    • [:cmdc_orchestrator, :run, :start | :stop | :exception]

    • [:cmdc_orchestrator, :node, :start | :stop | :exception]

    • metadata 保持小而结构化,不包含 prompt/chunk/完整工具输出
  • example/workflow_spec_demo.exs 展示 WorkflowSpec validate → dry_run → execute 路径。

Changed

Tested

  • 83 个测试全部通过,新增覆盖 WorkflowSpec、dry_run、registry 自定义节点、 ToolNode、EvalGateNode、Telemetry 和内置模板 mock provider 执行。

[0.3.2] - 2026-05-18

Patch release — repository URL normalization + documentation cleanup. No code changes, no behavior changes.

  • Repository URL → https://github.com/tupleyun/cmdc_orchestrator
  • CHANGELOG sections rewritten to neutral technical descriptions

[0.3.1] - 2026-05-16

Compatibility patch — 让 cmdc_orchestrator 与 cmdc 0.4 主线生态 对齐，并补 benchmark 工具链（v0.3.0 后 commit 但未发布）。

Changed — cmdc 依赖范围升级

  • {:cmdc, "~> 0.2"} → {:cmdc, "~> 0.4"}
    • 背景：v0.2/v0.3 期间 cmdc_orchestrator 一直锁 ~> 0.2， 意味着 ~> 0.2 严格语义 >= 0.2.0 and < 0.3.0 阻塞与 cmdc 0.3/0.4 共存。用户写 {:cmdc, "~> 0.4"} + {:cmdc_orchestrator, "~> 0.3"} 会触发 Hex 版本冲突
    • 兼容性核实：本库使用的 cmdc API（create_agent/1 / stop/1 / subscribe/1 / unsubscribe/1 / prompt/2 / session_id/1）全部从 v0.1 起稳定；v0.3 #B21 facade tuple 改造 本库已用 with {:ok, pid} <- CMDC.create_agent(...) 兼容路径
    • 无运行时行为变更

Added — Benchmark 工具链

  • 新增 benchmark/dag_layered_order.exs — 100 节点 DAG layered_order 计算 Benchee suite，用于 release 前性能基线对比
  • benchmark/README.md — benchmark 运行指引
  • :benchee, ~> 1.3 加入 dev / test 依赖

Migration

老用户不受影响：

  • 仍用 cmdc 0.2 → 锁 {:cmdc_orchestrator, "0.3.0"} 即可
  • 想用 cmdc 0.4 → 升级到 {:cmdc_orchestrator, "~> 0.3.1"} 或 直接 {:cmdc_orchestrator, "~> 0.3"}（Hex 会自动选最新 0.3.x）

[0.3.0] - 2026-04-25

SubAgent 原生支持 + Multi-Agent 协作 (Debate / Hierarchy / Router LLM) —— 对齐 Agentic Design Patterns 第 7 章 Multi-Agent Collaboration。

Added

  • CMDCOrchestrator.Runtime —— DAG 全程共享的运行时容器，使用 ETS registry 管理 Agent 会话生命周期。提供 start/1、shutdown/1、 get_or_create_pool/3、start_subagent/2、untrack/2、session_count/1 六个 API。
  • CMDCOrchestrator.Nodes.AgentNode 新增 三种执行模式（config[:mode]）：
    • :standalone（默认） —— 每次调用一次性 ephemeral 会话，行为与 v0.2 完全一致。
    • :pool —— 同 pool_key 的多次调用复用同一会话，对话历史天然累积，适合 Debater 这类需要"角色记忆"的节点。
    • :subagent —— 通过 Runtime 注册一个独立长生命周期会话，对外行为类似 CMDC.SubAgent.Supervisor，由 Runtime 在 DAG 结束时统一回收。
  • CMDCOrchestrator.Nodes.DebateNode —— 多 Agent 辩论模式：
    • 多轮辩论（max_rounds）+ Judge 最终裁决；
    • 每轮内部按列表顺序顺序执行，确保后发言者能看到本轮先发言者的内容；
    • consensus_fn 可选回调，根据已完成轮次提前终止；

    • 错误结构化透传 {:debate_failed, :debater_round | :judge, reason}。

  • CMDCOrchestrator.Nodes.HierarchyNode —— Manager / Workers / Synthesizer 三段式协作：
    • 可选 Manager 把目标拆成子任务（缺省 → 直接 split_fn 切 goal，再缺省 → 按换行切分）；
    • :round_robin 与 :pairwise 两种 Worker 任务分配策略；
    • Workers 通过 Task.async_stream 并行（:max_parallel 受控）；
    • 可选 Synthesizer 汇总所有 Worker 输出生成最终答复。
  • CMDCOrchestrator.Nodes.RouterNode 新增 "llm" 策略：
    • 用 LLM 在 branches 中选择分支；
    • 自带 default_system_prompt/1 与简洁 prompt；
    • 输出截首行 + 大小写无关 + 子串匹配；任何解析失败或 Provider 异常自动 走 :fallback（默认 "default"），日志降级为 Logger.warning/2。
  • CMDCOrchestrator.DAG.node_type 类型扩展，新增 :debate / :hierarchy。
  • CMDCOrchestrator.Executor 全程透传 Runtime：在 DAG 开头 Runtime.start/1， 结束时 Runtime.shutdown/1（即使中途出错也保证清理），并把 runtime 透传给 所有节点 execute/4 调用。
  • example/multi_agent_debate_demo.exs —— 4 段式可独立运行的演示脚本：
    1. DebateNode 直接调用；2) HierarchyNode 三段式；3) RouterNode (llm) + fallback；4) DAG 集成（Router → Debate / Skip 剪枝）。所有演示通过内嵌 Mock Provider 跑通，无需真实 LLM key。
  • test/support/mock_provider.ex —— 测试基础设施：constant/1、queue/1 （使用 :atomics 计数器线程安全）、failing/2、opts_with/2、cleanup/1。

Changed

  • AgentNode.execute/3 新增 execute/4 重载， 第四参数为 Runtime.t() | nil；旧 execute/3 转发到 execute/4 传 nil， 保持向后兼容。
  • RouterNode.execute/3 新增 execute/4 重载（第四 参数为 runtime），旧两个 arity 全部保留并降级转发。
  • CMDCOrchestrator.Nodes.AgentNode 中 run_on_pid/3 不再调用 CMDC.collect_reply/2，改为先 CMDC.subscribe/1 再 CMDC.prompt/2 再用 内部 await_reply_loop/2 直接接收事件。修复了 mock provider 极快回复时 :agent_end 事件先于订阅建立而被错过的竞态。

Tested

  • 67 个测试全部通过（--max-cases 1），包括：
    • runtime_test.exs —— pool 复用 / 死亡重建 / subagent 注册 / 计数；
    • agent_node_test.exs —— 三种 mode + retries + fallback 模型；
    • debate_node_test.exs —— 完整多轮 / consensus 提前终止 / 跑满 max_rounds / 错误透传 / topic dep 回退；
    • hierarchy_node_test.exs —— 完整三段式 / 无 manager / fixed tasks / 分配策略 / Manager 失败 / no_subtasks / dep 回退；
    • router_node_test.exs —— rule + random + LLM × (匹配 / 截首行 / 兜底 / Provider 失败) 全覆盖。

[0.2.0] - 2026-04-23

Added

  • 真并行执行：拓扑分层 + Task.async_stream，单层并行度由 :max_concurrency 控制，下游节点等到所有上游完成才启动。
  • Router 真剪枝：上游为 :router 节点 + 边带 :branch 标签时，仅 route 命中的分支会被激活，其它分支自动剪枝并向下传染。
  • CMDCOrchestrator.Nodes.AgentNode 节点级 Recovery：config[:retries] 控制重试次数，config[:fallback_model] 在所有重试耗尽后切模型再试一次。
  • :agent_node_failed 事件 / 透明结构化错误 %{node_id, reason, completed}。

[0.1.0] - 2026-04-22

Added

  • 初始版本：DAG 定义 + 拓扑排序 + 4 种节点类型（:agent / :aggregator / :router / :gate）+ 串行执行器。