@routerhub/agent-rules 1.5.131 → 1.5.133

package/AGENTS.base.md

@@ -125,6 +125,20 @@
 
 - 用户明确要求上线/部署生产环境 → 直接执行。AI 自行触及生产环境操作 → 必须先向用户确认。
 
+## ⚠️ 机密与证书安全铁律
+
+### 1. TLS 证书校验：禁止用跳过校验来「修通」连接
+
+- ⚠️ **当 TLS 连接报「证书不被信任」（如 certificate signed by unknown authority）时，禁止用 `InsecureSkipVerify=true` 跳过校验来让连接「跑通」。** 根因通常是服务端证书由私有 CA / 内部 CA 签发、不在系统信任池。正确做法：把该私有 CA 的根证书（PEM）加入客户端 `RootCAs`，保持 `InsecureSkipVerify=false` 做真校验。跳过校验等于关闭证书校验，暴露中间人风险，属于安全降级。
+
+### 2. 机密/证书的获取方式：部署时确定且几乎不变 → 优先平台注入
+
+- ⚠️ **运行时需要的机密 / 证书 / 配置，若其特点是「部署时确定、几乎不变化（只在发版时才更新）」，优先用平台注入（Cloud Run `--update-secrets` / K8s Secret 挂载为环境变量），而不是运行时调 Secret Manager / 配置中心去拉。** 判断依据：
+  - 运行时拉取多一层故障点（超时 / 权限 / 网络任一挂掉 → 业务 fail-closed）、多一套解析与护栏代码；
+  - `versions/latest` 轮换后仍需重启进程才生效，「热更新」是伪优势；
+  - 两种方式安全效果等价，平台注入更简单、更稳；
+  - 若公司已有同类服务在生产采用某种方式，优先对齐，不另造一套。
+
 ## 代码风格
 
 - 驼峰命名，禁止下划线，变量至少两个单词。禁止 `as` 和 `any`。函数式编程，不写 `class`，不写 `try/catch`。
@@ -147,38 +161,7 @@
 
 ## ⚠️ E2E 回归测试铁律
 
