# Changelog

> 用户可见的版本变化摘要。完整 release notes 见
> [GitHub Releases](https://github.com/tupleyun/cmdc/releases)。

兼容边界与迁移代码见 [升级指南](upgrading.html)。

---

## 0.6.0 — 2026-05-25（**唯一 breaking change** + 5 项加性扩展）

> **唯一 minor breaking**:`CMDC.Sandbox.Local` `:virtual_mode` 默认 `false → true`,
> 路径越界（`..` / `~/` / 跨目录绝对路径）默认拦截。其他全部加性扩展。
>
> **务实裁剪**:核心 30+ EventBus 流式事件 / 完整 GroupSession `:llm_driven` /
> Plugin runtime attach/detach 等留 v0.6.x 按真实需求滚动加。详见底部
> 「Out of Scope」段。

### Breaking

- **`CMDC.Sandbox.Local` `:virtual_mode` 默认 `true`** —— 拒绝路径越界:
  - path 含 `..` (`"../etc/passwd"`)
  - path 以 `~` 开头 (`"~/.ssh/id_rsa"`)
  - 绝对路径解析后不在 `:working_dir` 内

  违反返 `{:error, "路径越界..."}`。`file_exists?/2` 在越界路径上返 `false`。

  **1 行 opt-out 回退老行为**:

  ```elixir
  CMDC.Sandbox.Local.read_file("../parent.txt",
    working_dir: dir,
    virtual_mode: false              # ← 显式回退到 v0.5 行为
  )
  ```

  自定义 `CMDC.Sandbox` behaviour 实现不受影响（virtual_mode 是 `Sandbox.Local`
  私有细节）。

  完整迁移指南见升级指南。

### 新能力 1 — 群体 Agent 协调（`EventBus.subscribe_group/2` + `group_id` 全链路）

多 Agent 编排 / SubAgent / Reviewer Pattern 场景的统一订阅维度,
集成方不必再为 N 个 session_id 各订阅一次。

- **`CMDC.Options.group_id :: String.t() | nil`** —— Agent 启动时声明所属群组;
  SubAgent 默认继承父 Agent `group_id`，也可显式覆盖
- **`CMDC.Agent.State.group_id` + `CMDC.Context.group_id`** —— 透传到 Emitter 广播路径
- **`CMDC.EventBus.subscribe_group(group_id, opts)`** —— 订阅一个群组下所有 Agent 的事件
  - 支持 `since:` / `types:` filter（与 `subscribe/1` 一致）
  - 同名重订阅幂等（不重复加 monitor）
- `{:cmdc_event, sid, event}` payload 不变，订阅方按 sid 区分来源

### 新能力 2 — `CMDC.Memory` `:tags` 一等公民 + `c:schema_version/0`

- **`CMDC.Memory.entry()` `:tags :: [String.t()]` 一等公民字段**（默认 `[]`） ——
  老 entry 写入时省略字段，backend 自动落 `[]`；`tags_*` filter 时视为不匹配
- **`search/3` filter 新增 `:tags_any` / `:tags_all`** —— entry.tags 与列表
  任一交集 / 全部包含
- **`c:schema_version/0` 可选 callback** —— Backend 标识 entry shape 版本;
  未实现 backend 默认返 `1`，`CMDC.Memory.resolve_schema_version/1` 安全读取
- **Backend 实现要求**:`store/3` 自动注入缺省 `:tags`，并为该字段建专用索引
  （PG GIN / ETS 二级索引）
- 配套 `cmdc_memory_pg 0.1.2` 升级 backend tags 列 + GIN 索引 + schema_version=2 迁移

### 新能力 3 — `Provider.Registry.register/2` `:resolver_fn` opt

多租户 production 部署常用 Cloak / Vault 做敏感凭据静态加密;
v0.6 加 `:resolver_fn` opt 让 Registry 在 `lookup/1` 时**懒解密**,
明文不入 ETS。

- **`Provider.Registry.register(profile, opts)` opts 新增 `:resolver_fn`** ——
  `(provider_opts) -> {:ok, resolved_opts} | {:error, reason}`
- **`Provider.Registry.lookup/1`** —— 命中 profile 时调用 `resolver_fn`;
  `{:error, _}` 时 emit `{:provider_resolver_error, ...}` fail-safe 保留老 profile
- 未传 `:resolver_fn` 时行为 100% 等同 v0.5（直接透传）

### 新能力 4 — `CMDC.update_plugin_opts/3` 长会话 Plugin 配置热更

长会话生产场景动态调整 Plugin 运行时参数（CostGuard 阈值随付费等级 /
HumanApproval 白名单运维期调整 / EventLogger 日志级别即时切换等），
无需停 Agent 重启。

- **`CMDC.update_plugin_opts(session, plugin_module, new_opts) :: :ok`** ——
  facade cast API，立即返回 `:ok`
- **行为语义**:
  - cast 入队 `state.pending_plugin_opts`
  - 同 plugin 多次更新 LWW（后写覆盖前写）
  - Agent idle 状态批处理 flush；running/streaming/executing_tools 走
    gen_statem `:postpone`，回 idle 后自动重投递
  - 每条 flush 先走 `:before_plugin_opts_update` Plugin hook（可被 abort/skip 拦截）
  - 通过 hook 后调用 plugin 的 `c:on_config_update/2`（若实现）或默认替换语义
- **`CMDC.Plugin` 加可选 callback `c:on_config_update/2`** ——
  `(new_opts, plugin_state) -> {:ok, new_state} | {:error, reason}`,
  未实现 plugin 走默认替换语义（keyword + map → `Map.merge`）
- **EventBus `{:plugin_opts_updated, %{plugin, success?, error, mode}}`** ——
  flush 完成事件，`mode` 取 `:callback | :default | :blocked`

### 新能力 5 — `CMDC.AuditEvent` 收敛版（15 EventBus + 18 telemetry + resolver + schema v2）

v0.5.4 引入轻量版 `from_turn/2` + 6 telemetry；v0.6 扩为收敛版。

- **`schema_version 1 → 2`** —— 加 `:tags :: [String.t()]` 字段（默认 `[]`),
  老 v1 消费者读 v2 兼容（忽略 `:tags` 字段即可）
