@optima-chat/dev-skills 0.16.6 → 0.16.8

package/bin/helpers/verify-health.ts

@@ -17,8 +17,8 @@
  *
  * 用法:
  *   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 user-auth --env prod        # 环境 stage|prod|cn-prod|cn-stage|all
+ *   optima-verify-health --all --env all             # stage/prod/cn-prod/cn-stage 四环境矩阵
  *   optima-verify-health gateway-core --expect-commit a1b2c3d
  *   optima-verify-health --url https://auth.yzsgo.com/health
  *   optima-verify-health --all --json                # 机器可读,接 CI
@@ -29,23 +29,40 @@ import { promises as dns } from 'node:dns';
 import * as tls from 'node:tls';
 import * as https from 'node:https';
 
-type Env = 'stage' | 'prod' | 'cn' | 'cn-stage';
-interface SvcCfg { path: string; stage?: string; prod?: string; cn?: string; cn_path?: string; 'cn-stage'?: string; 'cn-stage_path'?: string; }
+// 环境名与全仓保持一致（logs.ts 的 CN_ENVS、query-db.ts 的 VALID_ENVS、show-env、
+// billing-http 的 validateEnvCnProd）：阿里云生产叫 cn-prod，不叫 cn。
+// 🔴 名字对不上时 resolve() 会把每个 SvcCfg 键查成 undefined，于是走到「无目标」分支，
+// 把「环境名打错」报成「该服务无部署」—— 与 #83 那批 301 被报成「疑似未部署」同一个病：
+// 探针在不确定的时候撒了一个确定的谎。
+type Env = 'stage' | 'prod' | 'cn-prod' | 'cn-stage';
+interface SvcCfg { path: string; stage?: string; prod?: string; 'cn-prod'?: string; 'cn-prod_path'?: string; 'cn-stage'?: string; 'cn-stage_path'?: string; }
 
 // 服务 × 环境 FQDN 表。某服务某环境没部署 → 该 env 键缺省,探时跳过。
 // cn-prod 真实 subdomain 抄自 optima-terraform alicloud/stacks/cn-prod-ingress-sae/main.tf。
 // #201 (2026-06-12): yzsgo.com 全量迁移完成,旧 *-cn.optima.chat 路由已下线。
 // cn-stage（阿里云预发）域名 *.stage.optima.chat，抄自 cn-stage-ingress-sae services map。
+// #83 (2026-08-13): AWS stage 是 *.stage.optima.onl（点号），旧的连字符形式 *-stage.optima.onl
+// 已不再路由到服务——三项实测 301 → www.optima.onl，探测恒红并误报成「疑似未部署」。
+// 🔴 别只看 stage 列：agentic-chat 的 prod 也踩同一个坑（见下面那行的注释）。
 const SERVICES: Record<string, SvcCfg> = {
-  'user-auth':        { path: '/health',     stage: 'auth-stage.optima.onl', prod: 'auth.optima.onl', cn: 'auth.yzsgo.com', 'cn-stage': 'auth.stage.optima.chat' },
-  'agentic-chat':     { path: '/api/health', stage: 'ai-stage.optima.onl',   prod: 'ai.optima.onl',   cn: 'app.yzsgo.com', 'cn-stage': 'app.stage.optima.chat' },
-  'commerce-backend': { path: '/health',     stage: 'api-stage.optima.onl',  prod: 'api.optima.onl',  cn: 'commerce.yzsgo.com', cn_path: '/health/live', 'cn-stage': 'commerce.stage.optima.chat', 'cn-stage_path': '/health/live' },
-  'mcp-host':         { path: '/health',     stage: 'mcp-stage.optima.onl',  prod: 'mcp.optima.onl' },
-  'gateway-core':     { path: '/health',     cn: 'gw.yzsgo.com', 'cn-stage': 'gw.stage.optima.chat' },
-  'optima-scout':     { path: '/health',     cn: 'scout.yzsgo.com', 'cn-stage': 'scout.stage.optima.chat' },
-  'optima-skills':    { path: '/health',     cn: 'skills.yzsgo.com', 'cn-stage': 'skills.stage.optima.chat' },
+  'user-auth':        { path: '/health',     stage: 'auth.stage.optima.onl', prod: 'auth.optima.onl', 'cn-prod': 'auth.yzsgo.com', 'cn-stage': 'auth.stage.optima.chat' },
+  // agentic-chat 的 prod 入口是 www 不是 ai：prod-ecs/variables.tf 里它的 subdomain = "www"，
+  // 且 main.tf 有一条 ai_to_www_redirect(priority 309) 专门把 ai.optima.onl 301 到 www。
+  // 实测 ai.optima.onl/api/health → 301；www.optima.onl/api/health → 200 service=agentic-chat。
+  'agentic-chat':     { path: '/api/health', stage: 'ai.stage.optima.onl',   prod: 'www.optima.onl',  'cn-prod': 'app.yzsgo.com', 'cn-stage': 'app.stage.optima.chat' },
+  'commerce-backend': { path: '/health',     stage: 'api.stage.optima.onl',  prod: 'api.optima.onl',  'cn-prod': 'commerce.yzsgo.com', 'cn-prod_path': '/health/live', 'cn-stage': 'commerce.stage.optima.chat', 'cn-stage_path': '/health/live' },
+  // #83: mcp-host 已于 2025-12-18 下线,故不在表内 —— optima-terraform origin/main(f97adbb) 的
+  // stage-ecs/variables.tf:146 与 prod-ecs/variables.tf:508 都写着「MCP 工具服务已移除」,
+  // 两个 ecs stack 的 services map 里均无该条目;实测四个候选主机名全是壳(mcp.stage.optima.onl
+  // 307 → /en-US/health 前端 locale 路由,mcp-stage.optima.onl 与 prod 的 mcp.optima.onl 均
+  // 301 → www)。🔴 别再把它加回来:worstOk 是全局单标志(见 main()),留着它会让 `--all --env stage`
+  // 与 `--all --env prod` 恒 exit 1,而那个退出码正是接 CI 卡口时唯一被读的东西。
+  // 同一约束在 tests/service-matrix-alignment.test.js 里对 show-env 的清单也钉着。
+  'gateway-core':     { path: '/health',     'cn-prod': 'gw.yzsgo.com', 'cn-stage': 'gw.stage.optima.chat' },
+  'optima-scout':     { path: '/health',     'cn-prod': 'scout.yzsgo.com', 'cn-stage': 'scout.stage.optima.chat' },
+  'optima-skills':    { path: '/health',     'cn-prod': 'skills.yzsgo.com', 'cn-stage': 'skills.stage.optima.chat' },
 };
