@routerhub/agent-rules 1.5.95 → 1.5.97
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.
- package/AGENTS.base.md +39 -4
- package/package.json +1 -1
- package/rules/global.md +39 -4
package/AGENTS.base.md
CHANGED
|
@@ -24,6 +24,19 @@
|
|
|
24
24
|
- ⚠️ 严格按用户原话实现需求，禁止擅自添加用户未要求的限制、规则或约束。
|
|
25
25
|
- ⚠️ 不确定某个限制是否必要时，必须先询问用户，禁止直接添加。
|
|
26
26
|
|
|
27
|
+
## ⚠️ 排查与协作铁律
|
|
28
|
+
|
|
29
|
+
- ⚠️ **排查「以前能用、现在不行」类问题时禁止用绕过手段掩盖问题**（改配置屏蔽报错、写同步脚本搬数据、临时禁用校验等），必须先定位根因再修复。
|
|
30
|
+
- ⚠️ **给出多个方案（A/B/C）供选择时，必须等用户明确选定后再执行**，禁止默认执行「推荐方案」。
|
|
31
|
+
- ⚠️ **用户提出模糊的调整要求**（如「再加点间距」「跟上面保持一致」「差不多就行」）时，必须先确认具体参照物和数值，禁止凭感觉直接改。
|
|
32
|
+
- ⚠️ **同一个问题被用户连续纠正两次后，第三次必须停下来问清楚根本原因**，禁止继续「改了又错、错了再改」的循环尝试。
|
|
33
|
+
- ⚠️ **修改多处复用的公共部分**（组件、配置、脚本、样式）后，必须找出所有引用/调用位置逐一验证，禁止只验证当前改动的那一处。
|
|
34
|
+
- ⚠️ **「数值/坐标/结构对齐」类验收，除了程序化校验外，必须额外做一次实际效果验证**（截图、真实访问、人工看一眼），不能只信数值对得上就算完成。
|
|
35
|
+
- ⚠️ **验证功能是否修复时，要用真实存在的数据/路径去测试**，避免用虚构的测试数据得出「失败」的假结论。
|
|
36
|
+
- ⚠️ **定位并修复根因后，必须清理诊断过程中留下的临时改动**（调试代码、临时开关、测试脚本），不要把绕过方案的残留物留在代码里。
|
|
37
|
+
- **某个工具/脚本报错时，先检查是否有残留的锁文件、临时文件、缓存导致的问题**，清理后重试；仍失败再切换备用方案，不要一遇报错就直接换路子。
|
|
38
|
+
- **长任务或涉及截图等大内容的操作，注意控制单次传入的数据量**（压缩、降低分辨率等），避免不必要地占满上下文。
|
|
39
|
+
|
|
27
40
|
## Git 规范
|
|
28
41
|
|
|
29
42
|
- 分支用 Git Flow（`feature/`、`bugfix/`、`hotfix/`、`refactor/`、`chore/`、`docs/`、`test/`），英文小写中划线分隔。
|
|
@@ -49,13 +62,35 @@
|
|
|
49
62
|
|
|
50
63
|
## ⚠️ E2E 回归测试铁律
|
|
51
64
|
|
|
52
|
-
|
|
53
|
-
- ⚠️
|
|
65
|
+
### 一、登记用例：双文件同步，缺一不可
|
|
66
|
+
- ⚠️ **新增一条回归用例，必须同时改两处**，只改一个会导致测试中心看不到新用例：
|
|
67
|
+
- **Runner 脚本**（如 `superpowers-regression-runner.js`）：`TEST_CASES` 登记用例（id / name / command / cwd）+ `getVisualEvidenceDetails` 补验收详情。
|
|
68
|
+
- **报告页面**（如 `上线前回归测试.html`）：`EMBEDDED_TEST_DATA` 数据 + scope 下拉选项 + test ID 常量 + `FILE_TO_TEST_MAP` 映射。
|
|
69
|
+
|
|
70
|
+
### 二、Playwright 配置
|
|
71
|
+
- ⚠️ **截图必须用 `{ mode: 'on', fullPage: true }`**，禁止用默认的 `'only-on-failure'`。后者意味着测试全过时一张图都没有，报告里全是空白的。
|
|
54
72
|
- ⚠️ **必须从正确的子目录执行测试**，禁止从项目根目录直接跑。根目录跑会导致配置文件中的相对路径（如 `.env`）解析错误，拿到错误的端口号。
|
|
55
|
-
|
|
56
|
-
|
|
73
|
+
|
|
74
|
+
### 三、截图证据必须 base64 内嵌
|
|
75
|
+
- ⚠️ **报告 HTML 里的截图必须以 `data:image/png;base64` 内嵌**，禁止用文件路径 / 相对链接引用外部图片。报告会被打开、移动、分享，外部图片路径一旦脱离原目录就全部失效，报告里全是裂图，等于没有证据。
|
|
76
|
+
- ⚠️ **验证方法（返回值必须 > 0）**：`grep -c "data:image/png;base64" report.html`。返回 0 说明截图没内嵌成功，不算完成。
|
|
77
|
+
|
|
78
|
+
### 四、「完成」的定义：终端绿色 ≠ 做完
|
|
79
|
+
- ⚠️ **终端看到「全部通过」不等于工作完成**。真正的完成标志是三件事，缺一不可：① 确认测试中心在线（`/api/health`）；② 通过 API 触发可视化验收（`/api/run-visual`）；③ 确认报告里有内嵌截图（第三节的 grep > 0）。禁止看到终端绿色就告诉用户「做完了」——用户要的是能打开看的报告，不是终端日志。
|
|
80
|
+
|
|
81
|
+
### 五、失败排查顺序：先查基础设施
|
|
82
|
+
- ⚠️ **测试突然全部失败时，先检查外部依赖（数据库 / SSH 隧道、端口是否被抢）是否断开**，再改测试代码。禁止反复改测试代码去「绕过」基础设施问题。
|
|
83
|
+
|
|
84
|
+
### 六、等待策略：等元素，别等时间
|
|
57
85
|
- ⚠️ **页面 Loading 状态必须用元素可见性等待，禁止硬编码 `waitForTimeout`**。SPA 页面的正确等待顺序：先等关键元素出现（确认框架已挂载）→ 再等 Loading 状态消失（确认数据已返回）→ 最后才操作目标元素。顺序错了会出现「Loading 还没消失就点按钮 → 找不到 → 超时」。
|
|
58
86
|
|
|
87
|
+
## ⚠️ 截图规范
|
|
88
|
+
|
|
89
|
+
- ⚠️ **截图视口宽度统一按 4K（3840px 宽）设置，禁止用 1920px**。1920 宽对复杂内容看不全、看不清。用 agent-browser 时先 `agent-browser --cdp 9223 viewport 3840 <height>`（高度按内容给足，如 2400+），或全页截图并保证宽度 3840。
|
|
90
|
+
- ⚠️ **截图必须 `fullPage: true` 截完整页面**，不要只截视口的一部分。
|
|
91
|
+
- ⚠️ **截图中必须能看到当前页面 URL**（浏览器地址栏，或页面顶部叠加 URL 标注），确保证据可追溯。
|
|
92
|
+
- **保存到磁盘文件**（`page.screenshot({ path, fullPage: true })`），禁止只用内联展示的截图工具——内联的不落盘，用户无法在 Markdown / HTML 文档里查看。路径统一放 `docs/` 对应功能子目录，文件名用「编号 + 英文描述」（如 `01-login-page.png`）。
|
|
93
|
+
|
|
59
94
|
## Go 规则
|
|
60
95
|
|
|
61
96
|
- 值传递优先，软删除用 `gorm.DeletedAt`（禁止 `*time.Time`）。
|
package/package.json
CHANGED
package/rules/global.md
CHANGED
|
@@ -24,6 +24,19 @@ name: "通用规则"
|
|
|
24
24
|
- ⚠️ 严格按用户原话实现需求，禁止擅自添加用户未要求的限制、规则或约束。
|
|
25
25
|
- ⚠️ 不确定某个限制是否必要时，必须先询问用户，禁止直接添加。
|
|
26
26
|
|
|
27
|
+
## ⚠️ 排查与协作铁律
|
|
28
|
+
|
|
29
|
+
- ⚠️ **排查「以前能用、现在不行」类问题时禁止用绕过手段掩盖问题**（改配置屏蔽报错、写同步脚本搬数据、临时禁用校验等），必须先定位根因再修复。
|
|
30
|
+
- ⚠️ **给出多个方案（A/B/C）供选择时，必须等用户明确选定后再执行**，禁止默认执行「推荐方案」。
|
|
31
|
+
- ⚠️ **用户提出模糊的调整要求**（如「再加点间距」「跟上面保持一致」「差不多就行」）时，必须先确认具体参照物和数值，禁止凭感觉直接改。
|
|
32
|
+
- ⚠️ **同一个问题被用户连续纠正两次后，第三次必须停下来问清楚根本原因**，禁止继续「改了又错、错了再改」的循环尝试。
|
|
33
|
+
- ⚠️ **修改多处复用的公共部分**（组件、配置、脚本、样式）后，必须找出所有引用/调用位置逐一验证，禁止只验证当前改动的那一处。
|
|
34
|
+
- ⚠️ **「数值/坐标/结构对齐」类验收，除了程序化校验外，必须额外做一次实际效果验证**（截图、真实访问、人工看一眼），不能只信数值对得上就算完成。
|
|
35
|
+
- ⚠️ **验证功能是否修复时，要用真实存在的数据/路径去测试**，避免用虚构的测试数据得出「失败」的假结论。
|
|
36
|
+
- ⚠️ **定位并修复根因后，必须清理诊断过程中留下的临时改动**（调试代码、临时开关、测试脚本），不要把绕过方案的残留物留在代码里。
|
|
37
|
+
- **某个工具/脚本报错时，先检查是否有残留的锁文件、临时文件、缓存导致的问题**，清理后重试；仍失败再切换备用方案，不要一遇报错就直接换路子。
|
|
38
|
+
- **长任务或涉及截图等大内容的操作，注意控制单次传入的数据量**（压缩、降低分辨率等），避免不必要地占满上下文。
|
|
39
|
+
|
|
27
40
|
## Git 规范
|
|
28
41
|
|
|
29
42
|
- 分支用 Git Flow（`feature/`、`bugfix/`、`hotfix/`、`refactor/`、`chore/`、`docs/`、`test/`），英文小写中划线分隔。
|
|
@@ -49,13 +62,35 @@ name: "通用规则"
|
|
|
49
62
|
|
|
50
63
|
## ⚠️ E2E 回归测试铁律
|
|
51
64
|
|
|
52
|
-
|
|
53
|
-
- ⚠️
|
|
65
|
+
### 一、登记用例：双文件同步，缺一不可
|
|
66
|
+
- ⚠️ **新增一条回归用例，必须同时改两处**，只改一个会导致测试中心看不到新用例：
|
|
67
|
+
- **Runner 脚本**（如 `superpowers-regression-runner.js`）：`TEST_CASES` 登记用例（id / name / command / cwd）+ `getVisualEvidenceDetails` 补验收详情。
|
|
68
|
+
- **报告页面**（如 `上线前回归测试.html`）：`EMBEDDED_TEST_DATA` 数据 + scope 下拉选项 + test ID 常量 + `FILE_TO_TEST_MAP` 映射。
|
|
69
|
+
|
|
70
|
+
### 二、Playwright 配置
|
|
71
|
+
- ⚠️ **截图必须用 `{ mode: 'on', fullPage: true }`**，禁止用默认的 `'only-on-failure'`。后者意味着测试全过时一张图都没有，报告里全是空白的。
|
|
54
72
|
- ⚠️ **必须从正确的子目录执行测试**，禁止从项目根目录直接跑。根目录跑会导致配置文件中的相对路径（如 `.env`）解析错误，拿到错误的端口号。
|
|
55
|
-
|
|
56
|
-
|
|
73
|
+
|
|
74
|
+
### 三、截图证据必须 base64 内嵌
|
|
75
|
+
- ⚠️ **报告 HTML 里的截图必须以 `data:image/png;base64` 内嵌**，禁止用文件路径 / 相对链接引用外部图片。报告会被打开、移动、分享，外部图片路径一旦脱离原目录就全部失效，报告里全是裂图，等于没有证据。
|
|
76
|
+
- ⚠️ **验证方法（返回值必须 > 0）**：`grep -c "data:image/png;base64" report.html`。返回 0 说明截图没内嵌成功，不算完成。
|
|
77
|
+
|
|
78
|
+
### 四、「完成」的定义：终端绿色 ≠ 做完
|
|
79
|
+
- ⚠️ **终端看到「全部通过」不等于工作完成**。真正的完成标志是三件事，缺一不可：① 确认测试中心在线（`/api/health`）；② 通过 API 触发可视化验收（`/api/run-visual`）；③ 确认报告里有内嵌截图（第三节的 grep > 0）。禁止看到终端绿色就告诉用户「做完了」——用户要的是能打开看的报告，不是终端日志。
|
|
80
|
+
|
|
81
|
+
### 五、失败排查顺序：先查基础设施
|
|
82
|
+
- ⚠️ **测试突然全部失败时，先检查外部依赖（数据库 / SSH 隧道、端口是否被抢）是否断开**，再改测试代码。禁止反复改测试代码去「绕过」基础设施问题。
|
|
83
|
+
|
|
84
|
+
### 六、等待策略：等元素，别等时间
|
|
57
85
|
- ⚠️ **页面 Loading 状态必须用元素可见性等待，禁止硬编码 `waitForTimeout`**。SPA 页面的正确等待顺序：先等关键元素出现（确认框架已挂载）→ 再等 Loading 状态消失（确认数据已返回）→ 最后才操作目标元素。顺序错了会出现「Loading 还没消失就点按钮 → 找不到 → 超时」。
|
|
58
86
|
|
|
87
|
+
## ⚠️ 截图规范
|
|
88
|
+
|
|
89
|
+
- ⚠️ **截图视口宽度统一按 4K（3840px 宽）设置，禁止用 1920px**。1920 宽对复杂内容看不全、看不清。用 agent-browser 时先 `agent-browser --cdp 9223 viewport 3840 <height>`（高度按内容给足，如 2400+），或全页截图并保证宽度 3840。
|
|
90
|
+
- ⚠️ **截图必须 `fullPage: true` 截完整页面**，不要只截视口的一部分。
|
|
91
|
+
- ⚠️ **截图中必须能看到当前页面 URL**（浏览器地址栏，或页面顶部叠加 URL 标注），确保证据可追溯。
|
|
92
|
+
- **保存到磁盘文件**（`page.screenshot({ path, fullPage: true })`），禁止只用内联展示的截图工具——内联的不落盘，用户无法在 Markdown / HTML 文档里查看。路径统一放 `docs/` 对应功能子目录，文件名用「编号 + 英文描述」（如 `01-login-page.png`）。
|
|
93
|
+
|
|
59
94
|
## Go 规则
|
|
60
95
|
|
|
61
96
|
- 值传递优先，软删除用 `gorm.DeletedAt`（禁止 `*time.Time`）。
|