- **`from_event/3`** —— EventBus 事件 → AuditEvent，覆盖 15 个核心事件:
  - 会话:`:agent_start` / `{:agent_end, ...}` / `{:agent_abort, ...}`
  - 审批:`{:approval_required, ...}` / `{:approval_resolved, ...}`
  - 子代理:`{:subagent_start, ...}` / `{:subagent_end, ...}`
  - 工具:`{:tool_execution_start, ...}` / `{:tool_execution_end, ...}` /
    `{:tool_blocked, ...}`
  - 系统:`{:compact_start, ...}` / `{:compact_end, ...}` / `{:model_switched, ...}`
  - 错误:`{:stream_error, ...}` / `{:error, sid, reason}`
- **`from_telemetry/4`** —— 老 6 事件 API 完整保留（3 元 arity），新增 12 事件:
  `plugin.pipeline.{start,stop}` / `plugin.crash` / `compactor.run.{start,stop}` /
  `checkpoint.{save,load}` / `subagent.{start,stop}` / `agent.hibernate.configured` /
  `provider.registry.{lookup,register}`
- **3 个 resolver 注入点** —— `:actor_resolver` / `:target_resolver` /
  `:tags_resolver`（fail-safe，抛异常自动 rescue 用默认值）
- **双轨等价** —— EventBus from_event ↔ telemetry from_telemetry,
  tool exec 双轨 action / target_id / metadata 一致
- **`from_turn/2` 命名稳定** —— 保留 v0.5.4 `"agent.turn.finished|aborted"`
  （不强行统一到 `"turn.stop"`，避免破坏已落库过滤条件）

### 兼容性 — 全加性，零破坏（除 Sandbox virtual_mode）

| 模块 / API | 老调用是否需要改 |
|---|---|
| `CMDC.subscribe/1` | 不需要（subscribe_group/2 是新增 API） |
| `Memory.entry()` 不含 `:tags` | 不需要（backend 自动注入 `[]`） |
| `Memory.search/3` 老 filter | 不需要（`:tags_*` 是新增 filter） |
| `Provider.Registry.register/2` 不传 `:resolver_fn` | 不需要（默认透传） |
| `Plugin` 不实现 `on_config_update/2` | 不需要（默认替换语义兜底） |
| `AuditEvent.from_turn/2` 老调用 | 不需要（命名稳定 + opts 第三参可选） |
| `AuditEvent.from_telemetry/3` 老调用 | 不需要（3 元 arity 完整保留） |
| `AuditEvent.schema_version 1 → 2` | 不需要（v1 消费者忽略 `:tags` 字段） |
| `Sandbox.Local` 隐式 `virtual_mode` | **需要**（1 行 opt-out 或重设 `working_dir`） |

