@routerhub/agent-rules 1.5.97 → 1.5.99

package/AGENTS.base.md

@@ -84,6 +84,17 @@
 ### 六、等待策略：等元素，别等时间
 - ⚠️ **页面 Loading 状态必须用元素可见性等待，禁止硬编码 `waitForTimeout`**。SPA 页面的正确等待顺序：先等关键元素出现（确认框架已挂载）→ 再等 Loading 状态消失（确认数据已返回）→ 最后才操作目标元素。顺序错了会出现「Loading 还没消失就点按钮 → 找不到 → 超时」。
 
+### 七、可视化报告质量：新用例要达到 blog 用例水准
+- ⚠️ **用例命名格式固定为「模块前缀-序号：中文场景描述」**（如「博客首页表单编辑后 iframe 刷新」），必须写清楚具体动作和期望结果，禁止写「测试一下」「验证功能」这类空话。这句命名会原样显示为报告里用例卡片的标题，是读者第一眼看到「这条用例在干嘛」的地方。
+- ⚠️ **每次截图必须统一封装成一个截图函数，除了保存图片文件，还要输出一段结构化文本**，包含三部分：这张截图的文件名、专属说明文字、专属验证点清单。回归系统正是靠这条结构化文本才能把说明画在每张截图下面；漏了这一步，报告里那张图下面就是空的，或退化成一句放之四海皆可的套话——这正是其他用例报告不如 blog 好看的根本原因。
+  - 说明文字固定格式「场景名：做了什么动作，出现了什么结果」（如「编辑弹窗：点击 Edit 后弹窗正确打开，显示 Blog 首页表单字段」）。
+  - 验证点控制在 2-4 条，每条必须对应一个人眼可直接观察的界面状态或数据结果（如「编辑弹窗正常打开」「表单字段可编辑」），禁止写「功能正常」这种无法验证的话。
+  - ⚠️ **说明文字和验证点必须一图一句、逐张不同，禁止用整条用例通用的一句套话覆盖所有截图。**
+- ⚠️ **接入回归测试注册表时，必须补一条兜底业务说明**，只在某张截图漏加专属说明时才会被使用，主力仍是逐张配的专属说明。兜底说明包含三个字段：
+  1. 关联的具体页面（写清楚是管理端还是用户端的哪一个页面，禁止写「相关页面」这种模糊说法）
+  2. 一句话说明验证的具体业务规则（不是「测试了这个功能」，要说清是哪条具体规则或哪种数据结果）
+  3. 三到五条检查点，同样要求每条对应一个可观察的界面状态或数据结果
+
 ## ⚠️ 截图规范
 
 - ⚠️ **截图视口宽度统一按 4K（3840px 宽）设置，禁止用 1920px**。1920 宽对复杂内容看不全、看不清。用 agent-browser 时先 `agent-browser --cdp 9223 viewport 3840 <height>`（高度按内容给足，如 2400+），或全页截图并保证宽度 3840。

package/package.json

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

package/postinstall.js

@@ -59,10 +59,14 @@ if (projectRoot.includes("node_modules")) {
   process.exit(0);
 }
 
-// 确保下游项目 .npmrc 中关闭 frozen-lockfile + 启用依赖 pre/post 脚本
+// 确保下游项目 .npmrc 中关闭 frozen-lockfile + 启用依赖 pre/post 脚本 + 关闭副作用缓存
 // frozen-lockfile=false：让 pnpm install 能在版本更新后直接执行
 // enable-pre-post-scripts=true：让 pnpm 始终执行依赖包的 postinstall 生命周期脚本，
 //   否则 pnpm 默认不会运行依赖的 postinstall，导致 agent-rules 更新后规则文件不刷新
