@niujiajie/freespec 0.0.0-stage → 1.15.0

package/skill-files//346/267/261/346/200/235/references//344/270/211/346/226/271/346/240/270/345/257/271.md

@@ -0,0 +1,72 @@
+# 三方核对
+
+页面、表、接口要在仓库里打开文件核对。看过 `config/prompts.yaml` 不算对过实物。
+
+对不上的地方是答案里的漏洞。对得上的写进答案，并写上文件路径。对不上的先点选，人选定之前不要把某一边写进答案。
+
+需求文档里点名的页面、表、接口，要逐一到仓库里核对。还没有需求文档时，对用户已经点名的页面、表、接口做同样的事。
+
+没有点名的那一类，记不适用，原因写「未点名」。不要自己发明页面、表、接口去查。
+
+先把点名的清单列出来，再逐个打开文件。没有打开过文件的，不能记已定。
+
+对不上的全部收进同一批点选，不要停在第一处。点选方式见 `references/点选提问.md`。
+
+对完就按登记把结论写入答案。
+
+## 页面
+
+到前端项目里找路由、页面或组件。核对两件事：
+
+- 这个页面在不在
+- 需求或用户原话里的入口、看见的结果，和这个页面对不对得上
+
+需求写这次新增的页面，仓库里没有，记已定，结论写「仓库里还没有，这次新增」。不要为此提问。
+
+当前工作区找不到前端项目，不要当成已经核对过。这一题放进点选，选项两项：
+
+- 这次没有前端，页面记不适用
+- 前端在别的目录
+
+人选了第二项但没有写下目录：记未决，原因写「还没有前端目录」。目录让人用工具自带的「其他」写。不要编一个路径。
+
+## 表
+
+到 SQL 文件里找这张表。核对两件事：
+
+- 表在不在
+- 点到的列在不在，类型和所说的有没有冲突
+
+这次新增的表，仓库里没有，记已定「这次新增」。要改已有表，但 SQL 里找不到，或列对不上，收进点选，问以哪边为准。
+
+## 接口
+
+到后端 Controller 里找这个接口。核对四件事：
+
+- 方法和路径在不在
+- 路径风格是否一致。问号参数还是路径里的一段，以所说的和仓库同模块已有写法两边对照
+- 参数名是否一致
+- 所说的行为，和 Controller 里现在的行为对不对得上
+
+这次新增的接口，仓库里没有，记已定「这次新增」。不要问新路径怎么起、错误码是什么。
+
+## 问句
+
+每一处不一致单独成一题。不要把两处差异写成同一个选项。
+
+问句里写上三样：需求原文或用户原话、仓库文件路径、仓库里怎么写。
+
+选项固定两项：
+
+- 以需求原文为准。还没有需求文档时，写成「以用户原话为准」
+- 以仓库这份文件为准
+
+不要替用户选一边。人要用别的做法，用点选工具自带的「其他」写。
+
+## 登记
+
+每一条 conclusion 写上对过的文件路径。没有文件路径的「已核对」不算数。
+
+对不上、人还没选的，status 用未决。不能写成沿用材料。选定之后再写进答案。
+
+同一个核对项可以有多条 entries，一条对应一个页面、一张表或一个接口。

package/skill-files//346/267/261/346/200/235/references//344/276/213/345/255/220.md

@@ -0,0 +1,39 @@
+# 深思例子
+
+用户说：这次只改退款回调，没有页面。帮我把这个问题想透。
+
+应有的做法：
+
+- 目录若还没有，先建成 `freespec/退款回调变更/`
+- 复述：要回答的是退款通知再来一次时，订单应该怎样
+- 先看仓库里现在的做法，能看出来的写进答案，并写上文件路径
+- 已经知道没有页面，所以不问按钮和字段怎么摆，不问要不要新增接口
+- 失败、重复、没有数据还没写，而且会改答案：这题放进点选卡。选项用漏洞清单里的那一题
+- 人点完后，把选定的写进 `深思/记录.md` 的答案。还没定的写在「还要人定」
+- 对话里不贴 registry 全文，不报内部编号
+
+不应有的做法：
+
+- 只抛问题，不写答案
+- 写到仓库根的 `.deepthink/`
+- 点选工具就在会话里，却在对话里列成 A、B、C 让人打字
+- 一次只问「失败时看见什么」，把重复、没有数据留到下一轮再打字问
+- 写完答案接着写需求文档
+- 点了名的页面、表或接口却不打开文件
+
+用户说：需求里订单详情走 `GET /order/{id}`，表是 `order`。帮我把漏洞补上。
+
+应有的做法：
+
+- 先在后端 Controller 里找这个接口，并打开 SQL 里的 `order`
+- 对得上的写进答案，带上文件路径
+- 若接口对不上、表也对不上：两处各成一题，放在同一张点选卡里。选项只有「以需求原文为准」和「以仓库这份文件为准」
+- 人还没点之前，不要在答案里写成已经选定某一边
+- 点完再把选定的一边写入答案。Trae 一次最多 4 题，两题一张卡就够
+
+不应有的做法：
+
+- 当成新增接口，跳过核对
+- 自己把需求改成问号参数
+- 说「路径留给设计」然后结束，答案里仍空着
+- 把接口差异和表差异写成同一个选项

