# cmdc_skill_engine Changelog

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

## [0.2.2] - 2026-05-18

**Patch release** — repository URL normalization + documentation cleanup.
No code changes, no behavior changes.

- Repository URL → `https://github.com/tupleyun/cmdc_skill_engine`
- Module moduledoc rewritten to neutral technical description
- CHANGELOG sections rewritten to neutral technical descriptions

## [0.2.1] - 2026-05-16

**Compatibility patch** — 让 `cmdc_skill_engine` 与 cmdc 0.4 主线生态
对齐，并补 benchmark 工具链（v0.2.0 后 commit 但未发布）。

### Changed — cmdc 依赖范围升级

- `{:cmdc, "~> 0.2"}` → **`{:cmdc, "~> 0.4"}`**
  - **背景**：`~> 0.2` 严格语义 `>= 0.2.0 and < 0.3.0` 阻塞与 cmdc
    0.3/0.4 共存。用户同时引入 cmdc 0.4 + cmdc_skill_engine 0.2 会
    触发 Hex 版本冲突
  - **兼容性核实**：本库依赖的 cmdc 抽象（`CMDC.Plugin` behaviour +
    `CMDC.SystemPrompt` Skills 注入接口）都在 v0.1 起稳定，且 v0.2-v0.4
    无 breaking change（除 v0.3 #B21 facade tuple，本库不调 facade）
  - **无运行时行为变更**

### Added — Benchmark 工具链

- 新增 `benchmark/quality_update.exs` — 100 skills × 10 轮 quality_update
  传播 Benchee suite（Store + QualityTracker 热路径性能基线）
- `benchmark/README.md` — benchmark 运行指引
- `:benchee, ~> 1.3` 加入 `dev / test` 依赖

### Migration

- 老用户仍用 cmdc 0.2 → 锁 `{:cmdc_skill_engine, "0.2.0"}` 即可
- 想用 cmdc 0.4 → 升级到 `{:cmdc_skill_engine, "~> 0.2.1"}`

## [0.2.0] - 2026-04-25

**真实自进化闭环 —— 对齐 Agentic Design Patterns 第 9 章 (Learning and Adaptation)
与 OpenSpace SkillEvolver**。

### Added

- `CMDCSkillEngine.Store.Backend` behaviour — 存储后端抽象层，定义
  `init/1 / get_record/2 / save_record/2 / list_all/1 / update_counters/3 /
  reset/1 / terminate/1` 契约。
- `CMDCSkillEngine.Store.Backend.ETS` — v0.1 的默认后端，单节点开发/测试首选。
- `CMDCSkillEngine.Store.Backend.SQLite` — 基于 `exqlite` 的持久化后端，自动
  创建 schema + 索引，支持 JSON 字段序列化（lineage / recent_analyses / tags）。
- `CMDCSkillEngine.Analyzer.LLM` — ReqLLM `generate_object/4` 驱动的结构化
  分析器；强制输出 `task_completed / execution_note / tool_issues /
  skill_judgments / evolution_suggestions`；自带超时控制与 `:generate_fn`
  注入钩子便于离线测试。
- `CMDCSkillEngine.SkillRanker.Semantic` — 新的 Selector 实现，结合 BM25
  关键词相关性、`effective_rate` 质量反馈与可选 `ReqLLM.embed/3` 语义向量
  相似度（`:embedding_model` 未配置时自动退化为 BM25 + 质量加权）。
- `CMDCSkillEngine.QualityTracker.should_deactivate?/2` +
  `update_from_analysis/3` — 新增自动停用规则：达到 `min_samples` 后，若
  `applied_rate < applied_min` 或 `effective_rate < effective_min` 且
  `trend != :improving`，自动把 `is_active = false`。
- `CMDCSkillEngine.Evolver` fix 链长度上限（默认 5）；超过时返回
  `{:error, {:fix_chain_too_long, generation, max_depth}}`，防止进化链
  失控膨胀。
- `example/skill_evolution_demo.exs` — 10 轮会话的完整自进化演示，无 LLM
  依赖，可 `mix run` 复现。
- `test/cmdc_skill_engine/stress_test.exs` — 1000 轮收敛压力测试，验证
  QualityTracker 能在合理轮次内识别并停用低质量 Skill。

### Changed

- `CMDCSkillEngine.Store` 重构为委托结构：GenServer state 保存
  `{backend_module, backend_state}`，所有 CRUD 操作通过 Backend 契约转发；
  公共 API 完全向后兼容。
- `CMDCSkillEngine.Analyzer` 集成 LLM 路径：当 `analysis_model` 是 LLM
  spec（非 `nil / "builtin" / "manual" / "rule" / ""`）时，`:session_end`
  走 LLM 分析；任何失败（超时 / HTTP / schema / 异常）自动降级到规则分析，
  不打断 Agent 正常结束流程。
- `CMDCSkillEngine.Analyzer` state 新增 `:messages` 字段，累积
  `:before_prompt / :after_response` 消息，作为 LLM 分析上下文。
- `CMDCSkillEngine.QualityTracker.update_from_analysis/2` 改为三元参数版本
  `update_from_analysis/3`（第三参数可选 `keyword()`），保持对现有调用方
  向后兼容。
- `Application.start/2` 支持 `:start_store` 配置开关，测试环境默认关闭
  自动启动以避免与 ExUnit 测试隔离冲突。

### Fixed

- Store GenServer 初始化时默认启动逻辑与测试隔离机制冲突，导致多个测试
  互相竞争同一 ETS 表 —— 现通过 `start_store: false`（test 环境）+
  `test_helper.exs` 里的单次 `start_link` + `Process.unlink/1` 修复。

### Deps

- 新增 `{:exqlite, "~> 0.27"}`、`{:jason, "~> 1.4"}`（SQLite backend
  + JSON 序列化）

### 测试覆盖

- 105 个测试全部通过（3 个 `@moduletag :stress` 压力测试默认排除）
- Store Backend 契约共 32 个测试（ETS × 16 + SQLite × 16）
- Analyzer.LLM 10 个单元测试（全部通过 `:generate_fn` stub，无真实 LLM）
- Analyzer 集成 15 个测试（LLM 命中 + 失败降级 + 规则关键字保护）
- SkillRanker.Semantic 9 个测试（BM25 / 质量回退 / embedding 注入）
- QualityTracker 15 个测试（计数器 + trend + deactivation 门控）
- Evolver 10 个测试（FIX / DERIVED / CAPTURED + fix chain 上限）

## [0.1.0] - 2026-04-23

### Added

- 初始版本：ETS Store、规则 Analyzer、QualityTracker、Evolver
  (FIX/DERIVED/CAPTURED)、SkillRanker（按 effective_rate 排序）。
- 对标 OpenSpace SkillEvolver 的完整数据模型（SkillRecord / SkillLineage
  / ExecutionAnalysis / SkillJudgment / EvolutionSuggestion）。