@routerhub/agent-rules 1.5.120 → 1.5.121

package/AGENTS.base.md

@@ -80,6 +80,16 @@
 - ⚠️ **编写 HTML 页面或前端功能后，必须用测试环境的真实数据验证，禁止用虚构/mock 数据自测。** 虚构数据只能验证「代码不报错」，无法验证「功能在真实场景下正常工作」——真实数据会暴露边界情况（空值、超长文本、特殊字符、异常关联关系等），虚构数据碰不到这些。测试环境有真实数据时优先用测试环境；测试环境数据不足时，从生产环境脱敏导出。
 - ⚠️ **页面功能验证必须通过实际的页面交互操作来完成**（打开浏览器、点击按钮、填写表单、观察渲染结果），模拟真实用户操作路径。禁止只靠代码审查、单元测试断言或静态分析代替实际页面操作验证——用户最终是通过页面交互使用功能的，不是通过测试断言。能用浏览器手动操作的，就用浏览器手动操作一遍。
 
+## ⚠️ 用户视角测试铁律（先模拟用户，再写测试）
+
+- ⚠️ **写测试用例之前，必须先站在用户视角写出「用户操作路径」**：用户在哪个页面、依次点了什么、填了什么、提交后看到什么结果。测试代码必须逐条对应这条真实路径，禁止直接跳进接口层自己发明一套测法。
+- ⚠️ **凡用户能在页面上操作的功能，测试必须以页面交互驱动，禁止直接调 API 代替用户操作。** 页面驱动方式按可用性排序：真实浏览器手动操作（能手动就手动）→ Playwright E2E 模拟点击/填写/提交 → agent-browser 脚本化操作。API 直连只允许用于两类辅助动作：① **数据准备**（造前置数据）；② **结果核验**（查库/查接口确认数据落地正确）。禁止让 API 成为测试主线本身。
+- ⚠️ **判断标准：这个功能用户能不能在页面上操作？**
+  - 能 → 必须页面驱动，能模拟用户手动测试就手动；
+  - 不能（纯后端接口、定时任务、无页面入口的链路）→ 才允许用 API 冒烟测试，且断言必须基于运行时真实返回。
+- ⚠️ **为什么不能拿 API 代替页面操作：API 通 ≠ 用户功能可用。** 用户看到的界面和 API 之间隔着 JS 报错、参数拼错、字段绑定错误、权限拦截、渲染失败、Loading 时序等一整层风险，API 直连全部绕过——测了接口返回正确，不代表用户在页面上点按钮真的能用。
+- ⚠️ **典型反例（禁止）**：功能明明有页面，测试却只 `curl` 接口断言返回体；用脚本直接造数据、直接断言数据库，跳过了页面操作。**正确做法**：打开页面 → 模拟真实点击/填写/提交 → 断言页面渲染结果并截图 → 必要时查库核验数据落地。
+
 ## Git 规范
 
 - 分支用 Git Flow（`feature/`、`bugfix/`、`hotfix/`、`refactor/`、`chore/`、`docs/`、`test/`），英文小写中划线分隔。

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 所有对 @routerhub/agent-rules 的重大更改都会记录在这个文件中。
 
+## [1.5.121] - 2026-08-10
+
+### Added
+
+- 新增「用户视角测试铁律」（先模拟用户，再写测试）：写测试用例前必须先站在用户视角写出「用户操作路径」（用户在哪个页面、依次点了什么、填了什么、提交后看到什么），测试代码逐条对应真实路径。凡用户能在页面上操作的功能必须页面驱动——按可用性排序「能手动就手动 → Playwright E2E → agent-browser」——禁止直接调 API 代替用户操作；API 直连只允许用于数据准备和结果核验。原因：API 通 ≠ 用户功能可用，中间隔着 JS 报错、参数拼错、字段绑定、权限拦截、渲染失败等一整层风险。
+- 配套在 `tdd-workflow` Skill 第 3 步「测试先行」新增「用户视角先行」强制流程：① 先列用户操作路径清单再写测试代码；② 前端可操作功能必须页面驱动（Playwright / agent-browser），禁止 `curl` 代替；③ API 冒烟测试仅限无页面入口的纯后端接口；④ 能真实浏览器手动点一遍验证的先手动确认再写自动化用例。
+
 ## [1.5.114] - 2026-08-06
 
 ### Changed

package/package.json

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

package/rules/global.md

