@routerhub/agent-rules 1.5.216 → 1.5.218

package/AGENTS.base.md

@@ -208,6 +208,7 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
   3. **图间配过渡说明**：每张 caption 讲清「上一步发生了什么 → 这一步点哪里 → 预期看到什么」，报告内按操作顺序成段排布，读者能跟着连点；
   4. **逐张自检**：只看这张图 + 说明，能否照着点出下一步？能 = 合格；不能 = 补一张步骤图或补标注，直到整条流程读者不靠你就能走完。
   5. **就近嵌入（位置铁律）**：分步演示必须紧跟在「该操作对应概念/证据在报告中第一次出现、读者正要问『那到底怎么操作』」的地方之后（如展示「账户挂映射删除被 400 拒绝」的证据图 → 该图下方紧跟「先解绑再删除」的完整演示），禁止把演示单独堆到报告末尾或附录里——读者在定义处看不到演示、不知道下文还有、得自己翻到最后去找，等于没配演示。
+  6. **「差别可辨识」自检——读者照着做完，能看出你说的那个现象吗？** 光「能照着做出来」还不够，还得「做完能看懂」。凡文档描述了某种**对比 / 变化 / 前后差异**的步骤，必须自问：读者照着执行完，能不能一眼看出这个差异？**看不出 → 文字讲不清，必须补一张带箭头标注的执行现场截图，把「哪一行 / 哪个数字 / 哪一列」变了、变成了什么，直接圈出来。** 最容易翻车的是**肉眼看几乎一样的对比**：如 `UPDATE 1` 与 `UPDATE 0` 只差一个数字、同一段命令两次执行的输出几乎雷同、两次探测返回同一状态——作者自己心里清楚哪行对应哪句，读者对着一屏几乎相同的输出根本对不上号，只能回头来问「我执行了咋没看出有啥不同」。**判据是读者，不是作者——作者知道 ≠ 读者看得出。**
   - **类比**：交付报告像给菜谱——一道菜（一个功能）从备料到出锅（完整操作流程）必须给出「第 1 步切什么、第 2 步放多少油」的步骤图，读者照做能做出同一道菜；只贴一张成品照让读者猜过程，等于没教。
   - 反面示例：演示「删不掉挂着映射的账户」，只贴「删除被拒」和「最终删除成功」两张图、不展示中间「打开 Models → Remove(Unbind) → 确认」的顺序，读者仍不知道卡住时该点哪里。
 - ⚠️ **时序抢跑类 bug（表象像「坏了」、根因是「两个动作抢同一个瞬间被吞」）：测试中要能嗅出来，解释要先翻成人话。** 这类 bug 的表象（如「登录转圈 / 点按钮没反应 / 偶发失败」）离根因隔着好几层抽象——AI 测试功能过程中碰到此类现象，必须按时序根因去查，禁止当「偶发 / 环境问题」放掉；定位到根因后向用户解释时，必须先给一版「人话」（读者能顺着走一遍、能当场确认「对，就是它」），再附机制细节（路由守卫 / persist / token 生命周期……），禁止只甩机制清单、让用户自己翻译根因。识别指纹（命中越多越是这类）：
@@ -279,7 +280,7 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 
 - ⚠️ **核心认知：报告里的每一条主张——A/B 截图、前后对比、那个数字——都是你的结论，不是读者能自己检查的东西。** 他看完手里只有两个选项：信，或者不信。**一份只能「信或不信」的报告，等于把「可核实」偷偷降级成了「请相信我」。** 判据只有一句话：**把报告发给他、你不说任何一句话，他能不能自己把这条主张跑一遍、亲眼看到同样的结果？** 不能 = 这条主张没交付。
   - **类比：体检报告不能只印一句「各项指标正常」就让人签字——得把每项指标的数值、参考范围、以及「你自己去哪个科室能复查这一项」都写上，家属才可能拿着它去另一家医院复核。只给结论的报告是「请相信我」，不是「你可以自己看」。**
-- ⚠️ **硬性要求：每一条主张旁边，都要挂一份「你自己怎么复核这一条」的操作流程。** 适用范围 = 每条需求原话对应的实现、每个「已修复 / 已生效」的断言、每组前后对比。流程由**逐步编号的操作**组成，每步三件套缺一不可：
+- ⚠️ **硬性要求：每一条主张旁边，都要挂一份「你自己怎么复核这一条」的操作流程。** 适用范围 = 每条需求原话对应的实现、每个「已修复 / 已生效」的断言、每组前后对比，**外加报告里每个「请你自己去某环境跑一下 / 确认一下」的开放项**（待确认项、前置准备、动手环节——它们不是「主张」，作者自己也没结论，最容易只丢一行片段，因此同样必须给到从零可跑的完整流程，见「⚠️ 截图规范 → HTML 文档截图与 curl 命令规范」的「片段即未执行」）。流程由**逐步编号的操作**组成，每步三件套缺一不可：
   1. **可复制粘贴的完整命令 / 操作**：参数写全，**禁止用 `...` 或占位符省略**（呼应「⚠️ 截图规范」的命令完整性要求）；且**不得引用只有你本机才有的东西**（`localhost`、本机路径、容器名、未提交的文件、正在跑的本机服务）——否则读者一跑就断（呼应「⚠️ 验收环境铁律」）。
   2. **预期结果，对错两种都要给**：不只写「应该看到 X」（✅），还要写「**看到 Y 就是这条主张不成立**」（❌）。⚠️ **这是全篇最关键的一项**：只给成功输出，读者跑出任何别的东西时都无从判断是「我环境不对」还是「你说的不对」，最后又退回「信或不信」——**给了他反例，他才能自己宣判。**
   3. **这一步证明了什么**（一句话点明证据含义），让读者不必读完整篇才知道自己在验什么。
@@ -649,6 +650,7 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 ### HTML 文档截图与 curl 命令规范
 
 - ⚠️ **HTML 页面/文档中的外部链接默认用新标签页打开**：所有指向外部资源（其他网站、GitHub 文档、私有文档仓库等）的链接一律写成 `<a target="_blank" rel="noopener" href="...">`，禁止不加 `target` 让用户点击后直接跳出当前页面。**类比：逛商场拿着一份导购地图，每个店名都标着「在新窗口查看」——点一家店不会把你从地图里踢出去，地图还在，能连续逛好几家；不新开窗口的话，每点一家店整张地图就没了，得反复按返回。** `rel="noopener"` 是安全兜底，防止新页面通过 `window.opener` 反向控制当前页（tabnabbing 钓鱼攻击）。
