feat(i18n): localize newly added CLI help content

Author: XXPermanentXX

AGENTS.md

@@ -122,6 +122,10 @@ CLI 只为「自己能权威解释的错误」发出语义化信号,服务端的
 
 例外: 仅当作用域极小(≤3 行)且语义从上下文完全明确时,可使用 `k`/`v`(Object.entries 的 key/value)。
 
+### 6. 用户可见 CLI 文案必须支持中英文
+
+新增或修改用户可见的 CLI 文案时必须同时提供 `en-US` / `zh-CN`;runtime 公共文案遵循同一规则,服务端错误仍按第 3 节原样透传。命令文案的具体检查项见 [command-add-remove.md](docs/agents/command-add-remove.md)。
+
 ## 完成改动后的快速验证
 
 ```sh

docs/agents/command-add-remove.md

@@ -74,6 +74,7 @@ packages/commands/src/index.ts
   - 普通业务命令的 `run(ctx)` 只读 `ctx.flags` / `ctx.settings` / `ctx.client`
   - `commands/auth/**` 可用 `ctx.authStore`,`commands/config/**` 可用 `ctx.configStore`;不要把这些持久化能力扩散到普通业务命令
   - `commands/plugin/**` 可用 `ctx.commandPacks`;产品 policy 由 runtime 绑定,命令不要自行 import 产品入口
+- [ ] 用户可见 Help 文案在命令文件中就近提供 `en-US` / `zh-CN`:命令 `description`、flag `description`、`notes` 和包含自然语言的 `exampleArgs`;纯命令语法示例可保留为字符串,服务端错误不翻译
 - [ ] `packages/commands/src/index.ts`:新增或移除对应 export
 - [ ] 如果命令调用 Console Gateway,设置 `auth: "console"`;不要重复声明 console 凭证域 flags
 - [ ] 如果命令不需要网络或自己管理配置/登录,设置 `auth: "none"`;不要绕过 runtime auth stage

packages/commands/src/commands/deploy/pause.ts

@@ -13,12 +13,18 @@ const PAUSE_FLAGS = {
   deployedModel: {
     type: "string",
     valueHint: "<id>",
-    description: "Deployed model identifier (required)",
+    description: {
+      "en-US": "Deployed model identifier (required)",
+      "zh-CN": "已部署模型标识（必填）",
+    },
     required: true,
   },
   skipPrecheck: {
     type: "switch",
-    description: "Skip the local RUNNING/PENDING status precheck",
+    description: {
+      "en-US": "Skip the local RUNNING/PENDING status precheck",
+      "zh-CN": "跳过本地 RUNNING/PENDING 状态预检查",
+    },
   },
 } satisfies FlagsDef;
 
@@ -30,7 +36,10 @@ const PAUSE_FLAGS = {
  * Precheck: status must be RUNNING or PENDING.
  */
 export default defineCommand({
-  description: "Pause a running model deployment (stops billing for mu/ptu)",
+  description: {
+    "en-US": "Pause a running model deployment (stops billing for mu/ptu)",
+    "zh-CN": "暂停运行中的模型部署（mu/ptu 方案将停止计费）",
+  },
   auth: "console",
   usageArgs: "--deployed-model <id> [--skip-precheck]",
   flags: PAUSE_FLAGS,
@@ -40,8 +49,18 @@ export default defineCommand({
     "--deployed-model dep-... --dry-run",
   ],
   notes: [
-    "While paused, billing ceases for mu/ptu plans. Use `deploy resume` to bring it back online or `deploy delete` to remove.",
-    "Precheck verifies status is RUNNING/PENDING before issuing the pause; pass --skip-precheck to bypass.",
+    {
+      "en-US":
+        "While paused, billing ceases for mu/ptu plans. Use `deploy resume` to bring it back online or `deploy delete` to remove.",
+      "zh-CN":
+        "暂停期间，mu/ptu 方案将停止计费。使用 `deploy resume` 恢复服务，或使用 `deploy delete` 删除部署。",
+    },
+    {
+      "en-US":
+        "Precheck verifies status is RUNNING/PENDING before issuing the pause; pass --skip-precheck to bypass.",
+      "zh-CN":
+        "发起暂停前会预检查部署状态是否为 RUNNING/PENDING；可传入 --skip-precheck 跳过检查。",
+    },
   ],
   async run(ctx) {
     const { settings, flags } = ctx;

packages/commands/src/commands/deploy/resume.ts

@@ -13,12 +13,18 @@ const RESUME_FLAGS = {
   deployedModel: {
     type: "string",
     valueHint: "<id>",
-    description: "Deployed model identifier (required)",
+    description: {
+      "en-US": "Deployed model identifier (required)",
+      "zh-CN": "已部署模型标识（必填）",
+    },
     required: true,
   },
   skipPrecheck: {
     type: "switch",
-    description: "Skip the local STOPPED status precheck",
+    description: {
+      "en-US": "Skip the local STOPPED status precheck",
+      "zh-CN": "跳过本地 STOPPED 状态预检查",
+    },
   },
 } satisfies FlagsDef;
 
@@ -29,7 +35,10 @@ const RESUME_FLAGS = {
  * Precheck: status must be STOPPED.
  */
 export default defineCommand({
-  description: "Resume a paused model deployment (brings service back online)",
+  description: {
+    "en-US": "Resume a paused model deployment (brings service back online)",
+    "zh-CN": "恢复已暂停的模型部署（使服务重新上线）",
+  },
   auth: "console",
   usageArgs: "--deployed-model <id> [--skip-precheck]",
   flags: RESUME_FLAGS,
@@ -39,8 +48,15 @@ export default defineCommand({
     "--deployed-model dep-... --dry-run",
   ],
   notes: [
-    "Precheck verifies status is STOPPED before issuing the resume; pass --skip-precheck to bypass.",
-    "For mu/ptu plans, billing resumes once the service is back online.",
+    {
+      "en-US":
+        "Precheck verifies status is STOPPED before issuing the resume; pass --skip-precheck to bypass.",
+      "zh-CN": "发起恢复前会预检查部署状态是否为 STOPPED；可传入 --skip-precheck 跳过检查。",
+    },
+    {
+      "en-US": "For mu/ptu plans, billing resumes once the service is back online.",
+      "zh-CN": "对于 mu/ptu 方案，服务重新上线后将恢复计费。",
+    },
   ],
   async run(ctx) {
     const { settings, flags } = ctx;

packages/commands/src/commands/finetune/list.ts

@@ -26,7 +26,10 @@ const LIST_FLAGS = {
   baseModel: {
     type: "string",
     valueHint: "<model>",
-    description: "Filter by base model ID (server-side)",
+    description: {
+      "en-US": "Filter by base model ID (server-side)",
+      "zh-CN": "按基础模型 ID 筛选（服务端筛选）",
+    },
   },
 } satisfies FlagsDef;
 

packages/commands/src/commands/finetune/price.ts

@@ -13,24 +13,36 @@ const PRICE_FLAGS = {
   baseModel: {
     type: "string",
     valueHint: "<model>",
-    description: "Base model to fine-tune (e.g. qwen3-8b; not the output model name)",
+    description: {
+      "en-US": "Base model to fine-tune (e.g. qwen3-8b; not the output model name)",
+      "zh-CN": "待微调的基座模型（例如 qwen3-8b；不是输出模型名称）",
+    },
     required: true,
   },
   datasets: {
     type: "string",
     valueHint: "<ids>",
-    description: "Training dataset file IDs, comma-separated (required)",
+    description: {
+      "en-US": "Training dataset file IDs, comma-separated (required)",
+      "zh-CN": "训练数据集文件 ID，多个以逗号分隔（必填）",
+    },
     required: true,
   },
   trainingType: {
     type: "string",
     valueHint: "<type>",
-    description: "Training type: sft | dpo | cpt (default: sft)",
+    description: {
+      "en-US": "Training type: sft | dpo | cpt (default: sft)",
+      "zh-CN": "训练类型：sft | dpo | cpt（默认：sft）",
+    },
   },
   nEpochs: {
     type: "number",
     valueHint: "<n>",
-    description: "Number of training epochs (default: 3)",
+    description: {
+      "en-US": "Number of training epochs (default: 3)",
+      "zh-CN": "训练轮数（默认：3）",
+    },
   },
 } satisfies FlagsDef;
 
@@ -44,7 +56,10 @@ const ESTIMATE_MAX_LENGTH = 8192;
 const DEFAULT_N_EPOCHS = 3;
 
 export default defineCommand({
-  description: "Estimate the training cost for a fine-tune job (token billing)",
+  description: {
+    "en-US": "Estimate the training cost for a fine-tune job (token billing)",
+    "zh-CN": "估算微调任务的训练费用（按 Token 计费）",
+  },
   auth: "console",
   usageArgs: "--base-model <model> --datasets <ids> [--training-type <type>] [--n-epochs <n>]",
   flags: PRICE_FLAGS,
@@ -54,9 +69,21 @@ export default defineCommand({
     "--base-model qwen3-8b --datasets file-ft-xxx --training-type cpt",
   ],
   notes: [
-    "Estimate only — the server computes token usage from the datasets; final cost is subject to the bill.",
-    "Covers token billing for sft / dpo / cpt. Training-unit (MTU) billing is not supported by this command.",
-    "Hyper-parameters other than --n-epochs are fixed at representative defaults for estimation.",
+    {
+      "en-US":
+        "Estimate only — the server computes token usage from the datasets; final cost is subject to the bill.",
+      "zh-CN": "该结果仅为估算值——服务端根据数据集计算 Token 用量，最终费用以账单为准。",
+    },
+    {
+      "en-US":
+        "Covers token billing for sft / dpo / cpt. Training-unit (MTU) billing is not supported by this command.",
+      "zh-CN": "支持估算 sft / dpo / cpt 的 Token 计费；此命令不支持训练单元（MTU）计费估算。",
+    },
+    {
+      "en-US":
+        "Hyper-parameters other than --n-epochs are fixed at representative defaults for estimation.",
+      "zh-CN": "除 --n-epochs 外，其他超参数会使用具有代表性的固定默认值进行估算。",
+    },
   ],
   async run(ctx) {
     const { settings, flags } = ctx;

packages/commands/src/commands/knowledge/category-add.ts

@@ -13,28 +13,39 @@ const CATEGORY_ADD_FLAGS = {
   name: {
     type: "string",
     valueHint: "<text>",
-    description: "Category name (1-20 chars)",
+    description: { "en-US": "Category name (1-20 chars)", "zh-CN": "类目名称（1–20 个字符）" },
     required: true,
   },
   parentId: {
     type: "string",
     valueHint: "<id>",
-    description: "Create as a sub-category of this category",
+    description: {
+      "en-US": "Create as a sub-category of this category",
+      "zh-CN": "创建为该类目的子类目",
+    },
   },
   collectionId: {
     type: "string",
     valueHint: "<id>",
-    description: "Create under this collection (defaults to the platform collection)",
+    description: {
+      "en-US": "Create under this collection (defaults to the platform collection)",
+      "zh-CN": "在该数据集合下创建（默认为平台数据集合）",
+    },
   },
   ...WORKSPACE_FLAG,
 } satisfies FlagsDef;
 
 export default defineCommand({
-  description: "Create a data-center category",
+  description: { "en-US": "Create a data-center category", "zh-CN": "创建数据中心类目" },
   auth: "apiKey",
   usageArgs: "--name <text> [flags]",
   flags: CATEGORY_ADD_FLAGS,
-  notes: ["Use categories to organize data-center files by business domain."],
+  notes: [
+    {
+      "en-US": "Use categories to organize data-center files by business domain.",
+      "zh-CN": "使用类目按业务领域组织数据中心文件。",
+    },
+  ],
   exampleArgs: ["--name product-docs --workspace-id ws-xxx", "--name sub --parent-id cate-xxx"],
   validate(flags) {
     if (flags.name.length < 1 || flags.name.length > 20) return "--name must be 1-20 characters";

packages/commands/src/commands/knowledge/category-delete.ts

@@ -13,20 +13,27 @@ const CATEGORY_DELETE_FLAGS = {
   categoryId: {
     type: "string",
     valueHint: "<id>",
-    description: "Category ID to delete",
+    description: { "en-US": "Category ID to delete", "zh-CN": "要删除的类目 ID" },
     required: true,
   },
-  yes: { type: "switch", description: "Skip the confirmation prompt" },
+  yes: {
+    type: "switch",
+    description: { "en-US": "Skip the confirmation prompt", "zh-CN": "跳过确认提示" },
+  },
   ...WORKSPACE_FLAG,
 } satisfies FlagsDef;
 
 export default defineCommand({
-  description: "Delete a data-center category",
+  description: { "en-US": "Delete a data-center category", "zh-CN": "删除数据中心类目" },
   auth: "apiKey",
   usageArgs: "--category-id <id> [flags]",
   flags: CATEGORY_DELETE_FLAGS,
   notes: [
-    "Behavior for categories containing files or sub-categories is server-defined — the server error is passed through as-is.",
+    {
+      "en-US":
+        "Behavior for categories containing files or sub-categories is server-defined — the server error is passed through as-is.",
+      "zh-CN": "包含文件或子类目时的处理行为由服务端定义——服务端返回的错误将原样透传。",
+    },
   ],
   exampleArgs: ["--category-id cate-xxx --workspace-id ws-xxx", "--category-id cate-xxx --yes"],
   async run(ctx) {

packages/commands/src/commands/knowledge/category-list.ts

@@ -13,39 +13,54 @@ const CATEGORY_LIST_FLAGS = {
   collectionId: {
     type: "string",
     valueHint: "<id>",
-    description: "Filter by exact collection ID",
+    description: { "en-US": "Filter by exact collection ID", "zh-CN": "按数据集合 ID 精确筛选" },
   },
   parentId: {
     type: "string",
     valueHint: "<id>",
-    description: "List sub-categories of this exact parent category",
+    description: {
+      "en-US": "List sub-categories of this exact parent category",
+      "zh-CN": "列出该父类目下的子类目",
+    },
   },
   name: {
     type: "string",
     valueHint: "<text>",
-    description: "Filter by category name (exact match, unlike the knowledge base list)",
+    description: {
+      "en-US": "Filter by category name (exact match, unlike the knowledge base list)",
+      "zh-CN": "按类目名称筛选（精确匹配，与知识库列表不同）",
+    },
   },
   nextToken: {
     type: "string",
     valueHint: "<token>",
-    description: "Cursor for the next page (from previous output)",
+    description: {
+      "en-US": "Cursor for the next page (from previous output)",
+      "zh-CN": "下一页游标（来自上一次输出）",
+    },
   },
   maxResult: {
     type: "number",
     valueHint: "<n>",
-    description: "Items per page (default: 20)",
+    description: { "en-US": "Items per page (default: 20)", "zh-CN": "每页条目数（默认：20）" },
   },
   ...WORKSPACE_FLAG,
 } satisfies FlagsDef;
 
 export default defineCommand({
-  description: "List data-center categories",
+  description: { "en-US": "List data-center categories", "zh-CN": "列出数据中心类目" },
   auth: "apiKey",
   usageArgs: "[flags]",
   flags: CATEGORY_LIST_FLAGS,
   notes: [
-    "Categories marked [default] are where files land when no category is specified.",
-    "Pagination is cursor-based: reuse the printed next token to continue.",
+    {
+      "en-US": "Categories marked [default] are where files land when no category is specified.",
+      "zh-CN": "未指定类目时，文件会进入标记为 [default] 的类目。",
+    },
+    {
+      "en-US": "Pagination is cursor-based: reuse the printed next token to continue.",
+      "zh-CN": "分页使用游标：复用输出中的 next token 继续查询。",
+    },
   ],
   exampleArgs: ["--workspace-id ws-xxx", "--name my-category", "--next-token <token>"],
   async run(ctx) {