@routerhub/agent-rules 1.5.119 → 1.5.121
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 +14 -0
- package/CHANGELOG.md +7 -0
- package/package.json +1 -1
- package/rules/global.md +14 -0
- package/skills/create-pr/SKILL.md +25 -0
- package/skills/tdd-workflow/SKILL.md +6 -0
package/AGENTS.base.md
CHANGED
|
@@ -80,6 +80,16 @@
|
|
|
80
80
|
- ⚠️ **编写 HTML 页面或前端功能后，必须用测试环境的真实数据验证，禁止用虚构/mock 数据自测。** 虚构数据只能验证「代码不报错」，无法验证「功能在真实场景下正常工作」——真实数据会暴露边界情况（空值、超长文本、特殊字符、异常关联关系等），虚构数据碰不到这些。测试环境有真实数据时优先用测试环境；测试环境数据不足时，从生产环境脱敏导出。
|
|
81
81
|
- ⚠️ **页面功能验证必须通过实际的页面交互操作来完成**（打开浏览器、点击按钮、填写表单、观察渲染结果），模拟真实用户操作路径。禁止只靠代码审查、单元测试断言或静态分析代替实际页面操作验证——用户最终是通过页面交互使用功能的，不是通过测试断言。能用浏览器手动操作的，就用浏览器手动操作一遍。
|
|
82
82
|
|
|
83
|
+
## ⚠️ 用户视角测试铁律（先模拟用户，再写测试）
|
|
84
|
+
|
|
85
|
+
- ⚠️ **写测试用例之前，必须先站在用户视角写出「用户操作路径」**：用户在哪个页面、依次点了什么、填了什么、提交后看到什么结果。测试代码必须逐条对应这条真实路径，禁止直接跳进接口层自己发明一套测法。
|
|
86
|
+
- ⚠️ **凡用户能在页面上操作的功能，测试必须以页面交互驱动，禁止直接调 API 代替用户操作。** 页面驱动方式按可用性排序：真实浏览器手动操作（能手动就手动）→ Playwright E2E 模拟点击/填写/提交 → agent-browser 脚本化操作。API 直连只允许用于两类辅助动作：① **数据准备**（造前置数据）；② **结果核验**（查库/查接口确认数据落地正确）。禁止让 API 成为测试主线本身。
|
|
87
|
+
- ⚠️ **判断标准：这个功能用户能不能在页面上操作？**
|
|
88
|
+
- 能 → 必须页面驱动，能模拟用户手动测试就手动；
|
|
89
|
+
- 不能（纯后端接口、定时任务、无页面入口的链路）→ 才允许用 API 冒烟测试，且断言必须基于运行时真实返回。
|
|
90
|
+
- ⚠️ **为什么不能拿 API 代替页面操作：API 通 ≠ 用户功能可用。** 用户看到的界面和 API 之间隔着 JS 报错、参数拼错、字段绑定错误、权限拦截、渲染失败、Loading 时序等一整层风险，API 直连全部绕过——测了接口返回正确，不代表用户在页面上点按钮真的能用。
|
|
91
|
+
- ⚠️ **典型反例（禁止）**：功能明明有页面，测试却只 `curl` 接口断言返回体；用脚本直接造数据、直接断言数据库，跳过了页面操作。**正确做法**：打开页面 → 模拟真实点击/填写/提交 → 断言页面渲染结果并截图 → 必要时查库核验数据落地。
|
|
92
|
+
|
|
83
93
|
## Git 规范
|
|
84
94
|
|
|
85
95
|
- 分支用 Git Flow（`feature/`、`bugfix/`、`hotfix/`、`refactor/`、`chore/`、`docs/`、`test/`），英文小写中划线分隔。
|
|
@@ -95,6 +105,10 @@
|
|
|
95
105
|
- ⚠️ **截图必须通过 PR Description 编辑区直接上传（拖拽/粘贴/文件选择按钮），禁止走评论区 `input[type=file]` 上传后再搬运 CDN URL。** 原因：PR Description 编辑区本身支持图片拖拽上传、自动转为 `` 内嵌，一步到位；走评论区上传需要多一步「提交评论 → 复制 URL → 粘贴到 Description」，产生的临时图片评论会留在 PR 对话里干扰 reviewer 阅读，且多了一步手动搬运、容易出错。
|
|
96
106
|
- ⚠️ 创建 PR 使用 `/create-pr` skill（自动生成中文内容 + 效果截图 + CDN 上传）。
|
|
97
107
|
- ⚠️ **创建 PR 后，必须先检查与主分支（默认分支）是否有冲突**：用 `gh pr view <PR> --json mergeable -q .mergeable` 检查（`MERGEABLE`=无冲突可合并，`CONFLICTING`=存在冲突，`UNKNOWN`=GitHub 尚未判定，稍后复查）。若存在冲突，必须先解决冲突再交付 review——`git merge origin/main`（或 `git rebase origin/main`）→ 解决冲突文件 → 测试通过 → 推送，确保 PR 处于可合并状态，禁止把带冲突的 PR 抛给 reviewer。
|
|
108
|
+
- ⚠️ **创建 PR 后，除冲突检查外还必须检查 GitHub 静态编译是否通过，通过后发新版本**，三步收尾缺一不可：
|
|
109
|
+
1. **与主分支冲突检查**：按上一条规则执行（`gh pr view <PR> --json mergeable -q .mergeable`），有冲突必须先解决。
|
|
110
|
+
2. **GitHub 静态编译检查**：用 `gh pr checks <PR>` 查看 CI 检查状态（`success`=通过，`failure`=失败，`pending`=进行中）。存在失败项时，必须定位失败根因、修改代码并重新推送，直到全部通过，禁止把静态编译未通过的 PR 抛给 reviewer。
|
|
111
|
+
3. **发新版本**：PR 合并后按项目发布流程发布新版本（本项目统一执行根目录 `./release.sh`，自动完成 patch 版本号 +1、更新 package.json、`git commit`/`push`、打 tag、`npm publish`）。
|
|
98
112
|
- ⚠️ **私有仓库的 PR/Issue 正文中插入截图，禁止使用 `raw.githubusercontent.com` 链接，必须使用 `github.com/OWNER/REPO/blob/BRANCH/path?raw=true` 格式。** 原因：`raw.githubusercontent.com` 不识别 GitHub 网页端的登录态（session cookie），GitHub 渲染 PR/Issue 正文图片时走的是 camo 图片代理服务器端匿名拉取——对私有仓库该链接返回 404，导致图片框显示为普通文字链接而非图片；`github.com/.../blob/...?raw=true` 走的是 github.com 主域名，能通过登录态正确鉴权，图片才能正常渲染。凡是「先 `git add -f` 把截图提交进 `screenshots/` 目录、再在 PR 描述里用 Markdown 引用」的流程，图片链接一律拼接为后一种格式。
|
|
99
113
|
|
|
100
114
|
## 安全
|
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,13 @@
|
|
|
2
2
|
|
|
3
3
|
所有对 @routerhub/agent-rules 的重大更改都会记录在这个文件中。
|
|
4
4
|
|
|
5
|
+
## [1.5.121] - 2026-08-10
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
|
|
9
|
+
- 新增「用户视角测试铁律」（先模拟用户，再写测试）：写测试用例前必须先站在用户视角写出「用户操作路径」（用户在哪个页面、依次点了什么、填了什么、提交后看到什么），测试代码逐条对应真实路径。凡用户能在页面上操作的功能必须页面驱动——按可用性排序「能手动就手动 → Playwright E2E → agent-browser」——禁止直接调 API 代替用户操作；API 直连只允许用于数据准备和结果核验。原因：API 通 ≠ 用户功能可用，中间隔着 JS 报错、参数拼错、字段绑定、权限拦截、渲染失败等一整层风险。
|
|
10
|
+
- 配套在 `tdd-workflow` Skill 第 3 步「测试先行」新增「用户视角先行」强制流程：① 先列用户操作路径清单再写测试代码；② 前端可操作功能必须页面驱动（Playwright / agent-browser），禁止 `curl` 代替；③ API 冒烟测试仅限无页面入口的纯后端接口；④ 能真实浏览器手动点一遍验证的先手动确认再写自动化用例。
|
|
11
|
+
|
|
5
12
|
## [1.5.114] - 2026-08-06
|
|
6
13
|
|
|
7
14
|
### Changed
|
package/package.json
CHANGED
package/rules/global.md
CHANGED
|
@@ -80,6 +80,16 @@ name: "通用规则"
|
|
|
80
80
|
- ⚠️ **编写 HTML 页面或前端功能后，必须用测试环境的真实数据验证，禁止用虚构/mock 数据自测。** 虚构数据只能验证「代码不报错」，无法验证「功能在真实场景下正常工作」——真实数据会暴露边界情况（空值、超长文本、特殊字符、异常关联关系等），虚构数据碰不到这些。测试环境有真实数据时优先用测试环境；测试环境数据不足时，从生产环境脱敏导出。
|
|
81
81
|
- ⚠️ **页面功能验证必须通过实际的页面交互操作来完成**（打开浏览器、点击按钮、填写表单、观察渲染结果），模拟真实用户操作路径。禁止只靠代码审查、单元测试断言或静态分析代替实际页面操作验证——用户最终是通过页面交互使用功能的，不是通过测试断言。能用浏览器手动操作的，就用浏览器手动操作一遍。
|
|
82
82
|
|
|
83
|
+
## ⚠️ 用户视角测试铁律（先模拟用户，再写测试）
|
|
84
|
+
|
|
85
|
+
- ⚠️ **写测试用例之前，必须先站在用户视角写出「用户操作路径」**：用户在哪个页面、依次点了什么、填了什么、提交后看到什么结果。测试代码必须逐条对应这条真实路径，禁止直接跳进接口层自己发明一套测法。
|
|
86
|
+
- ⚠️ **凡用户能在页面上操作的功能，测试必须以页面交互驱动，禁止直接调 API 代替用户操作。** 页面驱动方式按可用性排序：真实浏览器手动操作（能手动就手动）→ Playwright E2E 模拟点击/填写/提交 → agent-browser 脚本化操作。API 直连只允许用于两类辅助动作：① **数据准备**（造前置数据）；② **结果核验**（查库/查接口确认数据落地正确）。禁止让 API 成为测试主线本身。
|
|
87
|
+
- ⚠️ **判断标准：这个功能用户能不能在页面上操作？**
|
|
88
|
+
- 能 → 必须页面驱动，能模拟用户手动测试就手动；
|
|
89
|
+
- 不能（纯后端接口、定时任务、无页面入口的链路）→ 才允许用 API 冒烟测试，且断言必须基于运行时真实返回。
|
|
90
|
+
- ⚠️ **为什么不能拿 API 代替页面操作：API 通 ≠ 用户功能可用。** 用户看到的界面和 API 之间隔着 JS 报错、参数拼错、字段绑定错误、权限拦截、渲染失败、Loading 时序等一整层风险，API 直连全部绕过——测了接口返回正确，不代表用户在页面上点按钮真的能用。
|
|
91
|
+
- ⚠️ **典型反例（禁止）**：功能明明有页面，测试却只 `curl` 接口断言返回体；用脚本直接造数据、直接断言数据库，跳过了页面操作。**正确做法**：打开页面 → 模拟真实点击/填写/提交 → 断言页面渲染结果并截图 → 必要时查库核验数据落地。
|
|
92
|
+
|
|
83
93
|
## Git 规范
|
|
84
94
|
|
|
85
95
|
- 分支用 Git Flow（`feature/`、`bugfix/`、`hotfix/`、`refactor/`、`chore/`、`docs/`、`test/`），英文小写中划线分隔。
|
|
@@ -95,6 +105,10 @@ name: "通用规则"
|
|
|
95
105
|
- ⚠️ **截图必须通过 PR Description 编辑区直接上传（拖拽/粘贴/文件选择按钮），禁止走评论区 `input[type=file]` 上传后再搬运 CDN URL。** 原因：PR Description 编辑区本身支持图片拖拽上传、自动转为 `` 内嵌，一步到位；走评论区上传需要多一步「提交评论 → 复制 URL → 粘贴到 Description」，产生的临时图片评论会留在 PR 对话里干扰 reviewer 阅读，且多了一步手动搬运、容易出错。
|
|
96
106
|
- ⚠️ 创建 PR 使用 `/create-pr` skill（自动生成中文内容 + 效果截图 + CDN 上传）。
|
|
97
107
|
- ⚠️ **创建 PR 后，必须先检查与主分支（默认分支）是否有冲突**：用 `gh pr view <PR> --json mergeable -q .mergeable` 检查（`MERGEABLE`=无冲突可合并，`CONFLICTING`=存在冲突，`UNKNOWN`=GitHub 尚未判定，稍后复查）。若存在冲突，必须先解决冲突再交付 review——`git merge origin/main`（或 `git rebase origin/main`）→ 解决冲突文件 → 测试通过 → 推送，确保 PR 处于可合并状态，禁止把带冲突的 PR 抛给 reviewer。
|
|
108
|
+
- ⚠️ **创建 PR 后，除冲突检查外还必须检查 GitHub 静态编译是否通过，通过后发新版本**，三步收尾缺一不可：
|
|
109
|
+
1. **与主分支冲突检查**：按上一条规则执行（`gh pr view <PR> --json mergeable -q .mergeable`），有冲突必须先解决。
|
|
110
|
+
2. **GitHub 静态编译检查**：用 `gh pr checks <PR>` 查看 CI 检查状态（`success`=通过，`failure`=失败，`pending`=进行中）。存在失败项时，必须定位失败根因、修改代码并重新推送，直到全部通过，禁止把静态编译未通过的 PR 抛给 reviewer。
|
|
111
|
+
3. **发新版本**：PR 合并后按项目发布流程发布新版本（本项目统一执行根目录 `./release.sh`，自动完成 patch 版本号 +1、更新 package.json、`git commit`/`push`、打 tag、`npm publish`）。
|
|
98
112
|
- ⚠️ **私有仓库的 PR/Issue 正文中插入截图，禁止使用 `raw.githubusercontent.com` 链接，必须使用 `github.com/OWNER/REPO/blob/BRANCH/path?raw=true` 格式。** 原因：`raw.githubusercontent.com` 不识别 GitHub 网页端的登录态（session cookie），GitHub 渲染 PR/Issue 正文图片时走的是 camo 图片代理服务器端匿名拉取——对私有仓库该链接返回 404，导致图片框显示为普通文字链接而非图片；`github.com/.../blob/...?raw=true` 走的是 github.com 主域名，能通过登录态正确鉴权，图片才能正常渲染。凡是「先 `git add -f` 把截图提交进 `screenshots/` 目录、再在 PR 描述里用 Markdown 引用」的流程，图片链接一律拼接为后一种格式。
|
|
99
113
|
|
|
100
114
|
## 安全
|
|
@@ -94,6 +94,30 @@ gh pr create \
|
|
|
94
94
|
- 关联 issue：如有
|
|
95
95
|
- Milestone：如有
|
|
96
96
|
|
|
97
|
+
### 7. 创建 PR 后收尾检查（冲突 + 静态编译 + 发版本）
|
|
98
|
+
|
|
99
|
+
⚠️ 创建 PR 后，三步收尾缺一不可，禁止创建完 PR 就直接抛给 reviewer。
|
|
100
|
+
|
|
101
|
+
**① 与主分支冲突检查**：
|
|
102
|
+
```bash
|
|
103
|
+
gh pr view <PR> --json mergeable -q .mergeable
|
|
104
|
+
```
|
|
105
|
+
- `MERGEABLE`=无冲突可合并
|
|
106
|
+
- `CONFLICTING`=存在冲突：`git merge origin/$DEFAULT_BRANCH`（或 `git rebase origin/$DEFAULT_BRANCH`）→ 解决冲突文件 → 测试通过 → 推送
|
|
107
|
+
- `UNKNOWN`=GitHub 尚未判定，稍后复查
|
|
108
|
+
|
|
109
|
+
**② GitHub 静态编译检查**：
|
|
110
|
+
```bash
|
|
111
|
+
gh pr checks <PR>
|
|
112
|
+
```
|
|
113
|
+
- `success`=通过，`failure`=失败，`pending`=进行中
|
|
114
|
+
- 存在失败项：定位失败根因 → 修改代码 → 重新推送，直到全部通过
|
|
115
|
+
- 禁止把静态编译未通过的 PR 抛给 reviewer
|
|
116
|
+
|
|
117
|
+
**③ 发新版本**：
|
|
118
|
+
- PR 合并后按项目发布流程发布新版本
|
|
119
|
+
- 本项目统一执行根目录 `./release.sh`（自动完成 patch 版本号 +1、更新 package.json、`git commit`/`push`、打 tag、`npm publish`）
|
|
120
|
+
|
|
97
121
|
## 重要规则
|
|
98
122
|
|
|
99
123
|
- ⚠️ 一个 PR 只做一件事
|
|
@@ -101,5 +125,6 @@ gh pr create \
|
|
|
101
125
|
- ⚠️ 必须附截图作为可视化证据
|
|
102
126
|
- ⚠️ 截图禁止提交到 Git 仓库
|
|
103
127
|
- ⚠️ PR 截图直接内嵌在 Description 正文中（Markdown 图片语法）
|
|
128
|
+
- ⚠️ 创建 PR 后必须做三步收尾：冲突检查 → 静态编译检查 → PR 合并后发新版本（见步骤 7）
|
|
104
129
|
- 先开 Draft PR，准备好再标记 Ready for review
|
|
105
130
|
- 作者不能 Approve 自己的 PR
|
|
@@ -51,6 +51,12 @@ description: >-
|
|
|
51
51
|
- 覆盖：新建、编辑、删除、查看/搜索、状态流转、异常操作
|
|
52
52
|
- 每条测试用例必须附带对应步骤的截图
|
|
53
53
|
|
|
54
|
+
**⚠️ 用户视角先行（写用例前强制）**：
|
|
55
|
+
1. **先列「用户操作路径清单」**：这个功能的用户（不是开发）在哪个页面、依次点了什么按钮、填了什么表单、提交后页面变成什么样。清单写出来之前，禁止动笔写测试代码。
|
|
56
|
+
2. **前端可操作功能必须页面驱动**：用 Playwright E2E / agent-browser 模拟真实点击、填写、提交、等待渲染，断言页面上的可见结果（元素、状态、提示），并逐步骤截图。禁止用 `curl` 直接调 API 代替页面操作——API 通不等于用户点按钮能用，中间隔着 JS 报错、参数拼错、字段绑定、权限拦截、渲染失败等风险。
|
|
57
|
+
3. **API 冒烟测试只给纯后端接口**：只有无页面入口的纯接口 / 定时任务链路，才允许写 `regression-api-smoke.js` 冒烟用例；且只能作为「数据准备」或「结果核验」的辅助手段，不能代替页面主验证。
|
|
58
|
+
4. **能手动操作就手动**：编写测试时，凡能用真实浏览器手动点一遍验证的，先手动点一遍确认页面真实行为，再据此写自动化用例，不要凭空猜页面行为。
|
|
59
|
+
|
|
54
60
|
### 第 4 步：跑基线回归
|
|
55
61
|
|
|
56
62
|
⚠️ 改代码之前，先跑一次全量回归建立基线：
|