@routerhub/agent-rules 1.5.112 → 1.5.114

package/AGENTS.base.md

@@ -81,6 +81,7 @@
 - ⚠️ **截图必须直接内嵌在 PR Description 中，让 reviewer 打开 PR 就能看到效果图（`![](CDN_URL)` 方式渲染为可见图片），禁止只在文字里描述"改动了什么"而不放图，也禁止把截图只作为文件附件/提交到分支目录而不在 PR 正文中引用。** 原因：reviewer 看 PR 的第一眼就是看描述，如果看不到图、只能读文字，完全无法直观感知改动效果；截图不内嵌 = 等于没附。
 - ⚠️ **截图必须通过 PR Description 编辑区直接上传（拖拽/粘贴/文件选择按钮），禁止走评论区 `input[type=file]` 上传后再搬运 CDN URL。** 原因：PR Description 编辑区本身支持图片拖拽上传、自动转为 `![](CDN_URL)` 内嵌，一步到位；走评论区上传需要多一步「提交评论 → 复制 URL → 粘贴到 Description」，产生的临时图片评论会留在 PR 对话里干扰 reviewer 阅读，且多了一步手动搬运、容易出错。
 - ⚠️ 创建 PR 使用 `/create-pr` skill（自动生成中文内容 + 效果截图 + CDN 上传）。
+- ⚠️ **创建 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。
 - ⚠️ **私有仓库的 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 引用」的流程，图片链接一律拼接为后一种格式。
 
 ## 安全

package/CHANGELOG.md

@@ -2,11 +2,23 @@
 
 所有对 @routerhub/agent-rules 的重大更改都会记录在这个文件中。
 
+## [1.5.114] - 2026-08-06
+
+### Changed
+
+- `loop-review` Skill 收敛策略重构：结束条件从「无 🔴 Critical / 🟡 Warning」改为「本轮没有任何值得修的新问题」。原因：实测 PR 走了 10 轮仍未干净，bot 每轮全量重读 diff、总能挖出新的问题（漏报/回归/新代码），「严重度清零」是移动靶、循环永不收敛。现在每轮把 bot 的所有新建议逐条读真实代码判断——值得修就修、口味/过度设计/已处理的 Won't fix 回复切断，某轮无值得修的新问题即结束；最大轮数从 5 降到 3。结束时不要求严重度清零，bot 仍挂着几条判断过不值得修的属正常。
+
+## [1.5.113] - 2026-08-06
+
+### Added
+
+- 新增创建 PR 后冲突检查规则：创建 PR 后必须先检查与主分支（默认分支）是否有冲突（`gh pr view <PR> --json mergeable -q .mergeable`），存在冲突必须先解决（merge/rebase → 解决冲突文件 → 测试通过 → 推送）再交付 review，禁止把带冲突的 PR 抛给 reviewer。
+
 ## [1.5.112] - 2026-08-06
 
 ### Added
 
-- 新增 `loop-review` Skill（循环 Code Review / AI 交叉验证循环）：写完代码提交 PR 后，反复「拉取 AI review（Claude Opus 4.6 + GPT-5.5 交叉验证）→ 判断哪些建议要改 → 改 → push 触发新一轮 review → 直到无 Critical/Warning」。触发词如「循环review」「走一下循环review流程」。全自动执行（AI 判断要改就改，每轮汇报），无 🔴/🟡 即结束；内置最大轮数（5 轮）、等待超时（15 分钟）、Won't fix 防重复循环等兜底。
+- 新增 `loop-review` Skill（循环 Code Review / AI 交叉验证循环）：写完代码提交 PR 后，反复「拉取 AI review（Claude Opus 4.6 + GPT-5.5 交叉验证）→ 逐条判断哪些建议值得改 → 改 → push 触发新一轮 review → 直到某轮不再有新问题」。触发词如「循环review」「走一下循环review流程」。
 
 ## [1.5.25] - 2026-06-26
 

package/package.json

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

package/rules/global.md

