@routerhub/agent-rules 1.5.124 → 1.5.126

package/AGENTS.base.md

@@ -68,6 +68,7 @@
 - **长任务或涉及截图等大内容的操作，注意控制单次传入的数据量**（压缩、降低分辨率等），避免不必要地占满上下文。
 - ⚠️ **用户反馈"看起来没生效/没写入"时，先用权威数据源核实**（直连数据库/调对应 API 查，而不是只信一次前端页面截图），前端页面可能存在多个同名视图、未展开的关联表、缓存等歧义，容易把"看错了地方"误判成"修复失败"，也可能反过来把真的失败误判成"看错了"——两种方向都要用权威数据源排除，不能靠肉眼猜。
 - ⚠️ **停用/归档任何仍可能被其他配置引用的共享资源（数据库、开关、服务实例、旧接口等）前，必须先确认所有引用方已经完成切换**，禁止先下线资源、后补救引用；正确顺序是「新资源就位 → 所有引用方切到新资源并验证 → 确认无引用后才下线旧资源」。
+- ⚠️ **对「只增不改」的追加型数据表（日志表、流水表）做分批消费时，禁止用「每次从头查 + LIMIT 截断 + 幂等去重」的无状态写法**。无断点的全量查询每次都会返回最早的一批行（早已消费、被幂等跳过、不产生任何效果），而新行永远排在 LIMIT 之外——扣款/同步在数据量超过单批上限后静默停滞，不报错、不崩溃，余额/进度「悄悄不涨不降」，是最阴险的静默 bug（offset-pagination 饥荒）。正确写法是带「进度断点」的增量查询：**按业务排序键（如时间+ID）记录上次消费位置（游标），下轮用 `WHERE 排序键 > 断点` 的严格排他下界续拉，消费成功后游标单调推进到批次末尾**，保证不重也不漏。判断标准：只要处理逻辑会「跳过已处理的记录」且「数据量可能超过单批上限」，就必须用游标/断点，而非从头扫。
 
 ## ⚠️ 修复验证铁律
 
@@ -324,3 +325,42 @@
 - ⚠️ **部署到测试环境唯一入口：`/deploy-test` skill。** 不论用户怎么表述（「部署测试」「帮我部署」「推到test」「发布测试环境」等），必须通过 `Skill` 工具调用 `deploy-test`，禁止凭记忆手动执行 git 命令。
 - ⚠️ **必须先合并再部署**：流程必须是 `当前功能分支 → merge 到 test → push test → 触发部署 → 切回原分支`。严禁跳过 merge 步骤直接部署功能分支。
 - ⚠️ **部署完成后必须切回原分支**，不得停留在 test 分支。