-### 一、登记用例：双文件同步，缺一不可
-- ⚠️ **新增一条回归用例，必须同时改两处**，只改一个会导致测试中心看不到新用例：
-  - **Runner 脚本**（如 `superpowers-regression-runner.js`）：`TEST_CASES` 登记用例（id / name / command / cwd）+ `getVisualEvidenceDetails` 补验收详情。
-  - **报告页面**（如 `上线前回归测试.html`）：`EMBEDDED_TEST_DATA` 数据 + scope 下拉选项 + test ID 常量 + `FILE_TO_TEST_MAP` 映射。
-
-### 二、Playwright 配置
-- ⚠️ **截图必须用 `{ mode: 'on', fullPage: true }`**，禁止用默认的 `'only-on-failure'`。后者意味着测试全过时一张图都没有，报告里全是空白的。
-- ⚠️ **必须从正确的子目录执行测试**，禁止从项目根目录直接跑。根目录跑会导致配置文件中的相对路径（如 `.env`）解析错误，拿到错误的端口号。
-
-### 三、截图证据必须 base64 内嵌
-- ⚠️ **报告 HTML 里的截图必须以 `data:image/png;base64` 内嵌**，禁止用文件路径 / 相对链接引用外部图片。报告会被打开、移动、分享，外部图片路径一旦脱离原目录就全部失效，报告里全是裂图，等于没有证据。
-- ⚠️ **验证方法（返回值必须 > 0）**：`grep -c "data:image/png;base64" report.html`。返回 0 说明截图没内嵌成功，不算完成。
-
-### 四、「完成」的定义：终端绿色 ≠ 做完
-- ⚠️ **终端看到「全部通过」不等于工作完成**。真正的完成标志是三件事，缺一不可：① 确认测试中心在线（`/api/health`）；② 通过 API 触发可视化验收（`/api/run-visual`）；③ 确认报告里有内嵌截图（第三节的 grep > 0）。禁止看到终端绿色就告诉用户「做完了」——用户要的是能打开看的报告，不是终端日志。
-
-### 五、失败排查顺序：先查基础设施
-- ⚠️ **测试突然全部失败时，先检查外部依赖（数据库 / SSH 隧道、端口是否被抢）是否断开**，再改测试代码。禁止反复改测试代码去「绕过」基础设施问题。
-
-### 六、等待策略：等元素，别等时间
-- ⚠️ **页面 Loading 状态必须用元素可见性等待，禁止硬编码 `waitForTimeout`**。SPA 页面的正确等待顺序：先等关键元素出现（确认框架已挂载）→ 再等 Loading 状态消失（确认数据已返回）→ 最后才操作目标元素。顺序错了会出现「Loading 还没消失就点按钮 → 找不到 → 超时」。
-
-### 七、可视化报告质量：新用例要达到 blog 用例水准
-- ⚠️ **用例命名格式固定为「模块前缀-序号：中文场景描述」**（如「博客首页表单编辑后 iframe 刷新」），必须写清楚具体动作和期望结果，禁止写「测试一下」「验证功能」这类空话。这句命名会原样显示为报告里用例卡片的标题，是读者第一眼看到「这条用例在干嘛」的地方。
-- ⚠️ **每次截图必须统一封装成一个截图函数，除了保存图片文件，还要输出一段结构化文本**，包含三部分：这张截图的文件名、专属说明文字、专属验证点清单。回归系统正是靠这条结构化文本才能把说明画在每张截图下面；漏了这一步，报告里那张图下面就是空的，或退化成一句放之四海皆可的套话——这正是其他用例报告不如 blog 好看的根本原因。
-  - 说明文字固定格式「场景名：做了什么动作，出现了什么结果」（如「编辑弹窗：点击 Edit 后弹窗正确打开，显示 Blog 首页表单字段」）。
-  - 验证点控制在 2-4 条，每条必须对应一个人眼可直接观察的界面状态或数据结果（如「编辑弹窗正常打开」「表单字段可编辑」），禁止写「功能正常」这种无法验证的话。
-  - ⚠️ **说明文字和验证点必须一图一句、逐张不同，禁止用整条用例通用的一句套话覆盖所有截图。**
-- ⚠️ **接入回归测试注册表时，必须补一条兜底业务说明**，只在某张截图漏加专属说明时才会被使用，主力仍是逐张配的专属说明。兜底说明包含三个字段：
-  1. 关联的具体页面（写清楚是管理端还是用户端的哪一个页面，禁止写「相关页面」这种模糊说法）
-  2. 一句话说明验证的具体业务规则（不是「测试了这个功能」，要说清是哪条具体规则或哪种数据结果）
-  3. 三到五条检查点，同样要求每条对应一个可观察的界面状态或数据结果
+- ⚠️ 做回归测试 / 登记回归用例 / 上线前回归时，必须使用 `/regression-test` skill（用例双文件同步、Playwright 配置、截图 base64 内嵌、报告质量、失败排查、等待策略等完整规范见该 skill）。
 
 ## ⚠️ 截图规范
 
@@ -288,8 +271,7 @@
 ## 部署规则
 
 - 发版统一执行 `./release.sh`。（自包含铁律见上方「⚠️ 可部署性自包含铁律」章节）
-- ⚠️ 部署测试环境必须使用 `/deploy-test` skill。任何包含「部署测试」「发布测试」「上线测试」「部署test」「推到test」「部署到测试环境」等表述的需求，必须先调用 `Skill` 工具加载 `deploy-test`，严禁跳过 skill 直接执行部署操作。
-- ⚠️ 部署测试环境的正确流程是：当前分支 → 合并到 test 分支 → 推送 test → 触发部署 → 切回原分支。禁止直接在 test 分支上提交代码，禁止跳过合并步骤直接部署功能分支。
+- ⚠️ 部署测试环境必须使用 `/deploy-test` skill，严禁跳过 skill 直接执行部署操作（合并/推送/部署/切回的具体流程见该 skill）。
 
 ## ⚠️ 配置中心变更生效铁律
 
@@ -299,9 +281,7 @@
 
 ## 文档规则
 