+// side-effects-cache=false：pnpm 会按包内容哈希跨项目缓存"是否已执行过构建脚本"，
+//   一旦同一版本在本机任意项目装过一次，其他新项目直接装/更新该版本会被静默跳过 postinstall，
+//   而 agent-rules 的 postinstall 恰恰是往下游项目根目录写文件（不是往自身 node_modules 写副作用），
+//   关闭该缓存让 pnpm 每次都真正重新执行脚本
 const npmrcPath = path.join(projectRoot, ".npmrc");
 let npmrcContent = "";
 if (fs.existsSync(npmrcPath)) {
@@ -77,6 +81,10 @@ if (!npmrcContent.includes("enable-pre-post-scripts")) {
   npmrcEntries.push("# 确保依赖包的 postinstall 生命周期脚本始终执行（由 agent-rules 自动添加）");
   npmrcEntries.push("enable-pre-post-scripts=true");
 }
+if (!npmrcContent.includes("side-effects-cache")) {
+  npmrcEntries.push("# 关闭 pnpm 跨项目构建缓存，确保 agent-rules 每次 install/update 都重新生成规则文件（由 agent-rules 自动添加）");
+  npmrcEntries.push("side-effects-cache=false");
+}
 if (npmrcEntries.length > 0) {
   const newEntry = "\n" + npmrcEntries.join("\n") + "\n";
   fs.appendFileSync(npmrcPath, newEntry);

package/rules/global.md

@@ -84,6 +84,17 @@ name: "通用规则"
 ### 六、等待策略：等元素，别等时间
 - ⚠️ **页面 Loading 状态必须用元素可见性等待，禁止硬编码 `waitForTimeout`**。SPA 页面的正确等待顺序：先等关键元素出现（确认框架已挂载）→ 再等 Loading 状态消失（确认数据已返回）→ 最后才操作目标元素。顺序错了会出现「Loading 还没消失就点按钮 → 找不到 → 超时」。
 
+### 七、可视化报告质量：新用例要达到 blog 用例水准
+- ⚠️ **用例命名格式固定为「模块前缀-序号：中文场景描述」**（如「博客首页表单编辑后 iframe 刷新」），必须写清楚具体动作和期望结果，禁止写「测试一下」「验证功能」这类空话。这句命名会原样显示为报告里用例卡片的标题，是读者第一眼看到「这条用例在干嘛」的地方。
+- ⚠️ **每次截图必须统一封装成一个截图函数，除了保存图片文件，还要输出一段结构化文本**，包含三部分：这张截图的文件名、专属说明文字、专属验证点清单。回归系统正是靠这条结构化文本才能把说明画在每张截图下面；漏了这一步，报告里那张图下面就是空的，或退化成一句放之四海皆可的套话——这正是其他用例报告不如 blog 好看的根本原因。
+  - 说明文字固定格式「场景名：做了什么动作，出现了什么结果」（如「编辑弹窗：点击 Edit 后弹窗正确打开，显示 Blog 首页表单字段」）。
+  - 验证点控制在 2-4 条，每条必须对应一个人眼可直接观察的界面状态或数据结果（如「编辑弹窗正常打开」「表单字段可编辑」），禁止写「功能正常」这种无法验证的话。
+  - ⚠️ **说明文字和验证点必须一图一句、逐张不同，禁止用整条用例通用的一句套话覆盖所有截图。**
+- ⚠️ **接入回归测试注册表时，必须补一条兜底业务说明**，只在某张截图漏加专属说明时才会被使用，主力仍是逐张配的专属说明。兜底说明包含三个字段：
+  1. 关联的具体页面（写清楚是管理端还是用户端的哪一个页面，禁止写「相关页面」这种模糊说法）
+  2. 一句话说明验证的具体业务规则（不是「测试了这个功能」，要说清是哪条具体规则或哪种数据结果）
+  3. 三到五条检查点，同样要求每条对应一个可观察的界面状态或数据结果
+
 ## ⚠️ 截图规范
 
 - ⚠️ **截图视口宽度统一按 4K（3840px 宽）设置，禁止用 1920px**。1920 宽对复杂内容看不全、看不清。用 agent-browser 时先 `agent-browser --cdp 9223 viewport 3840 <height>`（高度按内容给足，如 2400+），或全页截图并保证宽度 3840。