@routerhub/agent-rules 1.5.140 → 1.5.142

package/AGENTS.base.md

@@ -90,15 +90,22 @@
 - ⚠️ **编写 HTML 页面或前端功能后，必须用测试环境的真实数据验证，禁止用虚构/mock 数据自测。** 虚构数据只能验证「代码不报错」，无法验证「功能在真实场景下正常工作」——真实数据会暴露边界情况（空值、超长文本、特殊字符、异常关联关系等），虚构数据碰不到这些。测试环境有真实数据时优先用测试环境；测试环境数据不足时，从生产环境脱敏导出。
 - ⚠️ **页面功能验证必须通过实际的页面交互操作来完成**（打开浏览器、点击按钮、填写表单、观察渲染结果），模拟真实用户操作路径。禁止只靠代码审查、单元测试断言或静态分析代替实际页面操作验证——用户最终是通过页面交互使用功能的，不是通过测试断言。能用浏览器手动操作的，就用浏览器手动操作一遍。
 
-## ⚠️ 用户视角测试铁律（先模拟用户，再写测试）
-
-- ⚠️ **写测试用例之前，必须先站在用户视角写出「用户操作路径」**：用户在哪个页面、依次点了什么、填了什么、提交后看到什么结果。测试代码必须逐条对应这条真实路径，禁止直接跳进接口层自己发明一套测法。
-- ⚠️ **凡用户能在页面上操作的功能，测试必须以页面交互驱动，禁止直接调 API 代替用户操作。** 页面驱动方式按可用性排序：真实浏览器手动操作（能手动就手动）→ Playwright E2E 模拟点击/填写/提交 → agent-browser 脚本化操作。API 直连只允许用于两类辅助动作：① **数据准备**（造前置数据）；② **结果核验**（查库/查接口确认数据落地正确）。禁止让 API 成为测试主线本身。
+## ⚠️ 可视化验证铁律（默认不写测试用例，用证据说话）
+
+- ⚠️ **AI 默认禁止主动写「测试用例」**（单元测试、Playwright E2E、API 冒烟脚本等）。写不写测试、写哪些，完全由用户显式提出（如「加测试」「写测试用例」「补一条回归用例」）才执行。AI 不得在未获明确指令时自行创建测试用例、主动建议补测试、或把「测试先行 / TDD」当作默认开发姿势。
+- ⚠️ **功能验证的第一交付物是可视化证据报告，而不是测试断言。** AI 每做一个功能/修复，必须用「真实数据 + 真实交互 + 可视化证据」证明给用户看（遵循「⚠️ 修复验证铁律」「⚠️ 截图规范」）：
+  1. **页面/界面改动** → 打开真实页面，用真实数据走真实交互，全页截图 + 箭头标注关键改动区域；
+  2. **涉及 Redis**（缓存、计数器、限流、Session 等）→ 直接查看 Redis 运行时的 key/value（用 Redis for VS Code 插件页截图），A/B 对比改动前后的值；
+  3. **涉及数据库** → 直接查看数据库运行时数据（用 SQLTools 插件截图），A/B 对比改动前后的值。
+  优先让用户配合一起截图（用户是真人验证关卡：截图里的数据必须是真实的，AI 不得用 mock/虚构数据凑证据）。生成的验证报告是给用户看的，用户能一眼判断功能对不对，禁止把「AI 自己写、AI 自己看」的测试断言当作交付完成。
+- ⚠️ **只有以下两类情况才允许写测试用例（有明确触发路径，非默认行为）**：
+  1. **时序/并发/缓存失效类逻辑**：问题出在「某个时刻的状态」，截图截不出来（如并发竞态、延迟失效），必须写测试来证明行为正确；
+  2. **回归事故补种**：出现「改 A 把 B 改坏」的回归事故后，当场为出问题的点补一条回归测试，防止同类问题再次悄悄发生。
+- ⚠️ **禁止写测试 ≠ 允许带着基本错误交付。** AI 改完代码至少必须跑通编译 / 类型检查 / 最小冒烟，能自行发现并修复语法、类型、启动崩溃这类基本错误后再交付验证。连基本错误都发现不了就交付，比不写测试更糟。
 - ⚠️ **判断标准：这个功能用户能不能在页面上操作？**
