ARTICLE · 1381546
DSH 系列·05|写一个工具插件:从加载到可调用能力

给 DSH 增加一个工具,关键是让宿主知道它需要什么服务、接受什么参数、返回什么规范值,以及卸载后怎样撤销注册。
本文制作一个小工具:输入 owner/repository,生成一份待填写的仓库评估模板。它不访问网络、不修改文件,也不替仓库作出未经核实的判断。这样可以把注意力集中在插件加载与工具调用上。
代码依据 DSH 固定版本的官方插件与工具教程编写。它是可按步骤检查的教学实现;工具卡片、模型行为与实际兼容性,应在自己的目标宿主中按文末清单验证。
01准备一个边界清楚的例子▪
●○先明确要交付什么,以及哪些词是不同的对象
目标是把 repo_report_template 加进源码 Web 组合,完成一次“传入仓库标识 → 返回未核实模板 → 模型读取结果”的往返,再移除覆盖层确认停用。读者需会保存 UTF-8 文本、在终端切换目录,并能阅读基础 TypeScript;不要求先开发过 Cordis 插件。实现依据固定提交的官方插件与工具接口,启动输出和模型调用结果均是待执行的验收项,不是本文实跑记录。
TypeScript是在 JavaScript 上增加类型检查的语言;.ts 源文件不是改后缀就能变成发布用 JavaScript。模块是可导入的代码文件。入口是 Loader 实际导入的文件或包。依赖注入(inject)在这里指声明需要哪个服务,让框架把已经就绪的服务交给当前插件上下文;不是把源代码字符串塞进程序。
ctx 是框架交给插件的上下文对象,ctx.tools 是工具注册服务,defineTool 是描述参数、执行和输出的定义函数。schema是输入或输出的结构约定。工具定义 DSL 指这一套声明接口,不是额外需要安装的一门脚本语言。
●○从空目录准备到可以加载源码
这里固定 Windows 原生 PowerShell 的路径写法,工作目录为自己选择的开发父目录;macOS/Linux 可沿用相同步骤并调整建目录命令。需要 Git ≥2.26、Node.js ≥24.9.0,以及由 Corepack 管理的 pnpm。官方入口分别是 Git 下载页[1] 与 Node.js 下载页[2]。安装后重新打开终端,先检查:
这里的 pnpm 是管理仓库依赖与执行包脚本的工具;Corepack 按项目声明选择包管理器版本,避免不同机器随意使用不同 pnpm。DSL 是 Domain-Specific Language,中文为领域专用语言;本文特指 defineTool 这一组描述输入、执行和输出的接口约定。
git --versionnode --versioncorepack --version如果 Node 安装没有附带 Corepack,先按 Corepack 官方安装说明[3] 执行 npm install --global corepack,再重开终端检查;已有 Corepack 则不必重复装。启用后,由仓库 packageManager 字段选择本例基线的 pnpm@11.28.5:
corepack enablegit clone https://github.com/deepseek-ai/deepseek-harness.gitSet-Location ./deepseek-harnessgit checkout ca33fd6843b205e279c7ccb6cb73a472c78f5760pnpm --versionpnpm install --frozen-lockfilepnpm run buildNew-Item -ItemType Directory -Force -Path ./scratch-plugin/src | Out-Null每一步成功退出后再进入下一步。pnpm install 取得仓库依赖,pnpm run build 准备工具链和运行产物,后面的 pnpm dsh web 使用这些产物而不会自动补做构建。固定提交是为了让本文接口、依赖和源码说明一致,不是要求把已有开发目录强制切回旧版;有现成目录时另建独立检出。
源码构建比运行发行包更重。官方说明 Host/Client 类型检查各自可设置 8 GiB 的 Node 堆上限,这不是“8 GiB 总内存足够”的保证。内存不足时可在 PowerShell 中设置 $env:DSH_GATE_CONCURRENCY = '1' 后重做构建,减少并行步骤;仍失败时保留首个错误定位缺失依赖或工具链。Windows 与 WSL 的检出、依赖和工具链应各留在同一环境,不能共用另一系统的 node_modules。
若错误涉及关闭 TypeScript 类型剥离,检查是否设置了 NODE_OPTIONS 中的 --no-experimental-strip-types;先消除该冲突,再重跑构建。不要在构建失败后跳到模型设置,那时插件还没有可用运行环境。
工具名称是 repo_report_template,输入只有仓库标识,输出是 Markdown 字符串。模板中的用途、许可、成本和限制都保留“未核实”,等待后续阅读资料填写。
这一步没有新增网络抓取能力。模型拿到模板后,可以继续调用已经授权的读取或搜索工具;它不能把模板本身当成仓库分析结果。
官方入门教程的前置条件是已经完成 DSH 从源码运行的准备。本文沿用这条开发路径:使用同一份仓库与依赖,不把随意创建的独立目录当作已经安装了所有类型与运行服务。
本文固定代码基线为ca33fd6843b205e279c7ccb6cb73a472c78f5760,其根package.json版本为0.2.2-rc.4。11月18日晚已另有rc.5预发布;这里采用可对齐文档和源码的固定基线,不把它描述为当前最新。源码提交与发行包是两种标识,不能仅凭版本号推断所有文件完全一致。
02文件树与插件入口▪
在已准备好的源码仓库中添加:
scratch-plugin/├── cordis.yml└── src/ └── my-plugin.tsmy-plugin.ts 的教学实现如下。工具定义沿用官方 defineTool 接口,业务逻辑为本例编写:
import type { Context } from '@deepseek-ai/cordis'import { defineTool } from '@deepseek-ai/dsh-tools'export const name = 'repo-report-tool'export const inject = ['tools']export function apply(ctx: Context) { ctx.tools.register(defineTool({ name: 'repo_report_template', description: 'Create an unverified review template for a GitHub repository.', parameters: { repository: { type: 'string', required: true, description: 'A GitHub repository in owner/name format.', }, }, output: { schema: { type: 'string' }, render: (_args, value) => [{ type: 'text', text: value }], }, async execute(args) { if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(args.repository)) { throw new Error('Expected a repository in owner/name format.') } const repositoryUrl = `https://github.com/${args.repository}` return [ `# ${args.repository} 项目评估`, '', `仓库:${repositoryUrl}`, '版本或提交:未核实', '评估方式:资料评估,未进行运行测试', '', '## 用途与适用场景', '未核实', '', '## 授权与使用边界', '未核实', '', '## 接入成本与限制', '未核实', '', '## 结论与来源', '未核实', ].join('\n') }, }))}这里的格式校验只限制输入形状,不确认仓库存在,也不确认访问权限。即便输入正确,返回的内容仍是一份空模板。
●○两个名字不要混淆
模块导出的 name 标识插件;defineTool 中的 name 标识模型可调用的工具。一个插件可以注册多个工具,两者不需要同名。
inject = ['tools'] 表达对工具服务的依赖。它让框架在依赖就绪后执行插件,避免通过猜启动顺序解决服务未准备的问题。
●○返回值与模型内容分开
parameters 描述并约束工具输入,execute 执行业务逻辑,返回符合 output.schema 的规范值;output.render 再将这个值投影为模型可读取的内容。
把任意对象塞进 execute,却仍声明字符串输出,会破坏契约。需要结构化结果时,应连同输出 schema 和渲染一起设计,而不只是改返回值。

