@optima-chat/dev-skills 0.7.29 → 0.7.31

package/.claude/commands/trace-user.md

@@ -0,0 +1,293 @@
+# /trace-user - 用户链路追踪
+
+查看指定用户在 agentic-chat -> optima-gateway -> agent-runtime 全链路的日志，分析耗时、成功/失败、返回值等。
+
+**版本**: v0.1.0
+
+## 使用场景
+
+**前端开发者**: 用户反馈 "聊天没反应"，快速定位是前端、网关还是 Agent 的问题
+**后端开发者**: 追踪特定用户的请求链路，分析 LLM 调用耗时和工具执行
+**DevOps**: 排查线上用户问题，查看完整的跨服务日志关联
+
+## 用法
+
+```
+/trace-user <user-id-or-email> [environment] [time-range] [options]
+```
+
+## 参数
+
+- `user-id-or-email` (必需): 用户标识
+  - 包含 `@` → email（用 `userEmail` 字段过滤）
+  - UUID 格式 → userId（用 `userId` 字段过滤）
+- `environment` (可选): `stage` 或 `prod`，默认 `stage`
+- `time-range` (可选): 如 `10m`, `30m`, `1h`, `2h`, `1d`，默认 `30m`
+- 选项:
+  - `--errors` — 只看 error/warn 级别
+  - `--session SESSION_ID` — 限定某个 session
+  - `--trace TRACE_ID` — 限定某个 traceId
+  - `--raw` — 显示原始 JSON
+
+## 示例
+
+```bash
+/trace-user alice@example.com                    # Stage，最近 30 分钟
+/trace-user 37c03a9f-0b47-409c-81a3-5634eaab1a6c prod 2h  # Prod，最近 2 小时
+/trace-user alice@example.com --errors           # 只看错误
+/trace-user alice@example.com --session sess-xxx # 指定 session
+```
+
+如果用户输入 `/trace-user` 或 `/trace-user --help`，显示此帮助文档，不执行查询。
+
+ARGUMENTS: $ARGUMENTS
+
+## Claude Code 执行步骤
+
+### 1. 解析参数
+
+从 `$ARGUMENTS` 中解析用户标识、环境、时间范围和选项。
+
+**用户标识判断**:
+- 包含 `@` → email → 使用 `userEmail` 字段
+- UUID 格式（`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`）→ 使用 `userId` 字段
+- 其他 → 当作 userId 尝试
+
+### 2. 日志组映射
+
+三层服务对应的 CloudWatch Log Group：
+
+| 层 | 服务 | Stage 日志组 | Prod 日志组 |
+|----|------|-------------|------------|
+| L1 | agentic-chat | `/ecs/agentic-chat-stage` | `/ecs/agentic-chat-prod` |
+| L2 | gateway-core | `/ecs/gateway-core-stage` | `/ecs/gateway-core-prod` |
+| L3 | agent-runtime | `/ecs/gw-agent-runtime-stage` | `/ecs/gw-agent-runtime-prod` |
+
+**AWS 区域**: `ap-southeast-1`
+
+### 3. 搜索策略
+
+#### 第一步：在 gateway-core 找到用户的 session
+
+```bash
+# 按 email 搜索
+aws logs filter-log-events \
+  --log-group-name /ecs/gateway-core-{ENV} \
+  --filter-pattern '{ $.userEmail = "USER_EMAIL" }' \
+  --start-time $(date -d 'TIME_RANGE ago' +%s)000 \
+  --region ap-southeast-1 \
+  --output json | head -100
+
+# 按 userId 搜索
+aws logs filter-log-events \
+  --log-group-name /ecs/gateway-core-{ENV} \
+  --filter-pattern '{ $.userId = "USER_ID" }' \
+  --start-time $(date -d 'TIME_RANGE ago' +%s)000 \
+  --region ap-southeast-1 \
+  --output json | head -100
+```
+
+从结果中提取 `sessionId` 和 `traceId`。
+
+#### 第二步：跨服务关联查询（Logs Insights）
+
+优先使用 CloudWatch Logs Insights 跨多个 log group 查询：
+
+```bash
+# 按 userId/email 跨服务查询
+aws logs start-query \
+  --log-group-names \
+    /ecs/gateway-core-{ENV} \
+    /ecs/gw-agent-runtime-{ENV} \
+  --start-time $(date -d 'TIME_RANGE ago' +%s) \
+  --end-time $(date +%s) \
+  --query-string '
+    fields @timestamp, @logStream, @message
+    | filter userId = "USER_ID" or userEmail = "USER_EMAIL"
+    | sort @timestamp asc
+    | limit 500
+  ' \
+  --region ap-southeast-1
+
+# 等几秒后获取结果
+aws logs get-query-results --query-id QUERY_ID --region ap-southeast-1
+```
+
+如果已知 sessionId：
+
+```bash
+aws logs start-query \
+  --log-group-names \
+    /ecs/gateway-core-{ENV} \
+    /ecs/gw-agent-runtime-{ENV} \
+  --start-time $(date -d 'TIME_RANGE ago' +%s) \
+  --end-time $(date +%s) \
+  --query-string '
+    fields @timestamp, @logStream, level, message, sessionId, traceId, duration_ms
+    | filter sessionId = "SESSION_ID"
+    | sort @timestamp asc
+    | limit 500
+  ' \
+  --region ap-southeast-1
+```
+
+#### 第三步：agentic-chat 日志（补充）
+
+agentic-chat 前端日志可能不含 userId/sessionId 字段，用时间窗口 + 关键词辅助：
+
+```bash
+aws logs tail /ecs/agentic-chat-{ENV} --since {TIME_RANGE} \
+  --region ap-southeast-1 | grep -i "USER_EMAIL_OR_ID"
+```
+
+#### 第四步：只看错误（--errors）
+
+```bash
+aws logs start-query \
+  --log-group-names \
+    /ecs/gateway-core-{ENV} \
+    /ecs/gw-agent-runtime-{ENV} \
+  --start-time $(date -d 'TIME_RANGE ago' +%s) \
+  --end-time $(date +%s) \
+  --query-string '
+    fields @timestamp, @logStream, level, message, sessionId, error
+    | filter (userId = "USER_ID" or userEmail = "USER_EMAIL")
+      and (level = "error" or level = "warn")
+    | sort @timestamp asc
+    | limit 200
+  ' \
+  --region ap-southeast-1
+```
+
+### 4. 结构化日志字段参考
+
+optima-gateway 的日志通过 AsyncLocalStorage 自动注入：
+
+```json
+{
+  "timestamp": "2026-04-16T10:30:00.000Z",
+  "level": "info",
+  "service": "gateway-core",
+  "userId": "37c03a9f-...",
+  "userEmail": "alice@example.com",
+  "sessionId": "sess-xxx",
+  "traceId": "gw-abc123",
+  "message": "Session created",
+  "duration_ms": 123
+}
+```
+
+**关键字段**:
+- `userId` / `userEmail` — 用户标识
+- `sessionId` — 会话 ID
+- `traceId` — 跨服务链路 ID
+- `duration_ms` — 操作耗时
+- `level` — 日志级别（info/warn/error）
+
+### 5. 输出格式
+
+#### A. 概览信息
+
+```
+用户: alice@example.com (37c03a9f-...)
+环境: Stage
+时间范围: 最近 30 分钟
+找到 session 数: 3
+```
+
+#### B. Session 列表
+
+| Session ID | 创建时间 | 状态 | 持续时间 | 消息数 | 错误数 |
+|-----------|---------|------|---------|-------|-------|
+| sess-001 | 10:30:00 | running | 5m | 12 | 0 |
+| sess-002 | 10:20:00 | terminated | 8m | 24 | 1 |
+
+#### C. 请求链路时间线
+
+```
+Session: sess-001
+TraceId: gw-abc123
+
+时间线：
+┌──────────────────────────────────────────────────────────────────────┐
+│ 10:30:00.000 [gateway-core]   WS connected, authenticating...       │
+│ 10:30:00.150 [gateway-core]   OIDC verified, userId=37c03a9f       │ +150ms
+│ 10:30:00.200 [gateway-core]   Session creating                      │ +50ms
+│ 10:30:00.800 [gateway-core]   Agent task started (ECS RunTask)      │ +600ms
+│ 10:30:03.200 [agent-runtime]  Container ready, WS connected         │ +2400ms
+│ 10:30:03.250 [gateway-core]   Session running                       │ +50ms
+│ 10:30:05.000 [gateway-core]   Client message received               │
+│ 10:30:05.100 [agent-runtime]  LLM request started (openai)          │ +100ms
+│ 10:30:08.500 [agent-runtime]  LLM response complete                 │ +3400ms
+│ 10:30:08.600 [agent-runtime]  Tool call: read_file                  │
+│ 10:30:08.800 [agent-runtime]  Tool result returned                  │ +200ms
+│ 10:30:09.000 [gateway-core]   Message forwarded to client           │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+#### D. 耗时分析
+
+```
+关键耗时:
+  OIDC 认证:         150ms
+  Session 创建:       50ms
+  ECS 容器启动:     2400ms  (>2s 时标记 warning)
+  WS 回连:            50ms
+  首次 LLM 调用:    3400ms
+  工具执行:          200ms
+
+统计:
+  总消息数: 12 (user: 5, assistant: 7)
+  LLM 调用次数: 7
+  平均 LLM 延迟: 2800ms
+  工具调用次数: 3
+```
+
+#### E. 错误/告警
+
+```
+发现 1 个错误:
+  10:35:12 [agent-runtime] ERROR: LLM request failed
+    provider: openai
+    error: "rate_limit_exceeded"
+    sessionId: sess-002
+    → 已自动重试（CircuitBreaker half-open）
+```
+
+### 6. 常用诊断场景
+
+| 用户报告 | 推荐策略 |
+|---------|---------|
+| "连不上" / "打不开" | 查 gateway-core 连接日志 + OIDC 认证 |
+| "没反应" / "卡住了" | 查 agent-runtime 是否收到消息 + LLM 是否响应 |
+| "回复慢" | 查 duration_ms 字段，分析 ECS 启动 + LLM 延迟 |
+| "出错了" / "报错" | `--errors` 模式，重点看 error 级别 |
+| "用了一半断了" | 查 WS 断连事件 + session 状态变化 |
+| "总是失败" | 查 CircuitBreaker 状态 + provider 切换日志 |
+
+### 7. 快捷跟进命令
+
+```bash
+# 查看服务健康状态
+curl -s https://gw.stage.optima.onl/health | jq .
+curl -s https://ai.stage.optima.onl/api/health | jq .
+
+# 查看服务 debug 信息
+curl -s -H "X-Debug-Key: 7eede5747b6c50f1c8f2358b98462f74696cdef9bfeab85eaf7ea41166788b5c" \
+  https://gw.stage.optima.onl/debug/info | jq .
+
+# 查看 ECS 服务状态
+aws ecs describe-services --cluster optima-stage-cluster \
+  --services gateway-core-stage --region ap-southeast-1 \
+  --query 'services[0].{status:status,running:runningCount,desired:desiredCount}'
+```
+
+## 注意事项
+
+1. **CloudWatch 延迟**: 最新日志可能需要等 10-30 秒才出现
+2. **速率限制**: `filter-log-events` 有限流，大范围查询优先用 `start-query` (Logs Insights)
+3. **日志保留**: CloudWatch 保留 14 天
+4. **结构化日志**: JSON 日志输出到 stderr，在 CloudWatch 中显示为普通文本行
+5. **Insights 限制**: 最多返回 10000 条，一般够用
+6. **权限要求**: 需要 AWS CLI 配置了正确的凭证（`ap-southeast-1` 区域）
+7. 如果用户没有任何日志，可能是该用户在指定时间范围内没有活动、标识输入有误、或服务未部署

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

@@ -1,12 +1,12 @@
 ---
 name: "grant-credits"
-description: "当用户请求赠送 credits、充值积分、grant credits、加 credits、奖励积分、补偿 credits、推荐奖励时，使用此技能。支持 Stage、Prod 两个环境。"
+description: "当用户请求赠送 credits、充值余额、grant credits、加余额、奖励积分、补偿、推荐奖励时，使用此技能。支持 Stage、Prod 两个环境。"
 allowed-tools: ["Bash"]
 ---
 
-# 赠送 Credits
+# 赠送余额（Grant Credits）
 
-当你需要为用户赠送额外 credits 时，使用这个场景。
+当你需要为用户赠送额外 wallet 余额时，使用这个场景。赠送的额度会加到 `usd_wallets.granted_balance_micros`。
 
 ## 执行方式：使用 CLI 工具
 
@@ -19,38 +19,40 @@ optima-grant-credits <email> --amount <n> [options]
 **为什么使用 CLI 工具**：
 - 自动通过 email 查找 userId（跨 user-auth 数据库）
 - 自动处理 SSH 隧道和数据库连接
-- 不会影响现有订阅和 credits（纯追加）
+- 不会影响现有订阅和已有余额（纯追加到 granted balance）
 - 一条命令完成操作
 
 ## 适用情况
 
-- 赠送额外 credits（奖励、补偿、推广等）
-- 推荐奖励 credits
-- 运营活动发放 credits
+- 赠送额外余额（奖励、补偿、推广等）
+- 推荐奖励
+- 运营活动发放
 - 客户补偿
 
 ## 快速操作
 
 ```bash
