@routerhub/agent-rules 1.5.177 → 1.5.179

package/rules/global.md

@@ -10,9 +10,9 @@ name: "通用规则"
 
 - **新增、修改、删除规则，必须改 `AGENTS.base.md`（源文件），禁止直接改 `CLAUDE.md` 或 `AGENTS.md`**。改完后必须执行 `node merge.js sync` 重新生成输出文件。
 - ⚠️ **新增行为/指令时，先判断该放规则还是 Skill**：
-  - **规则（Rule）**：始终生效的约束，如代码风格、命名规范、行为要求、注释规范。写入 `AGENTS.base.md`。
-  - **Skill**：多步骤操作流程，需按需调用，如部署、发 PR、Figma 还原、TDD 流程。新建 `skills/技能名/SKILL.md`。
-  - **判断标准**：「这件事每次写代码都要遵守吗？」→ 是 = 规则，否（只有特定场景才触发）= Skill。
+    - **规则（Rule）**：始终生效的约束，如代码风格、命名规范、行为要求、注释规范。写入 `AGENTS.base.md`。
+    - **Skill**：多步骤操作流程，需按需调用，如部署、发 PR、Figma 还原、TDD 流程。新建 `skills/技能名/SKILL.md`。
+    - **判断标准**：「这件事每次写代码都要遵守吗？」→ 是 = 规则，否（只有特定场景才触发）= Skill。
 
 ## 语言与内容
 
@@ -27,12 +27,12 @@ name: "通用规则"
 
 ## ⚠️ 环境配置禁止推断
 
-- ⚠️ **写代码或注释涉及环境相关的值（域名、地址、端口、密钥、外部服务 URL 等）时，禁止根据已知值类推未知值**（例如「测试是 api-test.xxx，那生产应该就是 api.xxx」）。必须从以下来源至少一处交叉确认：
-  1. 项目内的部署脚本、Dockerfile、CI 配置
-  2. 实际 DNS 解析（`dig`/`nslookup`）
-  3. 云平台控制台（Cloud Run 域名映射、GCLB、Ingress 等）
+- ⚠️ **写代码或注释涉及环境相关的值（域名、地址、端口、密钥、外部服务 URL 等）时，禁止根据已知值类推未知值**（例如「测试是 api-test.xxx，那生产应该就是 api.xxx」）。必须从以下来源至少一处交��确认：
+1. 项目内的部署脚本、Dockerfile、CI 配置
+2. 实际 DNS 解析（`dig`/`nslookup`）
+3. 云平台控制台（Cloud Run 域名映射、GCLB、Ingress 等）
 - ⚠️ **上述来源都找不到的，就写「待确认」或留空，禁止自行补全。** 错误的推断值比留空危害更大——留空会在运行时报错、立刻暴露；错误的推断值可能静默运行数月后才被发现（如请求打到了错误的环境），排查成本极高。
-- ⚠️ **代码中使用环境变量占位符（如 `process.env.XXX`）时，必须同时确认测试/生产部署脚本（或配置中心）已提供该变量的具体值。** 禁止只写占位符不落地——代码能编译不代表部署后取值非空。具体值的存放规则：敏感值（密钥、Token 等）必须配到 Nacos 配置中心，禁止写进部署脚本；非敏感值（域名、地址、端口、外部服务 URL 等）写入测试/生产各自的部署脚本。部署脚本中找不到的值仍按本规则写「待确认」或留空，禁止自行补全。
+- ⚠️ **代码中使用环境变量占位符（如 `process.env.XXX`）时，必须同时确认测试/生产部署脚本（或配置中心）已提供该变量的具体值。** 禁止只写占位符不落地——代码能编译不代表部署���取值非空。具体值的存放规则：敏感值（密钥、Token 等）必须配到 Nacos 配置中心，禁止写进部署脚本；非敏感值（域名、地址、端口、外部服务 URL 等）写入测试/生产各自的部署脚本。部署脚本中找不到的值仍按本规则写「待确认」或留空，禁止自行补全。
 - ⚠️ **部署生产前必须做「部署脚本配置 vs 线上实际环境」对账，禁止直接信任部署脚本里的环境值。** 部署脚本常是多人接力维护的产物，其中的 PROJECT / 服务名 / Nacos namespace / 数据库名可能被中途改掉、与线上真实环境脱节——脚本能跑、能编译、甚至部署能成功（Cloud Run 生成新 revision），但流量不接、数据不对，直到有人切流量才暴露（静默脱节）。实例（SolarX 生产事故 2026-08）：部署脚本 `PROJECT=solarisx-api` / Nacos `f8703bd7`，线上实际服务却是 `solarisx-503302` / Nacos `638c11fe`，两套环境并存从未对齐，导致 admin/console 前端 nginx 注入错误后端、gateway 连错库，线上被迫切回旧版。**动手前必做的对账动作**：`gcloud config get-value project` 核对项目、`gcloud run services list` 核对真实服务名、核对 Nacos namespace 与库名；对不上 → 停下来问用户，绝不按脚本直接部署。
 
 ## ⚠️ 可部署性自包含铁律（写代码之前考虑）
@@ -40,9 +40,9 @@ name: "通用规则"
 - ⚠️ **写任何逻辑、用任何环境变量/配置值之前，必须先把"这个改动上线后部署怎么办"想清楚**：能直接写死的就写死，该放部署脚本的就放部署脚本，该配配置中心的就配配置中心。所有环境准备（建表、迁移、字段变更、初始化/导入数据、配置下发）一律内嵌到部署脚本自动完成。**达成的效果：上线时只需执行部署脚本，数据库迁移、人工改配置等一切操作全部免掉，上线后零操心。**
 - ⚠️ **触发时机是写代码之前，不是部署的时候。** 禁止先写代码、等要部署了再补部署脚本。每写一个涉及环境准备的改动，部署逻辑必须随之一起落地，不允许"代码完成、部署待办"的中间态。
 - ⚠️ **写完涉及环境准备的改动，必须当场自查三问**（参考 DELETE 铁律格式；任一答案为「是」而部署脚本无对应逻辑 → **该改动不算完成**）：
-  1. **改数据库了吗？** 新增/修改表、字段或数据 → 部署脚本必须有幂等 schema 确保逻辑（如 `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`、`ensure_xxx()` 前置函数），加列/建表失败即停止部署。
-  2. **改配置了吗？** 新增/修改环境变量、Nacos 配置、部署脚本值 → 具体值必须已落地部署脚本或配置中心，禁止只写占位符或"待确认"。
-  3. **要初始化/搬运数据吗？** 需要初始化、导入、转换数据 → 必须脚本化进部署流程自动完成。
+1. **改数据库了吗？** 新增/修改表、字段或数据 → 部署脚本必须有幂等 schema 确保逻辑（如 `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`、`ensure_xxx()` 前置函数），加列/建表失败即停止部署。
+2. **改配置了吗？** 新增/修改环境变量、Nacos 配置、部署脚本值 → 具体值必须已落地部署脚本或配置中心，禁止只写占位符或"待确认"。
+3. **要初始化/搬运数据吗？** 需要初始化、导入、转换数据 → 必须脚本化进部署流程自动完成。
 - ⚠️ **发现「部署后还需要手动补步骤」= 部署流程有缺口**：一旦某次部署发现还要人工执行迁移、导数据、改配置等步骤功能才能用，必须当场把该步骤自动化进部署脚本，禁止继续靠记性每次手动补。**人为手动步骤是上线遗漏的根源**（测试环境做了、生产环境容易忘）。
 - ⚠️ **部署完成的定义 = 脚本执行完 → 功能直接可用 → 期间零人工补操作。** 未满足「零人工补操作」的部署不算完成，禁止在还需手动补步骤时宣称部署完成。
 - ⚠️ **「部署可用」≠「功能已验证」**：部署自动化到位只保证环境就绪、功能直接可操作；功能是否正确，仍需按既有验证铁律用真实数据验证，两者不冲突。
