@routerhub/agent-rules 1.5.195 → 1.5.197

package/AGENTS.base.md

@@ -46,6 +46,8 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 - ⚠️ **代码中使用环境变量占位符（如 `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 与库名；对不上 → 停下来问用户，绝不按脚本直接部署。
 
+- ⚠️ **发现部署脚本 / 配置里的生产环境标识（PROJECT / 服务名 / namespace / 库名 / 域名等）与线上错位，属于事故级问题。修复后必须合入主干（main/master）并发版，禁止只修在分支或测试环境——主干长期留着错值，等于给下一次部署埋同一颗雷。** 上一条 SolarX 事故中，错值曾由修复分支纠正、却从未合入主干，主干一直带错，是同类事故复发的最常见原因。
+
 ## ⚠️ 可部署性自包含铁律（写代码之前考虑）
 
 - ⚠️ **写任何逻辑、用任何环境变量/配置值之前，必须先把"这个改动上线后部署怎么办"想清楚**：能直接写死的就写死，该放部署脚本的就放部署脚本，该配配置中心的就配配置中心。所有环境准备（建表、迁移、字段变更、初始化/导入数据、配置下发）一律内嵌到部署脚本自动完成。**达成的效果：上线时只需执行部署脚本，数据库迁移、人工改配置等一切操作全部免掉，上线后零操心。**
@@ -567,6 +569,15 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 - ⚠️ **评估后确认必须改共享基础设施本身才能修复时，必须先向用户说明改动内容和影响范围（这份配置还被哪些其他服务/流量依赖），得到明确确认后才能执行**，禁止在诊断过程中把"顺手改一下共享配置"当成常规修复步骤直接执行——这类改动一旦出错，影响的不是一个功能，而是所有依赖这份共享配置的系统。
 - ⚠️ **共享存储字段变更（如 BigQuery 表加列、共享 DB 加字段）是最容易漏的手动步骤**：这类资源由多个系统共享（写入方、读取方、传输层），天然不在单一部署脚本的「本能覆盖范围」内。每次新增/修改后端读取的字段，必须同步检查对应的共享存储是否已加列/加字段，并把「幂等确保存在」逻辑内嵌进部署脚本（如 `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`、`bq mk if-not-exists`、幂等的 `ensure_xxx()` 前置函数），而不是留给运维手动跑一次。参考模式：`deploy_backend()` 内先调用幂等 `ensure_usage_logs_schema()` 再部署，加列失败即停止部署，不产生「接口挂」的中间态；代码层面再加列存在性动态检测兜底（缺列时优雅降级，不报 `Unrecognized name`）。
 
+## 🚨 客户生产入口默认「在用」红线（负载均衡 / 网关 / DNS 指向 / 共享基础设施）
+
+- ⚠️ **负载均衡（GCLB/LB）、网关、域名 DNS 指向、反向代理等「客户流量入口」基础设施，默认一律视为客户生产在用，禁止在未获用户本人显式确认的情况下对其做任何写操作**（改路由 / 增删 pathMatcher / 切流量 / 新建或删除 / 改 DNS 指向）。**举证责任反置：不是「看起来没用、好像是测试的 → 可以动」，而是「默认不能动，只有用户亲口说出『没人用 / 这是测试环境 / 可以动』，才允许动」。**
+- ⚠️ **用户让你做某件事 ≠ 用户允许你动客户生产入口。** 任务本身会写到负载均衡 / 网关 / DNS 时——哪怕目标是「修 404」「补条路由」「对齐配置」这类听起来合理的需求——动前也必须先过一遍「是否客户生产在用」判断：需求方甚至用户本人，都可能没意识到目标对象正被客户使用。判定顺序：
+  1. 用户已明说状态 → 采信：说在用 = 不动；说没人用 / 测试 = 可继续，但先把「我会动 X，因为你确认它没人用 / 是测试环境」复述一遍再动手；
+  2. 需求没说明 → 自查证据：域名解析（dig）有无真实请求指向它、后端服务 / revision 有无流量、对象命名与域名前缀（api. / console. 等客户域名）、仓库文档有无「客户在用」记录；
+  3. 证据不足 / 无权限核对生产（最常见）→ 一律判「在用」不能动，把已有证据摆出来问用户：「我判断不了它是否客户在用，请明确：没人用 / 测试环境吗？你确认了我才动」。
+- ⚠️ **异常 ≠ 没人用，尤其 404 / 错误配置本身就是「客户流量正打到这里」的证据。** 域名能解析出 IP、请求能到达 LB / 网关、只是路由配错才返回 404 / 502 —— 恰恰证明有人在访问，该对象是客户入口；禁止把它当「闲置、坏了、没人用」顺手修改。正确反应是停止并上报，而不是「修好它」。
+
 ## 网关/负载均衡 404 排查规范
 
 - ⚠️ **域名访问 404 时，禁止优先假设是 DNS 问题**。DNS 只负责把域名解析到 IP，能解析到正确 IP 但仍 404，说明问题在 IP 之后的路由链路上（负载均衡 / API 网关 / 反向代理的路由规则），必须先排查这一层，而不是重新配置 DNS。
@@ -602,6 +613,9 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 - ⚠️ **部署生产前必须通读一遍部署脚本再执行，禁止盲跑。** 部署脚本是多人接力的产物，其中任何一行环境值（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` 的「规则漂移检查」（发版前强制校验规则已同步、未同步即中止），把「人记得校验」升级为「脚本强制校验」。
 
