DSH plugin 开发教程：从环境准备、脚手架到打包上架，DSH 插件开发完整教程与新手入门流程

DSH plugin 开发教程的完整路径是六步：准备环境 → 创建插件工程 → 写 apply → 用 cordis.yml 挂载调试 → 打包成 bundle → 装进 profile 验证。 前三步让插件跑起来，后三步把它变成别人能装的包。本文按官方文档的顺序给出每一步的确切命令与预期输出。无论你把它叫 DSH插件 还是 DeepSeek插件，走的都是同一套插件框架与同一份命令约定。

DSH plugin 开发第一步：准备环境

DSH plugin 开发需要能跑源码版的 DeepSeek Harness，官方教程从仓库检出开始。 前置条件是 Node 与 pnpm 装好，然后 clone 并安装依赖（来源）：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install

如果你还没装好宿主本体，先按《DSH plugin 开发环境搭建》把 Node 版本与 pnpm 配置妥当——版本不匹配会在后面每一步都制造假故障。

DSH plugin 开发第二步：创建插件工程

在仓库根下建一个临时目录放插件源码，tmp/ 与 scratch-* 都不进版本控制。 官方教程的做法：

mkdir -p scratch-plugin/src

这不是必须叫 scratch-plugin，只是官方示例的命名。真正要遵守的只有一条：插件的模块路径由 profile 目录解析，本地调试时用绝对路径引用最省事，所以把源码放在检出内。

DSH plugin 开发第三步：写 apply 让插件能加载

一个 DSH plugin 最小就是导出 apply 的 TypeScript 模块。 创建 scratch-plugin/src/my-plugin.ts：

import type { Context } from '@deepseek-ai/cordis'

export const name = 'hello-plugin'

export function apply(ctx: Context) {
  // 必需依赖在 apply 运行前就已就绪。
  console.log('[hello-plugin] plugin loaded!')
}

name 是标识，apply 是入口，ctx 是注册能力的通道。想深入导出与命名的规范细节，见《DSH plugin 开发规范》。

DSH plugin 开发第四步：用 cordis.yml 挂载调试

用 --patch 覆盖层把本地插件插进配置树，启动 Web UI 看输出。 三步（来源）：

1. 取仓库根的绝对路径 —— 在仓库根执行 pwd。预期：打印出仓库根的绝对路径，下一步的 name 要用它。

pwd

2. 写覆盖层配置 —— 创建 scratch-plugin/cordis.yml，把 name 换成上一步打印的真实路径：

- insert:
    - id: hello
      name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'

3. 带 patch 启动 —— 执行下面的命令。预期：Web UI 在 http://127.0.0.1:3080 起来，启动过程中终端打印 [hello-plugin] plugin loaded!：

pnpm dsh web --patch ./scratch-plugin/cordis.yml

两个必须记住的点：插件路径必须绝对；patch 文件只贡献配置，不会改变加载器解析模块路径的 profile 目录。

DSH plugin 开发第五步：打包成 bundle

要让别人能装，就得把插件做成「组合包」（bundle）。 目录结构：

hello-plugin/
├── package.json       # 声明 dsh.bundle
├── cordis.patch.yml   # 该组合包贡献的配置层
└── index.js           # patch 行引用的插件模块

package.json 的四项声明：

{
  "name": "dsh-hello-plugin",
  "version": "0.1.0",
  "type": "module",
  "main": "index.js",
  "files": ["index.js", "cordis.patch.yml"],
  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
}

cordis.patch.yml 按包名引用自己：

- insert:
  - id: hello
    name: dsh-hello-plugin

注意这里的差异：调试期的 cordis.yml 用绝对路径指向源文件，发布期的 cordis.patch.yml 用包名——因为安装后包已经在 profile 的依赖里解析得到。

DSH plugin 开发第六步：装进 profile 验证

先 add、再 --dump-config、最后启动，三步都不能省。 dsh plugin 会把参数转发给 profile 目录里的 pnpm（来源）：

1. 装进 profile —— 执行 dsh plugin --profile demo add ./hello-plugin。预期：包被写进 profile 依赖；因为包声明了 dsh.bundle，DSH 会把它追加进 dsh.profile.bundles。
2. 核对配置层 —— 执行 dsh --profile demo --dump-config。预期：打印出的配置树里能看到你的 patch 行。跳过这一步直接启动，很容易把「没挂载」误判成「插件代码有 bug」。
3. 启动验证 —— 执行 dsh --profile demo。预期：插件在运行中的插件树里生效，终端能看到它的输出。

想先看看社区里同类插件的成品长什么样，可以在 DSH Plugin Hub 里挑一个装起来对照。

六步跑通后，最容易卡住的三处：

1. 路径写成相对路径 —— 第四步的 cordis.yml 里 name 必须是绝对路径，否则加载器从 profile 目录解析，找不到文件。
2. 打包漏了 cordis.patch.yml —— files 里没写它，npm 不会带上，安装方拿不到配置层，插件装了不挂载。
3. 本地目录安装与发布包混淆 —— dsh plugin add ./hello-plugin 装的是本地目录，与从 npm 装包的解析路径不同；本地目录安装的细节见《DSH plugin 本地目录安装》。

六步走通后，把成品提交到社区收录的流程见《DSH plugin 发布到插件市场》；如果插件装上了但一直不激活，按《DSH plugin 装了不生效》用 Fiber 状态定位。

来源：官方「你的第一个插件」、官方 Cordis 教程、dsh CLI README