@@ -81,6 +81,7 @@ name: "通用规则"
 - ⚠️ **截图必须直接内嵌在 PR Description 中，让 reviewer 打开 PR 就能看到效果图（`![](CDN_URL)` 方式渲染为可见图片），禁止只在文字里描述"改动了什么"而不放图，也禁止把截图只作为文件附件/提交到分支目录而不在 PR 正文中引用。** 原因：reviewer 看 PR 的第一眼就是看描述，如果看不到图、只能读文字，完全无法直观感知改动效果；截图不内嵌 = 等于没附。
 - ⚠️ **截图必须通过 PR Description 编辑区直接上传（拖拽/粘贴/文件选择按钮），禁止走评论区 `input[type=file]` 上传后再搬运 CDN URL。** 原因：PR Description 编辑区本身支持图片拖拽上传、自动转为 `![](CDN_URL)` 内嵌，一步到位；走评论区上传需要多一步「提交评论 → 复制 URL → 粘贴到 Description」，产生的临时图片评论会留在 PR 对话里干扰 reviewer 阅读，且多了一步手动搬运、容易出错。
 - ⚠️ 创建 PR 使用 `/create-pr` skill（自动生成中文内容 + 效果截图 + CDN 上传）。
+- ⚠️ **创建 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。
 - ⚠️ **私有仓库的 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 引用」的流程，图片链接一律拼接为后一种格式。
 
 ## 安全

package/skills/loop-review/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: loop-review
 description: >-
-  循环 Code Review（AI 交叉验证循环）——写完代码提交 PR 后，反复「拉取 AI review（Claude Opus 4.6 + GPT-5.5 交叉验证）→ 判断哪些建议要改 → 改 → push 触发新一轮 review → 直到无 Critical/Warning」。触发场景包括但不限于：
+  循环 Code Review（AI 交叉验证循环）——写完代码提交 PR 后，反复「拉取 AI review（Claude Opus 4.6 + GPT-5.5 交叉验证）→ 逐条判断哪些建议值得改 → 改 → push 触发新一轮 review → 直到某轮不再有新问题」。触发场景包括但不限于：
   「循环review」「循环审查」「循环评审」「循环 Review」「loop review」「Loop Review」「review循环」「review 循环」。
   「循环review流程」「走一下循环review」「走循环review」「循环review一下」「循环处理review」「循环处理一下review」。
   「循环到没问题」「review到没问题」「review到干净」「反复review」「重复review」「一直review到干净」「review迭代」「交叉验证循环」。
@@ -11,18 +11,28 @@ description: >-
 
 # 循环 Code Review（AI 交叉验证循环）
 
-⚠️ **本 Skill 已触发。第一句话必须输出：「🔧 已触发 `loop-review`，开始循环 review 流程（拉取 AI 交叉验证 → 判断 → 修改 → 再 review → 干净为止）」然后严格按照以下步骤执行，不得跳过。**
+⚠️ **本 Skill 已触发。第一句话必须输出：「🔧 已触发 `loop-review`，开始循环 review 流程（拉取 AI 交叉验证 → 逐条判断 → 修改 → 再 review → 直到不再有新问题）」然后严格按照以下步骤执行，不得跳过。**
 