-# 赠送 100 bonus credits，Stage 环境（默认）
+# 赠送 100 credits ($1.00)，Stage 环境（默认）
 optima-grant-credits user@example.com --amount 100
 
-# 赠送 500 bonus credits，Prod 环境
+# 赠送 500 credits ($5.00)，Prod 环境
 optima-grant-credits user@example.com --amount 500 --env prod
 
-# 推荐奖励 credits
+# 推荐奖励
 optima-grant-credits user@example.com --amount 200 --type referral --env prod
 
 # 自定义描述
 optima-grant-credits user@example.com --amount 300 --description "客户补偿 - 服务中断" --env prod
 ```
 
+> 1 credit = $0.01 = 10,000 micros。--amount 500 即赠送 $5.00 到 granted balance。
+
 ### 参数说明
 
 | 参数 | 说明 | 默认值 |
 |------|------|--------|
 | `<email>` | 用户邮箱（必填） | - |
-| `--amount <n>` | Credits 数量（必填，>=1） | - |
+| `--amount <n>` | Credits 数量（必填，>=1，1 credit = $0.01） | - |
 | `--type <type>` | 类型：bonus, referral | bonus |
 | `--description <text>` | 描述（可选） | Auto-generated |
 | `--env <env>` | 环境：stage, prod | stage |
@@ -59,15 +61,15 @@ optima-grant-credits user@example.com --amount 300 --description "客户补偿 -
 
 | | grant-credits | grant-subscription |
 |---|---|---|
-| 作用 | 追加 credits | 开通/切换订阅计划 |
-| 现有 credits | 不影响 | 清零后重新授予 |
+| 作用 | 追加 granted balance | 开通/切换订阅计划 |
+| 现有余额 | 不影响（纯累加） | 重置 granted balance |
 | 现有订阅 | 不影响 | 取消旧的，创建新的 |
 | Token quota | 不影响 | 按计划更新 |
 | 适用场景 | 奖励、补偿、推广 | 开通会员、升级计划 |
 
 ## 常见使用场景
 
-### 场景 1：奖励 credits
+### 场景 1：奖励余额
 
 **用户请求**："给 xxx@gmail.com 加 200 credits"
 
@@ -85,7 +87,7 @@ optima-grant-credits xxx@gmail.com --amount 300 --type referral --env prod
 
 ### 场景 3：客户补偿
 
-**用户请求**："服务出了问题，补偿 xxx 500 credits"
+**用户请求**："服务出了问题，补偿 xxx $5"
 
 ```bash
 optima-grant-credits xxx@gmail.com --amount 500 --description "服务中断补偿" --env prod
