@optima-chat/dev-skills 0.7.37 → 0.7.38

package/.claude/commands/logs.md

@@ -50,6 +50,7 @@
   - `ci` - CI 持续集成环境（开发环境，默认）
   - `stage` - Stage 预发布环境（ECS Fargate）
   - `prod` - 生产环境（ECS Fargate）
+  - `cn-prod`（别名 `cn`）- 阿里云 cn-prod 环境（SAE，cn-beijing，经 buildbox 取日志）
 
 ## 示例
 
@@ -71,6 +72,7 @@
 - `ci` 或未指定 → 使用 SSH + Docker Compose（第 0 节，默认）
 - `stage` → 使用 AWS CloudWatch Logs - ECS（第 1 节）
 - `prod` → 使用 AWS CloudWatch Logs - ECS（第 2 节）
+- `cn-prod` / `cn` → 阿里云 SAE，经 buildbox 调 `DescribeInstanceLog`（第 3 节）
 
 ### 0. CI 环境（environment = "ci" 或默认）
 
@@ -209,6 +211,59 @@ aws logs get-log-events --log-group-name /ecs/commerce-backend-prod --log-stream
 
 **注意**: `optima-store` 仅在 Stage 环境部署
 
+### 3. cn-prod 环境（environment = "cn-prod" 或 "cn"）
+
+**部署方式**: 阿里云 **SAE**（Serverless App Engine，cn-beijing），不是 ECS/CloudWatch。
+**访问方式**: 经 buildbox（`root@47.94.105.163`，唯一装了 `aliyun-optima` profile + VPC 可达的机器）调 SAE OpenAPI。
+
+> ⚠️ SAE **未配 SLS**，stdout 日志只能用 `DescribeInstanceLog` 取实例**当前缓冲**（非历史检索；重启/滚动后旧日志丢）。要历史检索需给 SAE 配 SLS。
+
+**日志链**: service → AppId → GroupId → InstanceId → `DescribeInstanceLog`
+
+**关键坑**（实测）:
+- API 是 RPC-style `aliyun sae DescribeInstanceLog`，ROA 路径是 `/pop/v1/sam/**instance**/describeInstanceLog`（不是 `/sam/app/...`，写错报 "can not find api by path"）。
+- buildbox 密码在 1P `op://Optima/gdmixcizjci5bvuu3nuvgg4ooe/password`（标题带括号必须用 item ID）。
+
+**service → AppId 映射**（cn-prod，2026-06-01；新增/变动用 `aliyun sae ListApplications` 重查）:
+
+| service | AppId |
+|---|---|
+| `gateway-core` | `a08ce23f-3d3e-4d89-a2cf-53c8adba614e` |
+| `agentic-chat` | `6e290c73-a646-43ef-9da5-ad0b2e7eff73` |
+| `gw-admin` | `c6bc5a78-b27f-46e2-825a-eaa338c23645` |
+| `user-auth` | `d6fbf9de-fed6-4165-978f-7b3a0a456acc` |
+| `user-auth-admin` | `54093f99-37bf-4354-abd7-f6e76abdbcb6` |
+| `optima-scout` | `f5bb7e82-e57c-4bd4-83ae-2c25f8d38647` |
+| `optima-skills` | `55a63ee7-fb75-46e4-99f3-20854a699237` |
+| `infisical` | `52b33fc6-b26d-495a-8885-225d38b3d42f` |
+
+**完整脚本**（本地跑、经 buildbox 中转；改 `SERVICE`/`LINES`）:
+```bash
+SERVICE=gateway-core; LINES=80
+BBPW=$(op-win read "op://Optima/gdmixcizjci5bvuu3nuvgg4ooe/password")
+declare -A APPID=(
+  [gateway-core]=a08ce23f-3d3e-4d89-a2cf-53c8adba614e
+  [agentic-chat]=6e290c73-a646-43ef-9da5-ad0b2e7eff73
+  [gw-admin]=c6bc5a78-b27f-46e2-825a-eaa338c23645
+  [user-auth]=d6fbf9de-fed6-4165-978f-7b3a0a456acc
+  [user-auth-admin]=54093f99-37bf-4354-abd7-f6e76abdbcb6
+  [optima-scout]=f5bb7e82-e57c-4bd4-83ae-2c25f8d38647
+  [optima-skills]=55a63ee7-fb75-46e4-99f3-20854a699237
+  [infisical]=52b33fc6-b26d-495a-8885-225d38b3d42f )
+AID=${APPID[$SERVICE]}
+sshpass -p "$BBPW" ssh -o StrictHostKeyChecking=no root@47.94.105.163 "bash -s" <<REMOTE | tail -n $LINES
+P="--region cn-beijing --profile aliyun-optima"
+GID=\$(aliyun sae GET /pop/v1/sam/app/describeApplicationGroups --AppId $AID \$P 2>/dev/null | python3 -c "import sys,json;print(json.load(sys.stdin)['Data'][0]['GroupId'])")
+IID=\$(aliyun sae GET /pop/v1/sam/app/describeApplicationInstances --AppId $AID --GroupId \$GID \$P 2>/dev/null | python3 -c "import sys,json;d=json.load(sys.stdin)['Data'];print((d if isinstance(d,list) else d['Instances'])[0]['InstanceId'])")
+aliyun sae DescribeInstanceLog --InstanceId "\$IID" \$P 2>/dev/null | python3 -c "import sys,json;print(json.load(sys.stdin).get('Data',''))"
+REMOTE
+```
+
+**局限 / 提示**:
+- 只取第 1 个 InstanceId；多副本要遍历 `Data` 里全部 instance。
+- `agent-runtime` 不在 SAE（是 ECI 动态容器）——它的日志看 `gateway-core` 里 `eci-bridge` 的转发/错误行，或单独查对应 ECI。
+- 过滤：把上面输出 `| grep -iE 'error|eci|fail'` 即可（例：排 agentic-chat 链路 ECI 失败就 grep `gateway-core` 日志的 `eci-bridge`）。
+
 ## 完整示例脚本
 
 ### Stage 环境

package/.claude/skills/logs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "logs"
-description: "当用户请求查看日志、查看服务日志、排查问题、看看日志、检查日志、商品服务日志、后端日志、API日志、正式环境日志、生产环境日志、CI环境日志、开发环境日志时，使用此技能。支持 CI、Stage、Prod 三个环境的 commerce-backend、user-auth、agentic-chat、bi-backend、session-gateway 等服务。"
+description: "当用户请求查看日志、查看服务日志、排查问题、看看日志、检查日志、商品服务日志、后端日志、API日志、正式环境日志、生产环境日志、CI环境日志、开发环境日志、阿里云日志、cn-prod 日志、SAE 日志时，使用此技能。支持 CI、Stage、Prod（AWS ECS/CloudWatch）以及 cn-prod（阿里云 SAE，经 buildbox）四个环境的 commerce-backend、user-auth、agentic-chat、gateway-core、optima-scout、optima-skills 等服务。"
 allowed-tools: ["Bash", "SlashCommand"]
 ---
 