package/skill-files//346/267/261/346/200/235/references//346/200/216/344/271/210/346/203/263.md

@@ -0,0 +1,61 @@
+# 深思：怎么把问题想透
+
+从用户的问题出发。先用一两句复述要回答的是哪一句。复述偏了，先点选确认问题，再往下想。
+
+往深处想，也往旁边想。要找的是：这句话没说清的、说漏的、和仓库对不上的。这些就是漏洞。
+
+能从用户原话、已有材料或仓库补上的，写进答案，并写依据。不要再拿去问人。
+
+只有会改答案、又不能代用户定的，才按 `references/点选提问.md` 点选。先把这一批收齐，一次点选。不要问完一题就停下来等打字。
+
+不要替设计发明新的路径、错误码、表结构。问句写在点选卡里。不要在出卡前先写一大段说明。
+
+`config/prompts.yaml` 里 `text` 写着「这里换成…」的，出卡前换成仓库里看到的内容。没换成不要出这题。`skip_if` 已经成立的不要出。
+
+## 沿着问题看这些面
+
+材料里已经写死的跳过。还空着、而且会改答案的，才进入点选。
+
+- 谁在办、从哪里办、办完谁看见
+- 成功之外：失败、重复、没有数据
+- 旁边容易被算进来的一块，这次动不动
+- 以前已经产生的数据，动不动
+- 仓库里现在的行为，这次保持还是改掉
+- 用户或材料点了名的页面、表、接口，按 `references/三方核对.md` 对实物
+
+这份清单代替不了打开文件。不是每轮必答，也不要跑脚本。
+
+实物对不上、人还没选定时，不要把别的漏洞放进同一张卡，也不要把某一边写进答案。没有对不上的，直接看别的漏洞。
+
+## 从哪里完成
+
+还不知道人从哪里完成时，先补这一面。不要默认有页面：
+
+- 有页面：可以写多了或少了哪一块。不问按钮怎么摆、字段怎么放。
+- 没有页面：不问按钮和字段怎么摆。答案里按情况写：成功、重复、失败、没有数据。
+- 几个系统交接：写谁交给谁、交完看见什么。
+- 配置、定时或修数据：写谁触发、跑完怎样、不跑时怎样。
+
+已经说这次不动的，不要再问回去。
+
+## 推断和问不清
+
+你替用户做的推断，放成第一项，标签末尾写「（建议）」，说明里写这是推断。让人能改选。
+
+同一件事点选两次之后仍不清，改记未决，写进答案的「还要人定」。不要开第三张卡继续抠。不要留空。
+
+人改口：把和这句冲突的已定结论改成未决，依赖它的题重新放回点选。对话里说一句因为哪句改口、要重新确认哪一条。不要悄悄改登记。
+
+一题的答案能连带定下别的题：把连带结论直接写进答案，对话里说一句「按这一条，一并记下……，不对请改口」。不要为连带的题再出一遍。
+
+人点的和之前已定或材料里写的矛盾：这一处单独成一题，问以哪边为准。选项两项：以这次点的为准、以原来的为准。不要把两边的结论都留着。
+
+上游已经否定的，不要再问它下面的事。例如已经定了不新增接口，就不要再问新增接口的规则。
+
+用户说「先不考虑」：这件事不改答案，就记已定并写明这次不管；会改答案又没有默认，记未决。
+
+人跳过点选卡，或关掉不答：这一批记未决，写进「还要人定」，然后把已经能写的答案落盘。不要立刻把同一张卡再发一次。不要把跳过的题写成已经定了。
+
+对话里不要报内部编号，不要把登记文件全文贴出来。问句用简体中文白话。路径和协议原文可以保留。
+
+答案落盘后停下。