-  - 能 → 必须页面驱动，能模拟用户手动测试就手动；
-  - 不能（纯后端接口、定时任务、无页面入口的链路）→ 才允许用 API 冒烟测试，且断言必须基于运行时真实返回。
-- ⚠️ **为什么不能拿 API 代替页面操作：API 通 ≠ 用户功能可用。** 用户看到的界面和 API 之间隔着 JS 报错、参数拼错、字段绑定错误、权限拦截、渲染失败、Loading 时序等一整层风险，API 直连全部绕过——测了接口返回正确，不代表用户在页面上点按钮真的能用。
-- ⚠️ **典型反例（禁止）**：功能明明有页面，测试却只 `curl` 接口断言返回体；用脚本直接造数据、直接断言数据库，跳过了页面操作。**正确做法**：打开页面 → 模拟真实点击/填写/提交 → 断言页面渲染结果并截图 → 必要时查库核验数据落地。
+  - 能 → 必须用真实页面交互验证，能模拟用户手动测试就手动，并截图留证；
+  - 不能（纯后端接口、定时任务、无页面入口的链路）→ 用运行时真实返回验证（curl/日志/查库/查 Redis），并把结果渲染成可视化证据（暗色终端风格的请求/响应对比 HTML 截图，或 Redis/SQLTools 插件截图）。
+- ⚠️ **验证结论必须基于运行时真实数据，禁止用 mock/虚构数据自测。** 真实数据会暴露边界情况（空值、超长文本、特殊字符、异常关联关系等），虚构数据碰不到这些。测试环境有真实数据时优先用测试环境；测试环境数据不足时，从生产环境脱敏导出。
 
 ## Git 规范
 
@@ -301,9 +308,10 @@
 - Figma 设计还原使用 `/figma-to-code` skill，按 MCP 三步验证法执行。
 - ⚠️ **禁止用截图还原页面，必须走 Figma MCP。** 截图只能得到像素观感，拿不到真实的尺寸、间距、颜色 token、字体、层级结构等设计数据，还原结果必然失真。所有 Figma 还原必须通过 MCP 读取节点的结构化设计信息。
 
-## TDD 开发
+## 功能开发（可视化验证驱动）
 
-- 接收新需求使用 `/tdd-workflow` skill，按七步流程执行。
+- ⚠️ **日常对话中，只要聊到写代码/改代码/排查问题/验证功能/实现需求等任何越过「闲聊」的实质内容，就自动触发 `/visual-report` skill，用它管理「验证证据」的产出**，无需用户额外吩咐。触发不依赖于用户正式说「提需求」「做功能」——用户在平常对话里随口提到的开发任务（如「这个页面的按钮没反应」「Redis 里这个 key 好像不对」「帮我把这个查询优化一下」）同样自动触发。该 skill 的职责是：真实数据 + 真实交互 + 可视化证据（页面截图 / Redis 截图 / 数据库截图），把「功能对不对」用用户能一眼看懂的截图和报告证明给用户看。
+- ⚠️ **只有用户显式提到「测试 / TDD / 测试用例」时，才调用 `/tdd-workflow` skill**（写测试用例、跑回归）。没有明确指令时，禁止把 TDD 当作默认开发流程；默认开发流程是上面的 `/visual-report`。
 
 ## 优先级
 

package/package.json

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

package/rules/global.md

@@ -90,15 +90,22 @@ name: "通用规则"
 - ⚠️ **编写 HTML 页面或前端功能后，必须用测试环境的真实数据验证，禁止用虚构/mock 数据自测。** 虚构数据只能验证「代码不报错」，无法验证「功能在真实场景下正常工作」——真实数据会暴露边界情况（空值、超长文本、特殊字符、异常关联关系等），虚构数据碰不到这些。测试环境有真实数据时优先用测试环境；测试环境数据不足时，从生产环境脱敏导出。
 - ⚠️ **页面功能验证必须通过实际的页面交互操作来完成**（打开浏览器、点击按钮、填写表单、观察渲染结果），模拟真实用户操作路径。禁止只靠代码审查、单元测试断言或静态分析代替实际页面操作验证——用户最终是通过页面交互使用功能的，不是通过测试断言。能用浏览器手动操作的，就用浏览器手动操作一遍。
 
