DSH 插件经验库
这里收的是做 DeepSeek Harness（DSH）插件的经验：前人踩过的坑，和公开的好插件里值得照着做的做法。每条都写明什么情况下会遇到、该怎么做、在哪个版本上核对的、凭什么这么说。
给两种人用：在创造模式里让模型帮你做插件的人，和自己动手写插件的人。
一句话用上
在创造模式里，说需求之前先贴这一句：
> 做之前先读一下 https://raw.githubusercontent.com/oxmumu3/dsh-plugin-lessons/main/QUICK.md
QUICK.md 是速查版，一行一条，约 9KB。模型扫一眼就知道有哪些坑；遇到具体问题，再按行尾的文件名去读那一条的做法和证据。
做完之后，如果这次踩到了新坑，贴这一句：
> 把这次踩的坑按 https://raw.githubusercontent.com/oxmumu3/dsh-plugin-lessons/main/FORMAT.md 的格式写成一条，去掉路径和隐私，我来提交。
模型会按格式写好一条。你自己看一遍，确认里面没有不该公开的东西，再提一个 issue 贴进去。有人审过之后会收进来，署你的名字。
模型读不了这个网址的话（网络连不上，或者当前模式不让它上网），把 QUICK.md 的内容直接贴进对话，效果一样。
这套东西有没有用，我自己按道理觉得有用，但没有做过贴与不贴的对比。你试了觉得没用，也欢迎告诉我。
为什么要有这个库
DSH 的创造模式本身带了一份官方的开发说明，写得不差。但有些坑它没写，有些坑写了大家还是会踩，还有些坑是某个版本特有的，过两个版本就没了。这些东西现在散在每个人自己的对话记录里，下一个人照样踩一遍。
好的一面也一样。社区里已经有做得很顺手的插件，它们的代码是公开的，里面有不少一看就能照着做的写法，只是没人把它们一条一条拎出来。
所以把这两样都记成一条一条的，带上版本和证据，放在一个谁都能看、谁都能改的地方。
这是个人发起的社区项目，不是 DeepSeek 官方的。
怎么用
做插件的人
- 读全文：LESSONS.md 是带做法和证据的完整合集，按「动手之前、接口与注册、工具与提示词、客户端加载、界面与体验、发版与兼容、看效果与排错」分了七节。要做带界面的插件，就看「客户端加载」和「界面与体验」；要给模型加工具，就看「工具与提示词」；要发版，就看「发版与兼容」。也可以把某一节整段贴进对话。
- 遇到报错来搜：很多条目里有报错原文，直接搜关键词。
做工具的人（想把这些经验带进自己的插件或脚本）
- 用 lessons.json，里面是全部条目，字段说明见 FORMAT.md。
- 请带一份你读过的快照，并记下是哪一次提交。不要让插件在运行时直接拉这个仓库的最新内容，原因见下面的「安全说明」。
一条经验长什么样
---
标题: 工具的可选参数直接不写 required，写 required: false 会注册失败
类型: 踩过的坑
分类: 接口与注册
状态: 有效
宿主版本: 0.2.2-rc.1
最近核对: 2026-11-10
来源: 「发现好插件」内置避坑清单
---
## 什么情况下会遇到
用 defineTool 给插件注册工具，想标明某个参数是可选的，顺手写了 required: false。
## 该怎么做
必填的参数写 required: true，可选的参数不写这个字段。
## 证据
- 报错原文：harness.defineTool <参数路径>.required must be true when present
- 宿主代码：0.2.2-rc.1 规范化工具参数时，值不是 true 就抛上面这个错。
全部条目在 entries/ 里，一条一个文件。每条有一个「类型」：
- 踩过的坑：这么做会出问题。证据通常是报错原文、一次真实的事故，或者宿主里的硬限制。
- 好做法：这么做更好。证据通常是某个公开插件某个版本的某个文件，或者官方说明。
贡献一条
- 复制 entries/_template.md，改个英文文件名（小写加连字符，比如
tool-param-required.md）。 - 照着模板里的提示填。填不出证据的，先别提交。
- 在仓库根目录跑一下
node scripts/build.mjs。它会检查格式，并重新生成 QUICK.md、LESSONS.md 和 lessons.json。 - 提合并请求。会有人把你写的每一句读一遍再合并。
嫌麻烦的话，直接提一个 issue 把经验贴上来也行，有现成的填写模板。
发现哪条错了、过期了，也按同样的方式改，见下面「条目会过期」。
收什么
三个条件都满足才收：
- 通用：换一个人、做另一个插件，也会遇到。
- 可核对：有报错原文、宿主里的接口名、公开仓库里的文件，或者写明哪天怎么试的。别人能顺着证据自己验证。
- 带版本：写明是在哪个 DSH 版本上遇到或核对的。真不知道就写「未记录」，并把状态标成「待复核」。
好做法另有两条要求：
- 能落成一条具体做法，并且指得到出处：哪个公开插件、哪个版本、哪个文件。只引用公开仓库，用自己的话描述，不搬别人的代码。
- 只写事实，不写因果。「这个插件这么做」可以写；「它因此好用」是推测，不写。
纯经验性的做法（比如「先做空架子」）没法在宿主或仓库里核对，也收，但证据里要写明它是做法建议，以及是谁在什么情况下总结的。
不收什么
- 只对某一个插件成立的事：它自己的样式类名、产品决定、测试约束。
- 整篇的案例拆解和产品观点：「这个插件为什么好用」「边界要窄」这类。它们值得写成文章，但没法核对，也不适合贴给模型当做法执行。从拆解里拎出来的具体做法可以收，拆解本身不收。
- 拿别人的插件当反面例子并且点名。坑可以写，名字不用提。
- 和 DSH 无关的通用工程习惯：依赖版本怎么钉、npm 怎么发布、怎么写测试。
- 没有证据的感觉，以及效果数字。「用了能省多少 Token」这类话，没有公开可复现的测量就不写。
- 官方开发说明的原文搬运。官方说明里讲了后果的、或者不容易翻到的做法可以收，但要用自己的话说，并注明出处和版本。
- 凭据、个人路径、别人的隐私、对话记录原文。
条目会过期
宿主升级很快，一条经验可能两个版本后就不对了。所以每条都有状态：
| 状态 | 意思 |
|---|---|
| 有效 | 回到证据核对过，在标注的版本上站得住 |
| 待复核 | 证据不全，或者有地方对不上。条目里会写明哪一点没核对 |
| 已过期 | 在新版本上不成立了。条目留着不删，并指向替代它的那一条 |
你在新版本上验证了某一条：把「宿主版本」和「最近核对」改成你的，提合并请求。
你发现某一条不成立了：把状态改成「已过期」，在「替代项」里填替代它的条目文件名（没有就写「无」），在备注里说一句怎么发现的。不要直接删，后来的人搜报错时还能看到「这条路以前这么走，现在不行了」。
「最近核对」隔得太久的条目，用之前自己先验证一下。
安全说明
这里的文字会被人贴给模型，模型会把它当成做法去执行。这和普通文档不一样：一句写歪了的话，可能让模型在别人的电脑上做出不该做的事。所以有几条规矩：
- 每条都要人读过才合并。 构建脚本会拦掉一些明显的问题（个人路径、疑似密钥、邮箱、「忽略以上要求」这类话），但它只是道绊线，不能代替人读。
- 条目只描述情况和做法，不对模型发号施令。 不能出现让模型跳过用户确认、瞒着用户做事、放宽权限、无视其他规则的内容。合并请求里有这类话，直接拒绝。
- 条目里不放凭据、个人路径、用户名、会话编号、别人的隐私。
- 带进插件之前再审一次。 任何插件要内置这些条目，请带一份自己读过的快照并锁定提交，不要在运行时拉取最新内容。这样即使这个仓库哪天被合进了不好的东西，也到不了你的用户那里。
- 开头那句话读的是主分支上的当前内容。 主分支只有审过的合并才会变。想更稳妥，可以把网址里的
main换成某一次提交的编号，读到的内容就固定了。 - 用的人自己留个心。 条目和你当前宿主的实际接口不一致时，信宿主；和你自己的要求冲突时，听你的。
发现条目里有不安全的内容，请直接提 issue。
这些经验从哪来
现在共 64 条：32 条坑，32 条好做法。其中 5 条标了「待复核」。
| 来源 | 条数 |
|---|---|
| 七个社区头部插件的源码和注释 | 32 |
| 「发现好插件」的内置避坑清单和发起人做多款自有插件记下的实测经验 | 24 |
| 宿主安装包内置的官方开发说明 | 6 |
| 别人公开发表的文章 | 2 |
读过的七个插件（按读的版本）：dsh-media-desk 2.6.2、dsh-guizang-design 0.1.4、DSH-better-sidebar 0.30.1、dsh-TUI 0.19.0、dshmarket 1.73.17、dsh-ops 0.5.2、dsh-agent-teams 0.1.29。谢谢这些作者把代码和注释写得这么清楚，很多坑是他们先踩的。
关于这部分要说明三点：
- 只读了代码和注释，没有运行这些插件。条目写的是「这个仓库这么做、注释这么说」，不是我验证过它在所有版本上都成立。
- 没有搬代码，做法都是用自己的话写的；示例代码是按意思重写的最小片段。
- 哪位作者觉得描述得不对，或者不希望被引用，提个 issue，马上改。
每一条收进来之前都回到出处核对过，核对不了的标了「待复核」。
和「发现好插件」的关系
这个库是独立项目，不是「发现好插件」（@oxmumu3/dsh-plugin-finder）的一部分。「发现好插件」打算做它的第一个读者，定期带一份人审过的快照，这一步还没接上。别的插件、别的工具也可以用同样的方式读它。
许可
MIT。条目经常要被整段带进别的插件里，而社区里的 DSH 插件多数也是 MIT，用同一个许可最省事：保留许可声明就可以用。
发起人：牛村木木山（oxmumu3）。
