5. 分发与发布

5.1 bundle 与 profile

DSH 有两个分发概念，都在 package.json 的 dsh 键下声明：

// bundle：一个携带配置层的 npm 包。
{ "name": "dsh-hello-plugin", "type": "module", "main": "index.js",
  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } } }

// profile：$DSH_HOME/profiles/<name> 下的一次可运行组合。
{ "dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "dsh-hello-plugin"] } } }

cordis.patch.yml 插入你的插件行：

# `name` 是「包名」（通过 profile 的 node_modules 或回退 $DSH_HOME/profiles/node_modules 解析），
# 不是相对路径。
- insert:
    - id: spike-tool-time
      name: dsh-spike
    - id: spike-lifecycle-logger
      name: dsh-spike/lifecycle

层序（后层覆盖前层，按 id 整行替换）：每个 bundle 的 cordis.patch.yml（按 profile.bundles 顺序） → profile 自己的 cordis.patch.yml → $DSH_HOME/cordis.patch.yml → 每个 --patch <path> 覆盖层（argv 顺序）。

5.2 bundle 的 package.json

{
  "name": "dsh-spike",
  "version": "0.1.0",
  "type": "module",
  "main": "./dist/tool-time.js",
  "exports": { ".": "./dist/tool-time.js", "./lifecycle": "./dist/lifecycle-logger.js" },
  "files": ["dist", "cordis.patch.yml"],
  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } },
  "dependencies": { "@deepseek-ai/dsh-tools": "^0.1.0-rc.6" },
  "peerDependencies": { "@deepseek-ai/cordis": "^4.0.1" },
  "devDependencies": { "@deepseek-ai/cordis": "^4.0.1", "@deepseek-ai/dsh-session": "^0.1.0-rc.6", "typescript": "^5.6.0" }
}

5.3 版本坑

1. @deepseek-ai/dsh-tools 锁 next tag 版本。 npm 的 latest tag 是过期的 0.0.1-rc.1；真正的版本线是 next（0.1.0-rc.x）。裸 npm i @deepseek-ai/dsh-tools 会装到坏掉的旧线。create-dsh-plugin 在生成时解析当前 next 版本并精确锁定。
2. 所有 @deepseek-ai/dsh-* 保持同一 0.1.0-rc.x 版本线，避免 pnpm 装出两份 dsh-tools。
3. @deepseek-ai/cordis 是 peerDependency——只用 import type；运行时 ctx 由宿主传入。
4. 纯 ESM（"type": "module"）；tsc 用 module: esnext + moduleResolution: bundler 保留裸 specifier。
5. Node ^22.19.0 || >=24.0.0（旧 Node 只警告 EBADENGINE）。

---

← Prev: 调试与验证工作流 · Contents · Next: FAQ — 十四个最易踩的坑 →