-## ⚠️ 用户视角测试铁律（先模拟用户，再写测试）
-
-- ⚠️ **写测试用例之前，必须先站在用户视角写出「用户操作路径」**：用户在哪个页面、依次点了什么、填了什么、提交后看到什么结果。测试代码必须逐条对应这条真实路径，禁止直接跳进接口层自己发明一套测法。
-- ⚠️ **凡用户能在页面上操作的功能，测试必须以页面交互驱动，禁止直接调 API 代替用户操作。** 页面驱动方式按可用性排序：真实浏览器手动操作（能手动就手动）→ Playwright E2E 模拟点击/填写/提交 → agent-browser 脚本化操作。API 直连只允许用于两类辅助动作：① **数据准备**（造前置数据）；② **结果核验**（查库/查接口确认数据落地正确）。禁止让 API 成为测试主线本身。
+## ⚠️ 可视化验证铁律（默认不写测试用例，用证据说话）
+
+- ⚠️ **AI 默认禁止主动写「测试用例」**（单元测试、Playwright E2E、API 冒烟脚本等）。写不写测试、写哪些，完全由用户显式提出（如「加测试」「写测试用例」「补一条回归用例」）才执行。AI 不得在未获明确指令时自行创建测试用例、主动建议补测试、或把「测试先行 / TDD」当作默认开发姿势。
+- ⚠️ **功能验证的第一交付物是可视化证据报告，而不是测试断言。** AI 每做一个功能/修复，必须用「真实数据 + 真实交互 + 可视化证据」证明给用户看（遵循「⚠️ 修复验证铁律」「⚠️ 截图规范」）：
+  1. **页面/界面改动** → 打开真实页面，用真实数据走真实交互，全页截图 + 箭头标注关键改动区域；
+  2. **涉及 Redis**（缓存、计数器、限流、Session 等）→ 直接查看 Redis 运行时的 key/value（用 Redis for VS Code 插件页截图），A/B 对比改动前后的值；
+  3. **涉及数据库** → 直接查看数据库运行时数据（用 SQLTools 插件截图），A/B 对比改动前后的值。
+  优先让用户配合一起截图（用户是真人验证关卡：截图里的数据必须是真实的，AI 不得用 mock/虚构数据凑证据）。生成的验证报告是给用户看的，用户能一眼判断功能对不对，禁止把「AI 自己写、AI 自己看」的测试断言当作交付完成。
+- ⚠️ **只有以下两类情况才允许写测试用例（有明确触发路径，非默认行为）**：
+  1. **时序/并发/缓存失效类逻辑**：问题出在「某个时刻的状态」，截图截不出来（如并发竞态、延迟失效），必须写测试来证明行为正确；
+  2. **回归事故补种**：出现「改 A 把 B 改坏」的回归事故后，当场为出问题的点补一条回归测试，防止同类问题再次悄悄发生。
+- ⚠️ **禁止写测试 ≠ 允许带着基本错误交付。** AI 改完代码至少必须跑通编译 / 类型检查 / 最小冒烟，能自行发现并修复语法、类型、启动崩溃这类基本错误后再交付验证。连基本错误都发现不了就交付，比不写测试更糟。
 - ⚠️ **判断标准：这个功能用户能不能在页面上操作？**
-  - 能 → 必须页面驱动，能模拟用户手动测试就手动；
-  - 不能（纯后端接口、定时任务、无页面入口的链路）→ 才允许用 API 冒烟测试，且断言必须基于运行时真实返回。
-- ⚠️ **为什么不能拿 API 代替页面操作：API 通 ≠ 用户功能可用。** 用户看到的界面和 API 之间隔着 JS 报错、参数拼错、字段绑定错误、权限拦截、渲染失败、Loading 时序等一整层风险，API 直连全部绕过——测了接口返回正确，不代表用户在页面上点按钮真的能用。
-- ⚠️ **典型反例（禁止）**：功能明明有页面，测试却只 `curl` 接口断言返回体；用脚本直接造数据、直接断言数据库，跳过了页面操作。**正确做法**：打开页面 → 模拟真实点击/填写/提交 → 断言页面渲染结果并截图 → 必要时查库核验数据落地。
+  - 能 → 必须用真实页面交互验证，能模拟用户手动测试就手动，并截图留证；
+  - 不能（纯后端接口、定时任务、无页面入口的链路）→ 用运行时真实返回验证（curl/日志/查库/查 Redis），并把结果渲染成可视化证据（暗色终端风格的请求/响应对比 HTML 截图，或 Redis/SQLTools 插件截图）。
+- ⚠️ **验证结论必须基于运行时真实数据，禁止用 mock/虚构数据自测。** 真实数据会暴露边界情况（空值、超长文本、特殊字符、异常关联关系等），虚构数据碰不到这些。测试环境有真实数据时优先用测试环境；测试环境数据不足时，从生产环境脱敏导出。
 
 ## Git 规范
 