@@ -175,6 +175,19 @@ INFO - Database query took 3200ms: SELECT * FROM products WHERE...
 - 通过 CloudWatch Logs 查看
 - 日志保留 7 天
 
+### cn-prod 环境（阿里云）
+
+```
+/logs gateway-core 100 cn-prod
+/logs agentic-chat 80 cn
+```
+
+**特点**：
+- 阿里云 **SAE**（cn-beijing），不是 AWS
+- 经 buildbox（`root@47.94.105.163`）调 SAE `DescribeInstanceLog`
+- SAE 未配 SLS → 只取实例**当前 stdout 缓冲**（非历史检索）
+- 技术细节 + service→AppId 映射见 `/logs --help`（第 3 节）
+
 ## 支持的服务列表
 
 | 服务 | 说明 | CI | Stage | Prod |

package/bin/cli.js

@@ -32,6 +32,7 @@ switch (command) {
     log('Available Commands:', 'yellow');
     log('  optima-query-db <service> "<sql>" [env]              Query database', 'cyan');
     log('  optima-show-env <service> [env]                      Show service env vars', 'cyan');
+    log('  optima-verify-health <service> [--env cn|prod|all]   Probe L1-L5 上线健康', 'cyan');
     log('  optima-generate-test-token [--env production]        Generate test token', 'cyan');
     log('  optima-grant-balance <email> --amount <usd> [--env]  Grant USD wallet balance', 'cyan');
     log('  optima-grant-subscription <email> --plan <p> [--env] Grant subscription', 'cyan');

package/bin/helpers/db-utils.ts

@@ -1,5 +1,6 @@
-import { execSync } from 'child_process';
+import { execSync, spawn } from 'child_process';
 import * as fs from 'fs';
+import * as os from 'os';
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 export interface InfisicalConfig { url: string; clientId: string; clientSecret: string; projectId: string }
@@ -18,6 +19,11 @@ export const RDS_HOSTS: Record<string, string> = {
   prod:  'optima-prod-postgres.ctg866o0ehac.ap-southeast-1.rds.amazonaws.com',
 };
 
+// Shared bastion (optima-bi-data EC2, shared-services stack). Reached via SSM —
+// no public port 22 dependency, so it is immune to the MaxStartups throttling that
+// the open-to-world sshd suffers under internet scan load. SSH path kept as fallback.
+const AWS_REGION = 'ap-southeast-1';
+const BASTION_INSTANCE_ID = 'i-03286fb0a9ce7e6b1';
 const EC2_HOST = '3.0.210.113';
 
 // ─── SQL escaping ───────────────────────────────────────────────────────────
@@ -114,6 +120,75 @@ export function setupSSHTunnel(dbHost: string, localPort: number): void {
   );
 }
 
