@lumenkey/cli 0.2.0 → 0.2.2

package/README.md

@@ -16,6 +16,8 @@
 
 ## 📦 极速上手 (Quick Start)
 
+运行环境：Node.js **20.18.1 或更新**（建议使用当前 Node LTS）。CLI 与 MCP 需使用同一已安装版本；升级后请重启 IDE 的 MCP 进程。
+
 ### 1. 认证配置
 
 可通过环境变量或配置命令设置您的 API Key：
@@ -29,6 +31,8 @@ export LUMENKEY_API_KEY="lk_live_xxxxxxxx"
 npx @lumenkey/cli login --key lk_live_xxxxxxxx
 ```
 
+也可运行 `lumenkey login` 交互输入（不回显），或从标准输入传入一行密钥；不要把真实密钥写进命令历史。`login` 只保存显式输入的字段，不把本次进程的网关、超时等环境变量固化到配置。损坏的 `config.json` / `profiles.json` 会报错并保留原文件，请先备份再修正；不会当成空档案覆盖。POSIX 上保存文件权限为 0600，Windows 仍应由用户目录 ACL 保护。
+
 ---
 
 ## 💻 命令行模式 (CLI Usage)
@@ -42,6 +46,8 @@ npx @lumenkey/cli models
 npx @lumenkey/cli models --type video
 ```
 
+目录价格用于浏览模型，不等于具体参数及账户条件下的最终报价。图像/视频请先不带 `--confirm` 报价，以服务端返回的 `credits` 为准；客户端不自行改价或补算账户折扣。目录参数以 `lumenkey model explain <modelId>` 为准，错误值不会原样写入报错。
+
 ### 2. 视频先报价，确认后生成
 不加 `--confirm` 只报价，不提交生成任务。参数与默认值由所选模型目录决定；不要把某个模型的规格套用到其他模型。
 
@@ -66,7 +72,13 @@ npx @lumenkey/cli status <jobId>
 npx @lumenkey/cli --json status <jobId>
 ```
 
-`status` 和 `tasks progress` 默认显示可读的任务/模型/状态；脚本应显式加 `--json`。等待超时以退出码 1 结束，不会自动取消任务，也不代表已退款。`tasks wait --json` 保留 `status: "TIMEOUT"`、`ok: false`、`timedOut: true`，同时带 `code: "WAIT_TIMEOUT"`。
+`status` 和 `tasks progress` 默认显示可读的任务/模型/状态；脚本应显式加 `--json`。失败任务仍返回原始任务详情和 `error.code`，同时以退出码 1 结束。网关请求失败等命令错误统一返回 `error`、`code`、`type`，有 HTTP 状态时另带 `httpStatus`。任务错误码可能为小写（例如 `provider_error`），请原样处理。
+
+图片、视频、`tasks wait` 共用轮询逻辑，默认间隔 5 秒、等待 1800 秒。间隔必须大于 0，指定 25 秒不会被缩短到 10 秒。等待时长是两次请求之间检查的预算，不会中断已发出的单次查询；单次网关请求另受 `LUMENKEY_TIMEOUT_MS` 控制。超时带 `WAIT_TIMEOUT`、`timedOut: true` 和任务号；不取消任务、不代表退款。
+
+Ctrl+C / SIGTERM 只停止本机等待或下载，不调用取消接口；分别以 130 / 143 退出并保留恢复查询信息。取消任务必须显式运行 `tasks cancel <jobId> --yes`（MCP 使用 `yes: true`）。
+
+`--output` 下载不覆盖已有文件，单次限 120 秒、128 MiB。生成成功但保存失败时，仍返回 `status: "succeeded"`、`jobId`、`idempotencyKey` 和全部 `urls`，另带 `download: {ok:false,code,error}`；CLI 以 1 退出表示本机保存失败，MCP 保留生成成功和下载警告。请用结果地址另存，不要为下载失败重新提交付费生成。下载中断时也保留这些结果。
 
 ### 4. 查看账户算力余额
 ```bash
@@ -77,7 +89,11 @@ npx @lumenkey/cli balance
 
 `LUMENKEY_BASE_URL`、config.json 的 baseUrl、当前档案 host 按顺序选择，最后才使用默认网关。所选地址会裁掉首尾空白并移除一个尾部 `/v1`；显式设置空字符串会报错，不会悄悄切回默认站点。`doctor` 默认只做本地检查，`--online` 才读取网关余额。
 