@@ -301,9 +308,10 @@ name: "通用规则"
 - Figma 设计还原使用 `/figma-to-code` skill，按 MCP 三步验证法执行。
 - ⚠️ **禁止用截图还原页面，必须走 Figma MCP。** 截图只能得到像素观感，拿不到真实的尺寸、间距、颜色 token、字体、层级结构等设计数据，还原结果必然失真。所有 Figma 还原必须通过 MCP 读取节点的结构化设计信息。
 
-## TDD 开发
+## 功能开发（可视化验证驱动）
 
-- 接收新需求使用 `/tdd-workflow` skill，按七步流程执行。
+- ⚠️ **日常对话中，只要聊到写代码/改代码/排查问题/验证功能/实现需求等任何越过「闲聊」的实质内容，就自动触发 `/visual-report` skill，用它管理「验证证据」的产出**，无需用户额外吩咐。触发不依赖于用户正式说「提需求」「做功能」——用户在平常对话里随口提到的开发任务（如「这个页面的按钮没反应」「Redis 里这个 key 好像不对」「帮我把这个查询优化一下」）同样自动触发。该 skill 的职责是：真实数据 + 真实交互 + 可视化证据（页面截图 / Redis 截图 / 数据库截图），把「功能对不对」用用户能一眼看懂的截图和报告证明给用户看。
+- ⚠️ **只有用户显式提到「测试 / TDD / 测试用例」时，才调用 `/tdd-workflow` skill**（写测试用例、跑回归）。没有明确指令时，禁止把 TDD 当作默认开发流程；默认开发流程是上面的 `/visual-report`。
 
 ## 优先级
 

package/skills/tdd-workflow/SKILL.md

@@ -1,22 +1,20 @@
 ---
 name: tdd-workflow
 description: >-
-  新需求 / 新功能 / 功能开发的 TDD 全流程。触发场景包括但不限于：
-  「新需求」「新功能」「新特性」「新模块」「新增」「添加功能」「加功能」「加个功能」「加一个功能」「做一个功能」「开发一个功能」「实现一个功能」。
-  「帮我开发」「帮我实现」「帮我写」「帮我做」「帮我搞」「帮我弄」「开发一下」「实现一下」「写一下」「做一下」「搞一下」「弄一下」。
-  「需求来了」「有个需求」「来了个需求」「接到需求」「需求是」「要做」「需要做」「需要开发」「需要实现」「需要写」「要开发」「要实现」「要写」「要做」。
-  「功能开发」「功能实现」「业务开发」「业务实现」「代码开发」「代码实现」。
-  「修改代码」「改代码」「改一下」「改一改」「改一版」「改功能」「改一下功能」「修改功能」「调整一下」「调整功能」「优化一下」「重构一下」。
-  「需求文档」「需求分析」「写需求」「需求设计」「方案设计」「设计方案」「出方案」。
-  「开始开发」「开始写」「开始写代码」「开始编码」「开始做」「开工」「动手」「动手吧」「开始吧」「搞起」「开搞」。
-  严格按：需求记录→确认版本→测试先行→基线回归→实现代码→全量回归→上线前回归，七步不可跳过。
+  仅当用户显式要求写测试时的 TDD 全流程。触发场景只有：用户明确说了
+  「加测试」「写测试用例」「补测试」「补一条回归用例」「TDD」「测试先行」等，
+  明确表示要写测试代码时才触发本 Skill。其他情况下收到新需求/功能开发，
+  一律走 /visual-report 的可视化验证流程，禁止本 Skill 被默认触发。
+  触发后严格按：需求记录→确认版本→测试先行→基线回归→实现代码→全量回归→上线前回归，七步执行。
 ---
 
 # TDD 开发流程
 
