DeepSeek Harness 插件开发指南：从零开发到验证安装

DeepSeek Harness 插件开发指南：从零开发到验证安装

一、先搞清楚：DSH 插件到底是什么

DeepSeek Harness（命令行工具叫 dsh）是 DeepSeek 开源的 Agent 框架，它最核心的设计理念只有一句话：Everything is a Plugin（万物皆插件） 。模型适配器是插件、工具注册表是插件、会话日志是插件、UI 是插件，甚至连 Agent 执行循环本身也是插件------框架没有特权核心，你想替换哪块能力，就换掉哪个插件 (Github) 。

从技术形态上看，一个 DSH 插件就是一个导出 apply 函数的 TypeScript/JavaScript 模块 。框架加载插件时调用 apply，并传入一个上下文对象 ctx（来自 Cordis 运行时），你通过 ctx 注册自己的能力：工具、服务、事件监听、Web 路由、Skill......

一个最小插件的骨架长这样：

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

export const name = 'my-plugin'

export function apply(ctx: Context) {
  // 在这里注册工具、服务、事件等能力
}

注意：DeepSeek Harness 目前处于 developer preview 阶段，迭代非常快，官方明确提示会有兼容性破坏式变更。开发插件时务必锁定你所针对的 dsh 版本，并在 README 中写明 (Github) 。

---

二、开发前的环境准备

• 安装 Node.js （以及 pnpm------dsh plugin 命令内部会转发给 pnpm，这是硬性依赖 (Github) ）。
• 确保 dsh CLI 可用：

# 通过 npm 直接运行（默认在 http://127.0.0.1:3080 启动 Web UI）
npx @deepseek-ai/dsh web

或者从源码运行，适合需要跟踪最新开发者文档的场景：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

官方插件开发教程位于仓库的 docs/user/develop/basic/ 目录，从源码运行后可以跟着做 。

---

三、动手开发：插件的三层结构

和「单独一份脚本 / 一份 SKILL.md」相比，一个可分发、可验证的 DSH 插件多了三层东西 ：

第一层：插件声明

package.json 中的 dsh.bundle 字段 告诉 Harness 从哪里启动这个插件；cordis.patch.yml 告诉它怎么把自己挂进现有的配置树（把自己 insert 进 Loader entries） (Github) 。

典型目录结构参考（以一个宿主 + 浏览器双端插件为例） (Github) ：

.
├── package.json       # 包清单：dsh.bundle（bundle 层）+ dsh.client（浏览器插件）声明
├── cordis.patch.yml   # bundle 补丁：挂载进 Loader entries
├── LICENSE
└── lib
    ├── index.js       # 宿主侧：注册工具 / HTTP 路由等
    └── client.js      # 浏览器侧：UI 注入（如设置页标签）

第二层：运行入口（注册能力）

在 apply(ctx) 中把能力注册进运行时。最常见的需求是注册一个 Agent 可调用的工具：

ctx.tools.register(
  defineTool({
    name: 'my_tool',
    description: '描述该工具的作用、前置条件与副作用',
    parameters: { /* JSON Schema */ },
    async execute(args) {
      // 工具实现
    },
  }),
)

工具描述（description）要写清楚三件事：何时调用、必要前置条件、失败语义与副作用 ------这直接决定模型能不能用对你的工具 。如果你注册的是 Skill、模板、参考文件等资源，则交给 ctx.skills；如果是 Web 端能力，可通过 ctx.webServer.register 挂载路由、通过 dsh.client 声明注入浏览器端 UI (Github) 。

第三层：可分发与可验证

• 所有资源（模板、字体、脚本）要随包一起带上，保证在全新环境里安装后能被发现；
• 示例必须真的能跑，输出物要完整可用 ；
• 「两个部署环境可能需要不同的值」一律做成配置字段 ：默认配置写在 cordis.yml / cordis.patch.yml 中，Cordis 加载插件时会用导出的 schema 校验配置并填充默认值 。

这三层结构在第六章的真实插件案例 dsh-workspace-enhance 中都有完整落地，开发时可以对照着看。

---

四、验证：别只在自己的开发目录里自测

这是社区开发者总结的最重要的一条经验：用全新的 Profile 安装验证，而不是只在开发目录里跑 。

1. 单元与功能测试

先保证包自身的测试全过。例如社区某 Skill 迁移插件的做法是：Python 测试 5 项全过、Node 测试 2 项全过，示例输出物（19 页 PPT 渲染出的 PNG）逐张检查尺寸和内容完整性。核心思想是：插件宣称的每一个能力，都有一个可重复执行的验证用例。

2. 用全新 Profile 做安装级验证

# 用本地路径以 link 方式装进一个干净的 profile
dsh plugin --profile web add link:/path/to/your-plugin

# 或者模拟用户从 GitHub 安装
dsh plugin --profile web add github:OWNER/your-repo

