@optima-chat/dev-skills 0.8.2 → 0.9.0

package/.claude/skills/account/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: "account"
+description: "当用户请求查看账号状态、查询某用户的订阅/权益、禁用账号、封禁用户、ban、停用账号、解封、恢复账号、unban 时，使用此技能。支持 stage、prod、cn-prod、cn-stage 四个环境；标识符支持邮箱/手机号/userId。"
+allowed-tools: ["Bash"]
+---
+
+# 账号运营（status / ban / unban）
+
+以用户为中心的运营 admin 操作：查状态、禁用、恢复。CLI：`optima-account`。
+
+标识符 `<email|phone|userId>`：**cn-prod / cn-stage 用户多为手机号注册**，三种都支持；AWS stage/prod 仅 email（经 RDS SSH 隧道解析）。执行前都会打印 `🎯 目标账号` 反查回显，防止发错账号。
+
+## 执行方式
+
+```bash
+optima-account status <email|phone|userId> --env <env>
+optima-account ban   <email|phone|userId> --reason "..." --env <env> [--yes]
+optima-account unban <email|phone|userId> --env <env> [--yes]
+```
+
+| 参数 | 说明 | 默认 |
+|------|------|------|
+| `<email\|phone\|userId>` | 用户标识（必填）；cn 支持手机号/userId | - |
+| `--reason "..."` | 禁用原因（**ban 必填**） | - |
+| `--env <env>` | stage / prod / cn-prod / cn-stage | stage |
+| `--yes` | 跳过 prod / cn-prod 的确认提示 | - |
+
+## status（只读聚合）
+
+显示：订阅（membership-status）+ 权益（entitlements）。纯 M2M，无需 admin 凭证。
+
+```bash
+optima-account status 18898654855 --env cn-prod
+```
+> ⚠️ 账号禁用状态（banned_at/原因）与 credits 余额**暂不显示**——无 M2M 读取端点，见 optima-dev-skills#36。
+
+## ban / unban（需 admin-用户 token）
+
+走 user-auth `/api/v1/admin/users/{id}/{ban,unban}`，鉴权用 **admin 用户 token**（ROPC password grant，凭证读 Infisical `/shared-secrets/credentials`）。
+
+- **cn-prod / cn-stage** 需运行时设 `INFISICAL_CN_EMAIL` / `INFISICAL_CN_PASSWORD`（读 cn Infisical）。
+- **prod / cn-prod**（两个生产环境）执行前要求输入 `yes` 确认；`--yes` 可跳过。
+
+```bash
+optima-account ban user@example.com --reason "abuse" --env prod
+optima-account unban 18898654855 --env cn-prod
+```
+
+> ⚠️ **ban 不是即时踢会话**：仅置 `is_active=false`，挡新登录/刷新，但**已签发的 access token 仍有效到过期**。需要立即失效在线会话的能力是 user-auth 后续支持项。
+
+## 安全提醒
+
+1. ban/unban 前看清打印的 `🎯 目标账号`（手机/email/userId）。
+2. prod / cn-prod 是生产，确认无误再 `yes`。
+3. ban 是名义禁用，活跃会话不会立刻断——别误以为已立即封死。
+
+## 相关命令
+
+- `optima-grant-subscription` / `optima-grant-balance` - 开通会员 / 赠送 credits
+- `optima-entitlement` - 产品权益授予/撤销/查询
+- `optima-query-db` - 直查数据库核对（如 `is_active` / `banned_at`）