### 测试增量

- 主库:1349 → **1449 tests + 21 doctests + 0 failures + 5 skipped + 1 excluded**（**+100** tests）
- `cmdc_memory_pg`:8 → **18 tests + 0 failures**（**+10** tests）

### Out of Scope（v0.6.x patch 路线图，按真实反馈滚动加）

- ❌ **AuditEvent 30+ 流式 / 业务事件全集映射**（`:message_delta` / `:thinking_delta` /
  `:status_update` / `:tool_calls` / `:context_overflow` / `:retry` 等）——
  v0.6 仅覆盖核心 15，剩余按真实反馈 v0.6.x 滚动加；集成方可用
  resolver 自扩展
- ❌ **完整 `GroupSession` `:llm_driven` turn_policy** —— 行业无成熟参考,
  需 ≥3 集成方真实需求触发；v0.6 仅完成 `subscribe_group/2` 订阅维度
- ❌ **Plugin runtime attach/detach** —— Plugin 间互引用 / 启动序列依赖比 Tool 复杂得多,
  按需 RFC 后落地；v0.6 仅完成「同 plugin opts 热更」

---

## 0.5.4 — 2026-05-25

**Patch release** — 三项加性增强(ContentPolicy 真 LLM judge / EpisodicMemory 多租户严格模式 / AuditEvent helper)。
**全加性扩展,零破坏** —— 不配置新选项时行为完全等同 0.5.3。

### 新能力

- **`CMDC.Plugin.Builtin.ContentPolicy` 真 LLM-as-Judge** —— `:judge_model` 配置非 nil 时
  默认走 `ReqLLM.generate_object/4` 结构化 JSON 输出(此前默认仅启发式)
  - schema 强制三字段 `compliance_status` / `evaluation_summary` / `triggered_policies`
  - 新增 `:judge_timeout` opt(默认 8s)+ `judge_object_schema/0` 调试 helper
  - 优先级:`judge_fn`(注入)> `judge_model`(req_llm)> 启发式 fallback
- **`CMDC.Plugin.Builtin.EpisodicMemory` 多租户严格模式** —— `:require_user_id` opt
  (默认 `false` 兼容)开启后,ctx 无 `user_id` 时跳过 session_start 检索 + session_end 写入,
  避免多租户场景潜在数据互窜
- **`CMDC.AuditEvent` struct + helper** —— 行业标准 audit_log 6 元组,一行落库
  - `from_turn/2` —— `:after_turn` Plugin hook payload 直接转 AuditEvent(高价值快路径)
  - `from_telemetry/3` —— 6 个核心 telemetry 事件映射(agent.turn / llm.request / tool.exec)
  - `@derive Jason.Encoder` + `@enforce_keys`,直接 `Jason.encode!` 落库
  - cookbook 第 11 节附完整 Plugin + Postgres schema 参考
- 主库测试 1315 → **1349 tests + 21 doctests + 0 failures**(**+34** tests)

### 配套子库 patch

- **`cmdc_memory_pg 0.1.1`** —— `EpisodicMemoryBackend` 多租户隔离安全修复
  - 新增 `:on_missing_tenant` opt(`:return_empty` 默认 / `:return_error` 严格模式)
  - 修复 v0.1.0 注释声称"避免误泄"但代码不过滤的 bug
  - 多租户集成方**强烈建议升级**

### 兼容性

向后兼容 0.5.3,无 breaking change。所有新功能 opt-in:

- ContentPolicy 不配 `:judge_model` 时行为等同 0.5.3(启发式 fallback)
- EpisodicMemory `:require_user_id` 默认 `false`,老用户零影响
- AuditEvent 是全新模块,不订阅就零开销

### 多租户最佳实践

    plugins: [
      {CMDC.Plugin.Builtin.EpisodicMemory,
       memory_module: CMDCMemoryPg.EpisodicMemoryBackend,
       require_user_id: true},                       # 主库 Plugin 层

      {MyApp.Plugins.AuditSink, repo: MyApp.Repo}    # 用 CMDC.AuditEvent 落 audit_logs
    ]

---

## 0.5.3 — 2026-05-18

