怎么给 DeepSeek Harness 写个插件从打印一行日志开始把text_stats注册成模型可以主动调用的 Tool。2026 年 8 月 15 日我给刚开源的 DeepSeek Harness 写了一个很小的插件统计一段文字的字符数和单词数。最后一次测试时我没有告诉模型工具叫什么只问它请帮我统计下面这句话有多少个字符和多少个单词 Everything is a PluginDSH 自己选择了text_stats传入原文再把结果交回模型22 个字符4 个单词。这就是本文的目标。准确地说我们要做的是一个Tool 类型的 PluginPlugin 负责把能力装进 DSHtext_statsTool 负责统计文字。完成后会留下加载日志、真实 Tool call 和 Trajectory 三类证据它们分别验证不同环节。1. 这次要写的 Plugin到底是什么DeepSeek 官方把 Harness 的设计概括为Everything is a Plugin。官方中文教程给出的定义很具体Plugin 是一个导出apply函数的 TypeScript 模块。DSH 加载模块时调用apply(ctx)插件再通过ctx注册能力。本文主要参考两份官方文档第一个插件中文开发一个工具中文先把两个容易混淆的词分开。Plugin 是装配单元。DSH 启动时加载它并执行它导出的apply(ctx)。Tool 是一项具体能力。Plugin 把 Tool 注册进 DSH 后模型才能发现并调用它。本篇会写一个Tool 类型的 Plugin再让它注册text_statsTool。关系如下DSH 启动 → 加载 Plugin → 执行 apply(ctx) → Plugin 注册 text_stats → 模型通过 Tool call 调用 text_stats这也解释了为什么后面既要看plugin loaded又要看 Tool call终端出现plugin loaded只证明 DSH 找到了 Plugin并执行了apply()。对话出现Tool call · text_stats才证明这个 Plugin 提供的能力已经注册成功可以被模型使用。Tool call 不是所有 Plugin 的通用验收方法。如果 Plugin 监听事件就应该触发事件检查响应如果它提供 Service就应该调用 Service如果它只负责日志检查日志即可。本文看 Tool call是因为我们做的恰好是 Tool 类型的 Plugin。我们会先做一个只打印日志的 Plugin确认加载链路没问题随后在同一个 Plugin 里注册text_statsTool。这样出错时容易定位不会把“插件没加载”和“工具没注册”混在一起。2. 先把源码版 DSH 跑起来这次需要从源码运行 Harness因为我们要让它加载本地 TypeScript 文件。不是为了修改 DSH 核心代码。本文固定到我实际跑通的提交47f9438。这个提交的根package.json标记为0.1.0-rc.5要求 Node.js^22.19.0 || 24.0.0并声明 pnpm11.7.0。DSH 仍处于 Developer Preview固定提交能减少主分支快速变化带来的干扰。先在 PowerShell 检查环境node-v git--version corepack--version看不到版本号时先补齐对应环境。Node.js 建议直接使用官方要求的版本如果corepack pnpm无法执行可以运行corepack enable再重新打开终端。接着克隆仓库并切到实测提交git clone https://github.com/deepseek-ai/deepseek-harness.git cd.\deepseek-harness git checkout 47f9438 git rev-parse--short HEADgit checkout后出现 detached HEAD 提示很正常这里是在复现固定版本不是在这个分支继续开发 DSH。安装、检查、构建依次执行corepack pnpm install corepack pnpm run typecheck corepack pnpm run build安装过程中可能出现 Linux 专用包不支持 Windows、workspace 循环依赖等WARN。警告文字本身不等于失败以命令是否正常结束、后续typecheck和build能否完成为准。先不要写插件启动原版 Web UIcorepack pnpm dsh web终端打印http://127.0.0.1:3080后在浏览器打开这个地址。确认页面可以进入再回到终端按CtrlC停止服务。成功标志原版 Web UI 能打开说明源码、依赖和构建链路都正常。后面若出错范围就缩小到了我们的 Plugin。最小排错typecheck或build报错时先核对git rev-parse --short HEAD和 Node.js 版本不要带着失败继续启动。3. 写一个只会打印日志的最小 Plugin在仓库根目录创建临时插件目录New-Item-ItemType Directory-Path.\scratch-plugin\src-Force用 VS Code 打开当前仓库code.如果系统不认识code直接从 VS Code 的“打开文件夹”选择deepseek-harness即可。创建scratch-plugin/src/my-plugin.tsimporttype{Context}fromdeepseek-ai/cordisexportconstnamehello-pluginexportfunctionapply(_ctx:Context){console.log([hello-plugin] plugin loaded!)}这里先认识三个东西name是 Plugin 自己的名字。apply()是 DSH 加载插件时调用的入口。ctx是插件连接 Harness 能力的上下文第一版还没用到所以写成_ctx。我还在scratch-plugin/tsconfig.json加了下面的配置{extends:../tsconfig.base.json,compilerOptions:{noEmit:true,composite:false,incremental:false,declaration:false,declarationMap:false},include:[src/**/*.ts]}这个文件方便 VS Code 继承仓库的 TypeScript 配置并检查插件代码。DSH 的官方最小教程没有要求它Plugin loader 也不靠它定位模块不想处理编辑器提示时可以先跳过。最后创建scratch-plugin/cordis.yml。完成后的目录应该是scratch-plugin/ ├─ cordis.yml ├─ tsconfig.json └─ src/ └─ my-plugin.ts4. 用 cordis.yml 把 Plugin 插进 Web UI先在仓库根目录取得插件文件的绝对路径(Get-Item.\scratch-plugin\src\my-plugin.ts).FullName把输出替换到cordis.yml的name-insert:-id:helloname:C:/你的路径/deepseek-harness/scratch-plugin/src/my-plugin.ts官方教程当前要求这里使用绝对路径。Windows 路径可以写成上面的正斜杠形式避免 YAML 转义带来的困扰。不要照抄作者电脑的用户名和目录。我的原始实验截图里使用了file:///C:/...形式并且在提交47f9438上成功加载。为了和官方教程保持一致读者复现时优先使用上面的绝对路径写法。带着这层配置启动 Web UIcorepack pnpm dsh web--patch./scratch-plugin/cordis.yml看到下面两行最小 Plugin 就加载成功了[hello-plugin] plugin loaded! dsh web: http://127.0.0.1:3080注意这时只过了“加载关”。plugin loaded只证明my-plugin.ts被 DSH 加载、apply()已执行这个版本还没有注册任何模型可以调用的 Tool。--patch会把cordis.yml作为最后一层配置叠加到 Web profile。我们没有改 DSH 核心源码只在启动时插入自己的模块。最小排错没出现日志时先检查 YAML 缩进和绝对路径。修改 Plugin 后要停止并重新启动命令单纯刷新浏览器不会重新加载终端进程。5. 把 Plugin 升级成 text_stats Tool现在往 Plugin 这个装配单元里放入第一项能力text_statsTool。替换my-plugin.ts。这段代码比第一版长但每一部分都有明确用途可以直接复制importtype{Context}fromdeepseek-ai/cordisimport{defineTool}fromdeepseek-ai/dsh-toolsexportconstnametext-stats-toolexportconstinject[tools]exportfunctionapply(ctx:Context){ctx.tools.register(defineTool({name:text_stats,description:Count the number of characters and whitespace-separated words in a piece of text.,parameters:{text:{type:string,required:true,description:The text to analyze,},},output:{schema:{type:object,additionalProperties:false,properties:{characters:{type:integer,required:true,},words:{type:integer,required:true,},},},render:(_args,value)[{type:text,text:characters:${value.characters}\nwords:${value.words},},],},asyncexecute(args){constcharactersArray.from(args.text).lengthconsttrimmedargs.text.trim()constwordstrimmed?trimmed.split(/\s/).length:0return{characters,words,}},}),)}先抓住六个关键点inject [tools]等 Tool Registry 就绪后再加载这个 Plugin。ctx.tools.register(...)把新能力登记进 DSH。name和description告诉模型工具叫什么、能解决什么问题。parameters规定调用时必须传入字符串text不合要求的参数会被拦下。execute()这里才会真正运行 TypeScript 统计代码。output先声明返回值结构再通过render把结果交给模型阅读。官方文档也强调了这条链路defineTool根据parameters推导并校验参数execute返回output.schema声明的值output.render再把结果转换为模型可用的内容。这个 Tool 统计的是 Unicode 码点数量空格也算字符“单词”按空白分隔。它适合本文的英文验证句不是中文分词器也不会把带组合符号的字形当成一个视觉字符。保存代码停止旧进程再重新启动corepack pnpm dsh web--patch./scratch-plugin/cordis.yml6. 先明确指定 Tool排除注册问题加载日志已经证明 Plugin 能进 DSH但最终版本的职责是注册text_stats。因此还要通过一次真实 Tool call 验证它提供的能力而不能停在plugin loaded。第一次测试明确要求使用text_stats先排除注册问题不考验模型会不会自主选择。把工具名字写进提示词请使用 text_stats 工具统计下面这段文字 hello deepseek harness这次实际出现了Tool call · text_stats输入和输出如下IN { text: hello deepseek harness } OUT characters: 22 words: 3这一步验证的是 Plugin 提供的能力Tool 已注册、模型能发起 Tool call、execute()返回了预期结果。如果对话只有模型自己计算的答案没有Tool call · text_stats先回到终端确认 Plugin 已重启再检查inject、ctx.tools.register和 Tool 名称。不要急着进入下一步。7. 不点名 Tool看模型会不会自己选新建一个会话这次只描述任务请帮我统计下面这句话有多少个字符和多少个单词 Everything is a Plugin开头展示的结果来自这次测试。提示词里没有text_stats模型仍然选择了它Tool call · text_stats · Everything is a Plugin characters: 22 words: 4这比显式调用多证明了一层模型看到了 Tool 的名称、描述和参数并判断它适合当前任务。截图中使用的是本次实验配置的模型。模型标签不是本文的安装要求复现时使用你已经在 DSH 中正确配置、能够完成 Tool call 的模型即可。API Key 只填在自己的配置界面不要写进 Plugin、截图或提交记录。8. 最后看 Trajectory确认调用链没有脑补聊天区已经显示 Tool call再打开上方的Trajectory。选择text_stats这一条记录可以看到Status: CompletedPayload 中的原始textResult 中的characters和wordsTool schema 与执行耗时到这里整条链路可以复核用户提出任务 → 模型选择 text_stats → Harness 调用 execute() → Tool 返回统计结果 → 模型组织最终回答Trajectory 是这次实验最有价值的证据。聊天回答只能说明模型说了什么Trajectory 能确认它实际调用了哪个工具、传了什么、拿到了什么。9. 跑通以后怎么理解“一切皆插件”这次只写了一个几十行的 Tool但官方口号已经落到代码上Plugin 通过ctx接入 Harnessctx.tools提供 Tool Registry模型在需要时选择我们登记的能力。本文故意停在这里。官方教程还提供自动清理、插件配置、服务与依赖、事件和生命周期等内容第一次实践不需要一起塞进来。关闭实验时在运行 DSH 的终端按CtrlC。scratch-plugin可以留着继续改也可以在确认不再需要后单独归档。本次通关标准分成三个层级加载证据终端出现[hello-plugin] plugin loaded!证明 Plugin 被加载。能力证据对话中出现真实的Tool call · text_stats证明它注册的 Tool 可以使用。执行记录Trajectory 的输入和结果与聊天答案一致证明调用过程可以复核。三条都满足你就完成了一个真正可用的 DeepSeek Harness Tool 类型 Plugin。
