DeepSeek Harness 插件使用方式

面向 DSH 用户与开发者:从找插件 → 安装 → 验证 → 开发 → 发布全流程。DSH 当前处于 Developer Preview,命令与 API 可能随版本变化,遇到不一致以官方仓库为准。

一、插件是什么

DSH 的核心理念是 "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) {
  // 在这里注册工具、服务、事件等能力
}

二、去哪里找插件

渠道	说明
GitHub `dsh-plugin` Topic	官方和社区目录唯一的发现机制,打上该 topic 的仓库会被各类插件市场收录
Web UI「设置 → 插件」	社区图形化插件市场,可浏览 GitHub 上 `topic:dsh-plugin` 的仓库并一键安装(底层仍是 `dsh plugin` 命令)
官方 Discussions	官方发布插件系列(如 14 个零配置工具插件:dsh-http、dsh-case、dsh-fmt 等)
社区插件站	dsh-plugin.org 等(可搜 DSH Plugin Hub / dshmarket 插件市场)

三、安装插件(核心)

1. 前提

先跑通 DSH 本体(启动过一次 npx @deepseek-ai/dsh web,web profile 会自动初始化),并确认本机有 Node.js + pnpm(dsh plugin 内部会转发给 pnpm)。

2. 一条命令安装

bash

