Merge pull request #168 from modelstudioai/feat/bilingual-quick-start-examples

feat(i18n): support bilingual CLI help and quick start

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/cli/src/main.ts

@@ -4,10 +4,11 @@ import { commandPackPolicy } from "./command-pack-policy.ts";
 import pkg from "../package.json" with { type: "json" };
 
 const quickStartTasks = [
-  "Help me generate a set of Amazon e-commerce main images for baseball caps (white background + lifestyle shots + model wear shots)",
-  "Help me generate a 3-minute humorous crosstalk audio clip",
-  "Help me generate a Little Red Riding Hood picture-book PDF (with illustrations)",
-  "Help me analyze this video and write a Xiaohongshu-style post",
+  "帮我创建一个能够生成短片分镜和视频的 Managed Agent。\n   Help me create a Managed Agent that can generate short-film storyboards and videos.",
+  "生成一张穿着太空服的猫站在火星上的图片，再把它制作成一段视频。\n   Generate an image of a cat in a spacesuit standing on Mars, then turn it into a video.",
+  "查看最近的模型用量、免费额度和限流情况。\n   Check my recent model usage, free quota, and rate limits.",
+  "推荐一个适合图片理解和智能客服的模型。\n   Recommend a model suitable for image understanding and intelligent customer service.",
+  "介绍一下 Bailian CLI 能帮我完成哪些任务，并根据我的需求推荐使用方式。\n   Explain what Bailian CLI can help me accomplish, and recommend how to use it based on my needs.",
 ] as const;
 
 void createCli(

packages/cli/tests/fixtures/command-pack/commands.mjs

@@ -1,5 +1,8 @@
 const ping = {
-  description: "Ping the Command Pack fixture",
+  description: {
+    "en-US": "Ping the Command Pack fixture",
+    "zh-CN": "调用 Command Pack 测试命令",
+  },
   auth: "none",
   flags: {
     message: {

packages/commands/src/commands/advisor/recommend.ts

@@ -226,24 +226,42 @@ function isEmptyResult(result: RecommendResult): boolean {
 }
 
 export default defineCommand({
-  description:
-    "Recommend the best models for your use case (intent analysis → candidate recall → LLM ranking)",
+  description: {
+    "en-US":
+      "Recommend the best models for your use case (intent analysis → candidate recall → LLM ranking)",
+    "zh-CN": "为你的使用场景推荐最佳模型（意图分析 → 候选召回 → LLM 排序）",
+  },
   auth: "apiKey",
   usageArgs: "--message <text> [flags]",
   flags: {
     message: {
       type: "string",
       valueHint: "<text>",
-      description: "Describe your requirements",
+      description: { "en-US": "Describe your requirements", "zh-CN": "描述你的需求" },
       required: true,
     },
   },
   exampleArgs: [
-    '--message "I need a visual-understanding chatbot"',
-    '--message "Build an Agent that auto-generates animations"',
-    '--message "Legal contract review, high precision required"',
-    '--message "Low-cost high-concurrency online customer service" --output text',
-    '--message "Long document summarization" --dry-run',
+    {
+      "en-US": '--message "I need a visual-understanding chatbot"',
+      "zh-CN": '--message "我需要一个能够理解图片的聊天机器人"',
+    },
+    {
+      "en-US": '--message "Build an Agent that auto-generates animations"',
+      "zh-CN": '--message "构建一个可以自动生成动画的智能体"',
+    },
+    {
+      "en-US": '--message "Legal contract review, high precision required"',
+      "zh-CN": '--message "审查法律合同，要求高准确率"',
+    },
+    {
+      "en-US": '--message "Low-cost high-concurrency online customer service" --output text',
+      "zh-CN": '--message "低成本、高并发的在线客服" --output text',
+    },
+    {
+      "en-US": '--message "Long document summarization" --dry-run',
+      "zh-CN": '--message "长文档摘要" --dry-run',
+    },
   ],
   async run(ctx) {
     const { settings, flags } = ctx;

packages/commands/src/commands/app/call.ts

@@ -11,58 +11,111 @@ import {
 import { ansi, emitResult, emitBare } from "bailian-cli-runtime";
 
 export default defineCommand({
-  description: "Call a Bailian application (agent or workflow)",
+  description: {
+    "en-US": "Call a Bailian application (agent or workflow)",
+    "zh-CN": "调用百炼应用（智能体或工作流）",
+  },
   auth: "apiKey",
   usageArgs: "--app-id <id> --prompt <text> [flags]",
   flags: {
     appId: {
       type: "string",
       valueHint: "<id>",
-      description: "Application ID (required)",
+      description: { "en-US": "Application ID (required)", "zh-CN": "应用 ID（必填）" },
       required: true,
     },
     prompt: {
       type: "string",
       valueHint: "<text>",
-      description: "Input prompt text",
+      description: { "en-US": "Input prompt text", "zh-CN": "输入提示词文本" },
       required: true,
     },
     image: {
       type: "array",
       valueHint: "<url>",
-      description: "Image URL(s) to pass to the app (repeatable)",
+      description: {
+        "en-US": "Image URL(s) to pass to the app (repeatable)",
+        "zh-CN": "传给应用的图片 URL（可重复）",
+      },
     },
     fileId: {
       type: "array",
       valueHint: "<id>",
-      description: "Pre-uploaded file ID(s) (repeatable)",
+      description: {
+        "en-US": "Pre-uploaded file ID(s) (repeatable)",
+        "zh-CN": "已上传的文件 ID（可重复）",
+      },
     },
     sessionId: {
       type: "string",
       valueHint: "<id>",
-      description: "Session ID for multi-turn conversation",
+      description: {
+        "en-US": "Session ID for multi-turn conversation",
+        "zh-CN": "多轮对话的 Session ID",
+      },
+    },
+    stream: {
+      type: "switch",
+      description: {
+        "en-US": "Stream response (default: on in TTY)",
+        "zh-CN": "流式输出响应（TTY 中默认开启）",
+      },
     },
-    stream: { type: "switch", description: "Stream response (default: on in TTY)" },
     pipelineIds: {
       type: "string",
       valueHint: "<ids>",
-      description: "Knowledge base pipeline IDs (comma-separated)",
+      description: {
+        "en-US": "Knowledge base pipeline IDs (comma-separated)",
+        "zh-CN": "知识库 Pipeline ID（以逗号分隔）",
+      },
+    },
+    memoryId: {
+      type: "string",
+      valueHint: "<id>",
+      description: {
+        "en-US": "Memory ID for long-term memory",
+        "zh-CN": "长期记忆使用的 Memory ID",
+      },
     },
-    memoryId: { type: "string", valueHint: "<id>", description: "Memory ID for long-term memory" },
     bizParams: {
       type: "string",
       valueHint: "<json>",
-      description: "Business parameters JSON (workflow variables)",
+      description: {
+        "en-US": "Business parameters JSON (workflow variables)",
+        "zh-CN": "业务参数 JSON（工作流变量）",
+      },
+    },
+    hasThoughts: {
+      type: "switch",
+      description: { "en-US": "Show agent thinking process", "zh-CN": "显示智能体思考过程" },
     },
-    hasThoughts: { type: "switch", description: "Show agent thinking process" },
   },
   exampleArgs: [
-    '--app-id abc123 --prompt "Hello"',
-    '--app-id abc123 --prompt "Describe this image" --image https://example.com/photo.jpg',
-    '--app-id abc123 --prompt "Analyze the image" --image img1.jpg --image img2.jpg',
-    '--app-id abc123 --prompt "Continue" --session-id sess_xxx --stream',
-    '--app-id abc123 --prompt "Search for materials" --pipeline-ids pipe1,pipe2',
-    '--app-id abc123 --prompt "Start" --biz-params \'{"key":"value"}\'',
+    {
+      "en-US": '--app-id abc123 --prompt "Hello"',
+      "zh-CN": '--app-id abc123 --prompt "你好"',
+    },
+    {
+      "en-US":
+        '--app-id abc123 --prompt "Describe this image" --image https://example.com/photo.jpg',
+      "zh-CN": '--app-id abc123 --prompt "描述这张图片" --image https://example.com/photo.jpg',
+    },
+    {
+      "en-US": '--app-id abc123 --prompt "Analyze the image" --image img1.jpg --image img2.jpg',
+      "zh-CN": '--app-id abc123 --prompt "分析这些图片" --image img1.jpg --image img2.jpg',
+    },
+    {
+      "en-US": '--app-id abc123 --prompt "Continue" --session-id sess_xxx --stream',
+      "zh-CN": '--app-id abc123 --prompt "继续" --session-id sess_xxx --stream',
+    },
+    {
+      "en-US": '--app-id abc123 --prompt "Search for materials" --pipeline-ids pipe1,pipe2',
+      "zh-CN": '--app-id abc123 --prompt "搜索资料" --pipeline-ids pipe1,pipe2',
+    },
+    {
+      "en-US": '--app-id abc123 --prompt "Start" --biz-params \'{"key":"value"}\'',
+      "zh-CN": '--app-id abc123 --prompt "开始" --biz-params \'{"key":"value"}\'',
+    },
   ],
   async run(ctx) {
     const { settings, flags } = ctx;

packages/commands/src/commands/app/list.ts

@@ -4,27 +4,38 @@ import { emitResult } from "bailian-cli-runtime";
 const APP_LIST_API = "zeldaEasy.broadscope-bailian.app-control.list";
 
 export default defineCommand({
-  description: "List Bailian applications",
+  description: { "en-US": "List Bailian applications", "zh-CN": "列出百炼应用" },
   auth: "console",
   usageArgs: "[flags]",
   flags: {
     name: {
       type: "string",
       valueHint: "<name>",
-      description: "Filter by app name (keyword search)",
+      description: {
+        "en-US": "Filter by app name (keyword search)",
+        "zh-CN": "按应用名称筛选（关键词搜索）",
+      },
     },
     page: {
       type: "number",
       valueHint: "<n>",
-      description: "Page number (default: 1)",
+      description: { "en-US": "Page number (default: 1)", "zh-CN": "页码（默认：1）" },
     },
     pageSize: {
       type: "number",
       valueHint: "<n>",
-      description: "Results per page (default: 30)",
+      description: { "en-US": "Results per page (default: 30)", "zh-CN": "每页结果数（默认：30）" },
     },
   },
-  exampleArgs: ["", "--name customer service", "--page 2 --page-size 10", "--output json"],
+  exampleArgs: [
+    "",
+    {
+      "en-US": "--name customer service",
+      "zh-CN": "--name 客户服务",
+    },
+    "--page 2 --page-size 10",
+    "--output json",
+  ],
   async run(ctx) {
     const { settings, flags } = ctx;
     const name = flags.name || "";

packages/commands/src/commands/auth/generate-access-token.ts

@@ -10,24 +10,33 @@ const FLAGS = {
   accessKeyId: {
     type: "string",
     valueHint: "<id>",
-    description: "Alibaba Cloud Access Key ID",
+    description: { "en-US": "Alibaba Cloud Access Key ID", "zh-CN": "阿里云 Access Key ID" },
     required: true,
   },
   accessKeySecret: {
     type: "string",
     valueHint: "<secret>",
-    description: "Alibaba Cloud Access Key Secret",
+    description: {
+      "en-US": "Alibaba Cloud Access Key Secret",
+      "zh-CN": "阿里云 Access Key Secret",
+    },
     required: true,
   },
   securityToken: {
     type: "string",
     valueHint: "<token>",
-    description: "Alibaba Cloud STS Security Token to store (optional)",
+    description: {
+      "en-US": "Alibaba Cloud STS Security Token to store (optional)",
+      "zh-CN": "要保存的阿里云 STS Security Token（可选）",
+    },
   },
 } satisfies FlagsDef;
 
 export default defineCommand({
-  description: "Generate a CLI access token using OpenAPI AK/SK",
+  description: {
+    "en-US": "Generate a CLI access token using OpenAPI AK/SK",
+    "zh-CN": "使用 OpenAPI AK/SK 生成 CLI Access Token",
+  },
   auth: "none",
   usageArgs: "--access-key-id <id> --access-key-secret <secret> --security-token <token>",
   flags: FLAGS,

packages/commands/src/commands/auth/login.ts

@@ -15,45 +15,66 @@ function hasValue(value: unknown): value is string {
 }
 
 export default defineCommand({
-  description:
-    "Authenticate with API key, console browser login, or OpenAPI AK/SK (credentials can coexist)",
+  description: {
+    "en-US":
+      "Authenticate with API key, console browser login, or OpenAPI AK/SK (credentials can coexist)",
+    "zh-CN": "使用 API Key、控制台浏览器登录或 OpenAPI AK/SK 进行认证（多种凭证可共存）",
+  },
   auth: "none",
   usageArgs:
     "--api-key <key> | --console | --open-api --access-key-id <id> --access-key-secret <secret>",
   flags: {
     apiKey: {
       type: "string",
       valueHint: "<key>",
-      description: "Model API key to store",
+      description: { "en-US": "Model API key to store", "zh-CN": "要保存的模型 API Key" },
     },
     baseUrl: {
       type: "string",
       valueHint: "<url>",
-      description: "Model API base URL (used with --api-key for validation)",
+      description: {
+        "en-US": "Model API base URL (used with --api-key for validation)",
+        "zh-CN": "模型 API Base URL（用于配合 --api-key 进行验证）",
+      },
     },
     console: {
       type: "switch",
-      description:
-        "Sign in via browser; use --console-site to choose domestic (default) or international",
+      description: {
+        "en-US":
+          "Sign in via browser; use --console-site to choose domestic (default) or international",
+        "zh-CN": "通过浏览器登录；使用 --console-site 选择国内站（默认）或国际站",
+      },
     },
     consoleSite: {
       type: "string",
       valueHint: "<site>",
-      description: "Console site: domestic, international",
+      description: {
+        "en-US": "Console site: domestic, international",
+        "zh-CN": "控制台站点：domestic、international",
+      },
     },
     openApi: {
       type: "switch",
-      description: "Store Alibaba Cloud OpenAPI AK/SK credentials",
+      description: {
+        "en-US": "Store Alibaba Cloud OpenAPI AK/SK credentials",
+        "zh-CN": "保存阿里云 OpenAPI AK/SK 凭证",
+      },
     },
     accessKeyId: {
       type: "string",
       valueHint: "<id>",
-      description: "Alibaba Cloud Access Key ID to store",
+      description: {
+        "en-US": "Alibaba Cloud Access Key ID to store",
+        "zh-CN": "要保存的阿里云 Access Key ID",
+      },
     },
     accessKeySecret: {
       type: "string",
       valueHint: "<secret>",
-      description: "Alibaba Cloud Access Key Secret to store",
+      description: {
+        "en-US": "Alibaba Cloud Access Key Secret to store",
+        "zh-CN": "要保存的阿里云 Access Key Secret",
+      },
     },
   },
   exampleArgs: [