安装后重启 dsh web，在全新会话里实际调用插件能力，确认：插件能被发现、Skill 能被搜索到、工具能被 Agent 正常调用、页面/服务正常启动 。

3. 排障利器：打印插件树

dsh --profile web --dump-config

这个命令会把当前真正启动的插件树打印出来。插件明明装了、能力却没出现时，先看这棵树，比对着界面猜快得多 。

4. 常见坑位清单

• 入口文件校验只是兜底 ：安装器一般只检查主入口是否存在且非空，深度语法问题要靠自己测 (Github) 。
• prepare 脚本白名单 ：git 方式安装会从源码构建，如果包的 prepare 脚本不在 pnpm-workspace.yaml 的 allowBuilds 白名单里会失败，CLI 会打印需要放行的 key (Github) 。
• pnpm 与 Node 版本兼容性 ：旧版 pnpm 在新版 Node 上可能报 ERR_INVALID_THIS，必要时升级 pnpm (Github) 。
• profile 是 pnpm workspace 根目录 ：在 profile 目录下执行 dsh plugin add 时可能需要加 -w 参数，否则 pnpm 会拒绝根目录 add (Github) 。
• 平台声明 ：如果插件只适用于 web profile（如声明 platform: web、依赖 @deepseek-ai/dsh-client-runtime），它不会在 TUI 等其他 profile 中生效------安装前确认目标 profile (Github) 。

---

五、安装：一条命令，多种来源

DSH 没有内置插件市场，官方安装路径统一走 dsh plugin 命令（本质是 pnpm 转发器 + bundle 调和器，安装后写入 profile 的 bundles 层栈） (Github) ：

dsh plugin --profile <profile名> add <插件来源>

<插件来源> 支持以下几种形式 (Github) ：

来源形式	示例
npm 包名	dsh plugin --profile web add dsh-market
GitHub 仓库	dsh plugin --profile web add github:owner/repo
git URL	dsh plugin --profile web add git+https://github.com/owner/repo.git
tarball 包	dsh plugin --profile web add https://github.com/owner/repo/archive/refs/tags/v0.4.0.tar.gz
本地路径（调试用）	dsh plugin --profile web add link:$(pwd)

安装后必须重启 DSH （如 dsh web）才会组合新的 bundle，插件能力才会生效；带前端依赖的插件还需要硬刷新页面 (Github) 。

对应的卸载与更新：

# 卸载
dsh plugin --profile web remove <package>

# 更新
dsh plugin --profile web update [package]

同样，卸载/更新后重启 DSH 以移除或刷新该层 (Github) 。

除了命令行，社区还做了图形化的插件市场类插件（在「设置 → 插件」里浏览 GitHub 上 topic:dsh-plugin 的仓库并一键安装），但它们底层调用的依然是官方 dsh plugin 机制 (Github) 。

---

六、实战案例：dsh-workspace-enhance（DSH 工作区加强）

讲完了方法论，来看一个真实落地的插件------dsh-workspace-enhance，一个增强 DSH Web 界面侧栏工作区能力的开源插件，也是一个学习插件开发的绝佳样本。

它解决什么问题

DSH Web 界面默认的工作区浏览器功能比较基础：左侧栏只能看到会话列表，想查看工作区里的文件、Git 状态、提交记录，都得切出去用别的工具。dsh-workspace-enhance 把左侧栏整体改造成工作区文件夹列表 ------每个文件夹展开后有 任务 / 文件 / Git 三个子 Tab ，再配上右侧的文件预览面板，写代码、看文件、查 Git 历史，全在一个界面里完成。

功能一览

模块	能力
任务	每个工作区文件夹下的任务（会话）管理：打开 / 重命名 / 归档 / 彻底删除（二次确认）；文件夹行支持新建任务 / 重命名 / 删除工作区；顶部「＋」一键新建任务
文件	以文件夹为根的文件树（懒加载、可切换显示隐藏文件）；彩色图标区分文件类型；点击文件在右侧预览：代码按语言语法高亮、Markdown 默认渲染 GFM 预览（可切换源码）、图片直接显示
Git	Changes / Graph 双视图：工作区改动列表 + 带 ASCII 分支图的提交记录；支持分支切换过滤、查看单次提交的变更文件与 diff；仅当目录是 Git 仓库时才显示
区头	搜索（文件名 + 内容搜索）、添加工作区（系统目录选择器）、视图选项（按工作区/平铺、最近更新/手动排序）

值得一提的是它对默认界面像素级的对齐：文件夹行 34px、会话行 32px、hover 行为、运行中会话的矩阵动画点、激活下划线等细节全部与内置工作区保持一致------样式直接复用默认工作区的 --dsw-* 变量，装上之后看不出是「外挂」。

架构：一个标准 DSH 插件的完整范式

这个插件几乎把前文讲的「三层结构」全部用到了，值得逐个对照：

1. 插件声明层

