# skill-evolution-manager

> 在对话结束时，将用户反馈/有效做法沉淀到目标 Skill 的 evolution.json，并自动缝合回 SKILL.md（可反复对齐，避免升级覆盖）。

- Author: AlataChan
- Repository: AlataChan/skill_flywheel
- Version: 20260123144638
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/AlataChan/skill_flywheel
- Web: https://mule.run/skillshub/@@AlataChan/skill_flywheel~skill-evolution-manager:20260123144638

---

---
name: skill-evolution-manager
description: 在对话结束时，将用户反馈/有效做法沉淀到目标 Skill 的 evolution.json，并自动缝合回 SKILL.md（可反复对齐，避免升级覆盖）。
license: MIT
---

# Skill Evolution Manager

这是技能库的“进化中枢”：把一次对话中验证有效的偏好、约束、修复点沉淀成结构化数据，并自动写回 Skill 文档，方便下一次直接复用。

## 核心职责

1.  **复盘诊断 (Session Review)**：在对话结束时，分析所有被调用的 Skill 的表现。
2.  **经验提取 (Experience Extraction)**：将非结构化反馈转为结构化 JSON（`evolution.json`，视为事实源）。
3.  **智能缝合 (Smart Stitching)**：将 `evolution.json` 渲染为 `SKILL.md` 中的自动维护区块（可反复重建，不怕升级覆盖）。

## 使用场景

**Trigger**: 
- `/evolve`
- `/evolve <skill_name>`
- `/evolve --path <skill_dir>`
- `/evolve --all`
- `/evolve --stitch-only <skill_name>`
- "复盘一下刚才的对话"
- "我觉得刚才那个工具不太好用，记录一下"
- "把这个经验保存到 Skill 里"

## 命令接口（可执行规范）

这套接口的目标是：让“复盘/沉淀经验”变成一个确定的协议（参数、路径、schema、默认行为明确），从而可重复、可审计、可自动化。

### 命令语义（/evolve 约定）

- `/evolve <skill_name>`：对目标 Skill 执行 **merge -> stitch**（把本次复盘 JSON 合并进 `evolution.json`，再缝合回 `SKILL.md`）。
- `/evolve --path <skill_dir>`：当 Skill 不在默认 skills 根目录下时使用（优先级最高）。
- `/evolve --all [--skills-root <dir>]`：对 `skills_root` 下所有包含 `evolution.json` 的 Skill 执行 **批量重新缝合**（不做 merge）。
- `/evolve --stitch-only <skill_name|--path>`：只做 **stitch**（当你手动编辑了 `evolution.json` 或刚升级了 Skill，需要恢复自动区块时）。
- `/evolve --dry-run ...`：只预览 **merge 后的 JSON** 与 **缝合后的 SKILL.md**，不写入磁盘。

### 路径解析规则（避免写错 Skill）

- 默认 `skills_root`：`skill-evolution-manager` 的父目录（通常就是你的 skills 目录）。
- 解析优先级：`--path` > `--skills-root + <skill_name>` > 默认 `skills_root`。
- 强烈建议在执行前输出/确认最终解析出的 `skill_dir`（尤其是同名目录/多 skills 根目录的机器上）。

### JSON schema（推荐字段）

- `preferences`: `string[]`（用户偏好：输出风格、默认行为等）
- `constraints`: `string[]`（硬约束：不能做什么、必须做什么）
- `contexts`: `string[]`（环境/背景：OS、网络、目录结构、版本差异）
- `fixes`: `string[]`（已知修复/坑点：参数变更、兼容性、workaround）
- `custom_prompts`: `string`（需要注入到未来执行中的自定义指令块）
  - 兼容：`custom_instructions` 会被接收并写入 `custom_prompts`

### 可直接运行的脚本入口（推荐）

使用 `scripts/evolve.py` 一步到位（内部会调用 `merge_evolution.py` + `smart_stitch.py`）：

- merge + stitch（推荐 stdin 避免转义）：
  - `cat <<'JSON' | python scripts/evolve.py --name <skill_name> --stdin`