@@ -95,11 +97,11 @@ optima-grant-credits xxx@gmail.com --amount 500 --description "服务中断补
 
 1. **Stage 优先**：默认操作 Stage 环境
 2. **Prod 谨慎**：操作 Prod 前确认邮箱和数量
-3. **纯追加**：不会影响现有 credits 和订阅
-4. **无过期**：bonus/referral credits 默认不设过期时间
+3. **纯追加**：不会影响现有余额和订阅（累加到 granted balance）
+4. **无过期**：granted balance 不会自动过期
 
 ## 相关命令
 
-- `optima-grant-credits` - 赠送 credits（主要方式）
+- `optima-grant-credits` - 赠送余额（主要方式）
 - `optima-grant-subscription` - 开通订阅计划
 - `optima-query-db` - 查询数据库验证结果

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

@@ -19,8 +19,8 @@ optima-grant-subscription <email> [options]
 **为什么使用 CLI 工具**：
 - 自动通过 email 查找 userId（跨 user-auth 数据库）
 - 自动处理 SSH 隧道和数据库连接
-- 自动取消旧订阅、清零旧 credits
-- 自动按 plan 配置授予 credits 和 token quota
+- 自动取消旧订阅、重置 wallet granted balance
+- 自动按 plan 配置授予 USD wallet 余额和 token quota
 - 一条命令完成所有操作
 
 ## 适用情况
