@lumenkey/cli 0.2.1 → 0.2.3

package/README.md

@@ -31,6 +31,10 @@ 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 保护。
+
+配置必须使用独立的普通文件/目录。`config.json` 的符号链接、硬链接或 `.lumenkey` 链接目录会被拒绝并返回 `CONFIG_UNSAFE_PATH`，不是目录不可写；不会修改链接目标。请先备份，再使用普通的私有文件/目录，不要放宽权限绕过保护。
+
 ---
 
 ## 💻 命令行模式 (CLI Usage)
@@ -70,7 +74,19 @@ 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`），请原样处理。
+
+从 0.2.3 起，CLI `--json` 失败输出统一提供 `ok:false`、`code`、`message`；任务失败另带实际 `jobStatus`。`message` 是便于展示的原因，`code` 供脚本判断；旧 `error`、`status`、`failureCode`、`failureMessage` 字段保留。等待超时使用 `waitStatus:"TIMEOUT"`，兼容旧 `status:"TIMEOUT"`，不凭空推断任务失败。图片/视频非法 `--max-credits` 返回 `CREDIT_LIMIT_INVALID`，聊天保持 `CHAT_CREDIT_LIMIT_INVALID`。MCP 工具既有文本/任务结果结构不因此更换。
+
+图片、视频、`tasks wait` 共用轮询逻辑，默认间隔 5 秒、等待 1800 秒。间隔必须大于 0，指定 25 秒不会被缩短到 10 秒。等待时长是两次请求之间检查的预算，不会中断已发出的单次查询；单次网关请求另受 `LUMENKEY_TIMEOUT_MS` 控制。超时带 `WAIT_TIMEOUT`、`timedOut: true` 和任务号；不取消任务、不代表退款。
+
+CLI 的 `--interval` / `--timeout` 单位都是**秒**，MCP 的 `intervalMs` / `timeoutMs` 则是**毫秒**。CLI 小于 1 秒的正数间隔仍可使用，但 stderr 会提示 `POLL_INTERVAL_SHORT`；例如 `--interval 0.001` 是 1 毫秒，不是 1 秒。建议使用默认 5 秒；警告不会混入 JSON stdout。
+
+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 保留生成成功和下载警告。请用结果地址另存，不要为下载失败重新提交付费生成。下载中断时也保留这些结果。
+
+`--output` 必须是包含文件名的路径；目标为目录时返回 `DOWNLOAD_IS_DIRECTORY`，已有普通文件则返回 `DOWNLOAD_EXISTS`，不会覆盖或删除它们。
 
 ### 4. 查看账户算力余额
 ```bash