**Patch release** — Skill v2 第二阶段（allowed_tools 白名单 enforce）+ 3 份 observability 配方。
**全加性扩展，零破坏** —— 不挂 `SkillGuard` Plugin 行为完全等同 0.5.2。

### 新能力

- **`CMDC.Plugin.Builtin.SkillGuard`** —— Skill `allowed_tools` 白名单 enforcer
  - 选项 `:skills` / `:active` / `:enforce_mode` (`:strict` / `:warn`)
  - 并集语义：多 active Skill 的 allowed_tools 取并集；任一未设白名单即不限制
  - `priority/0 = 20` 在 SecurityGuard:10 之后业务 Plugin 之前
- **3 份 observability 配方** (`docs/recipes/observability/`):
  - Langfuse OTLP（AI Agent 专用 trace/generation/scoring）
  - LangSmith OTel（LangChain 生态统一观测）
  - Grafana Tempo + Loki + PromEx（自建可观测性栈完整链路）
- 主库测试 1300 → **1315 tests + 21 doctests + 0 failures**

### 兼容性

向后兼容 0.5.2，无 breaking change。SkillGuard 显式 opt-in（不挂载就不工作）。
可选采用项:
- Skill 项目用户：挂 `SkillGuard` Plugin 启 `:enforce_mode: :warn` 观察一段后切 `:strict`
- 可观测性接入：参考 `docs/recipes/observability/` 选 1 份按集成方栈接入

完整 Skill v2 后续 (运行时 active 切换 / cmdc_tui /skills slash) 留 v0.5.4。

---

## 0.5.2 — 2026-05-18

**Patch release** — Skill v2 多源叠加 + Provider Registry 双节点 :pg 协议验证。
**全加性扩展，零破坏** —— 老 `Skill.discover([dir])` 调用形式零行为变化。

### 新能力

- **`CMDC.Skill` `:source` 字段** —— `:base | :user | :project | :team | :custom | nil`
  标识 Skill 来自哪一层目录，便于 Plugin / TUI 显示来源
- **`Skill.discover/1` 多源标签重载** —— `[{:base, dir1}, {:user, dir2}, {:project, dir3}]`
  形式，同名 Skill 后者覆盖前者，返回的 `%Skill{}` 携带胜出层的 source
- **Provider Registry handler 协议测** —— 3 个 `{:cmdc_registry_remote, _}`
  远端消息处理单测 + 1 个 `@tag :distributed` 真双节点 `:pg` 集群验收测
  （默认 exclude，CI 需 `mix test --include distributed` 跑）

### 兼容性

- `Skill.discover([dir])` 老调用零行为变化（`:source = nil`）
- `Skill.t()` struct 加字段，老 pattern match 不受影响

完整 12E Skill v2 后续（`allowed_tools` 生效 + cmdc_tui /skills slash）
留 v0.5.3 + `cmdc_tui 0.1.2` 落地。

---

## 0.5.1 — 2026-05-18

**Patch release** — 多租户场景 `CMDC.Provider.Registry` 命名 Provider Profile 落地，
一行 `model: "registry:tenant-A:claude-sonnet-4-5"` 替代 200µs/Agent `provider_opts` 拼装。
**全加性扩展，零破坏** —— 老 model 字符串行为不变，老 Plugin / 老订阅者 / 老 Snapshot 零影响。

### 新能力

- **`CMDC.Provider.Registry`** — Local-first ETS + GenServer 写串行化的运行时寻址中心
  - 5 公开 API：`register/2` / `lookup/1` / `unregister/1` / `list/0` / `subscribe/1`
  - hot-path `lookup/1` ≤ 1 µs（ETS `:set` + `read_concurrency: true`）
  - `subscribe/1` 进程退出时 monitor 自动清理订阅记录
- **`CMDC.Provider.Registry.Broadcaster`** behaviour（1 callback）解耦跨节点同步
  - `Broadcaster.Noop`（单机）+ `Broadcaster.PG`（默认 best-effort）
  - 集成方可实现 Phoenix.PubSub / Redis 自定义版本（见 cookbook §6.3 完整示例）
- **model 字符串协议 `"registry:profile:model_id"`** — `Options.model` 字段透明支持，
  Agent.init / switch_model 自动解析 + 透写 `provider_opts`；老 model 字符串零行为变化
- **`{:error, {:registry_profile_missing, name}}`** 错误码 — `create_agent` /
  `resume_session!` 在 Registry 缺失对应 profile 时返回，集成方可重新 register 后重试
