@routerhub/agent-rules 1.5.139 → 1.5.141

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 规范
 
@@ -117,6 +124,7 @@
 - ⚠️ **截图必须通过 PR Description 编辑区直接上传（拖拽/粘贴/文件选择按钮），禁止走评论区 `input[type=file]` 上传后再搬运 CDN URL。** 原因：PR Description 编辑区本身支持图片拖拽上传、自动转为 `![](CDN_URL)` 内嵌，一步到位；走评论区上传需要多一步「提交评论 → 复制 URL → 粘贴到 Description」，产生的临时图片评论会留在 PR 对话里干扰 reviewer 阅读，且多了一步手动搬运、容易出错。
 - ⚠️ 创建 PR 使用 `/create-pr` skill（自动生成中文内容 + 效果截图 + CDN 上传）。
 - ⚠️ **PR 创建即进入可评审状态**：直接创建正式 PR（非 Draft），创建完成、冲突检查与静态编译通过后即可直接交付 review，禁止先开 Draft PR、后续再手动标记 Ready for review。
+- ⚠️ **创建 PR 后必须先过 CI 再进入后续流程**：创建完成后第一时间执行 `gh pr checks <PR>`（必要时轮询直到非 `pending`）。若有任一检查 `failure`，必须先定位并修复失败项、推送新提交并复查到全部 `success`，然后才能进入循环 review、测试验证、交付 review 等后续步骤，禁止带红 CI 继续往下走。
 - ⚠️ **每次修改 PR 后（含创建 PR、push 新提交、响应 review 意见重新推送等所有改动 PR 的动作之后），都必须检查与主分支（默认分支）是否有冲突**：用 `gh pr view <PR> --json mergeable -q .mergeable` 检查（`MERGEABLE`=无冲突可合并，`CONFLICTING`=存在冲突，`UNKNOWN`=GitHub 尚未判定，稍后复查）。若存在冲突，必须先解决冲突再交付 review——`git merge origin/main`（或 `git rebase origin/main`）→ 解决冲突文件 → 测试通过 → 推送，确保 PR 处于可合并状态，禁止把带冲突的 PR 抛给 reviewer。主分支随时可能前进，一个创建时无冲突的 PR 可能在后续 push 后悄悄变冲突，因此每次改动 PR 后都必须重新检查，禁止只在创建时查一次就以为高枕无忧。
 - ⚠️ **每次修改 PR 后，除冲突检查外还必须检查 GitHub 静态编译是否通过，通过后发新版本**，三步收尾缺一不可：
   1. **与主分支冲突检查**：按上一条规则执行（`gh pr view <PR> --json mergeable -q .mergeable`），有冲突必须先解决。
@@ -300,9 +308,10 @@
 - Figma 设计还原使用 `/figma-to-code` skill，按 MCP 三步验证法执行。
 - ⚠️ **禁止用截图还原页面，必须走 Figma MCP。** 截图只能得到像素观感，拿不到真实的尺寸、间距、颜色 token、字体、层级结构等设计数据，还原结果必然失真。所有 Figma 还原必须通过 MCP 读取节点的结构化设计信息。
 
-## TDD 开发
+## 功能开发（可视化验证驱动）
 
-- 接收新需求使用 `/tdd-workflow` skill，按七步流程执行。
+- ⚠️ **接收新需求 / 功能开发时，自动触发 `/visual-report` skill，用它管理「验证证据」的产出**，无需用户额外吩咐。该 skill 的职责是：真实数据 + 真实交互 + 可视化证据（页面截图 / Redis 截图 / 数据库截图），把「功能对不对」用用户能一眼看懂的截图和报告证明给用户看。
+- ⚠️ **只有用户显式提到「测试 / TDD / 测试用例」时，才调用 `/tdd-workflow` skill**（写测试用例、跑回归）。没有明确指令时，禁止把 TDD 当作默认开发流程；默认开发流程是上面的 `/visual-report`。
 
 ## 优先级
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@routerhub/agent-rules",
-  "version": "1.5.139",
+  "version": "1.5.141",
   "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 规范
 
@@ -117,6 +124,7 @@ name: "通用规则"
 - ⚠️ **截图必须通过 PR Description 编辑区直接上传（拖拽/粘贴/文件选择按钮），禁止走评论区 `input[type=file]` 上传后再搬运 CDN URL。** 原因：PR Description 编辑区本身支持图片拖拽上传、自动转为 `![](CDN_URL)` 内嵌，一步到位；走评论区上传需要多一步「提交评论 → 复制 URL → 粘贴到 Description」，产生的临时图片评论会留在 PR 对话里干扰 reviewer 阅读，且多了一步手动搬运、容易出错。
 - ⚠️ 创建 PR 使用 `/create-pr` skill（自动生成中文内容 + 效果截图 + CDN 上传）。
 - ⚠️ **PR 创建即进入可评审状态**：直接创建正式 PR（非 Draft），创建完成、冲突检查与静态编译通过后即可直接交付 review，禁止先开 Draft PR、后续再手动标记 Ready for review。
