@routerhub/agent-rules 1.5.104 → 1.5.106

package/AGENTS.base.md

@@ -24,6 +24,14 @@
 - ⚠️ 严格按用户原话实现需求，禁止擅自添加用户未要求的限制、规则或约束。
 - ⚠️ 不确定某个限制是否必要时，必须先询问用户，禁止直接添加。
 
+## ⚠️ 环境配置禁止推断
+
+- ⚠️ **写代码或注释涉及环境相关的值（域名、地址、端口、密钥、外部服务 URL 等）时，禁止根据已知值类推未知值**（例如「测试是 api-test.xxx，那生产应该就是 api.xxx」）。必须从以下来源至少一处交叉确认：
+  1. 项目内的部署脚本、Dockerfile、CI 配置
+  2. 实际 DNS 解析（`dig`/`nslookup`）
+  3. 云平台控制台（Cloud Run 域名映射、GCLB、Ingress 等）
+- ⚠️ **上述来源都找不到的，就写「待确认」或留空，禁止自行补全。** 错误的推断值比留空危害更大——留空会在运行时报错、立刻暴露；错误的推断值可能静默运行数月后才被发现（如请求打到了错误的环境），排查成本极高。
+
 ## ⚠️ 排查与协作铁律
 
 - ⚠️ **排查「以前能用、现在不行」类问题时禁止用绕过手段掩盖问题**（改配置屏蔽报错、写同步脚本搬数据、临时禁用校验等），必须先定位根因再修复。
@@ -39,6 +47,15 @@
 - ⚠️ **用户反馈"看起来没生效/没写入"时，先用权威数据源核实**（直连数据库/调对应 API 查，而不是只信一次前端页面截图），前端页面可能存在多个同名视图、未展开的关联表、缓存等歧义，容易把"看错了地方"误判成"修复失败"，也可能反过来把真的失败误判成"看错了"——两种方向都要用权威数据源排除，不能靠肉眼猜。
 - ⚠️ **停用/归档任何仍可能被其他配置引用的共享资源（数据库、开关、服务实例、旧接口等）前，必须先确认所有引用方已经完成切换**，禁止先下线资源、后补救引用；正确顺序是「新资源就位 → 所有引用方切到新资源并验证 → 确认无引用后才下线旧资源」。
 
+## ⚠️ 修复验证铁律
+
+- ⚠️ **验证方法必须"可确定性复现"，优先选最直白的路径。** 不要依赖真实流量、后台任务或时序巧合去凑出被验证的状态（反直觉、难复现、别人无法照做）。判断顺序：先问「本次修复的唯一改动是什么」，把它精确映射成一个可手动触发的原子操作，再做 A/B 对照。例：验证"余额变更后网关缓存立即失效"，不要靠真实计费请求养缓存，而是直接 `SET` 种一个已知值 → `GET`（有值 = 修复前）→ `DEL`（= 失效动作）→ `GET`（nil = 修复后）。
+- ⚠️ **报告开头必带一张「为什么这样验证成立」的原理说明卡。** 先讲清楚 bug 前后差异的本质是哪一个动作，再论证"手动模拟该动作 = 真实场景"，让不了解背景的人也能信服。配一张修复前 vs 修复后的 A/B 对照表（代码行为 / 等价操作 / 观测结果三列并排）。
+- ⚠️ **每个验证步骤必须三要素齐全**：① 怎么做的（可复制粘贴的完整命令）② 结果（含可复查标识：执行 ID、时间戳、返回码）③ 这一步证明了什么（一句话点明证据含义，如"DEL 返回 1 = 删除前 key 确实存在"）。
+- ⚠️ **采用「主验证 + 真实链路佐证」双证据结构。** 主验证用最简单直观的方式（如直接看值）确保人人能复现；再补一条端到端真实链路证据（如真实日志、双侧时间戳对齐），把"手动演示"和"真实业务动作"接上，二者相互印证。
+- ⚠️ **截图是可视化证据，图注必须写清「这张图证明了什么」**，并标注关键行/关键数据（红框、箭头放在空白区，不遮挡原内容）。
+- ⚠️ **结论用「证据并列」呈现**：逐条列出每类证据的关键数值和可复查标识（执行 ID / 时间戳），最后一句量化修复效果（如"陈旧窗口从约 30 分钟压缩到 ≈0"）。
+
 ## Git 规范
 
 - 分支用 Git Flow（`feature/`、`bugfix/`、`hotfix/`、`refactor/`、`chore/`、`docs/`、`test/`），英文小写中划线分隔。

