从源码环境搭建到插件实战，循序渐进掌握如何使用DeepSeek Harness插件！
核心内容：
1. 环境准备与Harness源码配置，包含Node.js版本要求
2. 开发最小 greet 插件，理解工具定义、注册与调用流程
3. 安装第三方插件，快速获得完整能力并直接上手

Datawhale干货

最新：DeepSeek Harness

在上一篇 DeepSeek Harness 保姆级安装教程之后，我们继续深入一个最关键的主题：因为 DeepSeek Harness 的核心设计原则就是“一切皆插件”，所以今天带大家系统了解如何使用插件、开发插件，以及安装现成插件。

这件事可以分成两个部分：

1. 自己动手写一个最小插件，理解 Harness 如何注册工具。
2. 安装别人已经写好的插件，直接获得完整能力并快速投入使用。

第一部分帮助你理解底层机制，第二部分更适合日常高效使用。

保姆教程：写一个DeepSeek Harness的最小插件

我们先实现一个 greet 工具。当 Agent 调用它并传入名字后，插件会返回：

你好，Datawhale！你的第一个 Harness 插件已经运行。

1. 准备源码环境

如果只是直接体验 Harness，使用 npx @deepseek-ai/dsh web 基本就够了。但如果你想开发原始 TypeScript 插件，就需要进入 Harness 源码仓库，这也是官方入门文档推荐的方式。

git clone https://github.com/deepseek-ai/deepseek-harness.gitcd deepseek-harness
corepack enablepnpm installpnpm run build

本文实测使用的 Node.js 版本是 v24.19.0。Harness 官方声明支持的 Node.js 范围为 ^22.19.0 || >=24.0.0，如果你不确定该选哪个版本，直接使用 Node 24 通常最稳妥。

pnpm run build 这一步不要省略。我第一次只执行了依赖安装，虽然插件日志已经输出，但 Web 页面因为缺少构建产物而无法正常展示。

2. 创建插件文件

继续在 deepseek-harness 仓库根目录执行：

mkdir -p scratch-plugin/src

然后新建 scratch-plugin/src/greet-tool.ts：

import type { Context } from '@deepseek-ai/cordis'import { defineTool } from '@deepseek-ai/dsh-tools'
export const name = 'greet-tool'export const inject = ['tools']
export function apply(ctx: Context) {  ctx.tools.register(defineTool({    name: 'greet',    description: 'Greet someone by name.',    parameters: {      name: {        type: 'string',        required: true,        description: 'The name to greet',      },    },    output: {      schema: { type: 'string' },      render: (_args, value) => [{ type: 'text', text: value }],    },    async execute(args) {      return `你好，${args.name}！你的第一个 Harness 插件已经运行。`    },  }))  console.log('[greet-tool] loaded; tool name: greet')}

这里先不用急着研究所有类型定义。这个最小插件主要包含四个部分：

• name：插件名称。

• inject：声明需要注入 Harness 的工具服务。

• apply(ctx)：插件加载时的入口函数。

• ctx.tools.register(...)：注册一个可被模型调用的工具。

parameters 用于告诉模型应该传入什么参数；execute 负责真正执行逻辑代码；output 则定义结果类型以及最终的展示方式。

3. 把插件插入 Harness

先执行 pwd，获取当前 Harness 仓库的绝对路径。

接着新建 scratch-plugin/cordis.yml：

- insert:    - id: greet-tool      name: '/Users/yourname/deepseek-harness/scratch-plugin/src/greet-tool.ts'

把 name 替换为你本机上的绝对路径。

插件最好放在 Harness 源码仓库内部。因为这个示例依赖仓库中的 @deepseek-ai/cordis 和 @deepseek-ai/dsh-tools，如果放到其他目录，可能会遇到 Cannot find module 之类的模块找不到错误。

4. 启动并检查

pnpm dsh web --patch ./scratch-plugin/cordis.yml

如果 3080 端口已经被占用，可以改用其他端口，例如：

pnpm dsh web --patch ./scratch-plugin/cordis.yml --port 3082

看到下面两行输出，就说明插件和 Web 服务都已经正常启动：

[greet-tool] loaded; tool name: greetdsh web: http://127.0.0.1:3082

进入“设置 → 插件 → 插件列表”，搜索 greet-tool.ts，它的状态应显示为“已启用”。

插件已经成功挂载

5. 让 Agent 调用它

选择工作区，新建一个标准模式会话，然后输入：