package/skill-files//346/267/261/346/200/235/references//346/212/244/346/240/217.md

@@ -0,0 +1,26 @@
+# 护栏
+
+护栏挂在动作上，不靠回头翻清单。必须项只在这一份。`references/约束.md` 只是尽量项。
+
+## 想的时候查
+
+1. 能从用户原话、已有材料或仓库补上的，直接写进答案，不拿去点选。
+2. 会改答案、又补不上的，才进点选。一次收齐一批。
+
+## 出点选卡前查
+
+1. Cursor 用 `AskQuestion`，Trae 用 `AskUserQuestion`。两个都不在当前会话，才改成对话一次列出全部题，并写明没有点选工具。不退回一次只问一题。
+2. 选项是这次真能选的。凑不满两项不出这题。
+3. 实物还没选定时，同一张卡不放别的漏洞。
+4. 点了名的页面、表、接口都打开了文件，看过 `config/prompts.yaml` 不算对过实物。
+
+## 写答案时查
+
+1. `深思/记录.md` 有问题、答案、还要人定三个标题。答案先写结论。每条补上的漏洞写依据。
+2. 对不上的每一处单独成题，选项是「以需求原文为准」和「以仓库这份文件为准」。还没有需求文档时，前一项写成「以用户原话为准」。找不到前端项目时，用三方核对里的那两项。不替人选定。
+3. 每条已定的核对写上对过的文件路径。
+4. 人跳过的题写进「还要人定」，不写成已经定了。
+
+## 落盘后查
+
+对话只报 `记录.md` 的路径和「还要人定」里的条目。不说「接下来写需求」。

package/skill-files//346/267/261/346/200/235/references//347/202/271/351/200/211/346/217/220/351/227/256.md

@@ -0,0 +1,66 @@
+# 点选提问
+
+人用点选回答。一次交出当前这一批里所有题。不要在对话里列「1. 2. 3.」让人打字回复。
+
+先看当前会话的工具列表里实际有哪个，再调用。不要两个名字都试一遍。
+
+调用前以该工具自己的参数名为准。下面是两边常见的字段。名字对不上，就改成工具说明里的字段，题意不要改。
+
+## Cursor
+
+工具名是 `AskQuestion`。一次调用放进这一批的全部题。工具若拒收，拆成连续几张再出，不要改回一问一答。
+
+每题要有：
+
+- `id`：给登记用。用漏洞清单里的 id，或这一处核对的页面、表、接口路径。不要把这个 id 写进给人看的句子。
+- `prompt`：问句。写清这个洞会怎样改答案。三方核对要写上需求原文或用户原话、仓库文件路径、仓库里怎么写。
+- `options`：至少两项。每项有 `id` 和 `label`。`label` 是人要点的那一句。
+- 可以同时点多项时加 `allow_multiple: true`。两边互斥就不要加。
+
+可以加 `title`，用一句话说明这一批在问什么。
+
+每一题工具会自带「其他」，让人自己打字。不要再造一个「其他」选项。
+
+## Trae
+
+工具名是 `AskUserQuestion`。一次调用最多 4 题，每题 2 到 4 个选项。超过 4 题就先出 4 题，点完登记，立刻再出下一张，直到这一批问完。不要改成对话里一问一答。
+
+每题要有：
+
+- `question`：问句。写法和 Cursor 的 `prompt` 相同。
+- `header`：不超过 12 个字的短标签，例如「退款接口」「失败时」。不要用内部编号。漏洞清单里的题用 `config/prompts.yaml` 里的 `header`。
+- `multiSelect`：互斥填 false，可同时成立填 true。必须写上。对应清单里的 `allow_multiple`。
+- `options`：2 到 4 项。每项有 `label` 和 `description`。`label` 一句话说清选它会怎样。`description` 补半句原因。Cursor 的选项没有 `description` 时，不要为了 Trae 编一个新结论，把选项里已经有的 `description` 带上即可。
+
+不要自己加「其他」。工具会加。
+
+建议放第一项时，在 `label` 末尾写「（建议）」，并在 `description` 里写明这是推断，人可以改选。
+
+选项超过 4 个时，留下真正不同的，最多 4 个。不要为了塞进工具把两个不同结论并成一句。并完仍超过 4 个，拆成下一题。
+
+## 选项怎么写
+
+选项必须是这次真的可以选的结果。凑不满两项，就不要出这题。这一题自己写了不足两项时怎么记，就按那一句。没写的，改记未决，原因写「做不成点选」。
+
+三方核对里对不上的不一致，固定两项：
+
+- 以需求原文为准。还没有需求文档时，这一项写成「以用户原话为准」
+- 以仓库这份文件为准
+
+找不到前端项目时，不用这两项，用 `references/三方核对.md` 里写的「这次没有前端」和「前端在别的目录」。
+
+漏洞清单用 `config/prompts.yaml` 里写好的 options。材料已经让某项不成立，就拿掉该项。拿掉之后不足两项，按上面改记未决。
+
+问句里若要求把相邻块的名字写进选项，出卡前写上。看不出名字就按该题自己的说明处理，不要留「相邻块」这种空话。
+
+问句和选项用简体中文。路径、方法、参数这些原文保留。
+
+## 工具不在时
+
+当前会话的工具列表里没有 `AskQuestion`，也没有 `AskUserQuestion`：不要编一个不存在的工具名去调用。用对话一次列出这一批的全部题，每题给出和点选相同的选项，请人一次回复。开头写明：这次没有点选工具，所以改成一次回复。不要退回一次只问一题。
+
+## 点完之后
+
+按 `references/登记.md` 把这一批全部写入答案和登记。选了「其他」或自己打的字，结论用那句话，不要写成某个预设选项。
+
+同一件事点过两次仍对不上，记未决，写进「还要人定」，不要再出第三张卡抠同一件事。