-网关请求支持 HTTP(S) 代理：`https_proxy`/`HTTPS_PROXY`、`http_proxy`/`HTTP_PROXY`、`all_proxy`/`ALL_PROXY`。HTTPS 优先专属 HTTPS 代理，再回落 HTTP、ALL；HTTP 优先 HTTP，再回落 ALL。对应的小写变量优先；`no_proxy`/`NO_PROXY` 支持显式旁路。ALL 是回落项，不覆盖专属代理。SOCKS 等未支持协议报 `PROXY_PROTOCOL_UNSUPPORTED`，不会静默直连；代理地址和其中的凭据不写入报错。
+网关请求和产物下载共用 HTTP(S) 代理规则：`https_proxy`/`HTTPS_PROXY`、`http_proxy`/`HTTP_PROXY`、`all_proxy`/`ALL_PROXY`。HTTPS 优先专属 HTTPS 代理，再回落 HTTP、ALL；HTTP 优先 HTTP，再回落 ALL。对应的小写变量优先；`no_proxy`/`NO_PROXY` 支持显式旁路。ALL 是回落项，不覆盖专属代理。SOCKS 等未支持协议报 `PROXY_PROTOCOL_UNSUPPORTED`，不会静默直连；代理地址和其中的凭据不写入报错。产物请求不携带网关认证信息，也不跟随重定向。
+
+代理地址只能包含源地址（可带代理认证信息），不能附加 `/gw` 等路径、查询或片段；无效时返回 `PROXY_URL_INVALID`。`NO_PROXY` 明确旁路的请求不使用该代理。
+
+聊天返回 HTTP 5xx 且没有 `billing` 时，客户端会明确提示结算状态未知、算力点可能仍被冻结；不会承诺已释放、扣费为零或自动重试。服务端带回的 `SETTLED` / `RELEASED` / `PENDING` 仍是结算依据。目录查询失败不会被误写成聊天冻结。
 
 ---
 
@@ -141,6 +157,8 @@ claude mcp add lumenkey npx -y @lumenkey/cli mcp
 | `lumenkey_tasks_wait` | 等待已有任务，不新建任务 |
 | `lumenkey_tasks_cancel` | 传 `yes: true` 请求取消；不承诺退款 |
 
+`lumenkey_generate_image` / `lumenkey_generate_video` 支持可选 `intervalMs`、`timeoutMs`，与 CLI 共用默认 5000 / 1800000 毫秒；省略 `confirm` 仍然只报价。等待超时后可用 `lumenkey_query_job` 或 `lumenkey_tasks_progress` 继续查询。IDE 自身也可能有工具调用时限，需独立设置；客户端不会因此承诺服务端任务已取消。
+
 ---
 
 ## 🏗️ 架构与底层协议
@@ -148,7 +166,7 @@ claude mcp add lumenkey npx -y @lumenkey/cli mcp
 遵循光钥华语站/国际站 OpenAPI 标准：
 1. `POST /v1/generation-quotes`：获取单次生成报价与算力预扣凭据；
 2. `POST /v1/generation-jobs`：附带 `Idempotency-Key` 幂等创建异步作业；
-3. `GET /v1/generation-jobs/{jobId}`：指数退避轮询任务状态；
+3. `GET /v1/generation-jobs/{jobId}`：按指定间隔轮询，只有可重试错误才退避；
 4. `POST /v1/generation-jobs/{jobId}/cancel`：显式取消任务；等待超时不自动调用此接口。
 
 ---

package/dist/cli/copied.d.ts

@@ -24,10 +24,22 @@ export declare function outputUrls(detail: {
         url?: string;
     }>;
 }): string[];
+export declare function parsePollOptions(options: {
+    interval?: unknown;
+    timeout?: unknown;
+}): {
+    initialIntervalMs: number;
+    timeoutMs: number;
+};
 export declare function pollConfirmed(api: LumenKeyClient, jobId: string, options: {
     interval?: unknown;
     timeout?: unknown;
 }): Promise<GenerationJobDetail>;
+export declare function finishGeneration(api: LumenKeyClient, created: {
+    jobId: string;
+    idempotencyKey: string;
+}, options: Record<string, unknown>): Promise<void>;
+export declare function emitJobDetail(detail: GenerationJobDetail): void;
 export declare function promptForKey(): Promise<string | undefined>;
 export declare function readSecret(input?: NodeJS.ReadStream, output?: NodeJS.WritableStream): Promise<string>;
 //# sourceMappingURL=copied.d.ts.map

