@optima-chat/dev-skills 0.9.3 → 0.11.0

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

@@ -0,0 +1,66 @@
+---
+name: "grant-credits"
+description: "当用户请求赠送积分、发放积分、加积分、grant credits、充值积分、赠送余额（旧称）、奖励、补偿、推荐奖励、运营发放时，使用此技能。支持 Stage、Prod、cn-prod、cn-stage 四个环境；标识符支持邮箱/手机号/userId。"
+allowed-tools: ["Bash"]
+---
+
+# 发放积分（Grant Credits）
+
+为用户赠送积分（**bonus 积分桶，30 天有效期**）。经 billing 服务态端点 `POST /api/billing/admin/grant-credits` 入账，扣费时优先消费。
+
+> **命名历史**：本命令原名 `grant-credits`（按积分）→ 余额时代曾改名 `grant-balance` + 改吃 USD → P15 钱包退役回归积分后改回 `grant-credits` + `--credits` 原生按积分。`optima-grant-balance` 仍作**废弃别名**保留（会打弃用提示）。
+
+## 执行方式：使用 CLI 工具
+
+```bash
+optima-grant-credits <email|phone|userId> --credits <n> [options]
+```
+
+**为什么用 CLI**：自动通过 email/手机号/userId 查 userId（cn 走 HTTP lookup、AWS 走 SSH 隧道）+ 执行前打印 `🎯 目标账号` 反查 + 留审计痕迹（credit_lot，幂等键前缀 `dev-skills-grant:`）+ 不影响订阅和已有积分（纯累加 bonus 桶）。
+
+### 参数
+
+| 参数 | 说明 | 默认 |
+|------|------|------|
+| `<email\|phone\|userId>` | 用户标识（必填；cn 支持手机号/userId） | - |
+| `--credits <n>` | **赠送积分数（整数 ≥1，主单位）** | - |
+| `--amount <usd>` | 备选：按 USD 赠送（$1 = 700 积分）。`--credits` / `--amount` **二选一** | - |
+| `--description <text>` | 描述/原因（存入 credit lot（审计痕迹）） | - |
+| `--env <env>` | stage, prod, cn-prod, cn-stage | stage |
+
+## 快速操作
+
+```bash
+# 送 10000 积分（Prod）
+optima-grant-credits user@example.com --credits 10000 --env prod
+
+# cn-prod 手机号用户送 5000 积分
+optima-grant-credits 18898654855 --credits 5000 --env cn-prod
+
+# 按 USD 送（= 3500 积分），补偿场景
+optima-grant-credits user@example.com --amount 5 --description "服务中断补偿" --env prod
+```
+
+> 单位默认是**积分**。要按美元用 `--amount`（$1=700 积分）。两者只能给一个。
+
+## 适用场景
+奖励/活动、客户补偿、推荐奖励、内部测试账户充值。
+
+## 与 grant-subscription 的区别
+
+| | grant-credits | grant-subscription |
+|---|---|---|
+| 作用 | 追加 bonus 积分（30 天） | 开通/切换订阅计划 |
+| 现有积分 | 不影响（纯累加） | 重置 granted |
+| 现有订阅 | 不影响 | 取消旧的、建新的 |
+| 适用 | 奖励、补偿、推广 | 开会员、升级计划 |
+
+## 安全提醒
+1. **Prod / cn-prod 谨慎**：执行前确认打印的 `🎯 目标账号`（手机/email/userId）与积分数。
+2. **纯追加**：不影响现有积分和订阅；重复执行会叠加。
+3. **30 天有效期**：bonus 桶到期作废。
+
+## 相关命令
+- `optima-grant-subscription` - 开通订阅
+- `optima-account status` - 查用户订阅+权益
+- `optima-query-db` / billing `GET /api/billing/balance` - 核对积分余额

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

@@ -126,5 +126,5 @@ optima-grant-subscription user@example.com --plan starter --env prod
 ## 相关命令
 
 - `optima-grant-subscription` - 开通订阅（主要方式）
-- `optima-grant-balance` - 单独赠送 wallet 余额
+- `optima-grant-credits` - 单独赠送积分
 - `optima-query-db` - 查询数据库验证结果

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

