@routerhub/agent-rules 1.5.168 → 1.5.170

package/AGENTS.base.md

@@ -117,6 +117,17 @@
 - ⚠️ **已推送到远程的提交需要撤销时，必须用 `git revert`，禁止用 `git push --force` 覆盖远程历史。** `git revert` 会创建一条新的撤销提交，保留完整的操作记录，不影响其他协作者的本地分支；`git push --force` 会破坏远程历史，导致其他人的本地分支与远程脱节，极易引发合并冲突或丢失他人提交。
 - ⚠️ **提交并推送代码后，若发现与主分支存在冲突，必须主动解决**，不能推送完就算完事、把冲突留给别人处理。
 
+## ⚠️ 处理其他项目/副本时统一用 worktree 隔离（不改别人正在用的分支）
+
+- ⚠️ **需要修改某个仓库，而该仓库是多副本（A-/B-/C-/M- 前缀）且当前分支可能正被其他开发任务占用时，默认用临时 git worktree 隔离操作，禁止直接在当前工作副本上 `git checkout` 切换分支。** 多副本仓库中同一个克隆往往同时被多个任务使用：直接切分支会破坏别人正在进行的代码、或把自己卡在非主分支上。实例：`c-pomex-gateway` 正被 `feature/timeslot-pricing` 开发任务占用（落后 main 10 个提交），此时要做文档迁移，就用 `git worktree` 从 `origin/main` 检出到独立目录操作，feature 分支工作区完全不动。
+- ⚠️ **标准操作流程**：
+  1. 在仓库根目录执行 `git worktree add -b <任务分支> ../<任务>-work <基础分支>`（基础分支用 `origin/main` 或具体目标分支），独立目录检出并新建分支，当前工作副本完全不动。
+  2. 在 worktree 目录内完成改动 → 编译/测试通过 → `git push -u origin <任务分支>`。
+  3. 创建 PR（合并目标为仓库默认分支）。
+  4. 操作完成后 `git worktree remove ../<任务>-work` 清理，原副本分支状态不受影响。
+- ⚠️ **worktree 与主副本共享同一套本地 `.git`**，但工作目录、索引、当前分支状态完全独立，不会干扰正在 main 或其他分支上改动代码的协作者。
+- ⚠️ **worktree 目录默认在仓库根目录同级（`../`）**，避免被误当成子文件夹进 git；进入前先确认该路径不存在同名文件夹。
+
 ## ⚠️ PR 冲突修复统一用临时 worktree
 
 - ⚠️ **修复 PR 与主分支的冲突时，一律使用临时 git worktree，禁止直接在当前工作副本上切换分支（`git checkout`）解题。** 原因：A-/B-/C-/M- 多副本仓库中，同一个克隆往往同时被其他开发任务占用；直接切分支会破坏别人正在进行的代码、或把自己卡在非主分支上。
@@ -266,6 +277,13 @@
 - 典型反例：`byteplus/seedance-2.0-mini` 视频生成，上游（火山引擎 t2v）拒绝 `resolution` 参数返回 400「the parameter resolution ... is not valid」，调度器仍按通用重试逻辑重试 3 次、每次同样 400，重试耗尽后模型被标成红色 failed 徽章，官网视频一直生成不出来。根因是「该参数不该传」这个确定性错误，重试多少次都不会成功。
 - 自查：写重试逻辑时先问「这次失败重试一次会不会成功？」会（瞬时故障）→ 重试；不会（确定性错误）→ 不重试，直接暴露根因/告警。看到「重试 N 次全部失败」时，第一反应必须是研究「为什么每次都会失败」，而不是加大重试次数或加长间隔。
 
+### ⑪ 对称实现缺失：同一约束在多条等价路径上漏同步 = 静默放行
+
+- ⚠️ 同一个业务约束（拦截、限额、准入、状态判断）如果有多条**等价的代码路径**（如普通路由 + 健康分路由、多入口函数、多套 switch），必须确认每条路径都实现了同一套约束——漏掉任意一条，那条路径就静默绕过约束，不报错、不告警，是最隐蔽的缺口。
+- **类比：小区有正门和好几个侧门，正门配了保安，但侧门忘了配——坏人绕一下就从没保安的侧门进去了，你还以为整个小区都有人守。**
+- 典型反例：MP-73 vendor 双预算封顶。准入函数 `accountSkip` 在普通路由（`providers/pool.go`）实现了 `case accountSkipVendorBudget`（vendor 超限 → 429），但健康分路由 `pool_health.go` 的 6 处 *2 系列 switch（GenerateText2/Stream2/Responses2/ResponsesStream2/GenerateContentNative2/GenerateContentStreamNative2）全部漏了这个 case，vendor 超限时落入 default 被放行、返回 200 而非 429——同一条约束，普通路由守了、健康分路由没守。
+- 自查：新增/修改拦截、限额、准入类约束时，先 `grep -rn "switch.*accountSkip\|case accountSkip"` 找出**所有消费同一枚举/函数的路径**，逐个核对是否都补了新 case；Go 的 switch 漏 case 会落入 default（静默放行）而不是编译报错，不能靠编译器兜底。
+
 ## ⚠️ 网关后端编码铁律（来自 PR 评审沉淀）
 
 ⚠️ 本章来自 routerhub-gateway 92 个已合入 PR 中多位评审者（hankWaling / baikaifa / sam-pomex / rachelPomex / eason-qing / enzo0824）的 review 评论沉淀，每条都有真实 PR 出处。写 Go 后端（网关/代理/计费/路由类）代码时对照本节自查。本节所有条目均为强制规则，命中即自检。