●○沿真实输入追一遍代码,而不是只看 API 名称
把上面的完整 TypeScript 保存为 scratch-plugin/src/my-plugin.ts。import type 只引入检查用类型,运行时真正调用的是 defineTool。框架在 tools 服务可用后进入 apply(ctx),注册定义;这时执行的是注册动作,还没有生成报告模板。
当模型后来发来 {"repository":"deepseek-ai/deepseek-harness"},参数约定先确保必填字符串存在,execute(args) 再用正则校验 owner/name 形状。通过后拼出仓库 URL,把标题、占位段落组成字符串数组,再用 join('\n') 连接成 Markdown。output.schema 要求规范返回值是字符串;output.render 收到这个字符串,把它放进 type: 'text' 的模型内容块。
async 表示执行函数返回 Promise,即“稍后可取得结果或错误”的对象;本例没有网络等待,也不会因此产生后台抓取。_args 是渲染函数收到但本例不使用的输入参数;value 才是执行结果。若以后把 execute 改成返回对象,需要一起改 schema 和 render,不能只让模型猜这个对象是什么意思。
空字符串、缺少 repository、传入数组和完整 URL 不属于同一个分支:缺字段或类型错应被参数校验拒绝;空字符串、没有斜杠或完整 URL 会被本例正则拒绝。a/b 只证明形状合格,可能根本没有这个仓库;工具不联网,所以不能证明仓库存在。这是明确边界,不是待模型补全的工作。
若仓库标识长度为 n,正则检查和字符串构造的工作量随输入长度增长,模板其余部分固定。本例没有遍历仓库文件、递归查询依赖或分析授权;输出带“未核实”是设计要求。
03用覆盖层加载▪
创建 scratch-plugin/cordis.yml,将下面的绝对路径替换为实际源码路径:
- insert: - id: repo-report name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'Windows 可以使用对应盘符的正斜杠路径,例如 E:/dev/deepseek-harness/scratch-plugin/src/my-plugin.ts。关键是路径指向真实文件,而不是照抄示例目录。
官方入门文档特别说明:传入 patch 文件,不会把 loader 的模块解析根目录改成 patch 所在目录。因此,本地覆盖层的源码路径采用绝对路径;不要把这一点与打包后的 bundle 解析规则混淆。
在仓库根目录使用官方开发启动方式:
pnpm dsh web --patch ./scratch-plugin/cordis.yml常规 Web 入口默认访问 http://127.0.0.1:3080;如果启动配置覆盖了地址或端口,应以实际启动信息为准。桌面版默认端口策略不同,不能把 Web 地址硬套给桌面入口。
●○启动链上每个文件到底起什么作用
scratch-plugin/cordis.yml 是加载配置,src/my-plugin.ts 是实现,仓库根目录的 package.json 和依赖提供开发环境。把它们放在一起,不代表框架会自动扫描所有 .ts 文件。