-- 新建文档使用 HTML 格式（`.html`）、中文文件名，存到 `docs/` 目录。
-- 使用 `/create-doc` skill 生成符合规范的 HTML 文档。
-- ⚠️ **需求/方案/操作过程类文档必须按步骤逐段记录并详细说明**：文档按操作步骤逐段组织，每一步包含三要素——① 做了什么动作（点了什么按钮/执行了什么命令/打开了什么页面）② 该步骤对应的界面截图，带箭头/红框/提示文字标注指向关键操作点或关键数据（标注放空白区，不遮挡内容）③ 详细说明这一步的结果与验证点。禁止跳过步骤、禁止只贴截图不给说明、禁止用一句套话覆盖所有步骤的截图。图片一律 base64 内嵌。
+- 新建文档使用 `/create-doc` skill（HTML 格式、中文文件名、base64 内嵌、分步记录三要素等规范见该 skill）。
 
 ## Figma 还原
 
@@ -340,9 +320,7 @@
 
 ### 🚨 测试环境部署铁律（不可跳过）
 
-- ⚠️ **部署到测试环境唯一入口：`/deploy-test` skill。** 不论用户怎么表述（「部署测试」「帮我部署」「推到test」「发布测试环境」等），必须通过 `Skill` 工具调用 `deploy-test`，禁止凭记忆手动执行 git 命令。
-- ⚠️ **必须先合并再部署**：流程必须是 `当前功能分支 → merge 到 test → push test → 触发部署 → 切回原分支`。严禁跳过 merge 步骤直接部署功能分支。
-- ⚠️ **部署完成后必须切回原分支**，不得停留在 test 分支。
+- ⚠️ **部署到测试环境唯一入口：`/deploy-test` skill**，必须先合并再部署、部署后切回原分支，严禁跳过合并步骤直接部署功能分支（完整流程见该 skill）。
 
 <!-- @domain: review-boundary -->
 

package/package.json

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

package/rules/devops.md

@@ -10,6 +10,4 @@ outputName: "devops"
 
 ### 🚨 测试环境部署铁律（不可跳过）
 
-- ⚠️ **部署到测试环境唯一入口：`/deploy-test` skill。** 不论用户怎么表述（「部署测试」「帮我部署」「推到test」「发布测试环境」等），必须通过 `Skill` 工具调用 `deploy-test`，禁止凭记忆手动执行 git 命令。
-- ⚠️ **必须先合并再部署**：流程必须是 `当前功能分支 → merge 到 test → push test → 触发部署 → 切回原分支`。严禁跳过 merge 步骤直接部署功能分支。
-- ⚠️ **部署完成后必须切回原分支**，不得停留在 test 分支。
+- ⚠️ **部署到测试环境唯一入口：`/deploy-test` skill**，必须先合并再部署、部署后切回原分支，严禁跳过合并步骤直接部署功能分支（完整流程见该 skill）。

package/rules/global.md

@@ -125,6 +125,20 @@ name: "通用规则"
 
 - 用户明确要求上线/部署生产环境 → 直接执行。AI 自行触及生产环境操作 → 必须先向用户确认。
 
+## ⚠️ 机密与证书安全铁律
+
+### 1. TLS 证书校验：禁止用跳过校验来「修通」连接
+
+- ⚠️ **当 TLS 连接报「证书不被信任」（如 certificate signed by unknown authority）时，禁止用 `InsecureSkipVerify=true` 跳过校验来让连接「跑通」。** 根因通常是服务端证书由私有 CA / 内部 CA 签发、不在系统信任池。正确做法：把该私有 CA 的根证书（PEM）加入客户端 `RootCAs`，保持 `InsecureSkipVerify=false` 做真校验。跳过校验等于关闭证书校验，暴露中间人风险，属于安全降级。
+
+### 2. 机密/证书的获取方式：部署时确定且几乎不变 → 优先平台注入
+
+- ⚠️ **运行时需要的机密 / 证书 / 配置，若其特点是「部署时确定、几乎不变化（只在发版时才更新）」，优先用平台注入（Cloud Run `--update-secrets` / K8s Secret 挂载为环境变量），而不是运行时调 Secret Manager / 配置中心去拉。** 判断依据：
+  - 运行时拉取多一层故障点（超时 / 权限 / 网络任一挂掉 → 业务 fail-closed）、多一套解析与护栏代码；
+  - `versions/latest` 轮换后仍需重启进程才生效，「热更新」是伪优势；
+  - 两种方式安全效果等价，平台注入更简单、更稳；
+  - 若公司已有同类服务在生产采用某种方式，优先对齐，不另造一套。
+
 ## 代码风格
 
 - 驼峰命名，禁止下划线，变量至少两个单词。禁止 `as` 和 `any`。函数式编程，不写 `class`，不写 `try/catch`。
