@routerhub/agent-rules 1.5.70 → 1.5.72

package/AGENTS.base.md

@@ -120,13 +120,19 @@ Closes #456
   3. 对于有道理的问题，直接修改代码、提交并推送到该 PR 分支。
   4. ⚠️ **强制步骤：修改代码并推送后，必须在 GitHub PR 页面上逐条点击 Resolve conversation。** 此步骤不可跳过——即使已回复评论、已推送修复代码，只要未点 Resolve，该条评论仍处于”未解决”状态，reviewer 无法判断是否已处理完毕。每修复一条，立即 Resolve 一条，不要等所有问题修完再批量操作。
   5. 所有问题处理完毕后，重新请求 Copilot review。
-  6. 重复以上步骤，直到 Copilot review 不再提出新问题为止。
+  6. 重复以上步骤，直到满足以下任一终止条件为止。
 - 每一条 Copilot review 评论处理完毕后，必须点击 **Resolve conversation**，不能只回复不 Resolve。不点 Resolve 会导致该评论一直处于未解决状态，无法判断是否已完成处理。
 - 每次修改后提交的 commit 信息必须中文，格式：`修复 Copilot review 问题：[简要描述]`。
 - 如果 Copilot review 连续两轮提出同一问题但实际已修复或无道理，需在 PR 评论中明确说明原因并直接 Resolve，不再反复修改。
+- ⚠️ **循环终止条件（满足任意一条即停止）**：
+  1. **无新问题**：Copilot review 本轮未提出任何新问题 → 自然终止，循环结束。
+  2. **仅剩可忽略级别建议**：本轮 Copilot review 提出的所有问题均标注了 `nit:`、`optional:`、`question:` 或建议将配置项写入 `.env` 等可忽略类型，无任何 `Request changes` 级别的问题 → 逐条回复说明原因并 Resolve，然后终止循环，无需再请求新一轮 review。
+  3. **衰减到底**：连续两轮 review 的新问题数量均 ≤ 2 个，且均为风格偏好或可争议建议，无实质 bug 或安全风险 → 逐条处理并 Resolve，然后终止循环。
+  4. **硬上限**：循环已达到 5 轮仍无法满足上述条件 → 暂停循环，弹出通知告知用户当前状态（已跑 N 轮、剩余未解决问题数量及摘要），由用户决定是否继续。禁止在用户未确认的情况下自动跑第 6 轮。
+  - **核心原则：Copilot review 的目标是发现真正的代码缺陷，不是追求零评论。** 经过几轮修复后，剩余的 nit/optional 级别建议或可争议的风格偏好属于正常现象，直接标记处理即可，不应无限追逐”零评论”状态。
 - PR 图片文件检查：在 Copilot review 循环中（建议放在开始处理 review 问题之前，或所有 review 问题处理完毕之后），必须检查当前 PR 中是否存在未被引用的图片文件（PNG、JPG、JPEG、GIF、SVG、WebP 等）。检查方式：搜索代码库中是否有任何文件引用了该图片的文件名或路径，若没有任何引用 → 该图片为冗余文件。处理方式：若图片内容需要保留（如截图佐证），则将其转为 base64 data URI 内嵌到对应的 HTML 文档中，然后删除原图片文件；若图片内容无需保留，则直接删除。处理完毕后提交并推送。
 - 可忽略的 review 建议：如果 Copilot review 建议将配置项（API 地址、数据库连接、第三方服务地址等）写入 `.env` 文件，必须直接忽略并在评论中回复说明原因后 Resolve。说明内容：「本项目 `.env` 仅允许配置端口号（如 `PORT`、`API_PORT`），其余配置项一律写死在代码中，敏感信息统一放入 Nacos 配置中心，不放 `.env`。」
-- ⚠️ **强制步骤：重新请求 Copilot review 后，必须主动检查 Copilot 是否已回复。** 不能发完评论就停止等待。检查方式：使用 `gh api` 拉取 PR 的 reviews 和 comments，对比上次已知的最新 review 时间戳。检查频率：每次重新请求 review 后，约 2–3 分钟后主动检查一次；若 Copilot 已生成新 review 则立即进入下一轮处理；若尚未回复，再等 2–3 分钟后再次检查。不可无限等待，最多检查 3 次（约 6–9 分钟），若仍无回复则告知用户当前状态。
+- ⚠️ **强制步骤：重新请求 Copilot review 后，必须主动检查 Copilot 是否已回复。** 不能发完评论就停止等待。检查方式：使用 `gh api` 拉取 PR 的 reviews 和 comments，对比上次已知的最新 review 时间戳。检查频率：每次重新请求 review 后，约 2–3 分钟后主动检查一次；若 Copilot 已生成新 review 则立即进入下一轮处理；若尚未回复，再等 2–3 分钟后再次检查。⚠️ **这里的「最多检查 3 次」仅指每轮 review 请求后的轮询等待次数上限（约 6–9 分钟），与 review 循环的迭代轮数无关——循环轮数由上方终止条件控制，不受此限制。** 等待超时后若仍无回复，告知用户当前状态。
 
 ## 安全
 
