cmdc_orchestrator Changelog

Copy Markdown View Source

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

[0.6.0] - 2026-06-01

可恢复执行器 + policy / fork-join + human_task + AgentOps 集成契约 — 把 v0.5 的异步 Run API 从 TaskSupervisor 短任务推进为 gen_statem run process,并补齐企业 Run Console、Trace Viewer 与 Approval Center 需要的 恢复点、运行控制、暂停审批恢复协议和 Phoenix AgentOps 接入 contract。

Added

  • CMDCOrchestrator.RunExecutor
    • 基于 :gen_statem 的 run process；
    • 启动时 claim run,退出时 release lease；
    • 每个节点完成、等待、失败后写入 run snapshot；
    • 支持 executor 被 kill 后通过 resume_run/2 从 DAG snapshot 与 completed 结果恢复。
  • Run snapshot 字段扩展
    • current_layer
    • paused_at
    • claim_owner / claim_expires_at
    • idempotency_key
    • resume_cursor
    • retry_counters
    • branch_states
    • lock_version
  • RunState 新增 :paused。
  • RunStore 运行控制契约
    • compare_and_update_run/4
    • claim_run/4
    • release_run/3
    • get_idempotency/3
    • put_idempotency/4
  • CMDCOrchestrator.RunStore.Checkpoint
    • 复用 CMDC.Checkpoint.Backend 保存 RunStore 账本；
    • 可接 CMDC.Checkpoint.Backend.ETS/DETS 或 cmdc_memory_pg checkpoint backend；
    • 不引入 Phoenix / Ecto / Oban 依赖。
  • Run Console API
    • pause_run/3
    • resume_run/2
    • retry_run/2
    • retry_node/3
    • rerun/2
  • 节点级 policy
    • retries
    • timeout_ms
    • initial_delay_ms
    • backoff

    • on_error: :fail | :continue | :skip | :fallback | :emit_signal

    • fallback_output
  • :fork / :join 虚拟节点
    • branch-local context；
    • branch_states 账本；
    • join mode: :all / :any / :n_of_m；
    • fail strategy: :fail_fast / :wait_all / :tolerate；
    • WorkflowSpec validate 拒绝 dangling join、join 入边不足、嵌套 fork 和多 join 歧义。
  • DAG.snapshot/1 与 DAG.from_snapshot/1,用于 run 恢复时重建 workflow。
  • CMDCOrchestrator.HumanTask 与 CMDCOrchestrator.Nodes.HumanTaskNode
    • :human_task 可把 run 挂起到 :waiting；
    • 配置支持 title / description / input_schema / ui_schema / assignee_refs / approval_mode / required_count / timeout_ms / on_timeout / default_output / metadata；
    • 运行时生成 task_id / expires_at / correlation_id；
    • :human_approval / :approval / :human_task_node 导入别名归一化到 :human_task。
  • Human task 决策 API
    • submit_human_task_decision/4
    • complete_human_task/3
    • fail_human_task/3 / fail_human_task/4
    • expire_waiting_tasks/2
    • 支持 idempotency_key 防重复点击。
  • Human task 审批聚合
    • action: :approve / :reject / :request_changes / :progress；
    • mode: :single / :role / :any_of / :all_of / :quorum；
    • progress 只更新任务账本，不恢复 run；
    • 终局输出按 "approved" / "rejected" / "request_changes" / timeout signal 继续下游；
    • 非审批人、重复决策、过期决策返回结构化错误。
  • CMDCOrchestrator.AssigneeResolver behaviour
    • 仅约定 assignee_refs 解析边界；
    • 不内置 Accounts/Roles、通知、RBAC 或业务审计表。
  • Human task event ledger
    • human_task.created
    • human_task.decision_recorded
    • human_task.progress
    • human_task.completed
    • human_task.timeout
  • example/human_task_flow_demo.exs 展示 contract review flow、fork 分支中的 human_task、mock provider、mock approval 和 resume。
  • AgentOps 企业交付收口
    • guides/agentops_integration.md 定义 Phoenix 推荐表/索引、Workflow Designer JSON DSL、RunService/ApprovalService API、Trace Viewer/Gateway SSE 事件映射、 Skill Registry adapter、Oban/Temporal 边界和 Hive 迁移对照；
    • benchmark/workflow_runtime_baseline.exs 覆盖 50 节点 validate/dry_run、10 并发 run、condition 分支、fork/join、1000 事件分页 replay、Checkpoint payload 和 human_task suspend/resume baseline。

Changed

  • Runner.start/2 改为通过 DynamicSupervisor 启动 RunExecutor。
  • CMDCOrchestrator.Application 新增 CMDCOrchestrator.Run.Supervisor。
  • Node.Registry 注册 :fork / :join / :human_task。
  • WorkflowSpec.dry_run/2 对 :human_task 返回 status: :would_wait，不触发 人工审批副作用。
  • RunStore.ETS 与 RunStore.Checkpoint 的 list_events/2 支持 :limit、 :after_id / :cursor 和 :after_seq,供 Trace Viewer 长 run 分页回放。
  • RunStore.ETS.reset!/0 会先确保 ETS 表存在,避免并发 CI/benchmark 中临时 Task 首次建表后退出导致命名表消失。
  • HexDocs extras 增加 AgentOps 集成契约。

Tested

  • 新增覆盖 RunStore CAS / claim / idempotency、Checkpoint backend、pause/resume、 crash resume、retry exhausted、timeout fallback、error signal、fork/join 聚合和 WorkflowSpec fork/join validation。
  • 新增覆盖 human_task waiting、approval resume、progress、quorum、非审批人、 duplicate decision、request_changes signal、timeout default、fork 内等待恢复。
  • 新增覆盖 RunEvent 分页 replay。
  • 本地预检通过：mix format --check-formatted、mix compile --warnings-as-errors、 mix credo --strict、mix test、HEX_BUILD=1 mix hex.build。

[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）+ 串行执行器。