@optima-chat/dev-skills 0.8.2 → 0.9.1

package/bin/helpers/entitlement/grant.ts

@@ -1,8 +1,9 @@
-import { callBilling, validateEnvCnProd, resolveUserIdByEmailAnyEnv } from '../billing-http';
+import { callBilling, validateEnvCnProd } from '../billing-http';
 import { confirmIfProd } from '../confirm-prompt';
+import { resolveTargetUser } from '../grant-subscription';
 
 interface GrantArgs {
-  email: string;
+  identifier: string;
   productKey: string;
   justification: string;
   yes: boolean;
@@ -11,16 +12,16 @@ interface GrantArgs {
 
 function parseArgs(argv: string[]): GrantArgs {
   if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
-    console.log(`Usage: optima-entitlement grant --email <user> --product-key <slug> --justification "..." [options]
+    console.log(`Usage: optima-entitlement grant <email|phone|userId> --product-key <slug> --justification "..." [options]
 
 Required:
-  --email <user-email>             Resolved to userId via user-auth DB
+  <email|phone|userId>             Target user. phone/userId only on cn-prod / cn-stage (AWS resolves email only).
   --product-key <productKey>
   --justification "..."            Required by billing (400 otherwise); stored on entitlement.justification
 
 Optional:
-  --yes                            Skip prod confirmation prompt (no-op on stage)
-  --env stage|prod|cn-prod|cn-stage  (default: stage)
+  --yes                            Skip prod/cn-prod confirmation prompt (no-op on stage / cn-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);
@@ -30,15 +31,18 @@ Hardcoded server-side: source=ADMIN_GRANT, priceCents=0, currency=USD, grantedBy
     const a = argv[i];
     const next = argv[i + 1];
     switch (a) {
-      case '--email': out.email = next; i++; break;
+      case '--email': out.identifier = next; i++; break; // back-compat alias for the positional identifier
       case '--product-key': out.productKey = next; i++; break;
       case '--justification': out.justification = next; i++; break;
       case '--yes': out.yes = true; break;
       case '--env': out.env = next; i++; break;
-      default: throw new Error(`Unknown arg: ${a}`);
+      default:
+        if (a.startsWith('--')) throw new Error(`Unknown arg: ${a}`);
+        if (out.identifier) throw new Error(`Unexpected positional arg: ${a} (identifier already set to ${out.identifier})`);
+        out.identifier = a;
     }
   }
-  if (!out.email) throw new Error('--email required');
+  if (!out.identifier) throw new Error('target user required (<email|phone|userId> positional, or --email)');
   if (!out.productKey) throw new Error('--product-key required');
   if (!out.justification) throw new Error('--justification required (billing returns 400 otherwise)');
   return out as GrantArgs;
@@ -48,15 +52,17 @@ export async function runGrant(argv: string[]): Promise<void> {
   const args = parseArgs(argv);
   validateEnvCnProd(args.env);
 
-  const userId = await resolveUserIdByEmailAnyEnv(args.env, args.email);
+  // Shared resolver: accepts email/phone/userId, reverse-verifies + phone-asserts
+  // on cn-prod, email-only via SSH tunnel on AWS (gateway#923).
+  const { userId } = await resolveTargetUser(args.env, args.identifier);
 
   await confirmIfProd(
     args.env,
-    `Action: GRANT product '${args.productKey}' to user ${args.email} (userId=${userId}) on ${args.env.toUpperCase()}\nJustification: ${args.justification}`,
+    `Action: GRANT product '${args.productKey}' to ${args.identifier} (userId=${userId}) on ${args.env.toUpperCase()}\nJustification: ${args.justification}`,
     args.yes,
   );
 
-  console.log(`\n🎁 Granting ${args.productKey} to ${args.email}...`);
+  console.log(`\n🎁 Granting ${args.productKey} to ${args.identifier}...`);
   const res = await callBilling(args.env, 'POST', '/api/billing/admin/grant-entitlement', {
     userId,
     productKey: args.productKey,

package/bin/helpers/entitlement/list.ts

@@ -1,19 +1,20 @@
-import { callBilling, validateEnvCnProd, resolveUserIdByEmailAnyEnv } from '../billing-http';
+import { callBilling, validateEnvCnProd } from '../billing-http';
+import { resolveTargetUser } from '../grant-subscription';
 
 interface ListArgs {
-  email: string;
+  identifier: string;
   env: string;
 }
 
 function parseArgs(argv: string[]): ListArgs {
   if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
-    console.log(`Usage: optima-entitlement list --email <user-email> [options]
+    console.log(`Usage: optima-entitlement list <email|phone|userId> [options]
 
 Required:
-  --email <user-email>             Resolved to userId via user-auth DB
+  <email|phone|userId>             Target user. phone/userId only on cn-prod / cn-stage (AWS resolves email only).
 
 Optional:
-  --env stage|prod|cn-prod|cn-stage  (default: stage)`);
+  --env stage|prod|cn-prod|cn-stage   (default: stage)`);
     process.exit(0);
   }
   const out: Partial<ListArgs> = { env: 'stage' };
@@ -21,12 +22,15 @@ Optional:
     const a = argv[i];
     const next = argv[i + 1];
     switch (a) {
-      case '--email': out.email = next; i++; break;
+      case '--email': out.identifier = next; i++; break; // back-compat alias for the positional identifier
       case '--env': out.env = next; i++; break;
-      default: throw new Error(`Unknown arg: ${a}`);
+      default:
+        if (a.startsWith('--')) throw new Error(`Unknown arg: ${a}`);
+        if (out.identifier) throw new Error(`Unexpected positional arg: ${a} (identifier already set to ${out.identifier})`);
+        out.identifier = a;
     }
   }
-  if (!out.email) throw new Error('--email required');
+  if (!out.identifier) throw new Error('target user required (<email|phone|userId> positional, or --email)');
   return out as ListArgs;
 }
 
@@ -43,7 +47,7 @@ export async function runList(argv: string[]): Promise<void> {
   const args = parseArgs(argv);
   validateEnvCnProd(args.env);
 
-  const userId = await resolveUserIdByEmailAnyEnv(args.env, args.email);
+  const { userId } = await resolveTargetUser(args.env, args.identifier);
 
   const res = await callBilling<{ entitlements: EntitlementRow[] }>(
     args.env,
@@ -53,12 +57,12 @@ export async function runList(argv: string[]): Promise<void> {
 
   const rows = res.body.entitlements ?? [];
   if (rows.length === 0) {
-    console.log(`(no entitlements for ${args.email} on ${args.env})`);
+    console.log(`(no entitlements for ${args.identifier} on ${args.env})`);
     return;
   }
   // Newest first per spec
   rows.sort((a, b) => b.purchasedAt.localeCompare(a.purchasedAt));
-  console.log(`${rows.length} entitlement(s) for ${args.email}:\n`);
+  console.log(`${rows.length} entitlement(s) for ${args.identifier}:\n`);
   console.log('id'.padEnd(38) + ' | ' + 'productKey'.padEnd(32) + ' | ' + 'status'.padEnd(9) + ' | ' + 'source'.padEnd(12) + ' | purchasedAt              | refundedAt');
   console.log('-'.repeat(140));
   for (const r of rows) {

package/bin/helpers/entitlement/revoke.ts

@@ -1,8 +1,9 @@
-import { callBilling, validateEnvCnProd, resolveUserIdByEmailAnyEnv } from '../billing-http';
+import { callBilling, validateEnvCnProd } from '../billing-http';
 import { confirmIfProd } from '../confirm-prompt';
+import { resolveTargetUser } from '../grant-subscription';
 
 interface RevokeArgs {
-  email: string;
+  identifier: string;
   productKey: string;
   reason: string;
   yes: boolean;
@@ -18,16 +19,16 @@ interface EntitlementRow {
 
 function parseArgs(argv: string[]): RevokeArgs {
   if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
-    console.log(`Usage: optima-entitlement revoke --email <user> --product-key <slug> --reason "..." [options]
+    console.log(`Usage: optima-entitlement revoke <email|phone|userId> --product-key <slug> --reason "..." [options]
 
 Required:
-  --email <user-email>             Resolved to userId via user-auth DB
+  <email|phone|userId>             Target user. phone/userId only on cn-prod / cn-stage (AWS resolves email only).
   --product-key <productKey>
   --reason "..."                   Required by billing (400 otherwise); stored on entitlement.refundReason
 
 Optional:
-  --yes                            Skip prod confirmation prompt (no-op on stage)
-  --env stage|prod|cn-prod|cn-stage  (default: stage)
+  --yes                            Skip prod/cn-prod confirmation prompt (no-op on stage / cn-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.`);
@@ -38,15 +39,18 @@ error pointing to the right reversal flow.`);
     const a = argv[i];
     const next = argv[i + 1];
     switch (a) {
-      case '--email': out.email = next; i++; break;
+      case '--email': out.identifier = next; i++; break; // back-compat alias for the positional identifier
       case '--product-key': out.productKey = next; i++; break;
       case '--reason': out.reason = next; i++; break;
       case '--yes': out.yes = true; break;
       case '--env': out.env = next; i++; break;
-      default: throw new Error(`Unknown arg: ${a}`);
+      default:
+        if (a.startsWith('--')) throw new Error(`Unknown arg: ${a}`);
+        if (out.identifier) throw new Error(`Unexpected positional arg: ${a} (identifier already set to ${out.identifier})`);
+        out.identifier = a;
     }
   }
-  if (!out.email) throw new Error('--email required');
+  if (!out.identifier) throw new Error('target user required (<email|phone|userId> positional, or --email)');
   if (!out.productKey) throw new Error('--product-key required');
   if (!out.reason) throw new Error('--reason required (billing returns 400 otherwise)');
   return out as RevokeArgs;
@@ -60,7 +64,7 @@ export async function runRevoke(argv: string[]): Promise<void> {
   const args = parseArgs(argv);
   validateEnvCnProd(args.env);
 
-  const userId = await resolveUserIdByEmailAnyEnv(args.env, args.email);
+  const { userId } = await resolveTargetUser(args.env, args.identifier);
 
   // Step 1: Fetch user's entitlements
   const listRes = await callBilling<{ entitlements: EntitlementRow[] }>(
@@ -75,10 +79,10 @@ export async function runRevoke(argv: string[]): Promise<void> {
 
   // Step 3: Validate count (partial unique index enforces ≤1 ACTIVE)
   if (matches.length === 0) {
-    throw new Error(`no active entitlement for (user=${args.email}, product=${args.productKey}) on ${args.env}`);
+    throw new Error(`no active entitlement for (user=${args.identifier}, product=${args.productKey}) on ${args.env}`);
   }
   if (matches.length > 1) {
-    throw new Error(`unexpected: ${matches.length} ACTIVE entitlements for (user, product) — partial unique constraint should prevent this. Inspect with: optima-entitlement list --email ${args.email}`);
+    throw new Error(`unexpected: ${matches.length} ACTIVE entitlements for (user, product) — partial unique constraint should prevent this. Inspect with: optima-entitlement list ${args.identifier}`);
   }
   const target = matches[0];
 
@@ -89,7 +93,7 @@ export async function runRevoke(argv: string[]): Promise<void> {
 
   await confirmIfProd(
     args.env,
-    `Action: REVOKE entitlement ${target.id} (productKey=${target.productKey}) for user ${args.email} (userId=${userId}) on ${args.env.toUpperCase()}\nReason: ${args.reason}`,
+    `Action: REVOKE entitlement ${target.id} (productKey=${target.productKey}) for ${args.identifier} (userId=${userId}) on ${args.env.toUpperCase()}\nReason: ${args.reason}`,
     args.yes,
   );
 
@@ -102,7 +106,7 @@ export async function runRevoke(argv: string[]): Promise<void> {
   // this branch only ever runs for ADMIN_GRANT (priceCents=0) — Stripe
   // refund path in billing (admin-products.ts:296-307) is gated on
   // source=PAYMENT and won't trigger here.
-  console.log(`\n♻️  Revoking entitlement ${target.id} for ${args.email}...`);
+  console.log(`\n♻️  Revoking entitlement ${target.id} for ${args.identifier}...`);
   const res = await callBilling(args.env, 'POST', '/api/billing/admin/refund-entitlement', {
     entitlementId: target.id,
     refundReason: args.reason,

package/bin/helpers/grant-balance.ts

@@ -5,17 +5,20 @@
 // 改调 billing 服务态端点（grantCredits → bonus 积分）。
 // ⚠️ 语义变化：旧 wallet granted 无期限；积分 bonus 桶标准 30 天有效期。
 import { randomUUID } from 'crypto';
-import { getInfisicalConfig, getInfisicalToken, resolveUserId } from './db-utils';
-import { callBilling, resolveUserIdByEmail, validateEnvCnProd } from './billing-http';
+import { callBilling, validateEnvCnProd } from './billing-http';
+import { resolveTargetUser } from './grant-subscription';
 
-function parseArgs(args: string[]): { email: string; amountUsd: number; description: string | null; env: string } {
+function parseArgs(args: string[]): { identifier: string; amountUsd: number; description: string | null; env: string } {
   if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
-    console.log(`Usage: optima-grant-balance <email> --amount <usd> [options]
+    console.log(`Usage: optima-grant-balance <email|phone|userId> --amount <usd> [options]
 
 Grant credits to a user (bonus bucket, expires in 30 days).
 Used for promotional grants, compensation, referral rewards, etc.
 $1 = 700 credits (P15 unified ledger; the USD wallet is retired).
 
+Target user: <email|phone|userId> (positional). phone/userId only on
+cn-prod / cn-stage; AWS stage/prod resolve email only.
+
 Options:
   --amount <usd>        USD amount to grant (required, e.g. 5 for $5.00 = 3500 credits)
   --description <text>  Description for audit trail (optional)
@@ -24,13 +27,12 @@ Options:
 
 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 18898654855 --amount 1 --env cn-prod   # 手机号（cn 用户多为手机号注册）
   optima-grant-balance user@example.com --amount 1 --env cn-stage  # 阿里云预发`);
     process.exit(0);
   }
 
-  const email = args[0];
+  const identifier = args[0];
   let amountUsd = 0;
   let description: string | null = null;
   let env = 'stage';
@@ -47,25 +49,19 @@ Examples:
   }
   validateEnvCnProd(env);
 
-  return { email, amountUsd, description, env };
+  return { identifier, amountUsd, description, env };
 }
 
 async function main() {
-  const { email, amountUsd, description, env } = parseArgs(process.argv.slice(2));
+  const { identifier, amountUsd, description, env } = parseArgs(process.argv.slice(2));
 
-  console.log(`\n🎁 Granting $${amountUsd.toFixed(2)} (${Math.round(amountUsd * 700)} credits) to ${email} [${env.toUpperCase()}]\n`);
+  console.log(`\n🎁 Granting $${amountUsd.toFixed(2)} (${Math.round(amountUsd * 700)} credits) to ${identifier} [${env.toUpperCase()}]\n`);
   if (description) console.log(`   Reason: ${description}`);
 
-  // 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' || env === 'cn-stage') {
-    userId = await resolveUserIdByEmail(env, email);
-  } else {
-    const infisicalConfig = getInfisicalConfig();
-    const token = getInfisicalToken(infisicalConfig);
-    userId = await resolveUserId(email, env, infisicalConfig, token);
-  }
+  // Shared resolver: classify→resolve→reverse-verify echo→phone-assert on cn
+  // (so phone/userId works for cn's phone-registered users, gateway#923);
+  // email-only via the RDS SSH tunnel on AWS.
+  const { userId } = await resolveTargetUser(env, identifier);
 
   // 幂等键 per-invocation 生成、callBilling 的 5xx retry 复用同 body —— 「已
   // commit 但响应 5xx」场景重试不双发（billing spec R2-M3）。
@@ -80,7 +76,7 @@ async function main() {
   );
 
   console.log(`✓ Granted ${body.credits} credits (lot ${body.lotId})`);
-  console.log(`\n✅ Done! ${email} received ${body.credits} bonus credits (expires in 30 days)\n`);
+  console.log(`\n✅ Done! ${identifier} received ${body.credits} bonus credits (expires in 30 days)\n`);
 }
 
 main().catch(error => {

package/bin/helpers/grant-subscription.ts

@@ -64,15 +64,16 @@ export function assertAwsEmailOnly(env: string, kind: 'email' | 'phone' | 'userI
   }
 }
 
-// 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.
+// All envs use canonical plan ids (no market suffix). billing canonicalized
+// plan ids — dropped the `-cn` suffix; market is now carried by deployment-level
+// BILLING_MARKET + the plan's `currency` column, not the id (optima-billing#181).
+// cn envs additionally have the CN-only `free` tier. Per-env whitelist guards
+// against granting a plan absent in that env.
 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'],
-  // cn-stage 卖同一套 CNY -cn plan（billing plan 目录与 cn-prod 一致）
-  'cn-stage': ['trial', 'starter-cn', 'pro-cn', 'enterprise-cn'],
+  'cn-prod': ['trial', 'starter', 'pro', 'enterprise', 'free'],
+  'cn-stage': ['trial', 'starter', 'pro', 'enterprise', 'free'],
 };
 
 function parseArgs(args: string[]): { identifier: string; plan: string; months: number; env: string } {
@@ -81,7 +82,8 @@ function parseArgs(args: string[]): { identifier: string; plan: string; months:
 
 Options:
   --plan <id>       Plan: trial, starter, pro, enterprise (default: pro)
-                    cn-prod/cn-stage plans: trial, starter-cn, pro-cn, enterprise-cn (default: pro-cn)
+                    cn-prod/cn-stage additionally allow: free
+                    (legacy *-cn ids are accepted and normalized to canonical)
   --months <n>      Duration in months (default: 1)
   --env <env>       Environment: stage, prod, cn-prod, cn-stage (default: stage)
   -h, --help        Show this help`);
@@ -100,7 +102,10 @@ Options:
   }
 
   validateEnvCnProd(env);
-  plan = plan ?? (env === 'cn-prod' || env === 'cn-stage' ? 'pro-cn' : 'pro');
+  // billing canonicalized plan ids (dropped the -cn suffix, optima-billing#181).
+  // Default to canonical `pro`; accept legacy `*-cn` input (operator muscle
+  // memory) and normalize so it still resolves after the -cn rows are deleted.
+  plan = (plan ?? 'pro').replace(/-cn$/, '');
   const allowed = PLANS_BY_ENV[env];
   if (!allowed.includes(plan)) {
     console.error(`Unknown plan for ${env}: ${plan}. Available: ${allowed.join(', ')}`);
@@ -111,22 +116,37 @@ Options:
   return { identifier, plan, months, env };
 }
 
-async function main() {
-  const { identifier, plan, months, env } = parseArgs(process.argv.slice(2));
-
+/**
+ * Resolve a CLI identifier (`<email|phone|userId>`) to a userId + verified
+ * account identity, handling the AWS-vs-cn split. Shared by grant-subscription,
+ * grant-balance, the optima-entitlement subcommands, and optima-account so all
+ * four accept the same identifier forms (gateway#923: phone/userId on cn).
+ *
+ * - AWS (stage/prod): email-only via the RDS SSH tunnel; no internal HTTP
+ *   reverse-verify (the AWS dev-skills token lacks internal:users:write).
+ * - cn-prod / cn-stage: no tunnel into the Aliyun RDS — classify → resolve via
+ *   user-auth internal endpoints → getUserById reverse-verify → phone-assert.
+ *   cn-stage shares cn-prod's HTTP path (same internal endpoints, cn-stage M2M
+ *   token); the split is AWS-vs-cn, NOT prod-vs-stage.
+ *
+ * Prints a `🎯 目标账号` line in BOTH branches before returning, so a wrong
+ * userId is caught by eye before any destructive call (ban/grant/revoke).
+ */
+export async function resolveTargetUser(
+  env: string,
+  identifier: string,
+): Promise<{
+  userId: string;
+  kind: 'email' | 'phone' | 'userId';
+  identity: { phone: string | null; email: string | null };
+}> {
   const kind = classifyIdentifier(identifier);
   assertAwsEmailOnly(env, kind);
-  console.log(`\n🎁 Granting ${plan} subscription to ${identifier} (${kind}) for ${months} month(s) [${env.toUpperCase()}]\n`);
-
-  // identity is the verified target account to print on success. AWS keeps the
-  // pre-change behavior (email-only, no internal HTTP reverse-verify); only
-  // cn-prod / cn-stage run the full classify→resolve→getUserById→phone-assert防呆 path.
-  let userId: string;
-  let identity: { phone: string | null; email: string | null };
 
   if (env === 'cn-prod' || env === 'cn-stage') {
     // cn-prod / cn-stage have no SSH tunnel into the Aliyun RDS — resolve via
     // user-auth, and the dev-skills token carries internal:users:write for lookups.
+    let userId: string;
     if (kind === 'userId') {
       userId = identifier;
     } else if (kind === 'phone') {
@@ -136,28 +156,39 @@ async function main() {
     }
 
     // Reverse-verify: fetch and loudly print the target account identity
-    // before granting, so a wrong userId is caught by eye (gateway#923).
+    // before any mutation, so a wrong userId is caught by eye (gateway#923).
     const acct = await getUserById(env, userId);
     console.log(
       `🎯 目标账号: userId=${userId} 手机=${acct.phone || '(无)'} email=${acct.email || '(无)'} 当前plan=${acct.current_plan || '?'}`,
     );
 
     // Hard assertion: a phone-input grant must land on an account whose phone
-    // matches. Runs BEFORE callBilling — a mismatch aborts without granting.
+    // matches. Runs BEFORE the caller's mutation — a mismatch aborts.
     if (kind === 'phone') {
       assertPhoneMatch(identifier, acct.phone);
     }
-    identity = { phone: acct.phone, email: acct.email };
-  } else {
-    // AWS (stage/prod): email-only, resolved via the RDS SSH tunnel. No
-    // internal HTTP reverse-verify (token lacks internal:users:write → 403).
-    const infisicalConfig = getInfisicalConfig();
-    const token = getInfisicalToken(infisicalConfig);
-    userId = await resolveUserId(identifier, env, infisicalConfig, token);
-    console.log(`🎯 目标账号: userId=${userId} email=${identifier}`);
-    identity = { phone: null, email: identifier };
+    return { userId, kind, identity: { phone: acct.phone, email: acct.email } };
   }
 
+  // AWS (stage/prod): email-only, resolved via the RDS SSH tunnel. No internal
+  // HTTP reverse-verify (token lacks internal:users:write → 403), but still
+  // echo the resolved account so destructive ops have a confirmation line (R1).
+  const infisicalConfig = getInfisicalConfig();
+  const token = getInfisicalToken(infisicalConfig);
+  const userId = await resolveUserId(identifier, env, infisicalConfig, token);
+  console.log(`🎯 目标账号: userId=${userId} email=${identifier}`);
+  return { userId, kind, identity: { phone: null, email: identifier } };
+}
+
+async function main() {
+  const { identifier, plan, months, 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 callBilling<{
     success: boolean;
     subscriptionId: string;

package/dist/bin/helpers/account.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// optima-account：以用户为中心的运营 admin 操作。
+//  · status — 只读聚合（订阅 + 权益）。M2M。
+//  · ban / unban — user-auth 账号禁用/恢复。需 admin-用户 token（非 M2M）。
+//
+// 标识符 <email|phone|userId>：cn-prod/cn-stage 支持三种，AWS stage/prod 仅 email
+// （见 resolveTargetUser）。两个生产环境（prod/cn-prod）ban/unban 前会要求确认。
+const grant_subscription_1 = require("./grant-subscription");
+const billing_http_1 = require("./billing-http");
+const confirm_prompt_1 = require("./confirm-prompt");
+function parseArgs(argv, opts = {}) {
+    const out = { env: 'stage', reason: null, yes: false };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const next = argv[i + 1];
+        if (a === '--env') {
+            out.env = next;
+            i++;
+        }
+        else if (a === '--reason') {
+            out.reason = next;
+            i++;
+        }
+        else if (a === '--yes') {
+            out.yes = true;
+        }
+        else if (a.startsWith('--')) {
+            throw new Error(`Unknown arg: ${a}`);
+        }
+        else if (out.identifier) {
+            throw new Error(`Unexpected positional arg: ${a} (identifier already set to ${out.identifier})`);
+        }
+        else {
+            out.identifier = a;
+        }
+    }
+    if (!out.identifier)
+        throw new Error('target user required: <email|phone|userId>');
+    (0, billing_http_1.validateEnvCnProd)(out.env);
+    if (opts.reason && !out.reason)
+        throw new Error('--reason required for ban');
+    return out;
+}
+async function runStatus(argv) {
+    const { identifier, env } = parseArgs(argv);
+    const { userId, identity } = await (0, grant_subscription_1.resolveTargetUser)(env, identifier);
+    // 订阅（membership-status，M2M；路径前缀 /api/internal 经 billing base URL）
+    let sub = '(读取失败)';
+    try {
+        const { body } = await (0, billing_http_1.callBilling)(env, 'GET', `/api/internal/users/${encodeURIComponent(userId)}/membership-status`);
+        sub = `active=${body.active} plan=${body.planId} status=${body.status}`;
+    }
+    catch (e) {
+        sub = `(读取失败: ${e.message})`;
+    }
+    // 权益（admin/entitlements，M2M）
+    let ents = '(读取失败)';
+    try {
+        const { body } = await (0, billing_http_1.callBilling)(env, 'GET', `/api/billing/admin/entitlements?userId=${encodeURIComponent(userId)}`);
+        const rows = body.entitlements ?? [];
+        ents = rows.length ? rows.map((r) => `${r.productKey}(${r.status})`).join(', ') : '(无)';
+    }
+    catch (e) {
+        ents = `(读取失败: ${e.message})`;
+    }
+    console.log(`\n=== 账号状态 [${env.toUpperCase()}] ===`);
+    console.log(`userId : ${userId}`);
+    console.log(`手机   : ${identity.phone || '(无)'}`);
+    console.log(`email  : ${identity.email || '(无)'}`);
+    console.log(`订阅   : ${sub}`);
+    console.log(`权益   : ${ents}`);
+    console.log(`禁用态/credits 余额: 暂未纳入（banned_at 与 credits 无 M2M 读取端点，见 optima-dev-skills#36）\n`);
+}
+async function runBan(argv) {
+    const { identifier, env, reason, yes } = parseArgs(argv, { reason: true });
+    const { userId, identity } = await (0, grant_subscription_1.resolveTargetUser)(env, identifier);
+    await (0, confirm_prompt_1.confirmIfProd)(env, `Action: BAN userId=${userId} (手机=${identity.phone || '(无)'} email=${identity.email || '(无)'}) on ${env.toUpperCase()}\nReason: ${reason}`, yes);
+    console.log(`\n🚫 Banning ${identifier} (userId=${userId})...`);
+    const res = await (0, billing_http_1.callUserAuthAsAdmin)(env, 'POST', `/api/v1/admin/users/${encodeURIComponent(userId)}/ban`, { reason });
+    console.log(`✓ Banned (HTTP ${res.status})`);
+    console.log('⚠️  注意：ban 仅置 is_active=false——挡新登录/刷新，但**不会立即失效已签发的 access token**（活跃会话到 token 过期才失效）。即时踢会话需 user-auth 后续支持。\n');
+}
+async function runUnban(argv) {
+    const { identifier, env, yes } = parseArgs(argv);
+    const { userId, identity } = await (0, grant_subscription_1.resolveTargetUser)(env, identifier);
+    await (0, confirm_prompt_1.confirmIfProd)(env, `Action: UNBAN userId=${userId} (手机=${identity.phone || '(无)'} email=${identity.email || '(无)'}) on ${env.toUpperCase()}`, yes);
+    console.log(`\n♻️  Unbanning ${identifier} (userId=${userId})...`);
+    const res = await (0, billing_http_1.callUserAuthAsAdmin)(env, 'POST', `/api/v1/admin/users/${encodeURIComponent(userId)}/unban`);
+    console.log(`✓ Unbanned (HTTP ${res.status})\n`);
+}
+function printHelp() {
+    console.log(`Usage: optima-account <subcommand> <email|phone|userId> [options]
+
+Subcommands:
+  status   只读聚合：订阅(membership) + 权益(entitlements)
+  ban      禁用账号（user-auth is_active=false）。需 --reason
+  unban    恢复账号
+
+Target user: <email|phone|userId> (positional). phone/userId only on
+cn-prod / cn-stage; AWS stage/prod resolve email only.
+
+Options:
+  --reason "..."   Ban reason (required for ban; stored on the user)
+  --yes            Skip prod/cn-prod confirmation prompt
+  --env <env>      Environment: stage, prod, cn-prod, cn-stage (default: stage)
+
+Notes:
+  · ban/unban 用 admin-用户 token（Infisical /shared-secrets/credentials）。
+  · ban 非即时踢会话：仅挡新登录/刷新，活跃 token 过期后失效。
+  · 禁用原因/banned_at 与 credits 余额暂不在 status 显示（见 #36）。
+
+Examples:
+  optima-account status 18898654855 --env cn-prod
+  optima-account ban user@example.com --reason "abuse" --env prod
+  optima-account unban 18898654855 --env cn-prod`);
+}
+async function main() {
+    const [, , subcommand, ...rest] = process.argv;
+    if (!subcommand || subcommand === '-h' || subcommand === '--help') {
+        printHelp();
+        process.exit(0);
+    }
+    switch (subcommand) {
+        case 'status':
+            await runStatus(rest);
+            break;
+        case 'ban':
+            await runBan(rest);
+            break;
+        case 'unban':
+            await runUnban(rest);
+            break;
+        default:
+            console.error(`Unknown subcommand: ${subcommand}`);
+            printHelp();
+            process.exit(1);
+    }
+}
+main().catch((err) => { console.error('\n❌ Error:', err.message); process.exit(1); });