@routerhub/agent-rules 1.5.94 → 1.5.96

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/AGENTS.base.md +28 -4
  2. package/package.json +1 -1
  3. package/rules/frontend.md +2 -0
  4. package/rules/global.md +26 -4
package/AGENTS.base.md CHANGED
@@ -49,13 +49,35 @@
49
49
 
50
50
  ## ⚠️ E2E 回归测试铁律
51
51
 
52
- - ⚠️ **新增测试用例必须同步改两个文件**：Runner 脚本（登记用例 + 验收详情）和报告页面（数据 + 下拉选项 + 映射 + ID 常量），缺一不可。只改一处会导致测试中心看不到新用例。
53
- - ⚠️ **Playwright 截图必须用 `{ mode: 'on', fullPage: true }`**，禁止用默认的 `'only-on-failure'`。后者意味着测试全过时一张图都没有，报告里全是空白的。
52
+ ### 一、登记用例：双文件同步，缺一不可
53
+ - ⚠️ **新增一条回归用例，必须同时改两处**，只改一个会导致测试中心看不到新用例：
54
+ - **Runner 脚本**（如 `superpowers-regression-runner.js`）：`TEST_CASES` 登记用例（id / name / command / cwd）+ `getVisualEvidenceDetails` 补验收详情。
55
+ - **报告页面**（如 `上线前回归测试.html`）：`EMBEDDED_TEST_DATA` 数据 + scope 下拉选项 + test ID 常量 + `FILE_TO_TEST_MAP` 映射。
56
+
57
+ ### 二、Playwright 配置
58
+ - ⚠️ **截图必须用 `{ mode: 'on', fullPage: true }`**，禁止用默认的 `'only-on-failure'`。后者意味着测试全过时一张图都没有，报告里全是空白的。
54
59
  - ⚠️ **必须从正确的子目录执行测试**，禁止从项目根目录直接跑。根目录跑会导致配置文件中的相对路径（如 `.env`）解析错误，拿到错误的端口号。
55
- - ⚠️ **终端看到「全部通过」≠ 工作完成**。真正的完成标志是三件事：① 确认测试中心在线；② 通过 API 触发可视化验收；③ 确认报告里有截图。禁止看到终端绿色就告诉用户「做完了」——用户要的是能打开看的报告，不是终端日志。
56
- - ⚠️ **测试突然全部失败时，先检查外部依赖（数据库/SSH 隧道等）是否断开**，再改测试代码。禁止反复改测试代码去「绕过」基础设施问题。
60
+
61
+ ### 三、截图证据必须 base64 内嵌
62
+ - ⚠️ **报告 HTML 里的截图必须以 `data:image/png;base64` 内嵌**，禁止用文件路径 / 相对链接引用外部图片。报告会被打开、移动、分享，外部图片路径一旦脱离原目录就全部失效，报告里全是裂图，等于没有证据。
63
+ - ⚠️ **验证方法（返回值必须 > 0）**：`grep -c "data:image/png;base64" report.html`。返回 0 说明截图没内嵌成功，不算完成。
64
+
65
+ ### 四、「完成」的定义：终端绿色 ≠ 做完
66
+ - ⚠️ **终端看到「全部通过」不等于工作完成**。真正的完成标志是三件事，缺一不可：① 确认测试中心在线（`/api/health`）；② 通过 API 触发可视化验收（`/api/run-visual`）；③ 确认报告里有内嵌截图（第三节的 grep > 0）。禁止看到终端绿色就告诉用户「做完了」——用户要的是能打开看的报告，不是终端日志。
67
+
68
+ ### 五、失败排查顺序：先查基础设施
69
+ - ⚠️ **测试突然全部失败时，先检查外部依赖（数据库 / SSH 隧道、端口是否被抢）是否断开**，再改测试代码。禁止反复改测试代码去「绕过」基础设施问题。
70
+
71
+ ### 六、等待策略：等元素，别等时间
57
72
  - ⚠️ **页面 Loading 状态必须用元素可见性等待，禁止硬编码 `waitForTimeout`**。SPA 页面的正确等待顺序：先等关键元素出现（确认框架已挂载）→ 再等 Loading 状态消失（确认数据已返回）→ 最后才操作目标元素。顺序错了会出现「Loading 还没消失就点按钮 → 找不到 → 超时」。