@@ -147,38 +161,7 @@ name: "通用规则"
 
 ## ⚠️ E2E 回归测试铁律
 
-### 一、登记用例：双文件同步，缺一不可
-- ⚠️ **新增一条回归用例，必须同时改两处**，只改一个会导致测试中心看不到新用例：
-  - **Runner 脚本**（如 `superpowers-regression-runner.js`）：`TEST_CASES` 登记用例（id / name / command / cwd）+ `getVisualEvidenceDetails` 补验收详情。
-  - **报告页面**（如 `上线前回归测试.html`）：`EMBEDDED_TEST_DATA` 数据 + scope 下拉选项 + test ID 常量 + `FILE_TO_TEST_MAP` 映射。
-
-### 二、Playwright 配置
-- ⚠️ **截图必须用 `{ mode: 'on', fullPage: true }`**，禁止用默认的 `'only-on-failure'`。后者意味着测试全过时一张图都没有，报告里全是空白的。
-- ⚠️ **必须从正确的子目录执行测试**，禁止从项目根目录直接跑。根目录跑会导致配置文件中的相对路径（如 `.env`）解析错误，拿到错误的端口号。
-
-### 三、截图证据必须 base64 内嵌
-- ⚠️ **报告 HTML 里的截图必须以 `data:image/png;base64` 内嵌**，禁止用文件路径 / 相对链接引用外部图片。报告会被打开、移动、分享，外部图片路径一旦脱离原目录就全部失效，报告里全是裂图，等于没有证据。
-- ⚠️ **验证方法（返回值必须 > 0）**：`grep -c "data:image/png;base64" report.html`。返回 0 说明截图没内嵌成功，不算完成。
-
-### 四、「完成」的定义：终端绿色 ≠ 做完
-- ⚠️ **终端看到「全部通过」不等于工作完成**。真正的完成标志是三件事，缺一不可：① 确认测试中心在线（`/api/health`）；② 通过 API 触发可视化验收（`/api/run-visual`）；③ 确认报告里有内嵌截图（第三节的 grep > 0）。禁止看到终端绿色就告诉用户「做完了」——用户要的是能打开看的报告，不是终端日志。
-
-### 五、失败排查顺序：先查基础设施
-- ⚠️ **测试突然全部失败时，先检查外部依赖（数据库 / SSH 隧道、端口是否被抢）是否断开**，再改测试代码。禁止反复改测试代码去「绕过」基础设施问题。
-
-### 六、等待策略：等元素，别等时间
-- ⚠️ **页面 Loading 状态必须用元素可见性等待，禁止硬编码 `waitForTimeout`**。SPA 页面的正确等待顺序：先等关键元素出现（确认框架已挂载）→ 再等 Loading 状态消失（确认数据已返回）→ 最后才操作目标元素。顺序错了会出现「Loading 还没消失就点按钮 → 找不到 → 超时」。
-
-### 七、可视化报告质量：新用例要达到 blog 用例水准
-- ⚠️ **用例命名格式固定为「模块前缀-序号：中文场景描述」**（如「博客首页表单编辑后 iframe 刷新」），必须写清楚具体动作和期望结果，禁止写「测试一下」「验证功能」这类空话。这句命名会原样显示为报告里用例卡片的标题，是读者第一眼看到「这条用例在干嘛」的地方。
-- ⚠️ **每次截图必须统一封装成一个截图函数，除了保存图片文件，还要输出一段结构化文本**，包含三部分：这张截图的文件名、专属说明文字、专属验证点清单。回归系统正是靠这条结构化文本才能把说明画在每张截图下面；漏了这一步，报告里那张图下面就是空的，或退化成一句放之四海皆可的套话——这正是其他用例报告不如 blog 好看的根本原因。
-  - 说明文字固定格式「场景名：做了什么动作，出现了什么结果」（如「编辑弹窗：点击 Edit 后弹窗正确打开，显示 Blog 首页表单字段」）。
-  - 验证点控制在 2-4 条，每条必须对应一个人眼可直接观察的界面状态或数据结果（如「编辑弹窗正常打开」「表单字段可编辑」），禁止写「功能正常」这种无法验证的话。
-  - ⚠️ **说明文字和验证点必须一图一句、逐张不同，禁止用整条用例通用的一句套话覆盖所有截图。**
-- ⚠️ **接入回归测试注册表时，必须补一条兜底业务说明**，只在某张截图漏加专属说明时才会被使用，主力仍是逐张配的专属说明。兜底说明包含三个字段：
-  1. 关联的具体页面（写清楚是管理端还是用户端的哪一个页面，禁止写「相关页面」这种模糊说法）
-  2. 一句话说明验证的具体业务规则（不是「测试了这个功能」，要说清是哪条具体规则或哪种数据结果）
-  3. 三到五条检查点，同样要求每条对应一个可观察的界面状态或数据结果
+- ⚠️ 做回归测试 / 登记回归用例 / 上线前回归时，必须使用 `/regression-test` skill（用例双文件同步、Playwright 配置、截图 base64 内嵌、报告质量、失败排查、等待策略等完整规范见该 skill）。
 
 ## ⚠️ 截图规范
 