dsh plugin --profile web 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 plugin --profile web add file:./my-plugin`

命令本质:把插件 pnpm add 到 $DSH_HOME/profiles/web/node_modules,并把插件写入 profile 的 bundles 层栈。

3. 生效与重启

bash

# 安装后必须重启 DSH 才会组合新的 bundle
dsh web

带前端依赖的插件,重启后还需在浏览器硬刷新页面(Ctrl+Shift+R)。

4. 卸载与更新

bash

# 卸载
dsh plugin --profile web remove <包名>

# 更新(可指定包,也可全部)
dsh plugin --profile web update [包名]

同样,卸载/更新后重启 DSH 生效。

四、验证与排障

安装后确认插件真正生效:

bash

# 1. 打印当前真正启动的插件树(插件装了能力却没出现,先看这棵树)
dsh --profile web --dump-config

# 2. 验证 bundle 可访问(以 workspace-enhance 为例)
# 浏览器访问:http://127.0.0.1:3080/plugins/<插件名>/client.js
Invoke-WebRequest http://127.0.0.1:3080/plugins/dsh-workspace-enhance/client.js

# 3. 在全新会话里实际调用插件能力,确认工具/Skill/页面正常

临时禁用(不用卸载)

编辑 profile 的 cordis.patch.yml,加两行即禁用;删掉(或改回 false)并重启即恢复:

yaml

- id: dsh-workspace-enhance
  disabled: true

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

五、开发自己的插件

环境准备

Node.js + pnpm(dsh plugin 依赖 pnpm)
DSH CLI 可用(npx @deepseek-ai/dsh web 或源码运行)

插件的三层结构

第一层:插件声明

package.json 的 dsh.bundle 字段告诉 Harness 从哪启动插件;cordis.patch.yml 告诉它如何把自己挂进现有配置树。

典型目录结构(宿主 + 浏览器双端插件):

my-plugin/
├── package.json        # dsh.bundle(bundle 层)+ dsh.client(浏览器插件)声明
├── cordis.patch.yml    # bundle 补丁:挂载进 Loader entries
├── LICENSE
└── lib/
    ├── index.js        # 宿主侧:注册工具 / HTTP 路由 / RPC
    └── client.js       # 浏览器侧:UI 注入(如设置页标签)

第二层:运行入口(注册能力)

在 apply(ctx) 中注册 Agent 可调用的工具:

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

其他能力入口:

注册 Skill/模板/参考文件 → ctx.skills
挂载 Web 路由 → ctx.webServer.register
浏览器端 UI → 通过 dsh.client 声明,由 lib/client.js 注入
双半边通信(浏览器无法直接访问文件系统)→ 宿主侧用 ctx.connection.rpc.handle 开 RPC 通道

工具 description 要写清三件事:何时调用、必要前置条件、失败语义与副作用——这直接决定模型能不能用对你的工具。

第三层:可分发与可验证

所有资源(模板、字体、脚本)随包一起带上,保证全新环境安装后可用;
示例必须真的能跑,输出物完整可用;
不同环境需要不同值的配置一律做成配置字段,默认值写在 cordis.yml / cordis.patch.yml,Cordis 会用导出的 schema 校验并填充。

验证开发成果

关键经验:用全新 Profile 安装验证,别只在开发目录里自测。

bash

# 本地 link 方式装进干净 profile
dsh plugin --profile web add link:/path/to/your-plugin

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

# 重启后实际调用,并打印插件树确认
dsh web
dsh --profile web --dump-config

六、发布插件

给 GitHub 仓库添加 dsh-plugin topic ——官方和社区目录唯一的发现机制;
可选:发布到 npm,让用户可用包名直接安装;
到 GitHub Discussions / DSH Discord 社区分享、收集反馈;
把安装命令、使用方法、前提条件和已知限制写进 README。

七、常见坑位清单

坑	处理
装了没生效	重启 `dsh web`;带前端依赖的硬刷新页面;再看 `--dump-config` 插件树
`prepare` 脚本被拒	git 方式安装会从源码构建,`prepare` 脚本需在 `pnpm-workspace.yaml` 的 `allowBuilds` 白名单中,CLI 会提示需要放行的 key
pnpm/Node 版本冲突	旧版 pnpm 在新版 Node 上可能报 `ERR_INVALID_THIS`,必要时升级 pnpm
profile 目录 add 失败	profile 是 pnpm workspace 根目录,在该目录下 `dsh plugin add` 可能需要加 `-w` 参数
插件在别的 profile 不生效	插件声明了 `platform: web` 或依赖 `@deepseek-ai/dsh-client-runtime` 时只在 web profile 生效,安装前确认目标 profile
入口文件校验只是兜底	安装器只检查主入口存在且非空,深度语法问题要靠自己测
版本兼容	Developer Preview 阶段迭代快,开发时锁定目标 dsh 版本,README 写明兼容版本

八、实用插件示例

插件	作用	安装
dsh-http	结构化 HTTP 请求:方法/头/体、状态码/耗时/大小、Bearer/Basic 占位、JSON 自动解析、截断保护	`dsh plugin --profile web add dsh-http`
dsh-case	命名大小写转换:camel/Pascal/snake/kebab/CONSTANT 等 8 种风格,自动检测输入	`dsh plugin --profile web add dsh-case`
dsh-fmt	JSON/YAML/TOML/SQL 格式化与校验,错误精确到行列	`dsh plugin --profile web add dsh-fmt`
dsh-workspace-enhance	增强 Web 界面侧栏:工作区文件夹列表 + 任务/文件/Git 三个子 Tab + 文件预览面板	`dsh plugin --profile web add github:luis1232023/dsh-workspace-enhance`
dshmarket	社区插件市场(图形化浏览安装)	`dsh plugin --profile web add dshmarket`

参考来源

官方仓库:https://github.com/deepseek-ai/deepseek-harness
官方文档(开发插件):https://deepseek-harness.github.io/deepseek-harness/
官方 Discussion(零配置插件系列):https://github.com/deepseek-ai/deepseek-harness/discussions/2428
社区插件开发指南:https://blog.csdn.net/m0_37988015/article/details/163828355
社区插件站:https://deepseek-harness-plugin.com

DeepSeek Harness 插件使用方式 ​

一、插件是什么 ​

二、去哪里找插件 ​

三、安装插件(核心) ​

1. 前提 ​

2. 一条命令安装 ​

3. 生效与重启 ​

4. 卸载与更新 ​

四、验证与排障 ​

临时禁用(不用卸载) ​

五、开发自己的插件 ​

环境准备 ​

插件的三层结构 ​

验证开发成果 ​

六、发布插件 ​

七、常见坑位清单 ​

八、实用插件示例 ​

参考来源 ​

DeepSeek Harness 插件使用方式

一、插件是什么

二、去哪里找插件

三、安装插件(核心)

1. 前提

2. 一条命令安装

3. 生效与重启

4. 卸载与更新

四、验证与排障

临时禁用(不用卸载)

五、开发自己的插件

环境准备

插件的三层结构

验证开发成果

六、发布插件

七、常见坑位清单

八、实用插件示例

参考来源