DeepSeek Harness 处于开发者预览阶段，这意味着运行时会变，插件必须说明自己是针对什么版本构建的。社区目前的做法是往清单里写一段兼容性声明，把它写对，决定了一个插件是到处都能装，还是会悄悄坏掉。
清单里有什么
插件清单是向 harness 和目录站点描述这个包的元数据。实践中它存在于 package.json 里，外加一小段 harness 专用的配置块。真正重要的字段有：
| 字段 | 用途 | 说明 |
|---|---|---|
| name | 包的身份 | 必须与发布的名称完全一致 |
| version | 发布版本 | 遵循 semver；用户会锁定这个版本 |
| type | 模块系统 | 现代插件填 module |
| keywords | 被发现 | 包含 dsh-plugin 和 deepseek-harness |
| dsh.compatibility | Harness 兼容性 | 你实际测试过的版本范围 |
| license | 法律清晰度 | 多数目录站点要求提供 |
| repository | 事实来源 | 目录站点用它收录条目并跟踪活跃度 |
目录站点读不到的字段，它要么胡乱推断、要么留空——所以清单值得被当作用户可见的内容来对待，而不是构建期的附属品。
兼容性声明怎么运作
声明写的是你的插件实际构建并测试过的 harness 版本，例如 >=0.1.0-rc.6 <0.2.0 或 0.1.2-rc.1 || 0.1.5-alpha.1。它是契约，不是猜测。用户在安装前会拿它和自己装的 harness 对比，目录站点则把它原样记录下来——在本站，它就是每个插件页上展示的 dshTarget 字段。
关于这套机制有两个该如实告诉作者的事实：
- harness 并不强制执行它。 截至
0.1.5-rc.1，运行时里没有任何代码读取dsh.compatibility；声明不匹配的插件照样能装、照样加载。这段声明是写给人和目录站点看的，不是写给加载器的——这也让准确性更重要而不是更不重要，因为写错了不会有任何东西替你兜底。 - 要写真实存在的版本号。 已发布的版本线是普通的 semver 加预览标签：
0.1.0-rc.2到0.1.0-rc.8、0.1.1-rc.*、0.1.2-alpha.*、0.1.2-rc.1、0.1.3-alpha.*、0.1.5-alpha.*、0.1.5-rc.*、0.1.6-alpha.1，当前latest是0.1.5-rc.1。目录站点没法把它从没见过的缩写映射到这张表上——请从表里挑版本来声明，不要自造简称。
三条规则让声明保持有用：
- 声明你真正测过的版本。在
0.1.2-rc.1上测过、从没在0.1.5线上跑过的插件，就该如实写，哪怕更旧的版本号在列表里不好看。 - 在引入新运行时能力的同一个提交里更新它，不要拖到另一次发布再补——那种提交总会被忘掉。
- 声明的范围永远不要宽过你验证过的范围。声称兼容某个假想未来版本的插件，只会无谓地把能用的用户挡在门外，而且这种声明经不起推敲。
怎么写
生态目前沉淀下来的写法，是在 dsh 块里放一个 compatibility 对象：
{
"name": "dsh-my-plugin",
"version": "0.3.0",
"type": "module",
"keywords": ["dsh-plugin", "deepseek-harness", "web-search"],
"license": "MIT",
"repository": "https://github.com/you/dsh-my-plugin",
"dsh": {
"bundle": { "patch": "./cordis.patch.yml" },
"compatibility": {
"dsh": ">=0.1.0-rc.6 <0.2.0",
"profiles": ["web"],
"dshReleases": {
"0.1.5-alpha.1": "compatible",
"0.1.5-rc.1": "compatible"
}
}
}
}dsh 是范围；当一刀切会夸大时，用 dshReleases 把单个版本标成 compatible 或 unknown；profiles 说明你支持哪些 harness 界面。
在 README 里也用大白话写一遍，因为人先读的是 README：
已在 DSH 0.1.5-rc.1 上测试。在 0.1.2 线上工具能注册，但流式状态字段不可用。把失败现象写出来而不只写版本号，兼容性说明才真正能指导用户行动。
插件不兼容时会发生什么
失败通常是可读的：运行时会报这个插件的加载错误，会话的其余部分照常继续。要避免的是插件加载成功然后行为异常——在用户看来那像是 harness 本身的 bug，会引来一堆难查的报告。
如果你的插件触及一个你知道经常变动的层面（比如界面渲染或事件载荷结构），请在加载时做一次运行时检查，发现不匹配就用清晰的报错拒绝激活。体面地拒绝加载比带病加载的体验更好——而且这件事声明替你做不了，因为根本没有东西执行它。
兼容性作为收录信号
目录站点展示兼容性，是因为它回答了用户安装前最关心的问题：它在我的 harness 上能不能跑。在本站，声明会原样出现在每个插件页上，旁边是验证等级和最近更新日期，让你既能判断它能不能跑，也能判断还有没有在维护。验证等级 L3 要求的正是这两件事：安装命令可解析，且声明了目标版本。安装命令可解析但没有声明的插件会停在 L2，并且不会出现在兼容性矩阵的任何分组里——这如实反映了作者到底承诺过什么。
FAQ
兼容性声明能替代 peer 依赖声明吗？
不能。它向用户和目录站点传达 harness 兼容性；peer 依赖范围仍然决定安装时实际解析哪些 @deepseek-ai/* 包。两者用途不同：peer 范围是安装要求，兼容性声明是支持承诺。
多久该更新一次？
每当你引入新的运行时能力、或完成一轮兼容性复测时。不需要每次发版都动。
一个插件能同时支持两个 harness 版本吗？
可以——这正是范围写法或显式 dshReleases 映射的用途。声明 0.1.2-rc.1 || 0.1.5-alpha.1，并把中间的版本标成 unknown（如果你没测过），好过声称一个笼统的大范围。
完全不声明会怎样？
插件照样能装、能加载——harness 不检查。目录站点会记为「未声明」：在本站，该条目不显示目标版本、验证等级停在 L2、且不出现在兼容性矩阵的任何分组里。用户无从判断它适不适合自己，安装量会因此明显下降。
下一步
读 Cordis 生命周期指南 了解这些字段背后的运行时行为，然后发布你的插件。