@@ -81,7 +97,7 @@ 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` 明确旁路的请求不使用该代理。
 
@@ -149,6 +165,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 自身也可能有工具调用时限，需独立设置；客户端不会因此承诺服务端任务已取消。
+
 ---
 
 ## 🏗️ 架构与底层协议
@@ -156,7 +174,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

@@ -6,7 +6,7 @@ export declare function rawOption(names: string[], argv?: string[]): string | un
 export declare function applyRaw(options: Record<string, unknown>, key: string, names: string[]): void;
 export declare function emit(data: unknown, human: () => void, argv?: string[]): void;
 export declare function rejectEmptyIdempotencyKey(): void;
-export declare function parseMaxCredits(value: unknown, label?: string): number | undefined;
+export declare function parseMaxCredits(value: unknown, label?: string, code?: string): number | undefined;
 export declare function quoteCreditLimitError(label?: string): Error;
 export declare function dryRunPreview(modelId: string, input: Record<string, unknown>, model: ModelItem, confirm?: unknown): Record<string, unknown>;
 export declare function submitQuote(modelId: string, input: Record<string, unknown>, options: Record<string, unknown>): Promise<{
@@ -27,7 +27,7 @@ export declare function outputUrls(detail: {
 export declare function parsePollOptions(options: {
     interval?: unknown;
     timeout?: unknown;
-}): {
+}, warnShort?: boolean): {
     initialIntervalMs: number;
     timeoutMs: number;
 };
@@ -35,6 +35,11 @@ export declare function pollConfirmed(api: LumenKeyClient, jobId: string, option
     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":"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"}
+{"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, 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,14 +68,14 @@ 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') {
+export function parseMaxCredits(value, label = '--max-credits', code = 'CREDIT_LIMIT_INVALID') {
     if (value === undefined)
         return undefined;
     if ((typeof value !== 'string' && typeof value !== 'number') || !/^\d+$/.test(String(value)) || !Number.isSafeInteger(Number(value))) {
-        throw new LumenKeyError('CHAT_CREDIT_LIMIT_INVALID', undefined, undefined, spendingCapSentence(label));
+        throw new LumenKeyError(code, undefined, undefined, spendingCapSentence(label));
     }
     return Number(value);
 }
@@ -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);
@@ -266,7 +273,7 @@ export function registerCopied(cli) {
             throw new LumenKeyError('MODEL_REQUIRED');
         if (isBlankPrompt(options.prompt))
             throw new Error(blankPromptSentence('flag'));
-        parsePollOptions(options);
+        parsePollOptions(options, true);
         client().requireKey();
         parseMaxCredits(options.maxCredits);
         rejectEmptyIdempotencyKey();
@@ -289,20 +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);
-        const savedPath = urls[0] && typeof options.output === 'string' && options.output
-            ? await downloadFile(urls[0], options.output) : undefined;
-        if (wantsJson()) {
-            console.log(JSON.stringify({ submitted: true, idempotencyKey: created.idempotencyKey, status: detail.status, urls, localFile: savedPath }));
-            return;
-        }
-        for (const url of urls)
-            console.log(url);
-        if (savedPath) {
-            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>')
@@ -314,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, true);
+            const detail = await withCliWait(jobId, signal => waitForJob(client(), jobId, { intervalMs: timing.initialIntervalMs, timeoutMs: timing.timeoutMs, signal }));
+            emit({ ...detail, jobStatus: detail.status, 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}`));
@@ -362,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();
@@ -375,6 +348,9 @@ 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} 设置密钥。`)));
@@ -383,13 +359,13 @@ export function registerCopied(cli) {
         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 Error(ui(`Profile ${action} needs a name.`, `profile ${action} 需要名称。`));
+            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;
         }
@@ -426,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;
         }
@@ -460,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;
@@ -487,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;
         }
@@ -498,7 +474,7 @@ export function registerCopied(cli) {
         .action(async (options) => {
         const config = loadConfig();
         const checks = [
-            { name: 'cli', status: 'pass', version: '0.2.1' },
+            { 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 },
@@ -515,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}`));
@@ -530,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);
     });
 }
@@ -560,38 +536,114 @@ function coerceDeclared(spec, value, key) {
 export function outputUrls(detail) {
     return (detail.outputs ?? []).map((item) => item.url).filter((url) => typeof url === 'string' && url.length > 0);
 }
-export function parsePollOptions(options) {
+export function parsePollOptions(options, warnShort = false) {
     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 || timeout * 1000 > Number.MAX_SAFE_INTEGER - Date.now()) {
+    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');
     }
+    if (warnShort && interval < 1)
+        process.stderr.write(ui('Warning [POLL_INTERVAL_SHORT]: --interval uses seconds. Values below 1 second may cause excessive polling; consider --interval 5.\n', '警告 [POLL_INTERVAL_SHORT]：--interval 单位为秒。小于 1 秒可能导致过于频繁的查询；建议使用 --interval 5。\n'));
     return { initialIntervalMs: interval * 1000, timeoutMs: timeout * 1000 };
 }
 export async function pollConfirmed(api, jobId, options) {
     const timing = parsePollOptions(options);
-    const onSigint = () => {
-        api.cancelJob(jobId).catch(() => undefined).finally(() => process.exit(130));
-    };
-    process.once('SIGINT', onSigint);
+    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, {
-            ...timing,
-            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 failureResult = failure ? errorResult(failure) : undefined;
+    const result = { ...detail, jobStatus: detail.status, ...(failureResult ? {
+            ok: false, code: failureResult.code, message: failureResult.message,
+            failureCode: failureResult.code, failureMessage: failureResult.message,
+        } : {}) };
+    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) => {
@@ -606,7 +658,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: ', '请输入密钥：'));
         });
@@ -681,14 +733,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();
     });