dsh-npm

Files (3)

• SKILL.md
• templates.md · references/
• troubleshooting.md · references/

SKILL.md (first lines)

# DSH 插件适配与 npm 发布

## 目标

产出一个 `name@version`，在 `registry.npmjs.org` 上可安装；用户在 DSH 的 **Plugins → Add plugin** 里只填包名（或 `包名@版本`）就能得到：

- 一个 stdio MCP server，工具以 `mcp__<serverName>__<tool>` 暴露；
- 一个或多个 skill，出现在会话技能目录；
- 可选的 bundle 标题、描述、图标。

DSH 的 Add plugin 支持四种来源：npm 包名、Git 地址、tarball URL、本地绝对路径。npm 包名只是其中一种，但它是第三方安装体验最好的一种。

## 先做三个决定

| 问题 | 建议 |
|---|---|
| 只注册 skill，还是要连 MCP server？ | 只要 skill：一个 Host 插件行即可；要 MCP：再加 `@deepseek-ai/dsh-mcp-client` 行 |
| 包名用无 scope 还是 `@scope/name`？ | 无 scope 最容易让用户输入；先 `npm view <name> version`，404 只表示当前可用，不保留 |
| 包和 Python/CLI 同版本吗？ | 是。DSH bundle 只装注册层，CLI 仍要用户自己安装；版本对齐便于排障 |

## 目录骨架

```text
dsh-plugin/
  package.json
  cordis.patch.yml
  index.js
  locale/en.json
  locale/zh.json
  icon.png                 # 可选，128x128 PNG
  skills/
    my-skill/SKILL.md      # npm 包内必须自包含
  scripts/sync-skills.mjs  # 从仓库其他位置复制 skill
  README.md
  LICENSE
```

`README.md` 和 `LICENSE` 会被 npm 默认/显式打包；`skills/` 必须写进 `files`。

## 1. package.json

最小可用字段：

```json
{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "DeepSeek Harness bundle for ...",
  "type": "module",
  "license": "Apache-2.0",
  "exports": {
    ".": "./index.js",
    "./locale/*.json": "./locale/*.json",
    "./icon": "./icon.png",
    "./package.json": "./package.json"
  },
  "files": [
    "index.js",
    "cordis.patch.yml",
    "locale/*.json",
    "icon.png",
    "README.md",
    "LICENSE",
    "skills/**"
  ],
  "scripts": {
    "sync-skills": "node scripts/sync-skills.mjs",
    "check-skills": "node scripts/sync-skills.mjs --check",
    "prepack": "node scripts/sync-skills.mjs"
  },
  "publishConfig": { "access": "public" },
  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
}
```

关键点：

- **不要** `private: true`；它会让 `npm publish` 直接失败。
- `dsh.bundle.patch` 必须指向包内文件，且该文件必须在 `files` 里，否则装完 DSH 找不到 bundle。
- `exports` 至少暴露 `"."`；`locale` 和 `icon` 用于 UI 显示。`./package.json` 便于工具读取清单。
- `prepack` 在 `npm pack` / `npm publish` 前运行，生成的文件会进入 tarball；从 registry 安装时不会再次运行。
- `publishConfig.access: public` 避免 scoped 包默认 private。

## 2. cordis.patch.yml

```yaml
- insert:
    - id: my-plugin-mcp
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: myplugin          # 工具前缀 mcp__myplugin__...
        transport: stdio
        command: my-cli               # 必须在 DSH 进程的 PATH 上
        args:
          - run
        toolCallTimeoutMs: 1800000    # 长任务（批量下载/索引）按需放大
        failOnStartupError: false     # CLI 没装时不要让整个 harness 启动失败

    - id: my-plugin-skills
      name: my-plugin                 # 等于 package.json 的 name
      config: {}
```

规则：

- 每一行 `id` 唯一；`name` 是模块名。Host 插件行写包名；MCP 行写 `@deepseek-ai/dsh-mcp-client`。
- `serverName` 决定工具命名空间；不要用会变的版本号。
- 没有 MCP server 时删掉第一行，只保留 skill 行。
- 需要多个 server 时复制 MCP 行，换 `id` / `serverName` / `command`。
- `failOnStartupError: false` 时，CLI 缺失不会阻止 DSH 启动，但工具不会出现；skill 必须告诉用户怎么装 CLI。

## 3. index.js（注册 skill）

```js
import { readFileSync } from 'node:fs'
import { dirname, resolve } from 'node:path'
import { fileURLToPath } from 'node:url'

const packageRoot = dirname(fileURLToPath(import.meta.url))

From Rimagination/scansci-pdf, MIT.

More from Rimagination/scansci-pdf