skill-manager

English

repertoire — 技能曲目库

dsh（DeepSeek harness）插件：技能的发现、加载、创建与统计。

• 多级目录自动发现 — 从项目区 / 用户区 / 插件自带区三个 zone 递归发现技能，优先级明确、冲突可见
• 渐进式披露 — 目录索引（名称+用途）→ 技能正文（按需加载）→ 附属资源（按需读取/运行），三级暴露，成本可控
• 创建向导 — 一条命令生成规范技能骨架，生成即自检，新技能从出生起就是干净的
• 校验与统计 — 发现时强校验（命名/元数据），audit/check/forge 时全量审计；运行时账本记录扫描、加载、运行、创建等活动
• 零依赖 — 纯 Python 标准库实现（≥3.10），目录即插件，无需安装任何第三方包

技能目录（catalog）
    │  按 zone 优先级发现：workspace > personal > bundled > extra-*
    ▼
技能卡片（card）─────────────► 三级披露
  ├ 索引：name + description + 体积（始终可见）
  ├ 正文：SKILL.md 全文（按需加载，可强制）
  └ 附属：scripts/ references/ assets/（按需读取或运行）

目录结构

skill-manager/
├── manifest.json            # 插件清单（harness 从这里了解本插件；repertoire/manifest.json 为随包副本）
├── repertoire/              # 插件本体（零依赖 Python 包）
│   ├── plugin.py            # 入口：create_plugin() / 工具 / 事件
│   ├── forage.py            # 发现引擎（zone 扫描与冲突裁决）
│   ├── frontmatter.py       # 元数据解析（YAML 子集）
│   ├── card.py              # 技能卡片模型与状态
│   ├── audit.py             # 校验规则（fatal / warning）
│   ├── disclosure.py        # 渐进式披露三级实现
│   ├── atelier.py           # 创建向导（minimal / standard 模板）
│   ├── ledger.py            # 运行统计账本
│   ├── io_bridge.py         # JSON-lines 标准流协议
│   ├── cli.py               # 命令行入口
│   ├── config.py            # 配置模型
│   ├── manifest.json        # 随包分发的清单副本（pip 安装后由它提供 system.manifest）
│   └── skills/              # 自带示例技能（bundled zone，随包分发）
│       ├── change-log-scribe/   #   示例：变更文案技能（含脚本）
│       └── skill-smith/         #   示例：技能撰写规范（元技能）
├── examples/                # 接入示例（harness 演示 + 协议会话）
└── tests/                   # 单元测试（零依赖，unittest）

安装

在 DSH 中安装

dsh plugin --profile demo add github:JohnXu22786/skill-manager

零依赖，两种方式任选：

# 方式一：直接使用（无需安装）
python -m repertoire --help          # 从插件目录运行

# 方式二：安装为命令（可选）
pip install -e .
repertoire --help

快速开始

# 列出全部技能（索引级：名称 / 用途 / 来源 / 体积）
python -m repertoire list

# 加载一个技能的完整正文
python -m repertoire open change-log-scribe

# 读取技能内的附属文件
python -m repertoire peek change-log-scribe scripts/template.py

# 运行技能内的脚本
python -m repertoire run change-log-scribe scripts/template.py fix

# 创建向导：生成新技能骨架（-d 必填，--yes 跳过确认）
python -m repertoire forge my-new-skill -d "做什么 + 何时使用的说明" --template standard --yes

# 全量校验 + 统计
python -m repertoire audit
python -m repertoire status

list、audit、check、status 支持 --json 输出机器可读结果；所有命令支持 --config <文件> 指定配置文件。

技能格式规范

一个技能 = 一个目录 + 一个 SKILL.md 标记文件：

my-skill/
├── SKILL.md          # 必填：YAML 元数据 + Markdown 正文
├── scripts/          # 可选：确定性、可重复执行的脚本
├── references/       # 可选：按需阅读的辅助资料
└── assets/           # 可选：模板、图标等素材

SKILL.md 顶部是 --- 围栏包裹的元数据块：

---
name: my-skill              # 必填：小写 kebab-case，与目录名一致，≤64 字符
description: 一句话说明「做什么 + 何时使用」，是发现与触发的唯一依据
version: 1.0.0              # 可选
license: MIT                # 可选
tags:                       # 可选
  - demo