+- ⚠️ **禁止绕过仓库内受控部署/配置脚本，直接手敲云平台命令（gcloud / aws / kubectl 等）对生产环境做写操作**（部署新版本、切流量、改路由、改 DNS 指向、改共享配置）。生产写操作唯一入口是仓库内受控脚本；没有对应脚本就先补脚本（幂等、可 review、含环境自检）再执行动作，禁止「命令先跑、脚本后补」。
+- ⚠️ **禁止用未提交工作区（构建产物带 `-dirty`）或未合入主干的代码构建生产发布物。** 生产镜像/发布物必须来自干净的、已合入 main/master 的 commit——脏工作树或未合并分支里可能带着半成品/调试改动，一旦上生产极难排查，也无法回溯「线上跑的到底是哪份代码」。
+
 ### 🚨 上线安全四环铁律（部署生产 / 切流量必守）
 
 上线（部署生产、切流量、更新线上版本）的唯一不可接受后果是：**新版本有问题直接接流量，把原本正常服务顶崩**。上线必须走完以下四环，缺一不可；任何一环未过即中止，禁止带着未验证的环节继续。这里的核心是「你叫我怎样就怎样」行不通——**上线动作必须等校验全部通过才执行**。
@@ -623,6 +637,8 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 - 后端渐进切流量（5% → 观察 → 50% → 100%）；前端静态资源验证后一次性切。
 - 切流量前记录当前线上 revision 号；任何一步验证不过，`update-traffic --to-revision <旧版>` 秒切回，恢复线上原状后再排查。
 
+- ⚠️ **线上服务被回滚到旧版本（无论由谁回滚、是否发生在 AI 会话之外）＝ 我方变更被判定有问题的最强信号。必须先停止一切「重试 / 把变更原样重新应用回去」的动作，查清对方为何回滚、哪里没满足要求，向用户说明根因后再决定下一步。禁止未查清原因就把被回滚的变更重新应用。**
+
 ## ⚠️ 配置中心变更生效铁律
 
 - ⚠️ **修改外部配置中心（如 Nacos）的配置后，若应用是启动时一次性拉取、没有热更新监听，必须显式重启/重新部署服务才能生效**。发布配置后如果验证发现"没生效"，先确认服务是否已经重启到最新版本，再去怀疑配置内容本身写错了——顺序反了会在"配置到底对不对"上来回排查，白白浪费时间。

package/merge.js

@@ -17,7 +17,7 @@
  *     AGENTS.md                                    全量合并（兼容 Cursor/Claude Code）
  *     CLAUDE.md                                    全量合并（Claude Code 自动加载）
  *   团队级（始终生成、随仓库分发共享）：