- **Telemetry 扩展** — 从 16 事件扩到 18 个，新增 `[:cmdc, :provider, :registry, :lookup/:register]`
  事件供 Prometheus / Datadog 监控 profile 命中率

### 兼容性

向后兼容 0.5.0，无 breaking change。可选采用项：

- 多租户场景：启动时 `CMDC.Provider.Registry.register/2` 灌入持久层所有 profile
- Blueprint：用 `model: "registry:tenant-A:claude-sonnet-4-5"` 字符串协议
- 自定义跨节点同步：实现 `Broadcaster` behaviour 接 Phoenix.PubSub

完整配方见 `guides/cookbook.md` §6.3「多租户 Provider Profile」。

---

## 0.5.0 — 2026-05-18

**Minor release** — 长会话多租户场景的内存优化 + 跨进程会话恢复 facade +
自动持久化 Plugin + Telemetry 可观测性。
**全加性升级，零破坏**——所有 v0.4.x 代码不动即可跑通。

### 新能力

- **Hibernate 配置** — `CMDC.Options.hibernate_after_ms` 让 Agent 进程
  idle 超时自动 hibernate（走 OTP 原生 `:hibernate_after` 选项），
  单进程 heap ~8KB → ~1.5KB（节省 ~80% 内存），长会话多租户必备
- **Checkpoint Facade** — `CMDC.checkpoint!/2` + `CMDC.resume_session!/2`，
  一行抓快照 + 一行跨进程恢复对话；序列化策略自动剥离运行期字段，
  plugin 通过 `:session_start` hook 重建状态
- **`Checkpoint.Snapshot.redact/2`** — backend 写前预处理 hook，
  让集成方接 Cloak / KMS 实现 encryption-at-rest（CMDC 不强制加密策略）
- **`AutoCheckpoint` Plugin** — OR 触发自动存档（every_n_turns / on_tools /
  on_events 任一命中即存）+ 自动 GC（max_checkpoints + ttl_seconds），
  走 `CMDC.AsyncTaskSupervisor` 异步执行不阻塞 Agent
- **Telemetry 扩展** — 从 6 个事件扩到 16 个，新 10 个 system-wide 事件
  （Plugin Pipeline / Compactor / Checkpoint / SubAgent / Hibernate /
  Plugin crash）走 `:telemetry.execute` 直接埋点，避免 per-session 业务订阅噪音
- **`CMDC.AsyncTaskSupervisor`** 加入 application supervision tree，
  供 AutoCheckpoint + 其他需要 fire-and-forget 异步任务的 plugin 使用

### 同窗口发布子库

- **`cmdc_memory_pg 0.1.0`** — PostgreSQL backend 二件套
  （Checkpoint + EpisodicMemory），含 Ecto migration + Cloak 集成示例;
  v0.1 不含 pgvector / 3-tier Memory / Composite / KV jsonb
- **`cmdc_test 0.1.0`** — 测试 helpers 4 大模块（MockProvider Builder API +
  Plugin.run_hook + Plugin.Spy + EventCapture + Assertions），
  替代集成方各自重写的 mock LLM 模板

### 兼容性

向后兼容 v0.4.x，无 breaking change。可选采用项：
- 长会话场景：`hibernate_after_ms: 60_000`
- 持久化场景：挂 `AutoCheckpoint` Plugin
- 可观测性：attach 10 个新 telemetry 事件接 Langfuse / Datadog

---

## 0.4.1 — 2026-05-16

**纯文档 patch**，零代码 / 零行为变更。

- 重组 hex doc：按"用户使用顺序"分 9 大模块组（入门 / 事件与状态 / 工具 /
  Plugins / 存储与沙箱 / 扩展点 / 集成 / 内核）
- 新增 7 篇入门指南：[5 分钟上手](quickstart.html) / [核心概念](concepts.html) /
  [Agent 状态机与事件](agent-loop.html) / [写一个 Plugin](plugins.html) /
  [写一个 Tool](tools.html) / [常见配方](cookbook.html) / [升级指南](upgrading.html)
- 12 个内部协作模块（State / Pipeline / Stream / ToolRunner / Compactor 等）
  改为 `@moduledoc false`，hex doc 侧边栏不再展示——避免误导用户调用