-⚠️ **本 Skill 已触发。第一句话必须输出：「🔧 已触发 `tdd-workflow`，按 TDD 七步流程开发...」然后严格按照以下步骤执行，不得跳过。**
+⚠️ **本 Skill 已触发。第一句话必须输出：「🔧 已触发 `tdd-workflow`，用户显式要求写测试，按 TDD 七步流程开发...」然后严格按照以下步骤执行，不得跳过。**
 
-测试驱动开发，每次接收新需求时强制遵循。
+⚠️ 只有在用户显式要求「写测试 / TDD」时才进入本流程。若用户只是说「做功能 / 开发需求 / 改代码」，而未提测试，第一反应是走 `/visual-report` 的可视化验证流程，不触发本 Skill。
+
+测试驱动开发，每次接收新需求时强制遵循（前提：用户已显式要求写测试）。
 
 ## 七步流程
 
@@ -85,7 +83,7 @@ node 上线回归测试点.js
 
 ## 重要规则
 
-- ⚠️ AI 第一反应不是写代码，而是写需求文档 + 设计测试用例
+- ⚠️ 本流程仅在用户显式要求测试时才触发（见文件头部触发条件）
 - ⚠️ 改动必须有迹可循：需求文档 → 测试用例 → 回归报告 → 代码改动
-- 如果用户说「直接改就行不用测试」，必须提醒测试是安全网
-- 测试用例命名含需求关键词，方便追溯
+- 如果用户说「直接改就行不用测试」，尊重用户决定，不写测试用例，改用 `/visual-report` 的可视化验证
+- 测试用例命名含需求关键词，方便追溯

