实际开发中DeepSeek Harness 插件并不是一个只有命令行入口的脚本而是一个需要遵循固定目录结构、清单描述、入口导出和版本管理规则的程序包。只要把文件写对放进 DeepSeek Harness 能识别的插件目录再提交到 GitHub 并打上版本标签别人就可以通过下载 Release 或复制文件完成安装。这篇文章就按这条链路带你写一个正式的 DeepSeek Harness 插件。这里说的“正式”主要指两件事第一插件的文件结构完整不是临时散落在一个脚本里第二插件从开发、构建、测试到发布都走完整流程。文章更适合刚接触 DeepSeek Harness 插件系统、想写一个小工具并分享出去的开发者。整个过程中会涉及 Node.js、TypeScript、pnpm、Git 和 GitHub Release我会说清楚每一步的目的和检查点也会把常见坑放在末尾单独处理。1. 先理解 DeepSeek Harness 插件的运行边界与插件目录1.1 插件系统解决什么问题DeepSeek Harness 如果只提供内置功能那么每加一个能力都要升级主程序用户也必须接受新版本可能带来的兼容性问题。插件系统的核心思路是把主程序保持精简把扩展能力交给插件完成。插件可以单独安装、单独卸载、单独升级互不影响。从用户角度看插件让功能按需加载。不需要的人不会看到一个塞满功能的界面需要的人可以安装特定插件来扩展工作流。从开发者角度看插件是一个独立项目有自己的版本、依赖、测试和发布周期不需要和主程序同步发布。1.2 插件通常由哪几部分组成一份能被 DeepSeek Harness 正常加载的插件至少包含清单文件和入口文件。清单文件负责描述插件的身份包括插件名称、显示名称、版本号、入口文件路径、支持的接口版本等。它相当于插件的“身份证”DeepSeek Harness 在扫描插件目录时会先读取清单文件来判断插件是否合法。入口文件是插件真正运行的代码。DeepSeek Harness 加载插件后会调用入口文件导出的生命周期函数。常见的设计是activate表示插件被激活时执行deactivate表示插件被停用时释放资源。除了这两个核心文件正式发布时还应该包含 README、LICENSE、构建配置和类型声明。README 告诉使用者和维护者插件怎么装、怎么用LICENSE 说明其他人能不能复制和修改。1.3 为什么必须确认版本和官方接口DeepSeek Harness 的版本不同插件接口可能存在差异。常见的变化点包括清单文件的字段名、入口文件的导出方式、生命周期函数的参数结构、插件目录的位置。如果拿到一篇旧教程就直接照抄很容易出现插件清单解析失败、入口模块加载不到、激活函数参数为空这类问题。所以在动手之前先确认当前使用的 DeepSeek Harness 版本并找到对应版本的官方文档或现有插件示例。你可以在主程序的设置面板、关于页面或启动日志里看到版本号官方仓库里的示例插件是最值得参考的模板。补充一个判断标准如果某个插件字段在文档里完全搜不到说明它很可能是旧版本的写法不要强行兼容优先按当前版本调整。1.4 插件目录的结构和加载顺序DeepSeek Harness 在启动时会扫描固定的插件目录。不同系统、不同安装方式下插件目录可能不同。常见的分类是用户级插件目录、工作区级插件目录和全局插件目录扫描顺序通常是从用户级到全局后面的目录会补齐前面没有的插件。在开发阶段最稳妥的做法是先打开 DeepSeek Harness 的日志输出查找它打印出的插件扫描路径。这样可以避免把插件写进错误的目录白白浪费排查时间。2. 准备环境并搭建插件项目骨架2.1 环境检查清单写一个 DeepSeek Harness 插件需要 Node.js、包管理器和 Git。DeepSeek Harness 是桌面端应用插件运行环境通常内置了 Node.js 运行时但你在开发机上的 Node.js 版本需要与目标运行环境保持接近否则可能因为 API 差异出现兼容问题。先执行以下命令检查基础环境node -v npm -v pnpm -v git --version如果pnpm没有安装可以用 npm 安装npm install -g pnpm建议使用 pnpm因为 DeepSeek Harness 插件社区中 pnpm 的使用率较高依赖管理行为也更严格。但这不是强制要求npm 或 yarn 同样可以完成项目初始化。2.2 初始化插件项目创建一个独立目录并初始化项目mkdir deepseek-harness-demo-plugin cd deepseek-harness-demo-plugin pnpm initpnpm init会生成一个默认的package.json。对 DeepSeek Harness 插件来说这个文件记录项目依赖和构建命令并不是插件真正的清单文件。插件是否能被主程序识别取决于后面创建的清单文件。为了让项目更正式建议先调整package.json的核心字段{ name: deepseek-harness-demo-plugin, version: 0.1.0, description: 展示 DeepSeek Harness 插件开发流程的示例插件, main: ./dist/index.js, scripts: { build: tsc, watch: tsc -w }, devDependencies: {} }注意main指向构建后的入口文件开发阶段源码在src目录中构建后再输出到dist。2.3 设计目录结构推荐使用一个清晰的项目结构把源码、清单、文档和构建配置分开deepseek-harness-demo-plugin/ ├── src/ │ └── index.ts ├── manifest.json ├── package.json ├── tsconfig.json ├── README.md ├── LICENSE └── .gitignoresrc放源码manifest.json放插件清单tsconfig.json放 TypeScript 编译配置。README 和 LICENSE 在发布到 GitHub 时是必备的不建议省略。3. 编写核心插件文件3.1 编写插件清单文件在项目根目录创建manifest.json。这个文件是 DeepSeek Harness 识别插件的关键入口。下面是一个演示用清单{ name: deepseek-harness-demo-plugin, displayName: DeepSeek Harness Demo Plugin, version: 0.1.0, apiVersion: 1.0.0, main: ./dist/index.js, contributes: { commands: [ { command: dshDemo.hello, title: Hello from DeepSeek Harness Plugin, category: Demo } ] } }字段含义如下字段必填作用示例值name是插件的唯一标识建议与项目名一致deepseek-harness-demo-plugindisplayName否显示在插件列表里的名称DeepSeek Harness Demo Pluginversion是插件版本号遵循语义化版本0.1.0apiVersion是声明兼容的插件 API 版本1.0.0main是入口文件路径相对于插件根目录./dist/index.jscontributes否声明插件向主程序贡献的能力commandscontributes是插件系统中非常常见的设计它让插件在激活前就能被主程序列出能提供的命令、菜单或快捷键。用户无需执行代码就能看到插件已经注册的那些入口。注意具体字段名可能因 DeepSeek Harness 版本不同而不同。如果当前版本文档里没有apiVersion或contributes请以官方文档或已有插件为准不要照抄这份示例。3.2 编写入口文件在src/index.ts中编写插件的入口代码。为了让例子尽量通用我使用 TypeScript 风格的生命周期函数import type { PluginContext } from deepseek-harness-plugin-sdk; export function activate(context: PluginContext) { context.output.appendLine(DeepSeek Harness demo plugin activated); context.registerCommand(dshDemo.hello, () { context.output.appendLine(Hello from DeepSeek Harness Plugin); }); } export function deactivate() { // 释放定时器、监听器或其他全局资源 }这里有一个需要重点解释的设计activate函数在插件被激活时执行适合初始化配置、注册命令和订阅事件deactivate在插件卸载或主程序退出时执行适合清理定时器、关闭连接和移除监听器。如果只用了一个console.log日志不一定能出现在 DeepSeek Harness 的界面里。因此示例代码通过context.output.appendLine写入主程序日志这样用户才能在日志面板看到结果。要注意的是deepseek-harness-plugin-sdk这个包名和PluginContext的类型结构只是演示。实际项目里要安装当前版本对应的 SDK 或类型声明包并且确认registerCommand、output.appendLine的准确签名。如果包名写错构建阶段就会报Cannot find module。3.3 配置 TypeScript 编译创建tsconfig.json把源码从src编译到dist{ compilerOptions: { target: ES2020, module: commonjs, outDir: dist, rootDir: src, strict: true, declaration: false, sourceMap: false, esModuleInterop: true, skipLibCheck: true }, include: [src] }关键配置项target设为ES2020保证在桌面端内置 Node 环境中可以运行。module设为commonjs插件入口通常以 CommonJS 形式被加载兼容性更好。strict开启严格检查避免常见的空指针和类型错误。outDir和rootDir保证编译后的目录结构与源码保持一致。安装开发依赖pnpm add -D typescript types/node然后执行构建pnpm run build构建成功后dist/index.js会出现。可以在终端检查入口文件是否存在ls -l dist/index.js3.4 安装 SDK 和类型声明如果官方提供了插件 SDK 包安装它能让开发体验好很多pnpm add deepseek-harness-plugin-sdk即使 SDK 最终只提供类型声明也值得安装。它能让你在写代码时获得自动补全和编译期类型检查减少因为参数拼错导致的运行时错误。如果当前版本没有正式 SDK也可以查看现有插件是如何获取PluginContext的。有的插件系统直接把上下文对象作为全局变量挂在globalThis上有的则通过入口文件的第一个参数传入。判断标准很简单看官方示例怎么写保持一致。4. 构建、测试并装入插件目录4.1 验证构建产物构建完成后先检查dist/index.js是否有内容确认 TypeScript 已经正确编译。可以执行node -e const m require(./dist/index.js); console.log(typeof m.activate, typeof m.deactivate)预期输出是function function。如果输出undefined说明入口文件没有正确导出activate或deactivateDeepSeek Harness 加载时会失败。这一步的检查方式很关键。很多人写完代码直接复制到插件目录结果插件不工作最后才发现入口导出格式不对。先在本机验证导出结构可以省去大量反复重启应用的耗时。4.2 确定当前版本的插件目录在启动 DeepSeek Harness 后查看日志面板搜索plugin或extension关键词会看到实际扫描的插件目录。不同系统的常见位置如下系统常见插件目录说明Windows%APPDATA%\DeepSeekHarness\plugins用户级插件目录macOS~/Library/Application Support/DeepSeekHarness/plugins需要关注权限Linux~/.config/deepseek-harness/plugins或~/.deepseek-harness/plugins以日志为准需要再次强调这些路径只是常见位置不是你机器上的必然位置。最可靠的方式是打开日志面板看实际扫描路径然后基于这个路径操作。4.3 把插件装进插件目录开发阶段推荐使用符号链接而不是直接复制整个项目目录。这样修改源码后只需要重新构建插件目录里的文件就会自动更新。假设插件的绝对路径是/path/to/deepseek-harness-demo-plugin插件目录是~/.deepseek-harness/pluginsmkdir -p ~/.deepseek-harness/plugins ln -s /path/to/deepseek-harness-demo-plugin ~/.deepseek-harness/plugins/deepseek-harness-demo-plugin在 Windows 上打开管理员权限的 PowerShell使用New-Item -ItemType SymbolicLink -Path $env:APPDATA\DeepSeekHarness\plugins\deepseek-harness-demo-plugin -Target C:\path\to\deepseek-harness-demo-plugin如果你不确定符号链接是否成功也可以先用复制命令cp -r /path/to/deepseek-harness-demo-plugin ~/.deepseek-harness/plugins/但复制之后每次修改代码都要重新复制一次开发效率较低。建议开发阶段用符号链接正式发布时通过 GitHub Release 下载安装包。4.4 验证插件是否被加载重新启动 DeepSeek Harness然后打开日志面板查找类似下面的日志Plugin deepseek-harness-demo-plugin activated successfully如果日志里出现failed to load、Cannot find module或invalid manifest说明插件没有被正确识别。可以回到第 4.2 步确认插件目录是否与日志中的路径一致。验证插件功能时打开命令面板搜索Hello from DeepSeek Harness Plugin执行这条命令。如果日志里出现Hello from DeepSeek Harness Plugin说明插件从加载、激活到命令注册的完整链路已经跑通。提醒现在验证的是“插件能加载”和“命令能执行”。如果插件只是加载成功但命令没注册成功日志里通常不会有报错此时要在activate函数里增加临时日志来定位是哪一步中断。5. 发布到 GitHub 并管理版本5.1 初始化 Git 仓库并创建远程仓库进入项目根目录执行git init git add . git commit -m feat: create demo plugin for DeepSeek Harness git branch -M main git remote add origin https://github.com/your-name/deepseek-harness-demo-plugin.git git push -u origin main在 GitHub 网页端创建一个同名仓库时不要勾选自动生成 README否则会与本地仓库产生冲突。如果你已经在网页端创建了带 README 的仓库需要先执行git pull origin main --rebase再推送。5.2 补全 README 和 LICENSEREADME 的内容至少包含插件是什么。支持哪个版本的 DeepSeek Harness。安装方式最好给出具体命令。使用方式包含一个最小操作示例。常见问题与作者联系方式。LICENSE 建议使用 MIT 或 Apache 2.0。如果没有 LICENSE别人能看代码但缺少合法使用和分发的权限声明这会降低插件被采纳的意愿。在仓库根目录创建一个LICENSE文件并把协议内容放进去。5.3 编写 .gitignore 防止提交构建污染项目里应该忽略node_modules和部分构建产物。但要注意插件发布时通常需要dist目录因此不要把dist一概忽略。node_modules/ *.log .DS_Store如果插件发布到 GitHub 后通过 Release 提供dist目录就要把dist保留在版本控制里或者通过 CI 在发布时重新构建。推荐后者提交源码Release 流程中执行pnpm install pnpm run build然后把dist打包成压缩包。5.4 打标签并发布 Release代码推送到 GitHub 后下一步是打标签并发布 Releasegit tag v0.1.0 git push origin v0.1.0如果安装了 GitHub CLI可以直接在终端创建 Releasegh release create v0.1.0 \ --title v0.1.0 \ --notes Initial release of DeepSeek Harness demo plugin \ ./dist/index.js这条命令会把dist/index.js作为 Release 附件上传。使用者可以下载附件再放到自己的插件目录中。如果插件包含多个文件先压缩再上传zip -r deepseek-harness-demo-plugin-v0.1.0.zip dist manifest.json README.md LICENSEgh release create中换成刚生成的压缩包路径。5.5 发布前检查清单发布前用下面这张表过一遍项目检查项确认标准清单文件字段完整name、version、main都存在main路径有实际文件构建产物存在pnpm run build成功dist/index.js存在本地加载测试通过日志出现插件激活成功信息命令注册验证通过命令面板能搜索到并执行插件命令README 有安装和使用说明用户不需要看源码就能开始使用LICENSE 文件存在明确开源协议.gitignore正确没有把node_modules提交到仓库版本号一致package.json、manifest.json、Git tag 三处版本一致6. 常见问题排查6.1 插件没有出现在 DeepSeek Harness 列表中可能原因检查方式处理建议插件目录放错查看日志中的扫描路径把插件移到日志显示的目录清单文件字段不合法打开日志看是否有 JSON 解析错误用 JSON 校验工具检查manifest.json插件目录层级多了一层日志提示找不到manifest.json确认插件根目录就是包含manifest.json的目录插件名称冲突插件列表里显示相同名称的其他插件修改name为唯一值最快捷的定位方式是先看启动日志再检查目录层级。深一层和浅一层是最容易犯的目录错误。6.2 日志出现 Cannot find module这个报错通常代表入口文件里引用了某个模块但在插件目录中找不到。可能原因dist/index.js没有构建入口文件还是 TypeScript。开发依赖没有安装到插件目录require(some-module)找不到模块。manifest.json里的main路径写错指向了不存在的文件。检查顺序ls -l dist/index.js ls -l node_modules如果确认入口文件存在但仍然报错把插件的node_modules复制到插件目录或者在插件目录中执行一次pnpm install --prod。发布 Release 时要确保源码不依赖本机全局模块所有运行依赖都记录在dependencies中。6.3 代码修改后不生效现象常见原因解决方案改代码后重载插件行为没变没有重新构建执行pnpm run build构建后仍然没变DeepSeek Harness 缓存了插件产物重启 DeepSeek Harness或禁用再启用该插件改了清单文件字段但插件没识别清单文件未被读取确认修改的是manifest.json而不是package.json开发阶段建议先运行pnpm run watch让 TypeScript 在文件变化时自动编译减少手动执行构建的遗漏。6.4 GitHub 推送失败或 Release 上传失败推送失败时先分清楚是认证问题还是网络问题。git remote -v检查远程地址是否正确。如果是认证失败使用gh auth login重新登录或者配置 SSH key 后改用 SSH 地址git remote set-url origin gitgithub.com:your-name/deepseek-harness-demo-plugin.git如果 SSH 方式连接正常可以执行ssh -T gitgithub.com出现身份确认信息就说明网络到 GitHub 的通路是通的。剩下需要处理的就是本地仓库状态比如远端存在冲突时先git pull --rebase。6.5 插件激活成功但命令面板搜不到命令这种情况通常是contributes中注册的命令名称与activate中实际注册的命令名称不一致。比如清单里写的是dshDemo.hello代码里注册的是dshDemo.hello2。排查方式打开实际加载的manifest.json。打开实际运行的dist/index.js。比较两处命令字符串。如果一致但还是搜不到考虑是否插件在activate执行过程中抛了异常导致注册动作没有执行到。在代码里给registerCommand前后各加一条日志能快速确认执行流。7. 让插件更正式规范、测试与后续扩展7.1 插件命名与版本规范插件名统一使用小写字母和连字符例如deepseek-harness-demo-plugin。版本号使用语义化版本主版本号在不兼容变更时递增次版本号在向后兼容的功能新增时递增补丁版本号在向后兼容的问题修复时递增。三处版本需要保持一致package.json的version、manifest.json的version、Git tag。版本不一致会直接导致 Release 内容和插件清单描述不一致用户无法判断自己装的是哪个版本。7.2 增加单元测试插件功能的稳定性可以靠单元测试兜底。对纯函数比如命令参数处理、日志格式化、配置解析可以直接用测试框架覆盖。生命周期函数activate往往依赖上下文对象可以在测试里构造一个 mock 对象。const createMockContext () { const output { appendLine: jest.fn() }; const commands: string[] []; return { output, registerCommand(command: string, handler: unknown) { commands.push(command); }, get commands() { return commands; } }; };测试的核心目标不是追求覆盖率而是保证关键逻辑在修改后不会悄无声息地坏掉。7.3 用 CI 自动化构建和发布把构建过程交给 CI可以避免本机环境差异导致发布产物不一致。常见的操作是推送 tag 后GitHub Actions 执行以下步骤name: Build and Release on: push: tags: - v* jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: pnpm/action-setupv4 - uses: actions/setup-nodev4 with: node-version: 20 cache: pnpm - run: pnpm install --frozen-lockfile - run: pnpm run build - run: zip -r plugin.zip dist manifest.json README.md LICENSE - uses: softprops/action-gh-releasev2 with: files: plugin.zip这样每次打v*标签GitHub 都会自动生成 Release并把压缩包作为附件上传。发布流程变得可重复不会因为本地缺少某个依赖而失败。7.4 下一步可以扩展的方向插件开发从“能加载”到“好用”还有不小的距离。下一步可以围绕这些方向继续做提供配置项让用户能在设置面板调整插件行为。注册事件监听响应 DeepSeek Harness 中的对话、文件或任务变化。增加命令的权限控制避免高风险操作被无限制调用。接入插件市场让用户绕过手动复制目录完成安装。补全国际化文案让插件在主程序多语言环境下有更好的显示效果。对刚起步的开发者最好的练习方式不是追求插件功能复杂度而是把“项目写出来、装进去、跑起来、发布出去”这条链路重复做透。目录结构、清单字段、入口导出和版本管理这些基本功稳定以后再往上加功能会顺畅很多。