@@ -51,8 +51,8 @@ name: "通用规则"
 
 - ⚠️ **在测试环境验证任何涉及新增表/新增字段的功能（如充值、退款、发票，不限于这些）之前，必须先确认数据库表结构已就绪。** 测试环境 AutoMigrate 默认关闭（见「Go 规则」），新表/新字段不会随代码自动创建。跳过这一步直接验证，报出的缺表/缺字段错误是环境问题，不是代码问题，极易误判。
 - ⚠️ **验证前必须显式执行以下任一前置动作，禁止跳过：**
-  1. **临时打开 AutoMigrate 开关**，启动/重启服务完成建表后，恢复默认关闭；
-  2. **手动执行幂等建表/加字段 SQL**（`CREATE TABLE IF NOT EXISTS` / `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`），并确认目标表/字段已存在。
+1. **临时打开 AutoMigrate 开关**，启动/重启服务完成建表后，恢复默认关闭；
+2. **手动执行幂等建表/加字段 SQL**（`CREATE TABLE IF NOT EXISTS` / `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`），并确认目标表/字段已存在。
 - ⚠️ **遇到缺表/缺字段类报错时，第一优先级检查表结构是否就绪，禁止直接定性为代码 bug。** 特征报错：`relation "..." does not exist`、`table ... does not exist`、`column ... does not exist`、`Unknown column`、`Unrecognized name` 等。先查表（`\d 表名` / `DESCRIBE` / `information_schema`）确认就绪后再排查代码。
 
 ## ⚠️ 排查与协作铁律
@@ -67,7 +67,7 @@ name: "通用规则"
 - ⚠️ **定位并修复根因后，必须清理诊断过程中留下的临时改动**（调试代码、临时开关、测试脚本），不要把绕过方案的残留物留在代码里。
 - **某个工具/脚本报错时，先检查是否有残留的锁文件、临时文件、缓存导致的问题**，清理后重试；仍失败再切换备用方案，不要一遇报错就直接换路子。
 - **长任务或涉及截图等大内容的操作，注意控制单次传入的数据量**（压缩、降低分辨率等），避免不必要地占满上下文。
-- ⚠️ **用户反馈"看起来没生效/没写入"时，先用权威数据源核实**（直连数据库/调对应 API 查，而不是只信一次前端页面截图），前端页面可能存在多个同名视图、未展开的关联表、缓存等歧义，容易把"看错了地方"误判成"修复失败"，也可能反过来把真的失败误判成"看错了"——两种方向都要用权威数据源排除，不能靠肉眼猜。
+- ⚠️ **用户反馈"看起来没生效/没写入"时，先用权威数据源核实**（直连数据库/调对应 API 查，而不是只信一次前端页面截图），前端页面可能存在多个同名视图、未��开的关联表、缓存等歧义，容易把"看错了地方"误判成"修复失败"，也可能反过来把真的失败误判成"看错了"——两种方向都要用权威数据源排除，不能靠肉眼猜。
 - ⚠️ **停用/归档任何仍可能被其他配置引用的共享资源（数据库、开关、服务实例、旧接口等）前，必须先确认所有引用方已经完成切换**，禁止先下线资源、后补救引用；正确顺序是「新资源就位 → 所有引用方切到新资源并验证 → 确认无引用后才下线旧资源」。
 - ⚠️ **对「只增不改」的追加型数据表（日志表、流水表）做分批消费时，禁止用「每次从头查 + LIMIT 截断 + 幂等去重」的无状态写法**。无断点的全量查询每次都会返回最早的一批行（早已消费、被幂等跳过、不产生任何效果），而新行永远排在 LIMIT 之外——扣款/同步在数据量超过单批上限后静默停滞，不报错、不崩溃，余额/进度「悄悄不涨不降」，是最阴险的静默 bug（offset-pagination 饥荒）。正确写法是带「进度断点」的增量查询：**按业务排序键（如时间+ID）记录上次消费位置（游标），下轮用 `WHERE 排序键 > 断点` 的严格排他下界续拉，消费成功后游标单调推进到批次末尾**，保证不重也不漏。判断标准：只要处理逻辑会「跳过已处理的记录」且「数据量可能超过单批上限」，就必须用游标/断点，而非从头扫。
 
@@ -95,18 +95,18 @@ name: "通用规则"
 
 - ⚠️ **AI 默认禁止主动写「测试用例」**（单元测试、Playwright E2E、API 冒烟脚本等）。写不写测试、写哪些，完全由用户显式提出（如「加测试」「写测试用例」「补一条回归用例」）才执行。AI 不得在未获明确指令时自行创建测试用例、主动建议补测试、或把「测试先行 / TDD」当作默认开发姿势。
 - ⚠️ **功能验证的第一交付物是可视化证据报告，而不是测试断言。** AI 每做一个功能/修复，必须用「真实数据 + 真实交互 + 可视化证据」证明给用户看（遵循「⚠️ 修复验证铁律」「⚠️ 截图规范」）：
-  1. **页面/界面改动** → 打开真实页面，用真实数据走真实交互，全页截图 + 箭头标注关键改动区域；
-  2. **涉及 Redis**（缓存、计数器、限流、Session 等）→ 直接查看 Redis 运行时的 key/value（用 Redis for VS Code 插件页截图），A/B 对比改动前后的值；
-  3. **涉及数据库** → 直接查看数据库运行时数据（用 SQLTools 插件截图），A/B 对比改动前后的值。
-  优先让用户配合一起截图（用户是真人验证关卡：截图里的数据必须是真实的，AI 不得用 mock/虚构数据凑证据）。生成的验证报告是给用户看的，用户能一眼判断功能对不对，禁止把「AI 自己写、AI 自己看」的测试断言当作交付完成。
+1. **页面/界面改动** → 打开真实页面，用真实数据走真实交互，全页截图 + 箭头标注关键改动区域；
+2. **涉及 Redis**（缓存、计数器、限流、Session 等）→ 直接查看 Redis 运行时的 key/value（用 Redis for VS Code 插件页截图），A/B 对比改动前后的值；
+3. **涉及数据库** → 直接查看数据库运行时数据（用 SQLTools 插件截图），A/B 对比改动前后的���。
+   优先让用户配合一起截图（用户是真人验证关卡：截图里的数据必须是真实的，AI 不得用 mock/虚构数据凑证据）。生成的验证报告是给用户看的，用户能一眼判断功能对不对，禁止把「AI 自己写、AI 自己看」的测试断言当作交付完成。
 - ⚠️ **只有以下两类情况才允许写测试用例（有明确触发路径，非默认行为）**：
