# 条目格式 一条经验一个文件,放在 `entries/` 下。照着 [entries/_template.md](entries/_template.md) 填就行,这里是完整说明。 ## 文件名 小写英文、数字、连字符,以 `.md` 结尾,例如 `tool-param-required.md`。文件名就是这条经验的编号,定了以后不要改,别的条目和带快照的插件会用它来指这一条。 以下划线开头的文件(比如 `_template.md`)不算条目。 ## 字段区 文件开头用两行 `---` 包起来,一行一个字段,写成「字段名: 内容」。 | 字段 | 必填 | 怎么写 | | --- | --- | --- | | 标题 | 是 | 一句话说清「什么情况下,该怎么做」。读的人只看标题就该知道要不要点进来 | | 类型 | 是 | 二选一:踩过的坑、好做法。见下面「坑和好做法怎么分」 | | 分类 | 是 | 七选一:动手之前、接口与注册、工具与提示词、客户端加载、界面与体验、发版与兼容、看效果与排错 | | 状态 | 是 | 三选一:有效、待复核、已过期 | | 宿主版本 | 是 | 踩坑或核对时的 DSH 版本,例如 `0.2.2-rc.1`。不知道写「未记录」;做法类经验不依赖版本的写「与版本无关」 | | 最近核对 | 是 | 最近一次有人回去验证的日期,写成 `2026-11-10` | | 来源 | 是 | 谁、在做什么时遇到的。不想署名写「匿名贡献」 | | 替代项 | 已过期时必填 | 替代这条的条目文件名(不带 `.md`);没有替代就写「无」 | ## 坑和好做法怎么分 - **踩过的坑**:这么做会出问题。有人真的摔过,或者宿主里有硬限制。标题通常是「别这么做,改成那样」。 - **好做法**:这么做更好。不这么做也能跑,但公开的好插件或官方是这么做的。标题通常是「这么做」。 拿不准就选「踩过的坑」的标准来问自己:有没有报错、事故或硬限制?有就是坑,没有就是好做法。 好做法的证据要指得到出处:哪个公开插件、哪个版本、哪个文件,或者官方说明的哪一节。只写「它这么做」,不写「它因此好用」。 ## 正文 字段区后面直接写小标题,只用下面这几个,顺序照此: | 小标题 | 必填 | 写什么 | | --- | --- | --- | | `## 什么情况下会遇到` | 是 | 场景。让读的人能对上号:我现在就是这个情况 | | `## 该怎么做` | 是 | 具体做法。能给代码片段、接口名就给 | | `## 证据` | 是 | 用 `- ` 开头一条一条列,至少一条。见下面「证据怎么写」 | | `## 还没核对的` | 待复核时必填 | 哪一点没核对、为什么。状态是「有效」时不要这一节 | | `## 备注` | 否 | 例外情况、相关条目、历史变化 | ## 证据怎么写 每条证据开头标明是哪一种,方便读的人判断分量: - `报错原文:` 宿主或控制台的原话。最硬的一种,别人一搜就能对上。 - `宿主代码:` 哪个版本、哪个接口或哪段逻辑里能看到。用自己的话描述,不要大段贴宿主源码。 - `官方说明:` 宿主内置的开发说明或官方文档里怎么说的。用自己的话转述。只有官方说明这一种证据的条目也收,前提是它讲了后果(不这么做会怎样),或者是手写插件的人不容易翻到的。 - `公开仓库:` 哪个公开插件的哪个版本、哪个文件。好做法类条目最常用这一种。只引用公开仓库,用自己的话描述,不搬别人的代码。 - `公开文章:` 别人公开发表的文章。写明标题、作者、发在哪、日期。文章里的说法要尽量回宿主核对一遍,对不上的地方在备注里写明。 - `本人实测:` 哪天、做什么时、看到了什么。 - `经验做法:` 没法在宿主里核对的做法建议。写明是谁在什么情况下总结的,并且老实说没有对照数据。 没有效果数字就不要写效果数字。 ## 状态怎么定 - **有效**:至少有一条证据别人能顺着核对,并且在标注的版本上站得住。 - **待复核**:证据不全,或者有地方和宿主对不上。必须在「还没核对的」里写清楚。 - **已过期**:在新版本上不成立了。条目不删,填上「替代项」,在备注里说怎么发现的。 ## 写的时候注意 - 描述情况和做法,不要对模型下命令。这些文字会被贴进别人的创造会话。 - 不放凭据、个人路径、用户名、会话编号、别人的隐私。路径写成「插件目录」「宿主数据目录」这类说法。 - 代码示例里的包名、路径用 `@your-scope/your-plugin`、`/my-plugin/...` 这类占位写法。 - 一条只讲一件事。两件事就拆成两条。 ## 生成物 在仓库根目录运行: ```bash node scripts/build.mjs ``` 它会检查每个条目的格式,然后生成三个文件。只想检查不想生成,加 `--check`。需要 Node 18 或更新的版本,没有别的依赖。 **QUICK.md**:速查版,一条一行,只有类型、标题和条目文件名。适合让模型开工前先读,详情按需再读。 **LESSONS.md**:给人和模型读的合集,按分类排好,不含已过期的条目。 **lessons.json**:给程序读,结构如下。 ```json { "schema": 1, "count": 57, "kinds": ["踩过的坑", "好做法"], "categories": ["动手之前", "接口与注册", "工具与提示词", "客户端加载", "界面与体验", "发版与兼容", "看效果与排错"], "statuses": ["有效", "待复核", "已过期"], "entries": [ { "id": "tool-param-required", "title": "工具的可选参数直接不写 required,写 required: false 会注册失败", "kind": "踩过的坑", "category": "接口与注册", "status": "有效", "host_version": "0.2.2-rc.1", "verified": "2026-11-10", "source": "「发现好插件」内置避坑清单", "superseded_by": null, "when": "「什么情况下会遇到」的正文", "do": "「该怎么做」的正文,Markdown", "evidence": ["证据一", "证据二"], "unverified": null, "notes": null } ] } ``` 字段对应关系:`id` 是文件名,`title` 标题,`kind` 类型,`category` 分类,`status` 状态,`host_version` 宿主版本,`verified` 最近核对,`source` 来源,`superseded_by` 替代项,`when`、`do`、`evidence`、`unverified`、`notes` 依次对应五个小标题。没写的可选项是 `null`。 `schema` 只在结构发生不兼容的变化时加一。读这个文件的程序请先看 `schema`,再按 `status` 决定用不用:建议只用「有效」的,「待复核」的要用就把「还没核对的」一起带上,「已过期」的不要用。 ## 合并前的人审清单 给负责合并的人: 1. 从头到尾读一遍,包括代码块。 2. 挑一条证据顺着查一下,确实查得到。 3. 没有凭据、个人路径、用户名、别人的隐私。 4. 好做法类:出处是公开仓库,没有搬别人的代码,没有写因果。 5. 没有让模型跳过确认、瞒着用户、放宽权限、无视其他规则的话。做法是描述,不是命令。 6. `node scripts/build.mjs --check` 通过。