package/.claude/skills/entitlement/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: "entitlement"
+description: "当用户请求授予产品权益、发放 entitlement、发 scout-gift、给用户开某个 product、撤销权益、退权益、refund entitlement、查看某用户的权益列表时，使用此技能。支持 stage、prod、cn-prod、cn-stage 四个环境；标识符支持邮箱/手机号/userId。"
+allowed-tools: ["Bash"]
+---
+
+# 产品权益（Entitlement：grant / revoke / list）
+
+管理 billing 的产品权益（如 `scout-gift` 这类 `ONE_SHOT_SKILL` product）。CLI：`optima-entitlement`。
+
+标识符 `<email|phone|userId>`：**cn-prod / cn-stage 用户多为手机号**，三种都支持；AWS stage/prod 仅 email。授予/撤销前打印 `🎯 目标账号` 反查回显。
+
+## 执行方式
+
+```bash
+optima-entitlement grant  <email|phone|userId> --product-key <slug> --justification "..." --env <env> [--yes]
+optima-entitlement revoke <email|phone|userId> --product-key <slug> --reason "..."        --env <env> [--yes]
+optima-entitlement list   <email|phone|userId> --env <env>
+```
+
+| 参数 | 说明 | 默认 |
+|------|------|------|
+| `<email\|phone\|userId>` | 用户标识（必填；`--email` 为向后兼容别名） | - |
+| `--product-key <slug>` | 产品 key，如 `scout-gift`（grant/revoke 必填） | - |
+| `--justification "..."` | 授予理由（grant 必填，billing 否则 400） | - |
+| `--reason "..."` | 撤销理由（revoke 必填） | - |
+| `--env <env>` | stage / prod / cn-prod / cn-stage | stage |
+| `--yes` | 跳过 prod / cn-prod 确认 | - |
+
+服务端硬编码：`source=ADMIN_GRANT, priceCents=0, currency=USD, grantedBy=<dev-skills client>`。revoke 拒绝非 ADMIN_GRANT 来源（PAYMENT/PARTNER）。
+
+## 快速操作
+
+```bash
+# 给 cn-prod 手机号用户发 scout-gift
+optima-entitlement grant 18898654855 --product-key scout-gift --justification "运营赠送" --env cn-prod
+
+# 查权益
+optima-entitlement list 18898654855 --env cn-prod
+
+# 撤销
+optima-entitlement revoke user@example.com --product-key scout-gift --reason "误发" --env prod
+```
+
+## 环境说明
+
+- **stage / prod（AWS）**：仅 email；经 RDS SSH 隧道解析 userId。
+- **cn-prod / cn-stage（阿里云）**：email/手机号/userId；经 user-auth internal lookup（M2M，无 SSH 隧道）。走 HTTPS billing API（billing-api.yzsgo.com / billing-api.stage.optima.chat）。
+
+> prod / cn-prod 为生产环境，grant/revoke 执行前要求 `yes` 确认（`--yes` 跳过）。
+
+## 相关命令
+
+- `optima-account status` - 查看用户订阅+权益汇总
+- `optima-grant-subscription` / `optima-grant-balance` - 开通会员 / 赠送 credits

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

@@ -11,11 +11,11 @@ allowed-tools: ["Bash"]
 ## 执行方式：使用 CLI 工具
 
 ```bash
-optima-grant-balance <email> --amount <usd> [options]
+optima-grant-balance <email|phone|userId> --amount <usd> [options]
 ```
 
 **为什么使用 CLI 工具**：
-- 自动通过 email 查找 userId（跨 user-auth 数据库）
+- 自动通过 email/手机号/userId 查找 userId（cn 用户多为手机号；执行前打印 🎯 目标账号反查）
 - 自动处理 SSH 隧道和数据库连接
 - 不会影响现有订阅和已有余额（发放 bonus 积分（30 天有效期，重复执行会叠加发放））
 - 自动留审计痕迹（credit_lot 行，幂等键前缀 `dev-skills-grant:`）
@@ -47,7 +47,7 @@ optima-grant-balance user@example.com --amount 20 --description "服务中断补
 
 | 参数 | 说明 | 默认值 |
 |------|------|--------|
