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

DeepSeek Harness（命令行工具叫 dsh）是 DeepSeek 开源的 Agent 框架。它最核心的设计理念只有一句话：Everything is a Plugin（万物皆插件）。

模型适配器是插件，工具注册表是插件，会话日志是插件，UI 是插件，甚至连 Agent 执行循环本身也是插件。框架没有特权核心，你想替换哪块能力，就换掉哪个插件。

从技术形态上看，一个 DSH 插件就是一个导出 apply 函数的 TypeScript/Ja vaScript 模块。

框架加载插件时会调用 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 中写明。

二、开发前的环境准备

• 安装 Node.js。
• 安装 pnpm。因为 dsh plugin 命令内部会转发给 pnpm，这是硬性依赖。
• 确保 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。

典型目录结构参考如下。这里以一个宿主 + 浏览器双端插件为例：

.
├── 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 挂载路由。
• 浏览器端 UI 则可借助 dsh.client 声明注入。

第三层：可分发与可验证

• 所有资源（模板、字体、脚本）要随包一起带上，保证在全新环境里安装后能被发现。
• 示例必须真的能跑，输出物要完整可用。
• 「两个部署环境可能需要不同的值」一律做成配置字段。

默认配置写在 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. 常见坑位清单

• 入口文件校验只是兜底：安装器一般只检查主入口是否存在且非空，深度语法问题要靠自己测。
• 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 --profile  add <插件来源>

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

来源形式	示例
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 界面侧栏工作区能力的开源插件，也是学习插件开发的绝佳样本。

它解决什么问题

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 列表的搜索结果中
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 里。