58
73
 
74
+ ## ⚠️ 截图规范
75
+
76
+ - ⚠️ **截图视口宽度统一按 4K（3840px 宽）设置，禁止用 1920px**。1920 宽对复杂内容看不全、看不清。用 agent-browser 时先 `agent-browser --cdp 9223 viewport 3840 <height>`（高度按内容给足，如 2400+），或全页截图并保证宽度 3840。
77
+ - ⚠️ **截图必须 `fullPage: true` 截完整页面**，不要只截视口的一部分。
78
+ - ⚠️ **截图中必须能看到当前页面 URL**（浏览器地址栏，或页面顶部叠加 URL 标注），确保证据可追溯。
79
+ - **保存到磁盘文件**（`page.screenshot({ path, fullPage: true })`），禁止只用内联展示的截图工具——内联的不落盘，用户无法在 Markdown / HTML 文档里查看。路径统一放 `docs/` 对应功能子目录，文件名用「编号 + 英文描述」（如 `01-login-page.png`）。
80
+
59
81
  ## Go 规则
60
82
 
61
83
  - 值传递优先，软删除用 `gorm.DeletedAt`（禁止 `*time.Time`）。
@@ -122,6 +144,8 @@
122
144
 
123
145
  ## 前端规则
124
146
 
147
+ - ⚠️ **默认隐藏滚动条**：页面/容器出现滚动需求时，滚动条默认隐藏（内容仍可正常滚动），不得让滚动条可见。仅当用户明确说「需要滚动条」「可以有滚动条」「显示滚动条」等表述时，才允许显示。
148
+
125
149
  <!-- 前端特有规则在此添加 -->
126
150
 
127
151
  <!-- @domain: go-backend -->
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@routerhub/agent-rules",
3
- "version": "1.5.94",
3
+ "version": "1.5.96",
4
4
  "description": "Shared Copilot agent rules and guidelines for RouterHub projects",
5
5
  "main": "AGENTS.base.md",