-const ENVS: Env[] = ['stage', 'prod', 'cn', 'cn-stage'];
+const ENVS: Env[] = ['stage', 'prod', 'cn-prod', 'cn-stage'];
 
 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}` };
@@ -165,27 +182,56 @@ function resolve(svc: string, e: Env): [string, string, string] | null {
   return [`${svc} [${e}]`, host, path];
 }
 
+export interface Args { help: boolean; json: boolean; strict: boolean; all: boolean; env: Env | 'all'; expect?: string; url?: string; service?: string; }
+
+// 🔴 不认识的输入一律报错、绝不静默丢弃（同 query-db.ts 的 parseQueryDbArgs、logs.ts 的 parseArgs）：
+// 此前 `--env=stage` 不认、`--env` 漏写取值、多敲一个位置参数都会被静默无视而回落默认 cn-prod ——
+// 想探 stage，实际探的是阿里云生产，还 exit 0。
+export function parseArgs(argv: string[]): Args {
+  const flags = new Set<string>(), vals: Record<string, string> = {}, positional: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const eq = arg.startsWith('--') ? arg.indexOf('=') : -1;
+    const name = eq > 0 ? arg.slice(0, eq) : arg;
+    if (['--env', '--expect-commit', '--url'].includes(name)) {
+      const v = eq > 0 ? arg.slice(eq + 1) : argv[++i];
+      if (!v || v.startsWith('-')) throw new Error(`${name} 缺少取值`);
+      vals[name] = v;
+    } else if (['--json', '--strict', '--all', '--help', '-h'].includes(arg)) flags.add(arg);
+    else if (arg.startsWith('-')) throw new Error(`未知参数:${arg}`);
+    else positional.push(arg);
+  }
+  // 🔴 必须先校验再转型：不校验的话任何不认识的 env 都会让 resolve() 把每个 SvcCfg 键查成
+  // undefined，于是落到下面的「无目标」分支，把「环境名打错」报成「该服务无部署」——
+  // 一个活着的服务被说成没上线，正是 #83 要根治的那类静默误报。
+  let envArg = vals['--env'] || 'cn-prod';
+  // 'cn' 是本文件的历史叫法，继续放行但不在 usage 里宣传（同 query-db.ts 的 ENV_ALIASES）。
+  if (envArg === 'cn') envArg = 'cn-prod';
+  if (envArg !== 'all' && !ENVS.includes(envArg as Env)) throw new Error(`未知环境:${envArg}(可选:${ENVS.join(' | ')} | all)`);
+  if (positional.length > 1) throw new Error(`多余参数:${positional.slice(1).join(' ')}(一次探一个服务;环境用 --env 指定)`);
+  const service = positional[0];
+  if (service && !Object.keys(SERVICES).includes(service)) throw new Error(`未知服务:${service}(可选:${Object.keys(SERVICES).join(' | ')})`);
+  const url = vals['--url'], all = flags.has('--all');
+  return { help: flags.has('--help') || flags.has('-h') || !(url || all || service), json: flags.has('--json'), strict: flags.has('--strict'), all, env: envArg as Env | 'all', expect: vals['--expect-commit'], url, service };
+}
+
 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 args: Args;
+  try { args = parseArgs(process.argv.slice(2)); } catch (e: any) { console.error(`❌ ${e.message}`); process.exit(2); }
+  const { json: asJson, strict, expect, env } = args;
+  const envs: Env[] = env === 'all' ? ENVS : [env];
 
   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 {
+  if (args.help) {
     console.log((require('fs').readFileSync(__filename, 'utf-8').match(/\/\*\*[\s\S]*?\*\//)?.[0] || '').replace(/^\s*\*?/gm, ''));
     process.exit(2);
+  } else if (args.url) {
+    const u = new URL(args.url);
+    targets = [[u.hostname, u.hostname, u.pathname || '/health']];
+  } else if (args.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 (args.service) {
+    for (const e of envs) { const t = resolve(args.service, e); if (t) targets.push(t); }
   }
   if (targets.length === 0) { console.log(`(无目标:${env} 环境下该服务无部署)`); process.exit(2); }
 
@@ -207,4 +253,6 @@ async function main() {
   process.exitCode = worstOk ? 0 : 1;
 }
 
-main();
+if (require.main === module) {
+  main();
+}

package/dist/bin/helpers/billing-http.js

@@ -156,7 +156,15 @@ function getServiceToken(env, scope) {
     const effectiveScope = scope ?? (isCn ? CN_PROD_TOKEN_SCOPE : undefined);
     const scopeParam = effectiveScope ? `&scope=${encodeURIComponent(effectiveScope)}` : '';
     const body = `grant_type=client_credentials&client_id=${encodeURIComponent(clientId)}&client_secret=${encodeURIComponent(clientSecret)}${scopeParam}`;
-    const response = (0, child_process_1.execSync)(`curl -s -X POST '${authUrl}/api/v1/oauth/token' -H 'Content-Type: application/x-www-form-urlencoded' -d '${body}'`, { encoding: 'utf-8' });
+    // execFileSync + 参数数组（不经 shell）：Windows cmd.exe 不认单引号，shell 拼出的
+    // `-d '${body}'` 会被拆碎、curl 收到垃圾参数直接退出（#92）。数组传参绕开 shell、
+    // 跨平台一致；函数保持同步。
+    const response = (0, child_process_1.execFileSync)('curl', [
+        '-s', '-X', 'POST',
+        `${authUrl}/api/v1/oauth/token`,
+        '-H', 'Content-Type: application/x-www-form-urlencoded',
+        '-d', body,
+    ], { encoding: 'utf-8' });
     let parsed;
     try {
         parsed = JSON.parse(response);

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

@@ -117,8 +117,14 @@ function getInfisicalConfig() {
     };
 }
 function getInfisicalToken(config) {
-    const response = (0, child_process_1.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;
+    // 复用 curlJson（execFileSync + 参数数组、不经 shell）：Windows cmd.exe 不认单引号，
+    // 原来 shell 拼的 `-d '{...}'` JSON body 会被拆碎、curl 收垃圾参数直接退出（#92）。
+    // cn 路径早已用 curlJson，这里对齐；函数保持同步（调用方无需改 async）。
+    return curlJson([
+        '-X', 'POST', `${config.url}/api/v1/auth/universal-auth/login`,
+        '-H', 'Content-Type: application/json',
+        '-d', JSON.stringify({ clientId: config.clientId, clientSecret: config.clientSecret }),
+    ]).accessToken;
 }
 function getInfisicalSecrets(config, token, environment, secretPath) {
     const response = (0, child_process_1.execSync)(`curl -s "${config.url}/api/v3/secrets/raw?workspaceId=${config.projectId}&environment=${environment}&secretPath=${secretPath}" -H "Authorization: Bearer ${token}"`, { encoding: 'utf-8' });

package/dist/bin/helpers/entitlement/grant.js

@@ -4,6 +4,7 @@ exports.runGrant = runGrant;
 const billing_http_1 = require("../billing-http");
 const confirm_prompt_1 = require("../confirm-prompt");
 const grant_subscription_1 = require("../grant-subscription");
+const operator_1 = require("../operator");
 function parseArgs(argv) {
     if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
         console.log(`Usage: optima-entitlement grant <email|phone|userId> --product-key <slug> --justification "..." [options]
