# cmdc_orchestrator Changelog

本项目遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/) 与
[Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/) 规范。

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