+- ⚠️ **文档正文里每一个「让读者去打开」的地址，后面都要紧跟一个显式的「在新标签页打开」按钮。** 光把已有链接写成 `target="_blank"` 不够——文档里大量地址是以**裸文本**出现的（如步骤里写「打开 `https://github.com/.../postgres.go#L651-L660`」「访问 `https://test-admin.horizonapi.ai/models/accounts`」），读者只能手动选中、复制、切浏览器、粘贴，一步一断。**判断标准：这句话是不是在让读者去打开某个地址？是 → 那个地址后面就得跟一个按钮**（`<a class="open-btn" target="_blank" rel="noopener" href="...">在新标签页打开 ↗</a>`）——点一下直接过去，文档还留在原地，能连着核对好几条。**反面示例：把 `打开 https://.../report.go#L58-L64` 这类纯文字丢给读者，等于让他自己搬运地址。**
 - ⚠️ **截图版 HTML 文档中的截图必须自动加箭头标注**：当用户要求写「截图版 HTML」文档（以截图为主体、图文结合说明实现/操作步骤的文档，如部署实现说明、操作指南等）时，嵌入的每张截图都必须自动用醒目的箭头 + 简短文字标签标注出关键区域/验证点/操作位置，让读者一眼看懂这张图对应文档的哪一步、证明了什么，禁止只贴裸图不标注。箭头标注放在不遮挡原内容的位置。
 - ⚠️ **HTML 文档中的截图必须以 `data:image/png;base64,...` 内嵌，禁止用文件路径或相对链接引用外部 PNG 文件。** 文档会被打开、移动、分享，外部图片路径一旦脱离原目录就全部失效，文档里全是裂图。生成文档后，散落的零散 PNG 文件应一并清理，只保留 HTML 本身。
 - ⚠️ **curl 命令必须完整可复制执行，禁止省略关键参数。** 包括但不限于：API Key / Token、请求体中的图片数据、完整的 URL。禁止用 `...` 或「省略其余参数」代替——看的人无法区分「这里不重要所以省略了」还是「这里我不会写所以跳过了」，前者让命令不可执行，后者掩盖了潜在的错误。
@@ -658,6 +660,18 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 - ⚠️ **测试用的图片等静态资源统一放到 `screenshots/` 临时目录，curl 命令中用相对路径引用**（如 `@screenshots/test.jpg`），确保命令在项目根目录下可直接执行。
 - ⚠️ **一键执行脚本/命令必须能直接复制到终端执行，且文档中必须配「一键复制」按钮。** 每条命令必须完整可执行（禁止省略参数、禁止用 `...` 占位、禁止只给片段），在项目根目录下可直接运行；文档中命令块右上角必须提供复制按钮，点击即可将完整命令复制到剪贴板并给出「已复制」反馈。
 - ⚠️ **文档中给出的每条命令/脚本，写入前必须亲自在终端实际执行验证过，确认确实可行后才能写入。** 执行失败的命令一律不得写入文档，禁止凭推断「应该能跑」就写进文档——推断得出的结论不能作为生成依据，必须实际测试过才能下结论。