package/package.json

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

package/rules/global.md

@@ -117,6 +117,17 @@ name: "通用规则"
 - ⚠️ **已推送到远程的提交需要撤销时，必须用 `git revert`，禁止用 `git push --force` 覆盖远程历史。** `git revert` 会创建一条新的撤销提交，保留完整的操作记录，不影响其他协作者的本地分支；`git push --force` 会破坏远程历史，导致其他人的本地分支与远程脱节，极易引发合并冲突或丢失他人提交。
 - ⚠️ **提交并推送代码后，若发现与主分支存在冲突，必须主动解决**，不能推送完就算完事、把冲突留给别人处理。
 
+## ⚠️ 处理其他项目/副本时统一用 worktree 隔离（不改别人正在用的分支）
+
+- ⚠️ **需要修改某个仓库，而该仓库是多副本（A-/B-/C-/M- 前缀）且当前分支可能正被其他开发任务占用时，默认用临时 git worktree 隔离操作，禁止直接在当前工作副本上 `git checkout` 切换分支。** 多副本仓库中同一个克隆往往同时被多个任务使用：直接切分支会破坏别人正在进行的代码、或把自己卡在非主分支上。实例：`c-pomex-gateway` 正被 `feature/timeslot-pricing` 开发任务占用（落后 main 10 个提交），此时要做文档迁移，就用 `git worktree` 从 `origin/main` 检出到独立目录操作，feature 分支工作区完全不动。
+- ⚠️ **标准操作流程**：
+  1. 在仓库根目录执行 `git worktree add -b <任务分支> ../<任务>-work <基础分支>`（基础分支用 `origin/main` 或具体目标分支），独立目录检出并新建分支，当前工作副本完全不动。
+  2. 在 worktree 目录内完成改动 → 编译/测试通过 → `git push -u origin <任务分支>`。
+  3. 创建 PR（合并目标为仓库默认分支）。
+  4. 操作完成后 `git worktree remove ../<任务>-work` 清理，原副本分支状态不受影响。
+- ⚠️ **worktree 与主副本共享同一套本地 `.git`**，但工作目录、索引、当前分支状态完全独立，不会干扰正在 main 或其他分支上改动代码的协作者。
+- ⚠️ **worktree 目录默认在仓库根目录同级（`../`）**，避免被误当成子文件夹进 git；进入前先确认该路径不存在同名文件夹。
+
 ## ⚠️ PR 冲突修复统一用临时 worktree
 
 - ⚠️ **修复 PR 与主分支的冲突时，一律使用临时 git worktree，禁止直接在当前工作副本上切换分支（`git checkout`）解题。** 原因：A-/B-/C-/M- 多副本仓库中，同一个克隆往往同时被其他开发任务占用；直接切分支会破坏别人正在进行的代码、或把自己卡在非主分支上。
@@ -266,6 +277,13 @@ name: "通用规则"
 - 典型反例：`byteplus/seedance-2.0-mini` 视频生成，上游（火山引擎 t2v）拒绝 `resolution` 参数返回 400「the parameter resolution ... is not valid」，调度器仍按通用重试逻辑重试 3 次、每次同样 400，重试耗尽后模型被标成红色 failed 徽章，官网视频一直生成不出来。根因是「该参数不该传」这个确定性错误，重试多少次都不会成功。
 - 自查：写重试逻辑时先问「这次失败重试一次会不会成功？」会（瞬时故障）→ 重试；不会（确定性错误）→ 不重试，直接暴露根因/告警。看到「重试 N 次全部失败」时，第一反应必须是研究「为什么每次都会失败」，而不是加大重试次数或加长间隔。
 
+### ⑪ 对称实现缺失：同一约束在多条等价路径上漏同步 = 静默放行
+
+- ⚠️ 同一个业务约束（拦截、限额、准入、状态判断）如果有多条**等价的代码路径**（如普通路由 + 健康分路由、多入口函数、多套 switch），必须确认每条路径都实现了同一套约束——漏掉任意一条，那条路径就静默绕过约束，不报错、不告警，是最隐蔽的缺口。
+- **类比：小区有正门和好几个侧门，正门配了保安，但侧门忘了配——坏人绕一下就从没保安的侧门进去了，你还以为整个小区都有人守。**
+- 典型反例：MP-73 vendor 双预算封顶。准入函数 `accountSkip` 在普通路由（`providers/pool.go`）实现了 `case accountSkipVendorBudget`（vendor 超限 → 429），但健康分路由 `pool_health.go` 的 6 处 *2 系列 switch（GenerateText2/Stream2/Responses2/ResponsesStream2/GenerateContentNative2/GenerateContentStreamNative2）全部漏了这个 case，vendor 超限时落入 default 被放行、返回 200 而非 429——同一条约束，普通路由守了、健康分路由没守。
+- 自查：新增/修改拦截、限额、准入类约束时，先 `grep -rn "switch.*accountSkip\|case accountSkip"` 找出**所有消费同一枚举/函数的路径**，逐个核对是否都补了新 case；Go 的 switch 漏 case 会落入 default（静默放行）而不是编译报错，不能靠编译器兜底。
+
 ## ⚠️ 网关后端编码铁律（来自 PR 评审沉淀）
 
 ⚠️ 本章来自 routerhub-gateway 92 个已合入 PR 中多位评审者（hankWaling / baikaifa / sam-pomex / rachelPomex / eason-qing / enzo0824）的 review 评论沉淀，每条都有真实 PR 出处。写 Go 后端（网关/代理/计费/路由类）代码时对照本节自查。本节所有条目均为强制规则，命中即自检。