@@ -80,6 +80,16 @@ name: "通用规则"
 - ⚠️ **编写 HTML 页面或前端功能后，必须用测试环境的真实数据验证，禁止用虚构/mock 数据自测。** 虚构数据只能验证「代码不报错」，无法验证「功能在真实场景下正常工作」——真实数据会暴露边界情况（空值、超长文本、特殊字符、异常关联关系等），虚构数据碰不到这些。测试环境有真实数据时优先用测试环境；测试环境数据不足时，从生产环境脱敏导出。
 - ⚠️ **页面功能验证必须通过实际的页面交互操作来完成**（打开浏览器、点击按钮、填写表单、观察渲染结果），模拟真实用户操作路径。禁止只靠代码审查、单元测试断言或静态分析代替实际页面操作验证——用户最终是通过页面交互使用功能的，不是通过测试断言。能用浏览器手动操作的，就用浏览器手动操作一遍。
 
+## ⚠️ 用户视角测试铁律（先模拟用户，再写测试）
+
+- ⚠️ **写测试用例之前，必须先站在用户视角写出「用户操作路径」**：用户在哪个页面、依次点了什么、填了什么、提交后看到什么结果。测试代码必须逐条对应这条真实路径，禁止直接跳进接口层自己发明一套测法。
+- ⚠️ **凡用户能在页面上操作的功能，测试必须以页面交互驱动，禁止直接调 API 代替用户操作。** 页面驱动方式按可用性排序：真实浏览器手动操作（能手动就手动）→ Playwright E2E 模拟点击/填写/提交 → agent-browser 脚本化操作。API 直连只允许用于两类辅助动作：① **数据准备**（造前置数据）；② **结果核验**（查库/查接口确认数据落地正确）。禁止让 API 成为测试主线本身。
+- ⚠️ **判断标准：这个功能用户能不能在页面上操作？**
+  - 能 → 必须页面驱动，能模拟用户手动测试就手动；
+  - 不能（纯后端接口、定时任务、无页面入口的链路）→ 才允许用 API 冒烟测试，且断言必须基于运行时真实返回。
+- ⚠️ **为什么不能拿 API 代替页面操作：API 通 ≠ 用户功能可用。** 用户看到的界面和 API 之间隔着 JS 报错、参数拼错、字段绑定错误、权限拦截、渲染失败、Loading 时序等一整层风险，API 直连全部绕过——测了接口返回正确，不代表用户在页面上点按钮真的能用。
+- ⚠️ **典型反例（禁止）**：功能明明有页面，测试却只 `curl` 接口断言返回体；用脚本直接造数据、直接断言数据库，跳过了页面操作。**正确做法**：打开页面 → 模拟真实点击/填写/提交 → 断言页面渲染结果并截图 → 必要时查库核验数据落地。
+
 ## Git 规范
 
 - 分支用 Git Flow（`feature/`、`bugfix/`、`hotfix/`、`refactor/`、`chore/`、`docs/`、`test/`），英文小写中划线分隔。

package/skills/tdd-workflow/SKILL.md

@@ -51,6 +51,12 @@ description: >-
 - 覆盖：新建、编辑、删除、查看/搜索、状态流转、异常操作
 - 每条测试用例必须附带对应步骤的截图
 
+**⚠️ 用户视角先行（写用例前强制）**：
+1. **先列「用户操作路径清单」**：这个功能的用户（不是开发）在哪个页面、依次点了什么按钮、填了什么表单、提交后页面变成什么样。清单写出来之前，禁止动笔写测试代码。
+2. **前端可操作功能必须页面驱动**：用 Playwright E2E / agent-browser 模拟真实点击、填写、提交、等待渲染，断言页面上的可见结果（元素、状态、提示），并逐步骤截图。禁止用 `curl` 直接调 API 代替页面操作——API 通不等于用户点按钮能用，中间隔着 JS 报错、参数拼错、字段绑定、权限拦截、渲染失败等风险。
+3. **API 冒烟测试只给纯后端接口**：只有无页面入口的纯接口 / 定时任务链路，才允许写 `regression-api-smoke.js` 冒烟用例；且只能作为「数据准备」或「结果核验」的辅助手段，不能代替页面主验证。
+4. **能手动操作就手动**：编写测试时，凡能用真实浏览器手动点一遍验证的，先手动点一遍确认页面真实行为，再据此写自动化用例，不要凭空猜页面行为。
+
 ### 第 4 步：跑基线回归
 
 ⚠️ 改代码之前，先跑一次全量回归建立基线：