+- ⚠️ **创建 PR 后必须先过 CI 再进入后续流程**：创建完成后第一时间执行 `gh pr checks <PR>`（必要时轮询直到非 `pending`）。若有任一检查 `failure`，必须先定位并修复失败项、推送新提交并复查到全部 `success`，然后才能进入循环 review、测试验证、交付 review 等后续步骤，禁止带红 CI 继续往下走。
 - ⚠️ **每次修改 PR 后（含创建 PR、push 新提交、响应 review 意见重新推送等所有改动 PR 的动作之后），都必须检查与主分支（默认分支）是否有冲突**：用 `gh pr view <PR> --json mergeable -q .mergeable` 检查（`MERGEABLE`=无冲突可合并，`CONFLICTING`=存在冲突，`UNKNOWN`=GitHub 尚未判定，稍后复查）。若存在冲突，必须先解决冲突再交付 review——`git merge origin/main`（或 `git rebase origin/main`）→ 解决冲突文件 → 测试通过 → 推送，确保 PR 处于可合并状态，禁止把带冲突的 PR 抛给 reviewer。主分支随时可能前进，一个创建时无冲突的 PR 可能在后续 push 后悄悄变冲突，因此每次改动 PR 后都必须重新检查，禁止只在创建时查一次就以为高枕无忧。
 - ⚠️ **每次修改 PR 后，除冲突检查外还必须检查 GitHub 静态编译是否通过，通过后发新版本**，三步收尾缺一不可：
   1. **与主分支冲突检查**：按上一条规则执行（`gh pr view <PR> --json mergeable -q .mergeable`），有冲突必须先解决。
@@ -300,9 +308,10 @@ name: "通用规则"
 - Figma 设计还原使用 `/figma-to-code` skill，按 MCP 三步验证法执行。
 - ⚠️ **禁止用截图还原页面，必须走 Figma MCP。** 截图只能得到像素观感，拿不到真实的尺寸、间距、颜色 token、字体、层级结构等设计数据，还原结果必然失真。所有 Figma 还原必须通过 MCP 读取节点的结构化设计信息。
 
-## TDD 开发
+## 功能开发（可视化验证驱动）
 
-- 接收新需求使用 `/tdd-workflow` skill，按七步流程执行。
+- ⚠️ **接收新需求 / 功能开发时，自动触发 `/visual-report` skill，用它管理「验证证据」的产出**，无需用户额外吩咐。该 skill 的职责是：真实数据 + 真实交互 + 可视化证据（页面截图 / Redis 截图 / 数据库截图），把「功能对不对」用用户能一眼看懂的截图和报告证明给用户看。
+- ⚠️ **只有用户显式提到「测试 / TDD / 测试用例」时，才调用 `/tdd-workflow` skill**（写测试用例、跑回归）。没有明确指令时，禁止把 TDD 当作默认开发流程；默认开发流程是上面的 `/visual-report`。
 
 ## 优先级
 

package/skills/create-pr/SKILL.md

@@ -95,11 +95,12 @@ gh pr create \
 
 ⚠️ 创建完 PR 后，禁止只做完步骤 7 收尾就交付。必须自动依次走完下方闭环，全程自动执行，未走完不算完成：
 
-1. **自动走循环 review**：自动触发 `/loop-review` skill，反复「拉取 AI review（Claude Opus + GPT 交叉验证）→ 逐条读真实代码判断哪些值得修 → 值得修的改、不值得修/误报的 Won't fix 切断 → push 触发新一轮 review」，直到某一轮不再冒出值得修的新问题才结束。
-2. **重新部署到测试环境**：循环 review 走完后，自动触发 `/deploy-test` skill，把最新代码重新部署到测试环境，确保测试的是循环 review 之后的最终代码。
-3. **测试环境验证 + 全程截图标注**：在测试环境用真实数据、真实页面交互测试本次改动（遵循「⚠️ 页面功能验证铁律」「⚠️ 用户视角测试铁律」）。测试过程中每一步都截图保留（遵循「⚠️ 截图规范」：视口 3840px 宽、`fullPage` 全页、URL 可见、存盘到 `docs/` 对应子目录），并在每张截图上用**箭头标注**关键改动区域/验证点，让看的人一眼看懂这张图证明了什么。
-4. **确认没问题才算完成**：测试通过、截图与箭头标注齐全、功能符合预期，才算真正完成。禁止测试没跑、截图没标注就宣称完成。
-5. **发新版本**：确认没问题后，回到下方步骤 7 完成冲突检查与静态编译检查，PR 合并后执行根目录 `./release.sh` 发新版本。
+1. **先做 CI 闸门检查**：创建 PR 后立即执行 `gh pr checks <PR>`（必要时轮询直到非 `pending`）。若存在任一 `failure`，必须先定位失败根因并修复，推送后复查到全部 `success`，再继续后续步骤；禁止带红 CI 进入下一步。
+2. **自动走循环 review**：自动触发 `/loop-review` skill，反复「拉取 AI review（Claude Opus + GPT 交叉验证）→ 逐条读真实代码判断哪些值得修 → 值得修的改、不值得修/误报的 Won't fix 切断 → push 触发新一轮 review」，直到某一轮不再冒出值得修的新问题才结束。
+3. **重新部署到测试环境**：循环 review 走完后，自动触发 `/deploy-test` skill，把最新代码重新部署到测试环境，确保测试的是循环 review 之后的最终代码。
+4. **测试环境验证 + 全程截图标注**：在测试环境用真实数据、真实页面交互测试本次改动（遵循「⚠️ 页面功能验证铁律」「⚠️ 用户视角测试铁律」）。测试过程中每一步都截图保留（遵循「⚠️ 截图规范」：视口 3840px 宽、`fullPage` 全页、URL 可见、存盘到 `docs/` 对应子目录），并在每张截图上用**箭头标注**关键改动区域/验证点，让看的人一眼看懂这张图证明了什么。
+5. **确认没问题才算完成**：测试通过、截图与箭头标注齐全、功能符合预期，才算真正完成。禁止测试没跑、截图没标注就宣称完成。
+6. **发新版本**：确认没问题后，回到下方步骤 7 完成冲突检查与静态编译检查，PR 合并后执行根目录 `./release.sh` 发新版本。
 
 ### 7. 每次修改 PR 后收尾检查（冲突 + 静态编译 + 发版本）
 
