@optima-chat/dev-skills 0.8.1 → 0.9.0

package/.claude/commands/logs.md

@@ -50,7 +50,8 @@
   - `ci` - CI 持续集成环境（开发环境，默认）
   - `stage` - Stage 预发布环境（ECS Fargate）
   - `prod` - 生产环境（ECS Fargate）
-  - `cn-prod`（别名 `cn`）- 阿里云 cn-prod 环境（SAE，cn-beijing，经 buildbox 取日志）
+  - `cn-prod`（别名 `cn`）- 阿里云 cn-prod 环境（SAE，cn-beijing，`optima-logs` 直连 SLS）
+  - `cn-stage` - 阿里云 cn-stage 预发环境（SAE，cn-beijing，`optima-logs` 直连 SLS）
 
 ## 示例
 
@@ -72,7 +73,7 @@
 - `ci` 或未指定 → 使用 SSH + Docker Compose（第 0 节，默认）
 - `stage` → 使用 AWS CloudWatch Logs - ECS（第 1 节）
 - `prod` → 使用 AWS CloudWatch Logs - ECS（第 2 节）
-- `cn-prod` / `cn` → 阿里云 SAE，经 buildbox 调 `DescribeInstanceLog`（第 3 节）
+- `cn-prod` / `cn` / `cn-stage` → 阿里云 SLS，`optima-logs` 直连（第 3 节，免 buildbox）
 
 ### 0. CI 环境（environment = "ci" 或默认）
 
@@ -211,59 +212,38 @@ aws logs get-log-events --log-group-name /ecs/commerce-backend-prod --log-stream
 
 **注意**: `optima-store` 仅在 Stage 环境部署
 
-### 3. cn-prod 环境（environment = "cn-prod" 或 "cn"）
+### 3. cn-prod / cn-stage 环境（environment = "cn-prod"/"cn" 或 "cn-stage"）
 
-**部署方式**: 阿里云 **SAE**（Serverless App Engine，cn-beijing），不是 ECS/CloudWatch。
-**访问方式**: 经 buildbox（`root@47.94.105.163`，唯一装了 `aliyun-optima` profile + VPC 可达的机器）调 SAE OpenAPI。
+**部署方式**: 阿里云 **SAE**（cn-beijing），不是 ECS/CloudWatch。
+**访问方式**: ✅ **用 `optima-logs` CLI 直连阿里云 SLS**，不再经 buildbox。
 
-> ⚠️ SAE **未配 SLS**，stdout 日志只能用 `DescribeInstanceLog` 取实例**当前缓冲**（非历史检索；重启/滚动后旧日志丢）。要历史检索需给 SAE 配 SLS。
+> ✅ 现状更新（2026-06-16）：cn-prod / cn-stage 全部服务**已接 SLS**（含 ECI 的 `agent-runtime`）。
+> SLS `GetLogs` 是公网控制面 API，本机 `aliyun-optima` profile 直连即可，支持**历史检索 + 时间窗 + 关键词**——
+> 旧的「SSH buildbox → SAE `DescribeInstanceLog` 取当前缓冲」流程已弃用（缓冲式、重启即丢、不能检索）。
 
-**日志链**: service → AppId → GroupId → InstanceId → `DescribeInstanceLog`
-
-**关键坑**（实测）:
-- API 是 RPC-style `aliyun sae DescribeInstanceLog`，ROA 路径是 `/pop/v1/sam/**instance**/describeInstanceLog`（不是 `/sam/app/...`，写错报 "can not find api by path"）。
-- buildbox 密码在 1P `op://Optima/gdmixcizjci5bvuu3nuvgg4ooe/password`（标题带括号必须用 item ID）。
-
-**service → AppId 映射**（cn-prod，2026-06-01；新增/变动用 `aliyun sae ListApplications` 重查）:
+**推荐用法（首选）**:
+```bash
+optima-logs gateway-core                       # 默认 cn-prod，最近 1h，100 行
+optima-logs gateway-core --env cn-stage
+optima-logs agent-runtime --env cn-prod --since 2h   # ECI 容器也直接可见
+optima-logs user-auth --grep error -n 200
+optima-logs gateway-core --since 30m --json | jq .   # 机器可读
+```
 