package/skill-files//346/267/261/346/200/235/references//347/231/273/350/256/260.md

@@ -0,0 +1,45 @@
+# 深思登记
+
+记录放在变更目录里：
+
+- `freespec/<名称>变更/深思/记录.md`：给人看的答案，必须写
+- `freespec/<名称>变更/深思/registry.json`：已定和未决的结论
+
+`记录.md` 只用这三个标题：
+
+- 问题：用户要回答的那一句
+- 答案：先写结论。然后每条漏洞写补上了什么，依据是哪句原话、哪份材料或哪个文件
+- 还要人定：未决。没有就写「无」
+
+`registry.json` 字段：
+
+- session_id：变更名
+- delivery：交付给谁、从哪里用。用「人从哪里完成」的结论。还没问到就留空，不要为了填这个字段再单独出一题
+- scope_type：这次范围的一句话
+- asked_count：已经问过的题数，不是点选卡的张数
+- blocking：数组。每项有 id、layer、question、status
+- entries：数组。每项有 prompt_id、layer、status、conclusion
+
+status 只用：已定、不适用、未决、沿用材料。
+
+未决包括两类：会改答案、用户还没定的项；三方核对里对不上、还没选定以哪边为准的项。还没发生的新路径、新错误码、新表结构不在这里设计，不记成未决。不适用要写原因。沿用材料要写引用了哪一句。实物核对的已定结论要写上对过的文件路径。
+
+已定的结论要能写进答案里的一句。未决同时出现在 `记录.md` 的「还要人定」里。写需求时，未决放进需求待定。
+
+能从原话、材料或仓库补上的：直接写入 entries，status 用已定或沿用材料，不要为了走点选再问一遍。
+
+答完一批：每一题的 blocking 标完成，写入 entries，并写进答案。asked_count 加上这一批的题数。
+
+人点了某个预设选项：conclusion 用该选项的标签。实物题还要写上对过的文件路径。
+
+人点了工具自带的「其他」，或自己打了一句：conclusion 用那句话，不要改写成某个预设选项。
+
+某一题写明「几种答案同时点中时丢掉其中一项」的，按那一句记，不要两句都留着。
+
+人跳过或关掉这一张卡：卡上这些题 status 用未决，写入「还要人定」，不要留空，也不要写进答案正文当成已经定了。
+
+人改口：把冲突的 entry 改成未决，依赖它的 blocking 项重新放开。不要删掉原来的登记，conclusion 改写成新结论并写明改过口。
+
+若变更目录里只有上一版的 `追问/`，把它当作 `深思/` 来读。新写的文件放到 `深思/`。不要把已经定过的再问一遍。
+
+答案落盘后停下。对话只报 `记录.md` 的路径，和「还要人定」里的条目。