@@ -59,12 +59,14 @@ optima-grant-subscription user@example.com --plan enterprise --env prod
 
 ### 计划配置
 
-| Plan | Credits/月 | Session Token | Weekly Token |
-|------|-----------|---------------|--------------|
-| trial | 20 | 400K | 1M |
-| starter | 500 | 2M | 10M |
-| pro | 2,000 | 8M | 40M |
-| enterprise | 10,000 | 16M | 80M |
+| Plan | 月授予额 (USD) | Credits 等价 | Session Token | Weekly Token |
+|------|---------------|-------------|---------------|--------------|
+| trial | $0.20 | 20 | 400K | 1M |
+| starter | $5.00 | 500 | 2M | 10M |
+| pro | $20.00 | 2,000 | 8M | 40M |
+| enterprise | $100.00 | 10,000 | 16M | 80M |
+
+> 1 credit = $0.01 = 10,000 micros。授予额存入 `usd_wallets.granted_balance_micros`。
 
 ## 常见使用场景
 
@@ -97,22 +99,22 @@ optima-grant-subscription user@example.com --plan starter --env prod
 工具会自动完成以下步骤：
 
 1. 通过 email 在 user-auth 数据库查找 userId
-2. 加载对应 plan 的配置（credits、token 限额等）
+2. 加载对应 plan 的配置（月授予额、token 限额等）
 3. 取消该用户的所有活跃订阅
-4. 清零旧的 credits
-5. 创建新订阅（设置到期时间）
-6. 授予对应 credits
+4. 创建新订阅（设置到期时间）
+5. 重置 wallet granted balance 并授予新额度
+6. 记录 topup 审计记录（source: subscription_grant）
 7. 更新 token quota 限额
 
 ## 安全提醒
 
 1. **Stage 优先**：默认操作 Stage 环境
 2. **Prod 谨慎**：操作 Prod 前确认用户邮箱正确
-3. **不可逆**：旧订阅和 credits 会被清除
+3. **不可逆**：旧订阅会被取消，granted balance 会被重置
 4. **确认 email**：执行前务必确认邮箱地址无误
 
 ## 相关命令
 
 - `optima-grant-subscription` - 开通订阅（主要方式）
-- `optima-grant-credits` - 单独赠送 credits
+- `optima-grant-credits` - 单独赠送 wallet 余额
 - `optima-query-db` - 查询数据库验证结果

package/.claude/skills/query-db/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "query-db"
-description: "当用户请求查询数据库、执行SQL、查看数据、统计数据、检查数据库、查询表、数据库查询时，使用此技能。支持 CI、Stage、Prod 三个环境的 commerce-backend、user-auth、agentic-chat、bi-backend、session-gateway、ads-backend、amazon-backend、shopify-backend、optima-sentinel 等服务的数据库查询。优先使用 optima-query-db CLI 工具。"
+description: "当用户请求查询数据库、执行SQL、查看数据、统计数据、检查数据库、查询表、数据库查询时，使用此技能。支持 CI、Stage、Prod 三个环境的 commerce-backend、user-auth、agentic-chat、bi-backend、session-gateway、gateway-core、ads-backend、amazon-backend、shopify-backend、optima-sentinel 等服务的数据库查询。优先使用 optima-query-db CLI 工具。"
 allowed-tools: ["Bash", "SlashCommand"]
 ---
 
@@ -75,7 +75,8 @@ optima-query-db commerce-backend "SELECT status, COUNT(*) FROM orders GROUP BY s
 - `user-auth` - 用户认证数据库
 - `agentic-chat` - AI 聊天数据库
 - `bi-backend` - BI 后端数据库
-- `session-gateway` - AI Shell 网关数据库
+- `session-gateway` - AI Shell 网关数据库（老）
+- `gateway-core` - Optima Gateway (`optima_gateway`) 数据库 — sessions / conversations / messages / transcripts / credits
 - `optima-logistics` - 物流服务数据库
 - `ads-backend` - Ads 数据库
 - `amazon-backend` - Amazon 数据库