图为源码开发路径示意:patch 指定模块,Loader 导入,Cordis 等待依赖后激活,最后工具才进入可调用目录。注册完成之后,才发生后面的模型调用。
在仓库根目录运行 Get-Location 取得实际路径,用它填入 cordis.yml 的绝对路径。保存两个文件后,仍在根目录执行上面的 pnpm dsh web --patch ./scratch-plugin/cordis.yml。看到服务地址后打开界面,配置有工具能力的模型,选中本例工作区,再发送调用请求。
第一次启动失败时按顺序核对:仓库构建是否成功、patch 文件是否存在、绝对模块路径是否真实、tools 依赖是否就绪。四项分别对应运行产物、配置、导入和激活;改密钥只能处理进入模型请求后的认证问题。
04让模型调用,再检查完整往返▪
可以发送一个范围很小的请求:
请调用 repo_report_template,repository 使用 deepseek-ai/deepseek-harness。只返回工具生成的模板,不填补未核实项。期望检查的内容是:工具调用中确实出现这个名称,参数是指定仓库,工具结果含有仓库地址与“未核实”字段,随后模型正确读取结果。
模型也可能直接自行写模板。因此,只看到一份格式相似的回答,还不能确认工具被调用。应查看宿主提供的调用记录和结果。
对本例,返回字符串应有下面这样的起始内容。它是代码推导出的期望模板,不是终端成功日志:
# deepseek-ai/deepseek-harness 项目评估仓库:https://github.com/deepseek-ai/deepseek-harness版本或提交:未核实评估方式:资料评估,未进行运行测试正文中保留这些占位信息,是为了阻止“生成模板”被误读为“已经完成评估”。后续填写应绑定真实来源,不能把占位词简单批量替换成肯定结论。
再检查两个输入:一个正常仓库标识,一个缺少斜杠的字符串。后者应触发输入形状错误,不能被静默拼成一个看似真实的仓库地址。
这类确定性检查与模型质量评估不同。即使工具逻辑正确,模型也可能没有选择调用它;反过来,模型回答正确也不证明插件注册和清理正确。
05配置与资源怎样归属▪
这个版本没有可调参数,不需要导出 Config。以后若增加报告语言、模板名称或超时,应使用宿主支持的配置 schema,而不是把部署差异写死在实现中。
官方配置教程使用 Schemastery 的 schema。一个普通对象虽然看起来像 JSON Schema,也不能自动满足 Cordis 对插件配置验证接口的要求。
通过当前上下文注册的工具具有生命周期归属,卸载时会撤销相应注册。额外打开的网络连接、监听或定时器则应明确纳入可清理的 effect。
下面是独立的资源归属示例,不需要加入当前模板工具:
export function apply(ctx: Context) { ctx.effect(() => { const timer = setInterval(() => { console.log('heartbeat') }, 5000) return () => clearInterval(timer) })}这里展示的是“创建资源时同时提供释放函数”。若资源之间有严格先后关系,应在同一个 effect 的释放函数中显式安排,而不要假定多个独立 effect 会按某种顺序串行退出。
原生插件运行在宿主权限下。本例只拼接字符串,未来添加文件写入或外部请求时,应重新说明路径限制、认证、超时、取消和可见错误。
06从本地覆盖层到可安装组合包▪
本地开发覆盖层解决“从哪个文件加载”。分发用的 bundle 还需要回答“安装后贡献哪一层配置”。
官方打包文档使用以下结构:
dsh-repo-report/├── package.json├── cordis.patch.yml└── index.jsindex.js 是不带 TypeScript 类型语法的发布入口,业务逻辑应与前面的实现保持一致;依赖声明、构建和兼容范围需要按实际发布包核对。不要仅把源文件后缀改成 .js 就认为已经完成构建。
package.json 的核心关系是:
{ "name": "dsh-repo-report", "version": "0.1.0", "type": "module", "main": "index.js", "files": ["index.js", "cordis.patch.yml"], "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }}这是 manifest 结构示例;正式分发还需补全实际依赖、授权和经检查的宿主兼容声明。组合包的 patch 通过包名引用入口:
- insert: - id: repo-report name: dsh-repo-report有 dsh.bundle 的包可以贡献配置层;普通依赖包即使安装成功,也不会因此自动变成启用的插件。Profile 则保存使用哪些 bundle 及其顺序,和 bundle 本身是不同角色。
开发时先确认当前使用的 Profile。桌面版保留组合与另行安装的 CLI 不应交叉管理;需要安装和发布时,继续按目标入口对应的官方打包文档操作。
●○把“打包示意”补齐为本地可检查的产物
前面的 package.json 说明发布结构,不能单独当成模板工具的完整分发包。本地打包可以复用已经写好的工具代码,先在仓库根目录执行下面的 Node 脚本,生成不带 TypeScript 类型的入口。Node 版本仍须满足前面的下限:
New-Item -ItemType Directory -Force -Path ./dsh-repo-report | Out-Nullnode --input-type=module -e "import { readFileSync, writeFileSync } from 'node:fs'; import { stripTypeScriptTypes } from 'node:module'; const source = readFileSync('scratch-plugin/src/my-plugin.ts', 'utf8'); writeFileSync('dsh-repo-report/index.js', stripTypeScriptTypes(source));"这一步只剥离本例的类型语法,不做类型检查,不自动打包依赖。接着把前面的 package.json 和按包名引用的 cordis.patch.yml 保存到 dsh-repo-report/;因为本例运行时导入 @deepseek-ai/dsh-tools,还需从当前检出的同一份仓库取得它的版本,并同时声明共享宿主的 peer 依赖与开发依赖:
node --input-type=module -e "import { readFileSync, writeFileSync } from 'node:fs'; const target = 'dsh-repo-report/package.json'; const manifest = JSON.parse(readFileSync(target, 'utf8')); const tools = JSON.parse(readFileSync('packages/core/tools/package.json', 'utf8')); manifest.peerDependencies = { '@deepseek-ai/dsh-tools': tools.version }; manifest.devDependencies = { '@deepseek-ai/dsh-tools': tools.version }; writeFileSync(target, JSON.stringify(manifest, null, 2));"固定基线的真实路径是 packages/core/tools/package.json,其中工具包版本为 0.2.2-rc.4。peer 依赖表示运行时使用宿主提供的对应能力;dev 依赖供本地类型检查和开发使用。它们不能代替实际兼容检查,但避免把应共享的宿主包当成任意私有副本。这里的发布入口已删除 import type,所以不再运行时导入 Cordis 类型包。
在包目录执行打包,在仓库根目录使用同一套 DSH 管理测试用 Web profile:
Set-Location ./dsh-repo-reportpnpm packSet-Location ..pnpm dsh plugin --profile web add ./dsh-repo-report/dsh-repo-report-0.1.0.tgzpnpm dsh --profile web --dump-configpnpm dsh webpnpm pack 的预期产物是该目录下的 .tgz,检查实际打印的文件名。--dump-config 用来查看最终组合是否包含 repo-report 条目;它不是模型调用验证。正式安装包前,先停止仍带本地 --patch 的进程,避免本地覆盖层与组合包重复挂载同一工具。
若所选工具依赖版本没有对应可用的发行包,安装会在依赖解析阶段失败;此时继续使用同一仓库的覆盖层路径,不要把“源码里有这个包”当作“注册表上一定有同版本”。公开分发前还要落实 LICENSE、宿主兼容范围与实际安装验证;本文不把这个教学 tarball 当成已经发布的社区插件。
完成同一工具往返后,可用 pnpm dsh plugin --profile web remove dsh-repo-report 移除包;再按运行组合提示重启,并检查工具不再可见。安装、挂载、调用、移除分别通过,才覆盖这条路径。
07停用也要能检查▪
对本地示例,停止本次 Web 进程后,以不带该 --patch 的启动方式重新进入,可以检查该工具是否不再出现。采用插件管理界面停用时,则确认当前组合支持的生效方式和待重启提示。
卸载软件包与撤销运行中能力也不是同一件事。某些组合需要重启才能切换实际加载的模块,不能只看安装命令退出成功。
●○按失败阶段排查
找不到模块。 先检查覆盖层中的绝对路径、文件是否存在,以及是不是在正确的源码仓库启动。不要一开始就把问题归因于模型。
模块能加载,工具没有出现。 检查插件导出形态、inject 依赖是否就绪,以及注册过程有没有配置或 schema 错误。插件名称出现在列表中,也不必然说明它已经完成激活。
模型知道工具名,却没有调用。 查看当前工具是否对这个会话可见,再用明确的小任务确认。自然语言描述会影响选择,但不能靠改描述掩盖一个未完成的注册。
工具调用失败。 对照工具参数与异常信息。本例只接受 owner/name,完整 URL 会被拒绝,这是接口设计的结果;可以改进输入提示,也可以重新设计解析,不能静默接受不明确格式。
结果回来后模型又编了评估。 检查任务提示与工具描述,明确这只是模板,并保留“未核实”字段。业务边界需要在工具契约和验收中共同表达。
停用后仍有旧行为。 确认动作作用于当前 Profile、查看是否需要重启,再检查自建资源有没有绕开生命周期。包文件被删除,不能证明旧进程中的对象已经释放。
●○增加网络访问前再做一次设计
如果下一版要抓取 README,应明确只接受哪些仓库地址、怎样限制重定向、超时后返回什么、取消时怎样停止请求,以及结果是否需要截断。拿到原文之后,还要保留真实来源与版本。
这些规则应先成为确定性代码与检查项,再交给模型使用。把抓取失败包装成一段听起来正常的报告,会破坏工具作为事实来源的价值。
建议保留一份小清单:工具能被发现,参数不合规时有明确错误,规范输出与渲染一致,模型能够完成一次工具往返,停用后不再可调用,重新启用没有重复注册。
通过这些检查后,再增加网络与文件能力,问题会更容易定位到新增加的那一层。
参考资料
〔1〕官方:第一个插件:源码开发路径与本地加载。https://github.com/deepseek-ai/deepseek-harness/blob/ca33fd6843b205e279c7ccb6cb73a472c78f5760/docs/user/develop/basic/index.zh.md
〔2〕官方:开发一个工具:工具 DSL 与调用流程。https://github.com/deepseek-ai/deepseek-harness/blob/ca33fd6843b205e279c7ccb6cb73a472c78f5760/docs/user/develop/basic/tool.zh.md
〔3〕官方:插件配置:配置验证约定。https://github.com/deepseek-ai/deepseek-harness/blob/ca33fd6843b205e279c7ccb6cb73a472c78f5760/docs/user/develop/basic/config.zh.md
〔4〕官方:打包与安装插件:bundle 与 Profile。https://github.com/deepseek-ai/deepseek-harness/blob/ca33fd6843b205e279c7ccb6cb73a472c78f5760/docs/user/develop/basic/publish.zh.md
〔5〕地瓜:插件开发与内测记录:社区扩展的需求与实践背景。https://digua.moe/posts/20260813-dsh.html
DeepSeek Harness / DSH · 项目速览
作者:deepseek-ai
地址:https://github.com/deepseek-ai/deepseek-harness
许可:MIT License
关注公众号
✦
关注公众号:开源技术探索
关注「开源技术探索」,持续阅读开源工具、开发实践与技术详解。

使用与内容说明
资料截至2026年11月18日。本文依据官方资料、相关原文与固定版本源码编写,示例需按实际宿主和服务核对;未将资料整理或静态分析写成软件实测。各软件和服务分别适用其授权与条款,源码开源不等于模型服务免费。















































