@@ -256,6 +262,14 @@ Closes #456
 - 端口被占用时自动切换新端口。
 - 自动化测试中，若 Mock 数据不影响业务逻辑验证，优先使用 Mock 数据代替真实接口调用，减少外部依赖和测试不稳定性。
 - ⚠️ **测试用例编写顺序：必须先写主流程，再写边界情况**。主流程（happy path）是最重要的，必须优先覆盖并确保通过；边界情况（异常输入、空值、超时、并发竞态等）重要性相对较低，在主流程全部覆盖完毕后再补充。禁止主流程还没写完就去写边界情况测试，也禁止因为花太多时间在边界情况上而遗漏主流程覆盖。
+- ⚠️ **测试用例必须模拟真实用户的操作流程，禁止只写「XX 可见」类表面检查**。测试用例清单中的每一条主流程用例，必须以真实用户的操作路径来编写：打开页面 → 查看初始状态 → 点击按钮/填写表单 → 提交/保存 → 验证结果页面是否正确展示。核心覆盖场景必须包括：
+  - **新建**：从入口进入 → 填写表单 → 提交 → 在列表/详情页验证新建数据是否正确显示，截图每步关键状态。
+  - **编辑**：从列表/详情进入编辑 → 修改字段 → 保存 → 验证修改后的数据在页面上是否正确回显，截图前后对比。
+  - **删除**：触发删除 → 确认弹窗 → 确认后验证列表/页面中该数据已消失，截图删除前列表和删除后列表对比。
+  - **查看/搜索**：进入列表页 → 使用搜索/筛选 → 验证搜索结果是否符合筛选条件，截图搜索结果。
+  - **状态流转**：如果业务有状态变更（如审核、启用/禁用、支付等），必须覆盖每个状态流转的操作和页面反馈，截图每个状态下的页面展示。
+  - **异常操作**：空表单提交、超长文本输入、非法字符、重复提交等用户可能触发的异常场景，截图错误提示和页面状态。
+- ⚠️ **每一条测试用例必须附带对应步骤的截图，缺一不可**。测试用例清单中每条用例必须写出预期要截哪些图（如「截图1：新建表单填写完成」「截图2：提交成功后列表页新数据出现」），实际执行时每张截图都必须产出并嵌入 HTML 报告。禁止只写操作步骤而不产出对应截图，禁止用「已验证通过」等文字描述代替截图。
 
 ## 错误日志
 

package/package.json

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

package/rules/frontend.md

@@ -61,6 +61,14 @@ outputName: "frontend"
 - 端口被占用时自动切换新端口。
 - 自动化测试中，若 Mock 数据不影响业务逻辑验证，优先使用 Mock 数据代替真实接口调用，减少外部依赖和测试不稳定性。
 - ⚠️ **测试用例编写顺序：必须先写主流程，再写边界情况**。主流程（happy path）是最重要的，必须优先覆盖并确保通过；边界情况（异常输入、空值、超时、并发竞态等）重要性相对较低，在主流程全部覆盖完毕后再补充。禁止主流程还没写完就去写边界情况测试，也禁止因为花太多时间在边界情况上而遗漏主流程覆盖。
+- ⚠️ **测试用例必须模拟真实用户的操作流程，禁止只写「XX 可见」类表面检查**。测试用例清单中的每一条主流程用例，必须以真实用户的操作路径来编写：打开页面 → 查看初始状态 → 点击按钮/填写表单 → 提交/保存 → 验证结果页面是否正确展示。核心覆盖场景必须包括：
+  - **新建**：从入口进入 → 填写表单 → 提交 → 在列表/详情页验证新建数据是否正确显示，截图每步关键状态。
+  - **编辑**：从列表/详情进入编辑 → 修改字段 → 保存 → 验证修改后的数据在页面上是否正确回显，截图前后对比。
+  - **删除**：触发删除 → 确认弹窗 → 确认后验证列表/页面中该数据已消失，截图删除前列表和删除后列表对比。
+  - **查看/搜索**：进入列表页 → 使用搜索/筛选 → 验证搜索结果是否符合筛选条件，截图搜索结果。
+  - **状态流转**：如果业务有状态变更（如审核、启用/禁用、支付等），必须覆盖每个状态流转的操作和页面反馈，截图每个状态下的页面展示。
+  - **异常操作**：空表单提交、超长文本输入、非法字符、重复提交等用户可能触发的异常场景，截图错误提示和页面状态。
+- ⚠️ **每一条测试用例必须附带对应步骤的截图，缺一不可**。测试用例清单中每条用例必须写出预期要截哪些图（如「截图1：新建表单填写完成」「截图2：提交成功后列表页新数据出现」），实际执行时每张截图都必须产出并嵌入 HTML 报告。禁止只写操作步骤而不产出对应截图，禁止用「已验证通过」等文字描述代替截图。
 
 ## 错误日志
 

package/rules/global.md

