@optima-chat/dev-skills 0.9.3 → 0.11.0

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

@@ -1,104 +0,0 @@
----
-name: "grant-balance"
-description: "Use when the user wants to grant credits (bonus, 30-day expiry) to an Optima user — for promotional grants, compensation, referral rewards, etc. $1 = 700 credits via billing API; does not affect subscriptions."
----
-
-# 赠送 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 积分 = ¥7 档积分口径一致）。
-> **cn-stage（阿里云预发）**：同 cn-prod 走 HTTPS（auth.stage.optima.chat / billing-api.stage.optima.chat）；M2M 凭证读 cn Infisical staging，需 `INFISICAL_CN_EMAIL`/`INFISICAL_CN_PASSWORD`。
-
-## 与 grant-subscription 的区别
-
-| | 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

package/bin/helpers/grant-balance.ts

@@ -1,85 +0,0 @@
-#!/usr/bin/env node
-
-// P15 D8b（optima-billing docs/2026-06-11-p15-wallet-sunset-spec.md）：
-// USD 钱包已退役——原「SSH 直写 usd_wallets.granted_balance_micros」作废，
-// 改调 billing 服务态端点（grantCredits → bonus 积分）。
-// ⚠️ 语义变化：旧 wallet granted 无期限；积分 bonus 桶标准 30 天有效期。
-import { randomUUID } from 'crypto';
-import { callBilling, validateEnvCnProd } from './billing-http';
-import { resolveTargetUser } from './grant-subscription';
-
-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|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)
-  --env <env>           Environment: stage, prod, cn-prod, cn-stage (default: stage)
-  -h, --help            Show this help
-
-Examples:
-  optima-grant-balance user@example.com --amount 5 --env prod
-  optima-grant-balance 18898654855 --amount 1 --env cn-prod   # 手机号（cn 用户多为手机号注册）
-  optima-grant-balance user@example.com --amount 1 --env cn-stage  # 阿里云预发`);
-    process.exit(0);
-  }
-
-  const identifier = args[0];
-  let amountUsd = 0;
-  let description: string | null = null;
-  let env = 'stage';
-
-  for (let i = 1; i < args.length; i++) {
-    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]; }
-  }
-
-  if (!Number.isFinite(amountUsd) || amountUsd <= 0) {
-    console.error('--amount is required and must be > 0 (USD)');
-    process.exit(1);
-  }
-  validateEnvCnProd(env);
-
-  return { identifier, amountUsd, description, env };
-}
-
-async function main() {
-  const { identifier, amountUsd, description, env } = parseArgs(process.argv.slice(2));
-
-  console.log(`\n🎁 Granting $${amountUsd.toFixed(2)} (${Math.round(amountUsd * 700)} credits) 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);
-
-  // 幂等键 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,
-      amountUsd,
-      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/dist/bin/helpers/grant-balance.js

@@ -1,79 +0,0 @@
-#!/usr/bin/env node
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-// P15 D8b（optima-billing docs/2026-06-11-p15-wallet-sunset-spec.md）：
-// USD 钱包已退役——原「SSH 直写 usd_wallets.granted_balance_micros」作废，
-// 改调 billing 服务态端点（grantCredits → bonus 积分）。
-// ⚠️ 语义变化：旧 wallet granted 无期限；积分 bonus 桶标准 30 天有效期。
-const crypto_1 = require("crypto");
-const billing_http_1 = require("./billing-http");
-const grant_subscription_1 = require("./grant-subscription");
-function parseArgs(args) {
-    if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
-        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)
-  --env <env>           Environment: stage, prod, cn-prod, cn-stage (default: stage)
-  -h, --help            Show this help
-
-Examples:
-  optima-grant-balance user@example.com --amount 5 --env prod
-  optima-grant-balance 18898654855 --amount 1 --env cn-prod   # 手机号（cn 用户多为手机号注册）
-  optima-grant-balance user@example.com --amount 1 --env cn-stage  # 阿里云预发`);
-        process.exit(0);
-    }
-    const identifier = args[0];
-    let amountUsd = 0;
-    let description = null;
-    let env = 'stage';
-    for (let i = 1; i < args.length; i++) {
-        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];
-        }
-    }
-    if (!Number.isFinite(amountUsd) || amountUsd <= 0) {
-        console.error('--amount is required and must be > 0 (USD)');
-        process.exit(1);
-    }
-    (0, billing_http_1.validateEnvCnProd)(env);
-    return { identifier, amountUsd, description, env };
-}
-async function main() {
-    const { identifier, amountUsd, description, env } = parseArgs(process.argv.slice(2));
-    console.log(`\n🎁 Granting $${amountUsd.toFixed(2)} (${Math.round(amountUsd * 700)} credits) 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);
-    // 幂等键 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,
-        amountUsd,
-        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);
-});