@@ -212,6 +213,7 @@ optima-query-db commerce-backend "SELECT status, COUNT(*) FROM orders GROUP BY s
 | shopify-backend | `/services/shopify-backend` |
 | optima-generation | `/services/optima-generation` |
 | optima-sentinel | `/services/optima-sentinel` |
+| gateway-core | `/services/gateway-core` |
 
 ### RDS 连接
 

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

@@ -1,6 +1,6 @@
 ---
 name: "grant-credits"
-description: "Use when the user wants to add bonus or referral credits to an Optima user without changing their subscription."
+description: "Use when the user wants to add bonus or referral balance to an Optima user's wallet without changing their subscription."
 ---
 
 # Grant Credits
@@ -25,4 +25,4 @@ optima-grant-credits user@example.com --amount 300 --type referral --env prod
 
 - Default to `stage`.
 - Confirm the email and amount before using `prod`.
-- This operation appends credits and does not replace the user's subscription.
+- This operation appends to the user's wallet granted balance and does not replace their subscription. Amount is in credits (1 credit = $0.01).

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

@@ -25,5 +25,5 @@ optima-grant-subscription user@example.com --plan enterprise --env prod
 
 - Default to `stage`.
 - Confirm the user email before running on `prod`.
-- This operation replaces existing subscription state and resets credits according to the selected plan.
+- This operation replaces existing subscription state and resets the wallet granted balance according to the selected plan.
 - Use `optima-query-db` afterward if the user asks for verification.

package/bin/helpers/grant-credits.ts

