skill-curator

Readme

# skill-curator

**会自我积累的 DSH skill 管家**：一个"经验回流 + 知识积累"的闭环系统，而不只是安装与维护手册。

[English version](README.en.md)

---

## 这是什么

`skill-curator` 是一个面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）的元技能。它的核心职能是：

> **当任何一个 skill 在使用中遇到问题并被解决后，把解决方案与核心知识回流到那个 skill，并登记进统一的知识库；下次需要完善某个 skill 时，按知识库选择性应用已有经验。知识随使用滚雪球式积累。**

辅助职能（同样完整支持）：

1. **安装** skill（zip/目录/单文件来源，含 frontmatter 校验与逐文件对账）
2. **创建** skill（把某个能力整理成规范 skill）
3. **本地化**（Codex/其他平台的 skill 转成 DSH 可用）
4. **自我维护**（skill-curator 自身也按同一流程维护，含自校验脚本）

### 与普通"skill 管理工具"的区别

| 特征 | 说明 |
| --- | --- |
| **事件触发** | 不只靠用户显式调用——其他 skill 出问题并解决后即触发回流，在经验最新鲜的时刻写回 |
| **核心知识库** | 所有核心知识登记入库（问题→根因→解决→验证→已回流到哪些 skill），关键词 + 本地 bge-small-zh 语义**双通道检索** |
| **7 项判断清单** | 写回前逐项过滤（可复现性/相关性/稳定性/正确性/无冲突/粒度/权威同步），防止垃圾知识污染 skill |
| **防臃肿机制** | 登记前查重、条目分档管理、过时知识归档——知识库规模增长不失控 |
| **Token 意识** | 分流器式 SKILL.md + 按需加载分册 + 索引先行 + 局部读取，每次触发只加载相关部分 |

## 设计理念

1. **经验越新鲜越有价值**：问题刚解决时，报错、根因、修复、验证都在上下文中，此时写回最准确；延迟写回会因上下文压缩丢失细节。
2. **知识分层**：各 skill 的"维护须知"节只留"加载即得"的摘要；知识库条目是权威副本——不一致时以知识库为准。
3. **检索分工**：检索器只负责召回候选，语义判断交给模型本身——所以关键词（快、可解释）为主、向量（同义兜底）为辅是最优组合。
4. **一切为省 Token**：SKILL.md 是分流器（只载核心速查+分流表+验证清单），操作细节按场景拆分到 references 分册按需读取。

---

## 如何使用

### 方式一：自然语言触发（最简单）

不需要记任何命令，直接说：

| 场景 | 您说的话 | 发生什么 |
| --- | --- | --- |
| 安装 | "安装这个 zip 里的 skill" | 加载 skill-curator → 按安装流程执行 → 验证可用 |
| 创建 | "把 XX 能力整理成一个 skill" | 按规范创建 SKILL.md 与资源 → 安装验证 |
| 本地化 | "把这个 Codex skill 转成 DSH 的" | 删 Codex 专用配置、重构 frontmatter、适配工具链 |
| 完善 | "完善 csu-transfer-procedures" | 先检索知识库中与该 skill 相关的条目，**选择性**应用 |
| 检查 | "检查这个 skill 有没有问题" | 模拟 DSH 解析规则校验 frontmatter/资源/引用 |

### 方式二：事件触发（自动回流）

任何 skill 使用中遇到突发问题（编码乱码、路径失效、格式错误、脚本报错、解析失败）**并解决后**，模型会加载 skill-curator 执行回流三步：

```
① 判断值得回流（7 项清单过滤：可复现且相关？会过期吗？已验证吗？）
② 写回该 skill 的"维护须知"节（问题→根因→修复→验证；双版本脚本同步）
③ 登记知识库（先查重，新知识建条目+更新索引，再重建语义索引）
```

### 方式三：工作区钩子（可选，强化事件触发）

在您的项目工作区根目录创建 `AGENTS.md`，写入回流自查指令（DSH 每步自动注入，模型每轮结束前自查是否刚解决了 skill 问题）：

```markdown
# 工作区指令

## Skill 经验回流钩子（每轮自查）

每轮结束前自查：若本轮解决了某个 skill 执行中的突发问题（编码乱码、路径失效、
格式错误、脚本报错、解析失败等），在结束前调用 skill 工具加载 `skill-curator`，
按其 `references/feedback.md` 执行回流（判断 → 写回 → 登记知识库 → 自校验）。
不打断进行中的任务；一次性输入错误不值得回流。
```

### 方式四：自动检测插件（进阶，可选）

`scripts/feedback-hook/` 是一个 cordis 插件：检测到最后一条消息出现"已修复/已解决"等字样且提及 skill 时，自动注入回流提醒（平时零干扰）。安装见 [`scripts/feedback-hook/INSTALL.md`](scripts/feedback-hook/INSTALL.md)，需重启 DSH。四种方式的对比：

| | 自然语言 | 事件触发 | AGENTS.md 钩子 | 插件 |
| --- | --- | --- | --- | --- |
| 生效 | 即时 | 即时 | 写入即生效 | 需重启 DSH |
| 触发者 | 用户 | 模型自觉 | 常驻指令提醒 | 事后自动检测 |
| 成本 | 0 | 0 | 常驻 ~0.4K token | 命中时 ~0.3K token |
| 可靠性 | 高 | 中 | 高 | 高（安装后） |

