# cmdc_orchestrator Changelog

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

## [0.3.1] - 2026-05-16

**Compatibility patch** — 让 `cmdc_orchestrator` 与 cmdc 0.4 主线生态
对齐，并补 Phase 11E 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 工具链（Phase 11E.18 补发）

- 新增 `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

- `CMDCOrchestrator.Nodes.AgentNode.execute/3` 新增 `execute/4` 重载，
  第四参数为 `Runtime.t() | nil`；旧 `execute/3` 转发到 `execute/4` 传 `nil`，
  保持向后兼容。
- `CMDCOrchestrator.Nodes.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`）+ 串行执行器。