package/package.json

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

package/rules/global.md

@@ -24,6 +24,14 @@ name: "通用规则"
 - ⚠️ 严格按用户原话实现需求，禁止擅自添加用户未要求的限制、规则或约束。
 - ⚠️ 不确定某个限制是否必要时，必须先询问用户，禁止直接添加。
 
+## ⚠️ 环境配置禁止推断
+
+- ⚠️ **写代码或注释涉及环境相关的值（域名、地址、端口、密钥、外部服务 URL 等）时，禁止根据已知值类推未知值**（例如「测试是 api-test.xxx，那生产应该就是 api.xxx」）。必须从以下来源至少一处交叉确认：
+  1. 项目内的部署脚本、Dockerfile、CI 配置
+  2. 实际 DNS 解析（`dig`/`nslookup`）
+  3. 云平台控制台（Cloud Run 域名映射、GCLB、Ingress 等）
+- ⚠️ **上述来源都找不到的，就写「待确认」或留空，禁止自行补全。** 错误的推断值比留空危害更大——留空会在运行时报错、立刻暴露；错误的推断值可能静默运行数月后才被发现（如请求打到了错误的环境），排查成本极高。
+
 ## ⚠️ 排查与协作铁律
 
 - ⚠️ **排查「以前能用、现在不行」类问题时禁止用绕过手段掩盖问题**（改配置屏蔽报错、写同步脚本搬数据、临时禁用校验等），必须先定位根因再修复。
@@ -39,6 +47,15 @@ name: "通用规则"
 - ⚠️ **用户反馈"看起来没生效/没写入"时，先用权威数据源核实**（直连数据库/调对应 API 查，而不是只信一次前端页面截图），前端页面可能存在多个同名视图、未展开的关联表、缓存等歧义，容易把"看错了地方"误判成"修复失败"，也可能反过来把真的失败误判成"看错了"——两种方向都要用权威数据源排除，不能靠肉眼猜。
 - ⚠️ **停用/归档任何仍可能被其他配置引用的共享资源（数据库、开关、服务实例、旧接口等）前，必须先确认所有引用方已经完成切换**，禁止先下线资源、后补救引用；正确顺序是「新资源就位 → 所有引用方切到新资源并验证 → 确认无引用后才下线旧资源」。
 
+## ⚠️ 修复验证铁律
+
+- ⚠️ **验证方法必须"可确定性复现"，优先选最直白的路径。** 不要依赖真实流量、后台任务或时序巧合去凑出被验证的状态（反直觉、难复现、别人无法照做）。判断顺序：先问「本次修复的唯一改动是什么」，把它精确映射成一个可手动触发的原子操作，再做 A/B 对照。例：验证"余额变更后网关缓存立即失效"，不要靠真实计费请求养缓存，而是直接 `SET` 种一个已知值 → `GET`（有值 = 修复前）→ `DEL`（= 失效动作）→ `GET`（nil = 修复后）。
+- ⚠️ **报告开头必带一张「为什么这样验证成立」的原理说明卡。** 先讲清楚 bug 前后差异的本质是哪一个动作，再论证"手动模拟该动作 = 真实场景"，让不了解背景的人也能信服。配一张修复前 vs 修复后的 A/B 对照表（代码行为 / 等价操作 / 观测结果三列并排）。
+- ⚠️ **每个验证步骤必须三要素齐全**：① 怎么做的（可复制粘贴的完整命令）② 结果（含可复查标识：执行 ID、时间戳、返回码）③ 这一步证明了什么（一句话点明证据含义，如"DEL 返回 1 = 删除前 key 确实存在"）。
+- ⚠️ **采用「主验证 + 真实链路佐证」双证据结构。** 主验证用最简单直观的方式（如直接看值）确保人人能复现；再补一条端到端真实链路证据（如真实日志、双侧时间戳对齐），把"手动演示"和"真实业务动作"接上，二者相互印证。
+- ⚠️ **截图是可视化证据，图注必须写清「这张图证明了什么」**，并标注关键行/关键数据（红框、箭头放在空白区，不遮挡原内容）。
+- ⚠️ **结论用「证据并列」呈现**：逐条列出每类证据的关键数值和可复查标识（执行 ID / 时间戳），最后一句量化修复效果（如"陈旧窗口从约 30 分钟压缩到 ≈0"）。
+
 ## Git 规范
 
 - 分支用 Git Flow（`feature/`、`bugfix/`、`hotfix/`、`refactor/`、`chore/`、`docs/`、`test/`），英文小写中划线分隔。