@@ -15,6 +16,7 @@ Required:
 
 Optional:
   --yes                            Skip prod/cn-prod confirmation prompt (no-op on stage / cn-stage)
+  --operator <name>       Operator self-report for billing audit (default: local username)
   --env stage|prod|cn-prod|cn-stage   (default: stage)
 
 Hardcoded server-side: source=ADMIN_GRANT, priceCents=0, currency=USD, grantedBy=<clientId>.`);
@@ -40,6 +42,10 @@ Hardcoded server-side: source=ADMIN_GRANT, priceCents=0, currency=USD, grantedBy
             case '--yes':
                 out.yes = true;
                 break;
+            case '--operator':
+                out.operator = next;
+                i++;
+                break;
             case '--env':
                 out.env = next;
                 i++;
@@ -72,6 +78,7 @@ async function runGrant(argv) {
         userId,
         productKey: args.productKey,
         justification: args.justification,
+        actorUserId: (0, operator_1.operatorActorId)(args.operator ?? null),
     });
     console.log(`✓ Granted entitlement (HTTP ${res.status}):`);
     console.log(JSON.stringify(res.body, null, 2));

package/dist/bin/helpers/entitlement/revoke.js

@@ -4,6 +4,7 @@ exports.runRevoke = runRevoke;
 const billing_http_1 = require("../billing-http");
 const confirm_prompt_1 = require("../confirm-prompt");
 const grant_subscription_1 = require("../grant-subscription");
+const operator_1 = require("../operator");
 function parseArgs(argv) {
     if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
         console.log(`Usage: optima-entitlement revoke <email|phone|userId> --product-key <slug> --reason "..." [options]