-  1. **时序/并发/缓存失效类逻辑**：问题出在「某个时刻的状态」，截图截不出来（如并发竞态、延迟失效），必须写测试来证明行为正确；
-  2. **回归事故补种**：出现「改 A 把 B 改坏」的回归事故后，当场为出问题的点补一条回归测试，防止同类问题再次悄悄发生。
+1. **时序/并发/缓存失效类逻辑**：问题出在「某个时刻的状态」，截图截不出来（如并发竞态、延迟失效），必须写测试来证明行为正确；
+2. **回归事故补种**：出现「改 A 把 B 改坏」的回归事故后，当场为出问题的点补一条回归测试，防止同类问题再次悄悄发生。
 - ⚠️ **禁止写测试 ≠ 允许带着基本错误交付。** AI 改完代码至少必须跑通编译 / 类型检查 / 最小冒烟，能自行发现并修复语法、类型、启动崩溃这类基本错误后再交付验证。连基本错误都发现不了就交付，比不写测试更糟。
 - ⚠️ **判断标准：这个功能用户能不能在页面上操作？**
-  - 能 → 必须用真实页面交互验证，能模拟用户手动测试就手动，并截图留证；
-  - 不能（纯后端接口、定时任务、无页面入口的链路）→ 用运行时真实返回验证（curl/日志/查库/查 Redis），并把结果渲染成可视化证据（暗色终端风格的请求/响应对比 HTML 截图，或 Redis/SQLTools 插件截图）。
-- ⚠️ **验证结论必须基于运行时真实数据，禁止用 mock/虚构数据自测。** 真实数据会暴露边界情况（空值、超长文本、特殊字符、异常关联关系等），虚构数据碰不到这些。测试环境有真实数据时优先用测试环境；测试环境数据不足时，从生产环境脱敏导出。
+    - 能 → 必须用真实页面交互验证，能模拟用户手动测试就手动，并截图留证；
+    - 不能（纯后端接口、定时任务、无页面入口的链路）→ 用运行时真实返回验证（curl/日志/查库/查 Redis），并把结果渲染成可视化证据（暗色终端风格的请求/响应对比 HTML 截图，或 Redis/SQLTools 插件截图）。
+- ⚠️ **验证结论必须基于运行时真实数据，禁止用 mock/虚构数据自测。** 真实数据会暴露边界情况（空值、超长文本、特殊字符、异常关联关系等），��构数据碰不到这些。测试环境有真实数据时优先用测试环境；测试环境数据不足时，从生产环境脱敏导出。
 
 ## Git 规范
 