package/dist/cli/copied.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"copied.d.ts","sourceRoot":"","sources":["../../src/cli/copied.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAE/B,OAAO,EAAE,cAAc,EAAoC,MAAM,mBAAmB,CAAC;AASrF,OAAO,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AASvE,wBAAgB,SAAS,CAAC,IAAI,WAAe,GAAG,OAAO,CAEtD;AAOD,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,IAAI,WAAe,GAAG,MAAM,GAAG,SAAS,CAYlF;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAS7F;AAED,wBAAgB,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,IAAI,EAAE,IAAI,WAAe,GAAG,IAAI,CAMhF;AAYD,wBAAgB,yBAAyB,IAAI,IAAI,CAGhD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,SAAkB,GAAG,MAAM,GAAG,SAAS,CAM3F;AAED,wBAAgB,qBAAqB,CAAC,KAAK,SAAkB,GAAG,KAAK,CAEpE;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAS3I;AAED,wBAAsB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAC,CAyBnL;AAmCD,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,KAAK,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,CAAC,CAiBnO;AAsBD,wBAAgB,cAAc,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,CAwT7C;AAsBD,wBAAgB,UAAU,CAAC,MAAM,EAAE;IAAE,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,GAAG,MAAM,EAAE,CAElF;AAED,wBAAsB,aAAa,CAAC,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAmBxJ;AAED,wBAAsB,YAAY,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAGhE;AAED,wBAAsB,UAAU,CAC9B,KAAK,GAAE,MAAM,CAAC,UAA0B,EACxC,MAAM,GAAE,MAAM,CAAC,cAA+B,GAC7C,OAAO,CAAC,MAAM,CAAC,CA6DjB"}
+{"version":3,"file":"copied.d.ts","sourceRoot":"","sources":["../../src/cli/copied.ts"],"names":[],"mappings":"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"}

package/dist/cli/copied.js

@@ -1,15 +1,18 @@
 import crypto from 'node:crypto';
 import os from 'node:os';
 import { describeKey, loadConfig } from '../core/config.js';
-import { LumenKeyClient, LumenKeyError, validateModelType } from '../core/client.js';
-import { blankPromptSentence, errorSentence, isBlankPrompt, jobStatusText, missingModelSentence, quoteCapSentence, spendingCapSentence, ui, waitTimeoutDetail } from '../core/locale.js';
+import { assertIdempotencyKey, LumenKeyClient, LumenKeyError, validateModelType } from '../core/client.js';
+import { blankPromptSentence, errorSentence, isBlankPrompt, jobStatusText, missingModelSentence, quoteCapSentence, spendingCapSentence, ui } from '../core/locale.js';
 import { formatJobDetail } from '../core/job-display.js';
 import { normalizeGatewayOrigin } from '../core/origin.js';
 import { explainModel, findModels } from '../core/explain.js';
-import { applyKeyValues, asPairs, validateKnownEnums } from '../core/set-values.js';
+import { applyKeyValues, asPairs, modelParameterError, validateKnownEnums } from '../core/set-values.js';
 import { createProfile, currentProfile, deleteProfile, listProfiles, ProfileMissingError, publicProfile, setNamedProfileFields, setProfile, setProfileFields, unsetProfile } from '../core/profiles.js';
 import { waitForJob } from '../core/wait.js';
-import { assertJobResult, downloadFile, pollJob } from '../core/poller.js';
+import { assertJobResult, pollJob } from '../core/poller.js';
+import { generationResult } from '../core/generation-result.js';
+import { packageVersion } from '../core/version.js';
+import { errorResult } from '../core/error-result.js';
 const COMPLETIONS = {
     bash: `_lumenkey() {\n  local cur prev\n  cur="\${COMP_WORDS[COMP_CWORD]}"\n  prev="\${COMP_WORDS[COMP_CWORD-1]}"\n  case "$prev" in\n    model) COMPREPLY=( $(compgen -W "search get explain" -- "$cur") ) ;;\n    image) COMPREPLY=( $(compgen -W "generate" -- "$cur") ) ;;\n    tasks) COMPREPLY=( $(compgen -W "progress wait cancel" -- "$cur") ) ;;\n    profile) COMPREPLY=( $(compgen -W "list create set unset key host delete" -- "$cur") ) ;;\n    auth) COMPREPLY=( $(compgen -W "profile" -- "$cur") ) ;;\n    *) COMPREPLY=( $(compgen -W "login models video status balance chat mcp model image tasks profile auth doctor completion" -- "$cur") ) ;;\n  esac\n}\ncomplete -F _lumenkey lumenkey\n`,
     zsh: `#compdef lumenkey\n_lumenkey() {\n  if (( CURRENT == 2 )); then\n    compadd login models video status balance chat mcp model image tasks profile auth doctor completion\n  elif [[ \${words[2]} == model ]]; then\n    compadd search get explain\n  elif [[ \${words[2]} == image ]]; then\n    compadd generate\n  elif [[ \${words[2]} == tasks ]]; then\n    compadd progress wait cancel\n  fi\n}\ncompdef _lumenkey lumenkey\n`,
@@ -65,8 +68,8 @@ function propertiesOf(model) {
 }
 export function rejectEmptyIdempotencyKey() {
     const rawKey = rawOption(['--idempotency-key']);
-    if (rawKey !== undefined && !rawKey.trim())
-        throw new Error(ui('--idempotency-key must not be empty.', '幂等键不能为空。'));
+    if (rawKey !== undefined)
+        assertIdempotencyKey(rawKey);
 }
 export function parseMaxCredits(value, label = '--max-credits') {
     if (value === undefined)
@@ -111,8 +114,12 @@ export async function submitQuote(modelId, input, options) {
         });
         return;
     }
