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