-| `<email>` | 用户邮箱（必填） | - |
+| `<email|phone|userId>` | 用户标识（必填；cn 支持手机号/userId） | - |
 | `--amount <usd>` | USD 金额（必填，> 0） | - |
 | `--description <text>` | 描述/原因（仅 console 输出） | - |
 | `--env <env>` | 环境：stage, prod, cn-prod, cn-stage | stage |

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

@@ -13,11 +13,11 @@ allowed-tools: ["Bash"]
 **重要**：无论用户使用 `/grant-subscription` 命令还是直接请求开通会员，都应该使用 `optima-grant-subscription` CLI 工具：
 
 ```bash
-optima-grant-subscription <email> [options]
+optima-grant-subscription <email|phone|userId> [options]
 ```
 
 **为什么使用 CLI 工具**：
-- 自动通过 email 查找 userId（跨 user-auth 数据库）
+- 自动通过 email/手机号/userId 查找 userId（cn 用户多为手机号；执行前打印 🎯 目标账号反查）
 - 自动处理 SSH 隧道和数据库连接
 - 自动取消旧订阅、经 billing API supersede 旧授予（void 旧 subscription lot + 发新）
 - 自动按 plan 配置发放 subscription 积分（期末过期）和 token quota
@@ -60,10 +60,10 @@ optima-grant-subscription user@example.com --plan pro-cn --env cn-stage
 
 | 参数 | 说明 | 默认值 |
 |------|------|--------|
-| `<email>` | 用户邮箱（必填） | - |
+| `<email|phone|userId>` | 用户标识（必填；cn 支持手机号/userId） | - |
 | `--plan <id>` | 计划：trial, starter, pro, enterprise | pro |
 | `--months <n>` | 时长（月） | 1 |
-| `--env <env>` | 环境：stage, prod, cn-prod | stage |
+| `--env <env>` | 环境：stage, prod, cn-prod, cn-stage | stage |
 
 > **cn-prod（国内环境）**：plan 用 CNY 定价的 `-cn` 档（trial / starter-cn / pro-cn / enterprise-cn，默认 pro-cn）；裸 USD 档 id 会被客户端拒绝（防止给 CN 用户误赠 USD 档积分量）。email 查找走 user-auth internal lookup API（无 SSH 隧道）。
 

package/.codex/skills/account/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: "account"
+description: "当用户请求查看账号状态、查询某用户的订阅/权益、禁用账号、封禁用户、ban、停用账号、解封、恢复账号、unban 时，使用此技能。支持 stage、prod、cn-prod、cn-stage 四个环境；标识符支持邮箱/手机号/userId。"
+allowed-tools: ["Bash"]
+---
+
+# 账号运营（status / ban / unban）
+
+以用户为中心的运营 admin 操作：查状态、禁用、恢复。CLI：`optima-account`。
+
+标识符 `<email|phone|userId>`：**cn-prod / cn-stage 用户多为手机号注册**，三种都支持；AWS stage/prod 仅 email（经 RDS SSH 隧道解析）。执行前都会打印 `🎯 目标账号` 反查回显，防止发错账号。
+
+## 执行方式
+
+```bash
+optima-account status <email|phone|userId> --env <env>
+optima-account ban   <email|phone|userId> --reason "..." --env <env> [--yes]
+optima-account unban <email|phone|userId> --env <env> [--yes]
+```
+
+| 参数 | 说明 | 默认 |
+|------|------|------|
+| `<email\|phone\|userId>` | 用户标识（必填）；cn 支持手机号/userId | - |
+| `--reason "..."` | 禁用原因（**ban 必填**） | - |
+| `--env <env>` | stage / prod / cn-prod / cn-stage | stage |
+| `--yes` | 跳过 prod / cn-prod 的确认提示 | - |
+
+## status（只读聚合）
+
+显示：订阅（membership-status）+ 权益（entitlements）。纯 M2M，无需 admin 凭证。
+
+```bash
+optima-account status 18898654855 --env cn-prod
+```
+> ⚠️ 账号禁用状态（banned_at/原因）与 credits 余额**暂不显示**——无 M2M 读取端点，见 optima-dev-skills#36。
+
+## ban / unban（需 admin-用户 token）
+
+走 user-auth `/api/v1/admin/users/{id}/{ban,unban}`，鉴权用 **admin 用户 token**（ROPC password grant，凭证读 Infisical `/shared-secrets/credentials`）。
+
+- **cn-prod / cn-stage** 需运行时设 `INFISICAL_CN_EMAIL` / `INFISICAL_CN_PASSWORD`（读 cn Infisical）。
+- **prod / cn-prod**（两个生产环境）执行前要求输入 `yes` 确认；`--yes` 可跳过。
+
+```bash
+optima-account ban user@example.com --reason "abuse" --env prod
+optima-account unban 18898654855 --env cn-prod
+```
+
+> ⚠️ **ban 不是即时踢会话**：仅置 `is_active=false`，挡新登录/刷新，但**已签发的 access token 仍有效到过期**。需要立即失效在线会话的能力是 user-auth 后续支持项。
+
+## 安全提醒
+
+1. ban/unban 前看清打印的 `🎯 目标账号`（手机/email/userId）。
+2. prod / cn-prod 是生产，确认无误再 `yes`。
+3. ban 是名义禁用，活跃会话不会立刻断——别误以为已立即封死。
+
+## 相关命令
+
+- `optima-grant-subscription` / `optima-grant-balance` - 开通会员 / 赠送 credits
+- `optima-entitlement` - 产品权益授予/撤销/查询
+- `optima-query-db` - 直查数据库核对（如 `is_active` / `banned_at`）