- 清理 `@moduledoc` / `@doc` 中的内部任务编号与版本碎注（~390 处），
  让模块文档聚焦"它做什么、怎么用、参数、示例、约束"
- README 精简到 90 行，专心做 hex 包首屏 first impression

主库与 `cmdc_gateway` 0.4.1 同步发布。

---

## 0.4.0 — 2026-05-16

### 新能力

- **会话 checkpoint** — `CMDC.Checkpoint` facade + `Checkpoint.Backend`
  behaviour + 内置 ETS / DETS 两个 backend；BEAM 重启 / Gateway 滚动 /
  跨设备恢复同一会话
- **`CMDC.Backend`** 文件 / 状态 / 远程存储统一抽象 — 10 callback + 8 种
  Result struct + 4 个标准错误码；内置 `State / Filesystem / Composite`
  三件套，`Composite` 支持 prefix 路由（一个会话同时挂 sandbox + PG memory
  + ETS history）
- **Sandbox `virtual_mode`** — 拦 `..` / `~` traversal + `O_NOFOLLOW`
  symlink 防护；生产推荐开启
- **大工具结果 0 token 占用** — `LargeResultOffload` Plugin 把 200KB+
  result 写到 backend，message history 只留 head/tail preview + 路径，
  Agent 通过 `read_file(path, offset, limit)` 分页读取
- **HumanApproval `approve_always` 白名单** — session-scoped
  `MapSet<{tool, command_family}>`，连续审批同类命令 5 次后自动放行；
  对接 ACP 三态权限
- **内容安全 LLM-as-Judge** — `ContentPolicy` Plugin，4 大策略类别
  （越狱 / 有害 / 离题 / 品牌违规），默认启发式 + judge_fn 扩展点
- **情景记忆 few-shot** — `EpisodicMemory` Plugin，成功对话自动转 few-shot，
  按 user_id 多租户隔离
- **Skill v2 spec 对齐** — Anthropic Agent Skills 规范（license /
  compatibility / metadata + name 规范 + 10MB 上限）
- **`CMDC.Telemetry`** 6 个标准 `:telemetry` 事件契约，零侵入接 Langfuse /
  LangSmith / Tempo
- **A2A webhook 异步模式**（`cmdc_gateway` 0.4）— 立即返回 accepted +
  后台派发回调（HMAC-SHA256 签名 + 3 次指数退避重试），>5 分钟长任务的
  可靠回调机制

### 测试

cmdc 主库：1219 tests + 21 doctests，0 failures
cmdc_gateway：125 tests，0 failures（含 12 个 webhook 测试）

### 兼容性

向后兼容 v0.3.x，无 breaking change。

---

## 0.3.0 — 2026-05-16

### Highlights

- **Skill 真实自进化**（`cmdc_skill_engine` 0.2）— Store backend 抽象
  （ETS + SQLite）+ LLM-powered Analyzer + Semantic SkillRanker（BM25 +
  quality + embedding 混合）+ QualityTracker 自动停用 + 1000 轮收敛压力测试
- **多 Agent 协作**（`cmdc_orchestrator` 0.3）— Runtime + AgentNode 三模式
  （standalone / pool / subagent）+ Debate / Hierarchy / Router-LLM 三种
  DAG 节点
- **A2A 协议同步 + SSE**（`cmdc_gateway` 0.3）— `tasks/send` JSON-RPC 2.0 +
  `tasks/sendSubscribe` SSE 流推送 + Guardrails Plug 链
- **Planning + Reflection**（核心库 v0.2.1）— Producer-Reviewer 分离 +
  结构化 Plan + 动态 system context 注入；Reflection 支持独立 Reviewer
  SubAgent

### 公共 API 改进（13 条）

来自实战集成方反馈：

- 工具执行耗时自动埋点（`pending_tools[].started_at_ms` +
  `:tool_execution_metrics` 事件）
- 新增 `:after_turn` Plugin hook（每 turn 回 idle 前触发，含
  outcome / abort_reason / messages_diff / token_usage_diff）
- `switch_model/3` 支持同步替换 `provider_opts`（base_url / api_key 跨厂商切换）
- `attach_tools / detach_tools / replace_tools` 批量原子 API
- `monitor/1` 结构化崩溃 reason 表
- `EventBus.subscribe/2` 加 `:since` + `:types` replay 白名单
- `status/1` 扩展 `turns_count / messages_count / active_since_ms / token_usage`
- `abort/2` `:reason` 接受 string + 6 个标准 reason 白名单归一化