### 工具脚本（按需调用，均有 Python 版）

| 脚本 | 用途 | 调用时机 |
| --- | --- | --- |
| `scripts/validate_skill.py` | 模拟 DSH 解析规则校验任意 skill | 安装/更新后必跑；自我更新的安全网 |
| `scripts/search_kb.py` | 知识库关键词检索（bigram 匹配） | 完善 skill 时定位相关条目；登记前查重 |
| `scripts/search_kb.py --semantic` | 知识库语义检索（bge-small-zh） | 关键词检索漏检时的同义兜底 |
| `scripts/kb_embed.py build` | 构建/重建语义索引 | 知识库登记新条目后 |
| `scripts/feedback-hook/` | 回流自动检测插件 | 可选安装，见 INSTALL.md |

---

## 安装

```bash
# 1. 克隆或下载本仓库，把整个目录放入用户级 skill 根目录
git clone https://github.com/gwrsfsfeefdsfs/dsh-skill-curator.git ~/.dsh/skills/skill-curator
# 或手动复制 skill-curator/ 目录到 ~/.dsh/skills/

# 2. DSH 立即识别（available_skills 出现 skill-curator），无需重启
```

## 依赖（按需安装）

| 功能 | 依赖 | 安装 |
| --- | --- | --- |
| 校验 / 关键词检索 | Python 3.10+ + pyyaml | `pip install pyyaml` |
| 语义检索 | sentence-transformers + bge-small-zh-v1.5 模型（约 95MB） | `pip install sentence-transformers` |
| 模型获取 | 三种方式任选：① HF 自动下载；② 阿里魔搭下载到 `scripts/models/`；③ 环境变量 `BGE_MODEL_PATH` | 见下 |

```bash
# 依赖安装
pip install pyyaml sentence-transformers

# 模型获取方式 ②（HF 网络受限时推荐，国内可达）
pip install modelscope
python -c "from modelscope import snapshot_download; snapshot_download('AI-ModelScope/bge-small-zh-v1.5', local_dir='scripts/models/bge-small-zh-v1.5')"

# 首次构建语义索引（会自动加载模型）
python scripts/kb_embed.py build

# 双通道检索示例
python scripts/search_kb.py 编码                       # 关键词：精确、毫秒级
python scripts/search_kb.py --semantic 脚本输出乱码怎么修  # 语义：同义兜底、约 1-2 秒
```

---

## 目录结构

```
skill-curator/
├── SKILL.md                      # 分流器：核心速查 + 场景分流表 + 验证清单（每次加载仅此文件）
├── references/                   # 按场景加载的操作分册（省 Token 设计）
│   ├── dsh-skill-spec.md         #   DSH skill 机制规范（源码级：发现优先级/frontmatter/目录注入/热更新）
│   ├── install.md                #   安装流程（6 步 + 对账注意）
│   ├── localize.md               #   本地化流程（Codex→DSH 5 步）
│   ├── feedback.md               #   经验回流流程（三步）+ 7 项知识修改判断清单
│   ├── env-traps.md              #   环境陷阱清单（编码/路径/格式速查）
│   ├── token-patterns.md         #   Token 优化模式（大参考资料标准结构）
│   └── knowledge-base.md         #   核心知识库（条目索引 + 防臃肿规则 + 权威副本）
├── scripts/
│   ├── validate_skill.py         # 通用 skill 合规性校验
│   ├── search_kb.py              # 知识库检索（关键词 / --semantic）
│   ├── kb_embed.py               # embedding 索引构建（模型三级优先：环境变量→本地→HF）
│   └── feedback-hook/            # 可选：回流自动检测 cordis 插件
├── README.md / README.en.md      # 本说明（中/英）
├── LICENSE                       # MIT
└── .gitignore                    # 排除 models/、.kb-cache/、__pycache__/
```

## 知识库机制

- **条目格式**：`日期、问题、根因、解决、验证、已回流到哪些 skill`
- **双通道检索**：关键词 bigram 匹配（穿透中文词间隔，如"评估备案"可命中"评估报告备案"）+ bge-small-zh 语义兜底（同义不同词）
- **防臃肿分档**：任何规模登记前查重 → 条目 >30 用检索脚本定位 → 条目 >60 或文件 >50KB 触发整理归档（过时条目移入 `knowledge-archive.md`，主文件留指路行）
- **过时管理**：知识过期时标注"状态：已过时（原因+日期）"，不删除（可追溯）

## 常见问题

**Q：它会不会自动运行？** 不会。DSH 没有事件钩子，所有 skill 的触发都靠模型判断或用户指示；skill-curator 用精准的触发描述 + 可选插件最大化"自动"概率，用户显式指示是最终兜底。

**Q：知识库会不会越滚越大？** 有完整防臃肿机制（查重→检索脚本→归档），详见上文"知识库机制"。

**Q：它自己出问题谁来更新？** 它自己——自我维护是设计内能力，`validate_skill.py` 是自更新的安全网（改坏自己的 frontmatter 是最危险的自指失败，脚本负责拦截）。

**Q：语义检索模型必须装吗？** 不必。关键词检索零额外依赖即可用；语义检索只是同义查询的兜底增强。

## 许可

[MIT](LICENSE)