@routerhub/agent-rules 1.5.91 → 1.5.93

package/AGENTS.base.md

@@ -47,6 +47,15 @@
 - 测试描述、断言使用中文。测试用例先主流程再边界情况。
 - ⚠️ 代码中出现晦涩难懂的技术名词（如 X-Request-ID、反向代理、CORS、JWT、CSRF、幂等、熔断、降级等）时，必须附加中文注解。注解分两层：（1）先说明该名词是什么功能、解决什么问题；（2）再解释其中特殊因子/字段的具体作用。目的是让不熟悉该领域的人也能看懂代码逻辑，不要求已有背景知识。
 
+## ⚠️ E2E 回归测试铁律
+
+- ⚠️ **新增测试用例必须同步改两个文件**：Runner 脚本（登记用例 + 验收详情）和报告页面（数据 + 下拉选项 + 映射 + ID 常量），缺一不可。只改一处会导致测试中心看不到新用例。
+- ⚠️ **Playwright 截图必须用 `{ mode: 'on', fullPage: true }`**，禁止用默认的 `'only-on-failure'`。后者意味着测试全过时一张图都没有，报告里全是空白的。
+- ⚠️ **必须从正确的子目录执行测试**，禁止从项目根目录直接跑。根目录跑会导致配置文件中的相对路径（如 `.env`）解析错误，拿到错误的端口号。
+- ⚠️ **终端看到「全部通过」≠ 工作完成**。真正的完成标志是三件事：① 确认测试中心在线；② 通过 API 触发可视化验收；③ 确认报告里有截图。禁止看到终端绿色就告诉用户「做完了」——用户要的是能打开看的报告，不是终端日志。
+- ⚠️ **测试突然全部失败时，先检查外部依赖（数据库/SSH 隧道等）是否断开**，再改测试代码。禁止反复改测试代码去「绕过」基础设施问题。
+- ⚠️ **页面 Loading 状态必须用元素可见性等待，禁止硬编码 `waitForTimeout`**。SPA 页面的正确等待顺序：先等关键元素出现（确认框架已挂载）→ 再等 Loading 状态消失（确认数据已返回）→ 最后才操作目标元素。顺序错了会出现「Loading 还没消失就点按钮 → 找不到 → 超时」。
+
 ## Go 规则
 
 - 值传递优先，软删除用 `gorm.DeletedAt`（禁止 `*time.Time`）。

package/package.json

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

package/rules/global.md

@@ -47,6 +47,15 @@ name: "通用规则"
 - 测试描述、断言使用中文。测试用例先主流程再边界情况。
 - ⚠️ 代码中出现晦涩难懂的技术名词（如 X-Request-ID、反向代理、CORS、JWT、CSRF、幂等、熔断、降级等）时，必须附加中文注解。注解分两层：（1）先说明该名词是什么功能、解决什么问题；（2）再解释其中特殊因子/字段的具体作用。目的是让不熟悉该领域的人也能看懂代码逻辑，不要求已有背景知识。
 
+## ⚠️ E2E 回归测试铁律
+
+- ⚠️ **新增测试用例必须同步改两个文件**：Runner 脚本（登记用例 + 验收详情）和报告页面（数据 + 下拉选项 + 映射 + ID 常量），缺一不可。只改一处会导致测试中心看不到新用例。
+- ⚠️ **Playwright 截图必须用 `{ mode: 'on', fullPage: true }`**，禁止用默认的 `'only-on-failure'`。后者意味着测试全过时一张图都没有，报告里全是空白的。
+- ⚠️ **必须从正确的子目录执行测试**，禁止从项目根目录直接跑。根目录跑会导致配置文件中的相对路径（如 `.env`）解析错误，拿到错误的端口号。
+- ⚠️ **终端看到「全部通过」≠ 工作完成**。真正的完成标志是三件事：① 确认测试中心在线；② 通过 API 触发可视化验收；③ 确认报告里有截图。禁止看到终端绿色就告诉用户「做完了」——用户要的是能打开看的报告，不是终端日志。
+- ⚠️ **测试突然全部失败时，先检查外部依赖（数据库/SSH 隧道等）是否断开**，再改测试代码。禁止反复改测试代码去「绕过」基础设施问题。
+- ⚠️ **页面 Loading 状态必须用元素可见性等待，禁止硬编码 `waitForTimeout`**。SPA 页面的正确等待顺序：先等关键元素出现（确认框架已挂载）→ 再等 Loading 状态消失（确认数据已返回）→ 最后才操作目标元素。顺序错了会出现「Loading 还没消失就点按钮 → 找不到 → 超时」。
+
 ## Go 规则
 
 - 值传递优先，软删除用 `gorm.DeletedAt`（禁止 `*time.Time`）。

