@routerhub/agent-rules 1.5.213 → 1.5.215

package/AGENTS.base.md

@@ -259,6 +259,22 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
   - ⚠️ **不命中触发条件的改动，两段都不走**（纯文案、纯展示类改动不受影响）。
 - ⚠️ **具体操作流程见 `/real-chain-verify` skill**（怎么画链路、每类系统怎么取证、两段各自做到什么程度、证据怎么组织成报告）。
 
+## ⚠️ 报告以需求原话为骨架铁律（原文 ↔ 实现 ↔ 截图证据 三段式）
+
+- ⚠️ **核心认知：报告的读者是需求方，而他判断「做没做到」的唯一依据是需求原话。** 报告只写「我们做了什么」，等于让读者自己拿记忆里的需求去比对满篇实现描述——需求→实现之间隔着产品转述、口头对齐、中途口径变化，他拼错了图就会以为某条没做（或以为做了其实没做）。**把原话摆在每段实现旁边，读者不用回忆、不用拼图，逐句对一眼即可。**
+  - **类比：报销单不能只写「我花了多少钱」，得把发票贴在你填的每一个数字旁边——审核的人对着发票核你填的数，而不是凭你的口头描述签字。**
+- ⚠️ **硬性要求（交付任何需求实现 / 修复验证 / 取证报告时逐条满足，缺一不算完成）：**
+  1. **逐字引用需求原文**：从需求单（Jira / Notion / 需求文档）**原样摘录**，保留原文用词与标点，**禁止润色、提炼、转述**。原文有错别字 / 用词不统一（如「装填维度」实为「筛选维度」）也照抄，旁边用括号注明「此处逐字保留原文」——**改写会让读者无法确认你引的是不是他要的那句**。
+  2. **按句拆解，三列并排：「需求原文（逐字） / 我们的实现 / 截图证据」**——每句原文独占一行；中间列写明这句对应改了哪块代码 / 哪个页面；**最右列把对应的证据直接内嵌在同一行里**（能截图的一律放带箭头标注的截图，纯后端的放命令输出 / 关键数字），让「原话 ↔ 实现 ↔ 证据」横向对齐，读者一行一行对过去即可。禁止把多句原文压成一段再笼统配一句「已实现」；也禁止右列只写一句「证据见下图 3」把读者支使到别处去翻——**翻过去就断了「这句配这张图」的对应关系，等于没配。**
+  3. **原文之外我们额外做的必须单列并回连原文**：自研 / 顺带修的部分另起一张表（两列：「原文之外我们额外做的 / 它服务于原文的哪一句」），**逐条说明它服务于原文哪一句**。禁止让自研内容脱离原文独立成章——读者看不出它跟需求的关系，就会当成「夹带私货」或「跑偏了」。
+  4. **原话出处给到可点链接**：需求单号 + URL 写在引用块头部（如 `MP-160 · https://.../browse/MP-160`），让读者能自己回去核对原话，而不是只能信你摘的这段。
+  5. **右列截图必须「点击即放大」**：三列排版下截图只占版心约 1/3 宽，缩略图仅够「对上号」，细节根本看不清——所以每张截图必须支持点击放大到全屏（lightbox 遮罩层：点图 → 半透明黑底居中大图 → ESC / 点背景关闭）。**这是硬要求，不是加分项**：放不大 = 读者拿到一张看不清的图 = 证据链断在最后一步。
+     - ⚠️ **禁止用 `<a href="data:image/png;base64,...">` 包一层冒充「可放大」**：主流浏览器（Chrome 60+ / Firefox 59+）为防钓鱼**拦截 data: URI 的顶层导航**，点了毫无反应——看着写了，实际等于没做。必须用内联 JS lightbox。
+     - ⚠️ **lightbox 的 CSS 与 JS 必须内联写在文档里**：文档是离线双击打开的自包含单文件，引 CDN 一断网就失效。
+     - **类比：把发票缩印在报销单那一行旁边是为了「对得上」，但缩印件看不清金额——所以还得能拿起来凑近看。给不了这个动作，缩印就只是个装饰。**
+- ⚠️ **与相邻铁律的分工**：**本条管「报告怎么组织」——骨架必须是需求原文**；「⚠️ 取证报告铁律」管「报告要证明什么」（该变的变了 + 不该动的一行没动）；「⚠️ 修复验证铁律」管「怎么证明」（主验证 + 真实链路佐证）。三者叠加，报告才是「有骨架、有证据、有对照」的。
+- ⚠️ **具体操作流程见 `/forensic-report` skill 与 `/create-doc` skill**（需求原文从哪取、引用块与三列表怎么排、自研部分怎么回连）。
+
 ## ⚠️ 取证报告铁律（证明「该变的变了」+「不该动的地方一行没动」）
 
 - ⚠️ **核心认知：功能验证只回答了一半问题。** 「页面功能验证铁律」「跨系统真实链路验收铁律」证明的都是**该变的地方变了**；但一次写操作真正危险的部分是它的**副作用范围**——级联删除、批量更新、绑定清理会不会顺手把不该动的数据一起带走。**副作用失控是静默的**：页面照常渲染、功能照常用、接口照常 200，只有被顺带删掉的那几张表知道出过事，而没有任何页面会主动告诉你「我多删了 3 行」。所以「不该动的地方一行没动」必须**单独取证**，不能由「功能正常」推出来。