-让 AI review bot（Claude Opus 4.6 + GPT-5.5 交叉验证，由 `github-actions[bot]` 发布）循环审查，直到最新一轮 review 不再有 🔴 Critical / 🟡 Warning。
+让 AI review bot（Claude Opus 4.6 + GPT-5.5 交叉验证，由 `github-actions[bot]` 发布）循环审查，把**每一轮新出现且值得修的真问题都修掉**，直到某一轮不再冒出值得修的新问题即结束。
+
+## 为什么 bot 修完一轮还会冒出"新问题"（必须理解）
+
+bot **每一轮都把整份 PR diff 从头到尾全新读一遍**，不是只看这次改了什么。所以"新问题"永远是三个来源：
+
+1. **上一轮漏报的旧问题（最主要）**：同一批代码，第一轮注意力集中在最明显的 bug 上，修完之后它重新通读，才注意到之前没看的角落。不是问题"新增"了，是上一轮没看到。人审代码也一样——第一遍看主流程，第二遍才抠边界。
+2. **修复本身引入的回归**：为修问题 A 改动共享逻辑，波及问题 B。这是真实新问题，该修。
+3. **新代码自带新问题**：为新需求写的函数/逻辑，bot 会 review 新代码，新代码自然有新毛病。
+
+**关键认识**：bot 的"问题挖掘能力"是无限的，总能往下挖出新层次。**所以「追着严重度清零」是永远停不下来的循环**（实测 PR #26 走了 10 轮、第 7-8 轮曾短暂干净、第 9 轮又冒出新 Critical）。循环要收敛，靠的不是"问题清空了"，而是——**每一轮冒出的新问题我们都逐条判断过：值得修的修掉、不值得修/口味/过度设计的 Won't fix 切断**。剩下全是判断过"不值得修"的，bot 再提就用 Won't fix 挡住。
 
 ## 工作原理
 
 AI review bot 在**每次 push 到 PR 时自动触发新一轮 review**。因此循环流程是：
 
 ```
-拉取最新 review → 解析两个模型的建议 → 逐条判断（读真实代码）→ 需要改就改
-→ push（触发新 review）→ 等待新 review 到达 → 判定是否干净
-→ 不干净则回到「解析建议」，干净则结束
+拉取最新 review → 解析两个模型的建议 → 每条读真实代码判断（值得修 / 不值得修）
+→ 值得修的改 → 不值得修的 Won't fix 回复 → push（触发新 review）→ 等待新 review 到达
+→ 若本轮没有任何值得修的新问题 → 结束；否则进入下一轮
 ```
 
 ## 当前 PR
@@ -71,23 +81,29 @@ gh api repos/$REPO/pulls/$PR/reviews?per_page=100 --jq \
 
 若最新 review 对应的还是更早的 commit，说明 push 后 bot 尚未审查完，先进入步骤 5 的等待。
 
-### 2. 汇总建议并逐条判断
+### 2. 汇总建议并逐条判断（核心）
+
+解析两个模型的所有问题，**两模型报同一问题时合并为一条**（不要重复改两遍）。
 
-解析两个模型的所有问题，**两模型报同一问题时合并为一条**（不要重复改两遍）。逐条判断：
+⚠️ **严重度只是 bot 的标注，不是「该不该修」的依据**。真正决定改不改的是你读完代码后的判断。逐条按下面的决策框架：
 
-| 严重度 | 默认处理 |
-|--------|----------|
-| 🔴 Critical | 必须改，除非读代码确认是误报 |
-| 🟡 Warning | 应该改，默认改 |
-| 🔵 Suggestion | 可选，判断有无价值，低价值可拒绝 |
+| 判断 | 说明 | 处理 |
+|------|------|------|
+| **值得修** | 读代码确认是真实 bug / 真实风险，或明显值得改 | ✅ 改 |
+| **不值得修** | 过度设计 / 口味偏好 / 重构建议 / 收益小于风险 | ⛔ 不改 + Won't fix 回复 |
+| **已处理过** | 上一轮已修过但 bot 重提 | ⛔ 不改 + 回复「已修复于 <hash>」 |
+| **误报** | 读代码确认 review 描述不属实 | ⛔ 不改 + 回复「误报：<为什么>」 |
 
 **判断依据（每条必须读真实代码，禁止凭 review 文字盲改）**：
 
-- 这是否是真实 bug / 真实风险？（读代码验证，不轻信 review 描述）
+- 这是否是真实 bug / 真实风险？（读代码验证，不轻信 review 描述，也不轻信严重度标签）
 - 该建议是否符合本项目规则（AGENTS.base.md / AGENTS.private.md）？
-- 改动风险多大？会不会超出该建议本身的范围？
+- 改动风险多大？会不会超出该建议本身的范围？（为了修一条问题去大改共享逻辑，本身可能引入新风险）
+- 是"必须修"还是"有则更好"？后者更接近口味，可拒绝。
 - 两模型是否一致指出？一致 → 优先级更高、基本可信。
 
