DeepSeek Harness中插件开发的完整指南

DeepSeek Harness中插件开发的完整指南并不只看表面做法，关键还要理解相关条件、限制和后续影响。

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

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

从技术形态上看，一个 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 中写明 。

二、开发前的环境准备

1. 安装 Node.js（以及 pnpm——dsh plugin 命令内部会转发给 pnpm，这是硬性依赖。
2. 确保 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.gitcd deepseek-harnesspnpm installpnpm run buildpnpm dsh web

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

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

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

第一层：插件声明

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

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

.

├── 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。

第三层：可分发与可验证

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

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

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

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

1. 单元与功能测试

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

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

# 用本地路径以 link 方式装进一个干净的 profiledsh 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. 常见坑位清单

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

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

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

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

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

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

对应的卸载与更新：

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

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

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

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

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

它解决什么问题

DSH Web 界面默认的工作区浏览器功能比较基础：左侧栏只能看到会话列表，想查看工作区里的文件、Git 状态、提交记录，都得切出去用别的工具。dsh-workspace-enhance 把左侧栏整体改造成工作区文件夹列表——每个文件夹展开后有 任务 / 文件 / Git 三个子 Tab，再配上右侧的文件预览面板，写代码、看文件、查 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. 运行入口层——双半边架构

1. 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 能力，都走这条通道。
2. client 半边（src/client.tsx 构建为 lib/client.js，在浏览器运行）：注册两个槽位——sidebar.workspaces（priority: -1，遮蔽内置工作区浏览器）渲染文件夹与子 Tab 区域；shell.overlay（additive 列表槽）渲染右侧文件预览面板。

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

3. 可分发与可验证层

1. 资源随包分发（语法高亮库 inline 打包进 bundle，无外部依赖）；
2. scripts/ 目录内置集成测试、渲染测试、真实 store 测试，配合 .github/workflows/ci.yml 持续集成；
3. 仓库自带 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 列表的搜索结果中 
2. 可选：发布到 npm，让用户可以直接用包名安装
3. 到 GitHub Discussions 或 DSH Discord 社区分享插件、收集反馈
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 里。