Skill Evolution Manager

Skill 系统的"进化中枢"。负责将对话中的经验教训持久化存储，并跨版本、跨项目保留。

核心价值

问题: Skill 更新时，用户积累的最佳实践会丢失；不同项目间的经验无法共享。

解决方案:

将用户经验存储在独立的 evolution.json 文件中
通过智能缝合将经验自动写入 SKILL.md
Skill 更新后，通过全量对齐恢复经验
三层架构：支持上游层、全局层、项目层的经验分离和合并

三层架构

┌─────────────────────────────────────────────────────────────────────┐
│                          三层经验架构                                │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌──────────────────┐                                               │
│  │   上游层 (Upstream)  │  skills-repo 原始仓库的经验                │
│  │   evolution.json     │  来自社区/原作者的最佳实践                 │
│  │   位置: skills-repo/skills/<skill>/evolution.json                │
│  └─────────┬────────┘                                               │
│            │ 继承                                                    │
│            ▼                                                         │
│  ┌──────────────────┐                                               │
│  │   全局层 (Global)    │  你个人的通用经验                          │
│  │   evolution.json     │  可选择性提交 PR 到上游                    │
│  │   位置: ~/.claude/evolutions/<skill>/evolution.json              │
│  └─────────┬────────┘                                               │
│            │ 继承                                                    │
│            ▼                                                         │
│  ┌──────────────────┐                                               │
│  │   项目层 (Project)   │  项目特定经验                              │
│  │   <skill>.json       │  不提交到版本控制                          │
│  │   位置: <project>/.claude/evolutions/<skill>.json                │
│  └──────────────────┘                                               │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

合并优先级

最终生效的经验 = merge(
    上游层,      # 最低优先级
    全局层,      # 中等优先级
    项目层       # 最高优先级
)

列表字段 (preferences, fixes, contexts): 追加去重
custom_prompts: 项目层 > 全局层 > 上游层（覆盖）

核心功能

复盘诊断: 分析对话中的问题点和成功方案
经验提取: 将非结构化反馈转为结构化 JSON
增量合并: 去重合并新经验到 evolution.json
智能缝合: 将经验自动写入 SKILL.md 的专用章节
跨版本对齐: Skill 更新后重新缝合经验
跨项目管理: promote/pull 命令在层级间同步经验

使用场景

触发方式:

/skill-evolution 或 /evolve
"复盘一下刚才的对话"
"记录一下这个经验"
"把这个技巧保存到 Skill 里"
"这个问题的解决方案要记住"

工作流程

步骤 1: 复盘诊断

Agent 分析当前对话，识别：

问题点: 报错、参数错误、风格不对
成功方案: 有效的解决方法、最佳实践
用户偏好: 用户明确表达的喜好

步骤 2: 生成结构化 JSON

Agent 将提取的经验转换为 JSON 格式：

{
  "preferences": [
    "用户希望下载时默认静音",
    "优先使用 mp4 格式"
  ],
  "fixes": [
    "Windows 下路径需要转义",
    "某些参数在 v2.0 后已弃用"
  ],
  "contexts": [
    "批量操作时需要添加 --batch 参数",
    "处理大文件时增加超时时间"
  ],
  "custom_prompts": "在执行前总是先打印预估耗时"
}

步骤 3: 选择保存层级

Agent 询问用户：

全局层: 所有项目共享的通用经验
项目层: 仅当前项目使用的特定经验

步骤 4: 增量合并

运行 scripts/merge_evolution.py 将经验合并：

# 传统模式（保存到 skill 目录）
python scripts/merge_evolution.py <skill_dir> '<json_string>'

# 分层模式（保存到全局层）
python scripts/merge_evolution.py <skill_name> '<json_string>' --layer global

# 分层模式（保存到项目层）
python scripts/merge_evolution.py <skill_name> '<json_string>' --layer project --project /path/to/project

步骤 5: 智能缝合

