一、先搞清楚：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 插件时，务必锁定你所针对的 dsh 版本，并在 README 中清楚写明。
二、开发前的环境准备
- 安装 Node.js（以及
pnpm——dsh plugin命令内部会转发给 pnpm，这是硬性依赖。 - 确保
dshCLI 可用：
# 通过 npm 直接运行（默认在 https://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/ 目录，从源码运行后可以边看文档边实操，更适合入门 DeepSeek Harness 插件开发。
三、动手开发：插件的三层结构
和「单独一份脚本 / 一份 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 注入浏览器端。
第三层：可分发与可验证
- 所有资源（模板、字体、脚本）要随包一起带上，确保用户在全新环境中安装插件后就能正常发现和使用；
- 示例必须真实可运行，输出结果要完整、可复现、可直接验证；
- 「两个部署环境可能需要不同的值」这类内容，一律做成配置字段：默认配置写在
cordis.yml/cordis.patch.yml中，Cordis 加载插件时会通过导出的 schema 校验配置并自动填充默认值。
这三层结构在第六章的真实插件案例 dsh-workspace-enhance 中都有完整体现，开发 DSH 插件时非常值得对照参考。
四、验证：别只在自己的开发目录里自测
这是社区开发者反复强调、也最容易被忽略的一条经验：一定要用全新的 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. 常见坑位清单
- 入口文件校验只是兜底：安装器通常只检查主入口是否存在且非空，真正的语法错误和运行时问题还是要靠你自己测试。
prepare脚本白名单：git 方式安装会从源码构建，如果包的prepare脚本不在pnpm-workspace.yaml的allowBuilds白名单里就会失败，CLI 会打印需要放行的 key。- pnpm 与 Node 版本兼容性：旧版 pnpm 在新版 Node 上可能报
ERR_INVALID_THIS，必要时应升级 pnpm 版本。 - profile 是 pnpm workspace 根目录：在 profile 目录下执行
dsh plugin add时，可能需要追加-w参数，否则 pnpm 会拒绝在根目录执行 add。 - 平台声明：如果插件只适用于 web profile（如声明
platform: web、依赖@deepseek-ai/dsh-client-runtime），它不会在 TUI 等其他 profile 中生效——安装前一定要确认目标 profile。
五、安装：一条命令，多种来源
DSH 本身没有内置插件市场，官方统一通过 dsh plugin 命令来安装插件（本质上是 pnpm 转发器 + bundle 调和器，安装后会写入 profile 的 bundles 层栈）。
dsh plugin --profileadd <插件来源>
<插件来源> 支持以下几种形式：
| 来源形式 | 示例 |
|---|---|
| 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，插件能力才会真正生效；如果插件包含前端依赖，还需要硬刷新页面。
对应的卸载与更新：
# 卸载 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 界面侧栏工作区能力的开源插件，也是学习 DeepSeek Harness 插件开发的优秀范例。
它解决什么问题
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 https://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 中的对应行并重启，才能实现真正干净的移除。
七、发布：让别人能找到你的插件
- 给 GitHub 仓库添加
dsh-plugin话题（Topic）——这是官方和社区目录最核心的发现机制，打上标签后，你的插件更容易出现在各类插件市场和 awesome 列表的搜索结果中 - 可选：发布到 npm，让用户能够直接通过包名安装插件
- 到 GitHub Discussions 或 DSH Discord 社区分享插件并收集反馈
- 把 安装命令、使用方法、前提条件和已知限制 写进 README——这是插件能否被顺利使用的最后一公里。
八、最短路径总结
如果你已经有一套 Skill、脚本或工具，想把它改造成 DSH 插件，最短路径基本可以压缩为 5 步：
- 先定义插件要解决的一个明确问题——不要一开始就追求大而全；
- 加入 DSH 可识别的插件声明（
package.json中的dsh.bundle）以及 Cordis 配置（cordis.patch.yml）； - 把工具、Skill 或界面注册到运行时（
ctx.tools/ctx.skills/ctx.webServer）； - 用全新的 Profile 做安装验证，不要只在开发目录里自测，排障时优先查看
dsh --dump-config输出的插件树； - 把安装、使用、前提条件和限制写进 README，并打上
dsh-plugintopic 后发布。
Everything is a Plugin——DSH 插件体系真正的价值，不只在于框架本身有多强，而在于它让每个人都能把自己最顺手、最高效的工作流，安装进同一个 Agent 体系里。