@@ -121,10 +121,10 @@ name: "通用规则"
 
 - ⚠️ **需要修改某个仓库，而该仓库是多副本（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` 清理，原副本分支状态不受影响。
+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；进入前先确认该路径不存在同名文件夹。
 
@@ -132,10 +132,10 @@ name: "通用规则"
 
 - ⚠️ **修复 PR 与主分支的冲突时，一律使用临时 git worktree，禁止直接在当前工作副本上切换分支（`git checkout`）解题。** 原因：A-/B-/C-/M- 多副本仓库中，同一个克隆往往同时被其他开发任务占用；直接切分支会破坏别人正在进行的代码、或把自己卡在非主分支上。
 - ⚠️ **标准操作流程**：
-  1. 在仓库根目录执行 `git worktree add ../<pr>-fix <PR分支名> --detach`（或 `-b` 新建一个与 PR 分支同名的分支），临时分离出来用独立目录操作，当前工作副本状态完全不动。
-  2. 在 worktree 目录里 `git merge origin/main`（或 `git rebase origin/main`）→ 解决冲突文件 → 本地测试通过。
-  3. `git push` 推送回 PR 分支（须确认 push 目标为 origin 的对应 PR 分支，禁止 `--force`）。
-  4. 操作完成后用 `git worktree remove ../<pr>-fix` 清理临时 worktree，再回到原副本继续。
+1. 在仓库根目录执行 `git worktree add ../<pr>-fix <PR分支名> --detach`（或 `-b` 新建一个与 PR 分支同名的分支），临时分离出来用独立目录操作，当前工作副本状态完全不动。
+2. 在 worktree 目录里 `git merge origin/main`（或 `git rebase origin/main`）→ 解决冲突文件 → 本地测试通过。
+3. `git push` 推送回 PR 分支（须确认 push 目标为 origin 的对应 PR 分支，禁止 `--force`）。
+4. 操作完成后用 `git worktree remove ../<pr>-fix` 清理临时 worktree，再回到原副本继续。
 - ⚠️ **worktree 与主副本共享同一套本地 `.git`**，但工作目录、索引、当前分支状态完全独立，不会干扰正在 main 或其他分支上改动代码的协作者。
 - ⚠️ **worktree 目录默认在仓库根目录同级（`../`）**，避免被误当成子文件夹进 git；进入前先确认该路径不存在同名文件夹。
 
@@ -146,10 +146,10 @@ name: "通用规则"
 - **检测优先**：动手前先 `git worktree list`，若当前路径已在某个 worktree 内 → 直接用当前 worktree，禁止再套一层嵌套 worktree；只有不在 worktree 里且要写代码 → 按下面流程新建。
 - **复用场景（不新建）**：明确是「接着上一次会话/任务的未提交工作继续干」→ 回到原来的 worktree 目录继续，禁止另开新的而把未提交工作丢在原处。
 - ⚠️ **标准操作流程**：
-  1. `git fetch origin main`，确保基于最新远程主分支（`fetch` 不动主工作区，避免与其他会话占用冲突，比 `pull` 更安全）。
-  2. `git worktree add -b feature/<任务简称> ../<会话标识>-work origin/main`——从 `origin/main` 检出到独立目录并新建分支，当前工作区完全不动。目录名用英文小写中划线（含会话唯一标识），进入前先确认该路径不存在。
-  3. 在 worktree 目录内完成改动 → 编译/验证通过 → `git commit` → `git push -u origin feature/<任务简称>`。
-  4. 任务结束（提交完成 / PR 合并）后 `git worktree remove ../<会话标识>-work` 清理。一个会话全程只对应一个 worktree。
+1. `git fetch origin main`，确保基于最新远程主分支（`fetch` 不动主工作区，避免与其他会话占用冲突，比 `pull` 更安全）。
+2. `git worktree add -b feature/<任务简称> ../<会话标识>-work origin/main`——从 `origin/main` 检出到独立目录并新建分支，当前工作区完全不动。目录名用英文小写中划线（含会话唯一标识），进入前先确认该路径不存在。
+3. 在 worktree 目录内完成改动 → 编译/验证通过 → `git commit` → `git push -u origin feature/<任务简称>`。
+4. 任务结束（提交完成 / PR 合并）后 `git worktree remove ../<会话标识>-work` 清理。一个会话全程只对应一个 worktree。
 - ⚠️ **多副本仓库（A-/B-/C-/M- 前缀）叠加生效**：worktree 建在当前会话所在副本内（选哪个副本由「⚠️ 处理其他项目/副本时统一用 worktree 隔离」规则决定），本条规则负责副本内部的会话隔离，两者不冲突。
 - ⚠️ **worktree 只隔离「文件与 git」这一层**：端口、数据库、构建缓存、浏览器标签页等外部资源仍按各自规则隔离（如 agent-browser `--namespace`）。两个会话若改同一批文件，编辑阶段互不可见，冲突会推迟到合并回主分支时显式暴露——改动明显重叠的任务应合成一个会话完成，不要拆成两个 worktree 并行。
 
@@ -157,28 +157,28 @@ name: "通用规则"
 
 - ⚠️ PR Title / Description / Test Plan 全部中文。
 - ⚠️ **PR 必须附效果截图作为可视化证据，且逐条满足以下硬性要求（缺一不可，禁止跳过）**：
-  - **全页图**：用浏览器真实视口（`window.innerWidth` 即截图宽度，4K 屏自然宽 3840）`fullPage` 截完整页面，禁止只截视口一屏。⚠️ **禁止强制把视口硬拉成 3840 宽**——浏览器视口宽由屏幕实际分辨率决定，硬拉宽会让内容按比例缩小（看不清），且与截图像素发生缩放错位，是标注不准的根因之一。若要更高清晰度，用 `set viewport <W> <H> 2`（DPR 倍率）提高渲染精度（CSS 宽不变、像素更密），而不是拉宽 CSS 视口。
-  - **全面多角度**：一张全页图 + 每个关键改动区域的局部放大图，多个改动点要逐个覆盖，确保 reviewer 不看代码就能看全本次全部改动。
-  - **箭头标注（必须标注准）**：每张截图必须用醒目箭头 + 简短文字标签标注关键改动区域/验证点（修复前红框/红箭头、修复后绿框/绿箭头），标注放在不遮挡原内容的位置，禁止只贴裸图不标注。⚠️ **标注坐标必须来自浏览器 DOM 测量（`getBoundingClientRect()` + `scrollX/scrollY`）精确换算成截图像素，禁止肉眼看图估坐标**——全页拼接/缩放截图里 CSS 坐标 ≠ 截图像素，肉眼估位是标注不准的直接原因。标注统一走 `/screenshot-annotate` skill（坐标换算方法 + `annotate.js` 统一脚本）。
-  - **URL 可见**：截图中必须能看到当前页面 URL，确保证据可追溯。
-  - **前后对比**：必须同时展示修复前与修复后。
+    - **全页图**：用浏览器真实视口（`window.innerWidth` 即截图宽度，4K 屏自然宽 3840）`fullPage` 截完整页面，禁止只截视口一屏。⚠️ **禁止强制把视口硬拉成 3840 宽**——浏览器视口宽由屏幕实际分辨率决定，硬拉宽会让内容按比例缩小（看不清），且与截图像素发生缩放错位，是标注不准的根因之一。若要更高清晰度，用 `set viewport <W> <H> 2`（DPR 倍率）提高渲染精度（CSS 宽不变、像素更密），而不是拉宽 CSS 视口。
+    - **全面多角度**：一张全页图 + 每个关键改动区域的局部放大图，多个改动点要逐个覆盖，确保 reviewer 不看代码就能看全本次全部改动。
+    - **箭头标注（必须标注准）**：每张截图必须用醒目箭头 + 简短文字标签标注关键改动区域/验证点（修复前红框/红箭头、修复后绿框/绿箭头），标注放在不遮挡原内容的位置，禁止只贴裸图不标注。⚠️ **标注坐标必须来自浏览器 DOM 测量（`getBoundingClientRect()` + `scrollX/scrollY`）精确换算成截图像素，禁止肉眼看图估坐标**——全页拼接/缩放截图里 CSS 坐标 ≠ 截图像素，肉眼估位是标注不准的直接原因。标注统一走 `/screenshot-annotate` skill（坐标换算方法 + `annotate.js` 统一脚本）。
+    - **URL 可见**：截图中必须能看到当前页面 URL，确保证据可追溯。
+    - **前后对比**：必须同时展示修复前与修复后。
 - ⚠️ **截图必须直接内嵌在 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 创建即进入可评审状态**：直接创建正式 PR（非 Draft），创建完成、冲突检查与静态编译通过后即可直接交付 review，禁止先开 Draft PR、后续再手动标记 Ready for review。
-- ⚠️ **创建 PR 后必须先过 CI 再进入后续流程**：创建完成后第一时间执行 `gh pr checks <PR>`（必要时轮询直到非 `pending`）。若有任一检查 `failure`，必须先定位并修复失败项、推送新提交并复查到全部 `success`，然后才能进入循环 review、测试验证、交付 review 等后续步骤，禁止带红 CI 继续往下走。
+- ⚠️ **创建 PR 后必须先过 CI 再进入后续流程**：创建完成后第一时间执行 `gh pr checks <PR>`（必要时轮询直到非 `pending`）。若有任一检查 `failure`，必须���定位并修复失败项、推送新提交并复查到全部 `success`，然后才能进入循环 review、测试验证、交付 review 等后续步骤，禁止带红 CI 继续往下走。
 - ⚠️ **每次修改 PR 后（含创建 PR、push 新提交、响应 review 意见重新推送等所有改动 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 可能在后续 push 后悄悄变冲突，因此每次改动 PR 后都必须重新检查，禁止只在创建时查一次就以为高枕无忧。
 - ⚠️ **每次修改 PR 后，除冲突检查外还必须检查 GitHub 静态编译是否通过，通过后发新版本**，三步收尾缺一不可：
-  1. **与主分支冲突检查**：按上一条规则执行（`gh pr view <PR> --json mergeable -q .mergeable`），有冲突必须先解决。
-  2. **GitHub 静态编译检查**：用 `gh pr checks <PR>` 查看 CI 检查状态（`success`=通过，`failure`=失败，`pending`=进行中）。存在失败项时，必须定位失败根因、修改代码并重新推送，直到全部通过，禁止把静态编译未通过的 PR 抛给 reviewer。
-  3. **发新版本**：PR 合并后按项目发布流程发布新版本（本项目统一执行根目录 `./release.sh`，自动完成 patch 版本号 +1、更新 package.json、`git commit`/`push`、打 tag、`npm publish`）。
+1. **与主分支冲突检查**：按上一条规则执行（`gh pr view <PR> --json mergeable -q .mergeable`），有冲突必须先解决。
+2. **GitHub 静态编译检查**：用 `gh pr checks <PR>` 查看 CI 检查状态（`success`=通过，`failure`=失败，`pending`=进行中）。存在失败项时，必须定位失败根因、修改代码并重新推送，直到全部通过，禁止把静态编译未通过的 PR 抛给 reviewer。
+3. **发新版本**：PR 合并后按项目发布流程发布新版本（本项目统一执行根目录 `./release.sh`，自动完成 patch 版本号 +1、更新 package.json、`git commit`/`push`、打 tag、`npm publish`）。
 - ⚠️ **创建完 PR 后自动走完整闭环流程，未走完不算完成**：创建 PR → 循环 review → 重新部署测试环境验证 → 确认没问题 → 发 PR 链接给用户 → 发新版本，六步缺一不可，全程自动执行：
-  1. **自动走循环 review**：创建完 PR 后自动触发 `/loop-review` skill，反复「拉取 AI review（Claude Opus + GPT 交叉验证）→ 逐条读真实代码判断哪些值得修 → 值得修的改、不值得修/误报的 Won't fix 切断 → push 触发新一轮 review」，直到某一轮不再冒出值得修的新问题才结束，禁止只跑一轮就收工。**循环 review 走完后，必须显式输出「✅ 循环 review 完成，进入发布收尾闭环」，并调用 `/pr-release-loop` skill 走完后续步骤。**
-  2. **重新部署到测试环境（循环 review 后最容易漏掉的一步）**：循环 review 走完后，自动触发 `/deploy-test` skill，把最新代码重新部署到测试环境，确保测试的是循环 review 之后的最终代码。⚠️ **循环 review 期间每次修复都会 push 新 commit；不重新部署 = 测试环境跑的还是 review 之前的旧代码 = 用旧代码验证新改动 = 结论无效。因此循环 review 结束后禁止直接发 PR 链接 / 发版，必须先 `/deploy-test` 重部署。**
-  3. **测试环境验证 + 全程截图标注**：在测试环境用真实数据、真实页面交互测试本次改动（遵循「⚠️ 页面功能验证铁律」「⚠️ 用户视角测试铁律」）。测试过程中每一步都截图保留（遵循「⚠️ 截图规范」：真实视口 + `fullPage` 全页、URL 可见、存盘到 `screenshots/` 临时目录），并在每张截图上用**坐标换算后的箭头标注**（走 `/screenshot-annotate` skill）关键改动区域/验证点，让看的人一眼看懂这张图证明了什么。
-  4. **确认没问题才算完成**：测试通过、截图与箭头标注齐全、功能符合预期，才算真正完成。禁止测试没跑、截图没标注就宣称完成。
-  5. **把 PR 链接发给用户**：确认没问题后，先把 PR 链接发送给用户（`gh pr view <PR> --json url -q .url`），让用户能直接打开查看，再执行发版。
-  6. **发新版本**：确认没问题、PR 链接已发送后，按上面三步收尾完成冲突检查与静态编译检查，PR 合并后执行根目录 `./release.sh` 发新版本。
+1. **自动走循环 review**：创建完 PR 后自动触发 `/loop-review` skill，反复「拉取 AI review（Claude Opus + GPT 交叉验证）→ 逐条读真实代码判断哪些值得修 → 值得修的改、不值得修/误报的 Won't fix 切断 → push 触发新一轮 review」，直到某一轮不再冒出值得修的新问题才结束，禁止只跑一轮就收工。**循环 review 走完后，必须显式输出「✅ 循环 review 完成，进入发布收尾闭环」，并调用 `/pr-release-loop` skill 走完后续步骤。**
+2. **重新部署到测试环境（循环 review 后最容易漏掉的一步）**：循环 review 走完后，自动触发 `/deploy-test` skill，把最新代码重新部署到测试环境，确保测试的是循环 review 之后的最终代码。⚠️ **循环 review 期间每次修复都会 push 新 commit；不重新部署 = 测试环境跑的还是 review 之前的旧代码 = 用旧代码验证新改动 = 结论无效。因此循环 review 结束后禁止直接发 PR 链接 / 发版，必须先 `/deploy-test` 重部署。**
+3. **测试环境验证 + 全程截图标注**：在测试环境用真实数据、真实页面交互测试本次改动（遵循「⚠️ 页面功能验证铁律」「⚠️ 用户视角测试铁律」）。测试过程中每一步都截图保留（遵循「⚠️ 截图规范」：真实视口 + `fullPage` 全页、URL 可见、存盘到 `screenshots/` 临时目录），并在每张截图上用**坐标换算后的箭头标注**（走 `/screenshot-annotate` skill）关键改动区域/验证点，让看的人一眼看懂这张图证明了什么。
+4. **确认没问题才算完成**：测试通过、截图与箭头标注齐全、功能符合预期，才算真正完成。禁止测试没跑、截图没标注就宣称完成。
+5. **把 PR 链接发给用户**：确认没问题后，先把 PR 链接发送给用户（`gh pr view <PR> --json url -q .url`），让用户能直接打开查看，再执行发版。
+6. **发新版本**：确认没问题、PR 链接已发送后，按上面三步收尾完成冲突检查与静态编译检查，PR 合并后执行根目录 `./release.sh` 发新版本。
 - ⚠️ **私有仓库的 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 引用」的流程，图片链接一律拼接为后一种格式。
 
 ## 安全
@@ -194,10 +194,10 @@ name: "通用规则"
 ### 2. 机密/证书的获取方式：部署时确定且几乎不变 → 优先平台注入
 
 - ⚠️ **运行时需要的机密 / 证书 / 配置，若其特点是「部署时确定、几乎不变化（只在发版时才更新）」，优先用平台注入（Cloud Run `--update-secrets` / K8s Secret 挂载为环境变量），而不是运行时调 Secret Manager / 配置中心去拉。** 判断依据：
-  - 运行时拉取多一层故障点（超时 / 权限 / 网络任一挂掉 → 业务 fail-closed）、多一套解析与护栏代码；
-  - `versions/latest` 轮换后仍需重启进程才生效，「热更新」是伪优势；
-  - 两种方式安全效果等价，平台注入更简单、更稳；
-  - 若公司已有同类服务在生产采用某种方式，优先对齐，不另造一套。
+    - 运行时拉取多一层故障点（超时 / 权限 / 网络任一挂掉 → 业务 fail-closed）、多一套解析与护栏代码；
+    - `versions/latest` 轮换后仍需重启进程才生效，「热更新」是伪优势；
+    - 两种方式安全效果等价，平台注入更简单、更稳；
+    - 若公司已有同类服务在生产采用某种方式，优先对齐，不另造一套。
 
 ## 代码风格
 
@@ -352,7 +352,7 @@ name: "通用规则"
 - ⚠️ **请求带了但不支持的参数禁止静默忽略**：必须显式 4xx 报错——静默忽略让客户端误以为参数生效，是沉默失败。
 - ⚠️ **路由/解析 switch default 分支禁止静默 skip+warn**：静默跳过会让路由表悄悄缺模型/缺路由；应显式报错或强告警。路由收窄/拆池前先查全量数据分布。**依赖「客户端/上游不会这么发」假设的丢弃/忽略分支，必须打日志**：假设一旦被打破（上游发来畸形数据），生产可诊断，禁止静默丢弃。
 - ⚠️ **失败路径也要补全归属字段**：成功/失败覆盖一致（失败 usage 事件也要回填 ProviderAccountId 等），否则某个账号持续失败时按账号排查不出来。
-- ⚠️ **清理/剥离函数必须清「实际被填充」的字段**：核对写入方填哪个字段、清理方清哪个字段，二者对齐；只清自己认识的字段、漏掉写入方真正填的，等于没清。
+- ⚠️ **清理/剥离函数必须清「实际被填充」的字段**：核对写入方填哪个字段、清理方清哪个字��，二者对齐；只清自己认识的字段、漏掉写入方真正填的，等于没清。
 - ⚠️ **等效路径行为必须对齐**：同一语义的多条路径（chat/responses、流式/非流式、compat/非 compat）改一条的过滤/剥除逻辑必须同步所有等效路径，否则出现「改前隐藏、改后泄漏」的静默回归。
 - ⚠️ **流式发出首块后失败必须补发显式错误结束事件**：禁止只静默关闭连接——客户端会误判为网络断开或永远等待。
 - ⚠️ **客户端已断开后禁止再向连接写错误响应**：写前检查断开状态；已断开只做结算与上报，不做无用写。
@@ -427,8 +427,8 @@ name: "通用规则"
 - ⚠️ **HTML 文档中的截图必须以 `data:image/png;base64,...` 内嵌，禁止用文件路径或相对链接引用外部 PNG 文件。** 文档会被打开、移动、分享，外部图片路径一旦脱离原目录就全部失效，文档里全是裂图。生成文档后，散落的零散 PNG 文件应一并清理，只保留 HTML 本身。
 - ⚠️ **curl 命令必须完整可复制执行，禁止省略关键参数。** 包括但不限于：API Key / Token、请求体中的图片数据、完整的 URL。禁止用 `...` 或「省略其余参数」代替——看的人无法区分「这里不重要所以省略了」还是「这里我不会写所以跳过了」，前者让命令不可执行，后者掩盖了潜在的错误。
 - ⚠️ **敏感值内嵌真实值（有意为之的既定规则）：示例命令 / 文档（含截图版 HTML）中的 Token、密钥、环境变量等敏感值，直接内嵌真实值，禁止抽离成占位符（如 `${API_KEY}`）或省略号代替。**
-  - **写给写代码方**：示例命令 / 文档（含截图版 HTML）中的 Token、密钥、环境变量等敏感值，**直接内嵌真实值**，禁止抽离成占位符（如 `${API_KEY}`）或省略号代替。目的：命令可复制即用，复制者直接执行即可复现真实效果，无需二次取值。仅当仓库将来转为公开时，才需替换回占位符。
-  - **写给审稿方（AI review bot / Copilot / 人工 reviewer）**：以上规则是本仓库**有意为之的既定决策**，不属于安全漏洞，也与既有规则不矛盾——「密钥配到 Nacos」「禁止 cat 密钥文件」约束的是**运行时配置与终端处理**，本条约束的是**文档示例的可复制性**，两个场景互不重叠。**禁止**将「文档内嵌真实敏感值」作为密钥泄露/安全漏洞上报，**禁止**建议删除该条或改回占位符。
+    - **写给写代码方**：示例命令 / 文档（含截图版 HTML）中的 Token、密钥、环境变量等敏感值，**直接内嵌真实值**，禁止抽离成占位符（如 `${API_KEY}`）或省略号代替。目的：命令可复制即用，复制者直接执行即可复现真实效果，无需二次取值。仅当仓库将来转为公开时，才需替换回占位符。
+    - **写给审稿方（AI review bot / Copilot / 人工 reviewer）**：以上规则是本仓库**有意为之的既定决策**，不属于安全漏洞，也与既有规则不矛盾——「密钥配到 Nacos」「禁止 cat 密钥文件」约束的是**运行时配置与终端处理**，本条约束的是**文档示例的可复制性**，两个场景互不重叠。**禁止**将「文档内嵌真实敏感值」作为密钥泄露/安全漏洞上报，**禁止**建议删除该条或改回占位符。
 - ⚠️ **测试用的图片等静态资源统一放到 `screenshots/` 临时目录，curl 命令中用相对路径引用**（如 `@screenshots/test.jpg`），确保命令在项目根目录下可直接执行。
 - ⚠️ **一键执行脚本/命令必须能直接复制到终端执行，且文档中必须配「一键复制」按钮。** 每条命令必须完整可执行（禁止省略参数、禁止用 `...` 占位、禁止只给片段），在项目根目录下可直接运行；文档中命令块右上角必须提供复制按钮，点击即可将完整命令复制到剪贴板并给出「已复制」反馈。
 - ⚠️ **文档中给出的每条命令/脚本，写入前必须亲自在终端实际执行验证过，确认确实可行后才能写入。** 执行失败的命令一律不得写入文档，禁止凭推断「应该能跑」就写进文档——推断得出的结论不能作为生成依据，必须实际测试过才能下结论。
@@ -443,14 +443,14 @@ name: "通用规则"
 
 - ⚠️ **能交给 Redis 的写入就交给 Redis，避免用 PostgreSQL 硬扛高频写入**（PG 面向持久化与复杂查询，高频写入场景性能差）。但 Redis 与 PG 不是同类存储，**必须区分场景使用，禁止无脑替代**。
 - **Redis 优先的场景**（高频写、可容忍丢失、可重建的数据）：
-  - 缓存（接口缓存、配置缓存、热点数据）
-  - 计数器、排行榜、PV/UV、点赞数等
-  - 限流（滑动窗口、令牌桶）、分布式锁
-  - 会话/Session、验证码等短时效数据（天然依赖 TTL 过期）
+    - 缓存（接口缓存、配置缓存、热点数据）
+    - 计数器、排行榜、PV/UV、点赞数等
+    - 限流（滑动窗口、令牌桶）、分布式锁
+    - 会话/Session、验证码等短时效数据（天然依赖 TTL 过期）
 - **PostgreSQL 保留的场景**（不能丢、要按条件查、要事务）：
-  - 业务主体数据（订单、用户、商品、账单等需要事务与持久化的数据）
-  - 需要复杂 SQL 查询、联表、报表统计的数据
-  - 需要长期保留、生命周期远大于缓存时长的数据
+    - 业务主体数据（订单、用户、商品、账单等需要事务与持久化的数据）
+    - 需要复杂 SQL 查询、联表、报表统计的数据
+    - 需要长期保留、生命周期远大于缓存时长的数据
 - ⚠️ **判定标准**：落库前先问三个问题——「这份数据丢了行不行？」「需不需要按条件查？」「需不需要事务？」。只要有一个答案是「需要/不行」，就必须用 PostgreSQL；三个都是「可以丢 / 不用查 / 不用事务」，才优先用 Redis。
 - ⚠️ **Redis 只能做加速层，禁止作为唯一数据源承载不可重建的业务数据**——默认未开启持久化时进程重启数据即丢，Redis 中的数据必须能由上游（数据库/消息队列）重建。
 
@@ -458,23 +458,23 @@ name: "通用规则"
 
 - ⚠️ **DELETE 是数据库中唯一不可逆的写操作**（INSERT 可以删、UPDATE 可以回改，DELETE 执行后数据消失，只有备份能救）。因此 DELETE 的每一条都必须经过严格的「副作用范围检查」：
 
-  **副作用范围必须 ≤ 用户显式意图范围。**
+**副作用范围必须 ≤ 用户显式意图范围。**
 
-  也就是说：如果用户删了 A，代码只能删 A，绝不能顺便把 B、C、D 也删了。
+也就是说：如果用户删了 A，代码只能删 A，绝不能顺便把 B、C、D 也删了。
 
 - ⚠️ **每写一条 DELETE 语句，必须能在注释中回答以下三个问题**：
-  1. **删什么？** 精确到表名和筛选条件
-  2. **为什么在这里删？** 业务场景是什么（用户点了哪个按钮/执行了什么操作）
-  3. **最多影响多少行？** 如果用户操作 1 条记录，这条 DELETE 最多删几行？答案 ≠ 1 时，逻辑大概率有缺陷
-
+1. **删什么？** 精确到表名和筛选条件
+2. **为什么在这里删？** 业务场景是什么（用户点了哪个按钮/执行了什么操作）
+3. **最多影响多少行？** 如果用户操作 1 条记录，这条 DELETE 最多删几行？答案 ≠ 1 时，逻辑大概率有缺陷
 - ⚠️ **写路径禁止「全量同步」语义**。典型的错误模式：
-  ```sql
+
+```sql
   -- ❌ 危险：用「当前这次操作的数据」作为基准去删掉所有其他数据
   DELETE FROM t WHERE id NOT IN (本次操作涉及的一条/几条id)
 
   -- ✅ 安全：删除用户显式标记为「已删除」的记录
   DELETE FROM t WHERE status = 'deleted' AND deleted_by = 当前用户
-  ```
+```
 
 - ⚠️ **清理过期数据/元数据时，DELETE 条件必须精确到「过期标记」字段**（如 `expired_at < NOW()`），不能依赖「不在某个列表中」这种间接条件。
 
@@ -495,10 +495,10 @@ name: "通用规则"
 
 - ⚠️ **域名访问 404 时，禁止优先假设是 DNS 问题**。DNS 只负责把域名解析到 IP，能解析到正确 IP 但仍 404，说明问题在 IP 之后的路由链路上（负载均衡 / API 网关 / 反向代理的路由规则），必须先排查这一层，而不是重新配置 DNS。
 - 排查顺序（以 GCP GCLB 为例，其他云 / Nginx / API Gateway 同理）：
-  1. 确认域名解析到的 IP 由哪个转发规则（forwarding rule）监听
-  2. 找到该转发规则挂的 target-proxy → url-map
-  3. `describe` 该 url-map，重点看 `defaultService` 和 `hostRules`/`pathMatchers`——**404 常见根因是 url-map 只有 defaultService，指向的后端服务根本没部署这条路径**，而不是网络层不通
-  4. 直连后端服务（跳过网关）验证该路径本身是否存在，确认问题就在"网关路由配置"而非"服务本身"
+1. 确认域名解析到的 IP 由哪个转发规则（forwarding rule）监听
+2. 找到该转发规则挂的 target-proxy → url-map
+3. `describe` 该 url-map，重点看 `defaultService` 和 `hostRules`/`pathMatchers`——**404 常见根因是 url-map 只有 defaultService，指向的后端服务根本没部署这条路径**，而不是网络层不通
+4. 直连后端服务（跳过网关）验证该路径本身是否存在，确认问题就在"网关路由配置"而非"服务本身"
 - ⚠️ **修复共享网关配置时必须只做新增（additive-only），不得动原有 defaultService/pathRules**：新增一个独立的 backend service/NEG，在 url-map 上新增一个只作用于目标 host 的 pathMatcher，并显式将该 pathMatcher 自己的 `defaultService` 设置为原有的 backend service，确保其余所有路径行为不变。
 - 配置变更后如果立刻 curl 仍 404，先怀疑网关配置生效延迟（GCLB 常见有数十秒传播延迟），可用"直连后端验证"+"带 Host header 直连网关 IP 验证"两步排除"配置写错"和"还没生效"两种可能，再决定是否继续修改配置。
 
@@ -506,11 +506,11 @@ name: "通用规则"
 
 - ⚠️ **给新域名配置 DNS 解析前，必须先建好负载均衡并拿到静态 IP，再把这个 IP 交给配置 DNS 的人，禁止反过来先让人家配域名、再等 IP。** 顺序错了一次 DNS 就要改两次，而且 Google 托管证书依赖「域名 A 记录已指向 LB IP」才能自动签发——没有 IP 就配 A 记录，证书会一直卡在 FAILED_NOT_VISIBLE。
 - 标准流程：
-  1. 建 GCLB 负载均衡（以 HeliosX 体系为例，Serverless NEG → Cloud Run 后端），7 层链路缺一不可：静态 IP → 转发规则(443) → Target HTTPS Proxy → SSL 证书(Google 托管) → URL Map → Backend Service → Serverless NEG → Cloud Run 服务。
-  2. 从静态 IP 资源取到 IP（例如 8.232.47.30）。
-  3. 把这个 IP 连同「配一条 A 记录」的指令一起交给对方（对方唯一要做的：加一条 A 记录 → 名称 api-test / 值 8.232.47.30）。
-  4. 对方配好 A 记录后，证书会自动签发（FAILED_NOT_VISIBLE → ACTIVE），无需手动验证。
-  5. 证书 ACTIVE 后，才跑端到端验证（HTTPS 访问、留资流程等）。
+1. 建 GCLB 负载均衡（以 HeliosX 体系为例，Serverless NEG → Cloud Run 后端），7 层链路缺一不可：静态 IP → 转发规则(443) → Target HTTPS Proxy → SSL 证书(Google 托管) → URL Map → Backend Service → Serverless NEG → Cloud Run 服务。
+2. 从静态 IP 资源取到 IP（例如 8.232.47.30）。
+3. 把这个 IP 连同「配一条 A 记录」的指令一起交给对方（对方唯一要做的：加一条 A 记录 → 名称 api-test / 值 8.232.47.30）。
+4. 对方配好 A 记录后，证书会自动签发（FAILED_NOT_VISIBLE → ACTIVE），无需手动验证。
+5. 证书 ACTIVE 后，才跑端到端验证（HTTPS 访问、留资流程等）。
 - ⚠️ **给对方的信息必须把「负载均衡已建好 + IP」放在最显眼位置，明确告诉他「你只需要配一条 A 记录」**，避免对方误以为要自己去建 LB 或改一堆东西。
 
 ## 基础设施修复后代码 Workaround 清理规范
@@ -531,15 +531,19 @@ name: "通用规则"
 上线（部署生产、切流量、更新线上版本）的唯一不可接受后果是：**新版本有问题直接接流量，把原本正常服务顶崩**。上线必须走完以下四环，缺一不可；任何一环未过即中止，禁止带着未验证的环节继续。这里的核心是「你叫我怎样就怎样」行不通——**上线动作必须等校验全部通过才执行**。
 
 **环1 · 部署前环境对账**（详见「⚠️ 环境配置禁止推断」章节）
+
 - 脚本配置（PROJECT / 服务名 / Nacos namespace / 数据库 / 域名 / 后端 Host）与线上实际逐项对账（`gcloud config get-value project`、`gcloud run services list`、Nacos），对不上 → 先改脚本或停下问，禁止带疑似错误配置部署。
 
 **环2 · 部署前脚本通读 + 脚本自检**（详见上方「部署规则」两条铁律）
+
 - 通读一遍部署脚本再执行，禁止盲跑；脚本须内置「环境自检」（PROJECT 一致 / 目标服务存在 / Nacos 与库一致 / 后端 Host 非默认值），不一致即 abort；无自检先补上再跑。
 
 **环3 · 部署中先下不发（防「一上去就崩」的关键）**
+
 - 部署必须 `--no-traffic`（新 revision 保持 0% 流量），用 revision 临时 URL 验证新版本：日志无 ERROR、连对本环境库、关键接口 200、核心功能可跑通。**验证通过之前，禁止把流量切到新版本；禁止让 `gcloud run deploy` 默认把 100% 流量切到新 revision。**
 
 **环4 · 切流量渐进 + 全程可回滚**
+
 - 后端渐进切流量（5% → 观察 → 50% → 100%）；前端静态资源验证后一次性切。
 - 切流量前记录当前线上 revision 号；任何一步验证不过，`update-traffic --to-revision <旧版>` 秒切回，恢复线上原状后再排查。
 
@@ -557,10 +561,10 @@ name: "通用规则"
 - 新建文档使用 `/create-doc` skill：纯文字/表格类 → 直接写 MD 直传；截图版报告 → 生成 HTML → 无头 Chrome 转 PDF → push 到 `<项目>-docs` 私有仓库的 `docs` 分支 → 在代码仓库 `docs/index.html` 记录「文档名 | 链接」。
 - 文档链接格式：`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.<pdf|md>`，粘贴到浏览器即可查看（GitHub 内嵌渲染 PDF / Markdown；私有仓库未登录会跳登录页）。
 - ⚠️ **迁移项目既有文档到 `<项目>-docs` 前，先区分「纯文档」与「代码资产 / 对外服务页面」，禁止一刀切全迁**：
-  - **对外服务的 API 文档站**（gateway 类项目的 `docs/`：含 `index.html` + `authentication.html` + `css/` + `js/` + `nginx.conf.template` 的整套站点）是**线上产品页面**，随模型/接口持续更新（git log 常有「添加 xxx 模型」等提交），线上 URL 可访问（如 `https://xxx/docs` 返回 200）——这类**不能迁**，迁走线上直接 404。判断标准：线上有对应 URL 且能访问 → 是对外服务页面，不是内部文档。
-  - **散落文档目录**（`inter_docs/`、`local_docs/`、`design_docs/`、`internal/xxx/docs/`）里常**混着代码**：需求/设计/测试说明（.md）旁边就有集成测试脚本（.sh）、用例（.sql/.json）、env 模板、甚至被 Go 代码运行时引用的路径（如 `filepath.Join(repoRoot, "inter_docs", ...)`）。迁移前必须逐目录核对：**纯 .md 文档 → 迁；.sh/.sql/.json/.env 及被代码引用的路径 → 必须留在原位**，禁止连脚本一起搬走（搬走就破坏测试链路和运行时）。
-  - **类比：搬书房前先分清楚「书」和「记账本」**——书（纯文档）搬进藏书库（-docs 仓库），记账本（测试脚本/被引用的配置）得留在桌上随时用；把记账本也塞进藏书库，下次算账（跑测试）就找不到本子了。
-  - 核对方法：迁移前 `grep -rn "目录名"` 搜代码/CI/脚本，确认哪些路径被引用；被引用的保留，未被引用的纯文档才迁。
+    - **对外服务的 API 文档站**（gateway 类项目的 `docs/`：含 `index.html` + `authentication.html` + `css/` + `js/` + `nginx.conf.template` 的整套站点）是**线上产品页面**，随模型/接口持续更新（git log 常有「添加 xxx 模型」等提交），线上 URL 可访问（如 `https://xxx/docs` 返回 200）——这类**不能迁**，迁走线上直接 404。判断标准：线上有对应 URL 且能访问 → 是对外服务页面，不是内部文档。
+    - **散落文档目录**（`inter_docs/`、`local_docs/`、`design_docs/`、`internal/xxx/docs/`）里常**混着代码**：需求/设计/测试说明（.md）旁边就有集成测试脚本（.sh）、用例（.sql/.json）、env 模板、甚至被 Go 代码运行时引用的路径（如 `filepath.Join(repoRoot, "inter_docs", ...)`）。迁移前必须逐目录核对：**纯 .md 文档 → 迁；.sh/.sql/.json/.env 及被代码引用的路径 → 必须留在原位**，禁止连脚本一起搬走（搬走就破坏测试链路和运行时）。
+    - **类比：搬书房前先分清楚「书」和「记账本」**——书（纯文档）搬进藏书库（-docs 仓库），记账本（测试脚本/被引用的配置）得留在桌上随时用；把记账本也塞进藏书库，下次算账（跑测试）就找不到本子了。
+    - 核对方法：迁移前 `grep -rn "目录名"` 搜代码/CI/脚本，确认哪些路径被引用；被引用的保留，未被引用的纯文档才迁。
 
 ## 文档/文件链接交付
 