package/.codex/skills/entitlement/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: "entitlement"
+description: "当用户请求授予产品权益、发放 entitlement、发 scout-gift、给用户开某个 product、撤销权益、退权益、refund entitlement、查看某用户的权益列表时，使用此技能。支持 stage、prod、cn-prod、cn-stage 四个环境；标识符支持邮箱/手机号/userId。"
+allowed-tools: ["Bash"]
+---
+
+# 产品权益（Entitlement：grant / revoke / list）
+
+管理 billing 的产品权益（如 `scout-gift` 这类 `ONE_SHOT_SKILL` product）。CLI：`optima-entitlement`。
+
+标识符 `<email|phone|userId>`：**cn-prod / cn-stage 用户多为手机号**，三种都支持；AWS stage/prod 仅 email。授予/撤销前打印 `🎯 目标账号` 反查回显。
+
+## 执行方式
+
+```bash
+optima-entitlement grant  <email|phone|userId> --product-key <slug> --justification "..." --env <env> [--yes]
+optima-entitlement revoke <email|phone|userId> --product-key <slug> --reason "..."        --env <env> [--yes]
+optima-entitlement list   <email|phone|userId> --env <env>
+```
+
+| 参数 | 说明 | 默认 |
+|------|------|------|
+| `<email\|phone\|userId>` | 用户标识（必填；`--email` 为向后兼容别名） | - |
+| `--product-key <slug>` | 产品 key，如 `scout-gift`（grant/revoke 必填） | - |
+| `--justification "..."` | 授予理由（grant 必填，billing 否则 400） | - |
+| `--reason "..."` | 撤销理由（revoke 必填） | - |
+| `--env <env>` | stage / prod / cn-prod / cn-stage | stage |
+| `--yes` | 跳过 prod / cn-prod 确认 | - |
+
+服务端硬编码：`source=ADMIN_GRANT, priceCents=0, currency=USD, grantedBy=<dev-skills client>`。revoke 拒绝非 ADMIN_GRANT 来源（PAYMENT/PARTNER）。
+
+## 快速操作
+
+```bash
+# 给 cn-prod 手机号用户发 scout-gift
+optima-entitlement grant 18898654855 --product-key scout-gift --justification "运营赠送" --env cn-prod
+
+# 查权益
+optima-entitlement list 18898654855 --env cn-prod
+
+# 撤销
+optima-entitlement revoke user@example.com --product-key scout-gift --reason "误发" --env prod
+```
+
+## 环境说明
+
+- **stage / prod（AWS）**：仅 email；经 RDS SSH 隧道解析 userId。
+- **cn-prod / cn-stage（阿里云）**：email/手机号/userId；经 user-auth internal lookup（M2M，无 SSH 隧道）。走 HTTPS billing API（billing-api.yzsgo.com / billing-api.stage.optima.chat）。
+
+> prod / cn-prod 为生产环境，grant/revoke 执行前要求 `yes` 确认（`--yes` 跳过）。
+
+## 相关命令
+
+- `optima-account status` - 查看用户订阅+权益汇总
+- `optima-grant-subscription` / `optima-grant-balance` - 开通会员 / 赠送 credits

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