@@ -288,8 +271,7 @@ name: "通用规则"
 ## 部署规则
 
 - 发版统一执行 `./release.sh`。（自包含铁律见上方「⚠️ 可部署性自包含铁律」章节）
-- ⚠️ 部署测试环境必须使用 `/deploy-test` skill。任何包含「部署测试」「发布测试」「上线测试」「部署test」「推到test」「部署到测试环境」等表述的需求，必须先调用 `Skill` 工具加载 `deploy-test`，严禁跳过 skill 直接执行部署操作。
-- ⚠️ 部署测试环境的正确流程是：当前分支 → 合并到 test 分支 → 推送 test → 触发部署 → 切回原分支。禁止直接在 test 分支上提交代码，禁止跳过合并步骤直接部署功能分支。
+- ⚠️ 部署测试环境必须使用 `/deploy-test` skill，严禁跳过 skill 直接执行部署操作（合并/推送/部署/切回的具体流程见该 skill）。
 
 ## ⚠️ 配置中心变更生效铁律
 
@@ -299,9 +281,7 @@ name: "通用规则"
 
 ## 文档规则
 
-- 新建文档使用 HTML 格式（`.html`）、中文文件名，存到 `docs/` 目录。
-- 使用 `/create-doc` skill 生成符合规范的 HTML 文档。
-- ⚠️ **需求/方案/操作过程类文档必须按步骤逐段记录并详细说明**：文档按操作步骤逐段组织，每一步包含三要素——① 做了什么动作（点了什么按钮/执行了什么命令/打开了什么页面）② 该步骤对应的界面截图，带箭头/红框/提示文字标注指向关键操作点或关键数据（标注放空白区，不遮挡内容）③ 详细说明这一步的结果与验证点。禁止跳过步骤、禁止只贴截图不给说明、禁止用一句套话覆盖所有步骤的截图。图片一律 base64 内嵌。
+- 新建文档使用 `/create-doc` skill（HTML 格式、中文文件名、base64 内嵌、分步记录三要素等规范见该 skill）。
 
 ## Figma 还原
 

package/skills/create-doc/SKILL.md

@@ -69,7 +69,7 @@ description: >-
 
 - 截取整页（full page），不是可视区域
 - 截图结果必须包含当前页面 URL
-- 标注（箭头、提示文字等）放在页面空白区域，不覆盖页面内容
+- ⚠️ **截图版 HTML 的每张截图都必须加箭头（或红框）标注**，指向该图要说明的关键操作点或关键数据，禁止放无标注的「裸截图」；标注放在页面空白区域，不遮挡关键内容
 - 制作过程中产生的中间截图文件统一放到 `screenshots/` 目录
 
 ### 分步操作记录（每步必录）

package/skills/create-pr/SKILL.md