-    const provided = options.idempotencyKey == null ? '' : String(options.idempotencyKey).trim();
-    const key = provided || crypto.randomUUID();
+    if (options.idempotencyKey !== undefined) {
+        if (typeof options.idempotencyKey !== 'string')
+            throw new LumenKeyError('IDEMPOTENCY_INPUT_INVALID');
+        assertIdempotencyKey(options.idempotencyKey);
+    }
+    const key = options.idempotencyKey === undefined ? crypto.randomUUID() : String(options.idempotencyKey);
     console.error(ui('Submitting generation job...', '正在提交生成任务...'));
     const projectId = options.projectId == null || options.projectId === '' ? undefined : String(options.projectId);
     const job = await api.createJob({ quoteId: quote.quoteId, projectId, input }, key);
@@ -120,11 +127,6 @@ export async function submitQuote(modelId, input, options) {
         emit({ ...job, idempotencyKey: key, submitted: true }, () => console.log(ui(`Job created: ${job.jobId}`, `任务已创建：${job.jobId}`)));
     return { jobId: job.jobId, idempotencyKey: key };
 }
-function parameterLabel(key) {
-    if (key === 'aspect_ratio' || key === 'ratio')
-        return 'aspect ratio';
-    return key;
-}
 function hasDeclared(properties, key) {
     return Object.prototype.hasOwnProperty.call(properties, key);
 }
@@ -136,24 +138,24 @@ function assignAspect(properties, input, fields) {
     const hasAspect = hasDeclared(properties, 'aspect_ratio');
     const hasRatio = hasDeclared(properties, 'ratio');
     if (!hasAspect && !hasRatio)
-        throw new Error(`This model has no ${parameterLabel('aspect_ratio')} parameter.`);
+        throw modelParameterError('MODEL_PARAM_UNKNOWN', 'aspect_ratio');
     if (hasAspect && aspect !== undefined)
-        input.aspect_ratio = coerceDeclared(properties.aspect_ratio, aspect);
+        input.aspect_ratio = coerceDeclared(properties.aspect_ratio, aspect, 'aspect_ratio');
     if (hasRatio && ratio !== undefined)
-        input.ratio = coerceDeclared(properties.ratio, ratio);
+        input.ratio = coerceDeclared(properties.ratio, ratio, 'ratio');
     if (input.aspect_ratio === undefined && input.ratio === undefined) {
         const name = hasAspect ? 'aspect_ratio' : 'ratio';
         const value = aspect !== undefined ? aspect : ratio;
-        input[name] = coerceDeclared(properties[name], value);
+        input[name] = coerceDeclared(properties[name], value, name);
     }
 }
 function assignDeclared(properties, input, key, value) {
     if (!hasDeclared(properties, key))
-        throw new Error(`This model has no ${parameterLabel(key)} parameter.`);
+        throw modelParameterError('MODEL_PARAM_UNKNOWN', key);
     const spec = properties[key];
     const type = spec && typeof spec === 'object' && !Array.isArray(spec) ? spec.type : undefined;
     const scalar = value === null || value === undefined || typeof value !== 'object';
-    input[key] = scalar && (type === 'integer' || type === 'number' || type === 'string') ? coerceDeclared(spec, value) : value;
+    input[key] = scalar && (type === 'integer' || type === 'number' || type === 'string') ? coerceDeclared(spec, value, key) : value;
 }
 export async function buildGenerationInput(modelId, fields, pairs, known) {
     client().requireKey();
@@ -161,7 +163,7 @@ export async function buildGenerationInput(modelId, fields, pairs, known) {
         throw new Error(blankPromptSentence('flag'));
     const model = known?.id === modelId ? known : (await client().listModels()).find((item) => item.id === modelId);
     if (!model)
-        throw new LumenKeyError('MODEL_NOT_IN_CATALOG', undefined, undefined, `Model ${JSON.stringify(modelId)} is not in your available catalog. Use an exact model ID.`);
+        throw new LumenKeyError('MODEL_NOT_IN_CATALOG');
     const properties = propertiesOf(model);
     const defined = Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined));
     const input = {};