- *     .github/copilot-instructions.md              全局规则（VS Code Copilot）
+ *     .github/copilot-instructions.md              全局+完整私有规则（VS Code Copilot）
  *     .github/instructions/*.instructions.md       按域条件加载（VS Code Copilot applyTo）
  *     .github/PULL_REQUEST_TEMPLATE.md             统一 PR 模板（GitHub 新建 PR 时预填）
  *     .claude/skills/*                             同步 Skills 到项目本地
@@ -715,13 +715,20 @@ function mergeAgents(config) {
     .map((rule) => rule.content.trim())
     .join("\n\n");
 
-  // 4. 生成 .github/copilot-instructions.md（全局规则 + 私有全局部分）
+  // 4. 生成 .github/copilot-instructions.md
+  //    全局基础规则 + 完整私有规则（含各 @domain 段）。让任意 Agent（Claude Code /
+  //    VS Code Copilot / Cursor 等）读到同一份完整私有规则：只要 AGENTS.private.md 有
+  //    内容就整份追加，不再只取「私有全局段」——否则写在某个 @domain 段、或段落末尾
+  //    的私有规则会从 copilot-instructions.md 里静默缺失，造成「我加了规则但 Copilot
+  //    那边没同步到」的误解（与 AGENTS.md / CLAUDE.md 的全量注入保持一致）。
   let copilotContent = "# Copilot Agent Rules\n\n" + globalContent;
-  if (privateDomains.global) {
-    copilotContent += "\n\n---\n\n# 项目私有规则\n\n" + privateDomains.global;
+  if (privateContent) {
+    copilotContent +=
+      "\n\n---\n\n# 项目私有规则\n\n以下规则仅适用于本项目，会覆盖基础规则中的相同部分。\n\n" +
+      privateContent.trim();
   }
   writeFileIfChanged(copilotOutput, copilotContent);
-  console.log(`✅ 全局规则已生成: ${copilotOutput}`);
+  console.log(`✅ 全局规则已生成(含完整私有规则): ${copilotOutput}`);
 
   // 5. 生成 .github/instructions/*.instructions.md（各域规则）
   ensureParentDir(path.join(instructionsDir, "_placeholder"));
@@ -797,7 +804,7 @@ function initAgents() {
   console.log("   - CLAUDE.md / AGENTS.md（停用时不会生成，并清理本机残留）");
   console.log("     查看当前 git 身份：git config user.name  /  git config user.email");
   console.log("   团队级文件（始终生成、随仓库分发）:");
-  console.log("   - .github/copilot-instructions.md（全局规则）");
+  console.log("   - .github/copilot-instructions.md（全局规则 + 完整私有规则）");
   console.log("   - .github/instructions/*.instructions.md（按域条件加载）");
   console.log("   - .claude/skills/*（Claude Code Skills 技能文件）");
 }
@@ -954,7 +961,7 @@ function main() {
     );
     console.log("输出文件（团队级，始终生成）:");
     console.log(
-      "  .github/copilot-instructions.md              全局规则（VS Code Copilot）",
+      "  .github/copilot-instructions.md              全局+完整私有规则（VS Code Copilot）",
     );
     console.log(
       "  .github/instructions/*.instructions.md       按域条件加载（VS Code Copilot applyTo）",

package/package.json

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

package/rules/global.md

@@ -46,6 +46,8 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 - ⚠️ **代码中使用环境变量占位符（如 `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 与库名；对不上 → 停下来问用户，绝不按脚本直接部署。
 
+- ⚠️ **发现部署脚本 / 配置里的生产环境标识（PROJECT / 服务名 / namespace / 库名 / 域名等）与线上错位，属于事故级问题。修复后必须合入主干（main/master）并发版，禁止只修在分支或测试环境——主干长期留着错值，等于给下一次部署埋同一颗雷。** 上一条 SolarX 事故中，错值曾由修复分支纠正、却从未合入主干，主干一直带错，是同类事故复发的最常见原因。
+
 ## ⚠️ 可部署性自包含铁律（写代码之前考虑）
 
 - ⚠️ **写任何逻辑、用任何环境变量/配置值之前，必须先把"这个改动上线后部署怎么办"想清楚**：能直接写死的就写死，该放部署脚本的就放部署脚本，该配配置中心的就配配置中心。所有环境准备（建表、迁移、字段变更、初始化/导入数据、配置下发）一律内嵌到部署脚本自动完成。**达成的效果：上线时只需执行部署脚本，数据库迁移、人工改配置等一切操作全部免掉，上线后零操心。**
@@ -567,6 +569,15 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 - ⚠️ **评估后确认必须改共享基础设施本身才能修复时，必须先向用户说明改动内容和影响范围（这份配置还被哪些其他服务/流量依赖），得到明确确认后才能执行**，禁止在诊断过程中把"顺手改一下共享配置"当成常规修复步骤直接执行——这类改动一旦出错，影响的不是一个功能，而是所有依赖这份共享配置的系统。
 - ⚠️ **共享存储字段变更（如 BigQuery 表加列、共享 DB 加字段）是最容易漏的手动步骤**：这类资源由多个系统共享（写入方、读取方、传输层），天然不在单一部署脚本的「本能覆盖范围」内。每次新增/修改后端读取的字段，必须同步检查对应的共享存储是否已加列/加字段，并把「幂等确保存在」逻辑内嵌进部署脚本（如 `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`、`bq mk if-not-exists`、幂等的 `ensure_xxx()` 前置函数），而不是留给运维手动跑一次。参考模式：`deploy_backend()` 内先调用幂等 `ensure_usage_logs_schema()` 再部署，加列失败即停止部署，不产生「接口挂」的中间态；代码层面再加列存在性动态检测兜底（缺列时优雅降级，不报 `Unrecognized name`）。
 
+## 🚨 客户生产入口默认「在用」红线（负载均衡 / 网关 / DNS 指向 / 共享基础设施）
+
+- ⚠️ **负载均衡（GCLB/LB）、网关、域名 DNS 指向、反向代理等「客户流量入口」基础设施，默认一律视为客户生产在用，禁止在未获用户本人显式确认的情况下对其做任何写操作**（改路由 / 增删 pathMatcher / 切流量 / 新建或删除 / 改 DNS 指向）。**举证责任反置：不是「看起来没用、好像是测试的 → 可以动」，而是「默认不能动，只有用户亲口说出『没人用 / 这是测试环境 / 可以动』，才允许动」。**
+- ⚠️ **用户让你做某件事 ≠ 用户允许你动客户生产入口。** 任务本身会写到负载均衡 / 网关 / DNS 时——哪怕目标是「修 404」「补条路由」「对齐配置」这类听起来合理的需求——动前也必须先过一遍「是否客户生产在用」判断：需求方甚至用户本人，都可能没意识到目标对象正被客户使用。判定顺序：
+  1. 用户已明说状态 → 采信：说在用 = 不动；说没人用 / 测试 = 可继续，但先把「我会动 X，因为你确认它没人用 / 是测试环境」复述一遍再动手；
+  2. 需求没说明 → 自查证据：域名解析（dig）有无真实请求指向它、后端服务 / revision 有无流量、对象命名与域名前缀（api. / console. 等客户域名）、仓库文档有无「客户在用」记录；
+  3. 证据不足 / 无权限核对生产（最常见）→ 一律判「在用」不能动，把已有证据摆出来问用户：「我判断不了它是否客户在用，请明确：没人用 / 测试环境吗？你确认了我才动」。
+- ⚠️ **异常 ≠ 没人用，尤其 404 / 错误配置本身就是「客户流量正打到这里」的证据。** 域名能解析出 IP、请求能到达 LB / 网关、只是路由配错才返回 404 / 502 —— 恰恰证明有人在访问，该对象是客户入口；禁止把它当「闲置、坏了、没人用」顺手修改。正确反应是停止并上报，而不是「修好它」。
+
 ## 网关/负载均衡 404 排查规范
 
 - ⚠️ **域名访问 404 时，禁止优先假设是 DNS 问题**。DNS 只负责把域名解析到 IP，能解析到正确 IP 但仍 404，说明问题在 IP 之后的路由链路上（负载均衡 / API 网关 / 反向代理的路由规则），必须先排查这一层，而不是重新配置 DNS。
@@ -602,6 +613,9 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 - ⚠️ **部署生产前必须通读一遍部署脚本再执行，禁止盲跑。** 部署脚本是多人接力的产物，其中任何一行环境值（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` 的「规则漂移检查」（发版前强制校验规则已同步、未同步即中止），把「人记得校验」升级为「脚本强制校验」。
 
+- ⚠️ **禁止绕过仓库内受控部署/配置脚本，直接手敲云平台命令（gcloud / aws / kubectl 等）对生产环境做写操作**（部署新版本、切流量、改路由、改 DNS 指向、改共享配置）。生产写操作唯一入口是仓库内受控脚本；没有对应脚本就先补脚本（幂等、可 review、含环境自检）再执行动作，禁止「命令先跑、脚本后补」。
+- ⚠️ **禁止用未提交工作区（构建产物带 `-dirty`）或未合入主干的代码构建生产发布物。** 生产镜像/发布物必须来自干净的、已合入 main/master 的 commit——脏工作树或未合并分支里可能带着半成品/调试改动，一旦上生产极难排查，也无法回溯「线上跑的到底是哪份代码」。
+
 ### 🚨 上线安全四环铁律（部署生产 / 切流量必守）
 
 上线（部署生产、切流量、更新线上版本）的唯一不可接受后果是：**新版本有问题直接接流量，把原本正常服务顶崩**。上线必须走完以下四环，缺一不可；任何一环未过即中止，禁止带着未验证的环节继续。这里的核心是「你叫我怎样就怎样」行不通——**上线动作必须等校验全部通过才执行**。
@@ -623,6 +637,8 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 - 后端渐进切流量（5% → 观察 → 50% → 100%）；前端静态资源验证后一次性切。
 - 切流量前记录当前线上 revision 号；任何一步验证不过，`update-traffic --to-revision <旧版>` 秒切回，恢复线上原状后再排查。
 
+- ⚠️ **线上服务被回滚到旧版本（无论由谁回滚、是否发生在 AI 会话之外）＝ 我方变更被判定有问题的最强信号。必须先停止一切「重试 / 把变更原样重新应用回去」的动作，查清对方为何回滚、哪里没满足要求，向用户说明根因后再决定下一步。禁止未查清原因就把被回滚的变更重新应用。**
+
 ## ⚠️ 配置中心变更生效铁律
 
 - ⚠️ **修改外部配置中心（如 Nacos）的配置后，若应用是启动时一次性拉取、没有热更新监听，必须显式重启/重新部署服务才能生效**。发布配置后如果验证发现"没生效"，先确认服务是否已经重启到最新版本，再去怀疑配置内容本身写错了——顺序反了会在"配置到底对不对"上来回排查，白白浪费时间。