@@ -59,13 +59,11 @@ Closes #issue编号
 2. **截修复前**：临时注释/回退改动代码 → 等 hot reload → 同位置截图 → 恢复代码
    - ⚠️ **若线上数据已变化，导致无法在真实页面复现"修复前"效果**：允许改用等价的纯逻辑对比代替（用新旧两版逻辑代码跑同样的输入数据，把输出结果差异渲染成对比图），但必须在 Description 里明确写清楚"为什么无法复现 + 用了什么替代方案"，禁止因此省略截图或假装能复现。
 3. **生成对比图**：用 sharp 拼接 → 上方红/绿色标注条（❌修复前 / ✅修复后）→ 下方左右并排截图 → 关键改动区域矩形框圈选
-4. **上传 GitHub CDN**：
-   - 打开目标 PR 页面 → 找到评论框下隐藏的 `input[type=file]`（GitHub 当前实现选择器通常是 `#fc-new_comment_field`，选择器失效时用 `snapshot`/`eval` 重新定位，不要死等固定选择器）
-   - 用 `agent-browser upload` 上传本地图片 → GitHub 自动把图片转成 `https://github.com/user-attachments/assets/...` 的 CDN 地址并写入评论框文本
-   - 读取评论框内容拿到 CDN URL → 找到并点击提交按钮（`type=submit` 且文本为 `Comment` 的 `button`，例如 `Array.from(document.querySelectorAll('button')).find(b => b.textContent.trim() === 'Comment' && b.type === 'submit')`）**提交评论使图片持久化**（必须先提交评论，图片链接才长期有效）
-   - 若需要在评论框里追加/编辑文字（而非只上传图片），优先用 `agent-browser type` 模拟真实键盘输入——评论框是受控组件，直接用 `eval` 设置 `.value` 不会触发 React 状态更新，提交按钮会一直保持 disabled
+4. **上传 GitHub CDN**（在 PR Description 编辑区直接上传）：
+   - 打开目标 PR 页面 → 在 **Description 编辑区**直接上传图片（拖拽/粘贴，或定位 Description 编辑区的隐藏 `input[type=file]` 上传），GitHub 会自动把图片转成 `https://github.com/user-attachments/assets/...` 的 CDN 地址并插入 Description 正文，`![](CDN_URL)` 内嵌
+   - ⚠️ **禁止走评论区上传再搬运 CDN URL**：评论区上传需要多一步「提交评论 → 复制 URL → 粘贴到 Description」，产生的临时图片评论会留在 PR 对话里干扰 reviewer 阅读，且多一步手动搬运容易出错
    - ⚠️ **禁止用 `gh gist create --public` 等公开托管服务代替**——这属于未经授权的公开发布
-5. **写入 Description**：`gh pr edit --body-file` 把 CDN URL 替换进占位符位置，`![](CDN_URL)` 内嵌
+5. **保存 Description**：确认图片已内嵌进 Description 正文后，保存 PR Description 使图片持久化
 
 **截图规范**：
 - ⚠️ 截图禁止提交到 Git 仓库