@@ -10,11 +10,11 @@ description: "Use when the user wants to grant credits (bonus, 30-day expiry) to
 ## 执行方式：使用 CLI 工具
 
 ```bash
-optima-grant-balance <email> --amount <usd> [options]
+optima-grant-balance <email|phone|userId> --amount <usd> [options]
 ```
 
 **为什么使用 CLI 工具**：
-- 自动通过 email 查找 userId（跨 user-auth 数据库）
+- 自动通过 email/手机号/userId 查找 userId（cn 用户多为手机号；执行前打印 🎯 目标账号反查）
 - 自动处理 SSH 隧道和数据库连接
 - 不会影响现有订阅和已有余额（发放 bonus 积分（30 天有效期，重复执行会叠加发放））
 - 自动留审计痕迹（credit_lot 行，幂等键前缀 `dev-skills-grant:`）
@@ -46,7 +46,7 @@ optima-grant-balance user@example.com --amount 20 --description "服务中断补
 
 | 参数 | 说明 | 默认值 |
 |------|------|--------|
-| `<email>` | 用户邮箱（必填） | - |
+| `<email|phone|userId>` | 用户标识（必填；cn 支持手机号/userId） | - |
 | `--amount <usd>` | USD 金额（必填，> 0） | - |
 | `--description <text>` | 描述/原因（仅 console 输出） | - |
 | `--env <env>` | 环境：stage, prod, cn-prod, cn-stage | stage |

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

@@ -10,7 +10,7 @@ Use this skill when the user asks to open or change a subscription plan.
 ## Preferred Command
 
 ```bash
-optima-grant-subscription <email> [options]
+optima-grant-subscription <email|phone|userId> [options]
 ```
 
 ## Examples

package/README.md

@@ -105,6 +105,12 @@ Claude:
 | `optima-show-env` | 查看服务环境变量 | `optima-show-env commerce-backend stage --filter DATABASE` |
 | `optima-generate-test-token` | 生成测试 token | `optima-generate-test-token --business-name "测试店铺"` |
 | `optima-discount` | 优惠码管理 | `optima-discount create --code LAUNCH20 --percent 20 --env stage` |
+| `optima-grant-subscription` | 开通/切换订阅 | `optima-grant-subscription 18898654855 --plan pro-cn --env cn-prod` |
+| `optima-grant-balance` | 赠送 credits | `optima-grant-balance user@example.com --amount 5 --env prod` |
+| `optima-entitlement` | 产品权益 grant/revoke/list | `optima-entitlement grant 18898654855 --product-key scout-gift --justification "..." --env cn-prod` |
+| `optima-account` | 账号 status/ban/unban | `optima-account ban user@example.com --reason "abuse" --env prod` |
+
+> **4 环境 + 标识符**：`grant-subscription` / `grant-balance` / `entitlement` / `account` 均支持 `stage` / `prod` / `cn-prod` / `cn-stage`。标识符 `<email\|phone\|userId>`——**cn-prod / cn-stage 用户多为手机号注册**，三种均可；AWS stage/prod 仅 email。`ban`/`unban` 及 `account status` 的禁用态读取需 admin-用户凭证（Infisical `/shared-secrets/credentials`；cn 另需 `INFISICAL_CN_EMAIL/PASSWORD`）。
 
 **特点**：
 - ✅ 支持 CI、Stage、Prod 三个环境（query-db）