package/skill-files//346/267/261/346/200/235/references//347/272/246/346/235/237.md

@@ -0,0 +1,9 @@
+# 约束
+
+这里只写尽量做到的事。必须项在 `references/护栏.md`。
+
+## 尽量
+
+- 先看仓库里现在的行为，再决定这次保持还是改掉。
+- 建议项放第一，标签末尾写「（建议）」，说明里写明这是推断。
+- 点选卡的标题用一句话。不要在出卡前先写一大段。

package/skill-files//347/224/250/344/276/213/references//346/200/216/344/271/210/345/206/231.md

@@ -0,0 +1,13 @@
+# 用例怎么写
+
+说明必须是简体中文，写清测什么、期望什么，不靠黑话。
+
+每条用输入、操作、期望。方法和路径、JSON 键、业务码保留原文，旁边用中文说明。
+
+一条行为一条用例，不要合并。不要把试算草稿、自我纠正写进正文。
+
+有接口时分开写：正常、业务不允许、参数不合法。这次涉及登录或权限，再写未登录、无权限。不涉及的组删掉。
+
+期望和已经写过的功能点一致。没有功能点，就按这次对话写，并标明哪些是假设。需求待定里还没定的结果，不要写成期望。
+
+先写核算表：每条功能点对上哪条用例，还缺什么。对话里只报路径和还缺的功能点。

package/skill-files//347/224/250/344/276/213/references//346/212/244/346/240/217.md

@@ -0,0 +1,42 @@
+# 护栏
+
+护栏挂在动作上，不靠回头翻清单。落盘前运行 `scripts/check-cases.mjs`，脚本退出码不是 0，就不能交。必须项只在这一份。`references/约束.md` 只是尽量项。
+
+## 动笔前查
+
+1. 核算表已经写：每条功能点对上哪条用例、还缺什么。列不出不写正文。
+2. 期望只来自已经写过的功能点。没有功能点，按这次对话写，标明哪些是假设。
+
+## 写每条时查
+
+1. 一条行为一条用例，不合并。每条用一个 `###` 标题，标题下有输入、操作、期望。脚本按这个查。核算表里的列表不算用例。三种接口情况人看，脚本不查。
+2. 有接口时分开写：正常、业务不允许、参数不合法。涉及登录或权限，再写未登录、无权限。不涉及的组删掉。
+3. 需求待定里还没定的结果，没有写成期望。
+4. 没有测试代码，没有 Given、When、Then。
+
+## 遇到这些，按这个走
+
+| 遇到什么 | 怎么办 |
+|---|---|
+| 功能点写不出确定的期望 | 这条不写，在对话里报还缺哪条功能点。不编一个期望 |
+| 某个功能点这次不测 | 核算表里写明不测和原因，不算漏 |
+
+## 落盘前查
+
+1. 跑 `node scripts/check-cases.mjs <测试用例.md>`，退出码是 0。
+2. 对话只报路径和还缺的功能点。不接着写成 Java 测试，不说「接下来实现」。
+
+## 脚本核对
+
+上面的句子给人读。脚本只执行下面这块。要放宽、改禁词，改这里，不用改脚本。
+
+```json
+{
+  "核对": {
+    "三段说明": "「{标题}」里没有「{段}」",
+    "禁词说明": "第{行}行用了「{词}」",
+    "用例行禁词": ["Given", "When", "Then", "优化", "完善", "大概"],
+    "空文档说明": "一份用例都没有，写了用例文档但没有用例"
+  }
+}
+```

package/skill-files//347/224/250/344/276/213/references//347/272/246/346/235/237.md

@@ -0,0 +1,5 @@
+# 约束
+
+这里只写尽量做到的事。必须项在 `references/护栏.md`。
+
+期望和功能点一致、三种接口情况，已经写在护栏里，这里不再重复。

