@optima-chat/dev-skills 0.7.37 → 0.7.40

package/bin/helpers/grant-subscription.ts

@@ -1,6 +1,19 @@
 #!/usr/bin/env node
 
-import { getInfisicalConfig, getInfisicalToken, resolveUserId, connectBillingDB, escapeSQL } from './db-utils';
+// P15 D8b：USD 钱包退役——原「SSH 直写 subscriptions/usd_wallets/token_quotas」
+// 作废，改调 billing 服务态端点（与用户态 /api/admin/grant-subscription 同
+// 业务体：supersede 旧授予 + 实得 credits + token quota，重试双发不双倍）。
+import { getInfisicalConfig, getInfisicalToken, resolveUserId } from './db-utils';
+import { callBilling, resolveUserIdByEmail, validateEnvCnProd } from './billing-http';
+
+// cn-prod sells the CNY-priced -cn plans (P12); the bare USD plan ids also
+// exist in the cn DB, so a per-env whitelist (not billing-side validation)
+// is what prevents accidentally granting a USD-priced plan to a CN user.
+const PLANS_BY_ENV: Record<string, string[]> = {
+  stage: ['trial', 'starter', 'pro', 'enterprise'],
+  prod: ['trial', 'starter', 'pro', 'enterprise'],
+  'cn-prod': ['trial', 'starter-cn', 'pro-cn', 'enterprise-cn'],
+};
 
 function parseArgs(args: string[]): { email: string; plan: string; months: number; env: string } {
   if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
@@ -8,14 +21,15 @@ function parseArgs(args: string[]): { email: string; plan: string; months: numbe
 
 Options:
   --plan <id>       Plan: trial, starter, pro, enterprise (default: pro)
+                    cn-prod plans: trial, starter-cn, pro-cn, enterprise-cn (default: pro-cn)
   --months <n>      Duration in months (default: 1)
-  --env <env>       Environment: stage, prod (default: stage)
+  --env <env>       Environment: stage, prod, cn-prod (default: stage)
   -h, --help        Show this help`);
     process.exit(0);
   }
 
   const email = args[0];
-  let plan = 'pro';
+  let plan: string | null = null;
   let months = 1;
   let env = 'stage';
 
@@ -25,106 +39,50 @@ Options:
     else if (args[i] === '--env' && args[i + 1]) { env = args[++i]; }
   }
 
-  if (!['trial', 'starter', 'pro', 'enterprise'].includes(plan)) {
-    console.error(`Unknown plan: ${plan}. Available: trial, starter, pro, enterprise`);
+  validateEnvCnProd(env);
+  plan = plan ?? (env === 'cn-prod' ? 'pro-cn' : 'pro');
+  const allowed = PLANS_BY_ENV[env];
+  if (!allowed.includes(plan)) {
+    console.error(`Unknown plan for ${env}: ${plan}. Available: ${allowed.join(', ')}`);
     process.exit(1);
   }
   if (months < 1) { console.error('Months must be >= 1'); process.exit(1); }
-  if (!['stage', 'prod'].includes(env)) { console.error('Env must be stage or prod (billing DB not available in CI)'); process.exit(1); }
 
   return { email, plan, months, env };
 }
 
 async function main() {
   const { email, plan, months, env } = parseArgs(process.argv.slice(2));
-  const infisicalConfig = getInfisicalConfig();
-  const token = getInfisicalToken(infisicalConfig);
 
   console.log(`\n🎁 Granting ${plan} subscription to ${email} for ${months} month(s) [${env.toUpperCase()}]\n`);
 
-  const userId = await resolveUserId(email, env, infisicalConfig, token);
-  const billing = await connectBillingDB(env, infisicalConfig, token);
-  const bq = billing.query;
-
-  // Read plan config from DB
-  console.log(`Loading plan config: ${plan}`);
-  const planRow = bq(`SELECT name, monthly_credits, session_token_limit, weekly_token_limit FROM plans WHERE id='${escapeSQL(plan)}'`);
-  if (!planRow) { console.error(`❌ Plan not found in DB: ${plan}`); process.exit(1); }
-
-  const [planName, monthlyCreditsStr, sessionTokenLimitStr, weeklyTokenLimitStr] = planRow.split('|');
-  const monthlyCredits = parseInt(monthlyCreditsStr, 10);
-  const grantMicros = monthlyCredits * 10000; // 1 credit = $0.01 = 10,000 micros
-  const sessionTokenLimit = parseInt(sessionTokenLimitStr, 10);
-  const weeklyTokenLimit = parseInt(weeklyTokenLimitStr, 10);
-  console.log(`✓ Plan: ${planName} (grant: $${(grantMicros / 1000000).toFixed(2)}, session: ${sessionTokenLimit.toLocaleString()}, weekly: ${weeklyTokenLimit.toLocaleString()})`);
-
-  // Execute all mutations in a single transaction
-  const now = new Date().toISOString();
-  const periodEnd = new Date();
-  periodEnd.setMonth(periodEnd.getMonth() + months);
-  const periodEndISO = periodEnd.toISOString();
-  const sessionEnd = new Date(new Date().getTime() + 5 * 60 * 60 * 1000).toISOString();
-  const weekEnd = new Date(new Date().getTime() + 7 * 24 * 60 * 60 * 1000).toISOString();
-
-  const safeUserId = escapeSQL(userId);
-  const safePlan = escapeSQL(plan);
-  const safePlanName = escapeSQL(planName);
-
-  console.log('Executing transaction...');
-  const txSQL = `
-BEGIN;
-
--- Cancel active subscriptions
-UPDATE subscriptions SET status='canceled', canceled_at='${now}'
-WHERE user_id='${safeUserId}' AND status IN ('active','trialing');
-
--- Create new subscription
-INSERT INTO subscriptions (id, user_id, plan_id, status, billing_interval, current_period_start, current_period_end, created_at, updated_at)
-VALUES (concat('sub_gift_', substr(md5(random()::text), 1, 16)), '${safeUserId}', '${safePlan}', 'active', 'monthly', '${now}', '${periodEndISO}', '${now}', '${now}');
-
--- Ensure wallet exists (upsert)
-INSERT INTO usd_wallets (id, user_id, balance_micros, reserved_micros, granted_balance_micros, created_at, updated_at)
-VALUES (gen_random_uuid(), '${safeUserId}', 0, 0, 0, '${now}', '${now}')
-ON CONFLICT (user_id) DO NOTHING;
-
--- Reset granted balance and set new grant
-UPDATE usd_wallets SET granted_balance_micros = ${grantMicros}, updated_at = '${now}'
-WHERE user_id = '${safeUserId}';
-
--- Record topup for audit trail
-INSERT INTO usd_wallet_topups (id, wallet_id, amount_micros, service_fee_micros, net_credit_micros, status, source, service_namespace, created_at, completed_at)
-SELECT gen_random_uuid(), w.id, ${grantMicros}, 0, ${grantMicros}, 'completed', 'subscription_grant', 'platform', '${now}', '${now}'
-FROM usd_wallets w WHERE w.user_id = '${safeUserId}';
-
--- Update existing active session quota, or insert new one if none exists
-UPDATE token_quotas SET plan_id='${safePlan}', monthly_limit=${sessionTokenLimit}, updated_at='${now}'
-WHERE user_id='${safeUserId}' AND period_type='session' AND period_end > '${now}';
-
-INSERT INTO token_quotas (id, user_id, plan_id, period_type, monthly_limit, monthly_used, period_start, period_end, created_at, updated_at)
-SELECT concat('tq_sess_', substr(md5(random()::text), 1, 16)), '${safeUserId}', '${safePlan}', 'session', ${sessionTokenLimit}, 0, '${now}', '${sessionEnd}', '${now}', '${now}'
-WHERE NOT EXISTS (SELECT 1 FROM token_quotas WHERE user_id='${safeUserId}' AND period_type='session' AND period_end > '${now}');
-
--- Update existing active weekly quota, or insert new one if none exists
-UPDATE token_quotas SET plan_id='${safePlan}', monthly_limit=${weeklyTokenLimit}, updated_at='${now}'
-WHERE user_id='${safeUserId}' AND period_type='weekly' AND period_end > '${now}';
-
-INSERT INTO token_quotas (id, user_id, plan_id, period_type, monthly_limit, monthly_used, period_start, period_end, created_at, updated_at)
-SELECT concat('tq_week_', substr(md5(random()::text), 1, 16)), '${safeUserId}', '${safePlan}', 'weekly', ${weeklyTokenLimit}, 0, '${now}', '${weekEnd}', '${now}', '${now}'
-WHERE NOT EXISTS (SELECT 1 FROM token_quotas WHERE user_id='${safeUserId}' AND period_type='weekly' AND period_end > '${now}');
-
-COMMIT;
-  `.trim();
-
-  bq(txSQL);
-
-  console.log('✓ Old subscriptions canceled');
-  console.log(`✓ ${planName} subscription created (expires: ${periodEnd.toLocaleDateString()})`);
-  if (grantMicros > 0) {
-    console.log(`✓ Wallet granted $${(grantMicros / 1000000).toFixed(2)} (${monthlyCredits} credits equivalent)`);
+  // cn-prod has no SSH tunnel into the Aliyun RDS — resolve via user-auth's
+  // internal lookup API instead of the direct SQL path.
+  let userId: string;
+  if (env === 'cn-prod') {
+    userId = await resolveUserIdByEmail(env, email);
+  } else {
+    const infisicalConfig = getInfisicalConfig();
+    const token = getInfisicalToken(infisicalConfig);
+    userId = await resolveUserId(email, env, infisicalConfig, token);
   }
-  console.log(`✓ Token quotas updated (session: ${sessionTokenLimit.toLocaleString()}, weekly: ${weeklyTokenLimit.toLocaleString()})`);
 
-  console.log(`\n✅ Done! ${email} now has ${planName} plan until ${periodEnd.toLocaleDateString()}\n`);
+  const { body } = await callBilling<{
+    success: boolean;
+    subscriptionId: string;
+    planId: string;
+    credits: number;
+    sessionTokenLimit: number;
+    weeklyTokenLimit: number;
+    expiresAt: string;
+    warning?: string;
+  }>(env, 'POST', '/api/billing/admin/grant-subscription', { userId, planId: plan, months });
+
+  console.log(`✓ Subscription ${body.subscriptionId} (${body.planId})`);
+  console.log(`✓ Credits: ${body.credits.toLocaleString()} (expires ${body.expiresAt})`);
+  console.log(`✓ Token limits: session ${body.sessionTokenLimit.toLocaleString()} / weekly ${body.weeklyTokenLimit.toLocaleString()}`);
+  if (body.warning) console.log(`⚠️  ${body.warning}`);
+  console.log(`\n✅ Done! ${email} now has ${body.planId} until ${body.expiresAt}\n`);
 }
 
 main().catch(error => {

package/bin/helpers/query-db.ts

@@ -2,13 +2,7 @@
 
 import { execSync } from 'child_process';
 import * as fs from 'fs';
-
-interface InfisicalConfig {
-  url: string;
-  clientId: string;
-  clientSecret: string;
-  projectId: string;
-}
+import { ensureTunnel, getGitHubVariable, getInfisicalConfig, getInfisicalToken, getInfisicalSecrets, parseDatabaseUrl, isCnEnv, connectCnDB, connectCnDBFromUrl } from './db-utils';
 
 interface DatabaseConfig {
   host: string;
@@ -96,80 +90,8 @@ 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+)\/([^?]+)/);
-  if (!match) {
-    throw new Error(`Failed to parse DATABASE_URL: ${url}`);
-  }
-  return {
-    user: decodeURIComponent(match[1]),
-    password: decodeURIComponent(match[2]),
-    host: match[3],
-    port: parseInt(match[4]),
-    database: match[5]
-  };
-}
-
-function getGitHubVariable(name: string): string {
-  return execSync(`gh variable get ${name} -R Optima-Chat/optima-dev-skills`, { encoding: 'utf-8' }).trim();
-}
-
-function getInfisicalConfig(): InfisicalConfig {
-  return {
-    url: getGitHubVariable('INFISICAL_URL'),
-    clientId: getGitHubVariable('INFISICAL_CLIENT_ID'),
-    clientSecret: getGitHubVariable('INFISICAL_CLIENT_SECRET'),
-    projectId: getGitHubVariable('INFISICAL_PROJECT_ID')
-  };
-}
-
-function getInfisicalToken(config: InfisicalConfig): string {
-  const response = execSync(
-    `curl -s -X POST "${config.url}/api/v1/auth/universal-auth/login" -H "Content-Type: application/json" -d '{"clientId": "${config.clientId}", "clientSecret": "${config.clientSecret}"}'`,
-    { encoding: 'utf-8' }
-  );
-  return JSON.parse(response).accessToken;
-}
-
-function getInfisicalSecrets(config: InfisicalConfig, token: string, environment: string, secretPath: string): Record<string, string> {
-  const response = execSync(
-    `curl -s "${config.url}/api/v3/secrets/raw?workspaceId=${config.projectId}&environment=${environment}&secretPath=${secretPath}" -H "Authorization: Bearer ${token}"`,
-    { encoding: 'utf-8' }
-  );
-  const data = JSON.parse(response);
-  const secrets: Record<string, string> = {};
-  for (const secret of data.secrets || []) {
-    secrets[secret.secretKey] = secret.secretValue;
-  }
-  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}`);
-}
+// parseDatabaseUrl 统一用 db-utils 的实现：右切 userinfo 容忍密码特殊字符，
+// 且报错不回显 URL（这里曾把含密码的完整 URL 打进错误信息）。
 
 function findPsqlPath(): string {
   // 1. 优先从 PATH 中查找
@@ -235,7 +157,7 @@ async function main() {
     console.error('Usage: query-db.ts <service> <sql> [environment]');
     console.error('');
     console.error('Services: commerce-backend, user-auth, agentic-chat, bi-backend, session-gateway, gateway-core, optima-logistics, billing, ads-backend, amazon-backend, browser-backend, shopify-backend, optima-generation, optima-sentinel');
-    console.error('Environments: ci (default), stage, prod');
+    console.error('Environments: ci (default), stage, prod, cn (阿里云 cn-prod)');
     console.error('');
     console.error('Example: query-db.ts user-auth "SELECT COUNT(*) FROM users" prod');
     process.exit(1);
@@ -249,6 +171,26 @@ async function main() {
     process.exit(1);
   }
 
+  // cn-prod（阿里云）：独立 Infisical + 经 buildbox 跳板连内网 RDS（动态端口隧道）。
+  // 两类 cred：① shared-secrets/database-users（按 prefix）② 服务自己的 DATABASE_URL（展开引用）。
+  if (isCnEnv(environment)) {
+    const prodCfg = SERVICE_DB_MAP[service as keyof typeof SERVICE_DB_MAP].prod as any;
+    let db: { query: (sql: string) => string };
+    if (prodCfg?.userKey) {
+      const prefix = prodCfg.userKey.replace(/_DB_USER$/, '');
+      console.log(`\n🔍 Querying ${service} (CN-PROD, prefix ${prefix})...`);
+      db = connectCnDB(prefix);
+    } else if (prodCfg?.databaseUrlPath) {
+      console.log(`\n🔍 Querying ${service} (CN-PROD, DATABASE_URL @ ${prodCfg.databaseUrlPath})...`);
+      db = connectCnDBFromUrl(prodCfg.databaseUrlPath);
+    } else {
+      console.error(`cn-prod query 暂不支持 ${service}（既无 userKey 也无 databaseUrlPath）。见 optima-dev-skills#21。`);
+      process.exit(1);
+    }
+    console.log('\n' + db.query(sql));
+    return;
+  }
+
   const serviceConfig = SERVICE_DB_MAP[service as keyof typeof SERVICE_DB_MAP][environment as 'ci' | 'stage' | 'prod'];
 
   if (!serviceConfig) {
@@ -321,12 +263,7 @@ async function main() {
       }
     }
 
-    const localPort = environment === 'stage' ? 15432 : 15433;
-
-    setupSSHTunnel(EC2_HOST, dbHost, localPort);
-
-    // 等待隧道建立
-    await new Promise(resolve => setTimeout(resolve, 1000));
+    const localPort = ensureTunnel(dbHost);
 
     const result = queryDatabase('localhost', localPort, dbUser, dbPassword, database, sql);
     console.log('\n' + result);

package/bin/helpers/show-env.ts

@@ -1,13 +1,7 @@
 #!/usr/bin/env node
 
 import { execSync } from 'child_process';
-
-interface InfisicalConfig {
-  url: string;
-  clientId: string;
-  clientSecret: string;
-  projectId: string;
-}
+import { getInfisicalConfig, getInfisicalToken, InfisicalConfig } from './db-utils';
 
 // 支持的服务列表（Infisical 路径为 /services/<service-name>）
 const SUPPORTED_SERVICES = [
@@ -44,27 +38,8 @@ const ENV_MAP: Record<string, string> = {
   prod: 'prod'
 };
 
-function getGitHubVariable(name: string): string {
-  return execSync(`gh variable get ${name} -R Optima-Chat/optima-dev-skills`, { encoding: 'utf-8' }).trim();
-}
-
-function getInfisicalConfig(): InfisicalConfig {
-  return {
-    url: getGitHubVariable('INFISICAL_URL'),
-    clientId: getGitHubVariable('INFISICAL_CLIENT_ID'),
-    clientSecret: getGitHubVariable('INFISICAL_CLIENT_SECRET'),
-    projectId: getGitHubVariable('INFISICAL_PROJECT_ID')
-  };
-}
-
-function getInfisicalToken(config: InfisicalConfig): string {
-  const response = execSync(
-    `curl -s -X POST "${config.url}/api/v1/auth/universal-auth/login" -H "Content-Type: application/json" -d '{"clientId": "${config.clientId}", "clientSecret": "${config.clientSecret}"}'`,
-    { encoding: 'utf-8' }
-  );
-  return JSON.parse(response).accessToken;
-}
-
+// NOTE: getInfisicalSecrets is kept local because it encodes secretPath (encodeURIComponent),
+// unlike db-utils' raw-path variant; getGitHubVariable/getInfisicalConfig/getInfisicalToken are shared from db-utils.
 function getInfisicalSecrets(config: InfisicalConfig, token: string, environment: string, secretPath: string): Record<string, string> {
   const response = execSync(
     `curl -s "${config.url}/api/v3/secrets/raw?workspaceId=${config.projectId}&environment=${environment}&secretPath=${encodeURIComponent(secretPath)}" -H "Authorization: Bearer ${token}"`,

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();