---
## 何时使用
...

元数据解析器实现为严格的 YAML 子集（纯标准库）：支持普通/单双引号标量、列表、|/> 块标量（含 chomping）、注释；不支持嵌套映射、锚点等高级构造——遇到不支持的内容会报错并给出行号，而不是静默解析错误。需要完整 YAML 的宿主可自行替换该解析器（接口见 repertoire/frontmatter.py）。

多级目录发现

zone 按优先级从高到低：

优先级	zone	默认位置	用途
1	workspace	<项目根>/.dsh/skills	项目私有技能
2	personal	<用户主目录>/.dsh/skills	个人常用技能
3	bundled	<插件目录>/skills	插件自带技能
4	extra-*	配置指定	其他来源

扫描规则：

• 技能目录位于 zone 根下一层（<zone>/<skill>/SKILL.md）或两层（<zone>/<group>/<skill>/SKILL.md，支持分组），更深的目录忽略
• 隐藏目录（. 开头）忽略；标记文件名可配置（默认 SKILL.md）
• 同名冲突：高优先级 zone 胜出，低优先级副本记为「影子」（shadow）——目录中只出现一份，但审计会明确报告被压制的副本及其来源 zone
• 损坏条目：目录里有标记文件但元数据无法解析（如名字与目录不符、非法命名、缺描述），不会进入目录，而是进入「损坏」清单，附具体原因

渐进式披露

级别	内容	触发方式	成本
一级 · 索引	名称、用途、来源、体积、状态	会话开始自动注入（catalog.menu 事件）	极低，不含正文
二级 · 正文	SKILL.md 全文	skill.open 按需加载	受 max_open_bytes 限制，可 force
三级 · 附属	脚本 / 资料 / 素材	skill.peek 读取、skill.run 运行	按需，绝不自动载入

正文加载后卡片进入 open 状态并缓存，skill.drop 释放缓存回到 listed。

校验（audit）

发现阶段做强校验：元数据无法解析、命名非法、名字与目录不符、缺描述的条目不会进入目录，而是进入「损坏」清单。audit（全量）、check（单个）、forge（生成后自检）执行全量审计，发现项分两档：

• fatal — 不可用（缺元数据、命名非法、名字与目录不符、文件不可读）
• warning — 可用但不规范（描述过短、描述复读技能名、正文超行数上限、无标题分节、可选字段类型错误、存在被压制的影子副本）

strict 模式下 warning 全部升级为 fatal，适合需要硬性质量门禁的生态。运行 python -m repertoire audit 即可看到全部发现项。

创建向导（forge）

python -m repertoire forge <name> -d "<说明>" [-t minimal|standard] [-z <zone>] [--version V] [--license L] [--tags a,b] [--yes]

• 名称与描述先过校验：非法 kebab 命名、空描述直接拒绝
• 两个模板：minimal（仅 SKILL.md）、standard（+ scripts / references / assets 目录）
• 目标 zone 目录不存在时自动创建；已存在同名技能目录则拒绝
• 生成后立即对产物执行审计，并自动重新扫描目录——新技能马上可见；中途失败自动回滚已写入的文件

配置

JSON 配置文件（--config <path>）；标量项（marker、各限制值、strict）可用环境变量 REPERTOIRE_* 覆盖，例如 REPERTOIRE_STRICT=1（zone_paths / extra_zone_paths 为结构项，仅配置文件可设）：

{
  "marker": "SKILL.md",
  "max_scan_depth": 2,
  "max_open_bytes": 262144,
  "max_body_lines": 500,
  "peek_cap_bytes": 65536,
  "strict": false,
  "zone_paths": { "workspace": "C:/work/.dsh/skills" },
  "extra_zone_paths": ["D:/shared-skills"]
}

键	默认	说明
marker	SKILL.md	技能标记文件名
max_scan_depth	2	zone 内技能目录最大相对深度
max_open_bytes	262144	正文加载体积上限（force 可绕过）
max_body_lines	500	正文行数告警线
peek_cap_bytes	65536	附属文件单次读取上限
strict	false	warning 升级为 fatal
zone_paths	{}	覆盖默认 zone 位置；额外键成为具名 zone
extra_zone_paths	[]	追加低优先级 zone（自动命名 extra-1…）

接入说明（harness 如何加载本插件）

