# cmdc_orchestrator Changelog
本项目遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/) 与
[Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/) 规范。
## [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
- `CMDCOrchestrator.execute/2` 新增 `%WorkflowSpec{}` 输入分支；旧 `%DAG{}`
分支不变。
- `CMDCOrchestrator.Executor` 节点分发从硬编码 `case type` 收敛到
`Node.Registry`。
- `cmdc_orchestrator` 显式声明 `:nimble_options` 与 `:telemetry` 依赖。
### 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`）+ 串行执行器。