@routerhub/agent-rules 1.5.68 → 1.5.70

package/AGENTS.base.md

@@ -148,6 +148,7 @@ Closes #456
 - 所有新建 HTML 文档的文件名必须使用中文命名（如 `用户登录流程说明.html`），禁止使用英文或拼音文件名，方便团队成员一眼识别文档内容。
 - 所有新建 HTML 文档必须统一存放到项目根目录的 `docs/` 文件夹下，禁止散落在桌面、下载目录、临时目录或其他任意位置。如该文件夹不存在则先创建。
 - ⚠️ **编写 HTML 报告/文档时，每一段说明文字必须与其对应的截图、图片紧挨着放在一起（同一视觉区域内）**，禁止将说明文字集中放在页面顶部、图片全部堆在底部，导致读者需要上下翻页才能对照阅读。正确做法：每写完一段说明文字后，紧接着就放该段说明对应的图片，形成"说明 → 配图"的紧密组合，然后再写下一段说明和下一张图。
+- ⚠️ **HTML 报告必须以截图为主、文字为辅**：报告的核心内容是截图，文字仅作为截图的简要说明和补充。页面布局上截图应占主导地位（占据大部分版面），文字说明应精简扼要，禁止出现大段文字配少量截图的情况。读者应能通过翻阅截图快速了解全貌，无需阅读大量文字。
 
 ## 新需求与回归测试准入
 
@@ -254,6 +255,7 @@ Closes #456
 - 写完业务后执行 `pnpm run test:e2e:ui`，告知开发者对应测试用例名称；通过后打开 UI 供手动验证。
 - 端口被占用时自动切换新端口。
 - 自动化测试中，若 Mock 数据不影响业务逻辑验证，优先使用 Mock 数据代替真实接口调用，减少外部依赖和测试不稳定性。
+- ⚠️ **测试用例编写顺序：必须先写主流程，再写边界情况**。主流程（happy path）是最重要的，必须优先覆盖并确保通过；边界情况（异常输入、空值、超时、并发竞态等）重要性相对较低，在主流程全部覆盖完毕后再补充。禁止主流程还没写完就去写边界情况测试，也禁止因为花太多时间在边界情况上而遗漏主流程覆盖。
 
 ## 错误日志
 