+- ⚠️ **不止命令——文档里写的每一个操作步骤，都必须亲自真实走过一遍，并把这一次的执行现场截下来。** 「命令能跑通」和「跑出来长什么样」是两件事：读者要的是照着做出同一个结果，而你只有亲手做过，才知道中间会弹什么、输出长什么样、哪一步最容易看错。**执行过程本身就是配图的来源**——每写一步，手里就得有一步对应的现场截图（带箭头标注，圈出这一步的输出里哪一行是关键、它证明了什么）；**禁止事后凭印象补画，更禁止拿推断出的「应该会输出什么」当截图**。**没执行过就别写这一步**：没跑过就写进文档的步骤，轻则读者照着一路卡住，重则把错的做法教给了人。**自查一句话：文档里每一个「你来操作一下」的步骤，我能不能指出它对应的是我哪一次真实执行时截的图？指不出 = 这一步还不该出现在文档里。**
+  - **由来（真实案例）**：一份实现文档里写「第 1 次返回 `UPDATE 1`、第 2 次返回 `UPDATE 0`，证明幂等」——作者确实跑过、也确实知道哪行是哪行，但两行输出只差一个数字、psql 一屏几乎一模一样，读者照着敲完对不上号，只能回头问「我执行了咋没看出有啥不同」。**根因不是命令不对，而是少了那张把「哪一行」圈出来的现场截图**——执行过不等于交付清楚了（可辨识性要求见「⚠️ 可视化验证铁律」分步操作教学演示第 6 条）。
+- ⚠️ **「片段即未执行」——凡是请读者去做的动作，必须给一段「从零跑到结论」的完整流程，禁止只丢一行片段。** 适用范围：文档里所有「请你去某环境跑一下 / 去确认一下 / 去做一下」的地方——**待确认项、开放问题、前置准备、复核步骤里的动手环节**（与相邻铁律的分工见本条末）。**这类残缺有一个共同的诊断指纹：只给一行片段 = 作者没真跑过。** 真跑过的人写不出这种片段——他必然先起了代理、先确认了库名、先把 `<某个账号>` 换成了真值，这些「先做的事」都在他手上，顺手就写下来了；**只有没跑过的人，才会把「凭印象记得的那条核心语句」当成读者需要的全部**。所以看到一行片段，先别急着补字，先去把它跑一遍——缺什么，跑一遍自然就浮出来了。
+  - **一行片段的四类典型残缺（对照自查，命中任一项即补齐）：**
+    1. **位置状语没有落点**——「在 ha-testing 上执行」。ha-testing 是哪个实例（全名 `horizonapi-485401:asia-southeast1:ha-testing`）？怎么连上去（起代理的完整命令）？连哪个库（`horizon_api`，不是默认的 `postgres`）？**只写「在 X 上」，读者到达不了 X。**
+    2. **占位符没换真值**——`has_table_privilege('<网关运行账号>', ...)` 里的 `<网关运行账号>`。读者既不知道该填什么，也不知道去哪儿查（真值是 `970360445295-compute@developer`，即 Cloud Run 的运行账号）。**这不是「敏感值抽成占位符」式的谨慎，而是信息缺了一半**——占位符能成立的前提是「读者自己查得到真值」（见下方「敏感值内嵌真实值」）。
+    3. **判读标准缺失**——跑出 `t` 是好事还是坏事？`f` 呢？**不给对错两种结果，读者拿到 `t` 也不知道该松口气还是该报警。**
+    4. **前置条件没交代**——代理没起、gcloud 没登录、没有实例访问权……读者卡在第一步，却不知道卡在哪。
+  - ⚠️ **澄清一个常见误解：给本机地址（如 `127.0.0.1:5433`）本身不算违规，缺的是「怎么把它建起来」。** 「⚠️ 验收环境铁律」禁止的是**读者自己造不出来**的东西（你的 dev server、你未提交的文件、你正在跑的本机服务）；而 Cloud SQL 代理这类**读者照着命令就能在自己机器上建出同一个**的本机地址是可以给的：把 `cloud-sql-proxy --port 5433 --auto-iam-authn horizonapi-485401:asia-southeast1:ha-testing` 给全，读者起自己的代理、连自己的 5433，拿到的是同一个库。**判断标准：读者照这几行，能不能在自己机器上把那个地址造出来？能 → 可以给（且必须给全建它的命令）；不能 → 必须换成公共可达的地址。**
+  - **落笔自查一句话：把这几步原样发给一个没参与过这个项目的人，他能不能不问你任何一句话、从头跑到底，并自己判断结论对错？** 不能 → 缺的是上面四类里的哪一类，补齐再写。
+  - **由来（真实案例）**：一份实现文档的待确认项里写「授权是否生效 | 在 ha-testing 上执行 `SELECT has_table_privilege('<网关运行账号>','provider_accounts','UPDATE');`」——**四类缺口全中**：`<网关运行账号>` 没填真值、「在 ha-testing 上」没说怎么连、没说是 `horizon_api` 库、没说 `t` / `f` 各代表什么。读者照着做，第一步就停在「我怎么连上 ha-testing」，只能回来问作者。**作者亲手跑过的那一版**（还是同一条 SQL，只是补齐）是：① 起代理 `cloud-sql-proxy --port 5433 --auto-iam-authn horizonapi-485401:asia-southeast1:ha-testing`（已在跑则跳过）→ ② 连库执行 `psql "host=127.0.0.1 port=5433 dbname=horizon_api user=baikaifa666@gmail.com sslmode=disable" -X -c "SELECT has_table_privilege('970360445295-compute@developer','provider_accounts','UPDATE');"` → ③ 判读：返回 `t` = 授权已生效，网关可以 UPDATE 这张表；返回 `f` = 未生效，网关写这张表会报 `permission denied for table provider_accounts (SQLSTATE 42501)`。**同一件事，前者读者只能回来问，后者读者自己就能得出结论。**
+  - ⚠️ **与相邻铁律的分工**：**本条管「请你去做一下」这类动手指令**（待确认项 / 开放问题 / 前置准备 / 动手环节）——它们本身不是「主张」，不在「⚠️ 主张自带复核流程铁律」的适用范围内，是最容易漏的一类；**「⚠️ 主张自带复核流程铁律」管「主张旁边要挂复核流程」**（读者能不能自己验一条断言）；**「⚠️ 验收环境铁律」管「给出去的东西别人打不打得开 / 跑不跑得起来」**。三者叠加，读者才既知道「去哪儿」、也知道「到了之后怎么做完、怎么判对错」。**复核流程里那一步如果本身是「在 X 上跑 Y」，同样要按本条给到从零可跑。**
 
 ## Go 规则
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@routerhub/agent-rules",
-  "version": "1.5.216",
+  "version": "1.5.218",
   "description": "Shared Copilot agent rules and guidelines for RouterHub projects",
   "main": "AGENTS.base.md",
   "bin": {

package/rules/global.md

@@ -208,6 +208,7 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
   3. **图间配过渡说明**：每张 caption 讲清「上一步发生了什么 → 这一步点哪里 → 预期看到什么」，报告内按操作顺序成段排布，读者能跟着连点；
   4. **逐张自检**：只看这张图 + 说明，能否照着点出下一步？能 = 合格；不能 = 补一张步骤图或补标注，直到整条流程读者不靠你就能走完。
   5. **就近嵌入（位置铁律）**：分步演示必须紧跟在「该操作对应概念/证据在报告中第一次出现、读者正要问『那到底怎么操作』」的地方之后（如展示「账户挂映射删除被 400 拒绝」的证据图 → 该图下方紧跟「先解绑再删除」的完整演示），禁止把演示单独堆到报告末尾或附录里——读者在定义处看不到演示、不知道下文还有、得自己翻到最后去找，等于没配演示。
+  6. **「差别可辨识」自检——读者照着做完，能看出你说的那个现象吗？** 光「能照着做出来」还不够，还得「做完能看懂」。凡文档描述了某种**对比 / 变化 / 前后差异**的步骤，必须自问：读者照着执行完，能不能一眼看出这个差异？**看不出 → 文字讲不清，必须补一张带箭头标注的执行现场截图，把「哪一行 / 哪个数字 / 哪一列」变了、变成了什么，直接圈出来。** 最容易翻车的是**肉眼看几乎一样的对比**：如 `UPDATE 1` 与 `UPDATE 0` 只差一个数字、同一段命令两次执行的输出几乎雷同、两次探测返回同一状态——作者自己心里清楚哪行对应哪句，读者对着一屏几乎相同的输出根本对不上号，只能回头来问「我执行了咋没看出有啥不同」。**判据是读者，不是作者——作者知道 ≠ 读者看得出。**
   - **类比**：交付报告像给菜谱——一道菜（一个功能）从备料到出锅（完整操作流程）必须给出「第 1 步切什么、第 2 步放多少油」的步骤图，读者照做能做出同一道菜；只贴一张成品照让读者猜过程，等于没教。
   - 反面示例：演示「删不掉挂着映射的账户」，只贴「删除被拒」和「最终删除成功」两张图、不展示中间「打开 Models → Remove(Unbind) → 确认」的顺序，读者仍不知道卡住时该点哪里。
 - ⚠️ **时序抢跑类 bug（表象像「坏了」、根因是「两个动作抢同一个瞬间被吞」）：测试中要能嗅出来，解释要先翻成人话。** 这类 bug 的表象（如「登录转圈 / 点按钮没反应 / 偶发失败」）离根因隔着好几层抽象——AI 测试功能过程中碰到此类现象，必须按时序根因去查，禁止当「偶发 / 环境问题」放掉；定位到根因后向用户解释时，必须先给一版「人话」（读者能顺着走一遍、能当场确认「对，就是它」），再附机制细节（路由守卫 / persist / token 生命周期……），禁止只甩机制清单、让用户自己翻译根因。识别指纹（命中越多越是这类）：
@@ -272,9 +273,26 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
      - ⚠️ **禁止用 `<a href="data:image/png;base64,...">` 包一层冒充「可放大」**：主流浏览器（Chrome 60+ / Firefox 59+）为防钓鱼**拦截 data: URI 的顶层导航**，点了毫无反应——看着写了，实际等于没做。必须用内联 JS lightbox。
      - ⚠️ **lightbox 的 CSS 与 JS 必须内联写在文档里**：文档是离线双击打开的自包含单文件，引 CDN 一断网就失效。
      - **类比：把发票缩印在报销单那一行旁边是为了「对得上」，但缩印件看不清金额——所以还得能拿起来凑近看。给不了这个动作，缩印就只是个装饰。**
-- ⚠️ **与相邻铁律的分工**：**本条管「报告怎么组织」——骨架必须是需求原文**；「⚠️ 取证报告铁律」管「报告要证明什么」（该变的变了 + 不该动的一行没动）；「⚠️ 修复验证铁律」管「怎么证明」（主验证 + 真实链路佐证）。三者叠加，报告才是「有骨架、有证据、有对照」的。
+- ⚠️ **与相邻铁律的分工**：**本条管「报告怎么组织」——骨架必须是需求原文**；「⚠️ 主张自带复核流程铁律」管「读者能不能自己验」（每条主张旁挂一份可照做的流程）；「⚠️ 取证报告铁律」管「报告要证明什么」（该变的变了 + 不该动的一行没动）；「⚠️ 修复验证铁律」管「怎么证明」（主验证 + 真实链路佐证）。四者叠加，报告才是「有骨架、有证据、有对照、可复核」的。
 - ⚠️ **具体操作流程见 `/forensic-report` skill 与 `/create-doc` skill**（需求原文从哪取、引用块与三列表怎么排、自研部分怎么回连）。
 
+## ⚠️ 主张自带复核流程铁律（读者得能自己走一遍，而不是只能信你）
+
+- ⚠️ **核心认知：报告里的每一条主张——A/B 截图、前后对比、那个数字——都是你的结论，不是读者能自己检查的东西。** 他看完手里只有两个选项：信，或者不信。**一份只能「信或不信」的报告，等于把「可核实」偷偷降级成了「请相信我」。** 判据只有一句话：**把报告发给他、你不说任何一句话，他能不能自己把这条主张跑一遍、亲眼看到同样的结果？** 不能 = 这条主张没交付。
+  - **类比：体检报告不能只印一句「各项指标正常」就让人签字——得把每项指标的数值、参考范围、以及「你自己去哪个科室能复查这一项」都写上，家属才可能拿着它去另一家医院复核。只给结论的报告是「请相信我」，不是「你可以自己看」。**
+- ⚠️ **硬性要求：每一条主张旁边，都要挂一份「你自己怎么复核这一条」的操作流程。** 适用范围 = 每条需求原话对应的实现、每个「已修复 / 已生效」的断言、每组前后对比，**外加报告里每个「请你自己去某环境跑一下 / 确认一下」的开放项**（待确认项、前置准备、动手环节——它们不是「主张」，作者自己也没结论，最容易只丢一行片段，因此同样必须给到从零可跑的完整流程，见「⚠️ 截图规范 → HTML 文档截图与 curl 命令规范」的「片段即未执行」）。流程由**逐步编号的操作**组成，每步三件套缺一不可：
+  1. **可复制粘贴的完整命令 / 操作**：参数写全，**禁止用 `...` 或占位符省略**（呼应「⚠️ 截图规范」的命令完整性要求）；且**不得引用只有你本机才有的东西**（`localhost`、本机路径、容器名、未提交的文件、正在跑的本机服务）——否则读者一跑就断（呼应「⚠️ 验收环境铁律」）。
+  2. **预期结果，对错两种都要给**：不只写「应该看到 X」（✅），还要写「**看到 Y 就是这条主张不成立**」（❌）。⚠️ **这是全篇最关键的一项**：只给成功输出，读者跑出任何别的东西时都无从判断是「我环境不对」还是「你说的不对」，最后又退回「信或不信」——**给了他反例，他才能自己宣判。**
+  3. **这一步证明了什么**（一句话点明证据含义），让读者不必读完整篇才知道自己在验什么。
+- ⚠️ **必须就近嵌入，禁止堆到附录。** 流程要紧贴它要证明的那条主张（同一行，或该行的正下方），读者读到那句主张时当场就能验。堆到文末 = 读者读完满篇结论、再自己回头找对应关系——跟「⚠️ 报告以需求原话为骨架铁律」的「禁止把读者支使到别处去翻」是同一条道理（也呼应「⚠️ 可视化验证铁律」分步演示的「就近嵌入（位置铁律）」）。
+- ⚠️ **让因果链在代码 / 数据里自证，而不是靠你断言「是这个改动修好的」。** 报告里「问题 → 修复」的那一环，优先落到读者能自己打开的可自查锚点上——如**修复脚本 / 部署脚本的注释里逐字引用了问题日志的 trace_id**、迁移文件里写了对应的表名、配置项当年的错值就摆在 diff 里。**最好的形式是：读者顺着你给的文件路径和行号点进去，能看到「问题」与「修复」被同一份代码同时提到。** 只有确实找不到这种锚点时，才退而用你的叙述把因果讲清楚。
+  - **类比：说「这把锁是为那次失窃换的」没人能核；但换锁记录上就写着那次失窃的报案号，谁都能对一下——证据链自己闭上了，不需要你在旁边解释。**
+- ⚠️ **复现不出来的必须显式标注，并给出「读者怎么自查当前状态」。** 有些主张在读者动手时确实跑不出同样结果（功能开关当时没开、数据事后被人工改过、线上版本已前进、依赖的环境已下线）。这类**禁止悄悄略过或含糊带过**，必须：① 明说复现不出来的原因；② 给出读者**自行确认当前状态**的命令（查当前版本号、查那个开关的现值）；③ 写明当时的环境版本 / 时间戳，让他能判断差异来自环境变化、而不是你的结论不成立。**含糊的边界比诚实标注的边界危险得多**——前者要么让读者把正常的环境差异误判成造假，要么反过来把造假误判成环境差异。
+- ⚠️ **作者自己的验证 ≠ 读者的复核，两者都要有、不可互相替代。** 「⚠️ 修复验证铁律」的三要素（怎么做的 / 结果 / 证明了什么）是**你给自己留的记录**；本条要的是**读者照着能重跑的操作流程**。你写「我用命令 X 得到了 Y」不等于读者拿到了那条命令——前者是记录，后者是交付。
+- ⚠️ **与相邻铁律的分工**：**本条管「读者能不能自己验」**；「⚠️ 报告以需求原话为骨架铁律」管「骨架是不是需求原文」（读者能不能对上号）；「⚠️ 取证报告铁律」管「报告要证明什么」（该变的变了 + 不该动的一行没动）；「⚠️ 修复验证铁律」管「你自己怎么证明」。四条叠加，读者才是「能对上号、看得懂结论、能自己复核」的。
+- ⚠️ **与「可复核导航」的分工（同属取证报告体系，别混为一谈）**：可复核导航回答**「去哪儿看」**（哪个页面、哪张表、点哪几下、直达 URL）；本条回答**「到了之后按什么顺序做什么、看到什么算对、看到什么算错」**。只给导航 = 读者到了现场仍不知道该验哪一项；只给流程没有导航 = 读者走完了流程，却不知道最终状态该去哪个页面看。**两者是「门牌号」与「进门之后的动线」，缺一个都到不了终点。**
+- ⚠️ **具体操作流程见 `/forensic-report` skill 与 `/create-doc` skill**（复核流程怎么排在需求原话那一行的正下方、命令与预期结果的三件套怎么给、复现不出来的边界怎么标注）。
+
 ## ⚠️ 取证报告铁律（证明「该变的变了」+「不该动的地方一行没动」）
 
 - ⚠️ **核心认知：功能验证只回答了一半问题。** 「页面功能验证铁律」「跨系统真实链路验收铁律」证明的都是**该变的地方变了**；但一次写操作真正危险的部分是它的**副作用范围**——级联删除、批量更新、绑定清理会不会顺手把不该动的数据一起带走。**副作用失控是静默的**：页面照常渲染、功能照常用、接口照常 200，只有被顺带删掉的那几张表知道出过事，而没有任何页面会主动告诉你「我多删了 3 行」。所以「不该动的地方一行没动」必须**单独取证**，不能由「功能正常」推出来。
@@ -632,6 +650,7 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 ### HTML 文档截图与 curl 命令规范
 
 - ⚠️ **HTML 页面/文档中的外部链接默认用新标签页打开**：所有指向外部资源（其他网站、GitHub 文档、私有文档仓库等）的链接一律写成 `<a target="_blank" rel="noopener" href="...">`，禁止不加 `target` 让用户点击后直接跳出当前页面。**类比：逛商场拿着一份导购地图，每个店名都标着「在新窗口查看」——点一家店不会把你从地图里踢出去，地图还在，能连续逛好几家；不新开窗口的话，每点一家店整张地图就没了，得反复按返回。** `rel="noopener"` 是安全兜底，防止新页面通过 `window.opener` 反向控制当前页（tabnabbing 钓鱼攻击）。
+- ⚠️ **文档正文里每一个「让读者去打开」的地址，后面都要紧跟一个显式的「在新标签页打开」按钮。** 光把已有链接写成 `target="_blank"` 不够——文档里大量地址是以**裸文本**出现的（如步骤里写「打开 `https://github.com/.../postgres.go#L651-L660`」「访问 `https://test-admin.horizonapi.ai/models/accounts`」），读者只能手动选中、复制、切浏览器、粘贴，一步一断。**判断标准：这句话是不是在让读者去打开某个地址？是 → 那个地址后面就得跟一个按钮**（`<a class="open-btn" target="_blank" rel="noopener" href="...">在新标签页打开 ↗</a>`）——点一下直接过去，文档还留在原地，能连着核对好几条。**反面示例：把 `打开 https://.../report.go#L58-L64` 这类纯文字丢给读者，等于让他自己搬运地址。**
 - ⚠️ **截图版 HTML 文档中的截图必须自动加箭头标注**：当用户要求写「截图版 HTML」文档（以截图为主体、图文结合说明实现/操作步骤的文档，如部署实现说明、操作指南等）时，嵌入的每张截图都必须自动用醒目的箭头 + 简短文字标签标注出关键区域/验证点/操作位置，让读者一眼看懂这张图对应文档的哪一步、证明了什么，禁止只贴裸图不标注。箭头标注放在不遮挡原内容的位置。
 - ⚠️ **HTML 文档中的截图必须以 `data:image/png;base64,...` 内嵌，禁止用文件路径或相对链接引用外部 PNG 文件。** 文档会被打开、移动、分享，外部图片路径一旦脱离原目录就全部失效，文档里全是裂图。生成文档后，散落的零散 PNG 文件应一并清理，只保留 HTML 本身。
 - ⚠️ **curl 命令必须完整可复制执行，禁止省略关键参数。** 包括但不限于：API Key / Token、请求体中的图片数据、完整的 URL。禁止用 `...` 或「省略其余参数」代替——看的人无法区分「这里不重要所以省略了」还是「这里我不会写所以跳过了」，前者让命令不可执行，后者掩盖了潜在的错误。
@@ -641,6 +660,18 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 - ⚠️ **测试用的图片等静态资源统一放到 `screenshots/` 临时目录，curl 命令中用相对路径引用**（如 `@screenshots/test.jpg`），确保命令在项目根目录下可直接执行。
 - ⚠️ **一键执行脚本/命令必须能直接复制到终端执行，且文档中必须配「一键复制」按钮。** 每条命令必须完整可执行（禁止省略参数、禁止用 `...` 占位、禁止只给片段），在项目根目录下可直接运行；文档中命令块右上角必须提供复制按钮，点击即可将完整命令复制到剪贴板并给出「已复制」反馈。
 - ⚠️ **文档中给出的每条命令/脚本，写入前必须亲自在终端实际执行验证过，确认确实可行后才能写入。** 执行失败的命令一律不得写入文档，禁止凭推断「应该能跑」就写进文档——推断得出的结论不能作为生成依据，必须实际测试过才能下结论。
+- ⚠️ **不止命令——文档里写的每一个操作步骤，都必须亲自真实走过一遍，并把这一次的执行现场截下来。** 「命令能跑通」和「跑出来长什么样」是两件事：读者要的是照着做出同一个结果，而你只有亲手做过，才知道中间会弹什么、输出长什么样、哪一步最容易看错。**执行过程本身就是配图的来源**——每写一步，手里就得有一步对应的现场截图（带箭头标注，圈出这一步的输出里哪一行是关键、它证明了什么）；**禁止事后凭印象补画，更禁止拿推断出的「应该会输出什么」当截图**。**没执行过就别写这一步**：没跑过就写进文档的步骤，轻则读者照着一路卡住，重则把错的做法教给了人。**自查一句话：文档里每一个「你来操作一下」的步骤，我能不能指出它对应的是我哪一次真实执行时截的图？指不出 = 这一步还不该出现在文档里。**
+  - **由来（真实案例）**：一份实现文档里写「第 1 次返回 `UPDATE 1`、第 2 次返回 `UPDATE 0`，证明幂等」——作者确实跑过、也确实知道哪行是哪行，但两行输出只差一个数字、psql 一屏几乎一模一样，读者照着敲完对不上号，只能回头问「我执行了咋没看出有啥不同」。**根因不是命令不对，而是少了那张把「哪一行」圈出来的现场截图**——执行过不等于交付清楚了（可辨识性要求见「⚠️ 可视化验证铁律」分步操作教学演示第 6 条）。
+- ⚠️ **「片段即未执行」——凡是请读者去做的动作，必须给一段「从零跑到结论」的完整流程，禁止只丢一行片段。** 适用范围：文档里所有「请你去某环境跑一下 / 去确认一下 / 去做一下」的地方——**待确认项、开放问题、前置准备、复核步骤里的动手环节**（与相邻铁律的分工见本条末）。**这类残缺有一个共同的诊断指纹：只给一行片段 = 作者没真跑过。** 真跑过的人写不出这种片段——他必然先起了代理、先确认了库名、先把 `<某个账号>` 换成了真值，这些「先做的事」都在他手上，顺手就写下来了；**只有没跑过的人，才会把「凭印象记得的那条核心语句」当成读者需要的全部**。所以看到一行片段，先别急着补字，先去把它跑一遍——缺什么，跑一遍自然就浮出来了。
+  - **一行片段的四类典型残缺（对照自查，命中任一项即补齐）：**
+    1. **位置状语没有落点**——「在 ha-testing 上执行」。ha-testing 是哪个实例（全名 `horizonapi-485401:asia-southeast1:ha-testing`）？怎么连上去（起代理的完整命令）？连哪个库（`horizon_api`，不是默认的 `postgres`）？**只写「在 X 上」，读者到达不了 X。**
+    2. **占位符没换真值**——`has_table_privilege('<网关运行账号>', ...)` 里的 `<网关运行账号>`。读者既不知道该填什么，也不知道去哪儿查（真值是 `970360445295-compute@developer`，即 Cloud Run 的运行账号）。**这不是「敏感值抽成占位符」式的谨慎，而是信息缺了一半**——占位符能成立的前提是「读者自己查得到真值」（见下方「敏感值内嵌真实值」）。
+    3. **判读标准缺失**——跑出 `t` 是好事还是坏事？`f` 呢？**不给对错两种结果，读者拿到 `t` 也不知道该松口气还是该报警。**
+    4. **前置条件没交代**——代理没起、gcloud 没登录、没有实例访问权……读者卡在第一步，却不知道卡在哪。
+  - ⚠️ **澄清一个常见误解：给本机地址（如 `127.0.0.1:5433`）本身不算违规，缺的是「怎么把它建起来」。** 「⚠️ 验收环境铁律」禁止的是**读者自己造不出来**的东西（你的 dev server、你未提交的文件、你正在跑的本机服务）；而 Cloud SQL 代理这类**读者照着命令就能在自己机器上建出同一个**的本机地址是可以给的：把 `cloud-sql-proxy --port 5433 --auto-iam-authn horizonapi-485401:asia-southeast1:ha-testing` 给全，读者起自己的代理、连自己的 5433，拿到的是同一个库。**判断标准：读者照这几行，能不能在自己机器上把那个地址造出来？能 → 可以给（且必须给全建它的命令）；不能 → 必须换成公共可达的地址。**
+  - **落笔自查一句话：把这几步原样发给一个没参与过这个项目的人，他能不能不问你任何一句话、从头跑到底，并自己判断结论对错？** 不能 → 缺的是上面四类里的哪一类，补齐再写。
+  - **由来（真实案例）**：一份实现文档的待确认项里写「授权是否生效 | 在 ha-testing 上执行 `SELECT has_table_privilege('<网关运行账号>','provider_accounts','UPDATE');`」——**四类缺口全中**：`<网关运行账号>` 没填真值、「在 ha-testing 上」没说怎么连、没说是 `horizon_api` 库、没说 `t` / `f` 各代表什么。读者照着做，第一步就停在「我怎么连上 ha-testing」，只能回来问作者。**作者亲手跑过的那一版**（还是同一条 SQL，只是补齐）是：① 起代理 `cloud-sql-proxy --port 5433 --auto-iam-authn horizonapi-485401:asia-southeast1:ha-testing`（已在跑则跳过）→ ② 连库执行 `psql "host=127.0.0.1 port=5433 dbname=horizon_api user=baikaifa666@gmail.com sslmode=disable" -X -c "SELECT has_table_privilege('970360445295-compute@developer','provider_accounts','UPDATE');"` → ③ 判读：返回 `t` = 授权已生效，网关可以 UPDATE 这张表；返回 `f` = 未生效，网关写这张表会报 `permission denied for table provider_accounts (SQLSTATE 42501)`。**同一件事，前者读者只能回来问，后者读者自己就能得出结论。**
+  - ⚠️ **与相邻铁律的分工**：**本条管「请你去做一下」这类动手指令**（待确认项 / 开放问题 / 前置准备 / 动手环节）——它们本身不是「主张」，不在「⚠️ 主张自带复核流程铁律」的适用范围内，是最容易漏的一类；**「⚠️ 主张自带复核流程铁律」管「主张旁边要挂复核流程」**（读者能不能自己验一条断言）；**「⚠️ 验收环境铁律」管「给出去的东西别人打不打得开 / 跑不跑得起来」**。三者叠加，读者才既知道「去哪儿」、也知道「到了之后怎么做完、怎么判对错」。**复核流程里那一步如果本身是「在 X 上跑 Y」，同样要按本条给到从零可跑。**
 
 ## Go 规则
 

package/skills/create-doc/SKILL.md

@@ -160,6 +160,7 @@ description: >-
 - 截取整页（full page），不是可视区域；用真实视口宽度（4K 屏自然宽 3840），禁止强制把视口拉宽
 - 截图结果必须在图上写出文字版完整 URL（走 `/screenshot-annotate --url`，叠进截图标题条），不得只靠地址栏；且该 URL 必须是别人能直接打开的地址（测试环境 / 线上域名），禁止 `localhost` / `127.0.0.1` / `file:///` 等本机地址；截图一律在测试环境取证，本地效果不作交付证据
 - 文档里每张截图旁再给一个可点击的跳转入口（`<a target="_blank" rel="noopener" href="...">打开页面</a>` 渲染成按钮），让别人一点就在新标签页打开该页面亲自复核，不用从图里抄地址
+- ⚠️ **正文里出现的每一个地址，后面都要紧跟一个「在新标签页打开」按钮**——不只是截图旁那个页面入口：步骤里写的 GitHub 代码行链接（`.../postgres.go#L651-L660`）、要复核的后台页面地址、需求单 URL，**只要这句话是在让读者去打开它，就得跟一个按钮**（`<a class="open-btn" target="_blank" rel="noopener" href="...">在新标签页打开 ↗</a>`）。**禁止把地址当纯文本丢在正文里**——读者得选中、复制、切浏览器、粘贴，一步一断，还容易复制漏字符。（规则见 `AGENTS.base.md`「HTML 文档截图与 curl 命令规范」）
 - ⚠️ **截图版 HTML 的每张截图都必须加箭头（或红框）标注**，指向该图要说明的关键操作点或关键数据，禁止放无标注的「裸截图」；标注放在页面空白区域，不遮挡关键内容。⚠️ **标注坐标必须精确**：用 `/screenshot-annotate` skill（浏览器 DOM 测得的坐标 → `annotate.js` 换算到截图像素），禁止肉眼估位
 - 制作过程中产生的中间截图文件统一放到 `screenshots/` 目录
 
@@ -171,11 +172,16 @@ description: >-
   2. **配截图**：该步骤对应的界面截图，必须带箭头/红框/提示文字标注指向关键操作点或关键数据，标注放在页面空白区域，不遮挡关键内容
   3. **详细说明结果**：这一步执行后出现了什么结果、验证了什么、为什么重要
 - ⚠️ 步骤之间用编号衔接（步骤 1 → 步骤 2 → …），说明文字必须一图一句、逐张不同，禁止用一句套话覆盖所有步骤的截图
+- ⚠️ **每个步骤都必须是「我真跑过的那一次」**：写入文档前，这一步必须亲自真实执行一遍，且**这次执行的现场截图就是该步骤配图的唯一来源**——禁止事后凭印象补画，禁止拿推断出的「应该会输出什么」当截图。**没执行过就别写这一步**：没跑过就写进文档的步骤，轻则读者照着一路卡住，重则把错的做法教给了人。**自查：文档里每个「你来操作一下」的步骤，我能不能指出它对应哪一次真实执行时截的图？指不出 = 不该出现在文档里。**（规则见 `AGENTS.base.md`「HTML 文档截图与 curl 命令规范」）
+- ⚠️ **「差别可辨识」自检——读者照着做完，能看出你说的那个现象吗？** 凡步骤涉及**对比 / 变化 / 前后差异**（两次执行、修复前后、A/B 两组输出），必须自问：读者照做之后，能不能一眼看出这个差异？**看不出 → 文字讲不清，必须在现场截图上用箭头把「哪一行 / 哪个数字 / 哪一列」变了、变成了什么直接圈出来。** 最容易翻车的是**肉眼看几乎一样的对比**：如 `UPDATE 1` 与 `UPDATE 0` 只差一个数字、同一段命令两次执行输出几乎雷同、两次探测返回同一状态——作者自己清楚哪行对应哪句，读者对着一屏几乎相同的输出根本对不上号，只能回头问「我执行了咋没看出有啥不同」。**判据是读者，不是作者——作者知道 ≠ 读者看得出。**（规则见 `AGENTS.base.md`「⚠️ 可视化验证铁律」分步操作教学演示第 6 条）
+- ⚠️ **「片段即未执行」——凡是请读者去做的动作，必须给一段「从零跑到结论」的完整流程，禁止只丢一行片段。** 适用范围：文档里所有「请你去某环境跑一下 / 去确认一下」的地方——**待确认项、开放问题、前置准备**（这些不是「主张」、作者自己也没结论，最容易顺手写一行就过去，恰恰是读者最需要「具体咋弄」的地方）。**诊断指纹：只给一行片段 = 作者没真跑过**——真跑过的人必然先起了代理、先确认了库名、先把占位符换成了真值，这些「先做的事」顺手就写下来了。四类典型残缺（命中任一即补齐）：① **位置状语没有落点**（「在 ha-testing 上执行」→ 实例全名是什么、怎么连上去、连哪个库）；② **占位符没换真值**（`<网关运行账号>` 该填 `970360445295-compute@developer`）；③ **判读标准缺失**（返回 `t` 说明什么、`f` 说明什么）；④ **前置条件没交代**（代理没起、gcloud 没登录、没有访问权）。**自查：把这几步原样发给一个没参与过这个项目的人，他能不能不问你任何一句话、从头跑到底并自己判断对错？**（规则见 `AGENTS.base.md`「HTML 文档截图与 curl 命令规范」的「片段即未执行」）
+- ⚠️ **给本机地址（如 `127.0.0.1:5433`）本身不算违规，缺的是「怎么把它建起来」。** 「验收环境铁律」禁止的是**读者自己造不出来**的东西（你的 dev server、未提交的文件、正在跑的本机服务）；Cloud SQL 代理这类**读者照着命令就能在自己机器上建出同一个**的本机地址可以给，但建它的命令必须给全（`cloud-sql-proxy --port 5433 --auto-iam-authn horizonapi-485401:asia-southeast1:ha-testing`）。**判断标准：读者照这几行能不能在自己机器上造出那个地址？能 → 可以给；不能 → 换成公共可达的地址。**
 - 截图统一用 base64 data URI 内嵌，禁止引用外部图片文件
 
 ### 命令与复制按钮
 
 - ⚠️ 文档中出现的每条可执行命令/脚本，必须能**直接复制到终端执行**：命令完整可复制（禁止省略参数、禁止用 `...` 占位、禁止只给片段）、在项目根目录下可直接运行
+- ⚠️ **「禁止只给片段」不只看命令本身，还要看读者能不能到达执行它的现场**：命令再完整，如果它前面缺了「怎么连上那个环境」（起代理 / 登录 / 装依赖）和「在哪个库 / 目录下跑」，读者照样跑不起来。**凡命令是「在 X 上执行 Y」的形式，X 必须落到实处**——X 的完整标识、连接它的完整命令、以及前置条件。判读标准同样不能少（跑出 A 是对、跑出 B 是不对）。四类残缺与自查见上一节「分步操作记录」的「片段即未执行」。
 - ⚠️ 每条命令/脚本写入文档前，必须**亲自在终端实际执行一遍验证确实可行**，验证通过后才能写入文档；执行失败的命令一律不得写入，禁止凭推断「应该能跑」就下结论
 - ⚠️ 每个命令块必须配「一键复制」按钮：点击按钮将完整命令复制到剪贴板，并给出「已复制」反馈
 - 复制按钮实现：命令块右上角放复制按钮 → 点击用 `navigator.clipboard.writeText(命令全文)` 复制（不可用时用 `document.execCommand('copy')` 兜底）→ 按钮文案短暂变为「已复制」→ 约 2 秒后恢复为「复制」

package/skills/forensic-report/SKILL.md

@@ -179,6 +179,8 @@ SELECT provider_id, count(*) FROM provider_model_pricing
 
 ⚠️ **判断标准：用户拿着这份报告、不问你任何一句话，能不能自己把那几个数字核对一遍？** 能 = 合格；不能 = 补导航，别急着交付。
 
+⚠️ **导航表里的每个 URL 都要渲染成可点的按钮，不能只当文本写在格子里。** 「直达 URL」这一列若是裸地址，用户还得选中、复制、切标签页、粘贴——一步一断，还容易复制漏字符。写成 `<a class="open-btn" target="_blank" rel="noopener" href="...">在新标签页打开 ↗</a>`，一点就在新标签页打开、报告留在原地，能连着核下一条。**正文里其它「让读者去打开」的地址同样处理**（GitHub 代码行链接、需求单 URL、要复核的后台页面）——判断标准只有一句：这句话是不是在让读者去打开某个地址？是 → 后面就跟一个按钮。（规则见 `AGENTS.base.md`「HTML 文档截图与 curl 命令规范」）
+
 ⚠️ **导航只解决「去哪儿看」，不解决「怎么验」——两者都要有，别拿导航当复核流程交付。** 导航给的是门牌号（哪个页面、点哪几下），复核流程给的是进门之后的动线（按什么顺序做什么、看到什么算对）。只说「去 `/accounts` 看那一行」，用户到了现场还是不知道该验哪一项、看到什么算通过——见下一节。
 
 ## 主张自带复核流程（每条主张旁边挂一份能照做的流程）
@@ -197,6 +199,10 @@ SELECT provider_id, count(*) FROM provider_model_pricing
 
 ⚠️ **位置铁律：就近嵌入，禁止堆到附录。** 面板要紧贴它要证明的那条主张——**在「需求原文 / 我们的实现 / 截图证据」三列表里，就是那一行的正下方，跨整行（`colspan`）铺开**。用户读到那句主张时当场就能验；堆到文末 = 他读完满篇结论、再自己回头找对应关系。
 
+⚠️ **本节适用范围不止「主张」——报告里每个「请你自己去某环境跑一下 / 确认一下」的开放项（待确认项、上线前准备、动手环节）一律同样处理，而且这里最容易翻车。** 它最容易只丢一行片段（`在 ha-testing 上执行 SELECT has_table_privilege('<网关运行账号>','provider_accounts','UPDATE');`），因为它不是「断言」、作者自己也没结论，顺手写一行就过去了——**而它恰恰是用户最需要「具体咋弄」的地方**。**诊断指纹：只给一行片段 = 作者没真跑过**（真跑过的人必然先起了代理、先确认了库名、先把占位符换成了真值，顺手就写下来了）。补齐标准 = 上文三件套，外加两类只在这里出现的缺口：**① 位置状语要有落点**（「在 X 上」必须给出 X 的完整标识 + 怎么连上去 + 连哪个库）；**② 前置条件要交代**（代理没起、gcloud 没登录、没有访问权，用户会卡在第一步而不知卡在哪）。
+
+⚠️ **本机地址本身不违规——违规的是只给地址、不给「怎么把它建起来」。** 「只有你本机才有的东西」指**用户自己造不出来**的（你的 dev server、未提交的文件、正在跑的本机服务）；Cloud SQL 代理这类**用户照着命令就能在自己机器上建出同一个**的本机地址可以给，但**建它的命令必须给全**（`cloud-sql-proxy --port 5433 --auto-iam-authn horizonapi-485401:asia-southeast1:ha-testing`）。判断标准：用户照这几行能不能在自己机器上造出那个地址？能 → 可以给（且必须给全建它的命令）；不能 → 换成公共可达的地址。
+
 ⚠️ **让因果链在代码 / 数据里自证，而不是靠你断言「是这个改动修好的」。** 「问题 → 修复」那一环，优先落到用户能自己打开的可自查锚点上——**最强的形式是修复脚本 / 部署脚本的注释里逐字引用了问题日志的 trace_id**，用户顺着文件路径和行号点进去，能看到「问题」与「修复」被同一份代码同时提到。退而求其次：迁移文件里写了对应表名、配置项当年的错值就摆在 diff 里。只有确实找不到锚点时，才用你的叙述把因果讲清楚。
 
 > 实例：某次修复的 `deploy.sh` 注释里逐字写着 `trace_id f0aaf7f89cf29f6d69bc8180118de23e`，而那正是此前报 `permission denied (42501)` 那条日志的 trace_id。用户点开脚本第 317-319 行自己一看，「问题日志 → 修复动作」这条链就闭上了，完全不需要信作者的转述。
@@ -240,6 +246,10 @@ SELECT provider_id, count(*) FROM provider_model_pricing
 
 ⚠️ **禁止用脚本模拟点击、直接改数据库、或调内部接口去造出「改动后」的状态。** 那不是「用户这么操作会发生什么」，而是「我造了一个我希望看到的结果」——两者的差别正是这个 Skill 要防的东西。**报告里要能让读者看出每一步点的是哪个按钮。**
 
+⚠️ **图必须是那一次真实执行的现场截图，不允许事后补画。** 步骤走完再回头凭印象截图、或拿推断出的「应该会输出什么」当图，等于把「我造了一个我希望看到的结果」从「操作」搬到了「配图」——同样是造出来的。**自查：这一步的配图，我能不能指出它是哪一次真实执行时截的？指不出 = 这一步等于没做。**
+
+⚠️ **「差别可辨识」自检——读者照着做完，能看出你说的那个现象吗？** 凡步骤涉及**对比 / 变化 / 前后差异**（两次执行、修复前后、A/B 两组输出），必须自问：读者照做之后，能不能一眼看出这个差异？**看不出 → 文字讲不清，必须在现场截图上用箭头把「哪一行 / 哪个数字 / 哪一列」变了、变成了什么直接圈出来。** 最容易翻车的是**肉眼看几乎一样的对比**：如 `UPDATE 1` 与 `UPDATE 0` 只差一个数字、同一段命令两次执行输出几乎雷同、两次探测返回同一状态——作者自己清楚哪行对应哪句，读者对着一屏几乎相同的输出根本对不上号，只能回头问「我执行了咋没看出有啥不同」。**判据是读者，不是作者——作者知道 ≠ 读者看得出。**（见规则「⚠️ 可视化验证铁律」分步操作教学演示第 6 条）
+
 ⚠️ **遇到「必须先做某个前置动作才能走到目标操作」时，要把前置原因一并写清**（如「删除接口有硬前置校验 `if account.IsActive` → 400 `account must be disabled before deletion`，所以第 ② 步不是可选项」）——否则读者自己复现时会卡在第一步，以为报告是错的。
 
 ## 报告骨架（缺一不算完成）