请调用 greet 工具问候 Datawhale。

展开工具调用后，你可以看到输入参数和输出结果：

IN   { "name": "Datawhale" }OUT  你好，Datawhale！你的第一个 Harness 插件已经运行。

greet 工具调用成功

到这里，一个最小可运行的 DeepSeek Harness 插件闭环就完成了：加载插件、注册工具、模型调用、返回结果，整个流程已经打通。

直接安装生产级的插件

greet 更适合用来学习插件机制，但并不能解决真实业务问题，而且从零开发一个完整插件的门槛并不低。所以在实际使用中，直接安装成熟的第三方插件往往更高效。

这里以 DSH Vision Toolkit 为例，DeepSeek 当前这一条 Chat Completions 路由属于纯文本模型，因此无法直接理解图片内容；而 Vision Toolkit 可以先把图片交给独立的视觉模型处理，再将识别得到的文字、坐标以及文件产物回传给 Harness。

它提供的能力包括图片问答、OCR 识别、元素定位、图片裁剪、像素对比以及 HTML 截图等常见视觉工具。

1. 安装插件

如果你的终端环境里已经有 dsh 命令，可以直接执行：

dsh plugin --profile web add @dsh-external/dsh-vision-toolkit

如果你和上一篇一样一直使用 npx，那也可以写成：

npx @deepseek-ai/dsh@0.1.0-rc.6   plugin --profile web add @dsh-external/dsh-vision-toolkit

将插件安装到 web Profile 后，建议检查配置中是否已经成功出现对应项：

dsh --profile web --dump-config | grep vision-toolkit

随后记得重启正在运行的 Harness Web 服务。因为插件的宿主端代码和浏览器端代码都会在启动时加载，仅仅刷新浏览器页面通常是不够的。

2. 配置视觉模型

Vision Toolkit 要求 Python 3.11 或更高版本。第一次使用 managed 运行时时，还需要联网安装它锁定的 Python 依赖包。

打开 Harness 的“设置 → 视觉工具”，并配置以下内容：

• 一个兼容 OpenAI 接口的视觉模型地址；
• 对应的视觉模型名称；
• 一个 DSH Credential 引用，例如 VISION_API_KEY。

密钥可以通过命令写入 Harness 的凭据系统：

dsh credentials set VISION_API_KEY

这里填写的应该是视觉服务的 Key，而不是默认的 DeepSeek 文本模型 Key，除非你当前使用的网关本身明确同时提供视觉模型能力。

在设置页面点击“测试连接”。远程图片问答、元素定位和 OCR 等能力需要视觉服务支持；而裁剪、颜色分析、像素对比等本地工具则不需要额外 Key。

3. 在会话中使用

先把图片复制到当前工作区中，例如：

./screenshot.png

在会话里先加载插件附带的 Skill：

/vision-tools

接着就可以直接描述你的任务，例如：

请用 vision_glance 分析 ./screenshot.png，告诉我页面上出现了什么错误。

也可以执行更具体的视觉分析工作：

请用 vision_ground 定位截图里的发送按钮，并生成带标注的预览图。请比较 reference.png 和 actual.png，告诉我差异最大的区域。

插件会根据需要向当前 Agent 暴露相应的 vision_* 工具。生成的裁剪图、热力图以及分析报告，会保存在工作区的 .dsh-vision-toolkit/artifacts 目录中。

4. 更新或卸载

dsh plugin --profile web updatedsh plugin --profile web remove @dsh-external/dsh-vision-toolkit

执行这些操作后，记得重新启动 Web Profile。

安装第三方插件前的注意事项

• 仓库是否公开，许可证信息与维护者身份是否清晰；
• 安装脚本会下载哪些内容，是否会额外执行其他程序；
• 插件需要哪些目录权限、网络权限和凭据权限；
• 是否明确说明支持的 Harness 版本、卸载方式以及测试方法。

Harness 插件运行在宿主进程中，本质上属于可信代码执行环境。不要因为安装命令只有一行，就忽略源码审查和权限检查。

写在最后

自己写插件时，最小结构可以概括为：

apply(ctx) → 注册工具 → execute(args) → 返回结构化结果

而使用现成插件时，常见流程则是：

plugin add → 重启 Profile → 配置凭据 → 加载 Skill → 调用工具

前者帮助你真正理解 DeepSeek Harness 插件开发机制，后者则让 Harness 在实际场景中变得更强大、更实用。

一起“点赞”三连↓

登录查看剩余 70% 内容