运行 scripts/smart_stitch.py 将经验写入 SKILL.md：

# 单层模式
python scripts/smart_stitch.py <skill_dir>

# 分层模式（合并三层经验）
python scripts/smart_stitch.py <skill_dir> --layered --project /path/to/project

步骤 6: 跨版本对齐

当 skill-manager 更新 Skill 后，运行全量对齐恢复经验：

python scripts/align_all.py <skills_dir>

脚本说明

脚本	功能	参数
`layered_merge.py`	分层经验管理核心	`<action> <skill_name> [options]`
`merge_evolution.py`	增量合并经验	`<skill_dir> <json> [--layer] [--project]`
`smart_stitch.py`	缝合到 SKILL.md	`<skill_dir> [--layered] [--project]`
`align_all.py`	全量对齐	`<skills_dir> [--dry-run] [--backup]`

layered_merge.py 命令

# 查看经验状态
python scripts/layered_merge.py status <skill_name> [--project <path>]

# 合并三层经验（查看结果）
python scripts/layered_merge.py merge <skill_name> [--project <path>]

# 将项目经验提升到全局层
python scripts/layered_merge.py promote <skill_name> [--project <path>] [--fields f1,f2]

# 从全局层拉取经验到项目层
python scripts/layered_merge.py pull <skill_name> [--project <path>]

# 保存经验到指定层
python scripts/layered_merge.py save <skill_name> <layer> '<json>' [--project <path>]

evolution.json 格式

{
  "preferences": ["string"],
  "fixes": ["string"],
  "contexts": ["string"],
  "custom_prompts": "string",
  "last_updated": "ISO-8601 datetime",
  "last_evolved_hash": "commit hash"
}

字段	说明
`preferences`	用户偏好列表
`fixes`	已知问题修复方案
`contexts`	特定使用场景说明
`custom_prompts`	自定义指令注入
`last_updated`	最后更新时间
`last_evolved_hash`	最后进化时的 source_hash

最佳实践

通过 evolution.json 修改: 不要直接编辑 SKILL.md 中的经验章节
定期复盘: 每次使用 Skill 遇到问题或发现技巧时，及时记录
更新后对齐: 每次 skill-manager 更新 Skill 后，运行 align_all.py
备份重要经验: 使用 --backup 选项保护重要的经验数据
合理选择层级:
- 通用经验 → 全局层
- 项目特定经验 → 项目层
- 高质量经验 → 考虑 PR 到上游

示例

示例 1: 记录用户偏好到全局层

用户: 记录一下，我希望下载视频时默认不带字幕，这个是通用设置

Agent:
1. 识别这是一个用户偏好，且是通用设置
2. 生成 JSON: {"preferences": ["下载视频时默认不带字幕"]}
3. 运行 merge_evolution.py --layer global 合并到全局层
4. 运行 smart_stitch.py --layered 更新 SKILL.md

示例 2: 记录项目特定修复

用户: 这个项目的路径比较特殊，记住要用绝对路径

Agent:
1. 识别这是项目特定的修复方案
2. 生成 JSON: {"fixes": ["此项目必须使用绝对路径"]}
3. 运行 merge_evolution.py --layer project 合并到项目层

示例 3: 提升经验到全局

用户: 把这个项目里学到的经验提升到全局，其他项目也能用

Agent:
1. 运行 layered_merge.py promote <skill_name>
2. 项目层的经验被复制到全局层
3. 报告提升结果

示例 4: 新项目初始化

用户: 这是新项目，把全局经验拉下来

Agent:
1. 运行 layered_merge.py pull <skill_name>
2. 全局层的经验被复制到项目层
3. 可以在此基础上继续积累项目特定经验

与其他 Skill 的协作

skill-factory: 创建的 Skills 自动启用 evolution（evolution_enabled: true）
skill-manager: 更新 Skill 后应调用 align_all.py 恢复经验；提供 promote/pull 命令
skill-creator: 遵循相同的经验章节格式

skill-evolution