dsh-workspace-enhance/
├── package.json       # 插件清单：dsh.client 清单 + dsh.bundle.patch（安装入口）
├── cordis.patch.yml   # bundle patch：向 profile 注入一行插件配置
├── build.mjs          # 构建脚本（esbuild，产出 web2 ModuleLoader 格式 bundle）
├── tsconfig.json      # 类型检查（paths 指向 profile 内的 @deepseek-ai 类型）
├── lib/
│   ├── index.js       # node 半边（宿主进程运行）：RPC 通道 + fs/git/会话删除
│   └── client.js      # client 半边（浏览器运行）：由 src/ 构建产物
├── src/               # client 半边源码（TypeScript/TSX）
└── scripts/           # 测试与校验（node 集成测试、渲染测试、真实 store 测试）

2. 运行入口层------双半边架构

• node 半边 （lib/index.js，在宿主进程运行）：通过 ctx.connection.rpc.handle 注册通用 RPC 通道 /dsh-workspace-enhance，对外提供 fs/list、fs/read、git/log（含 --graph、按分支过滤）、git/status、git/branches、session/delete 等端点------浏览器端需要的一切文件系统和 Git 能力，都走这条通道。
• client 半边 （src/client.tsx 构建为 lib/client.js，在浏览器运行）：注册两个槽位------sidebar.workspaces（priority: -1，遮蔽内置工作区浏览器）渲染文件夹与子 Tab 区域；shell.overlay（additive 列表槽）渲染右侧文件预览面板。

这里有两个值得抄作业的技巧：用 priority: -1 替换内置 UI 而不必修改框架本身，正是「Everything is a Plugin」理念的体现；用 RPC 通道连接双半边，解决了浏览器端无法直接访问文件系统的天然限制。

3. 可分发与可验证层

• 资源随包分发（语法高亮库 inline 打包进 bundle，无外部依赖）；
• scripts/ 目录内置集成测试、渲染测试、真实 store 测试，配合 .github/workflows/ci.yml 持续集成；
• 仓库自带 CONTRIBUTING / CHANGELOG / SECURITY 等完整开源规范文件。

安装与验证（Windows 示例）

仓库地址：https://github.com/luis1232023/dsh-workspace-enhance

# 1. 从 GitHub 直接安装（推荐）
dsh plugin --profile web add github:luis1232023/dsh-workspace-enhance

# 如果是本机开发调试，克隆到本地后在插件目录的上级目录执行：
dsh plugin --profile web add file:./dsh-workspace-enhance

# 该命令会：把插件追加到 profile 的 dsh.profile.bundles；
# 因插件声明了 dsh.bundle.patch，自动把插件配置注入配置树；
# 并在 profile 的 node_modules 里安装插件依赖

# 2. 重启 dsh web 后生效
dsh web

# 3. 验证 bundle 可访问（PowerShell）
Invoke-WebRequest http://127.0.0.1:3080/plugins/dsh-workspace-enhance/client.js

# 4. 打印合成配置树，确认插件在插件树中
dsh --profile web --dump-config

临时禁用也很优雅------不用卸载，编辑 profile 的 cordis.patch.yml 加两行即可：

- id: dsh-workspace-enhance
  disabled: true

删掉这两行（或改回 false）并重启，即可恢复启用。这正是 Cordis 配置树「可组合、可覆盖」特性的实际收益。

注意：插件若声明了 dsh.bundle.patch，卸载时除了 dsh plugin remove，还需清理 cordis.patch.yml 中的对应行并重启，才能做到干净移除。

---

七、发布：让别人能找到你的插件

1. 给 GitHub 仓库添加 dsh-plugin 话题（Topic） ------这是官方和社区目录唯一的发现机制，打上标签后你的插件会出现在各类插件市场与 awesome 列表的搜索结果中 (Github) 。
2. 可选：发布到 npm，让用户可以直接用包名安装 (Github) 。
3. 到 GitHub Discussions 或 DSH Discord 社区分享插件、收集反馈 (Github) 。
4. 把 安装命令、使用方法、前提条件和已知限制 写进 README------这是插件能否被顺利使用的最后一公里 。

---

八、最短路径总结

如果你已经有一套 Skill、脚本或工具想改造成 DSH 插件，最短路径可以压成 5 步 ：

1. 先定义插件解决的一个明确问题------不要一上来就想做大而全；
2. 加入 DSH 能识别的插件声明 （package.json 的 dsh.bundle）和 Cordis 配置（cordis.patch.yml）；
3. 把工具、Skill 或界面注册到运行时 （ctx.tools / ctx.skills / ctx.webServer）；
4. 用全新的 Profile 安装验证 ，别只在开发目录里自测，排障先看 dsh --dump-config 的插件树；
5. 把安装、使用、前提和限制写进 README ，打上 dsh-plugin topic 发布。

Everything is a Plugin------插件体系的价值不在于框架本身多强，而在于它让每个人都能把自己最顺手的工作流，装进同一个 Agent 里。