@@ -588,6 +592,7 @@ name: "通用规则"
 任务的页面）。
 
 **必须遵守**：
+
 1. 每次浏览器操作都固定带专属 `--namespace <会话唯一标识>`，同一会话全程不变。
 2. 不信任「当前活动页是哪一页」。任何操作前先 `agent-browser tab` 列出标签页，
    按 URL 特征找到自己的页，再执行操作；**把「切到自己的 tab + 全部操作」合并进

package/rules/go-backend.md

@@ -6,4 +6,4 @@ outputName: "go-backend"
 
 ## Go 后端规则
 
-<!-- Go 后端特有规则在此添加 -->
+<!-- Go 后端规则 特有规则在此添加 -->

package/rules/review-boundary.md

@@ -51,7 +51,7 @@ outputName: "review-boundary"
 ⚠️ diff 出现带金钱/权限/路由后果的数值判定（`==`、`!=`、`HasPrefix`、`>=`、`default:` 等），必须对判定的反面和补集提三问，确认覆盖再认可：
 
 1. **排除项的孪生项**：`if status == "failed"` 排除后，同级的 `in_progress` / `searching` / 空串走哪个分支？判定的全集是什么？只盯着被排除的那一个，会漏掉其余状态的归属。
-2. **默认分支的安全方向**：未命中（`default:` / 最后 return）在金钱上朝哪边偏？朝「漏收」还是「多收」？哪个方向会造成静默的账面偏差。
+2. **默认分支的安全方向**：未命中（`default:` / 最后 return）在金钱上朝哪边偏？朝「漏收」��是「多收」？哪个方向会造成静默的账面偏差。
 3. **数值有核对来源吗**：常量数值（如 10_000 / 25_000）是对过上游公开报价，还是随手拍的？没核对来源的定价常量 → 必须报（呼应「环境配置禁止推断」）。
 
 **③ 以行为变更表为主攻目标**