package/skills/visual-report/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: visual-report
+description: >-
+  功能开发/需求实现的可视化验证证据产出流程（日常对话自动触发，替代「测试先行」）。
+  触发场景：日常对话中用户提出/聊到任何新需求、新功能、功能开发、修改功能、修复 bug、
+  「帮我开发」「帮我实现」「帮我写」「帮我做」「改一下」「优化一下」「重构一下」，
+  以及「这个页面的按钮没反应」「Redis 里这个 key 好像不对」「帮我把这个查询优化一下」等
+  任何越过「闲聊」、涉及写代码/改代码/排查问题/验证功能/实现需求的实质内容——
+  只要对话进入这类实质内容，就自动触发本 Skill，无需用户额外说「做验证」「加测试」「写报告」。
+  触发不依赖用户正式说「提需求/做功能」；日常对话里随口提到的开发任务同样触发。
+  职责：用真实数据 + 真实交互 + 可视化证据（页面截图 / Redis 截图 / 数据库截图），
+  把「功能对不对」用用户能一眼看懂的截图和报告证明给用户看。
+  ⚠️ 仅当用户显式提到「测试 / TDD / 测试用例」时才改走 /tdd-workflow。
+---
+
+# 可视化验证报告流程（Visual Report）
+
+⚠️ **本 Skill 已触发。第一句话必须输出：「🔧 已触发 `visual-report`，按可视化验证流程交付（真实数据 + 截图证据），不写测试用例」然后严格按照以下步骤执行，不得跳过。**
+
+## 核心原则
+
+- **验证职责 = 可视化证据，不是测试断言。** 功能对不对，用「用户能一眼看懂」的证据证明，而不是用「AI 自己写、AI 自己看」的测试用例（用户也看不懂、也影响不到最终质量）。
+- **默认不写测试用例。** 除非用户显式说「加测试 / 写测试用例 / 补回归」，否则不创建任何单测 / E2E / 冒烟脚本。
+- **证据必须基于运行时真实数据**，禁止 mock/虚构数据凑证据（真实数据会暴露空值、超长文本、特殊字符、异常关联等边界情况）。
+
+## 触发时机
+
+- **日常对话里只要出现实质性开发内容就自动触发本 Skill**，不依赖用户说「提需求/做功能」。包括：写代码、改代码、修 bug、排查问题、优化、重构、实现一个小功能，以及用户随口描述的一个开发任务（如「这个页面的按钮没反应」「Redis 里这个 key 好像不对」）。都要默认走可视化验证。
+- 用户说「加测试 / TDD / 测试用例」→ 改走 `/tdd-workflow`。
+
+## 验证矩阵（什么改动截什么证）
+
+| 改动类型 | 证据来源 | 具体动作 |
+|------|------|------|
+| 页面 / 界面改动 | 真实页面 | 打开真实页面，用真实数据走真实交互（点击、填写、提交、等待渲染），全页截图 + 箭头标注关键改动区域 |
+| Redis 相关 | Redis for VS Code 插件 | 查看运行时 Redis 的 key/value，A/B 对比改动前后的值（SET 已知值 → 触发业务动作 → 截图看值是否如预期） |
+| 数据库相关 | SQLTools 插件 | 查看运行时数据库的 row 数据，A/B 对比改动前后的值（插入/更新 → 触发业务动作 → 截图看落库是否如预期） |
+| 纯后端接口 / 定时任务无页面 | 运行时真实返回 | curl / 日志 / 查库 / 查 Redis，把结果渲染成可视化证据（暗色终端风格的请求/响应对比 HTML 截图，或 Redis/SQLTools 截图） |
+
+> Redis 和数据库截图优先用插件页截图：信息密度远高于命令行输出，且能直接看到 key 名、类型、TTL、行数据等完整上下文。
+
+## 用户配合截图
+
+- **AI 的屏幕截图能力是辅助，优先邀请用户配合一起截图。** 用户是真人验证关卡：截到的数据必须真实，AI 不得用 mock 数据骗自己（也骗用户）。
+- 需要用户操作浏览器/插件时，明确告诉用户「请打开 X，做 Y 操作，然后截图发给我」——具体到点哪个按钮、看哪个 key。
+- 用户截的图与 AI capability（agent-browser 截图 / 后台页面自动化截图）互为验证，双证据对齐。
+
+## 报告格式（交付物 = 可视化 HTML 报告）
+
+- 用 `/create-doc` skill 生成 HTML 格式报告（中文文件名），存到 `docs/` 对应子目录。
+- **报告骨架**（每个验证点必须有）：
+  1. **结论卡**：本次改动改了什么、验证结果是对是错、用户确认没有
+  2. **「为什么这样验证成立」原理说明卡**：先讲清楚 bug/功能差异的本质是哪一个动作，再论证「手动模拟该动作 = 真实场景」
+  3. **A/B 对照表**：修复前 vs 修复后（或改动前 vs 改动后），代码行为 / 等价操作 / 观测结果三列并排
+  4. **每步截图**：必须带箭头标注关键区域/验证点，图注写清「这张图证明了什么」，标注关键行/关键数据
+- 截图本身遵循「⚠️ 截图规范」：视口 3840px 宽、`fullPage` 全页、URL 可见、存到 `docs/` 对应子目录、文件名「编号 + 英文描述」。
+
+## 不写测试 ≠ 不查错
+
+- 禁写测试不代表带着基本错误交付。**改完代码至少必须跑通：编译 / 类型检查 / 最小冒烟**，能自行发现并修复语法、类型、启动崩溃这类基本错误后再交付验证。
+
+## 两类例外（用户显式要求或真实风险时才写测试）
+
+⚠️ 仅以下两类情况允许写测试用例（有明确触发路径，非默认行为）：
+
+1. **时序/并发/缓存失效类逻辑**：问题出在「某个时刻的状态」，截图截不出来（如并发竞态、延迟失效），必须写测试证明行为正确。
+2. **回归事故补种**：出现「改 A 把 B 改坏」的回归事故后，当场为出问题的点补一条回归测试，防止同类问题再次悄悄发生。
+
+## 重要规则
+
+- ⚠️ 第一反应不是写代码、也不是写测试，而是「想清楚怎么用证据证明功能对了」
+- ⚠️ 验证报告必须先给用户看、用户确认无误才算完成，禁止 AI 自认为「看起来对」就宣称完成
+- ⚠️ 带得动的改动（页面/Redis/数据库）必须走可视化验证；只有带不动又不属于上面两类的，才需要向用户说明并请用户决定