+
+<!-- @domain: review-boundary -->
+
+## 审稿边界（Review Boundary）
+
+⚠️ 本条是写给 **code review 审稿方**（AI review bot / Copilot code review / 人工 reviewer）的约束，**不是**给写代码方的新增要求。目标是让 review 收敛：只报「会导致 bug 的真问题」，不报「口味 / 风格 / 防御性」建议——后者正是循环 review 停不下来的元凶。写代码方遵守作者规则（AGENTS.base.md 其余章节）后，剩下的 review 意见大多是审稿人按自己的通用标准挖出来的口味问题，修完一轮又冒一轮，十几轮就是这么滚出来的。
+
+### 必须报（真问题）
+
+- 🔴 **会导致实际 bug / 数据丢失 / 数据错误 / 安全漏洞**：有明确触发路径（真实输入、真实调用链能复现），读 diff 能确认后果。
+- 🟡 **真实风险**：有明确触发条件，且触发后后果严重（如并发竞态、错误被静默吞掉、未处理空值导致崩溃）。
+- **违反本项目已固化规则**：AGENTS.base.md / AGENTS.private.md 里的 ⚠️ 铁律（DELETE 铁律、部署自包含、数据链路核对、环境配置禁止推断、测试环境验证前置等），diff 中明确违反 → 必须报。
+
+### 禁止报（不是问题，报了只会拉长循环）
+
+- 🔵 **口味 / 风格偏好**：换个命名更好、建议用某设计模式、提取公共函数、重构建议——作者规则已规范，审稿人不要另立标准。
+- 🛡️ **纯防御性建议**：以「如果未来 / 万一 / 边界情况下」开头、当前代码没有实际触发路径的「潜在风险」（如「序号 99999 溢出」「未来可能有人改这里」），一律不报。
+- ❓ **无法确认真假的问题**：读 diff 不能确认会导致 bug 的，默认按「不是问题」处理，禁止报「建议确认一下」这类空泛意见。
+- 🔁 **重复已处理的问题**：已在评论 / 历史中标记 Won't fix 或「已修复于 &lt;hash&gt;」的问题，不再重提。
+
+### 判断标准
+
+- **一句话：「这条不修，功能会不会错 / 数据会不会坏？」** 会 → 报；不会 → 不报。
+- 每条意见必须引用 diff 中的具体代码行作为证据，禁止臆测。
+- 无法确认 → 不报。宁可漏报一条真问题，也不用十条口味问题刷屏。
+- 每轮 review 的问题数量应当 ≤ 上一轮：修完真问题后没有新的真问题，就直接说「无值得修的新问题」，不要换个角度再挖。
+
+---
+
+When performing a code review, ONLY report issues that would cause an actual bug, data loss, or security vulnerability with a concrete, reproducible trigger path visible in the diff.
+
+Do NOT report:
+- Style, naming, or personal-preference opinions.
+- Refactoring, "extract a function", or design-pattern suggestions.
+- Defensive suggestions with no current trigger path (e.g. "in the future...", "what if...", "an edge case that cannot happen today").
+- Issues you cannot confirm from the diff. If unsure, do not report it.
+- Already-handled issues (previously Won't fix or marked "fixed in <hash>").
+
+Every comment MUST cite the specific diff lines as evidence. When in doubt, stay silent. One real bug beats ten style suggestions. If no real problems remain, say so explicitly and stop.

package/merge.js

@@ -199,6 +199,12 @@ const DOMAIN_META = {
     outputName: "devops",
     fileName: "devops.md",
   },
+  "review-boundary": {
+    name: "审稿边界",
+    applyTo: ["**/*"],
+    outputName: "review-boundary",
+    fileName: "review-boundary.md",
+  },
 };
 
 /**

package/package.json

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

package/rules/global.md

@@ -68,6 +68,7 @@ name: "通用规则"
 - **长任务或涉及截图等大内容的操作，注意控制单次传入的数据量**（压缩、降低分辨率等），避免不必要地占满上下文。
 - ⚠️ **用户反馈"看起来没生效/没写入"时，先用权威数据源核实**（直连数据库/调对应 API 查，而不是只信一次前端页面截图），前端页面可能存在多个同名视图、未展开的关联表、缓存等歧义，容易把"看错了地方"误判成"修复失败"，也可能反过来把真的失败误判成"看错了"——两种方向都要用权威数据源排除，不能靠肉眼猜。
 - ⚠️ **停用/归档任何仍可能被其他配置引用的共享资源（数据库、开关、服务实例、旧接口等）前，必须先确认所有引用方已经完成切换**，禁止先下线资源、后补救引用；正确顺序是「新资源就位 → 所有引用方切到新资源并验证 → 确认无引用后才下线旧资源」。
+- ⚠️ **对「只增不改」的追加型数据表（日志表、流水表）做分批消费时，禁止用「每次从头查 + LIMIT 截断 + 幂等去重」的无状态写法**。无断点的全量查询每次都会返回最早的一批行（早已消费、被幂等跳过、不产生任何效果），而新行永远排在 LIMIT 之外——扣款/同步在数据量超过单批上限后静默停滞，不报错、不崩溃，余额/进度「悄悄不涨不降」，是最阴险的静默 bug（offset-pagination 饥荒）。正确写法是带「进度断点」的增量查询：**按业务排序键（如时间+ID）记录上次消费位置（游标），下轮用 `WHERE 排序键 > 断点` 的严格排他下界续拉，消费成功后游标单调推进到批次末尾**，保证不重也不漏。判断标准：只要处理逻辑会「跳过已处理的记录」且「数据量可能超过单批上限」，就必须用游标/断点，而非从头扫。
 
 ## ⚠️ 修复验证铁律
 

package/rules/review-boundary.md

@@ -0,0 +1,42 @@
+---
+name: "审稿边界"
+applyTo: ["**/*"]
+outputName: "review-boundary"
+---
+
+## 审稿边界（Review Boundary）
+
+⚠️ 本条是写给 **code review 审稿方**（AI review bot / Copilot code review / 人工 reviewer）的约束，**不是**给写代码方的新增要求。目标是让 review 收敛：只报「会导致 bug 的真问题」，不报「口味 / 风格 / 防御性」建议——后者正是循环 review 停不下来的元凶。写代码方遵守作者规则（AGENTS.base.md 其余章节）后，剩下的 review 意见大多是审稿人按自己的通用标准挖出来的口味问题，修完一轮又冒一轮，十几轮就是这么滚出来的。
+
+### 必须报（真问题）
+
+- 🔴 **会导致实际 bug / 数据丢失 / 数据错误 / 安全漏洞**：有明确触发路径（真实输入、真实调用链能复现），读 diff 能确认后果。
+- 🟡 **真实风险**：有明确触发条件，且触发后后果严重（如并发竞态、错误被静默吞掉、未处理空值导致崩溃）。
+- **违反本项目已固化规则**：AGENTS.base.md / AGENTS.private.md 里的 ⚠️ 铁律（DELETE 铁律、部署自包含、数据链路核对、环境配置禁止推断、测试环境验证前置等），diff 中明确违反 → 必须报。
+
+### 禁止报（不是问题，报了只会拉长循环）
+
+- 🔵 **口味 / 风格偏好**：换个命名更好、建议用某设计模式、提取公共函数、重构建议——作者规则已规范，审稿人不要另立标准。
+- 🛡️ **纯防御性建议**：以「如果未来 / 万一 / 边界情况下」开头、当前代码没有实际触发路径的「潜在风险」（如「序号 99999 溢出」「未来可能有人改这里」），一律不报。
+- ❓ **无法确认真假的问题**：读 diff 不能确认会导致 bug 的，默认按「不是问题」处理，禁止报「建议确认一下」这类空泛意见。
+- 🔁 **重复已处理的问题**：已在评论 / 历史中标记 Won't fix 或「已修复于 <hash>」的问题，不再重提。
+
+### 判断标准
+
+- **一句话：「这条不修，功能会不会错 / 数据会不会坏？」** 会 → 报；不会 → 不报。
+- 每条意见必须引用 diff 中的具体代码行作为证据，禁止臆测。
+- 无法确认 → 不报。宁可漏报一条真问题，也不用十条口味问题刷屏。
+- 每轮 review 的问题数量应当 ≤ 上一轮：修完真问题后没有新的真问题，就直接说「无值得修的新问题」，不要换个角度再挖。
+
+---
+
+When performing a code review, ONLY report issues that would cause an actual bug, data loss, or security vulnerability with a concrete, reproducible trigger path visible in the diff.
+
+Do NOT report:
+- Style, naming, or personal-preference opinions.
+- Refactoring, "extract a function", or design-pattern suggestions.
+- Defensive suggestions with no current trigger path (e.g. "in the future...", "what if...", "an edge case that cannot happen today").
+- Issues you cannot confirm from the diff. If unsure, do not report it.
+- Already-handled issues (previously Won't fix or marked "fixed in <hash>").
+
+Every comment MUST cite the specific diff lines as evidence. When in doubt, stay silent. One real bug beats ten style suggestions. If no real problems remain, say so explicitly and stop.