@@ -15,6 +16,7 @@ Required:
 
 Optional:
   --yes                            Skip prod/cn-prod confirmation prompt (no-op on stage / cn-stage)
+  --operator <name>       Operator self-report for billing audit (default: local username)
   --env stage|prod|cn-prod|cn-stage   (default: stage)
 
 Refuses non-ADMIN_GRANT sources (PAYMENT, PARTNER) with source-specific
@@ -41,6 +43,10 @@ error pointing to the right reversal flow.`);
             case '--yes':
                 out.yes = true;
                 break;
+            case '--operator':
+                out.operator = next;
+                i++;
+                break;
             case '--env':
                 out.env = next;
                 i++;
@@ -102,6 +108,7 @@ async function runRevoke(argv) {
         entitlementId: target.id,
         refundReason: args.reason,
         refundAmountCents: 0,
+        actorUserId: (0, operator_1.operatorActorId)(args.operator ?? null),
     });
     console.log(`✓ Revoked entitlement (HTTP ${res.status}):`);
     console.log(JSON.stringify(res.body, null, 2));

package/dist/bin/helpers/generate-test-token.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAlreadyExistsError = isAlreadyExistsError;
 const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
@@ -88,6 +89,40 @@ async function httpRequest(url, options = {}) {
     }
     return response.json();
 }
+/**
+ * 判定「账号/商户已存在」——吃 httpRequest 抛出的 `HTTP <status>: <body>` message。
+ *
+ * 两条腿各自对应一个真实来源（user-auth / commerce-backend 是同一套代码跑在 AWS 与
+ * cn 两侧，响应形态一致；下列均为 2026-08-13 直查 origin/main 坐实）：
+ *
+ * - **文案腿** `^HTTP 4xx` 且 `already (exists|registered)`
+ *   · user-auth 注册已注册邮箱 → 400 "Email already registered"
+ *     （user-auth `app/services/user.py`）。**这就是 #78 的病灶**：旧判定只认
+ *     "already exists"，措辞对不上 ⇒ cn 侧 `--email` 复用已有账号必挂。
+ *     实测 cn-prod 响应体：{"error":"Email already registered","status_code":400}
+ *   · commerce-backend 重复建 merchant profile → 400 "Merchant profile already
+ *     exists. Use PUT ..."（commerce-backend `src/api/merchants.py`）
+ *   · 🔴 必须同时是 4xx：5xx 是服务端故障，body 里恰好带着这些词也不能吞 —— 否则
+ *     `POST /api/merchants/me` 的 502/503 会被报成 ℹ already exists，一路打印到
+ *     「✅ Test token generated successfully!」+ Merchant ID: N/A、exit 0。
+ * - **状态码腿** `^HTTP 409`
+ *   · 本工具只调 `POST /api/v1/auth/register/merchant` 与 `POST /api/merchants/me`
+ *     两个端点。**register/merchant 这条路径上唯一的 409** 是企业席位：
+ *     account_type == ENTERPRISE_SEAT → 409 detail "email_bound_to_seat"。
+ *     🔴 **该文案既不含 exists 也不含 registered，所以这条腿不是历史遗留、
+ *     是席位场景的唯一命中路径，别删。**
+ *     ⚠️ 「这条路径上唯一」的限定不是废话：user-auth 全仓有 20+ 处 409
+ *     （referral / internal-sms / teams / admin），措辞各异且语义完全不同
+ *     （如 `claim_in_progress` 是并发冲突）。给本工具接新端点时别想当然沿用本判定，
+ *     否则会把并发冲突静默吞成「已存在」。
+ *
+ * 锚 `^HTTP 409` 而不是 issue 建议的 `\b(409|400)\b`：后者会把 body 里夹带的数字当
+ * 状态码，把真故障（500 而 body 里提到 409）静默吞成「已存在」；而 400 本身太泛
+ * （参数校验失败也是 400），单凭它放行等于吞掉一切请求错误 —— 400 一律交给文案腿判。
+ */
+function isAlreadyExistsError(message) {
+    return /^HTTP 409\b/.test(message) || (/^HTTP 4\d\d\b/.test(message) && /already (exists|registered)/i.test(message));
+}
 async function registerMerchant(email, password, businessName, config, phone, address) {
     console.log(`\n📝 Registering merchant: ${email}...`);
     const payload = { email, password, business_name: businessName };
@@ -105,7 +140,7 @@ async function registerMerchant(email, password, businessName, config, phone, ad
         return result;
     }
     catch (error) {
-        if (error.message.includes('409') || error.message.includes('already exists')) {
+        if (isAlreadyExistsError(error.message)) {
             console.log(`ℹ Merchant already exists, proceeding to login...`);
             return { email, user_id: '', role: 'merchant', is_active: true, created_at: '', updated_at: '' };
         }
@@ -153,7 +188,7 @@ async function setupMerchantProfile(token, businessName, config) {
         return result;
     }
     catch (error) {
-        if (error.message.includes('409') || error.message.includes('already exists')) {
+        if (isAlreadyExistsError(error.message)) {
             console.log(`ℹ Merchant profile already exists`);
             return { merchant_id: '', business_name: businessName, user_id: '' };
         }
@@ -292,4 +327,6 @@ Example:
         process.exit(1);
     }
 }
-main();
+if (require.main === module) {
+    main();
+}

package/dist/bin/helpers/grant-credits.js

@@ -11,6 +11,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const path_1 = require("path");
 const crypto_1 = require("crypto");
 const billing_http_1 = require("./billing-http");
+const operator_1 = require("./operator");
 const grant_subscription_1 = require("./grant-subscription");
 const CREDITS_PER_USD = 700;
 function parseArgs(args) {
@@ -27,6 +28,7 @@ Options:
   --credits <n>         Credits to grant (integer >= 1). Primary unit.
   --amount <usd>        Alt: grant by USD ($1 = ${CREDITS_PER_USD} credits). Provide exactly one of --credits / --amount.
   --description <text>  Description for audit trail (optional)
+  --operator <name>       Operator self-report for billing audit (default: local username)
   --env <env>           Environment: stage, prod, cn-prod, cn-stage (default: stage)
   -h, --help            Show this help
 
@@ -40,6 +42,7 @@ Examples:
     let credits = null;
     let amountUsd = null;
     let description = null;
+    let operator = null;
     let env = 'stage';
     for (let i = 1; i < args.length; i++) {
         if (args[i] === '--credits' && args[i + 1]) {
@@ -51,6 +54,9 @@ Examples:
         else if (args[i] === '--description' && args[i + 1]) {
             description = args[++i];
         }
+        else if (args[i] === '--operator' && args[i + 1]) {
+            operator = args[++i];
+        }
         else if (args[i] === '--env' && args[i + 1]) {
             env = args[++i];
         }
@@ -69,14 +75,14 @@ Examples:
         process.exit(1);
     }
     (0, billing_http_1.validateEnvCnProd)(env);
-    return { identifier, credits, amountUsd, description, env };
+    return { identifier, credits, amountUsd, description, operator, env };
 }
 async function main() {
     // Deprecation notice when invoked via the legacy alias `optima-grant-balance`.
     if ((0, path_1.basename)(process.argv[1] || '').includes('grant-balance')) {
         console.warn('⚠️  optima-grant-balance 已更名为 optima-grant-credits（P15 钱包退役后回归积分）。请改用 `optima-grant-credits --credits <n>`；本别名仍可用，后续弃用。\n');
     }
-    const { identifier, credits, amountUsd, description, env } = parseArgs(process.argv.slice(2));
+    const { identifier, credits, amountUsd, description, operator, env } = parseArgs(process.argv.slice(2));
     const creditsDisplay = credits ?? Math.round(amountUsd * CREDITS_PER_USD);
     console.log(`\n🎁 Granting ${creditsDisplay} credits${amountUsd !== null ? ` ($${amountUsd.toFixed(2)})` : ''} to ${identifier} [${env.toUpperCase()}]\n`);
     if (description)
@@ -93,6 +99,7 @@ async function main() {
         userId,
         ...amountField,
         description: description ?? undefined,
+        actorUserId: (0, operator_1.operatorActorId)(operator),
         idempotencyKey: `dev-skills-grant:${(0, crypto_1.randomUUID)()}`,
     });
     console.log(`✓ Granted ${body.credits} credits (lot ${body.lotId})`);

package/dist/bin/helpers/grant-subscription.js

@@ -10,6 +10,7 @@ exports.resolveTargetUser = resolveTargetUser;
 // 业务体：supersede 旧授予 + 实得 credits + token quota，重试双发不双倍）。
 const db_utils_1 = require("./db-utils");
 const billing_http_1 = require("./billing-http");
+const operator_1 = require("./operator");
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 /**
  * Auto-detect what kind of identifier the operator passed. gateway#923: a
@@ -79,6 +80,7 @@ Options:
                     cn-prod/cn-stage additionally allow: free
                     (legacy *-cn ids are accepted and normalized to canonical)
   --months <n>      Duration in months (default: 1)
+  --operator <name>       Operator self-report for billing audit (default: local username)
   --env <env>       Environment: stage, prod, cn-prod, cn-stage (default: stage)
   -h, --help        Show this help`);
         process.exit(0);
