diff --git a/docs/agents/branch-merge-review.md b/docs/agents/branch-merge-review.md index be5667e..78f26dd 100644 --- a/docs/agents/branch-merge-review.md +++ b/docs/agents/branch-merge-review.md @@ -57,7 +57,7 @@ git diff --name-only ... - [ ] **新命令 / 新 flag** 已同步到用户面文档: - [README.md](README.md) + [README.zh.md](README.zh.md)(中英文都要,常漏 `_CN`) - (SKILL.md 已迁出本仓库,由 `npx add skills` 机制独立维护,不在本仓库 review 范围) -- [ ] **`bl --help`** 文案完整:`description` / `examples` / `apiDocs` 都填了 +- [ ] **`bl --help`** 文案完整:`description` / `examples` 都填了 - [ ] **demo / quickstart**:用户可调用的新命令至少有一个示例 - [ ] **行为变化的老命令**:在 commit message / CHANGELOG 注明用户感知的差异 - [ ] **错误信息 / 提示文案**:面向用户的字符串通顺、双语(项目主体是中文场景) diff --git a/docs/agents/command-add-remove.md b/docs/agents/command-add-remove.md index bdc0763..c68905a 100644 --- 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 ↓ @@ -53,7 +53,6 @@ registry.ts main.ts tools/generate-reference.ts export-schema.ts - 增删 `import xxx from "./.../xxx.ts"` - 在 `export const commands` 里增删 `" ": 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 index 62ec72d..9d6a1cc 100644 --- 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 --model ", options: [ { diff --git a/packages/cli/src/commands/image/edit.ts b/packages/cli/src/commands/image/edit.ts index 42f5d14..7942c13 100644 --- 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 --prompt [flags]", options: [ { diff --git a/packages/cli/src/commands/image/generate.ts b/packages/cli/src/commands/image/generate.ts index 1b89c90..ddfd3e8 100644 --- 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 [flags]", options: [ { flag: "--prompt ", description: "Image description", required: true }, diff --git a/packages/cli/src/commands/omni/chat.ts b/packages/cli/src/commands/omni/chat.ts index 169b831..828b8a5 100644 --- 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 [flags]", options: [ { diff --git a/packages/cli/src/commands/speech/recognize.ts b/packages/cli/src/commands/speech/recognize.ts index 3fdf21c..05e8874 100644 --- 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 [flags]", options: [ { diff --git a/packages/cli/src/commands/speech/synthesize.ts b/packages/cli/src/commands/speech/synthesize.ts index e20eda6..f134d6f 100644 --- 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 [flags]", options: [ { flag: "--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 index 18d74f0..9741c6d 100644 --- 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 [flags]", options: [ { flag: "--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 index 9ec8948..29fba24 100644 --- 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 --prompt [flags]", options: [ { flag: "--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 index 4fcab06..dc958d6 100644 --- 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 [--image ] [flags]", options: [ { diff --git a/packages/cli/src/commands/video/ref.ts b/packages/cli/src/commands/video/ref.ts index ecf185f..4eca5fd 100644 --- 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 --image ... [--ref-video ...] [flags]", options: [ { flag: "--model ", description: "Model ID (default: happyhorse-1.0-r2v)" }, diff --git a/packages/cli/src/main.ts b/packages/cli/src/main.ts index 798abe0..1cf512c 100644 --- 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 index d485ece..70ed9f8 100644 --- 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 index 4f236dd..02bbcf5 100644 --- 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; } @@ -24,7 +23,6 @@ export interface CommandSpec { usage?: string; options?: OptionDef[]; examples?: string[]; - apiDocs?: string; run: (config: Config, flags: GlobalFlags) => Promise; } @@ -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 index a9fc9fb..ef892da 100644 --- 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 --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 --model ` | #### Options diff --git a/skills/bailian-cli/reference/image.md b/skills/bailian-cli/reference/image.md index 64d0519..330068e 100644 --- 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 --prompt [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 --prompt [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 [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 [flags]` | #### Options diff --git a/skills/bailian-cli/reference/omni.md b/skills/bailian-cli/reference/omni.md index 9db91a3..11e39a1 100644 --- 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 [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 [flags]` | #### Options diff --git a/skills/bailian-cli/reference/speech.md b/skills/bailian-cli/reference/speech.md index eb4eaf9..873b5b3 100644 --- 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 [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 [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 [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 [flags]` | #### Options diff --git a/skills/bailian-cli/reference/text.md b/skills/bailian-cli/reference/text.md index 0f71186..a1dedfa 100644 --- 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 [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 [flags]` | #### Options diff --git a/skills/bailian-cli/reference/video.md b/skills/bailian-cli/reference/video.md index ff57302..42df4d6 100644 --- a/skills/bailian-cli/reference/video.md +++ b/skills/bailian-cli/reference/video.md @@ -44,12 +44,11 @@ bl video download --task-id 3b256896-xxxx --out video.mp4 --quiet ### `bl video edit` -| Field | Value | -| --------------- | ------------------------------------------------------------------------------------------------------- | -| **Name** | `video edit` | -| **Description** | Edit a video with happyhorse-1.0-video-edit (style transfer, object replacement, etc.) | -| **Usage** | `bl video edit --video --prompt [flags]` | -| **API docs** | [/best-practice/wanx/video-edit](https://help.aliyun.com/zh/model-studio/best-practice/wanx/video-edit) | +| Field | Value | +| --------------- | -------------------------------------------------------------------------------------- | +| **Name** | `video edit` | +| **Description** | Edit a video with happyhorse-1.0-video-edit (style transfer, object replacement, etc.) | +| **Usage** | `bl video edit --video --prompt [flags]` | #### Options @@ -92,12 +91,11 @@ bl video edit --video https://example.com/input.mp4 --prompt "给视频里的小 ### `bl video generate` -| Field | Value | -| --------------- | ------------------------------------------------------------------------------------------------------------- | -| **Name** | `video generate` | -| **Description** | Generate a video from text or image (happyhorse-1.0-t2v / happyhorse-1.0-i2v / wan2.6-t2v) | -| **Usage** | `bl video generate --prompt [--image ] [flags]` | -| **API docs** | [/best-practice/wanx/text-to-video](https://help.aliyun.com/zh/model-studio/best-practice/wanx/text-to-video) | +| Field | Value | +| --------------- | ------------------------------------------------------------------------------------------ | +| **Name** | `video generate` | +| **Description** | Generate a video from text or image (happyhorse-1.0-t2v / happyhorse-1.0-i2v / wan2.6-t2v) | +| **Usage** | `bl video generate --prompt [--image ] [flags]` | #### Options @@ -142,12 +140,11 @@ bl video generate --prompt "A cat playing with a ball" --watermark false ### `bl video ref` -| Field | Value | -| --------------- | ----------------------------------------------------------------------------------------------------------------- | -| **Name** | `video ref` | -| **Description** | Reference-to-video generation (happyhorse-1.0-r2v / wan2.6-r2v): multi-subject, multi-shot with voice | -| **Usage** | `bl video ref --prompt --image ... [--ref-video ...] [flags]` | -| **API docs** | [/best-practice/wanx/video-reference](https://help.aliyun.com/zh/model-studio/best-practice/wanx/video-reference) | +| Field | Value | +| --------------- | ----------------------------------------------------------------------------------------------------- | +| **Name** | `video ref` | +| **Description** | Reference-to-video generation (happyhorse-1.0-r2v / wan2.6-r2v): multi-subject, multi-shot with voice | +| **Usage** | `bl video ref --prompt --image ... [--ref-video ...] [flags]` | #### Options diff --git a/tools/generate-reference.ts b/tools/generate-reference.ts index 903cf56..8a223e6 100644 --- a/tools/generate-reference.ts +++ b/tools/generate-reference.ts @@ -11,12 +11,7 @@ import { mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs"; import { dirname, join } from "node:path"; import { fileURLToPath } from "node:url"; -import { - DOCS_HOSTS, - GLOBAL_OPTIONS, - type Command, - type OptionDef, -} from "../packages/core/dist/index.mjs"; +import { GLOBAL_OPTIONS, type Command, type OptionDef } from "../packages/core/dist/index.mjs"; import { commands } from "../packages/cli/src/commands/catalog.ts"; const __dirname = dirname(fileURLToPath(import.meta.url)); @@ -69,10 +64,6 @@ function commandSection(path: string, cmd: Command): string { if (cmd.usage) { lines.push(`| **Usage** | \`${escCell(cmd.usage)}\` |`); } - if (cmd.apiDocs) { - const url = `${DOCS_HOSTS.cn}${cmd.apiDocs}`; - lines.push(`| **API docs** | [${escCell(cmd.apiDocs)}](${url}) |`); - } lines.push(""); lines.push("#### Options", "");