dsh-skill-adapter

Readme

# dsh-skill-adapter

把 **Claude Code / Codex 生态的 SKILL.md 技能**导入或运行时挂载进 **DeepSeek Harness（DSH）**。

DeepSeek Harness 原生就认 `<name>/SKILL.md`（YAML frontmatter + Markdown），frontmatter 键名也与 Anthropic 规范对齐（`name` / `description` / `whenToUse` / `disable-model-invocation` / `user-invocable`）。缺的只是**导入、归一化与分发工具链**——本仓库补上这一环，让你把 [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills)、[ckorhonen/claude-skills](https://github.com/ckorhonen/claude-skills) 等数万星技能库一键搬进 DSH。

## 能力

| 包 | 形态 | 作用 |
|---|---|---|
| `@dsh-skill-adapter/core` | 库 | SKILL.md 解析（零依赖手写 YAML 子集）、frontmatter 归一化、本地/GitHub 源扫描 |
| `@dsh-skill-adapter/cli` | CLI | `dsh-skill-import`：批量抓取 → 校验 → 归一化 → 写盘 → 兼容性报告 |
| `@dsh-skill-adapter/plugin` | DSH 插件 | 注册一个 `SkillProvider`，运行时把 GitHub / 本地目录的技能动态挂载进 DSH |

**归一化规则**（对齐 DSH `skill-filesystem` 的行为）：

- 必需 frontmatter `name` + `description`（缺一即跳过并报告）
- `name` 非法时自动转 kebab-case
- `when-to-use` / `when_to_use` → `whenToUse`
- `disable-model-invocation`、`user-invocable` 透传为调用控制
- 其余字段（如 Claude 的 `allowed-tools`、`metadata`）保留进 metadata

## 快速开始

```bash
git clone <本仓库> && cd dsh-skill-adapter
# 零运行时依赖，无需 npm install，Node ≥ 18.17 直接跑
```

### 方式一：CLI 导入器（一次性导入到 DSH skills 目录）

```bash
# 从 GitHub 技能库导入（默认输出到 ~/.dsh/skills，即 DSH 的 user-dsh root）
node packages/cli/src/cli.js \
  --source github:addyosmani/agent-skills \
  --verbose

# 多个源 + 指定输出目录 + 预览
node packages/cli/src/cli.js \
  --source github:ckorhonen/claude-skills \
  --source local:./my-skills \
  --out ~/.dsh/skills \
  --dry-run --verbose

# 输出 JSON 报告
node packages/cli/src/cli.js --source local:./examples/skills --json
```

source 语法：`github:owner/repo[@ref][:path1,path2]` 或 `local:/path`（可重复 `--source`）。

装好后，技能即出现在 `<projectRoot>/.dsh/skills` 或 `~/.dsh/skills`，DSH 会自动发现。

### 方式二：DSH 插件（运行时动态挂载，免拷贝）

**推荐用官方安装命令**（仓库根即插件包，`dsh.bundle` 声明在根 package.json）：

```bash
dsh plugin --profile web add github:<你的用户名>/dsh-skill-adapter
# 或本地目录：dsh plugin --profile web add D:\路径\dsh-skill-adapter
```

安装后编辑已安装包的 `cordis.patch.yml`，把 `sources` 改成你的技能源（GitHub 仓库 / 本地目录均可）：

```yaml
- insert:
    - id: dsh-skill-adapter
      name: dsh-skill-adapter
      config:
        cacheTtlMs: 300000   # 列表缓存毫秒数（默认 5 分钟）
        sources:
          - type: github
            owner: addyosmani
            repo: agent-skills
          - type: local
            root: /path/to/my/skills
```

重启 `dsh web` 后，DSH 的 `skill` 工具即可看到这些技能。

**或手动在 `cordis.yml` 里挂载**（不依赖安装命令）：

```yaml
- "dsh-skill-adapter":
    sources:
      - { type: github, owner: addyosmani, repo: agent-skills }
      - { type: local, root: /path/to/my/skills }
    cacheTtlMs: 300000
```

插件注入 `skills` 服务，形态对齐官方 `dsh-skill-filesystem`；无需改 DSH 核心。完整发布步骤见 [PUBLISH.md](PUBLISH.md)。

## 目录结构

```
packages/
  core/     # 解析 + 归一化 + 源扫描（零依赖）
  cli/      # 导入编排 + 报告 + 命令入口
  plugin/   # DSH SkillProvider 插件
examples/
  skills/   # 演示用技能样本
  out/      # CLI 导入的写盘产物（示例）
scripts/
  smoke.mjs # 冒烟测试（本地源 + GitHub 源）
shims/
  node.d.ts # 最小 Node/全局/cordis 类型声明（仅用于 tsc check）
```

## 开发

```bash
npm run check   # tsc checkJs 类型检查
npm run smoke   # 冒烟测试（node scripts/smoke.mjs）
```

## 发布到 DSH 生态

按官方 [CONTRIBUTING.zh.md](https://github.com/deepseek-ai/deepseek-harness/blob/main/CONTRIBUTING.zh.md) 的指引：给本仓库打上 GitHub 话题 **`dsh-plugin`**（`@dsh-skill-adapter/plugin` 的 package.json 已含该 keyword），即可被 [dsh-recommend registry](https://github.com/topics/dsh-plugin)（每日自动重算）收录，出现在 Web GUI 的插件推荐里。

## 兼容性说明（与 DSH 的关系）

DSH 的 skill 子系统（`docs/subsystems/skills.md`）提供：

- 本地发现：`<name>/SKILL.md` 或 `<name>.md`，frontmatter 必需 `name` + `description`
- 远程 provider：`ctx.skills.registerProvider(create)` —— 本仓库的 plugin 包即基于此

因此本仓库做的不是「格式转换」，而是把 Claude/Codex 生态技能里的**键名差异、缺字段、命名不规范**等小差异自动抹平，并提供两种进 DSH 的方式（拷贝 / 动态挂载）。