# Changelog
> 用户可见的版本变化摘要。完整 release notes 见
> [GitHub Releases](https://github.com/tupleyun/cmdc/releases)。
兼容边界与迁移代码见 [升级指南](upgrading.html)。
---
## 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` 上下文压缩