+**每轮必须追问一句**：这条问题是不是上一轮已经判断过/处理过的？是 → 直接 Won't fix / 已修复，不重复改。**这一步是循环能收敛的关键。**
+
 输出判断表：
 
 ```
@@ -96,21 +112,31 @@ gh api repos/$REPO/pulls/$PR/reviews?per_page=100 --jq \
 | 1 | Opus+GPT | 🔴 | 并行部署失败被静默忽略 | 改 | 后台进程不受 set -e 管控，属实 |
 | 2 | GPT | 🟡 | test/prod 共用缓存 TAG | 改 | 有缓存污染风险 |
 | 3 | Opus | 🔵 | 提取重复代码 | 不改 | 仅出现两次，封装过度 |
+| 4 | Opus | 🔴 | 某竞态条件 | 不改 | 上一轮已修复于 3fa21c0，bot 重提 |
 ```
 
 ### 3. 应用修复
 
-- 功能性问题（🔴 / 🟡，以及所有判定「要改」的）→ 每个修复单独 commit，commit 信息用中文，正文引用对应 review 来源
-- 建议级（🔵）→ 合并为一个 commit
-- 判定「不改」的建议 → 记下理由，按步骤 4 回复，防止 bot 下一轮重复提同一问题
+- 判定「值得修」的（无论严重度）→ 每个修复单独 commit，commit 信息用中文，正文引用对应 review 来源
+- 纯建议级且判定值得改的 → 合并为一个 commit
+- 判定「不值得修 / 已处理 / 误报」的 → 按步骤 4 回复，切断 bot 下轮重提
 
-### 4. 对「不改」的建议回复（防重复循环）
+### 4. 对「不改」的建议回复（防重复循环，关键）
 
 ```bash
-gh pr comment $PR --body "Won't fix: <理由>。针对 <来源模型> 提出的「<建议摘要>」。"
+# 值得改的已修复
+gh pr comment $PR --body "Fixed in <hash>。针对「<建议摘要>」。"
+
+# 不值得修 / 口味
+gh pr comment $PR --body "Won't fix: <理由>。针对「<建议摘要>」。"
+
+# 误报
+gh pr comment $PR --body "误报：<读代码后为什么它不是问题>。针对「<建议摘要>」。"
 ```
 
-已修复的问题若 review 附了 inline comment，用 `gh api .../pulls/$PR/comments` 的 `in_reply_to` 回复「Fixed in <hash>」。
+已修复的问题若 review 附了 inline comment，用 `gh api .../pulls/$PR/comments` 的 `in_reply_to` 回复。
+
+⚠️ **改动的每条 review 建议都必须有落点**：要么修复 commit，要么 Won't fix/误报回复。**不允许静默跳过**——不回复的话 bot 下一轮还会原样重提，循环就真的无限了。
 
 ### 5. push 并等待下一轮 review
 
@@ -138,13 +164,13 @@ done
 
 ### 6. 判定本轮结果
 
-拉取针对当前 `HEAD` 的最新 review，解析其中 🔴 / 🟡 / 🔵 的剩余情况：
+拉取针对当前 `HEAD` 的最新 review，逐条判断（回到步骤 2 的决策框架）后：
 
-- **无 🔴 Critical / 🟡 Warning** → 循环结束 ✅，进入步骤 7 收尾
-- **仍有 🔴 / 🟡** → 回到步骤 2，进入下一轮
-- **达到最大轮数（默认 5 轮）仍未干净** → 停止循环，把剩余问题逐条列给用户，由用户决定（继续 / 放过 / 人工处理），禁止无限循环
+- **本轮没有任何「值得修」的新问题**（要么 bot 没提新的，要么新问题全是已处理/口味/误报，全部有回复落点）→ 循环结束 ✅，进入步骤 7 收尾
+- **本轮有「值得修」的新问题** → 已修复并回复，回到步骤 5 进入下一轮
+- **达到最大轮数（默认 3 轮）仍有值得修的新问题** → 停止循环，把剩余问题逐条列给用户，由用户决定（继续 / 放过 / 人工处理），禁止无限循环
 