@@ -56,6 +56,6 @@ optima-account unban 18898654855 --env cn-prod
 
 ## 相关命令
 
-- `optima-grant-subscription` / `optima-grant-balance` - 开通会员 / 赠送 credits
+- `optima-grant-subscription` / `optima-grant-credits` - 开通会员 / 赠送积分
 - `optima-entitlement` - 产品权益授予/撤销/查询
 - `optima-query-db` - 直查数据库核对（如 `is_active` / `banned_at`）

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

@@ -52,4 +52,4 @@ optima-entitlement revoke user@example.com --product-key scout-gift --reason "
 ## 相关命令
 
 - `optima-account status` - 查看用户订阅+权益汇总
-- `optima-grant-subscription` / `optima-grant-balance` - 开通会员 / 赠送 credits
+- `optima-grant-subscription` / `optima-grant-credits` - 开通会员 / 赠送积分

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

@@ -0,0 +1,66 @@
+---
+name: "grant-credits"
+description: "当用户请求赠送积分、发放积分、加积分、grant credits、充值积分、赠送余额（旧称）、奖励、补偿、推荐奖励、运营发放时，使用此技能。支持 Stage、Prod、cn-prod、cn-stage 四个环境；标识符支持邮箱/手机号/userId。"
+allowed-tools: ["Bash"]
+---
+
+# 发放积分（Grant Credits）
+
+为用户赠送积分（**bonus 积分桶，30 天有效期**）。经 billing 服务态端点 `POST /api/billing/admin/grant-credits` 入账，扣费时优先消费。
+
+> **命名历史**：本命令原名 `grant-credits`（按积分）→ 余额时代曾改名 `grant-balance` + 改吃 USD → P15 钱包退役回归积分后改回 `grant-credits` + `--credits` 原生按积分。`optima-grant-balance` 仍作**废弃别名**保留（会打弃用提示）。
+
+## 执行方式：使用 CLI 工具
+
+```bash
+optima-grant-credits <email|phone|userId> --credits <n> [options]
+```
+
+**为什么用 CLI**：自动通过 email/手机号/userId 查 userId（cn 走 HTTP lookup、AWS 走 SSH 隧道）+ 执行前打印 `🎯 目标账号` 反查 + 留审计痕迹（credit_lot，幂等键前缀 `dev-skills-grant:`）+ 不影响订阅和已有积分（纯累加 bonus 桶）。
+
+### 参数
+
+| 参数 | 说明 | 默认 |
+|------|------|------|
+| `<email\|phone\|userId>` | 用户标识（必填；cn 支持手机号/userId） | - |
+| `--credits <n>` | **赠送积分数（整数 ≥1，主单位）** | - |
+| `--amount <usd>` | 备选：按 USD 赠送（$1 = 700 积分）。`--credits` / `--amount` **二选一** | - |
+| `--description <text>` | 描述/原因（存入 credit lot（审计痕迹）） | - |
+| `--env <env>` | stage, prod, cn-prod, cn-stage | stage |
+
+## 快速操作
+
+```bash
+# 送 10000 积分（Prod）
+optima-grant-credits user@example.com --credits 10000 --env prod
+
+# cn-prod 手机号用户送 5000 积分
+optima-grant-credits 18898654855 --credits 5000 --env cn-prod
+
+# 按 USD 送（= 3500 积分），补偿场景
+optima-grant-credits user@example.com --amount 5 --description "服务中断补偿" --env prod
+```
+
+> 单位默认是**积分**。要按美元用 `--amount`（$1=700 积分）。两者只能给一个。
+
+## 适用场景
+奖励/活动、客户补偿、推荐奖励、内部测试账户充值。
+
+## 与 grant-subscription 的区别
+
+| | grant-credits | grant-subscription |
+|---|---|---|
+| 作用 | 追加 bonus 积分（30 天） | 开通/切换订阅计划 |
+| 现有积分 | 不影响（纯累加） | 重置 granted |
+| 现有订阅 | 不影响 | 取消旧的、建新的 |
+| 适用 | 奖励、补偿、推广 | 开会员、升级计划 |
+
+## 安全提醒
+1. **Prod / cn-prod 谨慎**：执行前确认打印的 `🎯 目标账号`（手机/email/userId）与积分数。
+2. **纯追加**：不影响现有积分和订阅；重复执行会叠加。
+3. **30 天有效期**：bonus 桶到期作废。
+
+## 相关命令
+- `optima-grant-subscription` - 开通订阅
+- `optima-account status` - 查用户订阅+权益
+- `optima-query-db` / billing `GET /api/billing/balance` - 核对积分余额

