@lumenkey/cli 0.3.1 → 0.4.0-rc.1

package/README.md

@@ -1,6 +1,6 @@
 # @lumenkey/cli
 
-本版：**0.3.0**（CLI/MCP）；下文 0.2.3 均为已发布旧版的行为对照。
+本候选版：**0.4.0-rc.1**（CLI、MCP、本机 Studio、画布与 3D 导演台）；下文 0.2.3 均为旧版行为对照。候选版不代表已发布。
 
 > **光钥 (LumenKey) 官方 CLI 命令行工具 & 智能体 MCP (Model Context Protocol) 统一服务包**  
 > 一套代码同构支持：**人类终端命令行 (CLI)** 与 **AI Agent (Cursor / Claude Code / Codex / Antigravity) 原生工具挂载 (MCP Server)**。
@@ -103,6 +103,12 @@ CLI `--json` 与 MCP 工具结果使用**同一个结果对象**（MCP 的 `cont
 
 供人阅读的短 `message` 及 CLI 错误显示使用**执行机本机时区**，附 `±HH:MM` 偏移；例如 `2026-10-16 17:47 (-07:00)`。机器字段 `resumeDeadline` 保持 UTC。已过期、记录丢失或幂等冲突时不提供 `recoveryCommand`；先核对任务列表与余额，不能靠换键重提来解决 unknown。
 
+过期的待确认提交统一返回 `code: "SUBMISSION_RECORD_EXPIRED"`、`recovery: "expired"` 和原记录的 `resumeDeadline`，CLI 与 MCP 相同。提前拒绝时 `submission: "none"` 仅说明这次没有重发，不证明历史提交未受理；若请求发出后才超过窗口，仍保留 `submission: "unknown"`。两种情况都不提供 `recoveryCommand`，不自动创建新任务。
+
+内部待确认记录的绝对路径不会出现在 `message`、`detail`、`error`、通知或 stderr，损坏记录用 `record:<短哈希>` 定位。配置文件与用户指定的下载目标仍可通过明确的 `path` 字段及兼容的配置错误文本显示，便于用户修正自己的路径；下载底层异常不会直接透传。该例外不适用于内部提交记录。
+
+中文简繁跟随设备：`LC_ALL` → `LC_MESSAGES` → `LANG` → Windows UI 语言 → Intl locale；`zh-TW`、`zh-HK`、`zh-MO`、`zh-Hant` 使用繁体，其余回落简体。可用 `LUMENKEY_ZH_SCRIPT=Hans|Hant` 明确覆写。此设置只选择 CLI/MCP 内置文案表，不转换用户输入、路径、模型回复或错误码；`--lang en` / `LUMENKEY_LANG=en` 仍选择英文。
+
 **提交后的真金字段。** 只要请求了 `--confirm`，无论成功失败，结果都带 `submission`；一旦拿到报价就带 `quoteId`，一旦决定了幂等键就带 `idempotencyKey`（报价之前的失败——参数错误、没有密钥、目录不可写——只带 `submission:"none"`，没有键和报价）。`submission`：`"created"` 已创建任务（带 `jobId`）、`"none"` 什么都没创建（请求没发出，或网关返回了格式正确的 4xx）、`"unknown"` 请求已发出但没有拿到格式正确的回答（连接中断、客户端超时、任何 5xx、2xx 但响应不合约）。旧的布尔 `submitted` 只在成功结果上保留（报价 `false`、已建单 `true`），已标记弃用，不会出现在失败结果里。`"unknown"` 时网关可能已受理并冻结算力点：**不要换键重提**。客户端在 POST 前把这次提交（幂等键、quoteId、projectId、模型与输入、状态、网关地址与密钥的 SHA-256 指纹，不含密钥本身）原子写入 `~/.lumenkey/pending-submissions/`；记录只对创建它的账号和网关有效：换档案后不会自动接续别人的记录，显式带别人的键会本地返回 `SUBMISSION_CREDENTIALS_MISMATCH` 且不发请求、不动记录；同一账号换了密钥也不再匹配（记录保留并在 24 小时后过期）。观察到 `"unknown"` 后记录改为 unknown 状态。之后**用相同参数再次运行同一命令/同一工具调用**（不带键也可以）：客户端找到模型与输入完全相同、状态为 unknown 的最早记录，原样重发它的请求体而不是重新报价，结果带 `resumed: true`；显式带 `--idempotency-key <同一个键>`（MCP `idempotencyKey`）则直接重发该键的记录，参数不同返回 `SUBMISSION_RETRY_MISMATCH`，不发任何请求。仍在运行的进程的 in-flight 记录不会被自动接续（stderr 会提示它的键），所以并行提交多个相同生成仍会得到多个任务；被杀死进程留下的本机记录会被接续。**恢复动词**：`lumenkey tasks resume <幂等键>`（MCP `lumenkey_resume_submission`）把记录的请求体原样重发——不读目录、不重新报价、不接受任何生成参数——遵守同样的账号绑定、23 小时窗口和重放分类，返回同样的结果对象并带 `resumed: true`；模型下架或目录变更后仍可用它找回已有任务。显式带一个新键而本机已有相同输入的未确认记录时，不会用新键发送任何内容，而是返回 `SUBMISSION_PENDING_IDENTICAL`（`submission:"none"`）：结果里 `idempotencyKey` 仍是你提供的键，`pendingIdempotencyKey`、`pendingQuoteId`、`pendingRecordedAt`、`pendingAgeSeconds` 指出阻塞的那条记录，文案指引先运行 `tasks resume <那个键>`。在那条记录处理完或记录后 23 小时过期之前，无法创建第二个相同的任务（显式键的语义不会被覆盖）。`tasks` 的各子命令只接受自己的选项（`progress` 无，`wait` 为 `--interval/--timeout`，`cancel` 为 `--yes`，`resume` 为 `-o/--interval/--timeout/--key`），其他选项返回 `INPUT_INVALID`；以 `-` 开头的键用 `tasks resume --key=<键>` 或 `tasks resume -- <键>` 传入。同模型但输入不同的未确认记录、其他主机的记录、过期的记录都会在 stderr 和 `detail` 里点名，不会被静默跳过。重发时只有网关在建单步骤内给出的明确拒绝（如 `QUOTE_NOT_AVAILABLE`、`INSUFFICIENT_CREDITS`）才算 `"none"` 并删除记录；鉴权、限流等其他 4xx 不能说明第一次有没有建单，结果保持 `"unknown"`、记录保留。首次提交时也只有带业务码的 4xx 才算 `"none"`；没有业务码的 4xx（例如代理返回的 HTML）同样是 `"unknown"`。记录可接续的窗口是 23 小时（比网关的 24 小时幂等记录短一小时）：过期记录不再自动接续，显式带它的键会本地返回 `SUBMISSION_RECORD_EXPIRED` 且不发请求；过期记录保留到 48 小时以便报告，之后清理。`"unknown"` 结果里的恢复建议按磁盘上的真实状态给出：记录已标记为 unknown → 直接重跑即接续；记录仍是 in-flight（标记失败）→ 需显式带键；记录已不存在 → 核对任务列表与余额。被杀死的进程留下的 in-flight 记录（本机、进程已不存在）会被相同的重跑接续；仍在运行的进程的记录不会；其他主机的记录会在 stderr 和 `detail` 中提示但不接续。
 
 **写不进记录时不提交任务。** 在报价之前就会探测记录目录是否可写，失败返回 `SUBMISSION_JOURNAL_UNWRITABLE`（带目录与原因），不会买下报价。这意味着 0.2.3 在只读 HOME（容器、CI、`HOME=/nonexistent`）下仍可 `--confirm`，而本版本会拒绝；请设置 `LUMENKEY_JOURNAL_DIR=<可写目录>` 把待确认记录放到别处（目录以 0700 创建），记录不可关闭。任务创建成功后记录删不掉只会写进 `detail`，不会改变结果。`--json --confirm` 下任务一创建就向 stderr 写一行 `{"event":"job_created","jobId":…,"idempotencyKey":…,"quoteId":…}`，stdout 仍是单个 JSON 文档；人类模式在任务号旁打印幂等键。
@@ -119,7 +125,11 @@ Ctrl+C / SIGTERM 只停止本机等待或下载，不调用取消接口；分别
 
 `--output` 下载不覆盖已有文件，单次限 120 秒、128 MiB；目标目录里超过 1 小时的残留 `.part` 文件会被清理。生成成功但保存失败时，仍返回 `status: "succeeded"`、`jobId`、`idempotencyKey` 和全部 `urls`，另带 `download: {ok:false,code,error}`；CLI 以 1 退出表示本机保存失败，MCP 保留生成成功和下载警告。请用结果地址另存，不要为下载失败重新提交付费生成。下载中断时也保留这些结果。
 
-`--output` 必须是包含文件名的路径；目标为目录（包括指向目录的符号链接/junction）时返回 `DOWNLOAD_IS_DIRECTORY`，已有普通文件（或指向文件的链接）则返回 `DOWNLOAD_EXISTS`，不会覆盖、删除或穿过链接写入。目标目录链只在结果开始落盘时创建，保存失败会删掉本次创建的空目录；不支持硬链接的文件系统（exFAT、部分 SMB）自动改用独占复制，仍不覆盖。两个入口都把开头的 `~/` 展开为主目录（不展开 `~user`）；CLI 的相对路径按当前目录解析，MCP 的 `downloadPath` 必须是绝对路径或 `~/` 开头，否则在报价前返回 `DOWNLOAD_PATH_NOT_ABSOLUTE`（MCP 服务的工作目录不属于调用方）。下载目录白名单留待后续版本。
+`--output` 必须是包含文件名的路径；目标为目录（包括指向目录的符号链接/junction）时返回 `DOWNLOAD_IS_DIRECTORY`，已有普通文件（或指向文件的链接）则返回 `DOWNLOAD_EXISTS`，不会覆盖、删除或穿过链接写入。目标目录链只在结果开始落盘时创建，保存失败会删掉本次创建的空目录；不支持硬链接的文件系统（exFAT、部分 SMB）自动改用独占复制，仍不覆盖。两个入口都把开头的 `~/` 展开为主目录（不展开 `~user`）；CLI 的相对路径按当前目录解析，MCP 的 `downloadPath` 必须是绝对路径或 `~/` 开头，否则在报价前返回 `DOWNLOAD_PATH_NOT_ABSOLUTE`（MCP 服务的工作目录不属于调用方）。
+
+可设置绝对目录 `LUMENKEY_DOWNLOAD_ROOT` 限制 CLI/MCP 下载位置；该配置为相对路径时返回 `DOWNLOAD_ROOT_INVALID`，请修正环境变量，而非更换输出文件名。越界或任何 `..` 路径段返回 `DOWNLOAD_OUTSIDE_ROOT`，无法验证、子目录符号链接/junction 或硬链接目标返回 `DOWNLOAD_UNSAFE_PATH`。配置根目录本身按 realpath 规范化，根内子路径不能通过链接逃逸；报价前及写入/发布前复查。未设置时沿用调用方选择的目标父目录作为默认范围，**不默认限制在 cwd**；IDE 管理员需要固定白名单时应明确设置此变量。此限制不代替操作系统权限隔离，不能对抗具有同等文件系统写权限的进程在检查与系统调用之间恶意替换目录。
+
+行为变更：即使未设置 `LUMENKEY_DOWNLOAD_ROOT`，也不再接受带 `..` 路径段的下载路径（包括 `~/a/../file`）；请传不含上级跳转的目标路径。为兼容脚本仍使用 `DOWNLOAD_OUTSIDE_ROOT`，这里表示拒绝上级跳转，不表示需要增设白名单。链接/junction/硬链接**目标**不会被覆盖或穿过写入；依检查阶段会返回 `DOWNLOAD_EXISTS`、`DOWNLOAD_IS_DIRECTORY` 或 `DOWNLOAD_UNSAFE_PATH`。未配置根时，其默认目标父目录按 realpath 处理，不代表任意祖先目录都禁止包含链接；要约束根内子目录，请显式配置固定根。
 
 `~/.lumenkey` 在首次写入时以 0700 创建，已存在但权限更宽时会被收紧（config.json、profiles.json、待确认提交记录共用同一写入路径；Windows 不应用权限位）。配置路径为符号链接或硬链接时，`config.json` 与 `profiles.json` 都返回 `CONFIG_UNSAFE_PATH`（0.2.3 对 profiles 返回 `PROFILE_UNREADABLE`，这是有意的契约变更）；路径存在但不是普通文件（目录、FIFO、套接字、设备）或 `.lumenkey` 不是目录时返回 `CONFIG_NOT_A_FILE`，带 `path` 与 `detail`。
 
@@ -217,3 +227,27 @@ claude mcp add lumenkey npx -y @lumenkey/cli mcp
 
 ## 📄 License
 MIT © 2026 LumenKey Team.
+
+## 本机 Studio（开发候选，尚未发布）
+
+在此源码包构建后运行：
+
+```powershell
+node bin/lumenkey.js studio --output-dir "D:\MyAssets"
+```
+
+服务只在本机启动，并打开本地工作台；可将已有 PNG/JPEG/WebP/MP4/WebM 保存到指定目录的 `LumenKey` 子目录、查看与读取素材。关闭网页或重启后，素材与已保存草稿仍从磁盘清单恢复。图像/视频创作可显式连接已有 CLI 配置，按目录报价和确认提交。
+
+省略 `--output-dir` 可以启动，但不能保存；不自动创建项目。`--no-open` 用于无浏览器诊断，打印的地址没有会话授权，交互使用请去掉该参数重新启动。退出按 Ctrl+C；同一保存目录同时只允许一个服务。
+
+启动、本机素材与草稿不需要云端 Key，也不自动调用云端。开发候选页面已接入云端目录、余额、报价、明确确认生成和任务查询；只有点击“连接云端”才读取已有 CLI 配置。页面按目录展示参数，留空使用平台默认，不写死模型、价格、时长或分辨率。报价不会自动下单，提交结果未知时会阻止再次下单；不宣称退款。详见 `docs/studio/runtime-contract-v1.md`。
+
+“保存草稿”把当前图像/视频编辑分别写入所选目录的 `LumenKey/drafts.json`，浏览器刷新或服务重启后可恢复。未保存编辑在关闭时提醒；强制结束浏览器无法保证保留未保存内容。草稿与任务输入均为明文，应保存在本人可控目录。目录被另一窗口更新时会提示冲突，不自动覆盖。
+
+“画布”与普通创作在同一个 Studio 内：可新建画布、编辑节点与连线、打组/解组、排列、引用本机素材、撤销重做、使用快捷键和保存。保存写入 `LumenKey/canvases.json`，刷新或服务重启后恢复；未完成的参数输入也保留为草稿。离开未保存画布时可保存、留下或放弃，遇到冲突不会自动覆盖。画布的“获取报价”和“确认提交”是两个明确动作，顶栏自动执行仍未开放；查询状态不会自动下载结果。
+
+生成任务的“云端完成”不等于“已保存到本机”。媒体结果在任务页明确选择“保存到本机”，受本机目录授权、输出身份和保存回执约束；核验结果与历史保存事实分别显示。画布中可打开任务与手动保存入口，不会另起一套远程下载/自动导入流程。远程文字结果自动回填及站位 JSON 自动应用尚未接入受保护的本机读取链路；不要把“查询成功”当成已写回节点。
+
+本地 3D 导演台提供人物/物件、机位、路径、时间线、PNG 和 WebM 导出，并与同一画布文件、素材和历史关联。WebGL、录制格式和设备性能受浏览器支持限制；Windows 合成验收不代表 Mac/Linux 已验收。角色造型室仍隐藏；手机虚拟相机、全景 AI、远程 ONNX 和多段成片拼接未开放。营销/充值、自动更新、参考素材上传也不在这版的已完成能力内。
+
+任务记录在本机 `LumenKey/runs.json`，包含提示词但不包含 API Key，当前不加密，请选择本人可控目录。原有 CLI 和 MCP 继续独立使用。本候选版默认打包包含 Studio、画布和导演台，不需要另外下载前端源码。0.4.0-rc.1 尚待审核，不代表已发布；已发布的 0.3.1 仍是 CLI/MCP 包。

package/dist/cli/copied.js

@@ -1,3 +1,4 @@
+import { zhText } from '../core/chinese-messages.js';
 import os from 'node:os';
 import pc from 'picocolors';
 import { describeKey, loadConfig } from '../core/config.js';
@@ -43,7 +44,7 @@ export function applyRaw(options, key, names) {
     if (raw !== undefined)
         options[key] = raw;
     else if (options[key] !== undefined && typeof options[key] !== 'string') {
-        throw new Error(ui(`${names[0]} could not be read as text. Use ${names[0]} <value>.`, `${names[0]} 无法按文本读取。请使用 ${names[0]} <值>。`));
+        throw new Error(ui(`${names[0]} could not be read as text. Use ${names[0]} <value>.`, ("" + (names[0]) + zhText("m359") + (names[0]) + zhText("m360"))));
     }
 }
 /** Plain data commands (catalog, balance, profiles) print their payload; outcomes go through renderOutcome. */
@@ -82,7 +83,7 @@ export async function withCliSignals(run) {
     }
 }
 function progressLine(status) {
-    process.stderr.write(ui(`  Status: ${jobStatusText(status)}\n`, `  状态：${jobStatusText(status)}\n`));
+    process.stderr.write(ui(`  Status: ${jobStatusText(status)}\n`, (zhText("m358") + (jobStatusText(status)) + "\n")));
 }
 /** CLI view of generation progress. In --json mode the job identity goes to stderr the moment it exists. */
 export function cliGenerationEvents() {
@@ -91,24 +92,24 @@ export function cliGenerationEvents() {
         switch (event.type) {
             case 'quoting':
                 if (!json && event.kind === 'video')
-                    console.log(pc.cyan(ui(`\n🎬 Requesting quote for model: ${pc.bold(event.modelId)}...`, `\n🎬 正在为模型 ${pc.bold(event.modelId)} 获取报价...`)));
+                    console.log(pc.cyan(ui(`\n🎬 Requesting quote for model: ${pc.bold(event.modelId)}...`, (zhText("m356") + (pc.bold(event.modelId)) + zhText("m357")))));
                 return;
             case 'submitting':
                 console.error(event.resubmit
-                    ? ui(`Re-sending an earlier unconfirmed submission (idempotency key ${event.idempotencyKey}, quote ${event.quoteId}) instead of creating a new job...`, `正在重发一次之前结果未确认的提交（幂等键 ${event.idempotencyKey}，报价 ${event.quoteId}），不会新建任务...`)
-                    : ui('Submitting generation job...', '正在提交生成任务...'));
+                    ? ui(`Re-sending an earlier unconfirmed submission (idempotency key ${event.idempotencyKey}, quote ${event.quoteId}) instead of creating a new job...`, (zhText("m354") + (event.idempotencyKey) + zhText("m34") + (event.quoteId) + zhText("m355")))
+                    : ui('Submitting generation job...', zhText("m353")));
                 return;
             case 'job_created':
                 if (json)
                     console.error(JSON.stringify({ event: 'job_created', jobId: event.jobId, idempotencyKey: event.idempotencyKey, quoteId: event.quoteId }));
                 else
-                    console.log(ui(`Job created: ${event.jobId} (idempotency key: ${event.idempotencyKey})`, `任务已创建：${event.jobId}（幂等键：${event.idempotencyKey}）`));
+                    console.log(ui(`Job created: ${event.jobId} (idempotency key: ${event.idempotencyKey})`, (zhText("m351") + (event.jobId) + zhText("m352") + (event.idempotencyKey) + "）")));
                 return;
             case 'progress':
                 progressLine(event.detail.status);
                 return;
             case 'notice':
-                console.error(ui(`Note: ${event.text}`, `注意：${event.text}`));
+                console.error(ui(`Note: ${event.text}`, (zhText("m350") + (event.text) + "")));
                 return;
             default:
                 return;
@@ -121,19 +122,19 @@ export function printGeneration(result) {
         return;
     }
     if ('requiresConfirmation' in result) {
-        console.log(ui(`Quote ID: ${result.quoteId} (${result.credits} credits)`, `报价编号：${result.quoteId}（${result.credits} 算力点）`));
-        console.log(ui('Quote only. No job submitted.', '只完成报价，没有提交任务。'));
+        console.log(ui(`Quote ID: ${result.quoteId} (${result.credits} credits)`, (zhText("m348") + (result.quoteId) + "（" + (result.credits) + zhText("m349"))));
+        console.log(ui('Quote only. No job submitted.', zhText("m347")));
         return;
     }
     const done = result;
-    console.log(ui('Generation succeeded!', '生成成功！'));
-    console.log(ui(`Task: ${done.jobId}`, `任务：${done.jobId}`));
+    console.log(ui('Generation succeeded!', zhText("m346")));
+    console.log(ui(`Task: ${done.jobId}`, (zhText("m50") + (done.jobId) + "")));
     for (const url of done.urls)
         console.log(url);
     if (done.localFile)
-        console.log(ui(`Saved to ${done.localFile}`, `已保存到 ${done.localFile}`));
+        console.log(ui(`Saved to ${done.localFile}`, (zhText("m345") + (done.localFile) + "")));
     if (done.download?.ok === false)
-        console.error(ui(`Local save failed: ${done.download.error} (${done.download.code}). The generation result remains available above.`, `本机保存失败：${done.download.error}（${done.download.code}）。生成结果仍可通过以上地址获取。`));
+        console.error(ui(`Local save failed: ${done.download.error} (${done.download.code}). The generation result remains available above.`, (zhText("m343") + (done.download.error) + "（" + (done.download.code) + zhText("m344"))));
 }
 /** Shared by `video` and `image generate`: options come from the core spec, values go through the core normalizer, one use case, one renderer. */
 export async function runCliGeneration(kind, spec, options) {
@@ -165,51 +166,51 @@ export function registerOptions(command, spec) {
 }
 function printProfiles(listed) {
     if (!listed.profiles.length) {
-        console.log(ui('No profiles configured. Create one with: lumenkey profile create <name>', '还没有档案。创建一个：lumenkey profile create <name>'));
+        console.log(ui('No profiles configured. Create one with: lumenkey profile create <name>', zhText("m342")));
         return;
     }
     for (const row of listed.profiles)
         console.log(`${row.isSet ? '* ' : '  '}${row.profile}  ${row.settings.join(', ')}`);
-    console.log(ui('* = active profile; fields shown are configured settings, not their values.', '* 表示当前档案；列出的是已配置的项，不是它们的值。'));
+    console.log(ui('* = active profile; fields shown are configured settings, not their values.', zhText("m341")));
 }
 function printModel(model) {
     console.log(`${model.id} — ${model.displayName || model.name || model.id}`);
     for (const param of explainModel(model).params) {
-        const choices = param.options.length ? `; ${ui('allowed', '允许')}: ${param.options.map(value => JSON.stringify(value)).join(', ')}` : '';
-        const defaultValue = param.default === null ? '' : `; ${ui('default', '默认')}: ${JSON.stringify(param.default)}`;
-        console.log(`${param.name}: ${param.required ? ui('required', '必填') : ui('optional', '可选')}${choices}${defaultValue}`);
+        const choices = param.options.length ? `; ${ui('allowed', zhText("m340"))}: ${param.options.map(value => JSON.stringify(value)).join(', ')}` : '';
+        const defaultValue = param.default === null ? '' : `; ${ui('default', zhText("m339"))}: ${JSON.stringify(param.default)}`;
+        console.log(`${param.name}: ${param.required ? ui('required', zhText("m338")) : ui('optional', zhText("m337"))}${choices}${defaultValue}`);
     }
-    const prices = model.pricing?.map(price => `${price.credits} ${ui('credits', '算力点')}/${price.unit}`).join(', ');
-    console.log(`${ui('Price', '价格')}: ${prices || ui('not reported in catalog', '目录未给出价格')}`);
+    const prices = model.pricing?.map(price => `${price.credits} ${ui('credits', zhText("m336"))}/${price.unit}`).join(', ');
+    console.log(`${ui('Price', zhText("m335"))}: ${prices || ui('not reported in catalog', zhText("m334"))}`);
 }
 export function registerCopied(cli) {
-    cli.option('--json', ui('Emit machine-readable JSON', '输出机器可读的 JSON'));
-    cli.command('model <action> [name]', ui('model search | get | explain', '搜索、查看或解释模型'))
+    cli.option('--json', ui('Emit machine-readable JSON', zhText("m333")));
+    cli.command('model <action> [name]', ui('model search | get | explain', zhText("m332")))
         .example('lumenkey model search wan --type video')
         .example('lumenkey model get minimax-h3')
         .example('lumenkey --json model explain minimax-h3')
-        .option('--type <type>', ui('Filter or disambiguate by catalog type', '按目录类型筛选或消除歧义'))
+        .option('--type <type>', ui('Filter or disambiguate by catalog type', zhText("m331")))
         .action(async (action, name, options) => {
         applyRaw(options, 'type', ['--type']);
         validateModelType(options.type);
         if (!['search', 'get', 'explain'].includes(action))
-            throw new Error(ui(`Unknown model command: ${action}`, `未知的 model 子命令：${action}`));
+            throw new Error(ui(`Unknown model command: ${action}`, (zhText("m326") + (action) + "")));
         if (action === 'search') {
             const models = findModels(await client().listModels(), name || '', options.type);
             emit({ query: name || '', count: models.length, models }, () => {
                 for (const model of models)
                     console.log(model.id);
                 if (models.length === 0)
-                    console.log(ui('No models available for this request.', '这次请求没有可用模型。'));
+                    console.log(ui('No models available for this request.', zhText("m330")));
             });
             return;
         }
         if (!name)
-            throw new Error(ui('Model name is required. Try: model search', '必须提供模型名称。可先运行：model search'));
+            throw new Error(ui('Model name is required. Try: model search', zhText("m329")));
         if (action === 'get') {
             const exact = findModels(await client().listModels(), '').filter((model) => model.id === name || (model.displayName || model.name || '').toLowerCase() === name.toLowerCase());
             if (exact.length !== 1)
-                throw exact.length === 0 ? new LumenKeyError('MODEL_NOT_IN_CATALOG', undefined, undefined, missingModelSentence(name)) : new Error(ui(`More than one model is named ${name}. Run: lumenkey model search ${name}`, `有多个模型叫 ${name}。请运行：lumenkey model search ${name}`));
+                throw exact.length === 0 ? new LumenKeyError('MODEL_NOT_IN_CATALOG', undefined, undefined, missingModelSentence(name)) : new Error(ui(`More than one model is named ${name}. Run: lumenkey model search ${name}`, (zhText("m327") + (name) + zhText("m328") + (name) + "")));
             emit(exact[0], () => printModel(exact[0]));
             return;
         }
@@ -218,36 +219,36 @@ export function registerCopied(cli) {
             const exact = all.filter((model) => model.id === name || (model.displayName || model.name || '').toLowerCase() === name.toLowerCase());
             const chosen = exact.length === 1 ? exact[0] : findModels(all, name, options.type).length === 1 ? findModels(all, name, options.type)[0] : undefined;
             if (!chosen)
-                throw exact.length === 0 ? new LumenKeyError('MODEL_NOT_IN_CATALOG', undefined, undefined, missingModelSentence(name)) : new Error(ui(`More than one model is named ${name}. Run: lumenkey model search ${name}`, `有多个模型叫 ${name}。请运行：lumenkey model search ${name}`));
+                throw exact.length === 0 ? new LumenKeyError('MODEL_NOT_IN_CATALOG', undefined, undefined, missingModelSentence(name)) : new Error(ui(`More than one model is named ${name}. Run: lumenkey model search ${name}`, (zhText("m327") + (name) + zhText("m328") + (name) + "")));
             const explained = explainModel(chosen);
             emit(explained, () => printModel(chosen));
             return;
         }
-        throw new Error(ui(`Unknown model command: ${action}`, `未知的 model 子命令：${action}`));
+        throw new Error(ui(`Unknown model command: ${action}`, (zhText("m326") + (action) + "")));
     });
-    registerOptions(cli.command('image <action>', ui('image generate', '生成图片'))
+    registerOptions(cli.command('image <action>', ui('image generate', zhText("m325")))
         .example('lumenkey image generate -m wan2.7-image -p "red circle"')
         .example('lumenkey image generate -m wan2.7-image -p "red circle" --set seed=2 --dry-run'), imageParams)
         .action(async (action, options) => {
         if (action !== 'generate')
-            throw new Error(ui(`Unknown image command: ${action}`, `未知的 image 子命令：${action}`));
+            throw new Error(ui(`Unknown image command: ${action}`, (zhText("m324") + (action) + "")));
         await runCliGeneration('image', imageParams, options);
     });
-    registerOptions(cli.command('tasks <action> [jobId]', ui('tasks progress | wait | cancel | resume', '查看进度、等待、取消任务，或重发一次记录的提交'))
+    registerOptions(cli.command('tasks <action> [jobId]', ui('tasks progress | wait | cancel | resume', zhText("m323")))
         .example('lumenkey tasks progress <jobId>')
         .example('lumenkey tasks wait <jobId> --interval 5 --timeout 1800')
         .example('lumenkey tasks cancel <jobId> --yes')
         .example('lumenkey tasks resume <idempotencyKey>')
         .example('lumenkey tasks resume --key=<idempotencyKey>   (for a key that begins with -)'), resumeParams)
-        .option('--yes', ui('Confirm cancellation', '确认取消'))
-        .option('--key <idempotencyKey>', ui('The idempotency key for tasks resume; use --key=<key> or -- <key> when the key begins with -', 'tasks resume 的幂等键；键以 - 开头时用 --key=<键> 或 -- <键>'))
+        .option('--yes', ui('Confirm cancellation', zhText("m322")))
+        .option('--key <idempotencyKey>', ui('The idempotency key for tasks resume; use --key=<key> or -- <key> when the key begins with -', zhText("m321")))
         .action(async (action, positional, options) => {
         // Each subcommand owns its options; any other option is as unknown here as on the MCP surface.
         rejectForeignTaskOptions(action);
         applyRaw(options, 'key', ['--key']);
         const jobId = positional ?? firstDoubleDashArgument(options) ?? (typeof options.key === 'string' ? options.key : undefined);
         if (jobId === undefined)
-            throw new UsageArgumentError(ui(`missing required args for command \`tasks ${action}\``, `命令 \`tasks ${action}\` 缺少必填参数。`));
+            throw new UsageArgumentError(ui(`missing required args for command \`tasks ${action}\``, (zhText("m319") + (action) + zhText("m320"))));
         if (action === 'progress') {
             renderOutcome(await readJob(client(), jobId), ok => console.log(formatJobDetail(ok.job)));
             return;
@@ -276,12 +277,12 @@ export function registerCopied(cli) {
             if (options.yes !== true)
                 throw new LumenKeyError('CANCEL_CONFIRMATION_REQUIRED');
             const result = await client().cancelJob(jobId);
-            emit(result, () => console.log(ui(`Cancellation requested for ${jobId}. Settlement is determined by the gateway.`, `已请求取消任务 ${jobId}，最终结算由网关确认。`)));
+            emit(result, () => console.log(ui(`Cancellation requested for ${jobId}. Settlement is determined by the gateway.`, (zhText("m317") + (jobId) + zhText("m318")))));
             return;
         }
-        throw new Error(ui(`Unknown tasks command: ${action}`, `未知的 tasks 子命令：${action}`));
+        throw new Error(ui(`Unknown tasks command: ${action}`, (zhText("m316") + (action) + "")));
     });