package/skills/deploy-test/SKILL.md

@@ -6,7 +6,7 @@ description: >-
   「帮我部署」「帮我发布」「帮我上线」「部署一下」「发布一下」「上线一下」「部署吧」「发布吧」「上线吧」「部署了」「发布了」「上线了」「搞部署」「做部署」「弄部署」。
   「打测试」「打test」「打一下测试」「打个测试包」「打包测试」「打包到测试」「发版测试」「发版到测试」。
   「部署」「发布」「上线」单独说且上下文在讨论测试环境时也应触发。
-  自动完成：记录当前分支→合并到test→推送→部署→发版→切回原分支。
+  自动完成：记录当前分支→提交并推送当前分支→合并到test→推送→部署→发版→切回原分支。
 ---
 
 # 部署测试环境
@@ -17,7 +17,7 @@ description: >-
 
 ## 🚨 铁律（违反即错误）
 
-- ⚠️ 部署测试环境**唯一正确流程**：当前功能分支 → 合并到 test → 推送 test → 触发部署 → 切回原分支。
+- ⚠️ 部署测试环境**唯一正确流程**：当前功能分支 → 提交并推送当前分支 → 合并到 test → 推送 test → 触发部署 → 切回原分支。
 - ⚠️ **绝对禁止**跳过合并步骤、直接在功能分支上部署、或往 test 分支直接提交代码。
 - ⚠️ 每一步必须执行完毕并确认成功后才能进入下一步，不可并行或跳过。
 
@@ -30,7 +30,17 @@ ORIGINAL_BRANCH=$(git branch --show-current)
 echo "当前分支: $ORIGINAL_BRANCH"
 ```
 
-### 2. test 分支检查
+### 2. 提交当前分支并推送远程
+
+⚠️ 合并前必须确保当前分支所有改动已提交并推送，避免遗漏代码。
+
+```bash
+git add -A
+git commit -m "..."  # 使用有意义的提交信息
+git push origin "$ORIGINAL_BRANCH"
+```
+
+### 3. test 分支检查
 
 如果 `test` 分支不存在，从主分支创建：
 
@@ -43,29 +53,31 @@ if ! git show-ref --verify --quiet refs/heads/test; then
 fi
 ```
 
-### 3. 合并当前分支到 test
+### 4. 合并当前分支到 test
+
+⚠️ 合并发生冲突时，以当前功能分支的内容为准（`-X theirs`）。因为当前分支的代码是刚改的最新版本，test 分支上的旧版本直接覆盖即可。
 
 ```bash
 git checkout test
 git pull origin test
-git merge "$ORIGINAL_BRANCH"
+git merge "$ORIGINAL_BRANCH" -X theirs
 ```
 
-### 4. 推送 test 分支
+### 5. 推送 test 分支
 
 ```bash
 git push origin test
 ```
 
-### 5. 部署 test 分支
+### 6. 部署 test 分支
 
 按项目自己的部署方式执行（Cloud Run / 容器 / npm publish 等）。
 
-### 6. 发新版本
+### 7. 发新版本
 
 按项目发版规则执行（如 `./release.sh`）。
 
-### 7. 切回原功能分支
+### 8. 切回原功能分支
 
 ```bash
 git checkout "$ORIGINAL_BRANCH"
@@ -76,5 +88,6 @@ git checkout "$ORIGINAL_BRANCH"
 - ⚠️ 推送 test 后必须立即执行 `git push origin test`
 - ⚠️ 部署完成后必须立即切回原功能分支
 - ⚠️ 部署必须自包含：migration、配置变更、依赖检查全部脚本化自动执行，禁止部署后人工补操作
+- ⚠️ 合并到 test 发生冲突时，必须用 `-X theirs`（以当前功能分支为准），因为当前分支是最新代码，test 旧版本直接覆盖即可。
 - 禁止直接往 test 分支提交代码
 - 敏感信息（密钥、Token）必须从 Nacos 配置中心拉取，不得写死