package/package.json

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

package/rules/global.md

@@ -259,6 +259,22 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
   - ⚠️ **不命中触发条件的改动，两段都不走**（纯文案、纯展示类改动不受影响）。
 - ⚠️ **具体操作流程见 `/real-chain-verify` skill**（怎么画链路、每类系统怎么取证、两段各自做到什么程度、证据怎么组织成报告）。
 
+## ⚠️ 报告以需求原话为骨架铁律（原文 ↔ 实现 ↔ 截图证据 三段式）
+
+- ⚠️ **核心认知：报告的读者是需求方，而他判断「做没做到」的唯一依据是需求原话。** 报告只写「我们做了什么」，等于让读者自己拿记忆里的需求去比对满篇实现描述——需求→实现之间隔着产品转述、口头对齐、中途口径变化，他拼错了图就会以为某条没做（或以为做了其实没做）。**把原话摆在每段实现旁边，读者不用回忆、不用拼图，逐句对一眼即可。**
+  - **类比：报销单不能只写「我花了多少钱」，得把发票贴在你填的每一个数字旁边——审核的人对着发票核你填的数，而不是凭你的口头描述签字。**
+- ⚠️ **硬性要求（交付任何需求实现 / 修复验证 / 取证报告时逐条满足，缺一不算完成）：**
+  1. **逐字引用需求原文**：从需求单（Jira / Notion / 需求文档）**原样摘录**，保留原文用词与标点，**禁止润色、提炼、转述**。原文有错别字 / 用词不统一（如「装填维度」实为「筛选维度」）也照抄，旁边用括号注明「此处逐字保留原文」——**改写会让读者无法确认你引的是不是他要的那句**。
+  2. **按句拆解，三列并排：「需求原文（逐字） / 我们的实现 / 截图证据」**——每句原文独占一行；中间列写明这句对应改了哪块代码 / 哪个页面；**最右列把对应的证据直接内嵌在同一行里**（能截图的一律放带箭头标注的截图，纯后端的放命令输出 / 关键数字），让「原话 ↔ 实现 ↔ 证据」横向对齐，读者一行一行对过去即可。禁止把多句原文压成一段再笼统配一句「已实现」；也禁止右列只写一句「证据见下图 3」把读者支使到别处去翻——**翻过去就断了「这句配这张图」的对应关系，等于没配。**
+  3. **原文之外我们额外做的必须单列并回连原文**：自研 / 顺带修的部分另起一张表（两列：「原文之外我们额外做的 / 它服务于原文的哪一句」），**逐条说明它服务于原文哪一句**。禁止让自研内容脱离原文独立成章——读者看不出它跟需求的关系，就会当成「夹带私货」或「跑偏了」。
+  4. **原话出处给到可点链接**：需求单号 + URL 写在引用块头部（如 `MP-160 · https://.../browse/MP-160`），让读者能自己回去核对原话，而不是只能信你摘的这段。
+  5. **右列截图必须「点击即放大」**：三列排版下截图只占版心约 1/3 宽，缩略图仅够「对上号」，细节根本看不清——所以每张截图必须支持点击放大到全屏（lightbox 遮罩层：点图 → 半透明黑底居中大图 → ESC / 点背景关闭）。**这是硬要求，不是加分项**：放不大 = 读者拿到一张看不清的图 = 证据链断在最后一步。
+     - ⚠️ **禁止用 `<a href="data:image/png;base64,...">` 包一层冒充「可放大」**：主流浏览器（Chrome 60+ / Firefox 59+）为防钓鱼**拦截 data: URI 的顶层导航**，点了毫无反应——看着写了，实际等于没做。必须用内联 JS lightbox。
+     - ⚠️ **lightbox 的 CSS 与 JS 必须内联写在文档里**：文档是离线双击打开的自包含单文件，引 CDN 一断网就失效。
+     - **类比：把发票缩印在报销单那一行旁边是为了「对得上」，但缩印件看不清金额——所以还得能拿起来凑近看。给不了这个动作，缩印就只是个装饰。**
+- ⚠️ **与相邻铁律的分工**：**本条管「报告怎么组织」——骨架必须是需求原文**；「⚠️ 取证报告铁律」管「报告要证明什么」（该变的变了 + 不该动的一行没动）；「⚠️ 修复验证铁律」管「怎么证明」（主验证 + 真实链路佐证）。三者叠加，报告才是「有骨架、有证据、有对照」的。
+- ⚠️ **具体操作流程见 `/forensic-report` skill 与 `/create-doc` skill**（需求原文从哪取、引用块与三列表怎么排、自研部分怎么回连）。
+
 ## ⚠️ 取证报告铁律（证明「该变的变了」+「不该动的地方一行没动」）
 
 - ⚠️ **核心认知：功能验证只回答了一半问题。** 「页面功能验证铁律」「跨系统真实链路验收铁律」证明的都是**该变的地方变了**；但一次写操作真正危险的部分是它的**副作用范围**——级联删除、批量更新、绑定清理会不会顺手把不该动的数据一起带走。**副作用失控是静默的**：页面照常渲染、功能照常用、接口照常 200，只有被顺带删掉的那几张表知道出过事，而没有任何页面会主动告诉你「我多删了 3 行」。所以「不该动的地方一行没动」必须**单独取证**，不能由「功能正常」推出来。