@@ -122,13 +122,19 @@ Closes #456
   3. 对于有道理的问题，直接修改代码、提交并推送到该 PR 分支。
   4. ⚠️ **强制步骤：修改代码并推送后，必须在 GitHub PR 页面上逐条点击 Resolve conversation。** 此步骤不可跳过——即使已回复评论、已推送修复代码，只要未点 Resolve，该条评论仍处于”未解决”状态，reviewer 无法判断是否已处理完毕。每修复一条，立即 Resolve 一条，不要等所有问题修完再批量操作。
   5. 所有问题处理完毕后，重新请求 Copilot review。
-  6. 重复以上步骤，直到 Copilot review 不再提出新问题为止。
+  6. 重复以上步骤，直到满足以下任一终止条件为止。
 - 每一条 Copilot review 评论处理完毕后，必须点击 **Resolve conversation**，不能只回复不 Resolve。不点 Resolve 会导致该评论一直处于未解决状态，无法判断是否已完成处理。
 - 每次修改后提交的 commit 信息必须中文，格式：`修复 Copilot review 问题：[简要描述]`。
 - 如果 Copilot review 连续两轮提出同一问题但实际已修复或无道理，需在 PR 评论中明确说明原因并直接 Resolve，不再反复修改。
+- ⚠️ **循环终止条件（满足任意一条即停止）**：
+  1. **无新问题**：Copilot review 本轮未提出任何新问题 → 自然终止，循环结束。
+  2. **仅剩可忽略级别建议**：本轮 Copilot review 提出的所有问题均标注了 `nit:`、`optional:`、`question:` 或建议将配置项写入 `.env` 等可忽略类型，无任何 `Request changes` 级别的问题 → 逐条回复说明原因并 Resolve，然后终止循环，无需再请求新一轮 review。
+  3. **衰减到底**：连续两轮 review 的新问题数量均 ≤ 2 个，且均为风格偏好或可争议建议，无实质 bug 或安全风险 → 逐条处理并 Resolve，然后终止循环。
+  4. **硬上限**：循环已达到 5 轮仍无法满足上述条件 → 暂停循环，弹出通知告知用户当前状态（已跑 N 轮、剩余未解决问题数量及摘要），由用户决定是否继续。禁止在用户未确认的情况下自动跑第 6 轮。
+  - **核心原则：Copilot review 的目标是发现真正的代码缺陷，不是追求零评论。** 经过几轮修复后，剩余的 nit/optional 级别建议或可争议的风格偏好属于正常现象，直接标记处理即可，不应无限追逐”零评论”状态。
 - PR 图片文件检查：在 Copilot review 循环中（建议放在开始处理 review 问题之前，或所有 review 问题处理完毕之后），必须检查当前 PR 中是否存在未被引用的图片文件（PNG、JPG、JPEG、GIF、SVG、WebP 等）。检查方式：搜索代码库中是否有任何文件引用了该图片的文件名或路径，若没有任何引用 → 该图片为冗余文件。处理方式：若图片内容需要保留（如截图佐证），则将其转为 base64 data URI 内嵌到对应的 HTML 文档中，然后删除原图片文件；若图片内容无需保留，则直接删除。处理完毕后提交并推送。
 - 可忽略的 review 建议：如果 Copilot review 建议将配置项（API 地址、数据库连接、第三方服务地址等）写入 `.env` 文件，必须直接忽略并在评论中回复说明原因后 Resolve。说明内容：「本项目 `.env` 仅允许配置端口号（如 `PORT`、`API_PORT`），其余配置项一律写死在代码中，敏感信息统一放入 Nacos 配置中心，不放 `.env`。」
-- ⚠️ **强制步骤：重新请求 Copilot review 后，必须主动检查 Copilot 是否已回复。** 不能发完评论就停止等待。检查方式：使用 `gh api` 拉取 PR 的 reviews 和 comments，对比上次已知的最新 review 时间戳。检查频率：每次重新请求 review 后，约 2–3 分钟后主动检查一次；若 Copilot 已生成新 review 则立即进入下一轮处理；若尚未回复，再等 2–3 分钟后再次检查。不可无限等待，最多检查 3 次（约 6–9 分钟），若仍无回复则告知用户当前状态。
+- ⚠️ **强制步骤：重新请求 Copilot review 后，必须主动检查 Copilot 是否已回复。** 不能发完评论就停止等待。检查方式：使用 `gh api` 拉取 PR 的 reviews 和 comments，对比上次已知的最新 review 时间戳。检查频率：每次重新请求 review 后，约 2–3 分钟后主动检查一次；若 Copilot 已生成新 review 则立即进入下一轮处理；若尚未回复，再等 2–3 分钟后再次检查。⚠️ **这里的「最多检查 3 次」仅指每轮 review 请求后的轮询等待次数上限（约 6–9 分钟），与 review 循环的迭代轮数无关——循环轮数由上方终止条件控制，不受此限制。** 等待超时后若仍无回复，告知用户当前状态。
 
 ## 安全