Merge pull request #53 from modelstudioai/feat/delete-apiDocs

XXPermanentXX · web-flow · commit 7c1be3906750 · 2026-06-12T16:05:55.000+08:00
feat: No longer expose API documentation
diff --git a/docs/agents/branch-merge-review.md b/docs/agents/branch-merge-review.md
@@ -57,7 +57,7 @@ git diff --name-only <base>...<head>
 - [ ] **新命令 / 新 flag** 已同步到用户面文档:
   - [README.md](README.md) + [README.zh.md](README.zh.md)(中英文都要,常漏 `_CN`)
   - (SKILL.md 已迁出本仓库,由 `npx add skills` 机制独立维护,不在本仓库 review 范围)
-- [ ] **`bl <cmd> --help`** 文案完整:`description` / `examples` / `apiDocs` 都填了
+- [ ] **`bl <cmd> --help`** 文案完整:`description` / `examples` 都填了
 - [ ] **demo / quickstart**:用户可调用的新命令至少有一个示例
 - [ ] **行为变化的老命令**:在 commit message / CHANGELOG 注明用户感知的差异
 - [ ] **错误信息 / 提示文案**:面向用户的字符串通顺、双语(项目主体是中文场景)
diff --git a/docs/agents/command-add-remove.md b/docs/agents/command-add-remove.md
@@ -27,7 +27,7 @@
 命令元数据以 **`catalog.ts` 为单一登记处**;`registry.ts` 只负责解析与打印 help,不再内嵌命令表或手写 Resources 列表。
 
 ```
-commands/<...>.ts   defineCommand({ name, description, usage, options, examples, apiDocs?, run })
+commands/<...>.ts   defineCommand({ name, description, usage, options, examples, run })
         ↓
 commands/catalog.ts   export const commands: Record<string, Command>
         ↓
@@ -53,7 +53,6 @@ registry.ts  main.ts      tools/generate-reference.ts   export-schema.ts
   - 增删 `import xxx from "./.../xxx.ts"`
   - 在 `export const commands` 里增删 `"<group> <action>": xxx`(key 与 `defineCommand({ name })` 一致)
 - [ ] **不要**在 `registry.ts` 里重复登记命令(已从 catalog 读取)
-- [ ] 命令需在 `bl help` / `reference/` 展示 API 文档链接时,在 `defineCommand` 里设 `apiDocs`(相对路径);help 与 reference 均从此字段生成
 - [ ] 如果命令需要鉴权之外的特殊路径,看 `packages/cli/src/main.ts` 的 `NO_AUTH_SETUP`
 - [ ] **`config/export-schema.ts`**: 若新命令不适合作为 agent tool,评估是否加入 `SKIP_PREFIXES`;该文件在 `run()` 内 `import("../catalog.ts")`,勿顶层 import catalog 以免循环依赖
 
diff --git a/packages/cli/src/commands/file/upload.ts b/packages/cli/src/commands/file/upload.ts
@@ -12,7 +12,6 @@ import { emitResult, emitBare } from "../../output/output.ts";
 export default defineCommand({
   name: "file upload",
   description: "Upload a local file to DashScope temporary storage (48h)",
-  apiDocs: "/developer-reference/get-temporary-file-url",
   usage: "bl file upload --file <path> --model <model>",
   options: [
     {
diff --git a/packages/cli/src/commands/image/edit.ts b/packages/cli/src/commands/image/edit.ts
@@ -32,7 +32,6 @@ import {
 export default defineCommand({
   name: "image edit",
   description: "Edit an existing image with text instructions (Qwen-Image)",
-  apiDocs: "/developer-reference/qwen-image-edit-api",
   usage: "bl image edit --image <url> --prompt <text> [flags]",
   options: [
     {
diff --git a/packages/cli/src/commands/image/generate.ts b/packages/cli/src/commands/image/generate.ts
@@ -43,7 +43,6 @@ function isSyncModel(model: string): boolean {
 export default defineCommand({
   name: "image generate",
   description: "Generate images (Qwen-Image / wan2.x)",
-  apiDocs: "/best-practice/wanx/text-to-image",
   usage: "bl image generate --prompt <text> [flags]",
   options: [
     { flag: "--prompt <text>", description: "Image description", required: true },
diff --git a/packages/cli/src/commands/omni/chat.ts b/packages/cli/src/commands/omni/chat.ts
@@ -44,7 +44,6 @@ function buildWavHeader(dataLength: number): Buffer {
 export default defineCommand({
   name: "omni",
   description: "Multimodal chat with text + audio output (Qwen-Omni)",
-  apiDocs: "/model-studio/qwen-omni",
   usage: "bl omni --message <text> [flags]",
   options: [
     {
diff --git a/packages/cli/src/commands/speech/recognize.ts b/packages/cli/src/commands/speech/recognize.ts
@@ -25,7 +25,6 @@ import { emitResult, emitBare } from "../../output/output.ts";
 export default defineCommand({
   name: "speech recognize",
   description: "Recognize speech from audio files (FunAudio-ASR)",
-  apiDocs: "/developer-reference/recording-file-recognition",
   usage: "bl speech recognize --url <audio-url> [flags]",
   options: [
     {
diff --git a/packages/cli/src/commands/speech/synthesize.ts b/packages/cli/src/commands/speech/synthesize.ts
@@ -144,7 +144,6 @@ function printVoiceList(model: string): void {
 export default defineCommand({
   name: "speech synthesize",
   description: "Synthesize speech from text (CosyVoice TTS)",
-  apiDocs: "/developer-reference/cosyvoice",
   usage: "bl speech synthesize --text <text> [flags]",
   options: [
     { flag: "--text <text>", description: "Text to synthesize into speech", required: true },
diff --git a/packages/cli/src/commands/text/chat.ts b/packages/cli/src/commands/text/chat.ts
@@ -70,7 +70,6 @@ function parseMessages(flags: GlobalFlags): ParsedMessages {
 export default defineCommand({
   name: "text chat",
   description: "Send a chat completion (OpenAI compatible, DashScope)",
-  apiDocs: "/compatibility-of-openai-with-dashscope",
   usage: "bl text chat --message <text> [flags]",
   options: [
     { flag: "--model <model>", description: "Model ID (default: qwen3.7-max)" },
diff --git a/packages/cli/src/commands/video/edit.ts b/packages/cli/src/commands/video/edit.ts
@@ -31,7 +31,6 @@ export default defineCommand({
   name: "video edit",
   description:
     "Edit a video with happyhorse-1.0-video-edit (style transfer, object replacement, etc.)",
-  apiDocs: "/best-practice/wanx/video-edit",
   usage: "bl video edit --video <url> --prompt <text> [flags]",
   options: [
     { flag: "--model <model>", description: "Model ID (default: happyhorse-1.0-video-edit)" },
diff --git a/packages/cli/src/commands/video/generate.ts b/packages/cli/src/commands/video/generate.ts
@@ -44,7 +44,6 @@ export default defineCommand({
   name: "video generate",
   description:
     "Generate a video from text or image (happyhorse-1.0-t2v / happyhorse-1.0-i2v / wan2.6-t2v)",
-  apiDocs: "/best-practice/wanx/text-to-video",
   usage: "bl video generate --prompt <text> [--image <url>] [flags]",
   options: [
     {
diff --git a/packages/cli/src/commands/video/ref.ts b/packages/cli/src/commands/video/ref.ts
@@ -31,7 +31,6 @@ export default defineCommand({
   name: "video ref",
   description:
     "Reference-to-video generation (happyhorse-1.0-r2v / wan2.6-r2v): multi-subject, multi-shot with voice",
-  apiDocs: "/best-practice/wanx/video-reference",
   usage: "bl video ref --prompt <text> --image <url>... [--ref-video <url>...] [flags]",
   options: [
     { flag: "--model <model>", description: "Model ID (default: happyhorse-1.0-r2v)" },
diff --git a/packages/cli/src/main.ts b/packages/cli/src/main.ts
@@ -3,11 +3,9 @@ import { registry } from "./registry.ts";
 import {
   GLOBAL_OPTIONS,
   loadConfig,
-  readConfigFile,
   resolveCredential,
   trackCommandExecution,
   flushTelemetry,
-  type Region,
 } from "bailian-cli-core";
 import { ensureApiKey } from "./utils/ensure-key.ts";
 import { handleError } from "./error-handler.ts";
@@ -22,13 +20,7 @@ import {
 } from "./utils/command-help.ts";
 
 registerCommandHelpPrinter((commandPath, out) => {
-  const a = process.argv.slice(2);
-  const ri = a.indexOf("--region");
-  const region = ((ri >= 0 && a[ri + 1]) ||
-    process.env.DASHSCOPE_REGION ||
-    readConfigFile().region ||
-    "cn") as Region;
-  registry.printHelp(commandPath, out, region);
+  registry.printHelp(commandPath, out);
 });
 
 // 优雅处理 Ctrl+C
@@ -84,12 +76,7 @@ async function main() {
   const commandPath = scanCommandPath(argv, GLOBAL_OPTIONS);
 
   if (argv.includes("--help") || argv.includes("-h")) {
-    const ri = argv.indexOf("--region");
-    const region = ((ri >= 0 && argv[ri + 1]) ||
-      process.env.DASHSCOPE_REGION ||
-      readConfigFile().region ||
-      "cn") as Region;
-    registry.printHelp(commandPath, process.stderr, region);
+    registry.printHelp(commandPath, process.stderr);
     process.exit(0);
   }
 
@@ -115,12 +102,7 @@ async function main() {
 
   // 组路径（例如 `bl speech` 未接子命令）：展示帮助后干净退出
   if (registry.isGroupPath(commandPath)) {
-    const ri = argv.indexOf("--region");
-    const region = ((ri >= 0 && argv[ri + 1]) ||
-      process.env.DASHSCOPE_REGION ||
-      readConfigFile().region ||
-      "cn") as Region;
-    registry.printHelp(commandPath, process.stderr, region);
+    registry.printHelp(commandPath, process.stderr);
     process.exit(0);
   }
 
diff --git a/packages/cli/src/registry.ts b/packages/cli/src/registry.ts
@@ -1,7 +1,7 @@
 import type { Command } from "bailian-cli-core";
 import { BailianError } from "bailian-cli-core";
 import { ExitCode } from "bailian-cli-core";
-import { DOCS_HOSTS, GLOBAL_OPTIONS, type Region } from "bailian-cli-core";
+import { GLOBAL_OPTIONS } from "bailian-cli-core";
 import { commands } from "./commands/catalog.ts";
 
 export type { Command, OptionDef } from "bailian-cli-core";
@@ -133,11 +133,7 @@ class CommandRegistry {
     out.isTTY ? `\x1b[38;2;59;130;246m${s}\x1b[0m` : s;
   private dim = (s: string, out: NodeJS.WriteStream) => (out.isTTY ? `\x1b[2m${s}\x1b[0m` : s);
 
-  printHelp(
-    commandPath: string[],
-    out: NodeJS.WriteStream = process.stdout,
-    region: Region = "cn",
-  ): void {
+  printHelp(commandPath: string[], out: NodeJS.WriteStream = process.stdout): void {
     if (commandPath.length === 0) {
       this.printRootHelp(out);
       return;
@@ -154,7 +150,7 @@ class CommandRegistry {
     }
 
     if (node.command) {
-      this.printCommandHelp(node.command, out, region);
+      this.printCommandHelp(node.command, out);
       return;
     }
 
@@ -233,7 +229,7 @@ ${b("Getting Help:")}
 `);
   }
 
-  private printCommandHelp(cmd: Command, out: NodeJS.WriteStream, region: Region = "cn"): void {
+  private printCommandHelp(cmd: Command, out: NodeJS.WriteStream): void {
     const b = (s: string) => this.bold(s, out);
     const a = (s: string) => this.accent(s, out);
     const d = (s: string) => this.dim(s, out);
@@ -253,9 +249,6 @@ ${b("Getting Help:")}
         out.write(`  ${d(ex)}\n`);
       }
     }
-    if (cmd.apiDocs) {
-      out.write(`\n${b("API Reference:")} ${d(DOCS_HOSTS[region] + cmd.apiDocs)}\n`);
-    }
     out.write(
       `\n${d("Global flags (--api-key, --output, --quiet, etc.) are always available.")}\n`,
     );
diff --git a/packages/core/src/types/command.ts b/packages/core/src/types/command.ts
@@ -14,7 +14,6 @@ export interface Command {
   usage?: string;
   options?: OptionDef[];
   examples?: string[];
-  apiDocs?: string;
   execute: (config: Config, flags: GlobalFlags) => Promise<void>;
 }
 
@@ -24,7 +23,6 @@ export interface CommandSpec {
   usage?: string;
   options?: OptionDef[];
   examples?: string[];
-  apiDocs?: string;
   run: (config: Config, flags: GlobalFlags) => Promise<void>;
 }
 
@@ -35,7 +33,6 @@ export function defineCommand(spec: CommandSpec): Command {
     usage: spec.usage,
     options: spec.options,
     examples: spec.examples,
-    apiDocs: spec.apiDocs,
     execute: (config, flags) => spec.run(config, flags),
   };
 }
diff --git a/skills/bailian-cli/reference/file.md b/skills/bailian-cli/reference/file.md
@@ -15,12 +15,11 @@ Index: [index.md](index.md)
 
 ### `bl file upload`
 
-| Field           | Value                                                                                                                             |
-| --------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| **Name**        | `file upload`                                                                                                                     |
-| **Description** | Upload a local file to DashScope temporary storage (48h)                                                                          |
-| **Usage**       | `bl file upload --file <path> --model <model>`                                                                                    |
-| **API docs**    | [/developer-reference/get-temporary-file-url](https://help.aliyun.com/zh/model-studio/developer-reference/get-temporary-file-url) |
+| Field           | Value                                                    |
+| --------------- | -------------------------------------------------------- |
+| **Name**        | `file upload`                                            |
+| **Description** | Upload a local file to DashScope temporary storage (48h) |
+| **Usage**       | `bl file upload --file <path> --model <model>`           |
 
 #### Options
 
diff --git a/skills/bailian-cli/reference/image.md b/skills/bailian-cli/reference/image.md
@@ -16,12 +16,11 @@ Index: [index.md](index.md)
 
 ### `bl image edit`
 
-| Field           | Value                                                                                                                       |
-| --------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| **Name**        | `image edit`                                                                                                                |
-| **Description** | Edit an existing image with text instructions (Qwen-Image)                                                                  |
-| **Usage**       | `bl image edit --image <url> --prompt <text> [flags]`                                                                       |
-| **API docs**    | [/developer-reference/qwen-image-edit-api](https://help.aliyun.com/zh/model-studio/developer-reference/qwen-image-edit-api) |
+| Field           | Value                                                      |
+| --------------- | ---------------------------------------------------------- |
+| **Name**        | `image edit`                                               |
+| **Description** | Edit an existing image with text instructions (Qwen-Image) |
+| **Usage**       | `bl image edit --image <url> --prompt <text> [flags]`      |
 
 #### Options
 
@@ -63,12 +62,11 @@ bl image edit --image ./photo.png --prompt "把背景换成海滩" --watermark f
 
 ### `bl image generate`
 
-| Field           | Value                                                                                                         |
-| --------------- | ------------------------------------------------------------------------------------------------------------- |
-| **Name**        | `image generate`                                                                                              |
-| **Description** | Generate images (Qwen-Image / wan2.x)                                                                         |
-| **Usage**       | `bl image generate --prompt <text> [flags]`                                                                   |
-| **API docs**    | [/best-practice/wanx/text-to-image](https://help.aliyun.com/zh/model-studio/best-practice/wanx/text-to-image) |
+| Field           | Value                                       |
+| --------------- | ------------------------------------------- |
+| **Name**        | `image generate`                            |
+| **Description** | Generate images (Qwen-Image / wan2.x)       |
+| **Usage**       | `bl image generate --prompt <text> [flags]` |
 
 #### Options
 
diff --git a/skills/bailian-cli/reference/omni.md b/skills/bailian-cli/reference/omni.md
@@ -15,12 +15,11 @@ Index: [index.md](index.md)
 
 ### `bl omni`
 
-| Field           | Value                                                                                     |
-| --------------- | ----------------------------------------------------------------------------------------- |
-| **Name**        | `omni`                                                                                    |
-| **Description** | Multimodal chat with text + audio output (Qwen-Omni)                                      |
-| **Usage**       | `bl omni --message <text> [flags]`                                                        |
-| **API docs**    | [/model-studio/qwen-omni](https://help.aliyun.com/zh/model-studio/model-studio/qwen-omni) |
+| Field           | Value                                                |
+| --------------- | ---------------------------------------------------- |
+| **Name**        | `omni`                                               |
+| **Description** | Multimodal chat with text + audio output (Qwen-Omni) |
+| **Usage**       | `bl omni --message <text> [flags]`                   |
 
 #### Options
 
diff --git a/skills/bailian-cli/reference/speech.md b/skills/bailian-cli/reference/speech.md
@@ -16,12 +16,11 @@ Index: [index.md](index.md)
 
 ### `bl speech recognize`
 
-| Field           | Value                                                                                                                                     |
-| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| **Name**        | `speech recognize`                                                                                                                        |
-| **Description** | Recognize speech from audio files (FunAudio-ASR)                                                                                          |
-| **Usage**       | `bl speech recognize --url <audio-url> [flags]`                                                                                           |
-| **API docs**    | [/developer-reference/recording-file-recognition](https://help.aliyun.com/zh/model-studio/developer-reference/recording-file-recognition) |
+| Field           | Value                                            |
+| --------------- | ------------------------------------------------ |
+| **Name**        | `speech recognize`                               |
+| **Description** | Recognize speech from audio files (FunAudio-ASR) |
+| **Usage**       | `bl speech recognize --url <audio-url> [flags]`  |
 
 #### Options
 
@@ -70,12 +69,11 @@ bl speech recognize --url https://example.com/audio.mp3 --no-wait --quiet
 
 ### `bl speech synthesize`
 
-| Field           | Value                                                                                                   |
-| --------------- | ------------------------------------------------------------------------------------------------------- |
-| **Name**        | `speech synthesize`                                                                                     |
-| **Description** | Synthesize speech from text (CosyVoice TTS)                                                             |
-| **Usage**       | `bl speech synthesize --text <text> [flags]`                                                            |
-| **API docs**    | [/developer-reference/cosyvoice](https://help.aliyun.com/zh/model-studio/developer-reference/cosyvoice) |
+| Field           | Value                                        |
+| --------------- | -------------------------------------------- |
+| **Name**        | `speech synthesize`                          |
+| **Description** | Synthesize speech from text (CosyVoice TTS)  |
+| **Usage**       | `bl speech synthesize --text <text> [flags]` |
 
 #### Options
 
diff --git a/skills/bailian-cli/reference/text.md b/skills/bailian-cli/reference/text.md
@@ -15,12 +15,11 @@ Index: [index.md](index.md)
 
 ### `bl text chat`
 
-| Field           | Value                                                                                                                     |
-| --------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| **Name**        | `text chat`                                                                                                               |
-| **Description** | Send a chat completion (OpenAI compatible, DashScope)                                                                     |
-| **Usage**       | `bl text chat --message <text> [flags]`                                                                                   |
-| **API docs**    | [/compatibility-of-openai-with-dashscope](https://help.aliyun.com/zh/model-studio/compatibility-of-openai-with-dashscope) |
+| Field           | Value                                                 |
+| --------------- | ----------------------------------------------------- |
+| **Name**        | `text chat`                                           |
+| **Description** | Send a chat completion (OpenAI compatible, DashScope) |
+| **Usage**       | `bl text chat --message <text> [flags]`               |
 
 #### Options
 
diff --git a/skills/bailian-cli/reference/video.md b/skills/bailian-cli/reference/video.md
diff --git a/tools/generate-reference.ts b/tools/generate-reference.ts

Original file line number	Diff line number	Diff line change
`@@ -12,7 +12,6 @@ import { emitResult, emitBare } from "../../output/output.ts";`
`12`	`12`	`export default defineCommand({`
`13`	`13`	`name: "file upload",`
`14`	`14`	`description: "Upload a local file to DashScope temporary storage (48h)",`
`15`		`- apiDocs: "/developer-reference/get-temporary-file-url",`
`16`	`15`	`usage: "bl file upload --file <path> --model <model>",`
`17`	`16`	`options: [`
`18`	`17`	`{`
Original file line number	Diff line number	Diff line change
`@@ -32,7 +32,6 @@ import {`
`32`	`32`	`export default defineCommand({`
`33`	`33`	`name: "image edit",`
`34`	`34`	`description: "Edit an existing image with text instructions (Qwen-Image)",`
`35`		`- apiDocs: "/developer-reference/qwen-image-edit-api",`
`36`	`35`	`usage: "bl image edit --image <url> --prompt <text> [flags]",`
`37`	`36`	`options: [`
`38`	`37`	`{`
Original file line number	Diff line number	Diff line change
`@@ -44,7 +44,6 @@ function buildWavHeader(dataLength: number): Buffer {`
`44`	`44`	`export default defineCommand({`
`45`	`45`	`name: "omni",`
`46`	`46`	`description: "Multimodal chat with text + audio output (Qwen-Omni)",`
`47`		`- apiDocs: "/model-studio/qwen-omni",`
`48`	`47`	`usage: "bl omni --message <text> [flags]",`
`49`	`48`	`options: [`
`50`	`49`	`{`
Original file line number	Diff line number	Diff line change
`@@ -25,7 +25,6 @@ import { emitResult, emitBare } from "../../output/output.ts";`
`25`	`25`	`export default defineCommand({`
`26`	`26`	`name: "speech recognize",`
`27`	`27`	`description: "Recognize speech from audio files (FunAudio-ASR)",`
`28`		`- apiDocs: "/developer-reference/recording-file-recognition",`
`29`	`28`	`usage: "bl speech recognize --url <audio-url> [flags]",`
`30`	`29`	`options: [`
`31`	`30`	`{`