使用 DeepSeek Harness Creator 构建小型插件
DeepSeek-V4 Team · 2026年10月8日 · 10 分钟阅读
第一个 Harness 插件，最好只承担一项职责，并且让结果一眼可见。显示固定项目清单的面板，就比同时修改文件、调用外部服务、管理凭证的扩展更适合入门。小版本能稳定工作后，后续变化才有可比较的基础。
2026 年 10 月 3 日发布的 Harness dsh-v0.2.1-alpha.1 在插件管理器中新增了 Creator 入口，可以带着草稿进入插件创建流程。下面依据该版本文档，说明如何提出需求、检查代码并验收一个本地插件。这是一套供读者执行的验收练习，并非已经在 Harness 中运行通过的成品插件。
准备一个便于检查的工作区
先确认安装的 Harness 版本，配置模型提供方，再为练习准备一个空目录。尚未安装的读者，可以先完成本地快速入门。不要直接拿重要项目的唯一副本做试验。
预期产物应包含插件源码目录，以及针对当前 Harness 版本的加载说明。要求智能体解释包入口、依赖和插件包（bundle）配置，不要把“生成了一个 TypeScript 文件”当成“已经可以从插件管理器安装”。
把第一版的验收目标限定为一个名叫 Project checklist 的面板，显示三行固定内容。暂时不做文件自动发现或状态保存。它们可以以后添加，但每增加一项能力，就多一组需要检查的行为。
打开 Creator，先看草稿再发送
在侧边栏打开 Plugins，点击 Add plugin 旁边的箭头，然后选择 Let the agent create a plugin。插件管理器参考文档说明，该入口由相应的预设界面插件提供。
进入 Creator 并不等于已经开始生成。发送前，检查当前工作区，以及草稿中沿用的文件、文件夹或会话引用。一个旧目录引用，就可能让智能体误判应该修改哪个项目。
可以从下面这段需求开始：
在这个空工作区创建本地 Harness 插件。以这里实际安装的 Harness 版本为目标，选择 API 前先查阅可用文档。添加名为 Project checklist 的面板，只显示三行固定内容：Review inputs、Inspect output、Record result。不使用网络请求、凭证、自动文件写入或后台计时器。编辑前列出计划创建的文件；完成后解释如何加载本地插件包和禁用它，并说明哪些验证没有实际运行。
这些约束让练习保持简单，也便于发现多余依赖。一个静态面板，通常没有引入 HTTP 客户端或调度服务的必要。
安装前，读懂生成的文件结构
官方第一个 Cordis 插件教程介绍了基础模型：插件导出 apply 函数，通过传入的上下文注册能力。因此，查看 apply 如何使用上下文，是理解生成代码的合适起点。
不过，入门示例不等于完整的可分发 UI 插件包。对于这个面板，应要求智能体从真正的入口文件，解释到注册与渲染代码。每个源文件为什么存在，都应该有清楚的答案，而不需要先阅读一套无关框架的教程。
还要检查包清单和安装脚本：依赖是否必要，引用的文件是否存在，命令是否在正确目录执行。如果智能体声称构建通过，应保留实际命令和退出结果。对构建过程的解释不能代替真实输出。
| 检查项 | 应看到的证据 |
|---|---|
| 入口 | 包清单或插件包配置指向实际存在的文件 |
| 面板注册 | 能指出哪处调用把插件接入可见界面 |
| 依赖 | 每个新增包都有明确用途 |
| 生命周期 | 禁用插件后，其界面元素能完整移除 |
| 验证 | 列明执行命令、结果和未测试的部分 |
安装本地插件包，核对加载版本
回到 Plugins → Add plugin。除了包仓库和 Git 来源，管理器也接受绝对本地路径。填写生成说明中标明的插件包根目录，不要随意选择一个恰好含有源码文件的子目录。
阅读安装预览和信任提示，随后安装并启用对应插件包或插件行。插件管理器中的已安装项目，与 Settings 中的内置插件清单不是同一列表。如果面板没有出现，先检查相应插件行是否启用，再修改源代码。
在测试记录中保留包标识和显示版本。十月版本改进了版本显示和代码来源信息；如果实际加载的还是旧包，正确修改也可能看起来没有生效。开发目录监听与更换已安装包版本是两种情况，后者仍然需要重启。
完整测试一次启用、禁用和重载
先启用插件，检查面板是否出现、三行内容是否齐全、顺序和文字是否与需求一致。然后禁用，确认面板消失。再次启用时，应只出现一个面板，不能有重复入口或残留元素。
接着按该插件包的开发说明，修改源码中的一行文字，观察面板是否更新。如果没有更新，先确认加载的源码路径及重启要求，不要立即让智能体重写整个组件。
最后重新打开应用，重复可见结果的检查。记录哪些步骤直接生效，哪些需要重启。这些信息比一张成功截图更能说明插件生命周期是否正常。
按故障发生的环节排查
面板不出现，可能是包路径没有解析成功、插件包未启用、注册失败，也可能是渲染失败。按这个顺序检查更容易缩小范围。Cordis 入门文档特别提醒，启动早期的路径解析错误有时不明显；新增入口看起来毫无反应时，应先检查路径拼写。
参考旧示例时，还要留意已经移除的 invariant 导出，以及输入框统计区域从 stats 拆成 activity、usage 的变化。这些是 0.2.1 发布说明列出的版本迁移问题，不应通过普遍关闭兼容性检查来绕过。
静态面板验收通过后，再一次增加一项能力。例如，在路径和失败处理明确的前提下读取一个指定文件，就适合作为下一步。持久化和外部请求留到单独的迭代，并保留已验证可用的最小版本，便于比较新问题。
升级背景可参见 Harness 0.2.1 更新解读。如果原本只是想写一个触发提醒的插件，可以先看看内置自动化教程，宿主可能已经提供了所需的调度功能。