@lingjingai/lj-awb-cli-pre 0.4.5 → 0.4.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lingjingai/lj-awb-cli-pre",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "Lingjing AWB CLI monorepo with shared core, standalone CLI, and agent skills (pre-release build pointing to https://animeworkbench-pre.lingjingai.cn)",
   "license": "MIT",
   "type": "module",

package/packages/awb-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lingjingai/awb-cli-bin",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "Standalone CLI for Lingjing AWB",
   "private": true,
   "license": "MIT",
@@ -13,6 +13,6 @@
     "README.md"
   ],
   "dependencies": {
-    "@lingjingai/awb-core": "0.4.5"
+    "@lingjingai/awb-core": "0.4.7"
   }
 }

package/packages/awb-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lingjingai/awb-core",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "Shared core runtime for Lingjing AWB CLI",
   "license": "MIT",
   "type": "module",

package/packages/awb-core/src/api.js

@@ -133,15 +133,25 @@ export async function fetchPoints() {
   return await apiFetch('/api/anime/member/benefits/queryGroupPoint', { body: {} });
 }
 
+export async function redeemCode(code) {
+  // 后端 redeemCode 的 code 是无注解 Spring 参数（按 query / form 绑定，不读 JSON body），
+  // 且必须带 userId / groupId 请求头（由 buildHeaders 从环境变量注入）。
+  return await apiFetch('/api/anime/member/redemption/redeemCode', {
+    method: 'POST',
+    query: { code },
+  });
+}
+
 export async function selectProjectGroup(projectGroupNo) {
   return await apiFetch('/api/anime/workbench/projectGroup/setLastProjectGroup', {
     body: { projectGroupNo },
   });
 }
 