@@ -40,7 +40,8 @@ async function main() {
   const infisicalConfig = getInfisicalConfig();
   const token = getInfisicalToken(infisicalConfig);
 
-  console.log(`\n🎁 Granting ${amount} ${type} credits to ${email} [${env.toUpperCase()}]\n`);
+  const amountMicros = amount * 10000; // 1 credit = $0.01 = 10,000 micros
+  console.log(`\n🎁 Granting $${(amountMicros / 1000000).toFixed(2)} (${amount} credits) as ${type} to ${email} [${env.toUpperCase()}]\n`);
 
   const userId = await resolveUserId(email, env, infisicalConfig, token);
   const billing = await connectBillingDB(env, infisicalConfig, token);
@@ -48,15 +49,34 @@ async function main() {
 
   const now = new Date().toISOString();
   const safeUserId = escapeSQL(userId);
-  const safeType = escapeSQL(type);
-  const safeDesc = escapeSQL(description || `Admin ${type} credit grant`);
+  const safeDesc = escapeSQL(description || `Admin ${type} grant`);
 
-  console.log(`Inserting ${amount} ${type} credits...`);
-  const ledgerId = bq(`INSERT INTO credit_ledger (id, user_id, type, description, initial_amount, remaining, created_at) VALUES (concat('crd_${safeType}_', substr(md5(random()::text), 1, 16)), '${safeUserId}', '${safeType}', '${safeDesc}', ${amount}, ${amount}, '${now}') RETURNING id`);
-  console.log(`✓ Credits granted (ledger ID: ${ledgerId})`);
+  console.log(`Granting to wallet...`);
+  const txSQL = `
+BEGIN;
 
-  const balance = bq(`SELECT COALESCE(SUM(remaining), 0) FROM credit_ledger WHERE user_id='${safeUserId}' AND remaining > 0 AND (expires_at IS NULL OR expires_at > NOW())`);
-  console.log(`\n✅ Done! ${email} now has ${balance} total credits\n`);
+-- Ensure wallet exists
+INSERT INTO usd_wallets (id, user_id, balance_micros, reserved_micros, granted_balance_micros, created_at, updated_at)
+VALUES (gen_random_uuid(), '${safeUserId}', 0, 0, 0, '${now}', '${now}')
+ON CONFLICT (user_id) DO NOTHING;
+
+-- Add to granted balance
+UPDATE usd_wallets SET granted_balance_micros = granted_balance_micros + ${amountMicros}, updated_at = '${now}'
+WHERE user_id = '${safeUserId}';
+
+-- Record topup for audit trail
+INSERT INTO usd_wallet_topups (id, wallet_id, amount_micros, service_fee_micros, net_credit_micros, status, source, service_namespace, created_at, completed_at)
+SELECT gen_random_uuid(), w.id, ${amountMicros}, 0, ${amountMicros}, 'completed', 'admin_grant', 'platform', '${now}', '${now}'
+FROM usd_wallets w WHERE w.user_id = '${safeUserId}';
+
+COMMIT;
+  `.trim();
+  bq(txSQL);
+  console.log(`✓ Wallet granted $${(amountMicros / 1000000).toFixed(2)}`);
+
+  const balanceMicros = bq(`SELECT granted_balance_micros FROM usd_wallets WHERE user_id='${safeUserId}'`);
+  const balanceUsd = (parseInt(balanceMicros, 10) / 1000000).toFixed(2);
+  console.log(`\n✅ Done! ${email} now has $${balanceUsd} granted balance\n`);
 }
 
 main().catch(error => {

package/bin/helpers/grant-subscription.ts

@@ -53,9 +53,10 @@ async function main() {
 
   const [planName, monthlyCreditsStr, sessionTokenLimitStr, weeklyTokenLimitStr] = planRow.split('|');
   const monthlyCredits = parseInt(monthlyCreditsStr, 10);
+  const grantMicros = monthlyCredits * 10000; // 1 credit = $0.01 = 10,000 micros
   const sessionTokenLimit = parseInt(sessionTokenLimitStr, 10);
   const weeklyTokenLimit = parseInt(weeklyTokenLimitStr, 10);
-  console.log(`✓ Plan: ${planName} (credits: ${monthlyCredits}, session: ${sessionTokenLimit.toLocaleString()}, weekly: ${weeklyTokenLimit.toLocaleString()})`);
+  console.log(`✓ Plan: ${planName} (grant: $${(grantMicros / 1000000).toFixed(2)}, session: ${sessionTokenLimit.toLocaleString()}, weekly: ${weeklyTokenLimit.toLocaleString()})`);
 
   // Execute all mutations in a single transaction
   const now = new Date().toISOString();
@@ -77,18 +78,23 @@ BEGIN;
 UPDATE subscriptions SET status='canceled', canceled_at='${now}'
 WHERE user_id='${safeUserId}' AND status IN ('active','trialing');
 
--- Zero out old subscription credits
-UPDATE credit_ledger SET remaining=0
-WHERE user_id='${safeUserId}' AND type IN ('monthly_grant','subscription') AND remaining > 0;
-
 -- Create new subscription
 INSERT INTO subscriptions (id, user_id, plan_id, status, billing_interval, current_period_start, current_period_end, created_at, updated_at)
 VALUES (concat('sub_gift_', substr(md5(random()::text), 1, 16)), '${safeUserId}', '${safePlan}', 'active', 'monthly', '${now}', '${periodEndISO}', '${now}', '${now}');
 
--- Grant monthly credits
-INSERT INTO credit_ledger (id, user_id, type, description, initial_amount, remaining, expires_at, created_at)
-SELECT concat('crd_gift_', substr(md5(random()::text), 1, 16)), '${safeUserId}', 'subscription', '${safePlanName} plan gift (${months} month)', ${monthlyCredits}, ${monthlyCredits}, '${periodEndISO}', '${now}'
-WHERE ${monthlyCredits} > 0;
+-- Ensure wallet exists (upsert)
+INSERT INTO usd_wallets (id, user_id, balance_micros, reserved_micros, granted_balance_micros, created_at, updated_at)
+VALUES (gen_random_uuid(), '${safeUserId}', 0, 0, 0, '${now}', '${now}')
+ON CONFLICT (user_id) DO NOTHING;
+
+-- Reset granted balance and set new grant
+UPDATE usd_wallets SET granted_balance_micros = ${grantMicros}, updated_at = '${now}'
+WHERE user_id = '${safeUserId}';
+
+-- Record topup for audit trail
+INSERT INTO usd_wallet_topups (id, wallet_id, amount_micros, service_fee_micros, net_credit_micros, status, source, service_namespace, created_at, completed_at)
+SELECT gen_random_uuid(), w.id, ${grantMicros}, 0, ${grantMicros}, 'completed', 'subscription_grant', 'platform', '${now}', '${now}'
+FROM usd_wallets w WHERE w.user_id = '${safeUserId}';
 
 -- Update existing active session quota, or insert new one if none exists
 UPDATE token_quotas SET plan_id='${safePlan}', monthly_limit=${sessionTokenLimit}, updated_at='${now}'
@@ -112,10 +118,9 @@ COMMIT;
   bq(txSQL);
 
   console.log('✓ Old subscriptions canceled');
-  console.log('✓ Old credits cleared');
   console.log(`✓ ${planName} subscription created (expires: ${periodEnd.toLocaleDateString()})`);
-  if (monthlyCredits > 0) {
-    console.log(`✓ ${monthlyCredits} credits granted`);
+  if (grantMicros > 0) {
+    console.log(`✓ Wallet granted $${(grantMicros / 1000000).toFixed(2)} (${monthlyCredits} credits equivalent)`);
   }
   console.log(`✓ Token quotas updated (session: ${sessionTokenLimit.toLocaleString()}, weekly: ${weeklyTokenLimit.toLocaleString()})`);
 

package/bin/helpers/query-db.ts

@@ -43,6 +43,11 @@ const SERVICE_DB_MAP = {
     stage: { userKey: 'AI_SHELL_DB_USER', passwordKey: 'AI_SHELL_DB_PASSWORD', database: 'optima_shell' },
     prod: { userKey: 'AI_SHELL_DB_USER', passwordKey: 'AI_SHELL_DB_PASSWORD', database: 'optima_ai_shell' }
   },
+  'gateway-core': {
+    ci: null, // CI 环境 gateway-core 不带 DB（本地 JSONL-only 模式）
+    stage: { databaseUrlPath: '/services/gateway-core', databaseUrlKey: 'DATABASE_URL' },
+    prod: { databaseUrlPath: '/services/gateway-core', databaseUrlKey: 'DATABASE_URL' }
+  },
   'optima-logistics': {
     ci: null,
     stage: { userKey: 'LOGISTICS_DB_USER', passwordKey: 'LOGISTICS_DB_PASSWORD', database: 'optima_stage_logistics' },
@@ -229,7 +234,7 @@ async function main() {
   if (args.length < 2) {
     console.error('Usage: query-db.ts <service> <sql> [environment]');
     console.error('');
-    console.error('Services: commerce-backend, user-auth, agentic-chat, bi-backend, session-gateway, optima-logistics, billing, ads-backend, amazon-backend, browser-backend, shopify-backend, optima-generation, optima-sentinel');
+    console.error('Services: commerce-backend, user-auth, agentic-chat, bi-backend, session-gateway, gateway-core, optima-logistics, billing, ads-backend, amazon-backend, browser-backend, shopify-backend, optima-generation, optima-sentinel');
     console.error('Environments: ci (default), stage, prod');
     console.error('');
     console.error('Example: query-db.ts user-auth "SELECT COUNT(*) FROM users" prod');

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

@@ -51,19 +51,39 @@ async function main() {
     const { email, amount, type, description, env } = parseArgs(process.argv.slice(2));
     const infisicalConfig = (0, db_utils_1.getInfisicalConfig)();
     const token = (0, db_utils_1.getInfisicalToken)(infisicalConfig);
-    console.log(`\n🎁 Granting ${amount} ${type} credits to ${email} [${env.toUpperCase()}]\n`);
+    const amountMicros = amount * 10000; // 1 credit = $0.01 = 10,000 micros
+    console.log(`\n🎁 Granting $${(amountMicros / 1000000).toFixed(2)} (${amount} credits) as ${type} to ${email} [${env.toUpperCase()}]\n`);
     const userId = await (0, db_utils_1.resolveUserId)(email, env, infisicalConfig, token);
     const billing = await (0, db_utils_1.connectBillingDB)(env, infisicalConfig, token);
     const bq = billing.query;
     const now = new Date().toISOString();
     const safeUserId = (0, db_utils_1.escapeSQL)(userId);
-    const safeType = (0, db_utils_1.escapeSQL)(type);
-    const safeDesc = (0, db_utils_1.escapeSQL)(description || `Admin ${type} credit grant`);
-    console.log(`Inserting ${amount} ${type} credits...`);
-    const ledgerId = bq(`INSERT INTO credit_ledger (id, user_id, type, description, initial_amount, remaining, created_at) VALUES (concat('crd_${safeType}_', substr(md5(random()::text), 1, 16)), '${safeUserId}', '${safeType}', '${safeDesc}', ${amount}, ${amount}, '${now}') RETURNING id`);
-    console.log(`✓ Credits granted (ledger ID: ${ledgerId})`);
-    const balance = bq(`SELECT COALESCE(SUM(remaining), 0) FROM credit_ledger WHERE user_id='${safeUserId}' AND remaining > 0 AND (expires_at IS NULL OR expires_at > NOW())`);
-    console.log(`\n✅ Done! ${email} now has ${balance} total credits\n`);
+    const safeDesc = (0, db_utils_1.escapeSQL)(description || `Admin ${type} grant`);
+    console.log(`Granting to wallet...`);
+    const txSQL = `
+BEGIN;
+
+-- Ensure wallet exists
+INSERT INTO usd_wallets (id, user_id, balance_micros, reserved_micros, granted_balance_micros, created_at, updated_at)
+VALUES (gen_random_uuid(), '${safeUserId}', 0, 0, 0, '${now}', '${now}')
+ON CONFLICT (user_id) DO NOTHING;
+
+-- Add to granted balance
+UPDATE usd_wallets SET granted_balance_micros = granted_balance_micros + ${amountMicros}, updated_at = '${now}'
+WHERE user_id = '${safeUserId}';
+
+-- Record topup for audit trail
+INSERT INTO usd_wallet_topups (id, wallet_id, amount_micros, service_fee_micros, net_credit_micros, status, source, service_namespace, created_at, completed_at)
+SELECT gen_random_uuid(), w.id, ${amountMicros}, 0, ${amountMicros}, 'completed', 'admin_grant', 'platform', '${now}', '${now}'
+FROM usd_wallets w WHERE w.user_id = '${safeUserId}';
+
+COMMIT;
+  `.trim();
+    bq(txSQL);
+    console.log(`✓ Wallet granted $${(amountMicros / 1000000).toFixed(2)}`);
+    const balanceMicros = bq(`SELECT granted_balance_micros FROM usd_wallets WHERE user_id='${safeUserId}'`);
+    const balanceUsd = (parseInt(balanceMicros, 10) / 1000000).toFixed(2);
+    console.log(`\n✅ Done! ${email} now has $${balanceUsd} granted balance\n`);
 }
 main().catch(error => {
     console.error('\n❌ Error:', error.message);

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

@@ -59,9 +59,10 @@ async function main() {
     }
     const [planName, monthlyCreditsStr, sessionTokenLimitStr, weeklyTokenLimitStr] = planRow.split('|');
     const monthlyCredits = parseInt(monthlyCreditsStr, 10);
+    const grantMicros = monthlyCredits * 10000; // 1 credit = $0.01 = 10,000 micros
     const sessionTokenLimit = parseInt(sessionTokenLimitStr, 10);
     const weeklyTokenLimit = parseInt(weeklyTokenLimitStr, 10);
-    console.log(`✓ Plan: ${planName} (credits: ${monthlyCredits}, session: ${sessionTokenLimit.toLocaleString()}, weekly: ${weeklyTokenLimit.toLocaleString()})`);
+    console.log(`✓ Plan: ${planName} (grant: $${(grantMicros / 1000000).toFixed(2)}, session: ${sessionTokenLimit.toLocaleString()}, weekly: ${weeklyTokenLimit.toLocaleString()})`);
     // Execute all mutations in a single transaction
     const now = new Date().toISOString();
     const periodEnd = new Date();
@@ -80,18 +81,23 @@ BEGIN;
 UPDATE subscriptions SET status='canceled', canceled_at='${now}'
 WHERE user_id='${safeUserId}' AND status IN ('active','trialing');
 
--- Zero out old subscription credits
-UPDATE credit_ledger SET remaining=0
-WHERE user_id='${safeUserId}' AND type IN ('monthly_grant','subscription') AND remaining > 0;
-
 -- Create new subscription
 INSERT INTO subscriptions (id, user_id, plan_id, status, billing_interval, current_period_start, current_period_end, created_at, updated_at)
 VALUES (concat('sub_gift_', substr(md5(random()::text), 1, 16)), '${safeUserId}', '${safePlan}', 'active', 'monthly', '${now}', '${periodEndISO}', '${now}', '${now}');
 
--- Grant monthly credits
-INSERT INTO credit_ledger (id, user_id, type, description, initial_amount, remaining, expires_at, created_at)
-SELECT concat('crd_gift_', substr(md5(random()::text), 1, 16)), '${safeUserId}', 'subscription', '${safePlanName} plan gift (${months} month)', ${monthlyCredits}, ${monthlyCredits}, '${periodEndISO}', '${now}'
-WHERE ${monthlyCredits} > 0;
+-- Ensure wallet exists (upsert)
+INSERT INTO usd_wallets (id, user_id, balance_micros, reserved_micros, granted_balance_micros, created_at, updated_at)
+VALUES (gen_random_uuid(), '${safeUserId}', 0, 0, 0, '${now}', '${now}')
+ON CONFLICT (user_id) DO NOTHING;
+
+-- Reset granted balance and set new grant
+UPDATE usd_wallets SET granted_balance_micros = ${grantMicros}, updated_at = '${now}'
+WHERE user_id = '${safeUserId}';
+
+-- Record topup for audit trail
+INSERT INTO usd_wallet_topups (id, wallet_id, amount_micros, service_fee_micros, net_credit_micros, status, source, service_namespace, created_at, completed_at)
+SELECT gen_random_uuid(), w.id, ${grantMicros}, 0, ${grantMicros}, 'completed', 'subscription_grant', 'platform', '${now}', '${now}'
+FROM usd_wallets w WHERE w.user_id = '${safeUserId}';
 
 -- Update existing active session quota, or insert new one if none exists
 UPDATE token_quotas SET plan_id='${safePlan}', monthly_limit=${sessionTokenLimit}, updated_at='${now}'
@@ -113,10 +119,9 @@ COMMIT;
   `.trim();
     bq(txSQL);
     console.log('✓ Old subscriptions canceled');
-    console.log('✓ Old credits cleared');
     console.log(`✓ ${planName} subscription created (expires: ${periodEnd.toLocaleDateString()})`);
-    if (monthlyCredits > 0) {
-        console.log(`✓ ${monthlyCredits} credits granted`);
+    if (grantMicros > 0) {
+        console.log(`✓ Wallet granted $${(grantMicros / 1000000).toFixed(2)} (${monthlyCredits} credits equivalent)`);
     }
     console.log(`✓ Token quotas updated (session: ${sessionTokenLimit.toLocaleString()}, weekly: ${weeklyTokenLimit.toLocaleString()})`);
     console.log(`\n✅ Done! ${email} now has ${planName} plan until ${periodEnd.toLocaleDateString()}\n`);

package/dist/bin/helpers/query-db.js

@@ -62,6 +62,11 @@ const SERVICE_DB_MAP = {
         stage: { userKey: 'AI_SHELL_DB_USER', passwordKey: 'AI_SHELL_DB_PASSWORD', database: 'optima_shell' },
         prod: { userKey: 'AI_SHELL_DB_USER', passwordKey: 'AI_SHELL_DB_PASSWORD', database: 'optima_ai_shell' }
     },
+    'gateway-core': {
+        ci: null, // CI 环境 gateway-core 不带 DB（本地 JSONL-only 模式）
+        stage: { databaseUrlPath: '/services/gateway-core', databaseUrlKey: 'DATABASE_URL' },
+        prod: { databaseUrlPath: '/services/gateway-core', databaseUrlKey: 'DATABASE_URL' }
+    },
     'optima-logistics': {
         ci: null,
         stage: { userKey: 'LOGISTICS_DB_USER', passwordKey: 'LOGISTICS_DB_PASSWORD', database: 'optima_stage_logistics' },
@@ -219,7 +224,7 @@ async function main() {
     if (args.length < 2) {
         console.error('Usage: query-db.ts <service> <sql> [environment]');
         console.error('');
-        console.error('Services: commerce-backend, user-auth, agentic-chat, bi-backend, session-gateway, optima-logistics, billing, ads-backend, amazon-backend, browser-backend, shopify-backend, optima-generation, optima-sentinel');
+        console.error('Services: commerce-backend, user-auth, agentic-chat, bi-backend, session-gateway, gateway-core, optima-logistics, billing, ads-backend, amazon-backend, browser-backend, shopify-backend, optima-generation, optima-sentinel');
         console.error('Environments: ci (default), stage, prod');
         console.error('');
         console.error('Example: query-db.ts user-auth "SELECT COUNT(*) FROM users" prod');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optima-chat/dev-skills",
-  "version": "0.7.29",
+  "version": "0.7.31",
   "description": "Claude Code Skills for Optima development team - cross-environment collaboration tools",
   "main": "index.js",
   "bin": {