@routerhub/agent-rules 1.5.156 → 1.5.158

package/AGENTS.base.md

@@ -33,6 +33,7 @@
   3. 云平台控制台（Cloud Run 域名映射、GCLB、Ingress 等）
 - ⚠️ **上述来源都找不到的，就写「待确认」或留空，禁止自行补全。** 错误的推断值比留空危害更大——留空会在运行时报错、立刻暴露；错误的推断值可能静默运行数月后才被发现（如请求打到了错误的环境），排查成本极高。
 - ⚠️ **代码中使用环境变量占位符（如 `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 与库名；对不上 → 停下来问用户，绝不按脚本直接部署。
 
 ## ⚠️ 可部署性自包含铁律（写代码之前考虑）
 
@@ -456,6 +457,8 @@
 
 - 发版统一执行 `./release.sh`。（自包含铁律见上方「⚠️ 可部署性自包含铁律」章节）
 - ⚠️ 部署测试环境必须使用 `/deploy-test` skill，严禁跳过 skill 直接执行部署操作（合并/推送/部署/切回的具体流程见该 skill）。
+- ⚠️ **部署生产前必须通读一遍部署脚本再执行，禁止盲跑。** 部署脚本是多人接力的产物，其中任何一行环境值（PROJECT / 服务名 / Nacos namespace / 数据库 / 域名 / 后端 Host / VPC / 密钥名）都可能被中途改错、与线上真实环境脱节——脚本能跑、能编译、甚至能部署成功，但连的是错环境。执行前逐行核对脚本配置与线上实际（`gcloud config get-value project`、`gcloud run services list`、Nacos 配置），对不上 → 先改脚本或停下来问，禁止带着疑似错误的配置直接部署（呼应「环境配置禁止推断」）。
+- ⚠️ **部署脚本必须内置「环境自检」：在真正执行部署动作之前，先自动校验脚本配置与线上环境一致，不一致即中止（abort），禁止在环境未验证的情况下执行 deploy。** 校验项至少包括：① PROJECT 与 `gcloud config get-value project` 一致；② 目标 Cloud Run 服务真实存在；③ Nacos namespace / 库名与线上一致；④ 前端代理的后端 Host（BACKEND_RUN_HOST）指向本环境后端，而非 Dockerfile 默认值或他环境。**目标脚本若没有自检逻辑，执行者必须先补上再跑——禁止「无自检的脚本直接部署」。** 参照 agent-rules 自身 `release.sh` 的「规则漂移检查」（发版前强制校验规则已同步、未同步即中止），把「人记得校验」升级为「脚本强制校验」。
 
 ## ⚠️ 配置中心变更生效铁律
 

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 所有对 @routerhub/agent-rules 的重大更改都会记录在这个文件中。
 
+## [1.5.158] - 2026-08-29
+
+### Added
+
+- **「部署规则」新增两条部署安全铁律（SolarX 事故延续教训）**：
+  1. **部署生产前必须通读部署脚本再执行，禁止盲跑**——脚本是多人接力维护的产物，任意环境值（PROJECT/服务名/Nacos namespace/数据库/域名/后端 Host/VPC/密钥名）都可能被改错或与线上脱节；执行前逐行核对脚本配置与线上实际，对不上先改脚本或停下问。
+  2. **部署脚本必须内置「环境自检」，真正执行部署前先校验、不一致即中止**——校验项至少包括 PROJECT 与 gcloud 当前项目一致、目标 Cloud Run 服务存在、Nacos namespace/库名与线上一致、前端代理后端 Host 指向本环境而非 Dockerfile 默认值；目标脚本无自检时执行者必须先补上再跑，禁止无自检直接部署。参照 agent-rules 自身 `release.sh` 的规则漂移检查，把「人记得校验」升级为「脚本强制校验」。
+
+## [1.5.157] - 2026-08-29
+
+### Added
+
+- **「环境配置禁止推断」新增部署前环境对账铁律（SolarX 生产事故教训）**：部署生产前必须做「部署脚本配置 vs 线上实际环境」对账（`gcloud config get-value project` 核对项目、`gcloud run services list` 核对真实服务名、核对 Nacos namespace 与库名），对不上就停下来问用户，禁止直接信任部署脚本里的环境值。原因：部署脚本是多人接力维护的产物，PROJECT / 服务名 / Nacos namespace / 库名可能被中途改掉且与线上脱节——脚本能跑、能编译、甚至部署成功（生成新 revision），但流量不接、数据不对，直到切流量才暴露（静默脱节）。实例：SolarX 生产事故——部署脚本 `PROJECT=solarisx-api` / Nacos `f8703bd7`，线上实际服务却是 `solarisx-503302` / Nacos `638c11fe`，两套环境并存从未对齐，导致 admin/console 前端 nginx 注入错误后端、gateway 连错库，线上被迫切回旧版。
+
 ## [1.5.154] - 2026-08-27
 
 ### Added

package/package.json

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

package/rules/global.md

@@ -33,6 +33,7 @@ name: "通用规则"
   3. 云平台控制台（Cloud Run 域名映射、GCLB、Ingress 等）
 - ⚠️ **上述来源都找不到的，就写「待确认」或留空，禁止自行补全。** 错误的推断值比留空危害更大——留空会在运行时报错、立刻暴露；错误的推断值可能静默运行数月后才被发现（如请求打到了错误的环境），排查成本极高。
 - ⚠️ **代码中使用环境变量占位符（如 `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 与库名；对不上 → 停下来问用户，绝不按脚本直接部署。
 
 ## ⚠️ 可部署性自包含铁律（写代码之前考虑）
 
@@ -456,6 +457,8 @@ name: "通用规则"
 
 - 发版统一执行 `./release.sh`。（自包含铁律见上方「⚠️ 可部署性自包含铁律」章节）
 - ⚠️ 部署测试环境必须使用 `/deploy-test` skill，严禁跳过 skill 直接执行部署操作（合并/推送/部署/切回的具体流程见该 skill）。
+- ⚠️ **部署生产前必须通读一遍部署脚本再执行，禁止盲跑。** 部署脚本是多人接力的产物，其中任何一行环境值（PROJECT / 服务名 / Nacos namespace / 数据库 / 域名 / 后端 Host / VPC / 密钥名）都可能被中途改错、与线上真实环境脱节——脚本能跑、能编译、甚至能部署成功，但连的是错环境。执行前逐行核对脚本配置与线上实际（`gcloud config get-value project`、`gcloud run services list`、Nacos 配置），对不上 → 先改脚本或停下来问，禁止带着疑似错误的配置直接部署（呼应「环境配置禁止推断」）。
+- ⚠️ **部署脚本必须内置「环境自检」：在真正执行部署动作之前，先自动校验脚本配置与线上环境一致，不一致即中止（abort），禁止在环境未验证的情况下执行 deploy。** 校验项至少包括：① PROJECT 与 `gcloud config get-value project` 一致；② 目标 Cloud Run 服务真实存在；③ Nacos namespace / 库名与线上一致；④ 前端代理的后端 Host（BACKEND_RUN_HOST）指向本环境后端，而非 Dockerfile 默认值或他环境。**目标脚本若没有自检逻辑，执行者必须先补上再跑——禁止「无自检的脚本直接部署」。** 参照 agent-rules 自身 `release.sh` 的「规则漂移检查」（发版前强制校验规则已同步、未同步即中止），把「人记得校验」升级为「脚本强制校验」。
 
 ## ⚠️ 配置中心变更生效铁律