@routerhub/agent-rules 1.5.111 → 1.5.113

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,6 +2,18 @@
 
 所有对 @routerhub/agent-rules 的重大更改都会记录在这个文件中。
 
+## [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 防重复循环等兜底。
+
 ## [1.5.25] - 2026-06-26
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@routerhub/agent-rules",
-  "version": "1.5.111",
+  "version": "1.5.113",
   "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

@@ -0,0 +1,184 @@
+---
+name: loop-review
+description: >-
+  循环 Code Review（AI 交叉验证循环）——写完代码提交 PR 后，反复「拉取 AI review（Claude Opus 4.6 + GPT-5.5 交叉验证）→ 判断哪些建议要改 → 改 → push 触发新一轮 review → 直到无 Critical/Warning」。触发场景包括但不限于：
+  「循环review」「循环审查」「循环评审」「循环 Review」「loop review」「Loop Review」「review循环」「review 循环」。
+  「循环review流程」「走一下循环review」「走循环review」「循环review一下」「循环处理review」「循环处理一下review」。
+  「循环到没问题」「review到没问题」「review到干净」「反复review」「重复review」「一直review到干净」「review迭代」「交叉验证循环」。
+  「再来一轮review」「下一轮review」「review下一轮」「再review一轮」。
+  当用户写完代码提交 PR 后，主动问「要不要走循环 review」时也可触发。
+---
+
+# 循环 Code Review（AI 交叉验证循环）
+
+⚠️ **本 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 在**每次 push 到 PR 时自动触发新一轮 review**。因此循环流程是：
+
+```
+拉取最新 review → 解析两个模型的建议 → 逐条判断（读真实代码）→ 需要改就改
+→ push（触发新 review）→ 等待新 review 到达 → 判定是否干净
+→ 不干净则回到「解析建议」，干净则结束
+```
+
+## 当前 PR
+
+!`gh pr view --json number,title,state -q '"PR #\(.number): \(.title) (\(.state))"' 2>/dev/null`
+
+## 核心流程
+
+### 0. 记录起始状态
+
+```bash
+REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner')
+PR=$(gh pr view --json number -q '.number')
+HEAD=$(git rev-parse --short HEAD)
+```
+
+记录本轮起始 `HEAD`，用于判断「新 review 是否已针对最新 push」。
+
+### 1. 拉取最新一轮 AI review
+
+```bash
+gh api repos/$REPO/pulls/$PR/reviews?per_page=100 --jq '
+  [.[] | select(.user.login == "github-actions[bot]") |
+   {id, commit_id, submitted_at, body}]
+'
+```
+
+review body 结构（已实测确认）：
+
+- 开头标注「审查 commit: \`xxx\`」——该轮 review 对应的提交
+- `## 🤖 Claude Opus 4.6 Code Review`：Opus 的审查结论
+- `## 🤖 GPT-5.5 Code Review（交叉验证）`：GPT-5.5 的交叉验证结论
+- 每个模型内部按严重度分节：`## 🔴 Critical` / `## 🟡 Warning` / `## 🔵 Suggestion`
+
+**确认「最新一轮 review 是否针对当前 HEAD」**，优先用 review 的 `commit_id` 字段，为空时解析 body 里的「审查 commit」：
+
+```bash
+# 取最新一条对应当前 HEAD 的 review（命中则输出 YES，否则为空）
+CUR=$(git rev-parse --short HEAD)
+gh api repos/$REPO/pulls/$PR/reviews?per_page=100 --jq \
+  --arg cur "$CUR" '
+  [.[] | select(.user.login == "github-actions[bot]") |
+   (.commit_id // (try (.body | capture("审查 commit: `(?<h>[0-9a-f]+)`") | .h) catch null))] |
+  if .[0] == $cur then "YES" else "NO" end'
+```
+
+若最新 review 对应的还是更早的 commit，说明 push 后 bot 尚未审查完，先进入步骤 5 的等待。
+
+### 2. 汇总建议并逐条判断
+
+解析两个模型的所有问题，**两模型报同一问题时合并为一条**（不要重复改两遍）。逐条判断：
+
+| 严重度 | 默认处理 |
+|--------|----------|
+| 🔴 Critical | 必须改，除非读代码确认是误报 |
+| 🟡 Warning | 应该改，默认改 |
+| 🔵 Suggestion | 可选，判断有无价值，低价值可拒绝 |
+
+**判断依据（每条必须读真实代码，禁止凭 review 文字盲改）**：
+
+- 这是否是真实 bug / 真实风险？（读代码验证，不轻信 review 描述）
+- 该建议是否符合本项目规则（AGENTS.base.md / AGENTS.private.md）？
+- 改动风险多大？会不会超出该建议本身的范围？
+- 两模型是否一致指出？一致 → 优先级更高、基本可信。
+
+输出判断表：
+
+```
+| # | 来源 | 严重度 | 建议摘要 | 判断 | 理由 |
+|---|------|--------|---------|------|------|
+| 1 | Opus+GPT | 🔴 | 并行部署失败被静默忽略 | 改 | 后台进程不受 set -e 管控，属实 |
+| 2 | GPT | 🟡 | test/prod 共用缓存 TAG | 改 | 有缓存污染风险 |
+| 3 | Opus | 🔵 | 提取重复代码 | 不改 | 仅出现两次，封装过度 |
+```
+
+### 3. 应用修复
+
+- 功能性问题（🔴 / 🟡，以及所有判定「要改」的）→ 每个修复单独 commit，commit 信息用中文，正文引用对应 review 来源
+- 建议级（🔵）→ 合并为一个 commit
+- 判定「不改」的建议 → 记下理由，按步骤 4 回复，防止 bot 下一轮重复提同一问题
+
+### 4. 对「不改」的建议回复（防重复循环）
+
+```bash
+gh pr comment $PR --body "Won't fix: <理由>。针对 <来源模型> 提出的「<建议摘要>」。"
+```
+
+已修复的问题若 review 附了 inline comment，用 `gh api .../pulls/$PR/comments` 的 `in_reply_to` 回复「Fixed in <hash>」。
+
+### 5. push 并等待下一轮 review
+
+```bash
+git push origin <当前分支>
+```
+
+- ⚠️ **禁止使用 `[skip ci]` / `[skip review]` 等关键词**——会跳过 bot 审查，循环就断了。
+- push 后 bot 需要一段时间才出新一轮 review（实测几分钟到几十分钟不等），用轮询等待，不要干等：
+
+```bash
+CUR=$(git rev-parse --short HEAD)
+for i in $(seq 1 45); do
+  R=$(gh api repos/$REPO/pulls/$PR/reviews?per_page=100 --jq \
+    --arg cur "$CUR" '
+    [.[] | select(.user.login == "github-actions[bot]") |
+     (.commit_id // (try (.body | capture("审查 commit: `(?<h>[0-9a-f]+)`") | .h) catch null))] | .[0]')
+  [ "$R" = "$CUR" ] && echo "NEW_REVIEW_READY" && break
+  sleep 20
+done
+```
+
+- ⚠️ **遵守心跳约定**：等待期间超过 1 分钟无输出，主动告知「正在等 bot 审查」。
+- 轮询约 15 分钟（45 次 × 20s）仍没出新 review → 停止等待，向用户报告当前状态并询问是否继续等。
+
+### 6. 判定本轮结果
+
+拉取针对当前 `HEAD` 的最新 review，解析其中 🔴 / 🟡 / 🔵 的剩余情况：
+
+- **无 🔴 Critical / 🟡 Warning** → 循环结束 ✅，进入步骤 7 收尾
+- **仍有 🔴 / 🟡** → 回到步骤 2，进入下一轮
+- **达到最大轮数（默认 5 轮）仍未干净** → 停止循环，把剩余问题逐条列给用户，由用户决定（继续 / 放过 / 人工处理），禁止无限循环
+
+⚠️ 每轮结束向用户汇报：本轮发现什么、改了什么、拒绝了什么、还剩什么。
+
+### 7. 收尾汇报
+
+循环结束或达到轮数上限后，输出汇总报告：
+
+```
+循环 review 完成，共 X 轮：
+- 第 1 轮：发现 3 个问题（2 Critical / 1 Warning），修复 2，拒绝 1
+- 第 2 轮：发现 1 个问题（1 Warning），修复 1
+- 第 3 轮：无 Critical/Warning，循环结束 ✅
+```
+
+## 循环终止条件（重要）
+
+| 条件 | 行为 |
+|------|------|
+| 最新一轮 review 无 🔴/🟡 | ✅ 结束 |
+| 达到最大轮数（默认 5 轮） | ⛔ 停止，剩余问题交用户决定 |
+| 等待新 review 超时（默认 15 分钟） | ⏸ 停止等待，询问用户 |
+| 连续两轮 review 内容完全相同（bot 疑似卡死） | ⛔ 停止，向用户报告 |
+
+## ⚠️ 铁律
+
+- ⚠️ **每条建议必须读真实代码再判断，禁止盲从 review 文字**。review 是 LLM 生成的，可能误报。
+- ⚠️ **禁止使用 `[skip ci]` / `[skip review]`**——循环依赖「每次 push 触发 review」，跳过就断了。
+- ⚠️ **不改的建议必须回复「Won't fix: 理由」**，否则同一问题被 bot 每轮重提，循环永不收敛。
+- ⚠️ **必须设最大轮数（默认 5）和等待超时（默认 15 分钟）**，禁止无限循环 / 无限等待。
+- ⚠️ **已修复的功能性问题单独 commit**，禁止与大量建议级改动混在一起，保证每轮 push 的 diff 可读。
+- ⚠️ **等待 bot 审查期间遵守心跳约定**：超过 1 分钟无输出主动说明在等什么。
+- ⚠️ **commit 用中文、禁止 `git push --force`、commit 信息引用对应 review 来源**。
+- ⚠️ **两模型报同一问题合并为一条处理**，不要重复改两遍。
+- ⚠️ **涉及生产部署、大范围改动等高风险修改，即使判定「要改」也应先向用户说明再执行**（与全自动模式互补，不冲突）。
+
+## 参考
+
+- 拉取评论 / 分类 / 回复 thread 的细节复用 `github-pr-review` skill（`skills/github-pr-review/SKILL.md`）
+- 严重度识别补充规则：`skills/github-pr-review/references/severity_guide.md`