@@ -342,9 +344,10 @@ function FieldTooltip({ text }: { text: string }) {
   1. **记录当前分支**：在切分支之前，先记录当前所在的功能分支名称（`git branch --show-current`），后续步骤需要用它切回来。
   2. **test 分支检查**：如果当前项目的 `test` 分支不存在，从主分支（`main` 或 `master`）创建 `test` 分支并推送到远程。
   3. **合并当前分支到 test**：将当前功能分支合并到 `test` 分支。
-  4. **部署 test 分支**：按当前项目自己的部署方式部署 `test` 分支（如 Cloud Run 部署、容器部署、npm publish 等）。
-  5. **发新版本**：按当前项目自己的发版规则发布新版本（如 `./release.sh`、自动递增版本号等）。
-  6. ⚠️ **切回原功能分支**：部署和发版全部完成后，必须立即切回步骤 1 记录的原功能分支（`git checkout <原分支名>`），确保 VS Code 当前所在的 Git 分支恢复到部署前的功能分支，而不是停留在 `test` 分支。如果忘记切回，用户后续的开发工作会在 `test` 分支上进行，违反「禁止直接在 test 分支上提交代码」的规则。
+  4. ⚠️ **推送 test 分支到远程**：合并完成后，必须立即将 `test` 分支推送到远程仓库（`git push origin test`），确保团队其他成员能看到 test 分支上的最新代码，避免远程 test 分支落后于本地。
+  5. **部署 test 分支**：按当前项目自己的部署方式部署 `test` 分支（如 Cloud Run 部署、容器部署、npm publish 等）。
+  6. **发新版本**：按当前项目自己的发版规则发布新版本（如 `./release.sh`、自动递增版本号等）。
+  7. ⚠️ **切回原功能分支**：部署和发版全部完成后，必须立即切回步骤 1 记录的原功能分支（`git checkout <原分支名>`），确保 VS Code 当前所在的 Git 分支恢复到部署前的功能分支，而不是停留在 `test` 分支。如果忘记切回，用户后续的开发工作会在 `test` 分支上进行，违反「禁止直接在 test 分支上提交代码」的规则。
 	- ⚠️ **部署必须自包含，禁止部署后人工补操作**：后端代码写完并部署时，所有依赖该代码的准备工作必须一并完成并通过自动化方式执行，不允许部署完成后再由人工手动执行命令补救。常见必须自动化的事项包括：
 	  - **数据库 migration**：涉及 schema 变更（新增表、字段、索引、约束等）时，必须同时编写 migration 脚本，并集成到部署流程中自动执行（如应用启动时自动 migrate、CI/CD 中跑 migrate 命令等），禁止部署后人工登数据库手动执行 DDL。
 	  - **数据迁移/回填脚本**：涉及存量数据清洗、转换、回填时，脚本必须随代码一起提交，并在部署流程中自动执行或在 PR 中明确写出执行计划。

package/package.json

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

package/rules/devops.md

@@ -13,9 +13,10 @@ outputName: "devops"
   1. **记录当前分支**：在切分支之前，先记录当前所在的功能分支名称（`git branch --show-current`），后续步骤需要用它切回来。
   2. **test 分支检查**：如果当前项目的 `test` 分支不存在，从主分支（`main` 或 `master`）创建 `test` 分支并推送到远程。
   3. **合并当前分支到 test**：将当前功能分支合并到 `test` 分支。
-  4. **部署 test 分支**：按当前项目自己的部署方式部署 `test` 分支（如 Cloud Run 部署、容器部署、npm publish 等）。
-  5. **发新版本**：按当前项目自己的发版规则发布新版本（如 `./release.sh`、自动递增版本号等）。
-  6. ⚠️ **切回原功能分支**：部署和发版全部完成后，必须立即切回步骤 1 记录的原功能分支（`git checkout <原分支名>`），确保 VS Code 当前所在的 Git 分支恢复到部署前的功能分支，而不是停留在 `test` 分支。如果忘记切回，用户后续的开发工作会在 `test` 分支上进行，违反「禁止直接在 test 分支上提交代码」的规则。
+  4. ⚠️ **推送 test 分支到远程**：合并完成后，必须立即将 `test` 分支推送到远程仓库（`git push origin test`），确保团队其他成员能看到 test 分支上的最新代码，避免远程 test 分支落后于本地。
+  5. **部署 test 分支**：按当前项目自己的部署方式部署 `test` 分支（如 Cloud Run 部署、容器部署、npm publish 等）。
+  6. **发新版本**：按当前项目自己的发版规则发布新版本（如 `./release.sh`、自动递增版本号等）。
+  7. ⚠️ **切回原功能分支**：部署和发版全部完成后，必须立即切回步骤 1 记录的原功能分支（`git checkout <原分支名>`），确保 VS Code 当前所在的 Git 分支恢复到部署前的功能分支，而不是停留在 `test` 分支。如果忘记切回，用户后续的开发工作会在 `test` 分支上进行，违反「禁止直接在 test 分支上提交代码」的规则。
 	- ⚠️ **部署必须自包含，禁止部署后人工补操作**：后端代码写完并部署时，所有依赖该代码的准备工作必须一并完成并通过自动化方式执行，不允许部署完成后再由人工手动执行命令补救。常见必须自动化的事项包括：
 	  - **数据库 migration**：涉及 schema 变更（新增表、字段、索引、约束等）时，必须同时编写 migration 脚本，并集成到部署流程中自动执行（如应用启动时自动 migrate、CI/CD 中跑 migrate 命令等），禁止部署后人工登数据库手动执行 DDL。
 	  - **数据迁移/回填脚本**：涉及存量数据清洗、转换、回填时，脚本必须随代码一起提交，并在部署流程中自动执行或在 PR 中明确写出执行计划。

package/rules/frontend.md

@@ -60,6 +60,7 @@ outputName: "frontend"
 - 写完业务后执行 `pnpm run test:e2e:ui`，告知开发者对应测试用例名称；通过后打开 UI 供手动验证。
 - 端口被占用时自动切换新端口。
 - 自动化测试中，若 Mock 数据不影响业务逻辑验证，优先使用 Mock 数据代替真实接口调用，减少外部依赖和测试不稳定性。
+- ⚠️ **测试用例编写顺序：必须先写主流程，再写边界情况**。主流程（happy path）是最重要的，必须优先覆盖并确保通过；边界情况（异常输入、空值、超时、并发竞态等）重要性相对较低，在主流程全部覆盖完毕后再补充。禁止主流程还没写完就去写边界情况测试，也禁止因为花太多时间在边界情况上而遗漏主流程覆盖。
 
 ## 错误日志
 

package/rules/global.md

@@ -150,6 +150,7 @@ Closes #456
 - 所有新建 HTML 文档的文件名必须使用中文命名（如 `用户登录流程说明.html`），禁止使用英文或拼音文件名，方便团队成员一眼识别文档内容。
 - 所有新建 HTML 文档必须统一存放到项目根目录的 `docs/` 文件夹下，禁止散落在桌面、下载目录、临时目录或其他任意位置。如该文件夹不存在则先创建。
 - ⚠️ **编写 HTML 报告/文档时，每一段说明文字必须与其对应的截图、图片紧挨着放在一起（同一视觉区域内）**，禁止将说明文字集中放在页面顶部、图片全部堆在底部，导致读者需要上下翻页才能对照阅读。正确做法：每写完一段说明文字后，紧接着就放该段说明对应的图片，形成"说明 → 配图"的紧密组合，然后再写下一段说明和下一张图。
+- ⚠️ **HTML 报告必须以截图为主、文字为辅**：报告的核心内容是截图，文字仅作为截图的简要说明和补充。页面布局上截图应占主导地位（占据大部分版面），文字说明应精简扼要，禁止出现大段文字配少量截图的情况。读者应能通过翻阅截图快速了解全貌，无需阅读大量文字。
 
 ## 新需求与回归测试准入