DSH HUB
HomePlugin StorePlugin PacksCommunityRankingsResourcesPublish Guide
Plugin source
Back to catalog

oxmumu3 /

oxmumu3/dsh-plugin-lessons

Topic repository only

做 DeepSeek Harness(DSH)插件的经验:踩过的坑和好做法,每条带版本和证据。社区项目,非官方。

★ 1 Stars0 Forks0 IssuesN/A Community rating0 Confirmed installs
View on GitHub
READMESource: main@d15ad375

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/ 里,一条一个文件。每条有一个「类型」:

  • 踩过的坑:这么做会出问题。证据通常是报错原文、一次真实的事故,或者宿主里的硬限制。
  • 好做法:这么做更好。证据通常是某个公开插件某个版本的某个文件,或者官方说明。

贡献一条

  1. 复制 entries/_template.md,改个英文文件名(小写加连字符,比如 tool-param-required.md)。
  2. 照着模板里的提示填。填不出证据的,先别提交。
  3. 在仓库根目录跑一下 node scripts/build.mjs。它会检查格式,并重新生成 QUICK.md、LESSONS.md 和 lessons.json。
  4. 提合并请求。会有人把你写的每一句读一遍再合并。

嫌麻烦的话,直接提一个 issue 把经验贴上来也行,有现成的填写模板。

发现哪条错了、过期了,也按同样的方式改,见下面「条目会过期」。

收什么

三个条件都满足才收:

  • 通用:换一个人、做另一个插件,也会遇到。
  • 可核对:有报错原文、宿主里的接口名、公开仓库里的文件,或者写明哪天怎么试的。别人能顺着证据自己验证。
  • 带版本:写明是在哪个 DSH 版本上遇到或核对的。真不知道就写「未记录」,并把状态标成「待复核」。

好做法另有两条要求:

  • 能落成一条具体做法,并且指得到出处:哪个公开插件、哪个版本、哪个文件。只引用公开仓库,用自己的话描述,不搬别人的代码。
  • 只写事实,不写因果。「这个插件这么做」可以写;「它因此好用」是推测,不写。

纯经验性的做法(比如「先做空架子」)没法在宿主或仓库里核对,也收,但证据里要写明它是做法建议,以及是谁在什么情况下总结的。

不收什么

  • 只对某一个插件成立的事:它自己的样式类名、产品决定、测试约束。
  • 整篇的案例拆解和产品观点:「这个插件为什么好用」「边界要窄」这类。它们值得写成文章,但没法核对,也不适合贴给模型当做法执行。从拆解里拎出来的具体做法可以收,拆解本身不收。
  • 拿别人的插件当反面例子并且点名。坑可以写,名字不用提。
  • 和 DSH 无关的通用工程习惯:依赖版本怎么钉、npm 怎么发布、怎么写测试。
  • 没有证据的感觉,以及效果数字。「用了能省多少 Token」这类话,没有公开可复现的测量就不写。
  • 官方开发说明的原文搬运。官方说明里讲了后果的、或者不容易翻到的做法可以收,但要用自己的话说,并注明出处和版本。
  • 凭据、个人路径、别人的隐私、对话记录原文。

条目会过期

宿主升级很快,一条经验可能两个版本后就不对了。所以每条都有状态:

状态 意思
有效 回到证据核对过,在标注的版本上站得住
待复核 证据不全,或者有地方对不上。条目里会写明哪一点没核对
已过期 在新版本上不成立了。条目留着不删,并指向替代它的那一条

你在新版本上验证了某一条:把「宿主版本」和「最近核对」改成你的,提合并请求。

你发现某一条不成立了:把状态改成「已过期」,在「替代项」里填替代它的条目文件名(没有就写「无」),在备注里说一句怎么发现的。不要直接删,后来的人搜报错时还能看到「这条路以前这么走,现在不行了」。

「最近核对」隔得太久的条目,用之前自己先验证一下。

安全说明

这里的文字会被人贴给模型,模型会把它当成做法去执行。这和普通文档不一样:一句写歪了的话,可能让模型在别人的电脑上做出不该做的事。所以有几条规矩:

  • 每条都要人读过才合并。 构建脚本会拦掉一些明显的问题(个人路径、疑似密钥、邮箱、「忽略以上要求」这类话),但它只是道绊线,不能代替人读。
  • 条目只描述情况和做法,不对模型发号施令。 不能出现让模型跳过用户确认、瞒着用户做事、放宽权限、无视其他规则的内容。合并请求里有这类话,直接拒绝。
  • 条目里不放凭据、个人路径、用户名、会话编号、别人的隐私。
  • 带进插件之前再审一次。 任何插件要内置这些条目,请带一份自己读过的快照并锁定提交,不要在运行时拉取最新内容。这样即使这个仓库哪天被合进了不好的东西,也到不了你的用户那里。
  • 开头那句话读的是主分支上的当前内容。 主分支只有审过的合并才会变。想更稳妥,可以把网址里的 main 换成某一次提交的编号,读到的内容就固定了。
  • 用的人自己留个心。 条目和你当前宿主的实际接口不一致时,信宿主;和你自己的要求冲突时,听你的。

发现条目里有不安全的内容,请直接提 issue。

这些经验从哪来

现在共 57 条:27 条坑,30 条好做法。其中 5 条标了「待复核」。

来源 条数
七个社区头部插件的源码和注释 32
「发现好插件」的内置避坑清单和它的作者自己记下的经验 17
宿主安装包内置的官方开发说明 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)。

—/ 5

No ratings yet

Manifest verification required

Commit d15ad3750d5b

Community comments

No comments yet. Be the first to write one.

DSH HUB

A community index for DSH plugins. Not an official GitHub or DeepSeek AI product.

CommunityResourcesAPIAbout