package/AGENTS.md

@@ -10,7 +10,7 @@ Prefer the installed CLI tools over reimplementing long shell workflows:
 - `optima-show-env <service> <stage|prod> [options]`
 - `optima-generate-test-token [options]`
 - `optima-grant-subscription <email> [options]`
-- `optima-grant-balance <email> --amount <usd> [options]`
+- `optima-grant-credits <email|phone|userId> --credits <n> [options]`
 - `optima-product <create|update|add-channel|toggle-channel|show> [options]` — manage paid-plugin marketplace Products + Stripe channels (Wave 1.5 admin endpoints; stage default)
 - `optima-entitlement <grant|revoke|list> [options]` — admin-grant / revoke / list paid-plugin entitlements (refuses revoke of PAYMENT / PARTNER source)
 - `optima-plugin <show|set-paid|set-default> [options]` — flip a plugin's skills-side paid/free state (isPaid) + defaultForUser (the user-facing gate; pairs with optima-product for the billing side)
@@ -27,7 +27,7 @@ After `npm install -g @optima-chat/dev-skills`, this package installs skills und
 - `generate-test-token`
 - `read-code`
 - `grant-subscription`
-- `grant-balance`
+- `grant-credits`
 - `restart-ecs`
 - `use-commerce-cli`
 

package/README.md

@@ -106,11 +106,11 @@ Claude:
 | `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-grant-credits` | 赠送积分 | `optima-grant-credits user@example.com --credits 10000 --env prod`（`optima-grant-balance` 为废弃别名）|
 | `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`）。