仓库同时还带一份 dsh.bundle（package.json + cordis.patch.yml + index.js）。 在 profile 中安装 — dsh plugin --profile demo add github:JohnXu22786/skill-manager — 会挂载一行 Cordis 插件注册，由 Node 桥接器拉起 python -m repertoire --io，把全部 8 个工具以及 system.ping / system.manifest 暴露给代理。桥接器用单个长驻进程保持 会话状态，目录缓存与已打开技能卡片与原生会话一致；插件卸载时一并释放。加载期无需 任何 npm 依赖；要求 PATH 上有 Python ≥ 3.10（可用 DSH_REPERTOIRE_PYTHON 指定 解释器、DSH_REPERTOIRE_TIMEOUT_MS 调整请求超时）。若 Python 缺失，桥接器会在启动 时打印清晰错误而不是崩溃。

本插件自包含，harness 只需四步：

import json
from repertoire import create_plugin

# 1. 读取清单（可选，用于注册能力）
manifest = json.loads(open("manifest.json", encoding="utf-8").read())

# 2. 创建实例
plugin = create_plugin()

# 3. 订阅事件 + 启动
plugin.on("catalog.menu", lambda p: inject_into_context(p["menu"]))
plugin.start()                              # 扫描一次并发出 catalog.menu

# 4. 生命周期与工具调用
plugin.handle("session.boot", {})           # 收到 harness 事件后分发
plugin.handle("session.compact", {})        # 上下文压缩后重发菜单
result = plugin.call("skill.open", {"name": "change-log-scribe"})

工具接口（8 个）

工具	参数	返回
catalog.ls	zone? limit?	索引级列表 + zone 清单
catalog.audit	—	全量校验报告 + 运行统计
skill.open	name force?	正文全文 + 字节数
skill.peek	name path	附属文件文本内容
skill.run	name script args? timeout?	退出码 + stdout/stderr
skill.drop	name	释放正文缓存
skill.forge	name description template? zone? version? license? tags?	创建结果 + 自检发现项
skill.check	name	单技能校验报告

事件接口

插件订阅（harness → 插件，调用 plugin.handle(event, payload)）：

事件	触发行为
session.boot	重新扫描 + 发出最新菜单
session.compact	重发最新菜单（上下文压缩后恢复记忆）
catalog.rescan	立即重新扫描

插件发出（插件 → harness，用 plugin.on(event, cb) 订阅）：

事件	载荷要点
catalog.menu	目录索引文本 + 数量（会话开始时注入模型上下文）
catalog.report	全量审计发现项 + 统计快照
catalog.problem	扫描发现损坏条目 / 影子副本
skill.engage	某技能正文被加载
skill.release	某技能正文被释放
skill.forged	新技能创建完成

语言无关接入（JSON-lines 标准流协议）

无法 import Python 的 harness（其他语言、独立进程）可以驱动本插件：

python -m repertoire --io

每行一个请求，每行一个响应（id 对应；无 id 视为通知，不回复）：

→ {"id": 1, "method": "catalog.ls", "params": {}}
← {"id": 1, "ok": true, "result": {"count": 2, "items": [...]}}
→ {"id": 2, "method": "skill.open", "params": {"name": "change-log-scribe"}}
← {"id": 2, "ok": true, "result": {"name": "...", "body": "..."}}
→ {"id": 9, "method": "no.such"}
← {"id": 9, "ok": false, "error": {"message": "unknown method 'no.such'"}}

协议方法 = 上述 8 个工具 + system.ping / system.manifest。完整会话示例见 examples/session.jsonl；最小 harness 演示见 examples/harness_demo.py（python examples/harness_demo.py 直接运行）。

安全边界

• 路径守卫：peek / run 的相对路径必须解析在技能目录内，越界即拒绝
• 发现阶段不跟随符号链接，外部内容无法借链接混入目录
• 二进制与超限附属文件拒绝读取；脚本运行有超时（默认 120s）
• .py 子进程强制 UTF-8 环境；其他脚本类型（.ps1/.bat/.sh）的输出按 UTF-8 解码（缺失字节以替换符呈现，不崩溃）
• 只读操作不修改技能内容；forge 拒绝覆盖已有技能目录，失败自动回滚

运行测试

python -m unittest discover -s tests -p "test_*.py"     # 188 个测试，零依赖

许可证

MIT