-    cli.command('profile <action> [value] [...extra]', ui('profile list | create | set | unset | key | host | delete', '列出、创建、切换或删除档案'))
+    cli.command('profile <action> [value] [...extra]', ui('profile list | create | set | unset | key | host | delete', zhText("m315")))
         .example('lumenkey profile create work')
         .example('lumenkey profile key')
         .example('lumenkey profile host https://123outlets.com')
@@ -290,7 +291,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 LumenKeyError('CLI_ARGUMENTS_INVALID', undefined, undefined, ui(`Unknown profile command: ${action}`, `未知的 profile 子命令：${action}`));
+            throw new LumenKeyError('CLI_ARGUMENTS_INVALID', undefined, undefined, ui(`Unknown profile command: ${action}`, (zhText("m303") + (action) + "")));
         }
         if (action === 'list') {
             const listed = listProfiles();
@@ -299,29 +300,29 @@ export function registerCopied(cli) {
         }
         if (action === 'unset') {
             unsetProfile();
-            emit({ current: null }, () => console.log(ui('Default profile unset.', '已取消默认档案。')));
+            emit({ current: null }, () => console.log(ui('Default profile unset.', zhText("m314"))));
             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)', '（当前档案）'));
+                throw new ProfileMissingError(target ?? ui('(active profile)', zhText("m313")));
             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} 设置密钥。`)));
+            emit({ profile: name, hasStoredToken: true }, () => console.log(ui(`Key set for profile ${name}.`, (zhText("m311") + (name) + zhText("m312")))));
             return;
         }
         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 <地址>。'));
+            throw new LumenKeyError('CLI_ARGUMENTS_INVALID', undefined, undefined, ui('Profile host needs a gateway address. Use profile host <address>.', zhText("m310")));
         if (action !== 'host' && !value)
-            throw new LumenKeyError('CLI_ARGUMENTS_INVALID', undefined, undefined, ui(`Profile ${action} needs a name.`, `profile ${action} 需要名称。`));
+            throw new LumenKeyError('CLI_ARGUMENTS_INVALID', undefined, undefined, ui(`Profile ${action} needs a name.`, ("profile " + (action) + zhText("m295"))));
         if (value === undefined)
             throw new LumenKeyError('CLI_ARGUMENTS_INVALID');
         if (action === 'create') {
             const result = createProfile(value);
             if (result === 'exists')
                 throw new LumenKeyError('PROFILE_EXISTS');
-            emit({ name: value, created: true }, () => console.log(ui(`Profile ${value} created.`, `已创建档案 ${value}。`)));
+            emit({ name: value, created: true }, () => console.log(ui(`Profile ${value} created.`, (zhText("m309") + (value) + "。"))));
             return;
         }
         if (action === 'set') {
@@ -332,14 +333,14 @@ export function registerCopied(cli) {
                 if (!(err instanceof ProfileMissingError))
                     throw err;
                 console.error(err.message);
-                const answer = (await ask(ui('Would you like to create it? (y/N): ', '要创建它吗？(y/N): '))).trim().toLowerCase();
+                const answer = (await ask(ui('Would you like to create it? (y/N): ', zhText("m308")))).trim().toLowerCase();
                 if (answer !== 'y' && answer !== 'yes') {
-                    emit({ current: null, created: false }, () => console.log(ui('Profile creation cancelled.', '已取消创建档案。')));
+                    emit({ current: null, created: false }, () => console.log(ui('Profile creation cancelled.', zhText("m307"))));
                     return;
                 }
                 createProfile(value);
             }
-            emit({ current: value }, () => console.log(ui(`Default profile set to ${value}.`, `默认档案已设为 ${value}。`)));
+            emit({ current: value }, () => console.log(ui(`Default profile set to ${value}.`, (zhText("m306") + (value) + "。"))));
             return;
         }
         if (action === 'host') {
@@ -351,34 +352,34 @@ export function registerCopied(cli) {
                 throw new LumenKeyError('BASE_URL_INVALID');
             }
             const name = setProfileFields({ host: value });
-            emit({ profile: name, host: value }, () => console.log(ui(`Host set to ${value}.`, `网关已设为 ${value}。`)));
+            emit({ profile: name, host: value }, () => console.log(ui(`Host set to ${value}.`, (zhText("m305") + (value) + "。"))));
             return;
         }
         if (action === 'delete') {
             const removed = deleteProfile(value);
             if (!removed)
                 throw new ProfileMissingError(value);
-            emit({ deleted: true, name: value }, () => console.log(ui(`Profile ${value} deleted.`, `已删除档案 ${value}。`)));
+            emit({ deleted: true, name: value }, () => console.log(ui(`Profile ${value} deleted.`, (zhText("m304") + (value) + "。"))));
             return;
         }
-        throw new Error(ui(`Unknown profile command: ${action}`, `未知的 profile 子命令：${action}`));
+        throw new Error(ui(`Unknown profile command: ${action}`, (zhText("m303") + (action) + "")));
     });
-    cli.command('auth <group> [action] [name]', ui('auth status | profile list | use | save | delete', '查看状态或管理登录档案'))
+    cli.command('auth <group> [action] [name]', ui('auth status | profile list | use | save | delete', zhText("m302")))
         .example('lumenkey auth profile list')
         .example('lumenkey auth profile save work')
         .example('lumenkey auth profile use work')
         .example('lumenkey auth profile delete work --yes')
-        .option('--yes', ui('Confirm deletion', '确认删除'))
-        .option('--store-token', ui('Store the environment key after a balance check', '余额检查通过后保存环境变量中的密钥'))
-        .option('--no-activate', ui('Do not make the saved profile active', '保存后不把它设为当前档案'))
+        .option('--yes', ui('Confirm deletion', zhText("m301")))
+        .option('--store-token', ui('Store the environment key after a balance check', zhText("m300")))
+        .option('--no-activate', ui('Do not make the saved profile active', zhText("m299")))
         .action(async (group, action, name, options) => {
         if (group === 'status') {
             const body = describeKey();
-            emit(body, () => console.log(body.keyConfigured ? ui(`key: ${body.keySource}`, `密钥：${body.keySource}`) : errorSentence('API_KEY_NOT_CONFIGURED')));
+            emit(body, () => console.log(body.keyConfigured ? ui(`key: ${body.keySource}`, (zhText("m298") + (body.keySource) + "")) : errorSentence('API_KEY_NOT_CONFIGURED')));
             return;
         }
         if (group !== 'profile')
-            throw new Error(ui(`Unknown auth command: ${group}`, `未知的 auth 子命令：${group}`));
+            throw new Error(ui(`Unknown auth command: ${group}`, (zhText("m297") + (group) + "")));
         if (action === 'list') {
             const data = listProfiles();
             const body = { active: data.current ?? null, profiles: data.profiles.map((row) => ({ name: row.profile, settings: row.settings })) };
@@ -387,15 +388,15 @@ export function registerCopied(cli) {
         }
         if (!action || !['use', 'save', 'delete'].includes(action)) {
             throw new Error(action
-                ? ui(`Unknown auth profile command: ${action}`, `未知的 auth profile 子命令：${action}`)
-                : ui('Unknown auth profile command.', '未知的 auth profile 子命令。'));
+                ? ui(`Unknown auth profile command: ${action}`, (zhText("m290") + (action) + ""))
+                : ui('Unknown auth profile command.', zhText("m296")));
         }
         if (!name)
-            throw new LumenKeyError('CLI_ARGUMENTS_INVALID', undefined, undefined, 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) + zhText("m295"))));
         if (action === 'use') {
             setProfile(name);
             const record = currentProfile().record;
-            emit({ name, hasStoredToken: Boolean(record?.key), account: publicProfile(record) }, () => console.log(ui(`Profile ${name} activated.`, `已启用档案 ${name}。`)));
+            emit({ name, hasStoredToken: Boolean(record?.key), account: publicProfile(record) }, () => console.log(ui(`Profile ${name} activated.`, (zhText("m294") + (name) + "。"))));
             return;
         }
         if (action === 'save') {
@@ -410,22 +411,22 @@ export function registerCopied(cli) {
                 setNamedProfileFields(name, { key, host: process.env.LUMENKEY_BASE_URL });
             }
             const record = listProfiles().profiles.find((row) => row.profile === name);
-            emit({ name, active: activate, storedToken: Boolean(options.storeToken), settings: record?.settings ?? [] }, () => console.log(ui(`Auth profile ${name} saved.`, `已保存认证档案 ${name}。`)));
+            emit({ name, active: activate, storedToken: Boolean(options.storeToken), settings: record?.settings ?? [] }, () => console.log(ui(`Auth profile ${name} saved.`, (zhText("m293") + (name) + "。"))));
             return;
         }
         if (action === 'delete') {
             if (!options.yes)
-                throw new Error(ui('Refusing to delete auth profile without --yes.', '未加 --yes，拒绝删除认证档案。'));
+                throw new Error(ui('Refusing to delete auth profile without --yes.', zhText("m292")));
             const removed = deleteProfile(name);
             if (!removed)
                 throw new ProfileMissingError(name);
-            emit({ deleted: true, name }, () => console.log(ui(`Auth profile ${name} deleted.`, `已删除认证档案 ${name}。`)));
+            emit({ deleted: true, name }, () => console.log(ui(`Auth profile ${name} deleted.`, (zhText("m291") + (name) + "。"))));
             return;
         }
-        throw new Error(ui(`Unknown auth profile command: ${action}`, `未知的 auth profile 子命令：${action}`));
+        throw new Error(ui(`Unknown auth profile command: ${action}`, (zhText("m290") + (action) + "")));
     });
-    cli.command('doctor', ui('Local environment summary. --online checks the key by reading balance', '本地环境摘要。--online 会读取余额来检查密钥'))
-        .option('--online', ui('Verify the configured key', '检查已配置的密钥'))
+    cli.command('doctor', ui('Local environment summary. --online checks the key by reading balance', zhText("m289")))
+        .option('--online', ui('Verify the configured key', zhText("m288")))
         .action(async (options) => {
         const config = loadConfig();
         const checks = [
@@ -446,24 +447,24 @@ export function registerCopied(cli) {
         }
         const ok = checks.every((check) => check.status !== 'fail');
         emit({ ok, checks }, () => {
-            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}`));
-            console.log(config.apiKey ? ui('key: configured', '密钥：已配置') : ui('key: not configured', '密钥：未配置'));
+            console.log(ui(`cli: ${packageVersion}`, (zhText("m287") + (packageVersion) + "")));
+            console.log(ui(`runtime: ${process.version}`, (zhText("m286") + (process.version) + "")));
+            console.log(ui(`platform: ${process.platform} ${os.release()}`, (zhText("m285") + (process.platform) + " " + (os.release()) + "")));
+            console.log(ui(`host: ${config.baseUrl}`, (zhText("m284") + (config.baseUrl) + "")));
+            console.log(config.apiKey ? ui('key: configured', zhText("m283")) : ui('key: not configured', zhText("m282")));
             if (options.online) {
                 const check = checks.find(row => row.name === 'onlineAuth');
-                console.log(`${ui('onlineAuth', '在线鉴权')}: ${check?.status}${check?.message ? ` — ${check.message}` : ''}`);
+                console.log(`${ui('onlineAuth', zhText("m281"))}: ${check?.status}${check?.message ? ` — ${check.message}` : ''}`);
             }
         });
         if (!ok)
             process.exitCode = 1;
     });