package/skills/create-doc/SKILL.md

@@ -115,11 +115,15 @@ description: >-
 ### 图片处理
 
 - ⚠️ 所有图片以 base64 data URI 形式内嵌到 HTML 中，禁止引用外部图片文件
-- ⚠️ 所有图片必须支持点击放大、全屏查看（lightbox 遮罩层）
+- ⚠️ 所有图片必须支持点击放大、全屏查看（lightbox 遮罩层）——三列排版的缩略图只够「对上号」，放不大等于给了张看不清的图
 - lightbox 实现：图片绑定 click → 弹出半透明黑色遮罩 → 图片居中自适应 → ESC/点击背景关闭
+- ⚠️ **禁止用 `<a href="data:image/png;base64,...">` 实现放大**：Chrome 60+ / Firefox 59+ 为防钓鱼**拦截 data: URI 的顶层导航**，点击后毫无反应，看着像实现了其实没做。必须用内联 JS lightbox
+- ⚠️ **lightbox 的 CSS 与 JS 必须内联写在文档里**：文档是离线双击打开的自包含单文件，引 CDN 一断网就失效
 
 ### 报告结构
 
+⚠️ **交付「需求实现 / 修复验证 / 取证」类文档时，正文骨架必须以需求原话为第一层**（规则见 `AGENTS.base.md`「⚠️ 报告以需求原话为骨架铁律」）：逐字引用需求原文（保留原用词与标点），按句拆成「需求原文 / 我们的实现 / 截图证据」三列表并排——**最右列把带箭头标注的截图直接内嵌在同一行**（点击可放大到全屏），而不是只写「证据见下图 N」让读者自己去翻；引用块头部给需求单号 + 可点 URL；原文之外额外做的另起一张「原文之外我们额外做的 / 它服务于原文的哪一句」两列表逐条回连。纯操作指南 / 纯设计文档不受此限。
+
 ```html
 <!DOCTYPE html>
 <html lang="zh-CN">

package/skills/forensic-report/SKILL.md

@@ -212,14 +212,15 @@ SELECT provider_id, count(*) FROM provider_model_pricing
 
 ## 报告骨架（缺一不算完成）
 
-1. **产品自己的承诺**（可选但强烈建议）：产品在界面上对用户承诺了什么（如确认框文案原文）。**先摆产品的承诺，再用证据逐条验证它有没有兑现**——这比自说自话有说服力得多。
-2. **去哪儿看**（可复核导航）：N 个入口的实拍位置 + 点哪几下 + 直达 URL + 搜索词。
-3. **证据分层结论**：三层（页面数字 / 逐像素 / 数据库）各自的关键数值，并按「从软到硬」说明**每一层会被什么骗过、为什么需要下一层**。
-4. **差异归因**：每一处差异的定位 + 放大图 + 归因结论。
-5. **数据库逐行对照**：基线 → 事后 → 增减量 → 是否等于预期。
-6. **真实的操作链**：逐步截图 + 前置条件说明。
-7. **副作用范围上界表**：逐条 DELETE 的三个问题 + 实测值。
-8. **结论**：逐条列出证据关键数值与可复查标识，量化说清「该变的变了多少、不该动的 0 变化」。
+1. **需求原文 ↔ 实现 ↔ 截图证据**（骨架的第一层，见规则「⚠️ 报告以需求原话为骨架铁律」）：逐字引用需求单原文（保留原用词与标点，错别字照抄并注明「逐字保留原文」），按句拆成三列表并排——「需求原文（逐字） / 我们的实现 / 截图证据」，**最右列把带箭头标注的截图直接内嵌在同一行**（点击可放大到全屏），而不是只写「证据见下图 N」把读者支使到别处翻；引用块头部给出需求单号 + 可点 URL；原文之外我们额外做的另起一张两列表「原文之外我们额外做的 / 它服务于原文的哪一句」，逐条回连。
+2. **产品自己的承诺**（可选但强烈建议）：产品在界面上对用户承诺了什么（如确认框文案原文）。**先摆产品的承诺，再用证据逐条验证它有没有兑现**——这比自说自话有说服力得多。
+3. **去哪儿看**（可复核导航）：N 个入口的实拍位置 + 点哪几下 + 直达 URL + 搜索词。
+4. **证据分层结论**：三层（页面数字 / 逐像素 / 数据库）各自的关键数值，并按「从软到硬」说明**每一层会被什么骗过、为什么需要下一层**。
+5. **差异归因**：每一处差异的定位 + 放大图 + 归因结论。
+6. **数据库逐行对照**：基线 → 事后 → 增减量 → 是否等于预期。
+7. **真实的操作链**：逐步截图 + 前置条件说明。
+8. **副作用范围上界表**：逐条 DELETE 的三个问题 + 实测值。
+9. **结论**：逐条列出证据关键数值与可复查标识，量化说清「该变的变了多少、不该动的 0 变化」。
 
 ⚠️ **报告要在靠前位置放一张「为什么这样验证成立」的原理卡**：先讲清「本次变更的本质是哪一个动作」，再论证「手动模拟该动作 = 真实场景」。**本次的核心论证是**：这个修复的唯一改动点，可以精确映射成一个可手动触发的原子操作（如「对一个还挂着 Active 模型映射的账户执行删除」）——它在旧代码上必定失败、在新代码上必定成功，**是一个天然的「版本判别器」**。所以并不是「删了账户再回头证明表没被动」，而是**刻意构造了一个只有新版本才做得成的动作**：动作做成了 = 新版在跑；副作用范围正确 = 级联被限制住了。**两件事一起成立，才等于「修复按预期生效」。**
 
@@ -241,7 +242,7 @@ SELECT provider_id, count(*) FROM provider_model_pricing
 
 ## 相关
 
-- 规则出处：`AGENTS.base.md`「⚠️ 取证报告铁律」
+- 规则出处：`AGENTS.base.md`「⚠️ 取证报告铁律」；报告骨架第一层（需求原文 ↔ 实现 ↔ 证据）出处：`AGENTS.base.md`「⚠️ 报告以需求原话为骨架铁律」
 - 改之前证明问题存在：`AGENTS.base.md`「⚠️ 缺陷复现铁律」
 - 改之后证明问题消失：`AGENTS.base.md`「⚠️ 修复验证铁律」
 - 链路成不成立（下游接住了吗）：`AGENTS.base.md`「⚠️ 跨系统真实链路验收铁律」+ `real-chain-verify` skill