@@ -76,6 +76,7 @@ outputName: "review-boundary"
 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").

package/rules/notion-devops.md

@@ -1,9 +0,0 @@
----
-name: "Notion 同步 · DevOps 规则"
-applyTo: ["**/Dockerfile","**/Dockerfile.*","**/docker-compose*.yml","**/docker-compose*.yaml","**/*.sh","**/.gitlab-ci.yml","**/.github/workflows/*.yml","**/.github/workflows/*.yaml"]
-outputName: "notion-devops"
----
-
-### 🚨 测试环境部署铁律（不可跳过）
-
-- ⚠️ **部署到测试环境唯一入口：`/deploy-test` skill**，必须先合并再部署、部署后切回原分支，严禁跳过合并步骤直接部署功能分支（完整流程见该 skill）。

package/rules/notion-frontend.md

@@ -1,12 +0,0 @@
----
-name: "Notion 同步 · 前端规则"
-applyTo: ["**/*.ts","**/*.tsx","**/*.js","**/*.jsx","**/*.vue","**/*.css","**/*.scss"]
-outputName: "notion-frontend"
----
-
-- ⚠️ **默认隐藏滚动条**：页面/容器出现滚动需求时，滚动条默认隐藏（内容仍可正常滚动），不得让滚动条可见。仅当用户明确说「需要滚动条」「可以有滚动条」「显示滚动条」等表述时，才允许显示。
-- ⚠️ **依赖安装统一 `pnpm`**，禁止 `npm install` / `yarn install`（pnpm workspace 混合安装会破坏依赖结构）。
-- ⚠️ **API 请求严格使用 OpenAPI 生成的方法，禁止手写请求或直接拼接路径**；接口变更后先更新 OpenAPI 定义并重新生成 API 代码，再进行业务开发。
-- ⚠️ **用 `console.error` 记录错误**（含函数名/模块名上下文），禁止用 `console.log` 输出错误；提交前移除调试日志和临时代码。
-- ⚠️ **调试过程中产生的中间产物（临时文件、测试脚本、调试截图、dump 文件、临时注释、`console.log` 等）禁止加入 Git 提交**，`.gitignore` 中应配置忽略常见中间产物。
-- TypeScript 类型优先复用 `api` 文件夹下 `typings.d.ts`，不存在时再自定义；组件 `props` 能复用时必须优先复用。