-    cli.command('completion <shell>', ui('Print a shell completion script', '打印 shell 补全脚本'))
+    cli.command('completion <shell>', ui('Print a shell completion script', zhText("m280")))
         .action((shell) => {
         const script = Object.hasOwn(COMPLETIONS, shell) ? COMPLETIONS[shell] : undefined;
         if (!script)
-            throw new LumenKeyError('CLI_ARGUMENTS_INVALID', undefined, undefined, 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.', zhText("m279")));
         console.log(script);
     });
 }
@@ -483,7 +484,7 @@ function rejectForeignTaskOptions(action) {
             break;
         const name = arg.split('=')[0];
         if (all.includes(name) && !owned.has(name)) {
-            throw new LumenKeyError('INPUT_INVALID', undefined, undefined, ui(`Unknown option ${JSON.stringify(name)} for tasks ${action}.`, `tasks ${action} 没有选项 ${JSON.stringify(name)}。`));
+            throw new LumenKeyError('INPUT_INVALID', undefined, undefined, ui(`Unknown option ${JSON.stringify(name)} for tasks ${action}.`, ("tasks " + (action) + zhText("m278") + (JSON.stringify(name)) + "。")));
         }
     }
 }
@@ -529,14 +530,14 @@ export async function readSecret(input = process.stdin, output = process.stderr)
                 answered = true;
                 reader.close();
                 if (!line.trim())