@@ -271,6 +273,7 @@ export function registerCopied(cli) {
             throw new LumenKeyError('MODEL_REQUIRED');
         if (isBlankPrompt(options.prompt))
             throw new Error(blankPromptSentence('flag'));
+        parsePollOptions(options);
         client().requireKey();
         parseMaxCredits(options.maxCredits);
         rejectEmptyIdempotencyKey();
@@ -293,19 +296,7 @@ export function registerCopied(cli) {
         const created = await submitQuote(String(options.model), built.input, { ...options, schemaProperties: built.properties, suppressEmit: wantsJson() && Boolean(options.confirm) });
         if (!created)
             return;
-        const detail = await pollConfirmed(client(), created.jobId, options);
-        assertJobResult(detail, true);
-        const urls = outputUrls(detail);
-        if (wantsJson()) {
-            console.log(JSON.stringify({ submitted: true, idempotencyKey: created.idempotencyKey, status: detail.status, urls }));
-            return;
-        }
-        for (const url of urls)
-            console.log(url);
-        if (urls[0] && typeof options.output === 'string' && options.output) {
-            const savedPath = await downloadFile(urls[0], options.output);
-            console.log(ui(`Saved to ${savedPath}`, `已保存到 ${savedPath}`));
-        }
+        await finishGeneration(client(), created, options);
     });
     cli.command('tasks <action> <jobId>', ui('tasks progress | wait | cancel', '查看进度、等待或取消任务'))
         .example('lumenkey tasks progress <jobId>')