-⚠️ 每轮结束向用户汇报：本轮发现什么、改了什么、拒绝了什么、还剩什么。
+⚠️ 每轮结束向用户汇报：本轮发现什么、改了什么、拒绝了什么、剩什么。
 
 ### 7. 收尾汇报
 
@@ -152,26 +178,30 @@ done
 
 ```
 循环 review 完成，共 X 轮：
-- 第 1 轮：发现 3 个问题（2 Critical / 1 Warning），修复 2，拒绝 1
-- 第 2 轮：发现 1 个问题（1 Warning），修复 1
-- 第 3 轮：无 Critical/Warning，循环结束 ✅
+- 第 1 轮：发现 4 个问题（1 Critical / 2 Warning / 1 Suggestion），修复 3，Won't fix 1
+- 第 2 轮：发现 2 个新问题（1 Critical / 1 Warning），修复 2，另收到 2 条重复重提 → 已回复已修复
+- 第 3 轮：无值得修的新问题，循环结束 ✅
+
+最终状态：真实问题已全部修复。bot 仍挂着 N 条建议（口味/过度设计），均已 Won't fix 回复并说明理由。
 ```
 
 ## 循环终止条件（重要）
 
 | 条件 | 行为 |
 |------|------|
-| 最新一轮 review 无 🔴/🟡 | ✅ 结束 |
-| 达到最大轮数（默认 5 轮） | ⛔ 停止，剩余问题交用户决定 |
+| 本轮没有任何「值得修」的新问题 | ✅ 结束（注意：**不是**「严重度清零」——bot 总会挂着几条我们判断过不值得修的） |
+| 达到最大轮数（默认 3 轮） | ⛔ 停止，剩余问题交用户决定 |
 | 等待新 review 超时（默认 15 分钟） | ⏸ 停止等待，询问用户 |
 | 连续两轮 review 内容完全相同（bot 疑似卡死） | ⛔ 停止，向用户报告 |
 
 ## ⚠️ 铁律
 
-- ⚠️ **每条建议必须读真实代码再判断，禁止盲从 review 文字**。review 是 LLM 生成的，可能误报。
+- ⚠️ **每条建议必须读真实代码再判断，禁止盲从 review 文字、也禁止盲从严重度标签**。review 是 LLM 生成的，可能误报，严重度只是它的标注。
+- ⚠️ **循环收敛靠「值得修的都修完 + 不值得修的 Won't fix 切断」**，不是靠「严重度清零」。禁止用「无 Critical/Warning」当结束标准。
+- ⚠️ **每条 review 建议必须有落点**（修复 commit / Won't fix / 误报回复），禁止静默跳过——不回复 bot 下轮必重提，循环无限。
+- ⚠️ **每轮先确认哪些是上一轮已处理过的**，一律不重复改，直接回复「已修复于 <hash>」。
 - ⚠️ **禁止使用 `[skip ci]` / `[skip review]`**——循环依赖「每次 push 触发 review」，跳过就断了。
-- ⚠️ **不改的建议必须回复「Won't fix: 理由」**，否则同一问题被 bot 每轮重提，循环永不收敛。
-- ⚠️ **必须设最大轮数（默认 5）和等待超时（默认 15 分钟）**，禁止无限循环 / 无限等待。
+- ⚠️ **必须设最大轮数（默认 3）和等待超时（默认 15 分钟）**，禁止无限循环 / 无限等待。
 - ⚠️ **已修复的功能性问题单独 commit**，禁止与大量建议级改动混在一起，保证每轮 push 的 diff 可读。
 - ⚠️ **等待 bot 审查期间遵守心跳约定**：超过 1 分钟无输出主动说明在等什么。
 - ⚠️ **commit 用中文、禁止 `git push --force`、commit 信息引用对应 review 来源**。