-                    reject(new Error(ui('Enter the key: empty.', '输入密钥不能为空。')));
+                    reject(new Error(ui('Enter the key: empty.', zhText("m276"))));
                 else
                     resolve(line.trim());
             });
             reader.once('close', () => { if (!answered)
                 reject(new LumenKeyError('INPUT_CLOSED')); });
             reader.once('error', reject);
-            output.write(ui('Enter the key: ', '请输入密钥：'));
+            output.write(ui('Enter the key: ', zhText("m272")));
         });
     }
     const wasRaw = Boolean(input.isRaw);
@@ -558,7 +559,7 @@ export async function readSecret(input = process.stdin, output = process.stderr)
                 input.setRawMode(wasRaw);
             }
             catch (restoreError) {
-                error = restoreError instanceof Error ? restoreError : new Error(ui('Could not restore terminal mode.', '无法恢复终端模式。'));
+                error = restoreError instanceof Error ? restoreError : new Error(ui('Could not restore terminal mode.', zhText("m277")));
             }
             if (wasPaused)
                 input.pause();
@@ -566,12 +567,12 @@ export async function readSecret(input = process.stdin, output = process.stderr)
             if (error)
                 reject(error);
             else if (!value.trim())
-                reject(new Error(ui('Enter the key: empty.', '输入密钥不能为空。')));
+                reject(new Error(ui('Enter the key: empty.', zhText("m276"))));
             else
                 resolve(value.trim());
             value = '';
         };