package/skills/regression-test/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: regression-test
+description: >-
+  E2E 回归测试 / 回归用例登记与执行。触发场景包括但不限于：
+  「回归测试」「跑回归」「回归」「跑一下回归」「E2E 测试」「端到端测试」「E2E 回归」「上线前回归」「全量回归」「跑全量回归」「回归用例」「新增回归用例」「登记回归用例」「写回归测试」「回归报告」「测试报告」。
+  任何要求执行、登记、编写回归测试或用例的场景都应触发。
+  覆盖：用例登记双文件同步、Playwright 配置、截图 base64 内嵌、可视化报告质量、失败排查顺序、等待策略等完整规范。
+---
+
+# E2E 回归测试
+
+⚠️ **本 Skill 已触发。第一句话必须输出：「🔧 已触发 `regression-test`，按 E2E 回归测试规范执行...」然后严格按照以下步骤执行，不得跳过。**
+
+## ⚠️ 回归测试铁律
+
+### 一、登记用例：双文件同步，缺一不可
+- ⚠️ **新增一条回归用例，必须同时改两处**，只改一个会导致测试中心看不到新用例：
+  - **Runner 脚本**（如 `superpowers-regression-runner.js`）：`TEST_CASES` 登记用例（id / name / command / cwd）+ `getVisualEvidenceDetails` 补验收详情。
+  - **报告页面**（如 `上线前回归测试.html`）：`EMBEDDED_TEST_DATA` 数据 + scope 下拉选项 + test ID 常量 + `FILE_TO_TEST_MAP` 映射。
+
+### 二、Playwright 配置
+- ⚠️ **截图必须用 `{ mode: 'on', fullPage: true }`**，禁止用默认的 `'only-on-failure'`。后者意味着测试全过时一张图都没有，报告里全是空白的。
+- ⚠️ **必须从正确的子目录执行测试**，禁止从项目根目录直接跑。根目录跑会导致配置文件中的相对路径（如 `.env`）解析错误，拿到错误的端口号。
+
+### 三、截图证据必须 base64 内嵌
+- ⚠️ **报告 HTML 里的截图必须以 `data:image/png;base64` 内嵌**，禁止用文件路径 / 相对链接引用外部图片。报告会被打开、移动、分享，外部图片路径一旦脱离原目录就全部失效，报告里全是裂图，等于没有证据。
+- ⚠️ **验证方法（返回值必须 > 0）**：`grep -c "data:image/png;base64" report.html`。返回 0 说明截图没内嵌成功，不算完成。
+
+### 四、「完成」的定义：终端绿色 ≠ 做完
+- ⚠️ **终端看到「全部通过」不等于工作完成**。真正的完成标志是三件事，缺一不可：① 确认测试中心在线（`/api/health`）；② 通过 API 触发可视化验收（`/api/run-visual`）；③ 确认报告里有内嵌截图（第三节的 grep > 0）。禁止看到终端绿色就告诉用户「做完了」——用户要的是能打开看的报告，不是终端日志。
+
+### 五、失败排查顺序：先查基础设施
+- ⚠️ **测试突然全部失败时，先检查外部依赖（数据库 / SSH 隧道、端口是否被抢）是否断开**，再改测试代码。禁止反复改测试代码去「绕过」基础设施问题。
+
+### 六、等待策略：等元素，别等时间
+- ⚠️ **页面 Loading 状态必须用元素可见性等待，禁止硬编码 `waitForTimeout`**。SPA 页面的正确等待顺序：先等关键元素出现（确认框架已挂载）→ 再等 Loading 状态消失（确认数据已返回）→ 最后才操作目标元素。顺序错了会出现「Loading 还没消失就点按钮 → 找不到 → 超时」。
+
+### 七、可视化报告质量：新用例要达到 blog 用例水准
+- ⚠️ **用例命名格式固定为「模块前缀-序号：中文场景描述」**（如「博客首页表单编辑后 iframe 刷新」），必须写清楚具体动作和期望结果，禁止写「测试一下」「验证功能」这类空话。这句命名会原样显示为报告里用例卡片的标题，是读者第一眼看到「这条用例在干嘛」的地方。
+- ⚠️ **每次截图必须统一封装成一个截图函数，除了保存图片文件，还要输出一段结构化文本**，包含三部分：这张截图的文件名、专属说明文字、专属验证点清单。回归系统正是靠这条结构化文本才能把说明画在每张截图下面；漏了这一步，报告里那张图下面就是空的，或退化成一句放之四海皆可的套话——这正是其他用例报告不如 blog 好看的根本原因。
+  - 说明文字固定格式「场景名：做了什么动作，出现了什么结果」（如「编辑弹窗：点击 Edit 后弹窗正确打开，显示 Blog 首页表单字段」）。
+  - 验证点控制在 2-4 条，每条必须对应一个人眼可直接观察的界面状态或数据结果（如「编辑弹窗正常打开」「表单字段可编辑」），禁止写「功能正常」这种无法验证的话。
+  - ⚠️ **说明文字和验证点必须一图一句、逐张不同，禁止用整条用例通用的一句套话覆盖所有截图。**
+- ⚠️ **接入回归测试注册表时，必须补一条兜底业务说明**，只在某张截图漏加专属说明时才会被使用，主力仍是逐张配的专属说明。兜底说明包含三个字段：
+  1. 关联的具体页面（写清楚是管理端还是用户端的哪一个页面，禁止写「相关页面」这种模糊说法）
+  2. 一句话说明验证的具体业务规则（不是「测试了这个功能」，要说清是哪条具体规则或哪种数据结果）
+  3. 三到五条检查点，同样要求每条对应一个可观察的界面状态或数据结果