+/** Block the current (sync) call for `ms` without spawning a subprocess. */
+function sleepSync(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function assertSSMPrereqs(): void {
+  for (const [bin, hint] of [
+    ['session-manager-plugin', 'https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html'],
+    ['aws', 'AWS CLI v2: https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html'],
+  ] as const) {
+    try { execSync(`command -v ${bin}`, { stdio: 'ignore' }); }
+    catch { throw new Error(`${bin} not found — required for the SSM DB tunnel. Install: ${hint}\n(or set OPTIMA_DB_TUNNEL=ssh to fall back to the legacy SSH tunnel)`); }
+  }
+}
+
+/**
+ * Open a local→RDS tunnel through the shared bastion using SSM port forwarding.
+ * No public SSH port is touched. A healthy existing tunnel on the port is reused
+ * (the ~2s SSM cold start is paid once, then every query is just a round-trip).
+ */
+export function setupSSMTunnel(dbHost: string, localPort: number): void {
+  let portInUse = false;
+  try { execSync(`lsof -ti:${localPort}`, { stdio: 'ignore' }); portInUse = true; } catch { /* free */ }
+
+  if (portInUse) {
+    if (isTunnelHealthy(localPort)) return;        // warm reuse — no cold start
+    console.log(`! Tunnel on port ${localPort} not responding (zombie), replacing...`);
+    killOrphanTunnel(localPort);
+  }
+
+  assertSSMPrereqs();
+  console.log(`Creating SSM tunnel: localhost:${localPort} -> ${BASTION_INSTANCE_ID} -> ${dbHost}:5432`);
+
+  const logFile = `${os.tmpdir()}/optima-ssm-tunnel-${localPort}.log`;
+  const out = fs.openSync(logFile, 'w');
+  const child = spawn('aws', [
+    'ssm', 'start-session',
+    '--region', AWS_REGION,
+    '--target', BASTION_INSTANCE_ID,
+    '--document-name', 'AWS-StartPortForwardingSessionToRemoteHost',
+    '--parameters', `host=${dbHost},portNumber=5432,localPortNumber=${localPort}`,
+  ], { detached: true, stdio: ['ignore', out, out] });
+  child.unref();
+
+  // Wait until the remote leg actually forwards (pg_isready probes RDS through the
+  // tunnel). Local port binds instantly; the remote hop needs ~1-2s to come up.
+  const deadlineMs = Date.now() + 20000;
+  while (Date.now() < deadlineMs) {
+    if (isTunnelHealthy(localPort)) { console.log(`✓ SSM tunnel ready on port ${localPort}`); return; }
+    sleepSync(500);
+  }
+
+  let tail = '(no log)';
+  try { tail = fs.readFileSync(logFile, 'utf-8').split('\n').slice(-8).join('\n'); } catch { /* ignore */ }
+  throw new Error(`SSM tunnel on port ${localPort} did not become ready within 20s.\n--- ${logFile} ---\n${tail}`);
+}
+
+/**
+ * Open a DB tunnel through the shared bastion. Defaults to SSM (no public port 22);
+ * set OPTIMA_DB_TUNNEL=ssh to fall back to the legacy SSH tunnel.
+ */
+export function setupTunnel(dbHost: string, localPort: number): void {
+  if ((process.env.OPTIMA_DB_TUNNEL || 'ssm').toLowerCase() === 'ssh') {
+    setupSSHTunnel(dbHost, localPort);
+  } else {
+    setupSSMTunnel(dbHost, localPort);
+  }
+}
+
 // ─── psql ───────────────────────────────────────────────────────────────────
 function findPsqlPath(): string {
   try {
@@ -142,8 +217,7 @@ export async function connectAuthDB(env: string, infisicalConfig: InfisicalConfi
   const host = RDS_HOSTS[env as 'stage' | 'prod'];
   const port = env === 'stage' ? 15432 : 15433;
 
-  setupSSHTunnel(host, port);
-  await new Promise(r => setTimeout(r, 1000));
+  setupTunnel(host, port);
 
   const conn: DBConnection = { host: 'localhost', port, user: secrets['AUTH_DB_USER'], password: secrets['AUTH_DB_PASSWORD'], database: 'optima_auth' };
   return { query: (sql: string) => queryDB(conn, sql) };
@@ -158,8 +232,7 @@ export async function connectBillingDB(env: string, infisicalConfig: InfisicalCo
 
   const parsed = parseDatabaseUrl(dbUrl);
   const port = env === 'stage' ? 15434 : 15435;
-  setupSSHTunnel(parsed.host, port);
-  await new Promise(r => setTimeout(r, 1000));
+  setupTunnel(parsed.host, port);
 
   const conn: DBConnection = { host: 'localhost', port, user: parsed.user, password: parsed.password, database: parsed.database };
   return { query: (sql: string) => queryDB(conn, sql) };

package/bin/helpers/query-db.ts

@@ -2,6 +2,7 @@
 
 import { execSync } from 'child_process';
 import * as fs from 'fs';
+import { setupTunnel } from './db-utils';
 
 interface InfisicalConfig {
   url: string;
@@ -96,9 +97,6 @@ const RDS_HOSTS = {
   prod: 'optima-prod-postgres.ctg866o0ehac.ap-southeast-1.rds.amazonaws.com'
 };
 
-// 统一使用 BI Data ARM Host 作为跳板机
-const EC2_HOST = '3.0.210.113';
-
 function parseDatabaseUrl(url: string): { user: string; password: string; host: string; port: number; database: string } {
   // postgresql://user:password@host:port/database?params
   const match = url.match(/^postgresql:\/\/([^:]+):([^@]+)@([^:]+):(\d+)\/([^?]+)/);
@@ -148,29 +146,6 @@ function getInfisicalSecrets(config: InfisicalConfig, token: string, environment
   return secrets;
 }
 
-function setupSSHTunnel(ec2Host: string, dbHost: string, localPort: number): void {
-  // 检查是否已有隧道
-  try {
-    execSync(`lsof -ti:${localPort}`, { stdio: 'ignore' });
-    console.log(`✓ SSH tunnel already exists on port ${localPort}`);
-    return;
-  } catch {
-    // 端口未占用，创建隧道
-  }
-
-  const sshKeyPath = `${process.env.HOME}/.ssh/optima-ec2-key`;
-  if (!fs.existsSync(sshKeyPath)) {
-    throw new Error(`SSH key not found: ${sshKeyPath}. Please obtain optima-ec2-key from xbfool.`);
-  }
-
-  console.log(`Creating SSH tunnel: localhost:${localPort} -> ${ec2Host} -> ${dbHost}:5432`);
-  execSync(
-    `ssh -i ${sshKeyPath} -f -N -o StrictHostKeyChecking=no -L ${localPort}:${dbHost}:5432 ec2-user@${ec2Host}`,
-    { stdio: 'inherit' }
-  );
-  console.log(`✓ SSH tunnel established on port ${localPort}`);
-}
-
 function findPsqlPath(): string {
   // 1. 优先从 PATH 中查找
   const whichCmd = process.platform === 'win32' ? 'where psql' : 'which psql';
@@ -323,10 +298,7 @@ async function main() {
 
     const localPort = environment === 'stage' ? 15432 : 15433;
 
-    setupSSHTunnel(EC2_HOST, dbHost, localPort);
-
-    // 等待隧道建立
-    await new Promise(resolve => setTimeout(resolve, 1000));
+    setupTunnel(dbHost, localPort);
 
     const result = queryDatabase('localhost', localPort, dbUser, dbPassword, database, sql);
     console.log('\n' + result);

package/bin/helpers/verify-health.ts

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+/**
+ * optima-verify-health —— 服务上线健康探针(L1 DNS / L2 TLS / L3-L5 /health)。
+ *
+ * 逐层探、逐层报,逐层 pass 才算上线成功。零依赖(纯 Node 内置)。
+ * 配套静态合规审计 audit-probe.py 在 optima-terraform 仓 docs/cn-prod/probes/(读 terraform 文件,绑仓不搬)。
+ *
+ *   L1 DNS  : FQDN 能解析到 IP
+ *   L2 TLS  : 443 握手 + 证书链/有效期/SNI(SAN)匹配
+ *   L3 /health : optima-core 风格 /health,顶层 status 健康
+ *   L4 真部署  : 解析 gitCommit;传 --expect-commit <sha> 时比对(证明跑的是这次镜像)
+ *   L5 依赖    : checks[*] 全绿(DB/Redis/上游由服务在 health handler 自注册)
+ *
+ * ⚠️ optima-core 的 JS 与 Py 两套 /health schema 不一致,都兼容:
+ *   JS : gitCommit(camel) / status∈{healthy,unhealthy} / 不健康返 503 / 有 gitBranch
+ *   Py : git_commit(snake) / status∈{healthy,degraded} / 永远 200 / check 可 timeout|error / 无 git_branch
+ *
+ * 用法:
+ *   optima-verify-health user-auth                  # 默认 cn-prod
+ *   optima-verify-health user-auth --env prod        # 环境 stage|prod|cn|all
+ *   optima-verify-health --all --env all             # stage/prod/cn 三环境矩阵
+ *   optima-verify-health gateway-core --expect-commit a1b2c3d
+ *   optima-verify-health --url https://auth-cn.optima.chat/health
+ *   optima-verify-health --all --json                # 机器可读,接 CI
+ *   optima-verify-health --all --strict              # warn 也算不通过
+ * 退出码:fail → 非 0;warn 默认放行(0),--strict 让 warn 也非 0。
+ */
+import { promises as dns } from 'node:dns';
+import * as tls from 'node:tls';
+import * as https from 'node:https';
+
+type Env = 'stage' | 'prod' | 'cn';
+interface SvcCfg { path: string; stage?: string; prod?: string; cn?: string; cn_path?: string; }
+
+// 服务 × 环境 FQDN 表。某服务某环境没部署 → 该 env 键缺省,探时跳过。
+// cn-prod 真实 subdomain 抄自 optima-terraform 的 stack main.tf(非文档表,如 agentic-chat 真名是 agentic-chat-cn 不是 ai-cn)。
+const SERVICES: Record<string, SvcCfg> = {
+  'user-auth':        { path: '/health',     stage: 'auth-stage.optima.onl', prod: 'auth.optima.onl', cn: 'auth-cn.optima.chat' },
+  'agentic-chat':     { path: '/api/health', stage: 'ai-stage.optima.onl',   prod: 'ai.optima.onl',   cn: 'agentic-chat-cn.optima.chat' },
+  'commerce-backend': { path: '/health',     stage: 'api-stage.optima.onl',  prod: 'api.optima.onl',  cn: 'api-cn.optima.chat', cn_path: '/health/live' },
+  'mcp-host':         { path: '/health',     stage: 'mcp-stage.optima.onl',  prod: 'mcp.optima.onl' },
+  'gateway-core':     { path: '/health',     cn: 'gw-cn.optima.chat' },
+  'optima-scout':     { path: '/health',     cn: 'scout-cn.optima.chat' },
+  'optima-skills':    { path: '/health',     cn: 'skills-cn.optima.chat' },
+};
+const ENVS: Env[] = ['stage', 'prod', 'cn'];
+
+const G = '\x1b[32m', R = '\x1b[31m', Y = '\x1b[33m', B = '\x1b[34m', N = '\x1b[0m';
+const MARK: Record<string, string> = { ok: `${G}✅${N}`, fail: `${R}❌${N}`, warn: `${Y}⚠️ ${N}`, na: `${B}··${N}` };
+type Result = 'ok' | 'warn' | 'fail';
+interface Layer { layer: string; result: Result; detail: string; }
+
+const verdict = (ls: Layer[]): 'pass' | 'warn' | 'fail' =>
+  ls.some((l) => l.result === 'fail') ? 'fail' : ls.some((l) => l.result === 'warn') ? 'warn' : 'pass';
+
+const VTXT: Record<string, string> = {
+  pass: `${G}上线成功(L1-L5 全绿)${N}`,
+  warn: `${Y}存活但有告警(见上 ⚠️;非阻塞)${N}`,
+  fail: `${R}未通过 — 见上 ❌${N}`,
+};
+
+function tlsCheck(host: string, timeout = 10000): Promise<{ ok: boolean; detail: string; result: Result }> {
+  return new Promise((resolve) => {
+    const sock = tls.connect({ host, port: 443, servername: host, timeout }, () => {
+      const cert = sock.getPeerCertificate();
+      const days = Math.floor((new Date(cert.valid_to).getTime() - Date.now()) / 86400000);
+      const sans = (cert.subjectaltname || '').split(',').map((s) => s.trim().replace(/^DNS:/, '')).slice(0, 3);
+      sock.end();
+      resolve({ ok: true, result: days > 7 ? 'ok' : 'warn',
+        detail: `证书 ${days}d 后过期, SAN=${sans.join(',')}` + (days > 7 ? '' : ` (剩 ${days}d!)`) });
+    });
+    sock.on('error', (e: Error) => resolve({ ok: false, result: 'fail', detail: `握手/证书失败: ${e.message}` }));
+    sock.on('timeout', () => { sock.destroy(); resolve({ ok: false, result: 'fail', detail: '握手超时' }); });
+  });
+}
+
+function httpGet(url: string, timeout = 10000): Promise<{ code: number; body: string; location?: string }> {
+  return new Promise((resolve, reject) => {
+    const req = https.get(url, { headers: { 'User-Agent': 'optima-verify-health' }, timeout }, (res) => {
+      let body = '';
+      res.on('data', (c) => (body += c));
+      res.on('end', () => resolve({ code: res.statusCode || 0, body, location: res.headers.location }));
+    });
+    req.on('error', reject);
+    req.on('timeout', () => { req.destroy(new Error('请求超时')); });
+  });
+}
+
+async function probe(host: string, path: string, expect?: string): Promise<Layer[]> {
+  const layers: Layer[] = [];
+
+  // L1 DNS
+  try {
+    const addrs = await dns.lookup(host, { all: true });
+    const ips = [...new Set(addrs.map((a) => a.address))];
+    layers.push({ layer: 'L1 DNS', result: 'ok', detail: `${host} → ${ips.join(', ')}` });
+  } catch (e: any) {
+    layers.push({ layer: 'L1 DNS', result: 'fail', detail: `${host} 无法解析: ${e.message}` });
+    return layers;
+  }
+
+  // L2 TLS
+  const t = await tlsCheck(host);
+  layers.push({ layer: 'L2 TLS', result: t.result, detail: t.detail });
+  if (!t.ok) return layers;
+
+  // L3-L5 /health
+  const url = `https://${host}${path}`;
+  let r: { code: number; body: string; location?: string };
+  try {
+    r = await httpGet(url);
+  } catch (e: any) {
+    layers.push({ layer: 'L3 /health', result: 'fail', detail: `${url} 无法连接: ${e.message}` });
+    return layers;
+  }
+  if (r.code >= 300 && r.code < 400) {
+    layers.push({ layer: 'L3 /health', result: 'fail', detail: `HTTP ${r.code} 重定向到 ${r.location || '?'}(没路由到服务,疑似未部署/listener 缺失)` });
+    return layers;
+  }
+  let d: any;
+  try { d = JSON.parse(r.body || '{}'); } catch {
+    layers.push({ layer: 'L3 /health', result: 'fail', detail: `HTTP ${r.code} 但非 JSON(可能不是 optima-core /health): ${JSON.stringify(r.body.slice(0, 80))}` });
+    return layers;
+  }
+
+  const status = d.status ?? '?';
+  if (status === 'healthy') layers.push({ layer: 'L3 /health', result: 'ok', detail: `HTTP ${r.code} status=healthy svc=${d.service ?? '?'} ver=${d.version ?? '?'}` });
+  else if (['ok', 'up', 'pass'].includes(status)) layers.push({ layer: 'L3 /health', result: 'warn', detail: `HTTP ${r.code} status=${status}(存活,但非 optima-core 标准 health,L4/L5 无从验证)` });
+  else if (status === 'degraded') layers.push({ layer: 'L3 /health', result: 'warn', detail: `HTTP ${r.code} status=degraded(Py:部分依赖挂但服务起着,见 L5)` });
+  else layers.push({ layer: 'L3 /health', result: 'fail', detail: `HTTP ${r.code} status=${status}` });
+
+  // L4 真部署 / 非裸起
+  const commit: string = d.gitCommit || d.git_commit || '';
+  const branch: string = d.gitBranch || '';
+  const bt = `commit=${commit || '∅'}` + (branch ? ` branch=${branch}` : '');
+  if (!commit) layers.push({ layer: 'L4 部署', result: 'warn', detail: '无 gitCommit(没用 optima-core health,或 build-info 没烘进去)' });
+  else if (expect) {
+    const short = expect.slice(0, commit.length);
+    layers.push(commit === short
+      ? { layer: 'L4 部署', result: 'ok', detail: `${bt} == 期望 ${short} ✓ 跑的是这次镜像` }
+      : { layer: 'L4 部署', result: 'fail', detail: `${bt} != 期望 ${short} ✗ 旧镜像/部署没生效` });
+  } else layers.push({ layer: 'L4 部署', result: 'ok', detail: `${bt}(未传 --expect-commit,仅展示)` });
+
+  // L5 依赖 checks 全绿
+  const checks: Record<string, any> = d.checks || {};
+  const keys = Object.keys(checks);
+  if (keys.length === 0) layers.push({ layer: 'L5 依赖', result: 'warn', detail: 'health 未注册任何 checks(服务没在 handler 里挂 DB/Redis/上游)' });
+  else {
+    const bad = keys.filter((k) => checks[k].status !== 'healthy');
+    const summary = keys.map((k) => `${k}=${checks[k].status}(${checks[k].latencyMs ?? checks[k].latency_ms ?? '?'}ms)`).join(', ');
+    layers.push(bad.length
+      ? { layer: 'L5 依赖', result: 'fail', detail: `${bad.length} 个不健康: ${bad.map((k) => `${k}=${checks[k].status}`).join(',')} | 全部: ${summary}` }
+      : { layer: 'L5 依赖', result: 'ok', detail: `${keys.length} 个依赖全绿: ${summary}` });
+  }
+  return layers;
+}
+
+function resolve(svc: string, e: Env): [string, string, string] | null {
+  const cfg = SERVICES[svc];
+  const host = cfg[e];
+  if (!host) return null;
+  const path = (cfg as any)[`${e}_path`] || cfg.path;
+  return [`${svc} [${e}]`, host, path];
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const has = (f: string) => argv.includes(f);
+  const val = (f: string) => { const i = argv.indexOf(f); return i >= 0 ? argv[i + 1] : undefined; };
+  const asJson = has('--json'), strict = has('--strict');
+  const expect = val('--expect-commit');
+  const env = (val('--env') || 'cn') as Env | 'all';
+  const envs: Env[] = env === 'all' ? ENVS : [env as Env];
+  const positional = argv.filter((x, i) => !x.startsWith('--') && !(i > 0 && argv[i - 1].startsWith('--') && ['--env', '--expect-commit', '--url'].includes(argv[i - 1])));
+
+  let targets: [string, string, string][] = [];
+  if (has('--url')) {
+    const u = new URL(val('--url')!);
+    targets = [[u.hostname, u.hostname, u.pathname || '/health']];
+  } else if (has('--all')) {
+    for (const e of envs) for (const s of Object.keys(SERVICES)) { const t = resolve(s, e); if (t) targets.push(t); }
+  } else if (positional[0] && SERVICES[positional[0]]) {
+    for (const e of envs) { const t = resolve(positional[0], e); if (t) targets.push(t); }
+  } else {
+    console.log((require('fs').readFileSync(__filename, 'utf-8').match(/\/\*\*[\s\S]*?\*\//)?.[0] || '').replace(/^\s*\*?/gm, ''));
+    process.exit(2);
+  }
+  if (targets.length === 0) { console.log(`(无目标:${env} 环境下该服务无部署)`); process.exit(2); }
+
+  const results: any[] = [];
+  let worstOk = true;
+  for (const [name, host, path] of targets) {
+    const layers = await probe(host, path, expect);
+    const v = verdict(layers);
+    if (v === 'fail' || (strict && v === 'warn')) worstOk = false;
+    if (asJson) results.push({ service: name, url: `https://${host}${path}`, verdict: v, layers });
+    else {
+      console.log(`\n${'='.repeat(60)}\n  ${name}  https://${host}${path}\n${'='.repeat(60)}`);
+      for (const l of layers) console.log(`  ${MARK[l.result] || '?'} ${l.layer.padEnd(11)} ${l.detail}`);
+      console.log(`  ${'—'.repeat(56)}\n  ${'结论'.padEnd(10)} ${VTXT[v]}`);
+    }
+  }
+  if (asJson) console.log(JSON.stringify(results, null, 2));
+  // 用 exitCode 而非 process.exit():后者会在管道(--json | jq)未 flush 完就退出而截断输出
+  process.exitCode = worstOk ? 0 : 1;
+}
+
+main();

package/dist/bin/helpers/db-utils.js

@@ -41,17 +41,25 @@ exports.getInfisicalToken = getInfisicalToken;
 exports.getInfisicalSecrets = getInfisicalSecrets;
 exports.parseDatabaseUrl = parseDatabaseUrl;
 exports.setupSSHTunnel = setupSSHTunnel;
+exports.setupSSMTunnel = setupSSMTunnel;
+exports.setupTunnel = setupTunnel;
 exports.queryDB = queryDB;
 exports.connectAuthDB = connectAuthDB;
 exports.connectBillingDB = connectBillingDB;
 exports.resolveUserId = resolveUserId;
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
 // ─── Constants ──────────────────────────────────────────────────────────────
 exports.RDS_HOSTS = {
     stage: 'optima-stage-postgres.ctg866o0ehac.ap-southeast-1.rds.amazonaws.com',
     prod: 'optima-prod-postgres.ctg866o0ehac.ap-southeast-1.rds.amazonaws.com',
 };
+// Shared bastion (optima-bi-data EC2, shared-services stack). Reached via SSM —
+// no public port 22 dependency, so it is immune to the MaxStartups throttling that
+// the open-to-world sshd suffers under internet scan load. SSH path kept as fallback.
+const AWS_REGION = 'ap-southeast-1';
+const BASTION_INSTANCE_ID = 'i-03286fb0a9ce7e6b1';
 const EC2_HOST = '3.0.210.113';
 // ─── SQL escaping ───────────────────────────────────────────────────────────
 /** Escape a string value for safe inclusion in SQL single-quoted literals. */
@@ -137,6 +145,82 @@ function setupSSHTunnel(dbHost, localPort) {
         `-o ExitOnForwardFailure=yes -o ConnectTimeout=10 ` +
         `-L ${localPort}:${dbHost}:5432 ec2-user@${EC2_HOST}`, { stdio: 'inherit' });
 }
+/** Block the current (sync) call for `ms` without spawning a subprocess. */
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function assertSSMPrereqs() {
+    for (const [bin, hint] of [
+        ['session-manager-plugin', 'https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html'],
+        ['aws', 'AWS CLI v2: https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html'],
+    ]) {
+        try {
+            (0, child_process_1.execSync)(`command -v ${bin}`, { stdio: 'ignore' });
+        }
+        catch {
+            throw new Error(`${bin} not found — required for the SSM DB tunnel. Install: ${hint}\n(or set OPTIMA_DB_TUNNEL=ssh to fall back to the legacy SSH tunnel)`);
+        }
+    }
+}
+/**
+ * Open a local→RDS tunnel through the shared bastion using SSM port forwarding.
+ * No public SSH port is touched. A healthy existing tunnel on the port is reused
+ * (the ~2s SSM cold start is paid once, then every query is just a round-trip).
+ */
+function setupSSMTunnel(dbHost, localPort) {
+    let portInUse = false;
+    try {
+        (0, child_process_1.execSync)(`lsof -ti:${localPort}`, { stdio: 'ignore' });
+        portInUse = true;
+    }
+    catch { /* free */ }
+    if (portInUse) {
+        if (isTunnelHealthy(localPort))
+            return; // warm reuse — no cold start
+        console.log(`! Tunnel on port ${localPort} not responding (zombie), replacing...`);
+        killOrphanTunnel(localPort);
+    }
+    assertSSMPrereqs();
+    console.log(`Creating SSM tunnel: localhost:${localPort} -> ${BASTION_INSTANCE_ID} -> ${dbHost}:5432`);
+    const logFile = `${os.tmpdir()}/optima-ssm-tunnel-${localPort}.log`;
+    const out = fs.openSync(logFile, 'w');
+    const child = (0, child_process_1.spawn)('aws', [
+        'ssm', 'start-session',
+        '--region', AWS_REGION,
+        '--target', BASTION_INSTANCE_ID,
+        '--document-name', 'AWS-StartPortForwardingSessionToRemoteHost',
+        '--parameters', `host=${dbHost},portNumber=5432,localPortNumber=${localPort}`,
+    ], { detached: true, stdio: ['ignore', out, out] });
+    child.unref();
+    // Wait until the remote leg actually forwards (pg_isready probes RDS through the
+    // tunnel). Local port binds instantly; the remote hop needs ~1-2s to come up.
+    const deadlineMs = Date.now() + 20000;
+    while (Date.now() < deadlineMs) {
+        if (isTunnelHealthy(localPort)) {
+            console.log(`✓ SSM tunnel ready on port ${localPort}`);
+            return;
+        }
+        sleepSync(500);
+    }
+    let tail = '(no log)';
+    try {
+        tail = fs.readFileSync(logFile, 'utf-8').split('\n').slice(-8).join('\n');
+    }
+    catch { /* ignore */ }
+    throw new Error(`SSM tunnel on port ${localPort} did not become ready within 20s.\n--- ${logFile} ---\n${tail}`);
+}
+/**
+ * Open a DB tunnel through the shared bastion. Defaults to SSM (no public port 22);
+ * set OPTIMA_DB_TUNNEL=ssh to fall back to the legacy SSH tunnel.
+ */
+function setupTunnel(dbHost, localPort) {
+    if ((process.env.OPTIMA_DB_TUNNEL || 'ssm').toLowerCase() === 'ssh') {
+        setupSSHTunnel(dbHost, localPort);
+    }
+    else {
+        setupSSMTunnel(dbHost, localPort);
+    }
+}
 // ─── psql ───────────────────────────────────────────────────────────────────
 function findPsqlPath() {
     try {
@@ -166,8 +250,7 @@ async function connectAuthDB(env, infisicalConfig, token) {
     const secrets = getInfisicalSecrets(infisicalConfig, token, infisicalEnv, '/shared-secrets/database-users');
     const host = exports.RDS_HOSTS[env];
     const port = env === 'stage' ? 15432 : 15433;
-    setupSSHTunnel(host, port);
-    await new Promise(r => setTimeout(r, 1000));
+    setupTunnel(host, port);
     const conn = { host: 'localhost', port, user: secrets['AUTH_DB_USER'], password: secrets['AUTH_DB_PASSWORD'], database: 'optima_auth' };
     return { query: (sql) => queryDB(conn, sql) };
 }
@@ -180,8 +263,7 @@ async function connectBillingDB(env, infisicalConfig, token) {
         throw new Error('DATABASE_URL not found for billing service');
     const parsed = parseDatabaseUrl(dbUrl);
     const port = env === 'stage' ? 15434 : 15435;
-    setupSSHTunnel(parsed.host, port);
-    await new Promise(r => setTimeout(r, 1000));
+    setupTunnel(parsed.host, port);
     const conn = { host: 'localhost', port, user: parsed.user, password: parsed.password, database: parsed.database };
     return { query: (sql) => queryDB(conn, sql) };
 }

package/dist/bin/helpers/query-db.js

@@ -36,6 +36,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
+const db_utils_1 = require("./db-utils");
 const SERVICE_DB_MAP = {
     'commerce-backend': {
         ci: { container: 'commerce-postgres', user: 'commerce', password: 'commerce123', database: 'commerce' },
@@ -113,8 +114,6 @@ const RDS_HOSTS = {
     stage: 'optima-stage-postgres.ctg866o0ehac.ap-southeast-1.rds.amazonaws.com',
     prod: 'optima-prod-postgres.ctg866o0ehac.ap-southeast-1.rds.amazonaws.com'
 };
-// 统一使用 BI Data ARM Host 作为跳板机
-const EC2_HOST = '3.0.210.113';
 function parseDatabaseUrl(url) {
     // postgresql://user:password@host:port/database?params
     const match = url.match(/^postgresql:\/\/([^:]+):([^@]+)@([^:]+):(\d+)\/([^?]+)/);
@@ -153,24 +152,6 @@ function getInfisicalSecrets(config, token, environment, secretPath) {
     }
     return secrets;
 }
-function setupSSHTunnel(ec2Host, dbHost, localPort) {
-    // 检查是否已有隧道
-    try {
-        (0, child_process_1.execSync)(`lsof -ti:${localPort}`, { stdio: 'ignore' });
-        console.log(`✓ SSH tunnel already exists on port ${localPort}`);
-        return;
-    }
-    catch {
-        // 端口未占用，创建隧道
-    }
-    const sshKeyPath = `${process.env.HOME}/.ssh/optima-ec2-key`;
-    if (!fs.existsSync(sshKeyPath)) {
-        throw new Error(`SSH key not found: ${sshKeyPath}. Please obtain optima-ec2-key from xbfool.`);
-    }
-    console.log(`Creating SSH tunnel: localhost:${localPort} -> ${ec2Host} -> ${dbHost}:5432`);
-    (0, child_process_1.execSync)(`ssh -i ${sshKeyPath} -f -N -o StrictHostKeyChecking=no -L ${localPort}:${dbHost}:5432 ec2-user@${ec2Host}`, { stdio: 'inherit' });
-    console.log(`✓ SSH tunnel established on port ${localPort}`);
-}
 function findPsqlPath() {
     // 1. 优先从 PATH 中查找
     const whichCmd = process.platform === 'win32' ? 'where psql' : 'which psql';
@@ -294,9 +275,7 @@ async function main() {
             }
         }
         const localPort = environment === 'stage' ? 15432 : 15433;
-        setupSSHTunnel(EC2_HOST, dbHost, localPort);
-        // 等待隧道建立
-        await new Promise(resolve => setTimeout(resolve, 1000));
+        (0, db_utils_1.setupTunnel)(dbHost, localPort);
         const result = queryDatabase('localhost', localPort, dbUser, dbPassword, database, sql);
         console.log('\n' + result);
     }

package/dist/bin/helpers/verify-health.js

@@ -0,0 +1,253 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * optima-verify-health —— 服务上线健康探针(L1 DNS / L2 TLS / L3-L5 /health)。
+ *
+ * 逐层探、逐层报,逐层 pass 才算上线成功。零依赖(纯 Node 内置)。
+ * 配套静态合规审计 audit-probe.py 在 optima-terraform 仓 docs/cn-prod/probes/(读 terraform 文件,绑仓不搬)。
+ *
+ *   L1 DNS  : FQDN 能解析到 IP
+ *   L2 TLS  : 443 握手 + 证书链/有效期/SNI(SAN)匹配
+ *   L3 /health : optima-core 风格 /health,顶层 status 健康
+ *   L4 真部署  : 解析 gitCommit;传 --expect-commit <sha> 时比对(证明跑的是这次镜像)
+ *   L5 依赖    : checks[*] 全绿(DB/Redis/上游由服务在 health handler 自注册)
+ *
+ * ⚠️ optima-core 的 JS 与 Py 两套 /health schema 不一致,都兼容:
+ *   JS : gitCommit(camel) / status∈{healthy,unhealthy} / 不健康返 503 / 有 gitBranch
+ *   Py : git_commit(snake) / status∈{healthy,degraded} / 永远 200 / check 可 timeout|error / 无 git_branch
+ *
+ * 用法:
+ *   optima-verify-health user-auth                  # 默认 cn-prod
+ *   optima-verify-health user-auth --env prod        # 环境 stage|prod|cn|all
+ *   optima-verify-health --all --env all             # stage/prod/cn 三环境矩阵
+ *   optima-verify-health gateway-core --expect-commit a1b2c3d
+ *   optima-verify-health --url https://auth-cn.optima.chat/health
+ *   optima-verify-health --all --json                # 机器可读,接 CI
+ *   optima-verify-health --all --strict              # warn 也算不通过
+ * 退出码:fail → 非 0;warn 默认放行(0),--strict 让 warn 也非 0。
+ */
+const node_dns_1 = require("node:dns");
+const tls = __importStar(require("node:tls"));
+const https = __importStar(require("node:https"));
+// 服务 × 环境 FQDN 表。某服务某环境没部署 → 该 env 键缺省,探时跳过。
+// cn-prod 真实 subdomain 抄自 optima-terraform 的 stack main.tf(非文档表,如 agentic-chat 真名是 agentic-chat-cn 不是 ai-cn)。
+const SERVICES = {
+    'user-auth': { path: '/health', stage: 'auth-stage.optima.onl', prod: 'auth.optima.onl', cn: 'auth-cn.optima.chat' },
+    'agentic-chat': { path: '/api/health', stage: 'ai-stage.optima.onl', prod: 'ai.optima.onl', cn: 'agentic-chat-cn.optima.chat' },
+    'commerce-backend': { path: '/health', stage: 'api-stage.optima.onl', prod: 'api.optima.onl', cn: 'api-cn.optima.chat', cn_path: '/health/live' },
+    'mcp-host': { path: '/health', stage: 'mcp-stage.optima.onl', prod: 'mcp.optima.onl' },
+    'gateway-core': { path: '/health', cn: 'gw-cn.optima.chat' },
+    'optima-scout': { path: '/health', cn: 'scout-cn.optima.chat' },
+    'optima-skills': { path: '/health', cn: 'skills-cn.optima.chat' },
+};
+const ENVS = ['stage', 'prod', 'cn'];
+const G = '\x1b[32m', R = '\x1b[31m', Y = '\x1b[33m', B = '\x1b[34m', N = '\x1b[0m';
+const MARK = { ok: `${G}✅${N}`, fail: `${R}❌${N}`, warn: `${Y}⚠️ ${N}`, na: `${B}··${N}` };
+const verdict = (ls) => ls.some((l) => l.result === 'fail') ? 'fail' : ls.some((l) => l.result === 'warn') ? 'warn' : 'pass';
+const VTXT = {
+    pass: `${G}上线成功(L1-L5 全绿)${N}`,
+    warn: `${Y}存活但有告警(见上 ⚠️;非阻塞)${N}`,
+    fail: `${R}未通过 — 见上 ❌${N}`,
+};
+function tlsCheck(host, timeout = 10000) {
+    return new Promise((resolve) => {
+        const sock = tls.connect({ host, port: 443, servername: host, timeout }, () => {
+            const cert = sock.getPeerCertificate();
+            const days = Math.floor((new Date(cert.valid_to).getTime() - Date.now()) / 86400000);
+            const sans = (cert.subjectaltname || '').split(',').map((s) => s.trim().replace(/^DNS:/, '')).slice(0, 3);
+            sock.end();
+            resolve({ ok: true, result: days > 7 ? 'ok' : 'warn',
+                detail: `证书 ${days}d 后过期, SAN=${sans.join(',')}` + (days > 7 ? '' : ` (剩 ${days}d!)`) });
+        });
+        sock.on('error', (e) => resolve({ ok: false, result: 'fail', detail: `握手/证书失败: ${e.message}` }));
+        sock.on('timeout', () => { sock.destroy(); resolve({ ok: false, result: 'fail', detail: '握手超时' }); });
+    });
+}
+function httpGet(url, timeout = 10000) {
+    return new Promise((resolve, reject) => {
+        const req = https.get(url, { headers: { 'User-Agent': 'optima-verify-health' }, timeout }, (res) => {
+            let body = '';
+            res.on('data', (c) => (body += c));
+            res.on('end', () => resolve({ code: res.statusCode || 0, body, location: res.headers.location }));
+        });
+        req.on('error', reject);
+        req.on('timeout', () => { req.destroy(new Error('请求超时')); });
+    });
+}
+async function probe(host, path, expect) {
+    const layers = [];
+    // L1 DNS
+    try {
+        const addrs = await node_dns_1.promises.lookup(host, { all: true });
+        const ips = [...new Set(addrs.map((a) => a.address))];
+        layers.push({ layer: 'L1 DNS', result: 'ok', detail: `${host} → ${ips.join(', ')}` });
+    }
+    catch (e) {
+        layers.push({ layer: 'L1 DNS', result: 'fail', detail: `${host} 无法解析: ${e.message}` });
+        return layers;
+    }
+    // L2 TLS
+    const t = await tlsCheck(host);
+    layers.push({ layer: 'L2 TLS', result: t.result, detail: t.detail });
+    if (!t.ok)
+        return layers;
+    // L3-L5 /health
+    const url = `https://${host}${path}`;
+    let r;
+    try {
+        r = await httpGet(url);
+    }
+    catch (e) {
+        layers.push({ layer: 'L3 /health', result: 'fail', detail: `${url} 无法连接: ${e.message}` });
+        return layers;
+    }
+    if (r.code >= 300 && r.code < 400) {
+        layers.push({ layer: 'L3 /health', result: 'fail', detail: `HTTP ${r.code} 重定向到 ${r.location || '?'}(没路由到服务,疑似未部署/listener 缺失)` });
+        return layers;
+    }
+    let d;
+    try {
+        d = JSON.parse(r.body || '{}');
+    }
+    catch {
+        layers.push({ layer: 'L3 /health', result: 'fail', detail: `HTTP ${r.code} 但非 JSON(可能不是 optima-core /health): ${JSON.stringify(r.body.slice(0, 80))}` });
+        return layers;
+    }
+    const status = d.status ?? '?';
+    if (status === 'healthy')
+        layers.push({ layer: 'L3 /health', result: 'ok', detail: `HTTP ${r.code} status=healthy svc=${d.service ?? '?'} ver=${d.version ?? '?'}` });
+    else if (['ok', 'up', 'pass'].includes(status))
+        layers.push({ layer: 'L3 /health', result: 'warn', detail: `HTTP ${r.code} status=${status}(存活,但非 optima-core 标准 health,L4/L5 无从验证)` });
+    else if (status === 'degraded')
+        layers.push({ layer: 'L3 /health', result: 'warn', detail: `HTTP ${r.code} status=degraded(Py:部分依赖挂但服务起着,见 L5)` });
+    else
+        layers.push({ layer: 'L3 /health', result: 'fail', detail: `HTTP ${r.code} status=${status}` });
+    // L4 真部署 / 非裸起
+    const commit = d.gitCommit || d.git_commit || '';
+    const branch = d.gitBranch || '';
+    const bt = `commit=${commit || '∅'}` + (branch ? ` branch=${branch}` : '');
+    if (!commit)
+        layers.push({ layer: 'L4 部署', result: 'warn', detail: '无 gitCommit(没用 optima-core health,或 build-info 没烘进去)' });
+    else if (expect) {
+        const short = expect.slice(0, commit.length);
+        layers.push(commit === short
+            ? { layer: 'L4 部署', result: 'ok', detail: `${bt} == 期望 ${short} ✓ 跑的是这次镜像` }
+            : { layer: 'L4 部署', result: 'fail', detail: `${bt} != 期望 ${short} ✗ 旧镜像/部署没生效` });
+    }
+    else
+        layers.push({ layer: 'L4 部署', result: 'ok', detail: `${bt}(未传 --expect-commit,仅展示)` });
+    // L5 依赖 checks 全绿
+    const checks = d.checks || {};
+    const keys = Object.keys(checks);
+    if (keys.length === 0)
+        layers.push({ layer: 'L5 依赖', result: 'warn', detail: 'health 未注册任何 checks(服务没在 handler 里挂 DB/Redis/上游)' });
+    else {
+        const bad = keys.filter((k) => checks[k].status !== 'healthy');
+        const summary = keys.map((k) => `${k}=${checks[k].status}(${checks[k].latencyMs ?? checks[k].latency_ms ?? '?'}ms)`).join(', ');
+        layers.push(bad.length
+            ? { layer: 'L5 依赖', result: 'fail', detail: `${bad.length} 个不健康: ${bad.map((k) => `${k}=${checks[k].status}`).join(',')} | 全部: ${summary}` }
+            : { layer: 'L5 依赖', result: 'ok', detail: `${keys.length} 个依赖全绿: ${summary}` });
+    }
+    return layers;
+}
+function resolve(svc, e) {
+    const cfg = SERVICES[svc];
+    const host = cfg[e];
+    if (!host)
+        return null;
+    const path = cfg[`${e}_path`] || cfg.path;
+    return [`${svc} [${e}]`, host, path];
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const has = (f) => argv.includes(f);
+    const val = (f) => { const i = argv.indexOf(f); return i >= 0 ? argv[i + 1] : undefined; };
+    const asJson = has('--json'), strict = has('--strict');
+    const expect = val('--expect-commit');
+    const env = (val('--env') || 'cn');
+    const envs = env === 'all' ? ENVS : [env];
+    const positional = argv.filter((x, i) => !x.startsWith('--') && !(i > 0 && argv[i - 1].startsWith('--') && ['--env', '--expect-commit', '--url'].includes(argv[i - 1])));
+    let targets = [];
+    if (has('--url')) {
+        const u = new URL(val('--url'));
+        targets = [[u.hostname, u.hostname, u.pathname || '/health']];
+    }
+    else if (has('--all')) {
+        for (const e of envs)
+            for (const s of Object.keys(SERVICES)) {
+                const t = resolve(s, e);
+                if (t)
+                    targets.push(t);
+            }
+    }
+    else if (positional[0] && SERVICES[positional[0]]) {
+        for (const e of envs) {
+            const t = resolve(positional[0], e);
+            if (t)
+                targets.push(t);
+        }
+    }
+    else {
+        console.log((require('fs').readFileSync(__filename, 'utf-8').match(/\/\*\*[\s\S]*?\*\//)?.[0] || '').replace(/^\s*\*?/gm, ''));
+        process.exit(2);
+    }
+    if (targets.length === 0) {
+        console.log(`(无目标:${env} 环境下该服务无部署)`);
+        process.exit(2);
+    }
+    const results = [];
+    let worstOk = true;
+    for (const [name, host, path] of targets) {
+        const layers = await probe(host, path, expect);
+        const v = verdict(layers);
+        if (v === 'fail' || (strict && v === 'warn'))
+            worstOk = false;
+        if (asJson)
+            results.push({ service: name, url: `https://${host}${path}`, verdict: v, layers });
+        else {
+            console.log(`\n${'='.repeat(60)}\n  ${name}  https://${host}${path}\n${'='.repeat(60)}`);
+            for (const l of layers)
+                console.log(`  ${MARK[l.result] || '?'} ${l.layer.padEnd(11)} ${l.detail}`);
+            console.log(`  ${'—'.repeat(56)}\n  ${'结论'.padEnd(10)} ${VTXT[v]}`);
+        }
+    }
+    if (asJson)
+        console.log(JSON.stringify(results, null, 2));
+    // 用 exitCode 而非 process.exit():后者会在管道(--json | jq)未 flush 完就退出而截断输出
+    process.exitCode = worstOk ? 0 : 1;
+}
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optima-chat/dev-skills",
-  "version": "0.7.37",
+  "version": "0.7.38",
   "description": "Claude Code Skills for Optima development team - cross-environment collaboration tools",
   "main": "index.js",
   "bin": {
@@ -13,7 +13,8 @@
     "optima-discount": "dist/bin/helpers/discount.js",
     "optima-product": "dist/bin/helpers/product.js",
     "optima-query-db": "dist/bin/helpers/query-db.js",
-    "optima-show-env": "dist/bin/helpers/show-env.js"
+    "optima-show-env": "dist/bin/helpers/show-env.js",
+    "optima-verify-health": "dist/bin/helpers/verify-health.js"
   },
   "scripts": {
     "postinstall": "node scripts/install.js",