package/skill-files//347/224/250/344/276/213/scripts/check-cases.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * 用例文档核对。条文在 references/护栏.md 的 json 块里，脚本只执行。
+ * 护栏未通过则退出码 1。
+ * 用法：node check-cases.mjs <测试用例.md>
+ *
+ * 查三样：每个 ### 标题下都有输入、操作、期望；该块禁词；至少有一条用例。
+ * 核算表里的列表行不算用例。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const docPath = process.argv[2];
+if (!docPath) {
+  console.error('用法：node check-cases.mjs <测试用例.md>');
+  process.exit(2);
+}
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const rulePath = path.join(here, '..', 'references', '护栏.md');
+const fence = fs.readFileSync(rulePath, 'utf8').match(/```json\s*([\s\S]*?)```/);
+let rules = {};
+if (fence) {
+  try {
+    rules = JSON.parse(fence[1]).核对 ?? {};
+  } catch (error) {
+    console.error(`护栏.md 里的 json 读不了：${error.message}`);
+    process.exit(2);
+  }
+}
+
+function fill(template, vars) {
+  return String(template ?? '未通过').replace(/\{([^}]+)\}/g, (_, key) => vars[key] ?? '');
+}
+
+const text = fs.readFileSync(docPath, 'utf8');
+const found = [];
+const chunks = [];
+const pattern = /^###\s+(.+)$/gm;
+const marks = [...text.matchAll(pattern)];
+for (let index = 0; index < marks.length; index++) {
+  const start = marks[index].index + marks[index][0].length;
+  const end = index + 1 < marks.length ? marks[index + 1].index : text.length;
+  chunks.push({ title: marks[index][1].trim(), body: text.slice(start, end) });
+}
+
+if (chunks.length === 0) {
+  found.push(fill(rules.空文档说明, {}));
+} else {
+  for (const chunk of chunks) {
+    for (const 段 of ['输入', '操作', '期望']) {
+      if (!chunk.body.includes(段)) {
+        found.push(fill(rules.三段说明, { 标题: chunk.title, 段 }));
+      }
+    }
+    for (const word of rules.用例行禁词 ?? []) {
+      if (chunk.body.includes(word)) {
+        found.push(fill(rules.禁词说明, { 行: chunk.title, 词: word }));
+      }
+    }
+  }
+}
+
+if (found.length > 0) {
+  console.error(`未通过 ${found.length} 项：`);
+  for (const item of found) console.error(`- ${item}`);
+  process.exit(1);
+}
+console.log('通过');

package/skill-files//350/256/276/350/256/241/references//345/207/206/345/244/207.md

@@ -0,0 +1,25 @@
+# 准备
+
+没有需求文档也可以写。有需求或深思记录就先读。需求待定里会改变做法的，不要在设计里替人决定。
+
+先读 `references/约束.md`。先判断涉及范围，再选章节。规则在 `references/类型.md`。有页面再读 `references/界面.md`。
+
+写变更方案之前先看仓库。注释和接口说明可能过时，以现有实现为准。跨进程时，配置变更常见是写库之后由定时任务比对更新时间再加载缓存，不要想当然写成发布订阅。先看服务实现和定时任务。
+
+业务不清楚时，先把读到的代码写进技术现状和改动清单，不要在正文里写「待了解业务」。
+
+有页面时，先写清谁在哪个菜单、哪几步、哪步可跳过，再写系统怎么跑。只有服务步骤、没有人怎么操作，不算写完。
+
+用户已经用操作说明讲了步骤时，先对齐或提出不同意见，再改表和接口。不要用专有名词盖过用户的说法。
+
+句子要能单独看懂。缓存、开关、定时任务、线程池、消息写在数据与配置的「其他配置」，不要塞进概述。
+
+接口默认只写 GET 和 POST，查询用问号参数。只有这个仓库同模块已经使用路径参数时才照仓库写。停用的接口留在清单里，并标明停用。写任务时再删掉对它的调用，不要在设计正文里写执行步骤。
+
+每个接口的详细设计先写对应的功能点原句。不要写规格编号。表头按模板。
+
+服务方法必须有步骤表。只留方法名、没有步骤，就停下来问，不要编算法。模板里「新增用户」那几行是样子，换成这次的方法，不要原样留着。没有分支就删掉「分支」列。没有事务、副作用、状态变化，就删掉那张表。
+
+文件已存在时只改和代码或需求不一致的段落。这次不再涉及的章整章删掉，剩下的从第一章连续编号。落盘前读 `references/护栏.md`，并运行 `scripts/check-design.mjs`。对话里不要贴大段代码。
+
+本仓库已有写法优先于模板里的示例。

