@optima-chat/dev-skills 0.7.43 → 0.8.1

package/.claude/skills/grant-balance/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "grant-balance"
-description: "当用户请求赠送余额、充值 USD 余额、grant balance、加余额、奖励、补偿、推荐奖励、运营发放时，使用此技能。支持 Stage、Prod、cn-prod 三个环境。"
+description: "当用户请求赠送余额、充值 USD 余额、grant balance、加余额、奖励、补偿、推荐奖励、运营发放时，使用此技能。支持 Stage、Prod、cn-prod、cn-stage 四个环境。"
 allowed-tools: ["Bash"]
 ---
 
@@ -50,9 +50,11 @@ optima-grant-balance user@example.com --amount 20 --description "服务中断补
 | `<email>` | 用户邮箱（必填） | - |
 | `--amount <usd>` | USD 金额（必填，> 0） | - |
 | `--description <text>` | 描述/原因（仅 console 输出） | - |
-| `--env <env>` | 环境：stage, prod, cn-prod | stage |
+| `--env <env>` | 环境：stage, prod, cn-prod, cn-stage | stage |
 
 > **cn-prod（国内环境）**：全程 HTTPS（auth.yzsgo.com / billing-api.yzsgo.com），email 查找走 user-auth internal lookup API（无 SSH 隧道）。金额输入仍是 USD（$1 = 700 积分，与 CN ¥1 = 100 积分同一账本单位）。例：`optima-grant-balance user@example.com --amount 1 --env cn-prod`
+>
+> **cn-stage（阿里云预发）**：同 cn-prod 走 HTTPS（auth.stage.optima.chat / billing-api.stage.optima.chat）。M2M 凭证读 cn Infisical **staging** /shared-secrets/oauth-clients，运行时需 `INFISICAL_CN_EMAIL`/`INFISICAL_CN_PASSWORD`（admin user）。例：`optima-grant-balance user@example.com --amount 1 --env cn-stage`
 
 ## 与 grant-subscription 的区别
 

package/.claude/skills/grant-subscription/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "grant-subscription"
-description: "当用户请求开通会员、赠送订阅、grant subscription、开通 Pro/Starter/Enterprise、升级计划、给用户开会员时，使用此技能。支持 Stage、Prod、cn-prod 三个环境。"
+description: "当用户请求开通会员、赠送订阅、grant subscription、开通 Pro/Starter/Enterprise、升级计划、给用户开会员时，使用此技能。支持 Stage、Prod、cn-prod、cn-stage 四个环境。"
 allowed-tools: ["Bash"]
 ---
 
@@ -50,6 +50,10 @@ optima-grant-subscription user@example.com --plan enterprise --env prod
 # cn-prod（国内环境）：plan 用 -cn 档，默认 pro-cn
 optima-grant-subscription user@example.com --env cn-prod
 optima-grant-subscription user@example.com --plan starter-cn --env cn-prod
+
+# cn-stage（阿里云预发）：同 cn-prod 用 -cn 档；需 INFISICAL_CN_EMAIL/PASSWORD。
+# ⚠️ cn-stage billing 的 plan 目录可能未 seed（报 403 Plan not found）——属 cn-stage 基建缺口，非本工具问题。
+optima-grant-subscription user@example.com --plan pro-cn --env cn-stage
 ```
 
 ### 参数说明

package/.codex/skills/grant-balance/SKILL.md

@@ -49,9 +49,10 @@ optima-grant-balance user@example.com --amount 20 --description "服务中断补
 | `<email>` | 用户邮箱（必填） | - |
 | `--amount <usd>` | USD 金额（必填，> 0） | - |
 | `--description <text>` | 描述/原因（仅 console 输出） | - |
-| `--env <env>` | 环境：stage, prod, cn-prod | stage |
+| `--env <env>` | 环境：stage, prod, cn-prod, cn-stage | stage |
 
 > **cn-prod**：走 HTTPS（auth.yzsgo.com / billing-api.yzsgo.com），email 查找经 user-auth internal lookup API（无 SSH 隧道）。金额输入仍是 USD（$1 = 700 积分 = ¥7 档积分口径一致）。
+> **cn-stage（阿里云预发）**：同 cn-prod 走 HTTPS（auth.stage.optima.chat / billing-api.stage.optima.chat）；M2M 凭证读 cn Infisical staging，需 `INFISICAL_CN_EMAIL`/`INFISICAL_CN_PASSWORD`。
 
 ## 与 grant-subscription 的区别
 

package/.codex/skills/grant-subscription/SKILL.md

@@ -25,12 +25,16 @@ optima-grant-subscription user@example.com --plan enterprise --env prod
 # cn-prod（国内环境）：plan 用 -cn 档，默认 pro-cn
 optima-grant-subscription user@example.com --env cn-prod
 optima-grant-subscription user@example.com --plan starter-cn --env cn-prod
+
+# cn-stage（阿里云预发）：同 cn-prod 用 -cn 档；需 INFISICAL_CN_EMAIL/PASSWORD。
+# ⚠️ cn-stage billing plan 目录可能未 seed（403 Plan not found）——cn-stage 基建缺口，非本工具问题。
+optima-grant-subscription user@example.com --plan pro-cn --env cn-stage
 ```
 
 ## Guidance
 
 - Default to `stage`.