+> **4 环境 + 标识符**：`grant-subscription` / `grant-credits` / `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

@@ -34,7 +34,7 @@ switch (command) {
     log('  optima-show-env <service> [env]                      Show service env vars', 'cyan');
     log('  optima-verify-health <service> [--env cn|prod|all]   Probe L1-L5 上线健康', 'cyan');
     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-credits <email|phone|userId> --credits <n> [--env] Grant credits (bonus, 30d)', 'cyan');
     log('  optima-grant-subscription <email|phone|userId> --plan <p> [--env] Grant subscription', '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');
@@ -49,7 +49,7 @@ switch (command) {
     log('\nExamples:', 'yellow');
     log('  /logs commerce-backend 100 prod', 'cyan');
     log('  optima-query-db user-auth "SELECT COUNT(*) FROM users" prod', 'cyan');
-    log('  optima-grant-balance user@example.com --amount 5 --env prod', 'cyan');
+    log('  optima-grant-credits user@example.com --credits 10000 --env prod', 'cyan');
 
     log('\nMore Info:', 'yellow');
     log('  optima-dev-skills --version              Show version', 'cyan');

package/bin/helpers/billing-http.ts

@@ -41,7 +41,7 @@ export function validateEnv(env: string): 'stage' | 'prod' {
 /**
  * Variant for commands that support all four envs (stage/prod/cn-prod/cn-stage)
  * because they reach billing / skills / user-auth over HTTPS only — e.g.
- * grant-balance, grant-subscription, entitlement, account, and optima-plugin
+ * grant-credits, grant-subscription, entitlement, account, and optima-plugin
  * (set-paid/set-default/show). Commands that resolve users via the AWS RDS SSH
  * tunnel (which does not exist for cn — Aliyun VPC-internal RDS) stay on
  * validateEnv so a cn typo fails fast instead of dying inside tunnel setup.

package/bin/helpers/grant-credits.ts

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+
+// 发放积分（bonus 积分桶，30 天有效期）。调 billing 服务态端点
+// POST /api/billing/admin/grant-credits（P15 钱包退役后的统一账本）。
+//
+// 历史：本命令原名 grant-credits（按积分），余额时代曾改名 grant-balance + 改吃 USD；
+// P15 钱包退役回归积分后，名字/单位一直没改回 —— 现在改回 grant-credits + --credits
+// 原生按积分发；--amount <usd> 作为按 USD 的兼容入口（$1=700 积分）；
+// optima-grant-balance 作为废弃别名保留。
+import { basename } from 'path';
+import { randomUUID } from 'crypto';
+import { callBilling, validateEnvCnProd } from './billing-http';
+import { resolveTargetUser } from './grant-subscription';
+
+const CREDITS_PER_USD = 700;
+
+interface Parsed {
+  identifier: string;
+  credits: number | null;
+  amountUsd: number | null;
+  description: string | null;
+  env: string;
+}
+
+function parseArgs(args: string[]): Parsed {
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    console.log(`Usage: optima-grant-credits <email|phone|userId> --credits <n> [options]
+
+Grant credits to a user (bonus bucket, expires in 30 days).
+Used for promotional grants, compensation, referral rewards, etc.
+
+Target user: <email|phone|userId> (positional). phone/userId only on
+cn-prod / cn-stage; AWS stage/prod resolve email only.
+
+Options:
+  --credits <n>         Credits to grant (integer >= 1). Primary unit.
+  --amount <usd>        Alt: grant by USD ($1 = ${CREDITS_PER_USD} credits). Provide exactly one of --credits / --amount.
+  --description <text>  Description for audit trail (optional)
+  --env <env>           Environment: stage, prod, cn-prod, cn-stage (default: stage)
+  -h, --help            Show this help
+
+Examples:
+  optima-grant-credits user@example.com --credits 10000 --env prod
+  optima-grant-credits 18898654855 --credits 5000 --env cn-prod   # 手机号（cn 用户多为手机号注册）
+  optima-grant-credits user@example.com --amount 5 --env prod     # 按 USD（= 3500 积分）`);
+    process.exit(0);
+  }
+
+  const identifier = args[0];
+  let credits: number | null = null;
+  let amountUsd: number | null = null;
+  let description: string | null = null;
+  let env = 'stage';
+
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === '--credits' && args[i + 1]) { credits = parseInt(args[++i], 10); }
+    else if (args[i] === '--amount' && args[i + 1]) { amountUsd = parseFloat(args[++i]); }
+    else if (args[i] === '--description' && args[i + 1]) { description = args[++i]; }
+    else if (args[i] === '--env' && args[i + 1]) { env = args[++i]; }
+  }
+
+  // Exactly one of --credits / --amount (mirrors billing endpoint's oneOf).
+  if ((credits !== null) === (amountUsd !== null)) {
+    console.error('提供且只能提供 --credits <n> 或 --amount <usd> 之一');
+    process.exit(1);
+  }
+  if (credits !== null && (!Number.isInteger(credits) || credits < 1)) {
+    console.error('--credits 必须是 >= 1 的整数');
+    process.exit(1);
+  }
+  if (amountUsd !== null && (!Number.isFinite(amountUsd) || amountUsd <= 0)) {
+    console.error('--amount 必须 > 0 (USD)');
+    process.exit(1);
+  }
+  validateEnvCnProd(env);
+
+  return { identifier, credits, amountUsd, description, env };
+}
+
+async function main() {
+  // Deprecation notice when invoked via the legacy alias `optima-grant-balance`.
+  if (basename(process.argv[1] || '').includes('grant-balance')) {
+    console.warn('⚠️  optima-grant-balance 已更名为 optima-grant-credits（P15 钱包退役后回归积分）。请改用 `optima-grant-credits --credits <n>`；本别名仍可用，后续弃用。\n');
+  }
+
+  const { identifier, credits, amountUsd, description, env } = parseArgs(process.argv.slice(2));
+
+  const creditsDisplay = credits ?? Math.round((amountUsd as number) * CREDITS_PER_USD);
+  console.log(`\n🎁 Granting ${creditsDisplay} credits${amountUsd !== null ? ` ($${amountUsd.toFixed(2)})` : ''} to ${identifier} [${env.toUpperCase()}]\n`);
+  if (description) console.log(`   Reason: ${description}`);
+
+  // 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);
+
+  // amountCredits（原生积分）与 amountUsd（USD 折算）二选一，对应 billing 端点的 oneOf。
+  const amountField = credits !== null ? { amountCredits: credits } : { amountUsd };
+
+  // 幂等键 per-invocation 生成、callBilling 的 5xx retry 复用同 body —— 「已
+  // commit 但响应 5xx」场景重试不双发（billing spec R2-M3）。
+  const { body } = await callBilling<{ success: boolean; lotId: string; credits: number }>(
+    env, 'POST', '/api/billing/admin/grant-credits',
+    {
+      userId,
+      ...amountField,
+      description: description ?? undefined,
+      idempotencyKey: `dev-skills-grant:${randomUUID()}`,
+    },
+  );
+
+  console.log(`✓ Granted ${body.credits} credits (lot ${body.lotId})`);
+  console.log(`\n✅ Done! ${identifier} received ${body.credits} bonus credits (expires in 30 days)\n`);
+}
+
+main().catch(error => {
+  console.error('\n❌ Error:', error.message);
+  process.exit(1);
+});

