@routerhub/agent-rules 1.5.130 → 1.5.132

package/AGENTS.base.md

@@ -125,6 +125,20 @@
 
 - 用户明确要求上线/部署生产环境 → 直接执行。AI 自行触及生产环境操作 → 必须先向用户确认。
 
+## ⚠️ 机密与证书安全铁律
+
+### 1. TLS 证书校验：禁止用跳过校验来「修通」连接
+
+- ⚠️ **当 TLS 连接报「证书不被信任」（如 certificate signed by unknown authority）时，禁止用 `InsecureSkipVerify=true` 跳过校验来让连接「跑通」。** 根因通常是服务端证书由私有 CA / 内部 CA 签发、不在系统信任池。正确做法：把该私有 CA 的根证书（PEM）加入客户端 `RootCAs`，保持 `InsecureSkipVerify=false` 做真校验。跳过校验等于关闭证书校验，暴露中间人风险，属于安全降级。
+
+### 2. 机密/证书的获取方式：部署时确定且几乎不变 → 优先平台注入
+
+- ⚠️ **运行时需要的机密 / 证书 / 配置，若其特点是「部署时确定、几乎不变化（只在发版时才更新）」，优先用平台注入（Cloud Run `--update-secrets` / K8s Secret 挂载为环境变量），而不是运行时调 Secret Manager / 配置中心去拉。** 判断依据：
+  - 运行时拉取多一层故障点（超时 / 权限 / 网络任一挂掉 → 业务 fail-closed）、多一套解析与护栏代码；
+  - `versions/latest` 轮换后仍需重启进程才生效，「热更新」是伪优势；
+  - 两种方式安全效果等价，平台注入更简单、更稳；
+  - 若公司已有同类服务在生产采用某种方式，优先对齐，不另造一套。
+
 ## 代码风格
 
 - 驼峰命名，禁止下划线，变量至少两个单词。禁止 `as` 和 `any`。函数式编程，不写 `class`，不写 `try/catch`。
@@ -268,6 +282,17 @@
 - ⚠️ **修复共享网关配置时必须只做新增（additive-only），不得动原有 defaultService/pathRules**：新增一个独立的 backend service/NEG，在 url-map 上新增一个只作用于目标 host 的 pathMatcher，并显式将该 pathMatcher 自己的 `defaultService` 设置为原有的 backend service，确保其余所有路径行为不变。
 - 配置变更后如果立刻 curl 仍 404，先怀疑网关配置生效延迟（GCLB 常见有数十秒传播延迟），可用"直连后端验证"+"带 Host header 直连网关 IP 验证"两步排除"配置写错"和"还没生效"两种可能，再决定是否继续修改配置。
 
+## 域名配置前置流程（先 LB 后 DNS）
+
+- ⚠️ **给新域名配置 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 访问、留资流程等）。
+- ⚠️ **给对方的信息必须把「负载均衡已建好 + IP」放在最显眼位置，明确告诉他「你只需要配一条 A 记录」**，避免对方误以为要自己去建 LB 或改一堆东西。
+
 ## 基础设施修复后代码 Workaround 清理规范
 
 - ⚠️ **临时绕过基础设施问题写入代码的 workaround（如硬编码直连地址、绕过网关/域名），修复根因基础设施问题后必须回退代码**，禁止让 workaround 永久留在代码里。基础设施修复完成后应主动排查代码里是否存在对应的临时绕过逻辑并清理。

package/package.json

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

package/rules/global.md

@@ -125,6 +125,20 @@ name: "通用规则"
 
 - 用户明确要求上线/部署生产环境 → 直接执行。AI 自行触及生产环境操作 → 必须先向用户确认。
 
+## ⚠️ 机密与证书安全铁律
+
+### 1. TLS 证书校验：禁止用跳过校验来「修通」连接
+
+- ⚠️ **当 TLS 连接报「证书不被信任」（如 certificate signed by unknown authority）时，禁止用 `InsecureSkipVerify=true` 跳过校验来让连接「跑通」。** 根因通常是服务端证书由私有 CA / 内部 CA 签发、不在系统信任池。正确做法：把该私有 CA 的根证书（PEM）加入客户端 `RootCAs`，保持 `InsecureSkipVerify=false` 做真校验。跳过校验等于关闭证书校验，暴露中间人风险，属于安全降级。
+
+### 2. 机密/证书的获取方式：部署时确定且几乎不变 → 优先平台注入
+
+- ⚠️ **运行时需要的机密 / 证书 / 配置，若其特点是「部署时确定、几乎不变化（只在发版时才更新）」，优先用平台注入（Cloud Run `--update-secrets` / K8s Secret 挂载为环境变量），而不是运行时调 Secret Manager / 配置中心去拉。** 判断依据：
+  - 运行时拉取多一层故障点（超时 / 权限 / 网络任一挂掉 → 业务 fail-closed）、多一套解析与护栏代码；
+  - `versions/latest` 轮换后仍需重启进程才生效，「热更新」是伪优势；
+  - 两种方式安全效果等价，平台注入更简单、更稳；
+  - 若公司已有同类服务在生产采用某种方式，优先对齐，不另造一套。
+
 ## 代码风格
 
 - 驼峰命名，禁止下划线，变量至少两个单词。禁止 `as` 和 `any`。函数式编程，不写 `class`，不写 `try/catch`。
@@ -268,6 +282,17 @@ name: "通用规则"
 - ⚠️ **修复共享网关配置时必须只做新增（additive-only），不得动原有 defaultService/pathRules**：新增一个独立的 backend service/NEG，在 url-map 上新增一个只作用于目标 host 的 pathMatcher，并显式将该 pathMatcher 自己的 `defaultService` 设置为原有的 backend service，确保其余所有路径行为不变。
 - 配置变更后如果立刻 curl 仍 404，先怀疑网关配置生效延迟（GCLB 常见有数十秒传播延迟），可用"直连后端验证"+"带 Host header 直连网关 IP 验证"两步排除"配置写错"和"还没生效"两种可能，再决定是否继续修改配置。
 
+## 域名配置前置流程（先 LB 后 DNS）
+
+- ⚠️ **给新域名配置 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 访问、留资流程等）。
+- ⚠️ **给对方的信息必须把「负载均衡已建好 + IP」放在最显眼位置，明确告诉他「你只需要配一条 A 记录」**，避免对方误以为要自己去建 LB 或改一堆东西。
+
 ## 基础设施修复后代码 Workaround 清理规范
 
 - ⚠️ **临时绕过基础设施问题写入代码的 workaround（如硬编码直连地址、绕过网关/域名），修复根因基础设施问题后必须回退代码**，禁止让 workaround 永久留在代码里。基础设施修复完成后应主动排查代码里是否存在对应的临时绕过逻辑并清理。