# Changelog

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

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

---

## 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` 上下文压缩