### Breaking Change

公共 API（`monitor / abort / attach_tool / detach_tool / status / messages /
agent_pid / steer / stop / switch_model / replace_tools / attach_tools /
detach_tools`）从 raise 改为 `{:ok, _} | {:error, _}` 返回。
迁移代码见 [升级指南](upgrading.html#v02x--v030-1-条-breaking-change)。

---

## 0.2.1 — 2026-04-25

- **Planning Plugin** — `plan_first` 自动让 LLM 先生成 markdown checklist，
  解析为 `%CMDC.Plan{}` struct，支持 `replace_steps / add_step /
  insert_step / remove_step` 动态调整
- **Reflection Plugin** — 多轮评审循环，可选独立 Reviewer SubAgent
  （Producer-Reviewer 分离），未通过则注入修改指令
- **Plugin Action 扩展** — `:before_prompt` 支持 `:intervene`；emit 支持
  4 种形态（单事件 / 多事件 / 4 元简写 / 3 元 tuple payload）
- **Dynamic System Context** — Plugin 可通过 `{:emit, {:update_system_context,
  k, text}, state}` 动态注入 system prompt，Planning 用此持续把 plan 注入
  后续请求

---

## 0.2.0 — 2026-04-24

### Highlights

- **Steering 软中断** — `CMDC.steer/2` API + 3 个新事件
  （`:steering_received` / `:steering_applied` / `:tool_skipped_for_steering`），
  正在执行的 killable 工具被 brutal_kill，下轮 LLM 调用看到合并后的新 prompt
- **PromptMode 4 模式自动降级** — `:full / :task / :minimal / :none`，
  SubAgent 默认 `:task` 节省 30-50% system prompt token
- **MemoryFlush Plugin** — `:before_compact` 钩子提取关键事实写
  `MEMORY.md`，下次会话由 `MemoryLoader` 自动加载，闭环长会话不失忆
- **ModelRouter 业务规则扩展** — `:token_budget_lt` /
  `:task_complexity` / `:time_of_day_in` / `:user_tier` /
  `:user_data` 业务友好条件，从 `:intervene` 系统消息改为更干净的
  `:switch_model` Plugin action

### 公共 API 改进

- `CMDC.Options` 加 `:user_data :: map()` 透传 + `SubAgent` 自动继承
- `CMDC.Options` 加 `:messages :: [Message.t()]` 注入历史（持久化恢复场景）
- `CMDC.approve/3` + `reject/3` 加 `:auto_resume`，自动续 turn 让 LLM 重试
- `subscribe(string)` 修字符串 session_id 入参的 bug；新增公开
  `CMDC.user_respond/3`
- `%CMDC.TokenUsage{}` struct 公开化，`{:agent_end, messages, token_usage}`
  第三参数从 plain map 改为 struct（自动归一化 Anthropic `input_tokens` /
  `output_tokens` 等别名）
- `abort/2` 加 `:reason / :clear_queue / :kill_tools` 选项；100ms 内保证
  `:agent_abort` 事件到达
- 运行期 `switch_model/2` + `attach_tool/2` / `detach_tool/2` 热更工具集
- EventBus per-session ring buffer + `subscribe/2` `:since` 重连补帧
- `status/1` 扩展 `pending_tools / pending_approvals / steering_queue_size /
  prompt_queue_size`
- `CMDC.monitor/1` 返回结构化 `{:cmdc_down, ref, sid, reason}`

---

## 0.1.1 — 2026-04-08

修复 hex 包文件清单 + 文档若干小问题。

---

## 0.1.0 — 2026-04-08

首个 Hex 公开版本。覆盖：

- Agent kernel：`gen_statem` 4 状态机 + Plugin Pipeline（11 hook × 7 action）
- 内置 6 个 Plugin（SecurityGuard / EventLogger / HumanApproval / MemoryLoader /
  PatchToolCalls / PromptCache）
- 内置 11 个 Tool（ReadFile / WriteFile / EditFile / Shell / Grep / ListDir /
  Glob / Task / WriteTodos / AskUser / CompactConversation）
- Provider 层（`req_llm` 封装），MCP 集成，`Skill` 渐进式发现，
  `Blueprint` 声明式 Agent，`Sandbox.Local`，`Memory.ETS`，`Compactor` 上下文压缩