-- Confirm the user email before running on `prod` / `cn-prod`.
-- `cn-prod` plans are the CNY-priced `-cn` ids (`starter-cn`, `pro-cn`, `enterprise-cn`, plus `trial`); bare USD ids are rejected client-side to avoid granting a USD-priced plan to a CN user.
+- Confirm the user email before running on `prod` / `cn-prod` / `cn-stage`.
+- `cn-prod` / `cn-stage` plans are the CNY-priced `-cn` ids (`starter-cn`, `pro-cn`, `enterprise-cn`, plus `trial`); bare USD ids are rejected client-side to avoid granting a USD-priced plan to a CN user.
 - This operation replaces existing subscription state and resets the wallet granted balance according to the selected plan.
 - Use `optima-query-db` afterward if the user asks for verification.

package/bin/cli.js

@@ -44,7 +44,7 @@ switch (command) {
     log('  session-gateway  optima-scout  billing  browser-backend  optima-generation', 'cyan');
 
     log('\nEnvironments:', 'yellow');
-    log('  stage (default)   prod', 'cyan');
+    log('  stage (default)   prod   cn-prod (阿里云生产)   cn-stage (阿里云预发)', 'cyan');
 
     log('\nExamples:', 'yellow');
     log('  /logs commerce-backend 100 prod', 'cyan');

package/bin/helpers/billing-http.ts

@@ -1,19 +1,22 @@
 import { execSync } from 'child_process';
 import { fetchInfisicalSecret } from './infisical-secrets';
-import { getInfisicalConfig, getInfisicalToken } from './db-utils';
+import { getInfisicalConfig, getInfisicalToken, getCnInfisicalToken, getCnSecrets, resolveUserId } from './db-utils';
 
 const USER_AUTH_URLS: Record<string, string> = {
   stage: 'https://auth.stage.optima.onl',
   prod: 'https://auth.optima.onl',
   // #201: yzsgo.com 全量迁移 (2026-06-12), 旧 auth-cn.optima.chat 路由已下线
   'cn-prod': 'https://auth.yzsgo.com',
+  // cn-stage（阿里云预发，独立于 AWS stage `.optima.onl`）
+  'cn-stage': 'https://auth.stage.optima.chat',
 };
 
-// cn-prod URLs are hardcoded: cn Infisical (secrets-cn.optima.chat) is a
+// cn URLs are hardcoded: cn Infisical (secrets-cn.optima.chat) is a
 // separate instance dev-skills has no machine identity for, and these domains
 // are stable. AWS envs keep reading /shared-secrets/domain-urls.
 // #201: yzsgo.com 全量迁移 (2026-06-12), 旧 billing-cn.optima.chat 路由已下线
 const CN_PROD_BILLING_URL = 'https://billing-api.yzsgo.com';
+const CN_STAGE_BILLING_URL = 'https://billing-api.stage.optima.chat';
 
 /**
  * Validate the --env flag value at command entry, before any I/O.
@@ -39,9 +42,9 @@ export function validateEnv(env: string): 'stage' | 'prod' {
  * exist for cn-prod (Aliyun VPC-internal RDS) — keep them on validateEnv so a
  * cn-prod typo fails fast instead of dying inside the tunnel setup.
  */
-export function validateEnvCnProd(env: string): 'stage' | 'prod' | 'cn-prod' {
-  if (env !== 'stage' && env !== 'prod' && env !== 'cn-prod') {
-    throw new Error(`--env must be "stage", "prod" or "cn-prod" (got: ${env})`);
+export function validateEnvCnProd(env: string): 'stage' | 'prod' | 'cn-prod' | 'cn-stage' {
+  if (env !== 'stage' && env !== 'prod' && env !== 'cn-prod' && env !== 'cn-stage') {
+    throw new Error(`--env must be "stage", "prod", "cn-prod" or "cn-stage" (got: ${env})`);
   }
   return env;
 }
@@ -84,6 +87,7 @@ const skillsUrlCache: Record<string, string> = {};
 
 function getBillingUrl(env: string): string {
   if (env === 'cn-prod') return CN_PROD_BILLING_URL;
+  if (env === 'cn-stage') return CN_STAGE_BILLING_URL;
   if (billingUrlCache[env]) return billingUrlCache[env];
   const url = fetchInfisicalSecret(env, '/shared-secrets/domain-urls', 'BILLING_URL');
   billingUrlCache[env] = url;
@@ -100,17 +104,33 @@ function getSkillsUrl(env: string): string {
 export function getServiceToken(env: string): string {
   if (tokenCache[env]) return tokenCache[env];
 
-  const cfg = getInfisicalConfig();
-  const tok = getInfisicalToken(cfg);
-  // Fetch BOTH client_id and client_secret from Infisical — they differ per env.
-  // cn-prod credentials are mirrored in the AWS Infisical *prod* environment
-  // (fetchInfisicalSecret has no cn-prod env slug), under CN-specific keys.
-  const isCn = env === 'cn-prod';
-  const infisicalEnv = isCn ? 'prod' : env;
-  const idKey = isCn ? DEV_SKILLS_CN_CLIENT_ID_KEY : DEV_SKILLS_CLIENT_ID_KEY;
-  const secretKey = isCn ? DEV_SKILLS_CN_CLIENT_SECRET_KEY : DEV_SKILLS_CLIENT_SECRET_KEY;
-  const clientId = fetchInfisicalSecret(infisicalEnv, DEV_SKILLS_OAUTH_PATH, idKey, cfg, tok);
-  const clientSecret = fetchInfisicalSecret(infisicalEnv, DEV_SKILLS_OAUTH_PATH, secretKey, cfg, tok);
+  // cn-prod 与 cn-stage 都用 client_credentials M2M token，scope=internal:users:write。
+  // 凭证来源不同：
+  //  · cn-prod —— 镜像在 AWS Infisical prod 环境（CN_PROD_ 前缀键），复用既有 AWS 访问。
+  //  · cn-stage —— canonical 在 cn Infisical staging /shared-secrets/oauth-clients
+  //    （dev-skills 无该 client 的 AWS 镜像；用 admin email/password 直读，
+  //     运行时需 INFISICAL_CN_EMAIL/PASSWORD，与 query-db cn 同一前提）。
+  const isCn = env === 'cn-prod' || env === 'cn-stage';
+  let clientId: string;
+  let clientSecret: string;
+  if (env === 'cn-stage') {
+    const cnTok = getCnInfisicalToken();
+    const oc = getCnSecrets(cnTok, '/shared-secrets/oauth-clients', false, 'staging');
+    clientId = oc['DEV_SKILLS_OAUTH_CLIENT_ID'];
+    clientSecret = oc['DEV_SKILLS_OAUTH_CLIENT_SECRET'];
+    if (!clientId || !clientSecret) {
+      throw new Error('cn-stage dev-skills OAuth client 凭证缺失（cn Infisical staging /shared-secrets/oauth-clients 的 DEV_SKILLS_OAUTH_CLIENT_ID/SECRET）。');
+    }
+  } else {
+    const cfg = getInfisicalConfig();
+    const tok = getInfisicalToken(cfg);
+    // Fetch BOTH client_id and client_secret from Infisical — they differ per env.
+    const infisicalEnv = env === 'cn-prod' ? 'prod' : env;
+    const idKey = env === 'cn-prod' ? DEV_SKILLS_CN_CLIENT_ID_KEY : DEV_SKILLS_CLIENT_ID_KEY;
+    const secretKey = env === 'cn-prod' ? DEV_SKILLS_CN_CLIENT_SECRET_KEY : DEV_SKILLS_CLIENT_SECRET_KEY;
+    clientId = fetchInfisicalSecret(infisicalEnv, DEV_SKILLS_OAUTH_PATH, idKey, cfg, tok);
+    clientSecret = fetchInfisicalSecret(infisicalEnv, DEV_SKILLS_OAUTH_PATH, secretKey, cfg, tok);
+  }
 
   const authUrl = USER_AUTH_URLS[env];
   if (!authUrl) throw new Error(`Unknown env: ${env}`);
@@ -272,6 +292,25 @@ export async function resolveUserIdByEmail(env: string, email: string): Promise<
   return parsed.user_id;
 }
 
+/**
+ * Resolve email → userId across all envs, picking the path that exists for
+ * each cloud. AWS (stage/prod) reaches the database over the RDS SSH tunnel
+ * (db-utils.resolveUserId). cn-prod / cn-stage have no tunnel into the Aliyun
+ * VPC-internal RDS, so they resolve via user-auth's internal HTTP lookup
+ * (resolveUserIdByEmail) — the cn dev-skills token carries the
+ * internal:users:write scope that endpoint requires. Lets the entitlement
+ * subcommands support cn the same way grant-subscription already does, without
+ * each call site re-implementing the branch.
+ */
+export async function resolveUserIdByEmailAnyEnv(env: string, email: string): Promise<string> {
+  if (env === 'cn-prod' || env === 'cn-stage') {
+    return resolveUserIdByEmail(env, email);
+  }
+  const cfg = getInfisicalConfig();
+  const token = getInfisicalToken(cfg);
+  return resolveUserId(email, env, cfg, token);
+}
+
 /**
  * Resolve a user's id by phone via user-auth's internal lookup endpoint
  * (POST /api/v1/internal/users/lookup with {phone}). Mirrors

package/bin/helpers/confirm-prompt.ts

@@ -1,17 +1,21 @@
 import * as readline from 'readline';
 
 /**
- * On prod, print the resolved action and require typing "yes" to proceed.
- * No-op on stage or when --yes was passed. Exits 1 if user declines.
+ * On a production env, print the resolved action and require typing "yes" to
+ * proceed. Both AWS `prod` and Aliyun `cn-prod` are production — cn-prod must
+ * gate identically or the cn rollout silently loses the prod safety prompt.
+ * No-op on stage / cn-stage or when --yes was passed. Exits 1 if user declines.
  */
+const PROD_ENVS = new Set(['prod', 'cn-prod']);
+
 export async function confirmIfProd(
   env: string,
   actionDescription: string,
   skipFlag: boolean,
 ): Promise<void> {
-  if (env !== 'prod' || skipFlag) return;
+  if (!PROD_ENVS.has(env) || skipFlag) return;
 
-  console.log(`\n⚠️  About to perform on PROD:\n${actionDescription}\n`);
+  console.log(`\n⚠️  About to perform on ${env.toUpperCase()}:\n${actionDescription}\n`);
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   const answer = await new Promise<string>((resolve) => {
     rl.question('Type "yes" to confirm: ', (a) => { rl.close(); resolve(a.trim()); });

package/bin/helpers/db-utils.ts

@@ -29,15 +29,33 @@ const EC2_HOST = '3.0.210.113';
 // ─── cn-prod (阿里云) 常量 ────────────────────────────────────────────────────
 // cn-prod 跑在阿里云 SAE，与海外 AWS 完全独立：独立 Infisical (secrets-cn.optima.chat)
 // + 内网 RDS（无公网端点）经 buildbox ECS 跳板 SSH 隧道访问。设计见 optima-dev-skills#21。
+// cn Infisical 是【单实例双环境】：prod=cn-prod、staging=cn-stage（URL/org/project 共享，
+// 只切 environment 参数）。cn-stage 数据面共用 prod VPC，故走【同一 buildbox】跳板。
 const CN_INFISICAL_URL     = process.env.INFISICAL_CN_URL     || 'https://secrets-cn.optima.chat';
 const CN_INFISICAL_ORG     = process.env.INFISICAL_CN_ORG     || 'f44012fa-0659-4f7e-b0ac-ed01244efc8a';
 const CN_INFISICAL_PROJECT = process.env.INFISICAL_CN_PROJECT || '4deef229-11be-40a5-8f56-b61f0bce7240';
-const CN_RDS_HOST          = 'pgm-2zexwx9eso9e4yla.pg.rds.aliyuncs.com';
+const CN_RDS_HOST          = 'pgm-2zexwx9eso9e4yla.pg.rds.aliyuncs.com'; // cn-prod RDS
+const CN_STAGE_RDS_HOST    = 'pgm-2zem1u9zdh06boim.pg.rds.aliyuncs.com'; // cn-stage RDS（独立实例，共用 prod VPC）
 const CN_BUILDBOX_HOST     = process.env.OPTIMA_CN_BUILDBOX_HOST || '47.94.105.163';
 
-/** env 是否指向 cn-prod（阿里云）。接受 `cn` / `cn-prod`。 */
+/** env 是否指向阿里云（cn-prod 或 cn-stage）。接受 `cn` / `cn-prod` / `cn-stage`。 */
 export function isCnEnv(env: string): boolean {
-  return env === 'cn' || env === 'cn-prod';
+  return env === 'cn' || env === 'cn-prod' || env === 'cn-stage';
+}
+
+/** env 是否指向 cn-stage（阿里云预发）。 */
+export function isCnStageEnv(env: string): boolean {
+  return env === 'cn-stage';
+}
+
+/** cn env → cn Infisical environment slug。cn-stage→staging，其余 cn→prod。 */
+export function cnInfisicalEnv(env: string): 'prod' | 'staging' {
+  return env === 'cn-stage' ? 'staging' : 'prod';
+}
+
+/** cn env → 内网 RDS host。cn-stage→stage 实例，其余 cn→prod 实例。 */
+export function cnRdsHost(env: string): string {
+  return env === 'cn-stage' ? CN_STAGE_RDS_HOST : CN_RDS_HOST;
 }
 
 // ─── SQL escaping ───────────────────────────────────────────────────────────
@@ -117,10 +135,13 @@ export function getCnInfisicalToken(): string {
   return org.token;
 }
 
-/** 读 cn Infisical 某 folder（prod env）→ key→value map。expand=true 让服务端解析 `${...}` 引用。 */
-export function getCnSecrets(token: string, secretPath: string, expand = false): Record<string, string> {
+/**
+ * 读 cn Infisical 某 folder → key→value map。expand=true 让服务端解析 `${...}` 引用。
+ * environment：cn-prod 用 `prod`、cn-stage 用 `staging`（同一实例双环境）。
+ */
+export function getCnSecrets(token: string, secretPath: string, expand = false, environment: 'prod' | 'staging' = 'prod'): Record<string, string> {
   const data = curlJson([
-    `${CN_INFISICAL_URL}/api/v3/secrets/raw?workspaceId=${CN_INFISICAL_PROJECT}&environment=prod&secretPath=${encodeURIComponent(secretPath)}&expandSecretReferences=${expand}`,
+    `${CN_INFISICAL_URL}/api/v3/secrets/raw?workspaceId=${CN_INFISICAL_PROJECT}&environment=${environment}&secretPath=${encodeURIComponent(secretPath)}&expandSecretReferences=${expand}`,
     '-H', `Authorization: Bearer ${token}`,
   ]);
   const secrets: Record<string, string> = {};
@@ -417,17 +438,18 @@ export function queryDB(conn: DBConnection, sql: string): string {
  * 连 cn-prod 某服务库：creds 取自 cn Infisical 的 /shared-secrets/database-users +
  * /database-names（按 prefix，如 AUTH/BILLING），经 buildbox 跳板隧道（动态端口）。
  */
-export function connectCnDB(prefix: string): { query: (sql: string) => string } {
+export function connectCnDB(prefix: string, cnEnv: string = 'cn-prod'): { query: (sql: string) => string } {
+  const infEnv = cnInfisicalEnv(cnEnv);
   const token = getCnInfisicalToken();
-  const users = getCnSecrets(token, '/shared-secrets/database-users');
-  const names = getCnSecrets(token, '/shared-secrets/database-names');
+  const users = getCnSecrets(token, '/shared-secrets/database-users', false, infEnv);
+  const names = getCnSecrets(token, '/shared-secrets/database-names', false, infEnv);
   const user = users[`${prefix}_DB_USER`];
   const password = users[`${prefix}_DB_PASSWORD`];
   const database = names[`${prefix}_DB_NAME`];
   if (!user || !password || !database) {
     throw new Error(`cn DB creds 不全 for ${prefix}（需 ${prefix}_DB_USER/PASSWORD@database-users + ${prefix}_DB_NAME@database-names）。该服务 cn 可能用字面 DATABASE_URL，见 optima-dev-skills#21。`);
   }
-  const port = ensureTunnel(CN_RDS_HOST, 'cn-buildbox');
+  const port = ensureTunnel(cnRdsHost(cnEnv), 'cn-buildbox');
   const conn: DBConnection = { host: 'localhost', port, user, password, database };
   return { query: (sql: string) => queryDB(conn, sql) };
 }
@@ -437,9 +459,9 @@ export function connectCnDB(prefix: string): { query: (sql: string) => string }
  * 用于 cred 不在 shared-secrets/database-users 的服务（如 gateway-core）。
  * expandSecretReferences=true 让 cn Infisical 解析 `${...}` 引用为字面值。
  */
-export function connectCnDBFromUrl(servicePath: string): { query: (sql: string) => string } {
+export function connectCnDBFromUrl(servicePath: string, cnEnv: string = 'cn-prod'): { query: (sql: string) => string } {
   const token = getCnInfisicalToken();
-  const secrets = getCnSecrets(token, servicePath, true);
+  const secrets = getCnSecrets(token, servicePath, true, cnInfisicalEnv(cnEnv));
   const dbUrl = secrets['DATABASE_URL'];
   if (!dbUrl) throw new Error(`cn DATABASE_URL 未找到 at ${servicePath}`);
   // 注意：DATABASE_URL 含凭证，报错只说事实，不回显值

package/bin/helpers/discount/create.ts

@@ -1,4 +1,4 @@
-import { callBilling, validateEnv } from '../billing-http';
+import { callBilling, validateEnvCnProd } from '../billing-http';
 import { confirmIfProd } from '../confirm-prompt';
 
 interface CreateArgs {
@@ -34,7 +34,7 @@ Optional:
   --ends <date>            Valid-until
   --max <N>                Max total redemptions (default: unlimited; 1 = single-use)
   --campaign <label>       Grouping label
-  --env stage|prod         (default: stage)
+  --env stage|prod|cn-prod|cn-stage  (default: stage)
   --yes                    Skip prod confirmation`);
     process.exit(0);
   }
@@ -62,7 +62,7 @@ Optional:
 
 export async function runCreate(argv: string[]): Promise<void> {
   const args = parseArgs(argv);
-  validateEnv(args.env);
+  validateEnvCnProd(args.env);
   await confirmIfProd(args.env, `Create discount code ${args.code.toUpperCase()} (${args.percentOff}% off)`, args.yes);
 
   const body: Record<string, unknown> = { code: args.code, percentOff: args.percentOff };

package/bin/helpers/discount/disable.ts

@@ -1,4 +1,4 @@
-import { callBilling, validateEnv } from '../billing-http';
+import { callBilling, validateEnvCnProd } from '../billing-http';
 import { confirmIfProd } from '../confirm-prompt';
 
 interface DisableArgs {
@@ -15,7 +15,7 @@ Required:
   --code <CODE>
 
 Optional:
-  --env stage|prod         (default: stage)
+  --env stage|prod|cn-prod|cn-stage  (default: stage)
   --yes                    Skip prod confirmation`);
     process.exit(0);
   }
@@ -36,7 +36,7 @@ Optional:
 
 export async function runDisable(argv: string[]): Promise<void> {
   const args = parseArgs(argv);
-  validateEnv(args.env);
+  validateEnvCnProd(args.env);
   await confirmIfProd(args.env, `Disable discount code ${args.code.toUpperCase()}`, args.yes);
   const res = await callBilling(args.env, 'PATCH', `/api/billing/admin/discount-codes/${encodeURIComponent(args.code)}`, { status: 'DISABLED' });
   console.log(`✓ Disabled (HTTP ${res.status}):`);

package/bin/helpers/discount/generate.ts

@@ -1,5 +1,5 @@
 import * as fs from 'fs';
-import { callBilling, validateEnv } from '../billing-http';
+import { callBilling, validateEnvCnProd } from '../billing-http';
 import { confirmIfProd } from '../confirm-prompt';
 
 interface GenArgs {
@@ -35,7 +35,7 @@ Optional:
   --products <a,b,...>     Limit to these productKeys
   --starts <date>          Valid-from (YYYY-MM-DD or ISO)
   --ends <date>            Valid-until
-  --env stage|prod         (default: stage)
+  --env stage|prod|cn-prod|cn-stage  (default: stage)
   --yes                    Skip prod confirmation`);
     process.exit(0);
   }
@@ -63,7 +63,7 @@ Optional:
 
 export async function runGenerate(argv: string[]): Promise<void> {
   const args = parseArgs(argv);
-  validateEnv(args.env);
+  validateEnvCnProd(args.env);
   await confirmIfProd(args.env, `Generate ${args.count} unique discount codes (${args.percentOff}% off, campaign ${args.campaign})`, args.yes);
 
   const body: Record<string, unknown> = { count: args.count, percentOff: args.percentOff, campaign: args.campaign };

package/bin/helpers/discount/list.ts

@@ -1,4 +1,4 @@
-import { callBilling, validateEnv } from '../billing-http';
+import { callBilling, validateEnvCnProd } from '../billing-http';
 
 interface ListArgs {
   campaign?: string;
@@ -15,7 +15,7 @@ Optional:
   --campaign <label>       Filter by campaign
   --code <CODE>            Filter by exact code
   --limit <N>              Max rows (default 500, max 1000)
-  --env stage|prod         (default: stage)`);
+  --env stage|prod|cn-prod|cn-stage  (default: stage)`);
     process.exit(0);
   }
   const out: Partial<ListArgs> = { env: 'stage' };
@@ -35,7 +35,7 @@ Optional:
 
 export async function runList(argv: string[]): Promise<void> {
   const args = parseArgs(argv);
-  validateEnv(args.env);
+  validateEnvCnProd(args.env);
   const qs = new URLSearchParams();
   if (args.campaign) qs.set('campaign', args.campaign);
   if (args.code) qs.set('code', args.code);

package/bin/helpers/entitlement/grant.ts

@@ -1,6 +1,5 @@
-import { callBilling, validateEnv } from '../billing-http';
+import { callBilling, validateEnvCnProd, resolveUserIdByEmailAnyEnv } from '../billing-http';
 import { confirmIfProd } from '../confirm-prompt';
-import { getInfisicalConfig, getInfisicalToken, resolveUserId } from '../db-utils';
 
 interface GrantArgs {
   email: string;
@@ -21,7 +20,7 @@ Required:
 
 Optional:
   --yes                            Skip prod confirmation prompt (no-op on stage)
-  --env stage|prod                 (default: stage)
+  --env stage|prod|cn-prod|cn-stage  (default: stage)
 
 Hardcoded server-side: source=ADMIN_GRANT, priceCents=0, currency=USD, grantedBy=<clientId>.`);
     process.exit(0);
@@ -47,11 +46,9 @@ Hardcoded server-side: source=ADMIN_GRANT, priceCents=0, currency=USD, grantedBy
 
 export async function runGrant(argv: string[]): Promise<void> {
   const args = parseArgs(argv);
-  validateEnv(args.env);
+  validateEnvCnProd(args.env);
 
-  const cfg = getInfisicalConfig();
-  const token = getInfisicalToken(cfg);
-  const userId = await resolveUserId(args.email, args.env, cfg, token);
+  const userId = await resolveUserIdByEmailAnyEnv(args.env, args.email);
 
   await confirmIfProd(
     args.env,

package/bin/helpers/entitlement/list.ts

@@ -1,5 +1,4 @@
-import { callBilling, validateEnv } from '../billing-http';
-import { getInfisicalConfig, getInfisicalToken, resolveUserId } from '../db-utils';
+import { callBilling, validateEnvCnProd, resolveUserIdByEmailAnyEnv } from '../billing-http';
 
 interface ListArgs {
   email: string;
@@ -14,7 +13,7 @@ Required:
   --email <user-email>             Resolved to userId via user-auth DB
 
 Optional:
-  --env stage|prod                 (default: stage)`);
+  --env stage|prod|cn-prod|cn-stage  (default: stage)`);
     process.exit(0);
   }
   const out: Partial<ListArgs> = { env: 'stage' };
@@ -42,11 +41,9 @@ interface EntitlementRow {
 
 export async function runList(argv: string[]): Promise<void> {
   const args = parseArgs(argv);
-  validateEnv(args.env);
+  validateEnvCnProd(args.env);
 
-  const cfg = getInfisicalConfig();
-  const token = getInfisicalToken(cfg);
-  const userId = await resolveUserId(args.email, args.env, cfg, token);
+  const userId = await resolveUserIdByEmailAnyEnv(args.env, args.email);
 
   const res = await callBilling<{ entitlements: EntitlementRow[] }>(
     args.env,

package/bin/helpers/entitlement/revoke.ts

@@ -1,6 +1,5 @@
-import { callBilling, validateEnv } from '../billing-http';
+import { callBilling, validateEnvCnProd, resolveUserIdByEmailAnyEnv } from '../billing-http';
 import { confirmIfProd } from '../confirm-prompt';
-import { getInfisicalConfig, getInfisicalToken, resolveUserId } from '../db-utils';
 
 interface RevokeArgs {
   email: string;
@@ -28,7 +27,7 @@ Required:
 
 Optional:
   --yes                            Skip prod confirmation prompt (no-op on stage)
-  --env stage|prod                 (default: stage)
+  --env stage|prod|cn-prod|cn-stage  (default: stage)
 
 Refuses non-ADMIN_GRANT sources (PAYMENT, PARTNER) with source-specific
 error pointing to the right reversal flow.`);
@@ -59,11 +58,9 @@ const PARTNER_REFUSAL = `refusing to revoke a PARTNER-source entitlement via CLI
 
 export async function runRevoke(argv: string[]): Promise<void> {
   const args = parseArgs(argv);
-  validateEnv(args.env);
+  validateEnvCnProd(args.env);
 
-  const cfg = getInfisicalConfig();
-  const token = getInfisicalToken(cfg);
-  const userId = await resolveUserId(args.email, args.env, cfg, token);
+  const userId = await resolveUserIdByEmailAnyEnv(args.env, args.email);
 
   // Step 1: Fetch user's entitlements
   const listRes = await callBilling<{ entitlements: EntitlementRow[] }>(

package/bin/helpers/generate-test-token.ts

@@ -24,7 +24,7 @@ interface MerchantSetupResponse {
   user_id: string;
 }
 
-type Environment = 'ci' | 'stage' | 'prod' | 'cn-prod';
+type Environment = 'ci' | 'stage' | 'prod' | 'cn-prod' | 'cn-stage';
 
 interface EnvironmentConfig {
   authUrl: string;
@@ -60,6 +60,14 @@ const ENV_CONFIG: Record<Environment, EnvironmentConfig> = {
     // 注意不要换成同名的 confidential client `commerce-cli-cn-prod-*`，那个需要 client_secret，走不通 CLI 的 public ROPC flow。
     clientId: 'dev-skill-cli-cn-pro-acvkmcuq',
     envName: 'cn-prod'
+  },
+  'cn-stage': {
+    // 阿里云预发（独立于 AWS stage `.optima.onl`）。域名 *.stage.optima.chat。
+    authUrl: 'https://auth.stage.optima.chat',
+    apiUrl: 'https://commerce.stage.optima.chat',
+    // cn-stage user-auth 里注册的 public client（开 password grant，ROPC flow）。
+    clientId: 'dev-skill-cli-cn-sta-3dvsxzdo',
+    envName: 'cn-stage'
   }
 };
 
@@ -183,6 +191,7 @@ async function main() {
   let phone: string | undefined;
   let address: string | undefined;
   let environment: Environment = 'ci';
+  let skipMerchant = false;
 
   // 解析命令行参数
   for (let i = 0; i < args.length; i++) {
@@ -198,12 +207,14 @@ async function main() {
       phone = args[++i];
     } else if (arg === '--address' && args[i + 1]) {
       address = args[++i];
+    } else if (arg === '--skip-merchant') {
+      skipMerchant = true;
     } else if (arg === '--env' && args[i + 1]) {
       const envArg = args[++i];
-      if (envArg === 'ci' || envArg === 'stage' || envArg === 'prod' || envArg === 'cn-prod') {
+      if (envArg === 'ci' || envArg === 'stage' || envArg === 'prod' || envArg === 'cn-prod' || envArg === 'cn-stage') {
         environment = envArg as Environment;
       } else {
-        console.error(`❌ Invalid environment: ${envArg}. Must be 'ci', 'stage', 'prod', or 'cn-prod'.`);
+        console.error(`❌ Invalid environment: ${envArg}. Must be 'ci', 'stage', 'prod', 'cn-prod', or 'cn-stage'.`);
         process.exit(1);
       }
     } else if (arg === '--help' || arg === '-h') {
@@ -216,20 +227,24 @@ Options:
   --business-name <name>       Merchant business name (default: auto-generated)
   --phone <phone>              Merchant phone number (optional)
   --address <address>          Merchant address (optional)
-  --env <environment>          Environment: ci (default), stage, prod, or cn-prod
+  --skip-merchant              只注册用户 + 拿 token，跳过 Commerce merchant profile 设置
+                               （token-only；用于 gateway E2E、或 commerce 未就绪的环境）
+  --env <environment>          Environment: ci (default), stage, prod, cn-prod, or cn-stage
   --help, -h                   Show this help message
 
 Environments:
-  ci       CI 环境 (auth.optima.chat, api.optima.chat)
-  stage    Stage 环境 (auth.stage.optima.onl, api.stage.optima.onl)
-  prod     Prod 环境 (auth.optima.onl, api.optima.onl)
-  cn-prod  阿里云生产环境 (auth.yzsgo.com, commerce.yzsgo.com) [#201]
+  ci        CI 环境 (auth.optima.chat, api.optima.chat)
+  stage     Stage 环境 (auth.stage.optima.onl, api.stage.optima.onl)
+  prod      Prod 环境 (auth.optima.onl, api.optima.onl)
+  cn-prod   阿里云生产环境 (auth.yzsgo.com, commerce.yzsgo.com) [#201]
+  cn-stage  阿里云预发环境 (auth.stage.optima.chat, commerce.stage.optima.chat)
 
 Example:
   optima-generate-test-token
   optima-generate-test-token --env stage
   optima-generate-test-token --env prod
   optima-generate-test-token --env cn-prod
+  optima-generate-test-token --env cn-stage
   optima-generate-test-token --business-name "My Test Shop" --env stage
       `);
       process.exit(0);
@@ -254,8 +269,11 @@ Example:
     // 2. 获取 token
     const token = await getToken(email, password, config);
 
-    // 3. 设置 merchant profile（Commerce API）
-    const merchantProfile = await setupMerchantProfile(token, businessName, config);
+    // 3. 设置 merchant profile（Commerce API）；--skip-merchant 时跳过（token-only）
+    const merchantProfile = skipMerchant
+      ? { merchant_id: 'N/A (skipped)' } as MerchantSetupResponse
+      : await setupMerchantProfile(token, businessName, config);
+    if (skipMerchant) console.log('\n⏭️  Skipped merchant profile setup (--skip-merchant)');
 
     // 4. 保存 token 到临时文件
     const tmpDir = os.tmpdir();

package/bin/helpers/grant-balance.ts

@@ -19,13 +19,14 @@ $1 = 700 credits (P15 unified ledger; the USD wallet is retired).
 Options:
   --amount <usd>        USD amount to grant (required, e.g. 5 for $5.00 = 3500 credits)
   --description <text>  Description for audit trail (optional)
-  --env <env>           Environment: stage, prod, cn-prod (default: stage)
+  --env <env>           Environment: stage, prod, cn-prod, cn-stage (default: stage)
   -h, --help            Show this help
 
 Examples:
   optima-grant-balance user@example.com --amount 5 --env prod
   optima-grant-balance user@example.com --amount 10 --description "Service outage compensation"
-  optima-grant-balance user@example.com --amount 1 --env cn-prod   # ¥-priced env, still USD input ($1 = 700 credits)`);
+  optima-grant-balance user@example.com --amount 1 --env cn-prod   # ¥-priced env, still USD input ($1 = 700 credits)
+  optima-grant-balance user@example.com --amount 1 --env cn-stage  # 阿里云预发`);
     process.exit(0);
   }
 
@@ -55,10 +56,10 @@ async function main() {
   console.log(`\n🎁 Granting $${amountUsd.toFixed(2)} (${Math.round(amountUsd * 700)} credits) to ${email} [${env.toUpperCase()}]\n`);
   if (description) console.log(`   Reason: ${description}`);
 
-  // cn-prod has no SSH tunnel into the Aliyun RDS — resolve via user-auth's
-  // internal lookup API instead of the direct SQL path.
+  // cn-prod / cn-stage have 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') {
+  if (env === 'cn-prod' || env === 'cn-stage') {
     userId = await resolveUserIdByEmail(env, email);
   } else {
     const infisicalConfig = getInfisicalConfig();