- merge + stitch（直接给路径）：
  - `python scripts/evolve.py --path <skill_dir> --json '{"preferences":["..."]}'`
- 只重新缝合：
  - `python scripts/evolve.py --name <skill_name> --stitch-only`
- 批量对齐：
  - `python scripts/evolve.py --align-all [--skills-root <dir>]`

## 工作流 (The Evolution Workflow)

### 1. 经验复盘 (Review & Extract)
当用户触发复盘时，Agent 必须执行：
1.  **扫描上下文**：找出用户不满意的点（报错、风格不对、参数错误）或满意的点（特定 Prompt 效果好）。
2.  **定位 Skill**：确定是哪个 Skill 需要进化（例如 `yt-dlp` 或 `baoyu-comic`）。
3.  **生成 JSON**：构建一个 JSON 对象（推荐键如下；可按需提供）：
    ```json
    {
      "preferences": ["用户希望输出更简洁", "默认静音下载"],
      "constraints": ["不得删除用户文件", "不得访问外网（除非用户要求）"],
      "contexts": ["Windows 路径需要转义", "公司网络需要代理"],
      "fixes": ["Windows 下 ffmpeg 路径需转义", "某参数在 v2 已弃用，需改用 --new-flag"],
      "custom_prompts": "在执行前先打印预估耗时与风险点"
    }
    ```
    - `custom_instructions` 也会被接受，并会写入到 `custom_prompts`（便于兼容旧结构）。

### 2. 经验持久化 (Persist)
Agent 调用 `scripts/merge_evolution.py`，将上述 JSON 增量写入目标 Skill 的 `evolution.json` 文件中。
- **推荐命令（避免 shell 转义痛苦）**：
  - `cat <<'JSON' | python scripts/merge_evolution.py <skill_path> --stdin`
  - （然后把 JSON 内容放进 heredoc，最后用 `JSON` 结束）
- **其他命令**：
  - `python scripts/merge_evolution.py <skill_path> --json '{"preferences":["..."]}'`
  - `python scripts/merge_evolution.py <skill_path> --json-file /path/to/new.json`
  - `python scripts/merge_evolution.py <skill_path> --dry-run --stdin`（只预览合并结果，不写文件）

### 3. 文档缝合 (Stitch)
Agent 调用 `scripts/smart_stitch.py`，将 `evolution.json` 渲染为 `SKILL.md` 中的自动维护区块。
- 该区块会被 `<!-- skill-evolution-manager:begin -->` / `<!-- skill-evolution-manager:end -->` 包裹，脚本只会替换这个区块，避免误删文档其他内容。
- **命令**：
  - `python scripts/smart_stitch.py <skill_path>`
  - `python scripts/smart_stitch.py <skill_path> --dry-run`（输出到 stdout，不落盘）

### 4. 跨版本对齐 (Align)
当 `skill-manager` 更新了某个 Skill 后，Agent 应主动运行 `smart_stitch.py`（或批量运行 `align_all.py`），将 `evolution.json` 的经验“重新缝合”到新版文档中。

## 核心脚本

- `scripts/merge_evolution.py`: **增量合并工具**。负责读取旧 JSON，去重合并新 List，保存。
- `scripts/smart_stitch.py`: **文档缝合工具**。负责读取 JSON，生成/更新 `SKILL.md` 中的自动维护区块（带 begin/end 标记）。
- `scripts/evolve.py`: **一键编排入口**。对单个 Skill 执行 merge+stitch，或执行批量对齐。
- `scripts/align_all.py`: **全量对齐工具**。遍历某个 skills 根目录下的所有 Skill 文件夹，对存在 `evolution.json` 的 Skill 执行重新缝合。
  - 默认 `skills_root` 为 `skill-evolution-manager` 的父目录（通常就是你的 skills 目录）。
  - 用法：`python scripts/align_all.py [skills_root]`

## 最佳实践

- **不要直接修改 SKILL.md 的自动维护区块**：所有经验修正应通过 `evolution.json` 通道进行，这样可以保证在 Skill 升级时经验不丢失。
- **多 Skill 协同**：如果一次对话涉及多个 Skill，请依次为每个 Skill 执行上述流程。