6
6
  "bin": {
package/rules/frontend.md CHANGED
@@ -6,4 +6,6 @@ outputName: "frontend"
6
6
 
7
7
  ## 前端规则
8
8
 
9
+ - ⚠️ **默认隐藏滚动条**：页面/容器出现滚动需求时，滚动条默认隐藏（内容仍可正常滚动），不得让滚动条可见。仅当用户明确说「需要滚动条」「可以有滚动条」「显示滚动条」等表述时，才允许显示。
10
+
9
11
  <!-- 前端特有规则在此添加 -->
package/rules/global.md CHANGED
@@ -49,13 +49,35 @@ name: "通用规则"
49
49
 
50
50
  ## ⚠️ E2E 回归测试铁律
51
51
 
52
- - ⚠️ **新增测试用例必须同步改两个文件**：Runner 脚本（登记用例 + 验收详情）和报告页面（数据 + 下拉选项 + 映射 + ID 常量），缺一不可。只改一处会导致测试中心看不到新用例。
53
- - ⚠️ **Playwright 截图必须用 `{ mode: 'on', fullPage: true }`**，禁止用默认的 `'only-on-failure'`。后者意味着测试全过时一张图都没有，报告里全是空白的。
52
+ ### 一、登记用例：双文件同步，缺一不可
53
+ - ⚠️ **新增一条回归用例，必须同时改两处**，只改一个会导致测试中心看不到新用例：
54
+ - **Runner 脚本**（如 `superpowers-regression-runner.js`）：`TEST_CASES` 登记用例（id / name / command / cwd）+ `getVisualEvidenceDetails` 补验收详情。
55
+ - **报告页面**（如 `上线前回归测试.html`）：`EMBEDDED_TEST_DATA` 数据 + scope 下拉选项 + test ID 常量 + `FILE_TO_TEST_MAP` 映射。
56
+
57
+ ### 二、Playwright 配置
58
+ - ⚠️ **截图必须用 `{ mode: 'on', fullPage: true }`**，禁止用默认的 `'only-on-failure'`。后者意味着测试全过时一张图都没有，报告里全是空白的。
54
59
  - ⚠️ **必须从正确的子目录执行测试**，禁止从项目根目录直接跑。根目录跑会导致配置文件中的相对路径（如 `.env`）解析错误，拿到错误的端口号。
55
- - ⚠️ **终端看到「全部通过」≠ 工作完成**。真正的完成标志是三件事：① 确认测试中心在线；② 通过 API 触发可视化验收；③ 确认报告里有截图。禁止看到终端绿色就告诉用户「做完了」——用户要的是能打开看的报告，不是终端日志。
56
- - ⚠️ **测试突然全部失败时，先检查外部依赖（数据库/SSH 隧道等）是否断开**，再改测试代码。禁止反复改测试代码去「绕过」基础设施问题。
60
+
61
+ ### 三、截图证据必须 base64 内嵌
62
+ - ⚠️ **报告 HTML 里的截图必须以 `data:image/png;base64` 内嵌**，禁止用文件路径 / 相对链接引用外部图片。报告会被打开、移动、分享，外部图片路径一旦脱离原目录就全部失效，报告里全是裂图，等于没有证据。
63
+ - ⚠️ **验证方法（返回值必须 > 0）**：`grep -c "data:image/png;base64" report.html`。返回 0 说明截图没内嵌成功，不算完成。
64
+
65
+ ### 四、「完成」的定义：终端绿色 ≠ 做完
66
+ - ⚠️ **终端看到「全部通过」不等于工作完成**。真正的完成标志是三件事，缺一不可：① 确认测试中心在线（`/api/health`）；② 通过 API 触发可视化验收（`/api/run-visual`）；③ 确认报告里有内嵌截图（第三节的 grep > 0）。禁止看到终端绿色就告诉用户「做完了」——用户要的是能打开看的报告，不是终端日志。
67
+
68
+ ### 五、失败排查顺序：先查基础设施
69
+ - ⚠️ **测试突然全部失败时，先检查外部依赖（数据库 / SSH 隧道、端口是否被抢）是否断开**，再改测试代码。禁止反复改测试代码去「绕过」基础设施问题。
70
+
71
+ ### 六、等待策略：等元素，别等时间
57
72
  - ⚠️ **页面 Loading 状态必须用元素可见性等待，禁止硬编码 `waitForTimeout`**。SPA 页面的正确等待顺序：先等关键元素出现（确认框架已挂载）→ 再等 Loading 状态消失（确认数据已返回）→ 最后才操作目标元素。顺序错了会出现「Loading 还没消失就点按钮 → 找不到 → 超时」。
58
73
 
74
+ ## ⚠️ 截图规范
75
+
76
+ - ⚠️ **截图视口宽度统一按 4K（3840px 宽）设置，禁止用 1920px**。1920 宽对复杂内容看不全、看不清。用 agent-browser 时先 `agent-browser --cdp 9223 viewport 3840 <height>`（高度按内容给足，如 2400+），或全页截图并保证宽度 3840。
77
+ - ⚠️ **截图必须 `fullPage: true` 截完整页面**，不要只截视口的一部分。
78
+ - ⚠️ **截图中必须能看到当前页面 URL**（浏览器地址栏，或页面顶部叠加 URL 标注），确保证据可追溯。
79
+ - **保存到磁盘文件**（`page.screenshot({ path, fullPage: true })`），禁止只用内联展示的截图工具——内联的不落盘，用户无法在 Markdown / HTML 文档里查看。路径统一放 `docs/` 对应功能子目录，文件名用「编号 + 英文描述」（如 `01-login-page.png`）。
80
+
59
81
  ## Go 规则
60
82
 
61
83
  - 值传递优先，软删除用 `gorm.DeletedAt`（禁止 `*time.Time`）。