@routerhub/agent-rules 1.5.116 → 1.5.118

package/AGENTS.base.md

@@ -31,6 +31,7 @@
   2. 实际 DNS 解析（`dig`/`nslookup`）
   3. 云平台控制台（Cloud Run 域名映射、GCLB、Ingress 等）
 - ⚠️ **上述来源都找不到的，就写「待确认」或留空，禁止自行补全。** 错误的推断值比留空危害更大——留空会在运行时报错、立刻暴露；错误的推断值可能静默运行数月后才被发现（如请求打到了错误的环境），排查成本极高。
+- ⚠️ **代码中使用环境变量占位符（如 `process.env.XXX`）时，必须同时确认测试/生产部署脚本（或配置中心）已提供该变量的具体值。** 禁止只写占位符不落地——代码能编译不代表部署后取值非空。具体值的存放规则：敏感值（密钥、Token 等）必须配到 Nacos 配置中心，禁止写进部署脚本；非敏感值（域名、地址、端口、外部服务 URL 等）写入测试/生产各自的部署脚本。部署脚本中找不到的值仍按本规则写「待确认」或留空，禁止自行补全。
 
 ## ⚠️ 排查与协作铁律
 
@@ -211,6 +212,7 @@
 
 - ⚠️ **问题根因是"某个被多个服务/项目共用的基础设施配置（网关、负载均衡器、DNS、Ingress、防火墙规则、共享中间件/代理配置、共享配置中心 namespace 等）转发或配置错了"时，禁止把"直接改这个共享配置"当作默认修复方案**。共享基础设施上的改动会波及所有依赖它的其他流量/服务，波及范围和风险几乎总是大于当前这一个问题本身。优先方案是在自己服务的边界内收敛解决——如直连正确后端的独立地址、加一层自己控制的适配/转发，而不触碰上游共享设施。
 - ⚠️ **评估后确认必须改共享基础设施本身才能修复时，必须先向用户说明改动内容和影响范围（这份配置还被哪些其他服务/流量依赖），得到明确确认后才能执行**，禁止在诊断过程中把"顺手改一下共享配置"当成常规修复步骤直接执行——这类改动一旦出错，影响的不是一个功能，而是所有依赖这份共享配置的系统。
+- ⚠️ **共享存储字段变更（如 BigQuery 表加列、共享 DB 加字段）是最容易漏的手动步骤**：这类资源由多个系统共享（写入方、读取方、传输层），天然不在单一部署脚本的「本能覆盖范围」内。每次新增/修改后端读取的字段，必须同步检查对应的共享存储是否已加列/加字段，并把「幂等确保存在」逻辑内嵌进部署脚本（如 `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`、`bq mk if-not-exists`、幂等的 `ensure_xxx()` 前置函数），而不是留给运维手动跑一次。参考模式：`deploy_backend()` 内先调用幂等 `ensure_usage_logs_schema()` 再部署，加列失败即停止部署，不产生「接口挂」的中间态；代码层面再加列存在性动态检测兜底（缺列时优雅降级，不报 `Unrecognized name`）。
 
 ## 网关/负载均衡 404 排查规范
 

package/package.json

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

package/rules/global.md

@@ -31,6 +31,7 @@ name: "通用规则"
   2. 实际 DNS 解析（`dig`/`nslookup`）
   3. 云平台控制台（Cloud Run 域名映射、GCLB、Ingress 等）
 - ⚠️ **上述来源都找不到的，就写「待确认」或留空，禁止自行补全。** 错误的推断值比留空危害更大——留空会在运行时报错、立刻暴露；错误的推断值可能静默运行数月后才被发现（如请求打到了错误的环境），排查成本极高。
+- ⚠️ **代码中使用环境变量占位符（如 `process.env.XXX`）时，必须同时确认测试/生产部署脚本（或配置中心）已提供该变量的具体值。** 禁止只写占位符不落地——代码能编译不代表部署后取值非空。具体值的存放规则：敏感值（密钥、Token 等）必须配到 Nacos 配置中心，禁止写进部署脚本；非敏感值（域名、地址、端口、外部服务 URL 等）写入测试/生产各自的部署脚本。部署脚本中找不到的值仍按本规则写「待确认」或留空，禁止自行补全。
 
 ## ⚠️ 排查与协作铁律
 
@@ -211,6 +212,7 @@ name: "通用规则"
 
 - ⚠️ **问题根因是"某个被多个服务/项目共用的基础设施配置（网关、负载均衡器、DNS、Ingress、防火墙规则、共享中间件/代理配置、共享配置中心 namespace 等）转发或配置错了"时，禁止把"直接改这个共享配置"当作默认修复方案**。共享基础设施上的改动会波及所有依赖它的其他流量/服务，波及范围和风险几乎总是大于当前这一个问题本身。优先方案是在自己服务的边界内收敛解决——如直连正确后端的独立地址、加一层自己控制的适配/转发，而不触碰上游共享设施。
 - ⚠️ **评估后确认必须改共享基础设施本身才能修复时，必须先向用户说明改动内容和影响范围（这份配置还被哪些其他服务/流量依赖），得到明确确认后才能执行**，禁止在诊断过程中把"顺手改一下共享配置"当成常规修复步骤直接执行——这类改动一旦出错，影响的不是一个功能，而是所有依赖这份共享配置的系统。
+- ⚠️ **共享存储字段变更（如 BigQuery 表加列、共享 DB 加字段）是最容易漏的手动步骤**：这类资源由多个系统共享（写入方、读取方、传输层），天然不在单一部署脚本的「本能覆盖范围」内。每次新增/修改后端读取的字段，必须同步检查对应的共享存储是否已加列/加字段，并把「幂等确保存在」逻辑内嵌进部署脚本（如 `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`、`bq mk if-not-exists`、幂等的 `ensure_xxx()` 前置函数），而不是留给运维手动跑一次。参考模式：`deploy_backend()` 内先调用幂等 `ensure_usage_logs_schema()` 再部署，加列失败即停止部署，不产生「接口挂」的中间态；代码层面再加列存在性动态检测兜底（缺列时优雅降级，不报 `Unrecognized name`）。
 
 ## 网关/负载均衡 404 排查规范