-        const onEnd = () => finish(new Error(ui('stdin closed before an answer was given.', '输入密钥前标准输入已关闭。')));
+        const onEnd = () => finish(new Error(ui('stdin closed before an answer was given.', zhText("m275"))));
         const onError = (error) => finish(error);
         const onData = (chunk) => {
             for (const char of typeof chunk === 'string' ? chunk : decoder.write(chunk)) {
@@ -580,7 +581,7 @@ export async function readSecret(input = process.stdin, output = process.stderr)
                     return;
                 }
                 if (char === '\u0003' || char === '\u0004') {
-                    finish(new Error(ui('Key entry cancelled.', '已取消输入密钥。')));
+                    finish(new Error(ui('Key entry cancelled.', zhText("m274"))));
                     return;
                 }
                 if (char === '\u007f' || char === '\b')
@@ -588,7 +589,7 @@ export async function readSecret(input = process.stdin, output = process.stderr)
                 else if (char >= ' ')
                     value += char;
                 if (value.length > 8192) {
-                    finish(new Error(ui('Key input is too long.', '密钥输入过长。')));
+                    finish(new Error(ui('Key input is too long.', zhText("m273"))));
                     return;
                 }
             }
@@ -599,11 +600,11 @@ export async function readSecret(input = process.stdin, output = process.stderr)
             input.once('end', onEnd);
             input.once('close', onEnd);
             input.once('error', onError);
-            output.write(ui('Enter the key: ', '请输入密钥：'));
+            output.write(ui('Enter the key: ', zhText("m272")));
             input.resume();
         }
         catch (error) {
-            finish(error instanceof Error ? error : new Error(ui('Could not disable terminal echo.', '无法关闭终端回显。')));
+            finish(error instanceof Error ? error : new Error(ui('Could not disable terminal echo.', zhText("m271"))));
         }
     });
 }