@@ -317,41 +308,20 @@ export function registerCopied(cli) {
         .action(async (action, jobId, options) => {
         if (action === 'progress') {
             const detail = await client().getJob(jobId);
-            assertJobResult(detail, detail.status === 'succeeded');
-            emit(detail, () => console.log(formatJobDetail(detail)));
+            emitJobDetail(detail);
             return;
         }
         if (action === 'wait') {
-            const interval = Number(options.interval);
-            const timeout = Number(options.timeout);
-            if (!Number.isFinite(interval) || interval < 0 || !Number.isFinite(timeout) || timeout < 0)
-                throw new Error(ui('--interval and --timeout must be non-negative numbers.', '--interval 和 --timeout 必须是非负数。'));
-            if (interval * 1000 > 2_147_483_647)
-                throw new Error(ui('--interval must be between 0 and 2147483 seconds.', '--interval 必须在 0 到 2147483 秒之间。'));
-            try {
-                const detail = await waitForJob(client(), jobId, { intervalMs: interval * 1000, timeoutMs: timeout * 1000 });
-                const failed = detail.error != null || ['failed', 'rejected', 'cancelled', 'expired'].includes(detail.status);
-                const body = { ...detail, ok: detail.status === 'succeeded' && !failed, timedOut: false };
-                emit(body, () => console.log(formatJobDetail(detail)));
-                if (!body.ok)
-                    process.exitCode = 1;
-                return;
-            }
-            catch (err) {
-                if (err instanceof LumenKeyError && err.code === 'WAIT_TIMEOUT') {
-                    const body = { status: 'TIMEOUT', ok: false, timedOut: true, jobId, code: 'WAIT_TIMEOUT' };
-                    emit(body, () => console.error(new LumenKeyError('WAIT_TIMEOUT', undefined, undefined, waitTimeoutDetail(jobId, timeout * 1000)).message));
-                    process.exitCode = 1;
-                    return;
-                }
-                throw err;
-            }
+            const timing = parsePollOptions(options);
+            const detail = await withCliWait(jobId, signal => waitForJob(client(), jobId, { intervalMs: timing.initialIntervalMs, timeoutMs: timing.timeoutMs, signal }));
+            emit({ ...detail, ok: true, timedOut: false }, () => console.log(formatJobDetail(detail)));
+            return;
         }
         if (action === 'cancel') {
             if (!options.yes)
-                throw new Error(ui('Refusing to cancel without --yes.', '未加 --yes，拒绝取消。'));
+                throw new LumenKeyError('CANCEL_CONFIRMATION_REQUIRED');
             const result = await client().cancelJob(jobId);
-            emit(result, () => console.log(JSON.stringify(result)));
+            emit(result, () => console.log(ui(`Cancellation requested for ${jobId}. Settlement is determined by the gateway.`, `已请求取消任务 ${jobId}，最终结算由网关确认。`)));
             return;
         }
         throw new Error(ui(`Unknown tasks command: ${action}`, `未知的 tasks 子命令：${action}`));
@@ -365,7 +335,7 @@ export function registerCopied(cli) {
         if (extra.length || (value !== undefined && ['list', 'unset'].includes(action)))
             throw new LumenKeyError('CLI_ARGUMENTS_INVALID');
         if (!['list', 'create', 'set', 'unset', 'key', 'host', 'delete'].includes(action)) {
-            throw new Error(ui(`Unknown profile command: ${action}`, `未知的 profile 子命令：${action}`));
+            throw new LumenKeyError('CLI_ARGUMENTS_INVALID', undefined, undefined, ui(`Unknown profile command: ${action}`, `未知的 profile 子命令：${action}`));
         }
         if (action === 'list') {
             const listed = listProfiles();
@@ -378,17 +348,24 @@ export function registerCopied(cli) {
             return;
         }
         if (action === 'key') {
+            const target = value ?? currentProfile().name;
+            if (!target || !listProfiles().profiles.some(row => row.profile === target))
+                throw new ProfileMissingError(target ?? ui('(active profile)', '（当前档案）'));
             const key = await readProfileKey();
             const name = value ? (setNamedProfileFields(value, { key }), value) : setProfileFields({ key });
             emit({ profile: name, hasStoredToken: true }, () => console.log(ui(`Key set for profile ${name}.`, `已为档案 ${name} 设置密钥。`)));
             return;
         }
-        if (!value)
-            throw new Error(ui(`Profile ${action} needs a name.`, `profile ${action} 需要名称。`));
+        if (action === 'host' && value === undefined)
+            throw new LumenKeyError('CLI_ARGUMENTS_INVALID', undefined, undefined, ui('Profile host needs a gateway address. Use profile host <address>.', 'profile host 需要网关地址。请使用 profile host <地址>。'));
+        if (action !== 'host' && !value)
+            throw new LumenKeyError('CLI_ARGUMENTS_INVALID', undefined, undefined, ui(`Profile ${action} needs a name.`, `profile ${action} 需要名称。`));
+        if (value === undefined)
+            throw new LumenKeyError('CLI_ARGUMENTS_INVALID');
         if (action === 'create') {
             const result = createProfile(value);
             if (result === 'exists')
-                throw new Error(ui(`Profile ${value} already exists.`, `档案 ${value} 已存在。`));
+                throw new LumenKeyError('PROFILE_EXISTS');
             emit({ name: value, created: true }, () => console.log(ui(`Profile ${value} created.`, `已创建档案 ${value}。`)));
             return;
         }
@@ -425,7 +402,7 @@ export function registerCopied(cli) {
         if (action === 'delete') {
             const removed = deleteProfile(value);
             if (!removed)
-                throw new Error(ui(`Profile ${value} does not exist.`, `档案 ${value} 不存在。`));
+                throw new ProfileMissingError(value);
             emit({ deleted: true, name: value }, () => console.log(ui(`Profile ${value} deleted.`, `已删除档案 ${value}。`)));
             return;
         }
@@ -459,7 +436,7 @@ export function registerCopied(cli) {
                 : ui('Unknown auth profile command.', '未知的 auth profile 子命令。'));
         }
         if (!name)
-            throw new Error(ui(`Auth profile ${action} needs a name.`, `auth profile ${action} 需要名称。`));
+            throw new LumenKeyError('CLI_ARGUMENTS_INVALID', undefined, undefined, ui(`Auth profile ${action} needs a name.`, `auth profile ${action} 需要名称。`));
         if (action === 'use') {
             setProfile(name);
             const record = currentProfile().record;
@@ -486,7 +463,7 @@ export function registerCopied(cli) {
                 throw new Error(ui('Refusing to delete auth profile without --yes.', '未加 --yes，拒绝删除认证档案。'));
             const removed = deleteProfile(name);
             if (!removed)
-                throw new Error(ui(`Profile ${name} does not exist.`, `档案 ${name} 不存在。`));
+                throw new ProfileMissingError(name);
             emit({ deleted: true, name }, () => console.log(ui(`Auth profile ${name} deleted.`, `已删除认证档案 ${name}。`)));
             return;
         }
@@ -497,7 +474,7 @@ export function registerCopied(cli) {
         .action(async (options) => {
         const config = loadConfig();
         const checks = [
-            { name: 'cli', status: 'pass', version: '0.2.0' },
+            { name: 'cli', status: 'pass', version: packageVersion },
             { name: 'runtime', status: 'pass', value: process.version },
             { name: 'platform', status: 'pass', value: `${process.platform} ${os.release()}` },
             { name: 'host', status: hostStatus(config), value: config.baseUrl },
@@ -514,7 +491,7 @@ export function registerCopied(cli) {
         }
         const ok = checks.every((check) => check.status !== 'fail');
         emit({ ok, checks }, () => {
-            console.log(ui('cli: 0.2.0', '命令行：0.2.0'));
+            console.log(ui(`cli: ${packageVersion}`, `命令行：${packageVersion}`));
             console.log(ui(`runtime: ${process.version}`, `运行时：${process.version}`));
             console.log(ui(`platform: ${process.platform} ${os.release()}`, `平台：${process.platform} ${os.release()}`));
             console.log(ui(`host: ${config.baseUrl}`, `网关：${config.baseUrl}`));
@@ -529,9 +506,9 @@ export function registerCopied(cli) {
     });
     cli.command('completion <shell>', ui('Print a shell completion script', '打印 shell 补全脚本'))
         .action((shell) => {
-        const script = COMPLETIONS[shell];
+        const script = Object.hasOwn(COMPLETIONS, shell) ? COMPLETIONS[shell] : undefined;
         if (!script)
-            throw new Error(ui('Shell must be bash, zsh, tcsh, or fish.', 'shell 只能是 bash、zsh、tcsh 或 fish。'));
+            throw new LumenKeyError('CLI_ARGUMENTS_INVALID', undefined, undefined, ui('Shell must be bash, zsh, tcsh, or fish.', 'shell 只能是 bash、zsh、tcsh 或 fish。'));
         console.log(script);
     });
 }
@@ -544,12 +521,12 @@ function hostStatus(config) {
         return 'fail';
     }
 }
-function coerceDeclared(spec, value) {
+function coerceDeclared(spec, value, key) {
     const type = spec && typeof spec === 'object' && !Array.isArray(spec) ? spec.type : undefined;
     if (type === 'integer' || type === 'number') {
         const parsed = Number(value);
         if (!Number.isFinite(parsed))
-            throw new Error(`Invalid number: ${String(value)}`);
+            throw modelParameterError('MODEL_PARAM_INVALID', key);
         return type === 'integer' ? Math.trunc(parsed) : parsed;
     }
     if (type === 'string')
@@ -559,35 +536,108 @@ function coerceDeclared(spec, value) {
 export function outputUrls(detail) {
     return (detail.outputs ?? []).map((item) => item.url).filter((url) => typeof url === 'string' && url.length > 0);
 }
-export async function pollConfirmed(api, jobId, options) {
+export function parsePollOptions(options) {
     const interval = Number(options.interval ?? 5);
     const timeout = Number(options.timeout ?? 1800);
-    if (!Number.isFinite(interval) || interval < 0 || interval * 1000 > 2_147_483_647 || !Number.isFinite(timeout) || timeout < 0) {
-        throw new Error(ui('--interval and --timeout must be non-negative numbers.', '--interval 和 --timeout 必须是非负数。'));
+    if (!Number.isFinite(interval) || interval <= 0 || interval * 1000 > 2_147_483_647 || !Number.isFinite(timeout) || timeout < 0 || timeout * 1000 > Number.MAX_SAFE_INTEGER - Date.now()) {
+        throw new LumenKeyError('WAIT_OPTIONS_INVALID');
     }
-    const onSigint = () => {
-        api.cancelJob(jobId).catch(() => undefined).finally(() => process.exit(130));
-    };
-    process.once('SIGINT', onSigint);
+    return { initialIntervalMs: interval * 1000, timeoutMs: timeout * 1000 };
+}
+export async function pollConfirmed(api, jobId, options) {
+    const timing = parsePollOptions(options);
+    return withCliWait(jobId, signal => pollJob(api, jobId, {
+        ...timing, signal,
+        onProgress: row => process.stderr.write(ui(`  Status: ${jobStatusText(row.status)}\n`, `  状态：${jobStatusText(row.status)}\n`)),
+    }));
+}
+async function withCliWait(jobId, wait) {
+    const controller = new AbortController();
+    const interrupt = (exitCode) => { if (!controller.signal.aborted) {
+        process.exitCode = exitCode;
+        controller.abort();
+    } };
+    const sigint = () => interrupt(130);
+    const sigterm = () => interrupt(143);
+    process.on('SIGINT', sigint);
+    process.on('SIGTERM', sigterm);
     try {
-        return await pollJob(api, jobId, {
-            initialIntervalMs: interval * 1000,
-            timeoutMs: timeout * 1000,
-            onProgress: (row) => process.stderr.write(ui(`  Status: ${jobStatusText(row.status)}\n`, `  状态：${jobStatusText(row.status)}\n`)),
-        });
+        return await wait(controller.signal);
+    }
+    catch (error) {
+        const failure = error instanceof Error ? error : new LumenKeyError('CLI_COMMAND_FAILED');
+        Object.assign(failure, { jobId });
+        if (failure instanceof LumenKeyError && failure.code === 'WAIT_TIMEOUT')
+            Object.assign(failure, { timedOut: true });
+        if (controller.signal.aborted)
+            failure.message += ui(` Resume with: lumenkey status ${jobId}`, ` 可继续查询：lumenkey status ${jobId}`);
+        throw failure;
     }
     finally {
-        process.off('SIGINT', onSigint);
+        process.off('SIGINT', sigint);
+        process.off('SIGTERM', sigterm);
+    }
+}
+export async function finishGeneration(api, created, options) {
+    try {
+        const timing = parsePollOptions(options);
+        const result = await withCliWait(created.jobId, async (signal) => {
+            const detail = await pollJob(api, created.jobId, { ...timing, signal,
+                onProgress: row => process.stderr.write(ui(`  Status: ${jobStatusText(row.status)}\n`, `  状态：${jobStatusText(row.status)}\n`)),
+            });
+            return generationResult(detail, created.idempotencyKey, typeof options.output === 'string' ? options.output : undefined, signal);
+        });
+        emit(result, () => {
+            console.log(ui('Generation succeeded!', '生成成功！'));
+            console.log(ui(`Task: ${result.jobId}`, `任务：${result.jobId}`));
+            for (const url of result.urls)
+                console.log(url);
+            if (result.localFile)
+                console.log(ui(`Saved to ${result.localFile}`, `已保存到 ${result.localFile}`));
+            if (result.download?.ok === false)
+                console.error(ui(`Local save failed: ${result.download.error} (${result.download.code}). The generation result remains available above.`, `本机保存失败：${result.download.error}（${result.download.code}）。生成结果仍可通过以上地址获取。`));
+        });
+        if (result.download?.ok === false && process.exitCode !== 130 && process.exitCode !== 143)
+            process.exitCode = 1;
+    }
+    catch (error) {
+        const failure = error instanceof Error ? error : new LumenKeyError('CLI_COMMAND_FAILED');
+        Object.assign(failure, created);
+        throw failure;
     }
 }
+export function emitJobDetail(detail) {
+    let failure;
+    try {
+        assertJobResult(detail, detail.status === 'succeeded');
+    }
+    catch (error) {
+        failure = error instanceof Error ? error : new LumenKeyError('JOB_TERMINAL_FAILURE');
+    }
+    const result = failure ? { ...detail, failureCode: errorResult(failure).code, failureMessage: failure.message } : detail;
+    emit(result, () => {
+        console.log(formatJobDetail(detail));
+        if (failure)
+            console.error(failure.message);
+    });
+    if (failure)
+        process.exitCode = 1;
+}
 export async function promptForKey() {
-    if (!process.stdin.isTTY || process.stdin.readableEnded || process.stdin.destroyed)
+    if (process.stdin.readableEnded || process.stdin.destroyed)
         return undefined;
-    return readProfileKey();
+    try {
+        return await readProfileKey();
+    }
+    catch (error) {
+        if (!process.stdin.isTTY && error instanceof LumenKeyError && error.code === 'INPUT_CLOSED')
+            return undefined;
+        throw error;
+    }
 }
 export async function readSecret(input = process.stdin, output = process.stderr) {
     if (input.readableEnded || input.destroyed)
-        throw new Error(ui('stdin closed before an answer was given.', '输入密钥前标准输入已关闭。'));
+        throw new LumenKeyError('INPUT_CLOSED');
     if (!input.isTTY) {
         const { createInterface } = await import('node:readline');
         return new Promise((resolve, reject) => {
@@ -602,7 +652,7 @@ export async function readSecret(input = process.stdin, output = process.stderr)
                     resolve(line.trim());
             });
             reader.once('close', () => { if (!answered)
-                reject(new Error(ui('stdin closed before an answer was given.', '输入密钥前标准输入已关闭。'))); });
+                reject(new LumenKeyError('INPUT_CLOSED')); });
             reader.once('error', reject);
             output.write(ui('Enter the key: ', '请输入密钥：'));
         });
@@ -677,14 +727,14 @@ export async function readSecret(input = process.stdin, output = process.stderr)
 }
 async function ask(prompt) {
     if (process.stdin.readableEnded || process.stdin.destroyed)
-        throw new Error('stdin closed before an answer was given.');
+        throw new LumenKeyError('INPUT_CLOSED');
     const readline = await import('node:readline');
     const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
     return await new Promise((resolve, reject) => {
         let answered = false;
         rl.once('line', (line) => { answered = true; rl.close(); resolve(line); });
         rl.once('close', () => { if (!answered)
-            reject(new Error('stdin closed before an answer was given.')); });
+            reject(new LumenKeyError('INPUT_CLOSED')); });
         rl.setPrompt(prompt);
         rl.prompt();
     });