# cmdc_skill_engine

**CMDC Skill 自进化引擎** — 对标 [OpenSpace Skill Evolution](https://github.com/OpenSpaceAI/OpenSpace)，
对齐 *Agentic Design Patterns* 第 9 章「Learning and Adaptation」。

本库在 CMDC Core 之外运行，负责为 Agent 的 Skill 体系加上**质量追踪 +
自进化**闭环：每次会话结束后，自动更新每个 Skill 的 applied / completion /
effective / fallback 四项指标，并按 FIX / DERIVED / CAPTURED 三种动作派生
新 Skill 版本。

## 核心能力

| 模块 | 职责 |
|------|------|
| `CMDCSkillEngine.Store` | ETS GenServer，提供 SkillRecord CRUD + 版本 DAG + 原子计数 |
| `CMDCSkillEngine.QualityTracker` | 计算并更新质量指标，判定 improving/stable/declining 趋势 |
| `CMDCSkillEngine.Analyzer` | `@behaviour CMDC.Plugin`，订阅 `session_start`/`after_tool`/`session_end` 产出 `ExecutionAnalysis` |
| `CMDCSkillEngine.Evolver` | 执行 FIX / DERIVED / CAPTURED 三类进化动作 |
| `CMDCSkillEngine.SkillRanker` | `@behaviour CMDC.Skill.Selector`，按 `effective_rate` 排序注入最有效 Skill |
| `CMDCSkillEngine` (facade) | `register_skill/1` / `stats/2` / `get_record/1` 等顶层 API |

## 安装

尚未发布到 Hex。本地集成：

```elixir
# 在业务应用的 mix.exs
defp deps do
  [
    {:cmdc, "~> 0.2"},
    {:cmdc_skill_engine, path: "path/to/cmdc_skill_engine"}
  ]
end
```

## 自进化闭环

```text
  Agent 运行
     │
     ▼
  session_end ──▶ Analyzer.handle_event
                       │
                       ▼
                 build_analysis
                       │
                       ├─▶ QualityTracker.update_from_analysis
                       │        │
                       │        ▼
                       │   Store.save_record  (持久化四项指标)
                       │
                       └─▶ EvolutionSuggestion 列表
                                │
                                ▼
                          Evolver (fix/derived/captured)
                                │
                                ▼
                          Store.save_record (新版本入库)
                                │
                                ▼
                   下次会话 SkillRanker 自动选中
                   effective_rate 最高的版本
```

对应 ADP 第 9 章：

- **SL / Few-shot**：Skill 本身即 in-context guidance
- **Strategic 适应**：QualityTracker + SkillRanker 让质量差的 Skill 自动退场
- **SICA 自迭代**：Evolver 的 FIX/DERIVED 将失败路径沉淀为新 Skill

## 快速上手

```elixir
# 1) 在 Application 启动 Store
children = [CMDCSkillEngine.Store]

# 2) 装载项目 Skills
CMDC.Skill.discover(["./skills"])
|> Enum.each(&CMDCSkillEngine.register_skill/1)

# 3) 在 CMDC Agent 接入 Analyzer + SkillRanker
{:ok, session} =
  CMDC.create_agent(
    model: "qwen3-max",
    plugins: [{CMDCSkillEngine.Analyzer, [auto_evolve: false]}],
    skills_dirs: ["./skills"],
    skill_selector: CMDCSkillEngine.SkillRanker
  )

# 4) 会话结束后查看 Skill 质量
{:ok, stats} = CMDCSkillEngine.stats("my-skill-id")
# => %{
#   applied_rate: 0.85,
#   completion_rate: 0.70,
#   effective_rate: 0.60,
#   fallback_rate: 0.15,
#   trend: :improving
# }

# 5) 追溯某个 Skill 的完整演化链
{:ok, chain} = CMDCSkillEngine.version_chain("my-skill-id")
# => [%SkillRecord{origin: :imported}, %SkillRecord{origin: :fixed}, ...]
```

## Analyzer 选项

```elixir
{CMDCSkillEngine.Analyzer,
  enabled: true,              # 主开关
  analysis_model: "qwen3-max", # 预留：后续接 LLM 结构化分析
  auto_evolve: false           # true 时自动把 suggestions 交给 Evolver
}
```

## 进化类型

| 类型 | 父数 | 用途 | 旧版本处理 |
|------|-----|------|------------|
| `:fix` | 1 | 修复现有 Skill（新版本继承名称与路径） | `is_active = false` |
| `:derived` | ≥ 1 | 从多个父 Skill 合成新 Skill | 不动 |
| `:captured` | 0 | 从失败路径捕获全新 Skill | 不存在父 |

## 质量指标语义

| 指标 | 公式 | 含义 |
|------|------|------|
| `applied_rate` | `applied / selections` | Skill 被选中后是否真正被应用 |
| `completion_rate` | `completions / applied` | 应用后任务是否完成 |
| `effective_rate` | `completions / selections` | 端到端效率（Ranker 排序依据） |
| `fallback_rate` | `fallbacks / selections` | 选中但没用上的比率（Skill 不适配信号） |

## 状态

- v0.1 — ETS 后端 + 完整 Plugin 生命周期；单节点适用
- v0.2 计划 — SQLite 持久化后端、LLM 结构化分析、embedding 选择器、多节点广播

## 开发

```bash
mix compile --warnings-as-errors
mix format --check-formatted
mix credo --strict
mix test
```

## 许可

Apache-2.0