package/bin/helpers/grant-subscription.ts

@@ -119,7 +119,7 @@ Options:
 /**
  * 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
+ * grant-credits, 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

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

@@ -49,7 +49,7 @@ function validateEnv(env) {
 /**
  * Variant for commands that support all four envs (stage/prod/cn-prod/cn-stage)
  * because they reach billing / skills / user-auth over HTTPS only — e.g.
- * grant-balance, grant-subscription, entitlement, account, and optima-plugin
+ * grant-credits, grant-subscription, entitlement, account, and optima-plugin
  * (set-paid/set-default/show). Commands that resolve users via the AWS RDS SSH
  * tunnel (which does not exist for cn — Aliyun VPC-internal RDS) stay on
  * validateEnv so a cn typo fails fast instead of dying inside tunnel setup.

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

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// 发放积分（bonus 积分桶，30 天有效期）。调 billing 服务态端点
+// POST /api/billing/admin/grant-credits（P15 钱包退役后的统一账本）。
+//
+// 历史：本命令原名 grant-credits（按积分），余额时代曾改名 grant-balance + 改吃 USD；
+// P15 钱包退役回归积分后，名字/单位一直没改回 —— 现在改回 grant-credits + --credits
+// 原生按积分发；--amount <usd> 作为按 USD 的兼容入口（$1=700 积分）；
+// optima-grant-balance 作为废弃别名保留。
+const path_1 = require("path");
+const crypto_1 = require("crypto");
+const billing_http_1 = require("./billing-http");
+const grant_subscription_1 = require("./grant-subscription");
+const CREDITS_PER_USD = 700;
+function parseArgs(args) {
+    if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+        console.log(`Usage: optima-grant-credits <email|phone|userId> --credits <n> [options]
+
+Grant credits to a user (bonus bucket, expires in 30 days).
+Used for promotional grants, compensation, referral rewards, etc.
+
+Target user: <email|phone|userId> (positional). phone/userId only on
+cn-prod / cn-stage; AWS stage/prod resolve email only.
+
+Options:
+  --credits <n>         Credits to grant (integer >= 1). Primary unit.
+  --amount <usd>        Alt: grant by USD ($1 = ${CREDITS_PER_USD} credits). Provide exactly one of --credits / --amount.
+  --description <text>  Description for audit trail (optional)
+  --env <env>           Environment: stage, prod, cn-prod, cn-stage (default: stage)
+  -h, --help            Show this help
+
+Examples:
+  optima-grant-credits user@example.com --credits 10000 --env prod
+  optima-grant-credits 18898654855 --credits 5000 --env cn-prod   # 手机号（cn 用户多为手机号注册）
+  optima-grant-credits user@example.com --amount 5 --env prod     # 按 USD（= 3500 积分）`);
+        process.exit(0);
+    }
+    const identifier = args[0];
+    let credits = null;
+    let amountUsd = null;
+    let description = null;
+    let env = 'stage';
+    for (let i = 1; i < args.length; i++) {
+        if (args[i] === '--credits' && args[i + 1]) {
+            credits = parseInt(args[++i], 10);
+        }
+        else if (args[i] === '--amount' && args[i + 1]) {
+            amountUsd = parseFloat(args[++i]);
+        }
+        else if (args[i] === '--description' && args[i + 1]) {
+            description = args[++i];
+        }
+        else if (args[i] === '--env' && args[i + 1]) {
+            env = args[++i];
+        }
+    }
+    // Exactly one of --credits / --amount (mirrors billing endpoint's oneOf).
+    if ((credits !== null) === (amountUsd !== null)) {
+        console.error('提供且只能提供 --credits <n> 或 --amount <usd> 之一');
+        process.exit(1);
+    }
+    if (credits !== null && (!Number.isInteger(credits) || credits < 1)) {
+        console.error('--credits 必须是 >= 1 的整数');
+        process.exit(1);
+    }
+    if (amountUsd !== null && (!Number.isFinite(amountUsd) || amountUsd <= 0)) {
+        console.error('--amount 必须 > 0 (USD)');
+        process.exit(1);
+    }
+    (0, billing_http_1.validateEnvCnProd)(env);
+    return { identifier, credits, amountUsd, description, env };
+}
+async function main() {
+    // Deprecation notice when invoked via the legacy alias `optima-grant-balance`.
+    if ((0, path_1.basename)(process.argv[1] || '').includes('grant-balance')) {
+        console.warn('⚠️  optima-grant-balance 已更名为 optima-grant-credits（P15 钱包退役后回归积分）。请改用 `optima-grant-credits --credits <n>`；本别名仍可用，后续弃用。\n');
+    }
+    const { identifier, credits, amountUsd, description, env } = parseArgs(process.argv.slice(2));
+    const creditsDisplay = credits ?? Math.round(amountUsd * CREDITS_PER_USD);
+    console.log(`\n🎁 Granting ${creditsDisplay} credits${amountUsd !== null ? ` ($${amountUsd.toFixed(2)})` : ''} to ${identifier} [${env.toUpperCase()}]\n`);
+    if (description)
+        console.log(`   Reason: ${description}`);
+    // 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 (0, grant_subscription_1.resolveTargetUser)(env, identifier);
+    // amountCredits（原生积分）与 amountUsd（USD 折算）二选一，对应 billing 端点的 oneOf。
+    const amountField = credits !== null ? { amountCredits: credits } : { amountUsd };
+    // 幂等键 per-invocation 生成、callBilling 的 5xx retry 复用同 body —— 「已
+    // commit 但响应 5xx」场景重试不双发（billing spec R2-M3）。
+    const { body } = await (0, billing_http_1.callBilling)(env, 'POST', '/api/billing/admin/grant-credits', {
+        userId,
+        ...amountField,
+        description: description ?? undefined,
+        idempotencyKey: `dev-skills-grant:${(0, crypto_1.randomUUID)()}`,
+    });
+    console.log(`✓ Granted ${body.credits} credits (lot ${body.lotId})`);
+    console.log(`\n✅ Done! ${identifier} received ${body.credits} bonus credits (expires in 30 days)\n`);
+}
+main().catch(error => {
+    console.error('\n❌ Error:', error.message);
+    process.exit(1);
+});

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

@@ -117,7 +117,7 @@ Options:
 /**
  * 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
+ * grant-credits, 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optima-chat/dev-skills",
-  "version": "0.9.3",
+  "version": "0.11.0",
   "description": "Claude Code Skills for Optima development team - cross-environment collaboration tools",
   "main": "index.js",
   "bin": {
@@ -8,7 +8,8 @@
     "optima-account": "dist/bin/helpers/account.js",
     "optima-entitlement": "dist/bin/helpers/entitlement.js",
     "optima-generate-test-token": "dist/bin/helpers/generate-test-token.js",
-    "optima-grant-balance": "dist/bin/helpers/grant-balance.js",
+    "optima-grant-credits": "dist/bin/helpers/grant-credits.js",
+    "optima-grant-balance": "dist/bin/helpers/grant-credits.js",
     "optima-grant-subscription": "dist/bin/helpers/grant-subscription.js",
     "optima-logs": "dist/bin/helpers/logs.js",
     "optima-plugin": "dist/bin/helpers/plugin.js",

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

@@ -1,106 +0,0 @@
----
-name: "grant-balance"
-description: "当用户请求赠送余额、充值 USD 余额、grant balance、加余额、奖励、补偿、推荐奖励、运营发放时，使用此技能。支持 Stage、Prod、cn-prod、cn-stage 四个环境。"
-allowed-tools: ["Bash"]
----
-
-# 赠送 USD 余额（Grant Balance）
-
-当你需要为用户赠送 wallet USD 余额时，使用这个场景。金额按 $1=700 积分换算，经 billing API 入 **bonus 积分桶（30 天有效期）**（P15 钱包退役后语义），billing 服务在扣费时会优先消费 granted balance。
-
-## 执行方式：使用 CLI 工具
-
-```bash
-optima-grant-balance <email|phone|userId> --amount <usd> [options]
-```
-
-**为什么使用 CLI 工具**：
-- 自动通过 email/手机号/userId 查找 userId（cn 用户多为手机号；执行前打印 🎯 目标账号反查）
-- 自动处理 SSH 隧道和数据库连接
-- 不会影响现有订阅和已有余额（发放 bonus 积分（30 天有效期，重复执行会叠加发放））
-- 自动留审计痕迹（credit_lot 行，幂等键前缀 `dev-skills-grant:`）
-
-## 适用情况
-
-- 奖励额外余额（推广、活动）
-- 客户补偿（服务中断等）
-- 推荐奖励
-- 内部测试账户充值
-
-## 快速操作
-
-```bash
-# 赠送 $5（Stage 环境，默认）
-optima-grant-balance user@example.com --amount 5
-
-# 赠送 $10 到 Prod
-optima-grant-balance user@example.com --amount 10 --env prod
-
-# 带描述（Reason 仅在 console 输出，不存 DB）
-optima-grant-balance user@example.com --amount 20 --description "服务中断补偿" --env prod
-```
-
-> **单位是美元（USD）**。`--amount 5` 即赠送 $5.00 到 granted balance。
-> 数据库底层用 micro-USD 精度（1 USD = 700 积分（P15 统一账本口径）
-
-### 参数说明
-
-| 参数 | 说明 | 默认值 |
-|------|------|--------|
-| `<email|phone|userId>` | 用户标识（必填；cn 支持手机号/userId） | - |
-| `--amount <usd>` | USD 金额（必填，> 0） | - |
-| `--description <text>` | 描述/原因（仅 console 输出） | - |
-| `--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 的区别
-
-| | grant-balance | grant-subscription |
-|---|---|---|
-| 作用 | 追加 USD granted balance | 开通/切换订阅计划 |
-| 现有余额 | 不影响（纯累加） | 重置 granted balance |
-| 现有订阅 | 不影响 | 取消旧的，创建新的 |
-| Token quota | 不影响 | 按计划更新 |
-| 适用场景 | 奖励、补偿、推广 | 开通会员、升级计划 |
-
-## 常见使用场景
-
-### 场景 1：客户补偿
-
-**用户请求**："服务出了问题，给 xxx@gmail.com 补偿 $5"
-
-```bash
-optima-grant-balance xxx@gmail.com --amount 5 --description "Service outage compensation" --env prod
-```
-
-### 场景 2：推荐奖励
-
-**用户请求**："xxx 推荐了新用户，奖励 $3"
-
-```bash
-optima-grant-balance xxx@gmail.com --amount 3 --description "Referral reward" --env prod
-```
-
-### 场景 3：运营发放
-
-**用户请求**："给 xxx@gmail.com 充 $20 测试余额"
-
-```bash
-optima-grant-balance xxx@gmail.com --amount 20 --env stage
-```
-
-## 安全提醒
-
-1. **Stage 优先**：默认操作 Stage 环境
-2. **Prod 谨慎**：操作 Prod 前确认邮箱和金额
-3. **纯追加**：不会影响现有余额和订阅（累加到 granted balance）
-4. **Audit trail**：每次赠送对应一个 credit_lot（幂等键前缀 `dev-skills-grant:`，type=bonus）
-
-## 相关命令
-
-- `optima-grant-balance` - 赠送 USD 余额（主要方式）
-- `optima-grant-subscription` - 开通订阅计划
-- `optima-query-db` - 查询数据库验证结果（`GET /api/billing/balance（credits.byType.bonus）或 query-db credit_lot