@@ -86,6 +88,7 @@ Options:
     const identifier = args[0];
     let plan = null;
     let months = 1;
+    let operator = null;
     let env = 'stage';
     for (let i = 1; i < args.length; i++) {
         if (args[i] === '--plan' && args[i + 1]) {
@@ -94,6 +97,9 @@ Options:
         else if (args[i] === '--months' && args[i + 1]) {
             months = parseInt(args[++i], 10);
         }
+        else if (args[i] === '--operator' && args[i + 1]) {
+            operator = args[++i];
+        }
         else if (args[i] === '--env' && args[i + 1]) {
             env = args[++i];
         }
@@ -112,7 +118,7 @@ Options:
         console.error('Months must be >= 1');
         process.exit(1);
     }
-    return { identifier, plan, months, env };
+    return { identifier, plan, months, operator, env };
 }
 /**
  * Resolve a CLI identifier (`<email|phone|userId>`) to a userId + verified
@@ -167,12 +173,12 @@ async function resolveTargetUser(env, identifier) {
     return { userId, kind, identity: { phone: null, email: identifier } };
 }
 async function main() {
-    const { identifier, plan, months, env } = parseArgs(process.argv.slice(2));
+    const { identifier, plan, months, operator, env } = parseArgs(process.argv.slice(2));
     console.log(`\n🎁 Granting ${plan} subscription to ${identifier} (${classifyIdentifier(identifier)}) for ${months} month(s) [${env.toUpperCase()}]\n`);
     // Shared resolver: classify → resolve → reverse-verify echo → phone-assert
     // (cn-prod/cn-stage), or email-only via SSH tunnel (AWS). See resolveTargetUser.
     const { userId, identity } = await resolveTargetUser(env, identifier);
-    const { body } = await (0, billing_http_1.callBilling)(env, 'POST', '/api/billing/admin/grant-subscription', { userId, planId: plan, months });
+    const { body } = await (0, billing_http_1.callBilling)(env, 'POST', '/api/billing/admin/grant-subscription', { userId, planId: plan, months, actorUserId: (0, operator_1.operatorActorId)(operator) });
     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()}`);

package/dist/bin/helpers/operator.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.operatorActorId = operatorActorId;
+const os_1 = require("os");
+// #429（Owner 拍板 3）：CLI 发放族自报操作者——informational，billing 信任 allowlist client
+// 自述（actor 不参与授权）；不带 --operator 时回退本机用户名。缺省链最终兜底在 billing
+// 侧（channel=client_id）。格式：dev-skills:<name>。
+function operatorActorId(operatorFlag) {
+    const name = (operatorFlag ?? '').trim() || (0, os_1.userInfo)().username;
+    return `dev-skills:${name}`;
+}

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

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseArgs = parseArgs;
 /**
  * optima-verify-health —— 服务上线健康探针(L1 DNS / L2 TLS / L3-L5 /health)。
  *
@@ -52,8 +53,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
  *
  * 用法:
  *   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 user-auth --env prod        # 环境 stage|prod|cn-prod|cn-stage|all
+ *   optima-verify-health --all --env all             # stage/prod/cn-prod/cn-stage 四环境矩阵
  *   optima-verify-health gateway-core --expect-commit a1b2c3d
  *   optima-verify-health --url https://auth.yzsgo.com/health
  *   optima-verify-health --all --json                # 机器可读,接 CI
@@ -67,16 +68,28 @@ const https = __importStar(require("node:https"));
 // cn-prod 真实 subdomain 抄自 optima-terraform alicloud/stacks/cn-prod-ingress-sae/main.tf。
 // #201 (2026-06-12): yzsgo.com 全量迁移完成,旧 *-cn.optima.chat 路由已下线。
 // cn-stage（阿里云预发）域名 *.stage.optima.chat，抄自 cn-stage-ingress-sae services map。
+// #83 (2026-08-13): AWS stage 是 *.stage.optima.onl（点号），旧的连字符形式 *-stage.optima.onl
+// 已不再路由到服务——三项实测 301 → www.optima.onl，探测恒红并误报成「疑似未部署」。
+// 🔴 别只看 stage 列：agentic-chat 的 prod 也踩同一个坑（见下面那行的注释）。
 const SERVICES = {
-    'user-auth': { path: '/health', stage: 'auth-stage.optima.onl', prod: 'auth.optima.onl', cn: 'auth.yzsgo.com', 'cn-stage': 'auth.stage.optima.chat' },
-    'agentic-chat': { path: '/api/health', stage: 'ai-stage.optima.onl', prod: 'ai.optima.onl', cn: 'app.yzsgo.com', 'cn-stage': 'app.stage.optima.chat' },
-    'commerce-backend': { path: '/health', stage: 'api-stage.optima.onl', prod: 'api.optima.onl', cn: 'commerce.yzsgo.com', cn_path: '/health/live', 'cn-stage': 'commerce.stage.optima.chat', 'cn-stage_path': '/health/live' },
-    'mcp-host': { path: '/health', stage: 'mcp-stage.optima.onl', prod: 'mcp.optima.onl' },
-    'gateway-core': { path: '/health', cn: 'gw.yzsgo.com', 'cn-stage': 'gw.stage.optima.chat' },
-    'optima-scout': { path: '/health', cn: 'scout.yzsgo.com', 'cn-stage': 'scout.stage.optima.chat' },
-    'optima-skills': { path: '/health', cn: 'skills.yzsgo.com', 'cn-stage': 'skills.stage.optima.chat' },
+    'user-auth': { path: '/health', stage: 'auth.stage.optima.onl', prod: 'auth.optima.onl', 'cn-prod': 'auth.yzsgo.com', 'cn-stage': 'auth.stage.optima.chat' },
+    // agentic-chat 的 prod 入口是 www 不是 ai：prod-ecs/variables.tf 里它的 subdomain = "www"，
+    // 且 main.tf 有一条 ai_to_www_redirect(priority 309) 专门把 ai.optima.onl 301 到 www。
+    // 实测 ai.optima.onl/api/health → 301；www.optima.onl/api/health → 200 service=agentic-chat。
+    'agentic-chat': { path: '/api/health', stage: 'ai.stage.optima.onl', prod: 'www.optima.onl', 'cn-prod': 'app.yzsgo.com', 'cn-stage': 'app.stage.optima.chat' },
+    'commerce-backend': { path: '/health', stage: 'api.stage.optima.onl', prod: 'api.optima.onl', 'cn-prod': 'commerce.yzsgo.com', 'cn-prod_path': '/health/live', 'cn-stage': 'commerce.stage.optima.chat', 'cn-stage_path': '/health/live' },
+    // #83: mcp-host 已于 2025-12-18 下线,故不在表内 —— optima-terraform origin/main(f97adbb) 的
+    // stage-ecs/variables.tf:146 与 prod-ecs/variables.tf:508 都写着「MCP 工具服务已移除」,
+    // 两个 ecs stack 的 services map 里均无该条目;实测四个候选主机名全是壳(mcp.stage.optima.onl
+    // 307 → /en-US/health 前端 locale 路由,mcp-stage.optima.onl 与 prod 的 mcp.optima.onl 均
+    // 301 → www)。🔴 别再把它加回来:worstOk 是全局单标志(见 main()),留着它会让 `--all --env stage`
+    // 与 `--all --env prod` 恒 exit 1,而那个退出码正是接 CI 卡口时唯一被读的东西。
+    // 同一约束在 tests/service-matrix-alignment.test.js 里对 show-env 的清单也钉着。
+    'gateway-core': { path: '/health', 'cn-prod': 'gw.yzsgo.com', 'cn-stage': 'gw.stage.optima.chat' },
+    'optima-scout': { path: '/health', 'cn-prod': 'scout.yzsgo.com', 'cn-stage': 'scout.stage.optima.chat' },
+    'optima-skills': { path: '/health', 'cn-prod': 'skills.yzsgo.com', 'cn-stage': 'skills.stage.optima.chat' },
 };
-const ENVS = ['stage', 'prod', 'cn', 'cn-stage'];
+const ENVS = ['stage', 'prod', 'cn-prod', 'cn-stage'];
 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';
@@ -194,21 +207,66 @@ function resolve(svc, e) {
     const path = cfg[`${e}_path`] || cfg.path;
     return [`${svc} [${e}]`, host, path];
 }
+// 🔴 不认识的输入一律报错、绝不静默丢弃（同 query-db.ts 的 parseQueryDbArgs、logs.ts 的 parseArgs）：
+// 此前 `--env=stage` 不认、`--env` 漏写取值、多敲一个位置参数都会被静默无视而回落默认 cn-prod ——
+// 想探 stage，实际探的是阿里云生产，还 exit 0。
+function parseArgs(argv) {
+    const flags = new Set(), vals = {}, positional = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        const eq = arg.startsWith('--') ? arg.indexOf('=') : -1;
+        const name = eq > 0 ? arg.slice(0, eq) : arg;
+        if (['--env', '--expect-commit', '--url'].includes(name)) {
+            const v = eq > 0 ? arg.slice(eq + 1) : argv[++i];
+            if (!v || v.startsWith('-'))
+                throw new Error(`${name} 缺少取值`);
+            vals[name] = v;
+        }
+        else if (['--json', '--strict', '--all', '--help', '-h'].includes(arg))
+            flags.add(arg);
+        else if (arg.startsWith('-'))
+            throw new Error(`未知参数:${arg}`);
+        else
+            positional.push(arg);
+    }
+    // 🔴 必须先校验再转型：不校验的话任何不认识的 env 都会让 resolve() 把每个 SvcCfg 键查成
+    // undefined，于是落到下面的「无目标」分支，把「环境名打错」报成「该服务无部署」——
+    // 一个活着的服务被说成没上线，正是 #83 要根治的那类静默误报。
+    let envArg = vals['--env'] || 'cn-prod';
+    // 'cn' 是本文件的历史叫法，继续放行但不在 usage 里宣传（同 query-db.ts 的 ENV_ALIASES）。
+    if (envArg === 'cn')
+        envArg = 'cn-prod';
+    if (envArg !== 'all' && !ENVS.includes(envArg))
+        throw new Error(`未知环境:${envArg}(可选:${ENVS.join(' | ')} | all)`);
+    if (positional.length > 1)
+        throw new Error(`多余参数:${positional.slice(1).join(' ')}(一次探一个服务;环境用 --env 指定)`);
+    const service = positional[0];
+    if (service && !Object.keys(SERVICES).includes(service))
+        throw new Error(`未知服务:${service}(可选:${Object.keys(SERVICES).join(' | ')})`);
+    const url = vals['--url'], all = flags.has('--all');
+    return { help: flags.has('--help') || flags.has('-h') || !(url || all || service), json: flags.has('--json'), strict: flags.has('--strict'), all, env: envArg, expect: vals['--expect-commit'], url, service };
+}
 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');
+    let args;
+    try {
+        args = parseArgs(process.argv.slice(2));
+    }
+    catch (e) {
+        console.error(`❌ ${e.message}`);
+        process.exit(2);
+    }
+    const { json: asJson, strict, expect, env } = args;
     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'));
+    if (args.help) {
+        console.log((require('fs').readFileSync(__filename, 'utf-8').match(/\/\*\*[\s\S]*?\*\//)?.[0] || '').replace(/^\s*\*?/gm, ''));
+        process.exit(2);
+    }
+    else if (args.url) {
+        const u = new URL(args.url);
         targets = [[u.hostname, u.hostname, u.pathname || '/health']];
     }
-    else if (has('--all')) {
+    else if (args.all) {
         for (const e of envs)
             for (const s of Object.keys(SERVICES)) {
                 const t = resolve(s, e);
@@ -216,17 +274,13 @@ async function main() {
                     targets.push(t);
             }
     }
-    else if (positional[0] && SERVICES[positional[0]]) {
+    else if (args.service) {
         for (const e of envs) {
-            const t = resolve(positional[0], e);
+            const t = resolve(args.service, 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);
@@ -252,4 +306,6 @@ async function main() {
     // 用 exitCode 而非 process.exit():后者会在管道(--json | jq)未 flush 完就退出而截断输出
     process.exitCode = worstOk ? 0 : 1;
 }
-main();
+if (require.main === module) {
+    main();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optima-chat/dev-skills",
-  "version": "0.16.6",
+  "version": "0.16.8",
   "description": "Claude Code Skills for Optima development team - cross-environment collaboration tools",
   "main": "index.js",
   "bin": {