-export async function updateCurrentTeam(groupId) {
-  return await apiFetch('/api/anime/user/group/updateCurrentGroup', {
-    body: { groupId },
+export async function fetchGroupAccessKey({ userId, groupId }) {
+  // 切换团队：用当前用户的 userId + 目标 groupId 换取该团队的 accessKey，再刷新本地认证文件。
+  return await apiFetch('/api/anime/user/account/groupAccessKey', {
+    body: { userId, groupId },
   });
 }
 

package/packages/awb-core/src/commands.js

@@ -14,6 +14,8 @@ import {
   authLogin,
   authLogout,
   creditsBalance,
+  creditsBuy,
+  creditsRedeem,
   creditsUsageSummary,
   createProjectGroupCommand,
   accountInfo,
@@ -398,6 +400,33 @@ export function registerAwbCommands(cli) {
     func: async (_ctx, kwargs) => creditsUsageSummary(kwargs),
   });
 
+  cli({
+    name: 'credits buy',
+    description: commandHelp('引导购买 / 充值：按当前环境（预发 / 正式）输出充值页面链接', {
+      examples: ['lj-awb credits buy'],
+      hint: '只输出充值链接，不发起网络请求；请在浏览器中打开链接完成购买。链接随构建环境写死，预发与正式各自指向对应工作台域名。',
+    }),
+    args: [],
+    func: async () => creditsBuy(),
+  });
+
+  cli({
+    name: 'credits redeem',
+    description: commandHelp('兑换码兑换：等待输入兑换码并调用平台兑换接口，成功后展示最新积分余额', {
+      examples: [
+        'lj-awb credits redeem',
+        'lj-awb credits redeem --code <code>',
+      ],
+      hint: '不传 --code 时进入交互模式，最长等待约 10 分钟读取兑换码（自动去除空格 / 换行）；非交互终端必须用 --code 传入。兑换成功后会顺带展示当前积分余额。',
+    }),
+    args: [
+      { name: 'code', valueName: 'code', description: '兑换码；不传则交互式等待输入' },
+      { name: 'wait-seconds', valueName: 'seconds', description: '交互模式下等待输入兑换码的最长秒数，默认 600' },
+      DRY_RUN_ARG,
+    ],
+    func: async (_ctx, kwargs) => creditsRedeem(kwargs),
+  });
+
   cli({
     name: 'model image-models',
     description: commandHelp('查询可用生图模型', {

package/packages/awb-core/src/common.js

@@ -11,6 +11,18 @@ export const API_ORIGIN = (
   || process.env.AWB_BASE_URL
   || DEFAULT_API_ORIGIN
 ).replace(/\/+$/, '');
+// 充值 / 购买引导页面链接：随构建环境写死，预发和正式分别指向各自的工作台域名。
+export const PURCHASE_URL_PRE = 'https://animeworkbench-pre.lingjingai.cn/platform/creation?openModal=RechargeModal';
+export const PURCHASE_URL_PROD = 'https://animeworkbench.lingjingai.cn/platform/creation?openModal=RechargeModal';
+
+export function resolvePurchaseUrl() {
+  const isPre = API_ORIGIN.includes('animeworkbench-pre') || API_ORIGIN.includes('-pre.');
+  return {
+    environment: isPre ? 'pre' : 'prod',
+    purchaseUrl: isPre ? PURCHASE_URL_PRE : PURCHASE_URL_PROD,
+  };
+}
+
 export const APP_HOME_DIR = process.env.LINGJING_AWB_STATE_DIR || process.env.ANIME_STATE_DIR || path.join(os.homedir(), '.lingjingai', 'awb');
 export const AUTH_PATH = process.env.LINGJING_AWB_AUTH_PATH || process.env.ANIME_AUTH_PATH || path.join(APP_HOME_DIR, 'auth.json');
 export const STATE_PATH = process.env.LINGJING_AWB_STATE_PATH || process.env.ANIME_STATE_PATH || path.join(APP_HOME_DIR, 'state.json');

package/packages/awb-core/src/output.js

@@ -1400,6 +1400,8 @@ const OUTPUT_KIND_BY_COMMAND = {
   'project ensure': 'generic',
   'credits balance': 'credits_balance',
   'credits usage': 'credits_usage',
+  'credits buy': 'purchase_guide',
+  'credits redeem': 'redeem_result',
   'model image-models': 'model_list',
   'model video-models': 'model_list',
   'model asset-review-models': 'asset_review_model_list',
@@ -1525,6 +1527,8 @@ const KIND_TITLES = {
   project_list: '项目组列表',
   project_summary: '项目组摘要',
   project_user_list: '项目组成员',
+  purchase_guide: '购买引导',
+  redeem_result: '兑换结果',
   subject_list: '主体列表',
   subject_publish_result: '主体创建结果',
   subject_status: '主体状态',
@@ -1598,6 +1602,9 @@ const FIELD_LABELS = {
   cleared: '已清空',
   loggedOut: '已退出登录',
   authPath: '认证文件',
+  purchaseUrl: '购买链接',
+  redeemed: '已兑换',
+  redemptionCode: '兑换码',
   clipCount: 'Clip 数',
   clipId: 'Clip ID',
   command: '命令',
@@ -1771,6 +1778,8 @@ const DETAIL_FIELDS_BY_KIND = {
   generic: ['cleared', 'selected', 'created', 'updated', 'reused', 'dryRun', 'action', 'projectGroupNo', 'projectGroupName', 'groupId', 'groupName', 'projectGroupName', 'point', 'memberCount', 'note'],
   local_task_records: ['count', 'taskCount', 'successTaskCount', 'resultCount', 'pointTotal'],
   project_summary: ['selected', 'created', 'updated', 'reused', 'projectGroupNo', 'projectGroupName', 'isSelected', 'projectBudgetBalance', 'projectBudgetMax', 'memberCount'],
+  purchase_guide: ['purchaseUrl'],
+  redeem_result: ['redeemed', 'redemptionCode', 'billingPointBalance', 'currentProjectGroupNo', 'currentProjectGroupName', 'projectBudgetBalance', 'projectBudgetMax'],
   subject_publish_result: ['created', 'name', 'elementId', 'subjectId', 'externalId', 'modelCode', 'status', 'taskStatus', 'errorMessage', 'nextRefSubject'],
   subject_status: ['name', 'elementId', 'subjectId', 'externalId', 'modelCode', 'status', 'taskStatus', 'errorMessage', 'isTerminal', 'nextRefSubject'],
   subject_voice_create_result: ['created', 'name', 'voiceRecordId', 'reqTaskId', 'voiceId', 'externalId', 'status', 'taskStatus', 'errorMessage', 'nextVoiceArg'],
@@ -1791,6 +1800,7 @@ const DRY_RUN_FIELDS_BY_COMMAND = {
   'project create': ['dryRun', 'action', 'projectGroupName', 'point', 'memberCount', 'note'],
   'project update': ['dryRun', 'action', 'projectGroupNo', 'projectGroupName', 'point', 'memberCount'],
   'project ensure': ['dryRun', 'action', 'projectGroupName', 'point', 'memberCount', 'note'],
+  'credits redeem': ['dryRun', 'action', 'redemptionCode'],
   'upload files': ['dryRun', 'fileCount', 'localFileCount', 'resourceConversionCount'],
   'create image': ['dryRun', 'action', 'modelGroupCode', 'projectGroupNo', 'prompt', 'ratio', 'quality', 'generateNum', 'resourceCount', 'localFileCount', 'assetCount'],
   'create video': ['dryRun', 'action', 'modelGroupCode', 'projectGroupNo', 'prompt', 'duration', 'ratio', 'quality', 'needAudio', 'resourceCount', 'localFileCount', 'assetCount'],

package/packages/awb-core/src/services.js

@@ -28,6 +28,7 @@ import {
   nowIso,
   parseJsonArg,
   parseListArg,
+  resolvePurchaseUrl,
   safeFileName,
   saveState,
   sleep,
@@ -471,6 +472,91 @@ export async function accountInfo() {
   };
 }
 
+const REDEEM_CODE_WAIT_SECONDS_DEFAULT = 600;
+
+// 去掉用户粘贴时可能带上的空格 / 制表符 / 换行，避免污染兑换码。
+function sanitizeRedeemCode(value) {
+  return String(value ?? '').replace(/\s+/g, '');
+}
+
+export async function creditsBuy() {
+  const { purchaseUrl } = resolvePurchaseUrl();
+  return {
+    action: 'credits buy',
+    purchaseUrl,
+  };
+}
+
+async function promptRedeemCode(waitSeconds) {
+  if (process.stdin.isTTY !== true || process.stderr.isTTY !== true) {
+    throw argumentError(
+      '未提供兑换码',
+      '非交互终端不会等待输入，请通过 --code 传入兑换码，例如 lj-awb credits redeem --code <code>。',
+    );
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), Math.max(1, waitSeconds) * 1000);
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    const answer = await rl.question('请输入兑换码后回车确认：', { signal: controller.signal });
+    return sanitizeRedeemCode(answer);
+  } catch (error) {
+    if (controller.signal.aborted) {
+      throw new LingjingAwbCliError('等待输入兑换码超时', {
+        type: 'redeem_timeout',
+        exitCode: 20,
+        hint: '重新运行 lj-awb credits redeem 并在限定时间内输入兑换码，或直接用 --code 传入。',
+      });
+    }
+    throw error;
+  } finally {
+    clearTimeout(timer);
+    rl.close();
+  }
+}
+
+export async function creditsRedeem(kwargs = {}) {
+  const waitSeconds = Math.max(0, toInt(kwargs.waitSeconds, REDEEM_CODE_WAIT_SECONDS_DEFAULT));
+  let code = sanitizeRedeemCode(kwargs.code);
+  if (!code) {
+    code = await promptRedeemCode(waitSeconds);
+  }
+  if (!code) {
+    throw argumentError('兑换码不能为空', '请提供有效兑换码，或通过 --code <code> 传入。');
+  }
+  if (toBool(kwargs.dryRun)) {
+    return { dryRun: true, action: 'credits redeem', redemptionCode: code };
+  }
+
+  try {
+    await awbApi.redeemCode(code);
+  } catch (error) {
+    // apiFetch 在平台返回 code != 200 时抛 api_error，并带上平台 msg；统一转成更友好的兑换失败提示。
+    if (error instanceof LingjingAwbCliError && (error.type === 'api_error' || error.type === 'http_error')) {
+      throw new LingjingAwbCliError(error.message || '兑换失败', {
+        type: 'redeem_failed',
+        exitCode: 1,
+        hint: '兑换处理失败，请确认兑换码是否正确或已被使用；若持续失败请联系平台处理。',
+        details: error.details,
+      });
+    }
+    throw error;
+  }
+
+  // 兑换成功后顺带拉取账号概览，展示最新积分余额（等同于 lj-awb account info）。
+  const account = await accountInfo().catch(() => null);
+  return {
+    redeemed: true,
+    action: 'credits redeem',
+    redemptionCode: code,
+    billingPointBalance: account?.billingPointBalance ?? null,
+    currentProjectGroupNo: account?.currentProjectGroupNo ?? null,
+    currentProjectGroupName: account?.currentProjectGroupName ?? null,
+    projectBudgetBalance: account?.projectBudgetBalance ?? null,
+    projectBudgetMax: account?.projectBudgetMax ?? null,
+  };
+}
+
 async function pathExists(filePath) {
   if (!filePath) return false;
   try {
@@ -618,9 +704,41 @@ export async function selectTeam(kwargs = {}) {
     action: 'account switch-team',
     groupId,
   });
-  await awbApi.updateCurrentTeam(groupId);
-  await saveState({ currentGroupId: groupId }).catch(() => {});
-  return { selected: true, groupId };
+  // userId 取当前登录用户（与 account info 同源：fetchUserInfo）
+  const userId = normalizeUserInfo(await awbApi.fetchUserInfo()).userId;
+  if (!userId) {
+    throw new LingjingAwbCliError('无法获取当前用户 userId，切换团队失败', {
+      type: 'api_error',
+      exitCode: 1,
+      hint: '请先确认已登录（lj-awb auth status），再重试。',
+    });
+  }
+  // 用 userId + 目标 groupId 换取该团队的 accessKey
+  const accessKey = trimSecret(await awbApi.fetchGroupAccessKey({ userId, groupId }));
+  if (!accessKey) {
+    throw new LingjingAwbCliError('切换团队失败：未返回该团队的 accessKey', {
+      type: 'api_error',
+      exitCode: 1,
+      hint: '请确认该 groupId 属于当前用户可访问的团队；若持续失败请联系平台。',
+    });
+  }
+  // 刷新本地认证文件（等同登录写入），并用新 key 校验，拿到切换后的用户 / 团队上下文
+  const saved = await saveVerifiedAccessKey(accessKey, { loginMethod: 'switch-team' });
+  const switchedGroupId = saved.user?.groupId ?? groupId;
+  await saveState({
+    currentGroupId: switchedGroupId,
+    currentGroupName: saved.user?.groupName ?? null,
+    currentUserId: saved.user?.userId ?? userId,
+  }).catch(() => {});
+  return {
+    selected: true,
+    action: 'account switch-team',
+    groupId: switchedGroupId,
+    groupName: saved.user?.groupName ?? null,
+    userId: saved.user?.userId ?? userId,
+    userName: saved.user?.userName ?? null,
+    accessKey: saved.accessKey,
+  };
 }
 
 export async function selectProjectGroupCommand(kwargs = {}) {

package/packages/awb-core/src/standalone.js

@@ -534,6 +534,9 @@ const GROUP_EXAMPLES = {
   credits: [
     'lj-awb credits balance',
     'lj-awb credits usage --project-group-no <no> --last-hours 24',
+    'lj-awb credits buy',
+    'lj-awb credits redeem',
+    'lj-awb credits redeem --code <code>',
   ],
   model: [
     'lj-awb model image-models --model Banana',
@@ -734,6 +737,7 @@ const REMOTE_WRITE_COMMANDS = new Set([
   'project create',
   'project update',
   'project ensure',
+  'credits redeem',
   'upload files',
   'create image',
   'create image-batch',
@@ -761,8 +765,8 @@ const LOCAL_STATE_WRITE_COMMANDS = new Set([
 ]);
 
 const DESTRUCTIVE_COMMANDS = new Set(['auth clear', ...ARTIFACT_DELETE_COMMANDS]);
-const LONG_RUNNING_COMMANDS = new Set(['auth login', 'task wait', 'task record-poll', 'create subject-wait', 'create subject-voice-wait']);
-const NETWORK_NONE_COMMANDS = new Set(['schema', 'auth status', 'auth clear', 'auth logout', 'model input-guide', 'task records']);
+const LONG_RUNNING_COMMANDS = new Set(['auth login', 'credits redeem', 'task wait', 'task record-poll', 'create subject-wait', 'create subject-voice-wait']);
+const NETWORK_NONE_COMMANDS = new Set(['schema', 'auth status', 'auth clear', 'auth logout', 'credits buy', 'model input-guide', 'task records']);
 const NETWORK_CONDITIONAL_COMMANDS = new Set(['doctor', 'auth login']);
 
 const OUTPUT_KIND_BY_COMMAND = {
@@ -780,6 +784,8 @@ const OUTPUT_KIND_BY_COMMAND = {
   'project users': 'project_user_list',
   'credits balance': 'credits_balance',
   'credits usage': 'credits_usage',
+  'credits buy': 'purchase_guide',
+  'credits redeem': 'redeem_result',
   'model image-models': 'model_list',
   'model video-models': 'model_list',
   'model asset-review-models': 'asset_review_model_list',

package/skills/lj-awb/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: lj-awb
-version: 0.4.5
-description: "灵境 AWB CLI skill。使用 `lj-awb` 命令调用动漫平台 / AWB 云端能力，覆盖认证、项目组、积分、模型发现、上传、统一 create 创建域、任务查询、视频超分、最终产物 artifact CRUD 与本地 JSON 导入。用户说生图、生视频、视频超分、主体、音色、素材加白、去字幕、artifact 写入或查询时使用。正式生成、切换项目组、清空认证、artifact 写入等写入或扣费动作前必须确认。"
+version: 0.4.7
+description: "灵境 AWB CLI skill。使用 `lj-awb` 命令调用动漫平台 / AWB 云端能力，覆盖认证、项目组、积分（含充值购买与兑换码兑换）、模型发现、上传、统一 create 创建域、任务查询、视频超分、最终产物 artifact CRUD 与本地 JSON 导入。用户说生图、生视频、视频超分、主体、音色、素材加白、去字幕、充值、购买积分、兑换码、artifact 写入或查询时使用。正式生成、切换项目组、清空认证、兑换码、artifact 写入等写入或扣费动作前必须确认。"
 metadata:
   bootstrap:
     package: "@lingjingai/lj-awb-cli"
-    version: "0.4.5"
+    version: "0.4.7"
     bin: "lj-awb"
   cliHelp: "lj-awb --help"
 ---
@@ -84,6 +84,7 @@ schema 查询必须先返回，再组织业务命令；不要把 schema 查询
 | 用户意图 | 先走 |
 |----------|------|
 | “能不能跑 / 认证 / 当前项目 / 余额” | `doctor --verify`，再按需 `account` / `project` / `credits` |
+| “充值 / 购买积分 / 积分不够了 / 兑换码” | [`modules/credits.md`](modules/credits.md)：购买走 `credits buy` 给链接，兑换走 `credits redeem`（非交互用 `--code <code>`）|
 | “有哪些模型 / 推荐模型 / 用某某模型” | [`modules/model.md`](modules/model.md)，模型口语名默认是平台模型，不是本地工具 |
 | “生图 / 生成图片 / 参考图生图” | [`modules/driver.md`](modules/driver.md) 创作链条 + [`modules/create-contract.md`](modules/create-contract.md) |
 | “生视频 / 首帧 / 首尾帧 / 音频参考 / 让图动起来” | [`modules/driver.md`](modules/driver.md) 创作链条 + [`modules/task-manual.md`](modules/task-manual.md) |

package/skills/lj-awb/VERSION

@@ -1 +1 @@
-0.4.5
+0.4.7

package/skills/lj-awb/compat.json

@@ -1,6 +1,6 @@
 {
-  "skillVersion": "0.4.5",
-  "minCliVersion": "0.4.5",
+  "skillVersion": "0.4.7",
+  "minCliVersion": "0.4.7",
   "preferredCommand": "lj-awb",
-  "updatedAt": "2026-06-10"
+  "updatedAt": "2026-06-12"
 }

package/skills/lj-awb/modules/account.md

@@ -9,7 +9,7 @@
 | `lj-awb account info` | 当前用户、团队、项目组、积分摘要（启动后第一条信息） |
 | `lj-awb account teams` | 列出当前账号可访问的团队 |
 | `lj-awb account switch-team --group-id <id> --dry-run` | 预览切换团队 |
-| `lj-awb account switch-team --group-id <id> --yes` | 切换团队（云端写入） |
+| `lj-awb account switch-team --group-id <id> --yes` | 切换团队（换取该团队 accessKey 并刷新本地登录态） |
 
 ## 什么时候切团队
 
@@ -25,6 +25,8 @@
 ## 规则
 
 - `account switch-team` 改变团队上下文，**必须确认**后追加 `--yes`。
+- 切换原理：用当前用户 `userId` + 目标 `groupId` 调 `groupAccessKey` 换到该团队的 accessKey，再**写回本地认证文件**（等同重新登录到该团队）。
+- 若用户是通过 `LINGJING_AWB_ACCESS_KEY` 环境变量登录的，写回文件**不生效**（env key 优先级高于文件）；这种情况下要么 `unset LINGJING_AWB_ACCESS_KEY` 后再切，要么直接换该团队的 access key。
 - 切换团队会**重置项目组上下文**：之后跑 `project current` 必然为空，需要让用户重新 `project use --project-group-no <no>` 选一个。
 - 不要把 `account info.groupName`（团队名）当作项目组名报告给用户。
 - 输出字段速查见 [`../references/output-fields.md`](../references/output-fields.md) 的"账号与项目组"小节。

package/skills/lj-awb/modules/credits.md

@@ -1,6 +1,6 @@
 # Credits Module
 
-积分模块用于预算确认和项目用量统计。
+积分模块用于预算确认、项目用量统计，以及积分的购买（充值）与兑换码兑换。
 
 ## 命令
 
@@ -10,6 +10,23 @@
 | `lj-awb credits balance --project-group-no <no>` | 查看可扣积分余额和指定项目组预算 |
 | `lj-awb credits usage --project-group-no <no> --last-hours 24` | 汇总最近任务消耗 |
 | `lj-awb credits usage --project-group-no <no> --task-types IMAGE_CREATE,VIDEO_GROUP --include-tasks` | 汇总并附带任务明细 |
+| `lj-awb credits buy` | 引导购买 / 充值：输出充值页面链接，让用户在浏览器打开完成购买（链接已自动匹配当前环境，无需告知用户环境）|
+| `lj-awb credits redeem` | 兑换码兑换：交互式等待用户输入兑换码，兑换成功后展示最新积分余额 |
+| `lj-awb credits redeem --code <code>` | 直接用 `--code` 传入兑换码，跳过交互（脚本 / 非交互终端必须这样用）|
+
+## 购买（充值）
+
+- `credits buy` **只输出链接、不发起网络请求**，输出里只有一个 `purchaseUrl`，已自动匹配当前 CLI 所在环境。
+- **直接把 `purchaseUrl` 给用户即可**：不要向用户提及 / 区分"预发""正式"环境，不要主动追问或提供"另一个环境的链接"，也不要展示 API 地址等环境细节——对用户而言只有"充值链接"这一个概念。
+- CLI 无法代用户完成支付，把链接交给用户在浏览器打开即可；不要承诺"已充值"。完成后可建议 `credits balance` 查看余额。
+
+## 兑换码
+
+- 不传 `--code` 时进入交互模式，最长等待约 **10 分钟**（可用 `--wait-seconds` 调）读取用户输入；输入会**自动去除空格 / 换行 / 制表符**，避免粘贴时带上多余字符。
+- **非交互终端 / AI agent 不会挂起**：未提供 `--code` 时直接报 `argument_error`，必须用 `--code <兑换码>` 传入。
+- 兑换是会改账户积分的远端写操作（`safeToAutoRun=false`）：执行前向用户确认兑换码；支持 `--dry-run` 预览将要提交的兑换码。
+- 平台接口 `code != 200` 即视为失败，CLI 抛 `redeem_failed`（保留平台原始 `msg`），提示用户确认兑换码或联系平台处理。
+- 兑换成功后会顺带调用 `account info` 拉取并展示最新 `billingPointBalance`，无需再单独跑 `credits balance`。
 
 ## 规则
 
@@ -25,4 +42,4 @@
 ## 下一步
 
 - 积分够 → 进 [`model.md`](model.md) 选模型，或直接 [`image.md`](image.md) / [`video.md`](video.md) 估价。
-- 积分不够 → 提示用户充值；不要默认换更便宜模型，先问用户偏好。
+- 积分不够 → 用 `credits buy` 给出充值链接，或 `credits redeem` 走兑换码；不要默认换更便宜模型，先问用户偏好。

package/skills/lj-awb/references/error-codes.md

@@ -16,6 +16,7 @@ CLI 失败时 envelope 形如：
 | `1` | `runtime_error` / `api_error` | 平台业务失败或一般运行异常 | 看 `message` / `details`；不要自动重试相同请求 |
 | `1` | `subject_failed` | 主体创建任务已失败 | 看 `details.errorMessage`，调整参考资源 / 模型后重新创建 |
 | `1` | `subject_voice_failed` | 主体音色创建任务已失败 | 看 `details.errorMessage`，调整音频 / 视频来源后重新创建 |
+| `1` | `redeem_failed` | 兑换码兑换失败（平台 `code != 200`） | 看 `message`（平台原始提示），确认兑换码是否正确 / 已被使用；持续失败联系平台处理 |
 | `2` | `argument_error` | 必填参数缺失、参数格式 / 枚举不合法 | 按 `hint` 补参数；用 `lj-awb schema --command <name> -f json` 查 `requiredOptions / requiredAnyOptions` |
 | `2` | `unknown_command` / `unknown_option` | 命令名 / 参数名打错 | 跑 `lj-awb -h` 或对应子域 `lj-awb <domain> -h` 重查命令 |
 | `3` | `auth_required` | 缺少 access key | 提示用户 `lj-awb auth login --access-key <key>` 或设置 `LINGJING_AWB_ACCESS_KEY` |
@@ -28,6 +29,7 @@ CLI 失败时 envelope 形如：
 | `20` | `subject_still_pending` | 主体 externalId 尚未回填 | 续跑 `create subject-wait --element-id ... --wait-seconds <n>` |
 | `20` | `subject_voice_still_pending` | 主体音色 externalId 尚未回填 | 续跑 `create subject-voice-wait --voice-record-id ... --wait-seconds <n>` |
 | `20` | `auth_flow_pending` | 浏览器授权等待窗口结束但用户尚未授权 | 用 `details.flowId` 续跑 `auth login --flow-id <flowId>`，**不要重发新 login**，**不代表失败** |
+| `20` | `redeem_timeout` | 交互式等待输入兑换码超时（默认约 10 分钟） | 重新跑 `credits redeem` 并及时输入，或直接 `credits redeem --code <code>` 传入 |
 | `30` | `network_error` | TLS / DNS / 连接失败 / 平台 5xx | 检查网络；macOS 证书问题用 `lj-awb`（shell wrapper）而不是直接 `node bin/lj-awb.js` |
 | `30` | `http_error` | 非 401 的 HTTP 错误（4xx / 5xx） | 看 `message`；429 等限流时退避重试 |
 | `30` | `upload_failed` | COS 上传失败 | 重试一次；持续失败检查文件大小 / mimeType / 网络 |
@@ -131,3 +133,18 @@ AI agent / 无法实时看输出时的标准流程：
 lj-awb auth login --no-wait --json     # 拿 flowId + verifyUrl，发给用户去浏览器授权
 lj-awb auth login --flow-id <flowId>   # 用户授权后续轮询，拿到并保存 accessKey
 ```
+
+### 场景 10：兑换码兑换（redeem_*）
+
+`credits redeem` 的几种结果：
+
+- `redeem_failed`（exit 1）：平台返回 `code != 200`，兑换没成功。`message` 是平台原始提示，如实复述给用户，让其确认兑换码是否正确 / 已被使用；持续失败建议联系平台处理。**不要自动重试相同兑换码**。
+- `redeem_timeout`（exit 20）：交互式等待输入超时（默认约 10 分钟）。重新发起并提醒用户及时输入。
+
+AI agent / 非交互终端**不要裸跑 `credits redeem`**（会因为无法读取输入直接报 `argument_error`），应让用户提供兑换码后用 `--code` 传入：
+
+```bash
+lj-awb credits redeem --code <code>    # 兑换成功后会顺带展示最新积分余额
+```
+
+兑换是会改账户积分的写操作，执行前先与用户确认；可先 `--dry-run` 预览将要提交的兑换码。

package/skills/lj-awb/references/output-fields.md

@@ -31,6 +31,8 @@
 |------------|------|-----------|--------------|--------|
 | `credits_balance` | `credits balance` | `billingPointBalance`、`projectBudgetBalance`、`projectBudgetMax` | — | `currentProjectGroupNo` |
 | `credits_usage` | `credits usage` | `pointTotal`、`scannedTaskCount`、`buckets[]` 汇总 | `tasks[]`（若 `--include-tasks`） | sinceMs/untilMs 原值 |
+| `purchase_guide` | `credits buy` | `purchaseUrl` | — | — |
+| `redeem_result` | `credits redeem` | `redeemed`、`billingPointBalance` | `redemptionCode` | `currentProjectGroupNo` |
 
 > 永远优先看 `billingPointBalance`（可扣积分）；`projectBudgetBalance` 是项目预算 / ROI 约束，不要混为一谈。