@routerhub/agent-rules 1.5.110 → 1.5.112

package/AGENTS.base.md

@@ -152,6 +152,8 @@
 - ⚠️ **HTML 文档中的截图必须以 `data:image/png;base64,...` 内嵌，禁止用文件路径或相对链接引用外部 PNG 文件。** 文档会被打开、移动、分享，外部图片路径一旦脱离原目录就全部失效，文档里全是裂图。生成文档后，散落的零散 PNG 文件应一并清理，只保留 HTML 本身。
 - ⚠️ **curl 命令必须完整可复制执行，禁止省略关键参数。** 包括但不限于：API Key / Token（用占位符 `${API_KEY}` 或真实值标注）、请求体中的图片数据、完整的 URL。禁止用 `...` 或「省略其余参数」代替——看的人无法区分「这里不重要所以省略了」还是「这里我不会写所以跳过了」，前者让命令不可执行，后者掩盖了潜在的错误。
 - ⚠️ **测试用的图片等静态资源统一放到 `docs/images/` 目录，curl 命令中用相对路径引用**（如 `@docs/images/test.jpg`），确保命令在项目根目录下可直接执行。
+- ⚠️ **一键执行脚本/命令必须能直接复制到终端执行，且文档中必须配「一键复制」按钮。** 每条命令必须完整可执行（禁止省略参数、禁止用 `...` 占位、禁止只给片段），在项目根目录下可直接运行；文档中命令块右上角必须提供复制按钮，点击即可将完整命令复制到剪贴板并给出「已复制」反馈。
+- ⚠️ **文档中给出的每条命令/脚本，写入前必须亲自在终端实际执行验证过，确认确实可行后才能写入。** 执行失败的命令一律不得写入文档，禁止凭推断「应该能跑」就写进文档——推断得出的结论不能作为生成依据，必须实际测试过才能下结论。
 
 ## Go 规则
 

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 所有对 @routerhub/agent-rules 的重大更改都会记录在这个文件中。
 
+## [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.110",
+  "version": "1.5.112",
   "description": "Shared Copilot agent rules and guidelines for RouterHub projects",
   "main": "AGENTS.base.md",
   "bin": {

package/rules/global.md

@@ -152,6 +152,8 @@ name: "通用规则"
 - ⚠️ **HTML 文档中的截图必须以 `data:image/png;base64,...` 内嵌，禁止用文件路径或相对链接引用外部 PNG 文件。** 文档会被打开、移动、分享，外部图片路径一旦脱离原目录就全部失效，文档里全是裂图。生成文档后，散落的零散 PNG 文件应一并清理，只保留 HTML 本身。
 - ⚠️ **curl 命令必须完整可复制执行，禁止省略关键参数。** 包括但不限于：API Key / Token（用占位符 `${API_KEY}` 或真实值标注）、请求体中的图片数据、完整的 URL。禁止用 `...` 或「省略其余参数」代替——看的人无法区分「这里不重要所以省略了」还是「这里我不会写所以跳过了」，前者让命令不可执行，后者掩盖了潜在的错误。
 - ⚠️ **测试用的图片等静态资源统一放到 `docs/images/` 目录，curl 命令中用相对路径引用**（如 `@docs/images/test.jpg`），确保命令在项目根目录下可直接执行。
+- ⚠️ **一键执行脚本/命令必须能直接复制到终端执行，且文档中必须配「一键复制」按钮。** 每条命令必须完整可执行（禁止省略参数、禁止用 `...` 占位、禁止只给片段），在项目根目录下可直接运行；文档中命令块右上角必须提供复制按钮，点击即可将完整命令复制到剪贴板并给出「已复制」反馈。
+- ⚠️ **文档中给出的每条命令/脚本，写入前必须亲自在终端实际执行验证过，确认确实可行后才能写入。** 执行失败的命令一律不得写入文档，禁止凭推断「应该能跑」就写进文档——推断得出的结论不能作为生成依据，必须实际测试过才能下结论。
 
 ## Go 规则
 

package/skills/create-doc/SKILL.md

@@ -8,6 +8,9 @@ description: >-
   「做文档」「做个文档」「做报告」「做个报告」「做汇报」「做个汇报」「做方案」「做个方案」「做总结」「做个总结」。
   「搞文档」「搞个文档」「搞报告」「搞个报告」「整文档」「整个文档」「整报告」「整个报告」「弄文档」「弄个文档」「弄报告」「弄个报告」。
   「文档」「报告」「需求文档」「汇报」单独说且上下文在讨论产出物时也应触发。
+  「生成一个截图版的html」「生成截图版html」「生成一个截图版」「生成截图版」「截图版文档」「截图版报告」「截图版说明」「截图版的」等任何「截图版」表述。
+  「生成一个html」「生成html」「生成一个html文档」「生成html文档」「写个html」「写html」「做一个html」「做个html」「出一个html」「出个html」「搞个html」「整个html」「弄个html」「html文档」「html报告」等任何明确要求生成 HTML 的表述。
+  「html」单独说且上下文在讨论产出物时也应触发。
   自动生成符合项目规范（HTML格式、中文文件名、base64内嵌图片、lightbox图片放大、截图为主文字为辅）的中文HTML文档，存放到docs/目录。
 ---
 
@@ -78,3 +81,10 @@ description: >-
   3. **详细说明结果**：这一步执行后出现了什么结果、验证了什么、为什么重要
 - ⚠️ 步骤之间用编号衔接（步骤 1 → 步骤 2 → …），说明文字必须一图一句、逐张不同，禁止用一句套话覆盖所有步骤的截图
 - 截图统一用 base64 data URI 内嵌，禁止引用外部图片文件
+
+### 命令与复制按钮
+
+- ⚠️ 文档中出现的每条可执行命令/脚本，必须能**直接复制到终端执行**：命令完整可复制（禁止省略参数、禁止用 `...` 占位、禁止只给片段）、在项目根目录下可直接运行
+- ⚠️ 每条命令/脚本写入文档前，必须**亲自在终端实际执行一遍验证确实可行**，验证通过后才能写入文档；执行失败的命令一律不得写入，禁止凭推断「应该能跑」就下结论
+- ⚠️ 每个命令块必须配「一键复制」按钮：点击按钮将完整命令复制到剪贴板，并给出「已复制」反馈
+- 复制按钮实现：命令块右上角放复制按钮 → 点击用 `navigator.clipboard.writeText(命令全文)` 复制（不可用时用 `document.execCommand('copy')` 兜底）→ 按钮文案短暂变为「已复制」→ 约 2 秒后恢复为「复制」

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`