package/skill-files//350/256/276/350/256/241/references//346/212/244/346/240/217.md

@@ -0,0 +1,134 @@
+# 护栏
+
+必须项只在这一份。落盘前逐条核对，并运行 `scripts/check-design.mjs`。脚本不写死条文，执行时读本文件里的「脚本核对」。脚本未通过，或下面有一条没做到，就不能交。
+
+第 1 到第 4 条脚本查不到，要人自己对过。第 5 条往后，脚本会挡。
+
+## 遇到这些，停手
+
+| 遇到什么 | 停下后干什么 |
+|---|---|
+| 需求待定里的问题会改变这次的做法 | 停，问人。不在设计里替人补一个结果 |
+| 追溯追不全（Controller、前端 api、组件有一层找不到） | 停，问人。不为了过检查去编文件 |
+| 需求文档和设计对不上，只差一个词就能对上 | 只在设计这一步可以改需求文档那一个词，不扩需求。改了在对话里说一句。差得多就停，问人。写代码那一步不能改 |
+
+## 人自己对
+
+1. 章名、节名用模板里的。章号连续即可，「第一章」和「第 1 章」都接受。概述下面直接是技术现状、目的与边界，不要先写总览段。技术现状只写现在代码怎样。
+2. 改动清单里出现的服务方法，要么有步骤表，要么写明为什么不写步骤。一个方法只留一套步骤。前后两种做法互相否定时，删掉被否定的那套。模板里「新增用户」那几行不要原样留下。
+3. 有建表或改表时，写明库的种类和可执行语句。旧数据要进新表时，写出怎么迁。只说「文件里删掉」不算写完。
+4. 有取舍时用三列：选了什么、另一个为什么不用、怎么回滚。回滚写不出来，这一行不能留着交。有页面章时，写清谁从哪个菜单进入、哪几步、哪步可跳过。只有服务步骤、没有人怎么操作，不能交。
+
+## 脚本会挡
+
+5. 改动清单有一棵模块树。节点标「新」「改」或「不动」。有前端时，前端在同一棵树上。
+6. 有页面章或接口章时，影响与测试关注里要有对应的行，并写上功能点原句。「对应功能点」不能空。不要写「见需求第几节」「文档第几行」。
+7. 有接口设计时，接口清单用模板那张表。每个还在用的接口各有请求参数、成功响应、业务错误三张表，列不能少。没有参数、没有字段、没有业务错误，表也留着，格子写「无」。停用接口在清单里标「停用」，可以不展开三张表。
+8. 改到的页面不凭界面变没变来选。页面引用的接口只要路径、参数名、参数位置、请求方式、响应结构有一项变了，就算改到，必须单写一节。每节用模板的「本页改动」表，并填「接口本次变化」。界面不用改时，「本页改动」写「无需改」，同一格写原因。整节只有「本次无改动」、没有原因的，删掉。
+9. 接口契约变更、字段重命名、表合并或删除落定后，沿 Controller → 前端 api → 引用该 api 的每个组件追溯。每一层的文件写进改动清单，填「层」和「追溯自」。追不全不要写后面的章。没有前端页面章时，只追到 Controller，不要为了过检查去编前端 api 和组件。
+10. 定稿前把改动清单和前端页面原型逐行对上。清单里每个前端文件的「对应页面节」指向页面章的某一节。页面章每一节都要在清单里有一行。对不上就补或删。章号按实际编号，不要按死「第四章」。
+
+## 脚本核对
+
+上面的句子给人读。脚本只执行下面这块。要放宽、改表头、改口，改这里，不用改脚本。
+
+```json
+{
+  "核对": [
+    {
+      "说明": "正文用章节号或行号代替了原句",
+      "匹配则失败": "见需求第|需求文档\\s*[\\d.]|文档第\\s*\\d+"
+    },
+    {
+      "说明": "改动清单缺少模块树",
+      "章": "变更方案",
+      "范围内含": "改动清单",
+      "要匹配": "[├└]"
+    },
+    {
+      "说明": "影响与测试里「{列}」是空的",
+      "仅当有章": ["前端页面原型设计", "接口设计"],
+      "章": "变更方案",
+      "节": "影响与测试",
+      "列不能空": ["对应功能点"],
+      "缺列说明": "影响与测试缺少「{列}」列"
+    },
+    {
+      "说明": "接口清单缺了要求的表头",
+      "章": "接口设计",
+      "范围内不含": "不涉及接口",
+      "表头要含": ["请求方式", "路径"]
+    },
+    {
+      "说明": "「{标题}」缺少「{词}」表",
+      "章": "接口设计",
+      "范围内不含": "不涉及接口",
+      "拆块": {
+        "级别": 4,
+        "没有块说明": "接口设计没有按四级标题分块，表无法逐个核对",
+        "跳过当": { "含": "停用", "且不含": "请求参数" },
+        "词后要有表": ["请求参数", "成功响应", "业务错误"]
+      }
+    },
+    {
+      "说明": "有页面章但没有按页分节",
+      "章": "前端页面原型设计",
+      "每个标题": {
+        "级别": 3,
+        "没有标题则失败": true,
+        "要有表": {
+          "表头含": ["本页改动", "接口本次变化"],
+          "列不能空": ["本页改动", "接口本次变化"],
+          "缺表说明": "「{标题}」缺少「本页改动」表",
+          "空列说明": "「{标题}」的「{列}」是空的",
+          "列不能整格匹配": {
+            "本页改动": {
+              "模式": "^(无需改|本次无改动)\\s*[。.]?\\s*$",
+              "说明": "「{标题}」写了无需改，但没有写原因"
+            }
+          }
+        }
+      }
+    },
+    {
+      "说明": "改动清单和页面章对不上",
+      "对账": {
+        "清单章": "变更方案",
+        "清单节": "改动清单",
+        "页面章": "前端页面原型设计",
+        "表头要含": ["层", "对应页面节"],
+        "缺表说明": "改动清单缺少对账要用的列",
+        "空值": ["", "无"],
+        "行": [
+          {
+            "当列匹配": { "层": "前端|组件|页面" },
+            "列要有字": "文件",
+            "列要指向标题": "对应页面节",
+            "说明": "改动清单里的前端文件「{文件}」没有指向页面章的某一节"
+          },
+          {
+            "当列匹配": { "层": "api|组件" },
+            "列要有字": "文件",
+            "列不能是": { "追溯自": ["", "无"] },
+            "说明": "「{文件}」没有填追溯来源"
+          }
+        ],
+        "每个标题要被指向": {
+          "列": "对应页面节",
+          "说明": "页面节「{标题}」在改动清单里没有对应的一行"
+        },
+        "至少各有一行": {
+          "当有章": ["接口设计"],
+          "或章匹配": { "数据与配置": "(?<!不)(?:合并|删除|重命名|改名)" },
+          "列": "层",
+          "模式": [
+            { "正则": "Controller|控制器", "说明": "追溯缺少控制层" },
+            { "正则": "api", "说明": "追溯缺少前端接口层", "当有章": ["前端页面原型设计"] },
+            { "正则": "组件", "说明": "追溯缺少引用该接口的组件", "当有章": ["前端页面原型设计"] }
+          ]
+        }
+      }
+    }
+  ]
+}
+```

package/skill-files//350/256/276/350/256/241/references//346/226/207/351/243/216.md

@@ -0,0 +1,17 @@
+# 设计文风
+
+正文必须是简体中文。概述用白话。类名、键名、方法名只放括号里，旁边用完整中文说明在干什么。读者应能不看括号读懂目的与边界、改动清单和页面原型。
+
+单段不超过 5 句。清单和规则用模板里的表，不要改成段落。模块树、建表或改表语句、页面框线留在表外。表缺了哪一张，以护栏和检查脚本为准。
+
+禁止自创缩略，例如：写边、选桶、查 bind、物化、对账、抽会话、封尾。写成完整动作。缩写第一次出现先写全称。
+
+禁止电报句。目标要写清哪几类、各做什么、缓存是谁写入谁读取、优先级的具体规则。读者不看后文也能懂这一句。
+
+禁止：大概、优化、提升、赋能、后续再看，以及正文里未决的「或」。
+
+不要把对话过程、优劣长辩、试错流水写进正文。有取舍才留一节：选了什么、另一个为什么不用、怎么回滚。没有就删掉这一节。
+
+不要贴完整的类实现。表结构语句可以写。不要用给定-当-则。
+
+章号连续即可。「第一章」和「第 1 章」都接受。不要用 §。