@@ -133,6 +134,6 @@ gh pr checks <PR>
 - ⚠️ 截图禁止提交到 Git 仓库
 - ⚠️ PR 截图直接内嵌在 Description 正文中（Markdown 图片语法）
 - ⚠️ 每次修改 PR 后（含创建、push 新提交、响应 review 意见）都必须做三步收尾：冲突检查 → 静态编译检查 → PR 合并后发新版本（见步骤 7）
-- ⚠️ **创建完 PR 后必须自动走完整闭环流程（见步骤 6.5）**：创建 PR → 自动循环 review → 重新部署测试环境验证（全程截图 + 箭头标注）→ 确认没问题 → 发新版本，五步缺一不可，未走完不算完成
+- ⚠️ **创建完 PR 后必须自动走完整闭环流程（见步骤 6.5）**：创建 PR → 先做 CI 闸门检查并修复失败项 → 自动循环 review → 重新部署测试环境验证（全程截图 + 箭头标注）→ 确认没问题 → 发新版本，六步缺一不可，未走完不算完成
 - ⚠️ **直接创建正式 PR（非 Draft）**：PR 创建完成即进入可评审状态，可直接交付 review，禁止先开 Draft PR、后续再手动标记 Ready for review
 - 作者不能 Approve 自己的 PR

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,71 @@
+---
+name: visual-report
+description: >-
+  功能开发/需求实现的可视化验证证据产出流程（默认触发，替代「测试先行」）。
+  触发场景：用户提出任何新需求、新功能、功能开发、修改功能、修复 bug、
+  「帮我开发」「帮我实现」「帮我写」「帮我做」「改一下」「优化一下」「重构一下」等
+  所有需要写代码产出功能的场景——只要用户是在提需求/做功能，就自动触发本 Skill，
+  无需用户额外说「做验证」「加测试」「写报告」。
+  职责：用真实数据 + 真实交互 + 可视化证据（页面截图 / Redis 截图 / 数据库截图），
+  把「功能对不对」用用户能一眼看懂的截图和报告证明给用户看。
+  ⚠️ 仅当用户显式提到「测试 / TDD / 测试用例」时才改走 /tdd-workflow。
+---
+
+# 可视化验证报告流程（Visual Report）
+
+⚠️ **本 Skill 已触发。第一句话必须输出：「🔧 已触发 `visual-report`，按可视化验证流程交付（真实数据 + 截图证据），不写测试用例」然后严格按照以下步骤执行，不得跳过。**
+
+## 核心原则
+
+- **验证职责 = 可视化证据，不是测试断言。** 功能对不对，用「用户能一眼看懂」的证据证明，而不是用「AI 自己写、AI 自己看」的测试用例（用户也看不懂、也影响不到最终质量）。
+- **默认不写测试用例。** 除非用户显式说「加测试 / 写测试用例 / 补回归」，否则不创建任何单测 / E2E / 冒烟脚本。
+- **证据必须基于运行时真实数据**，禁止 mock/虚构数据凑证据（真实数据会暴露空值、超长文本、特殊字符、异常关联等边界情况）。
+
+## 触发时机
+
+- **用户提需求 / 做功能 / 改 bug → 自动触发本 Skill**，不用等用户吩咐。
+- 用户说「加测试 / 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/数据库）必须走可视化验证；只有带不动又不属于上面两类的，才需要向用户说明并请用户决定