package/bin/helpers/account.ts

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+
+// 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 前会要求确认。
+import { resolveTargetUser } from './grant-subscription';
+import { callBilling, callUserAuthAsAdmin, validateEnvCnProd } from './billing-http';
+import { confirmIfProd } from './confirm-prompt';
+
+interface CommonArgs {
+  identifier: string;
+  env: string;
+  reason: string | null;
+  yes: boolean;
+}
+
+function parseArgs(argv: string[], opts: { reason?: boolean } = {}): CommonArgs {
+  const out: Partial<CommonArgs> = { 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>');
+  validateEnvCnProd(out.env as string);
+  if (opts.reason && !out.reason) throw new Error('--reason required for ban');
+  return out as CommonArgs;
+}
+
+async function runStatus(argv: string[]): Promise<void> {
+  const { identifier, env } = parseArgs(argv);
+  const { userId, identity } = await resolveTargetUser(env, identifier);
+
+  // 订阅（membership-status，M2M；路径前缀 /api/internal 经 billing base URL）
+  let sub = '(读取失败)';
+  try {
+    const { body } = await callBilling<{ active: boolean; planId: string; status: string }>(
+      env, 'GET', `/api/internal/users/${encodeURIComponent(userId)}/membership-status`,
+    );
+    sub = `active=${body.active} plan=${body.planId} status=${body.status}`;
+  } catch (e) {
+    sub = `(读取失败: ${(e as Error).message})`;
+  }
+
+  // 权益（admin/entitlements，M2M）
+  let ents = '(读取失败)';
+  try {
+    const { body } = await callBilling<{ entitlements: Array<{ productKey: string; status: string; expiresAt?: string | null }> }>(
+      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 as Error).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: string[]): Promise<void> {
+  const { identifier, env, reason, yes } = parseArgs(argv, { reason: true });
+  const { userId, identity } = await resolveTargetUser(env, identifier);
+
+  await 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 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: string[]): Promise<void> {
+  const { identifier, env, yes } = parseArgs(argv);
+  const { userId, identity } = await resolveTargetUser(env, identifier);
+
+  await 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 callUserAuthAsAdmin(env, 'POST', `/api/v1/admin/users/${encodeURIComponent(userId)}/unban`);
+  console.log(`✓ Unbanned (HTTP ${res.status})\n`);
+}
+
+function printHelp(): void {
+  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(): Promise<void> {
+  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); });

package/bin/helpers/billing-http.ts

@@ -255,6 +255,111 @@ export async function callSkills<T = unknown>(
   return callService<T>(getSkillsUrl(env), env, method, path, body);
 }
 
+// ───── Admin-USER token (ROPC password grant) ───────────────────────────────
+// Distinct from getServiceToken (M2M client_credentials): user-auth's /admin/*
+// endpoints gate on get_current_admin_user — a real role=ADMIN *user* — which an
+// M2M token (no user_id) can't satisfy. So ban/unban mint a password-grant token
+// for the seeded admin account. Per-env ROPC client = the same public client
+// generate-test-token uses; admin email/password live in Infisical
+// /shared-secrets/credentials. Cached separately from the M2M tokenCache.
+const adminTokenCache: Record<string, string> = {};
+
+const ADMIN_ROPC_CLIENT: Record<string, string> = {
+  stage: 'commerce-cli-stage-ihbbwplz',
+  prod: 'commerce-cli-ecs-pro-i2r5of1h',
+  'cn-prod': 'dev-skill-cli-cn-pro-acvkmcuq',
+  'cn-stage': 'dev-skill-cli-cn-sta-3dvsxzdo',
+};
+
+const ADMIN_CREDS_PATH = '/shared-secrets/credentials';
+
+export async function getAdminUserToken(env: string): Promise<string> {
+  if (adminTokenCache[env]) return adminTokenCache[env];
+
+  let email: string;
+  let password: string;
+  if (env === 'cn-prod' || env === 'cn-stage') {
+    // cn Infisical (separate instance; needs INFISICAL_CN_EMAIL/PASSWORD at runtime).
+    const cnTok = getCnInfisicalToken();
+    const creds = getCnSecrets(cnTok, ADMIN_CREDS_PATH, false, env === 'cn-stage' ? 'staging' : 'prod');
+    email = creds['USER_AUTH_ADMIN_EMAIL'];
+    password = creds['USER_AUTH_ADMIN_PASSWORD'];
+  } else {
+    const cfg = getInfisicalConfig();
+    const tok = getInfisicalToken(cfg);
+    email = fetchInfisicalSecret(env, ADMIN_CREDS_PATH, 'USER_AUTH_ADMIN_EMAIL', cfg, tok);
+    password = fetchInfisicalSecret(env, ADMIN_CREDS_PATH, 'USER_AUTH_ADMIN_PASSWORD', cfg, tok);
+  }
+  if (!email || !password) {
+    throw new Error(`admin 凭证缺失（Infisical ${ADMIN_CREDS_PATH} 的 USER_AUTH_ADMIN_EMAIL/PASSWORD，env=${env}）`);
+  }
+
+  const clientId = ADMIN_ROPC_CLIENT[env];
+  const authUrl = USER_AUTH_URLS[env];
+  if (!clientId || !authUrl) throw new Error(`Unknown env: ${env}`);
+
+  // fetch (not execSync curl) so the password never lands in a shell command line.
+  const form = new URLSearchParams({
+    grant_type: 'password',
+    username: email,
+    password,
+    client_id: clientId,
+  });
+  const res = await fetch(`${authUrl}/api/v1/oauth/token`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: form,
+  });
+  const text = await res.text();
+  let parsed: { access_token?: string };
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new Error(`user-auth admin token endpoint returned non-JSON (${env}): ${text.slice(0, 200)}`);
+  }
+  if (!parsed.access_token) {
+    throw new Error(`admin-user token mint failed (${env}): ${text.slice(0, 200)}`);
+  }
+  adminTokenCache[env] = parsed.access_token;
+  return parsed.access_token;
+}
+
+/**
+ * Authenticated call to user-auth as the admin USER (role=ADMIN), for the
+ * /api/v1/admin/* endpoints that getServiceToken's M2M token can't reach
+ * (ban/unban). Mirrors callService's shape; single retry on 5xx.
+ */
+export async function callUserAuthAsAdmin<T = unknown>(
+  env: string,
+  method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE',
+  path: string,
+  body?: object,
+): Promise<ServiceResponse<T>> {
+  const authUrl = USER_AUTH_URLS[env];
+  if (!authUrl) throw new Error(`Unknown env: ${env}`);
+  const token = await getAdminUserToken(env);
+
+  const doFetch = async () => fetch(`${authUrl}${path}`, {
+    method,
+    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  });
+
+  let res = await doFetch();
+  if (res.status >= 500) res = await doFetch();
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(formatServiceError(res.status, res.statusText, text));
+  }
+  let parsed: T;
+  try {
+    parsed = text ? (JSON.parse(text) as T) : (undefined as unknown as T);
+  } catch {
+    throw new Error(`user-auth admin returned non-JSON 2xx body: ${text.slice(0, 200)}`);
+  }
+  return { status: res.status, body: parsed };
+}
+
 /**
  * Resolve a user's id by email via user-auth's internal lookup endpoint
  * (POST /api/v1/internal/users/lookup). cn-prod only: AWS envs resolve via
@@ -292,25 +397,6 @@ 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