cmdc_skill_engine

CMDC Skill 自进化引擎 — Agent learning & adaptation 闭环：质量追踪 + 自动停用低效 Skill + FIX/DERIVED/CAPTURED 三种动作派生新版本。

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

核心能力

模块	职责
`CMDCSkillEngine.Store`	GenServer 委托到 Backend（ETS / SQLite），提供 SkillRecord CRUD + 版本 DAG + 原子计数
`CMDCSkillEngine.Store.Backend.ETS`	默认内存后端，重启丢失数据
`CMDCSkillEngine.Store.Backend.SQLite`	基于 `exqlite` 的持久化后端 (v0.2+)
`CMDCSkillEngine.QualityTracker`	计算质量指标 + 趋势判定 + 自动停用低质量 Skill
`CMDCSkillEngine.Analyzer`	`@behaviour CMDC.Plugin`，订阅 `session_start`/`before_prompt`/`after_response`/`after_tool`/`session_end` 产出 `ExecutionAnalysis`
`CMDCSkillEngine.Analyzer.LLM`	ReqLLM `generate_object/4` 结构化分析 + 失败降级 (v0.2+)
`CMDCSkillEngine.Evolver`	执行 FIX / DERIVED / CAPTURED 三类进化动作，带 fix 链长度上限 (v0.2+)
`CMDCSkillEngine.SkillRanker`	`@behaviour CMDC.Skill.Selector`，按 `effective_rate` 排序
`CMDCSkillEngine.SkillRanker.Semantic`	BM25 + quality + 可选 embedding 的混合排序 (v0.2+)
`CMDCSkillEngine` (facade)	`register_skill/1` / `stats/2` / `get_record/1` 等顶层 API

安装

# 在业务应用的 mix.exs
defp deps do
  [
    {:cmdc, "~> 0.5"},
    {:cmdc_skill_engine, "~> 0.3"}
  ]
end

Store 启动方式：

# 使用默认 ETS backend（开发/测试）
children = [CMDCSkillEngine.Store]

# 或者 SQLite 持久化 backend
children = [
  {CMDCSkillEngine.Store,
    backend: CMDCSkillEngine.Store.Backend.SQLite,
    backend_opts: [path: "priv/skills.db"]}
]

自进化闭环

  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 最高的版本

设计模式对照：

In-context guidance：Skill 本身即 in-context prompt fragment
Strategic 适应：QualityTracker + SkillRanker 让质量差的 Skill 自动退场
失败路径沉淀：Evolver 的 FIX/DERIVED 将失败路径沉淀为新 Skill

快速上手

# 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 选项

{CMDCSkillEngine.Analyzer,
  enabled: true,                  # 主开关
  auto_evolve: false,             # true 时自动把 suggestions 交给 Evolver
  analysis_model: "openai:gpt-4o-mini", # nil/"builtin"/"rule" 走规则分析
  llm_opts: [
    analysis_timeout: 15_000,
    req_llm_opts: [temperature: 0.1]
  ]
}

分析路径

analysis_model 设为 LLM spec 时：会话结束时调 ReqLLM.generate_object/4 产出结构化分析，失败自动降级到规则分析。
analysis_model 为 nil / ""/ "builtin" / "manual" / "rule"：只走规则分析，不联网。

进化类型

类型	父数	用途	旧版本处理
`: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 不适配信号）

Telemetry

v0.3 起暴露 4 个 :telemetry 事件（CMDCSkillEngine.Telemetry）：

事件	触发时机
`[:cmdc_skill_engine, :analyzer, :analyze, :start]`	Analyzer 开始分析 session
`[:cmdc_skill_engine, :analyzer, :analyze, :stop]`	Analyzer 分析完成（含降级路径）
`[:cmdc_skill_engine, :evolution, :emitted]`	Evolver 成功产出新 SkillRecord
`[:cmdc_skill_engine, :store, :record_updated]`	Store 完成写入或计数更新

集成方接入：

:telemetry.attach_many(
  "my-skill-engine-handler",
  CMDCSkillEngine.Telemetry.all_events(),
  &MyApp.SkillBridge.handle_event/4,
  nil
)

完整字段说明见 CMDCSkillEngine.Telemetry moduledoc。

状态

v0.3.0 (当前) — Telemetry 4 事件契约、SkillRecord 加 :scope / :metadata、SQLite idempotent migration
v0.2 — SQLite 持久化后端、LLM 结构化分析、语义排序、自动停用低质量 Skill、fix 链长度上限
v0.1 — ETS 后端 + 完整 Plugin 生命周期；单节点适用
v0.4 计划 — Store 多租户切片（:scope keyword）、Skill usage heatmap、embedding cache

开发

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

许可

Apache-2.0