-| service | AppId |
-|---|---|
-| `gateway-core` | `a08ce23f-3d3e-4d89-a2cf-53c8adba614e` |
-| `agentic-chat` | `6e290c73-a646-43ef-9da5-ad0b2e7eff73` |
-| `gw-admin` | `c6bc5a78-b27f-46e2-825a-eaa338c23645` |
-| `user-auth` | `d6fbf9de-fed6-4165-978f-7b3a0a456acc` |
-| `user-auth-admin` | `54093f99-37bf-4354-abd7-f6e76abdbcb6` |
-| `optima-scout` | `f5bb7e82-e57c-4bd4-83ae-2c25f8d38647` |
-| `optima-skills` | `55a63ee7-fb75-46e4-99f3-20854a699237` |
-| `infisical` | `52b33fc6-b26d-495a-8885-225d38b3d42f` |
+参数：`--env stage|prod|cn-prod|cn-stage`、`--since 30m|2h|1d`、`--grep <kw>`、`--lines/-n <N>`、`--json`。
+`service` == SLS logstore 名（同名）。列全部 logstore：
+`aliyun sls ListLogStores --project optima-cn-prod-1911493506120573 --region cn-beijing --profile aliyun-optima`
 
-**完整脚本**（本地跑、经 buildbox 中转；改 `SERVICE`/`LINES`）:
+**底层（仅参考，正常用 `optima-logs` 即可）**:
+- SLS project：`optima-cn-prod-1911493506120573` / `optima-cn-stage-1911493506120573`（`optima-<env>-<accountId>`）。
+- logstore = service 名；日志正文在 `content` 字段。
 ```bash
-SERVICE=gateway-core; LINES=80
-BBPW=$(op-win read "op://Optima/gdmixcizjci5bvuu3nuvgg4ooe/password")
-declare -A APPID=(
-  [gateway-core]=a08ce23f-3d3e-4d89-a2cf-53c8adba614e
-  [agentic-chat]=6e290c73-a646-43ef-9da5-ad0b2e7eff73
-  [gw-admin]=c6bc5a78-b27f-46e2-825a-eaa338c23645
-  [user-auth]=d6fbf9de-fed6-4165-978f-7b3a0a456acc
-  [user-auth-admin]=54093f99-37bf-4354-abd7-f6e76abdbcb6
-  [optima-scout]=f5bb7e82-e57c-4bd4-83ae-2c25f8d38647
-  [optima-skills]=55a63ee7-fb75-46e4-99f3-20854a699237
-  [infisical]=52b33fc6-b26d-495a-8885-225d38b3d42f )
-AID=${APPID[$SERVICE]}
-sshpass -p "$BBPW" ssh -o StrictHostKeyChecking=no root@47.94.105.163 "bash -s" <<REMOTE | tail -n $LINES
-P="--region cn-beijing --profile aliyun-optima"
-GID=\$(aliyun sae GET /pop/v1/sam/app/describeApplicationGroups --AppId $AID \$P 2>/dev/null | python3 -c "import sys,json;print(json.load(sys.stdin)['Data'][0]['GroupId'])")
-IID=\$(aliyun sae GET /pop/v1/sam/app/describeApplicationInstances --AppId $AID --GroupId \$GID \$P 2>/dev/null | python3 -c "import sys,json;d=json.load(sys.stdin)['Data'];print((d if isinstance(d,list) else d['Instances'])[0]['InstanceId'])")
-aliyun sae DescribeInstanceLog --InstanceId "\$IID" \$P 2>/dev/null | python3 -c "import sys,json;print(json.load(sys.stdin).get('Data',''))"
-REMOTE
+NOW=$(date +%s); FROM=$((NOW-3600))
+aliyun sls GetLogs --project optima-cn-prod-1911493506120573 --logstore gateway-core \
+  --from $FROM --to $NOW --line 100 --reverse true --query error \
+  --region cn-beijing --profile aliyun-optima
 ```
 
-**局限 / 提示**:
-- 只取第 1 个 InstanceId；多副本要遍历 `Data` 里全部 instance。
-- `agent-runtime` 不在 SAE（是 ECI 动态容器）——它的日志看 `gateway-core` 里 `eci-bridge` 的转发/错误行，或单独查对应 ECI。
-- 过滤：把上面输出 `| grep -iE 'error|eci|fail'` 即可（例：排 agentic-chat 链路 ECI 失败就 grep `gateway-core` 日志的 `eci-bridge`）。
-
 ## 完整示例脚本
 
 ### Stage 环境

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/cli.js

@@ -36,7 +36,7 @@ switch (command) {
     log('  optima-generate-test-token [--env production]        Generate test token', 'cyan');
     log('  optima-grant-balance <email> --amount <usd> [--env]  Grant USD wallet balance', 'cyan');
     log('  optima-grant-subscription <email|phone|userId> --plan <p> [--env] Grant subscription', 'cyan');
-    log('  /logs <service> [lines] [env]                        View service logs (skill)', 'cyan');
+    log('  optima-logs <service> [--env] [--since] [--grep] [-n]  View logs (cn=SLS 直连/aws=CloudWatch)', 'cyan');
     log('  /restart-ecs <service> [env]                         Restart ECS service (skill)', 'cyan');
 
     log('\nSupported Services:', 'yellow');

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