feat: Use command.skipDefaultApiKeySetup instead of NO_AUTH_SETUP to determine whether an API key is required

qcq01083097 · qcq01083097 · commit 2ed513124e25 · 2026-06-16T14:59:14.000+08:00
diff --git a/docs/agents/auth-change.md b/docs/agents/auth-change.md
@@ -78,9 +78,7 @@ flag 优先 ─→ config 文件 ─→ env var
 
 ### D. main 启动逻辑
 
-- [ ] `packages/cli/src/main.ts:NO_AUTH_SETUP` 列表:
-  - 如果新增的命令"自己管鉴权或不需要鉴权",加进去绕开 ensureApiKey 拦截
-  - 当前清单以 `main.ts:NO_AUTH_SETUP` 为准
+- [ ] 若新增命令**自行处理鉴权**或**不应在入口触发默认 API key 引导**,在对应 `defineCommand` 上设 `skipDefaultApiKeySetup: true`(见 `packages/core/src/types/command.ts`;`packages/cli/src/main.ts` 在 `registry.resolve` 后读取 `command.skipDefaultApiKeySetup`)
 
 ### E. 错误文案
 
diff --git a/docs/agents/branch-merge-review.md b/docs/agents/branch-merge-review.md
@@ -50,7 +50,7 @@ git diff --name-only <base>...<head>
 - [ ] **`package.json` 没破坏发布元数据**:`bin` / `exports` / `files` / `inlinedDependencies` 字段任何删除或改名都要单独评估
 - [ ] **公共依赖没被悄悄升级**:catalog / 根 lockfile 改动要列出来
 - [ ] **`package.json` version 没倒退**:目标分支已经更高时(如 main 1.0.3 vs head 1.0.0-beta.1),手动对齐版本号,不要被 head 覆盖
-- [ ] **全局表没冲突**:`registry.ts`、`NO_AUTH_SETUP`(`packages/cli/src/main.ts`)、`ExitCode` 三个全局表新增项不和现有项冲突
+- [ ] **全局表没冲突**:`registry.ts`、`defineCommand` 的 `skipDefaultApiKeySetup`(见 `packages/core/src/types/command.ts`)、`ExitCode` 三处新增项不和现有项冲突
 
 ## 清单 B:用户透出(用户可见的新东西必看)
 
@@ -80,7 +80,7 @@ git diff --name-only <base>...<head>
 解冲突要点(merge 时不要漏):
   - <冲突文件> + <字段/段落> + <怎么取舍>
   ↑ 放"合并那一刻才会出现"的细节,例如 package.json 的 files/scripts/devDependencies 各取并集、
-    NO_AUTH_SETUP 这种全局表两边都加项时不要丢一侧、pnpm-lock.yaml 直接 rm 后 pnpm install 重生等。
+    `skipDefaultApiKeySetup` 这类命令元数据两边都加项时不要丢一侧、pnpm-lock.yaml 直接 rm 后 pnpm install 重生等。
 建议修(可后置):
   - ...
 仅信息(无需动作,告知即可):
@@ -94,11 +94,11 @@ git diff --name-only <base>...<head>
 
 ## 常见漏点(基于历史踩坑)
 
-| 漏点                                                                           | 后果                                                                          |
-| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
-| `pnpm-workspace.yaml` 把 `packages/*` 收窄成显式列表                           | 合并后目标分支的新子包不再被 workspace 识别,`pnpm install` 看似正常但子包失联 |
-| 源分支 version 比目标分支低,直接 merge 覆盖                                    | npm 上版本号回退,latest tag 错乱                                              |
-| `registry.ts` 注册新命令但忘了 [README](README.md) / [README.zh](README.zh.md) | 用户完全感知不到新功能                                                        |
-| 共享 util 重构(抽公共函数)只改了一处调用方                                     | 其它调用方静默走旧分支,行为分裂                                               |
-| `NO_AUTH_SETUP` 加了不该免登录的命令                                           | 安全风险,用户没登录也能调付费 API                                             |
-| `NO_AUTH_SETUP` / `registry.ts` 这类全局表两边都加项,解冲突时被合掉一侧        | 某个命令突然要求登录 / 某个新命令注册丢失,编译能过、回归不易察觉              |
+| 漏点                                                                            | 后果                                                                          |
+| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `pnpm-workspace.yaml` 把 `packages/*` 收窄成显式列表                            | 合并后目标分支的新子包不再被 workspace 识别,`pnpm install` 看似正常但子包失联 |
+| 源分支 version 比目标分支低,直接 merge 覆盖                                     | npm 上版本号回退,latest tag 错乱                                              |
+| `registry.ts` 注册新命令但忘了 [README](README.md) / [README.zh](README.zh.md)  | 用户完全感知不到新功能                                                        |
+| 共享 util 重构(抽公共函数)只改了一处调用方                                      | 其它调用方静默走旧分支,行为分裂                                               |
+| 不该跳过默认 API key 引导的命令误设 `skipDefaultApiKeySetup: true`              | 安全风险,用户没配置 key 也能调付费 API                                        |
+| `catalog.ts` / `skipDefaultApiKeySetup` 这类元数据两边都加项,解冲突时被合掉一侧 | 某个命令突然要求登录 / 某个新命令注册丢失,编译能过、回归不易察觉              |
diff --git a/docs/agents/command-add-remove.md b/docs/agents/command-add-remove.md
@@ -53,7 +53,7 @@ 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 读取)
-- [ ] 如果命令需要鉴权之外的特殊路径,看 `packages/cli/src/main.ts` 的 `NO_AUTH_SETUP`
+- [ ] 如果命令需要跳过入口的默认 DashScope API key 引导(`ensureApiKey`),在对应 `defineCommand` 上设 `skipDefaultApiKeySetup: true`(字段定义见 `packages/core/src/types/command.ts`;`main.ts` 根据已解析的 `command` 读取)
 - [ ] **`config/export-schema.ts`**: 若新命令不适合作为 agent tool,评估是否加入 `SKIP_PREFIXES`;该文件在 `run()` 内 `import("../catalog.ts")`,勿顶层 import catalog 以免循环依赖
 
 ### B. 文档层
diff --git a/packages/cli/src/commands/app/list.ts b/packages/cli/src/commands/app/list.ts
@@ -13,6 +13,7 @@ const APP_LIST_API = "zeldaEasy.broadscope-bailian.app-control.list";
 export default defineCommand({
   name: "app list",
   description: "List Bailian applications",
+  skipDefaultApiKeySetup: true,
   usage: "bl app list [flags]",
   options: [
     {
diff --git a/packages/cli/src/commands/auth/login.ts b/packages/cli/src/commands/auth/login.ts
@@ -81,6 +81,7 @@ async function validateKeyAndPersist(config: Config, key: string): Promise<void>
 export default defineCommand({
   name: "auth login",
   description: "Authenticate with API key or console browser login (credentials can coexist)",
+  skipDefaultApiKeySetup: true,
   usage: "bl auth login --api-key <key> | bl auth login --console",
   options: [
     { flag: "--api-key <key>", description: "DashScope API key to store" },
diff --git a/packages/cli/src/commands/auth/logout.ts b/packages/cli/src/commands/auth/logout.ts
@@ -20,6 +20,7 @@ async function clearConsoleToken(): Promise<boolean> {
 export default defineCommand({
   name: "auth logout",
   description: "Clear stored credentials",
+  skipDefaultApiKeySetup: true,
   usage: "bl auth logout [--console] [--yes] [--dry-run]",
   options: [
     {
diff --git a/packages/cli/src/commands/config/export-schema.ts b/packages/cli/src/commands/config/export-schema.ts
@@ -13,6 +13,7 @@ export default defineCommand({
   name: "config export-schema",
   description:
     "Export all (or one) CLI command(s) as Anthropic/OpenAI-compatible JSON tool schemas",
+  skipDefaultApiKeySetup: true,
   usage: 'bl config export-schema [--command "<name>"]',
   options: [
     {
diff --git a/packages/cli/src/commands/config/set.ts b/packages/cli/src/commands/config/set.ts
@@ -53,6 +53,7 @@ const KEY_ALIASES: Record<string, string> = {
 export default defineCommand({
   name: "config set",
   description: "Set a config value",
+  skipDefaultApiKeySetup: true,
   usage: "bl config set --key <key> --value <value>",
   options: [
     {
diff --git a/packages/cli/src/commands/config/show.ts b/packages/cli/src/commands/config/show.ts
@@ -12,6 +12,7 @@ import { emitResult } from "../../output/output.ts";
 export default defineCommand({
   name: "config show",
   description: "Display current configuration",
+  skipDefaultApiKeySetup: true,
   usage: "bl config show",
   examples: ["bl config show", "bl config show --output json"],
   async run(config: Config, _flags: GlobalFlags) {
diff --git a/packages/cli/src/commands/console/call.ts b/packages/cli/src/commands/console/call.ts
@@ -14,6 +14,7 @@ import { emitResult } from "../../output/output.ts";
 export default defineCommand({
   name: "console call",
   description: "Call a Bailian console API via the CLI gateway",
+  skipDefaultApiKeySetup: true,
   usage: "bl console call --api <api> --data <json> [flags]",
   options: [
     {
diff --git a/packages/cli/src/commands/knowledge/retrieve.ts b/packages/cli/src/commands/knowledge/retrieve.ts
@@ -25,6 +25,7 @@ const BAILIAN_HOST = "bailian.cn-beijing.aliyuncs.com";
 export default defineCommand({
   name: "knowledge retrieve",
   description: "Retrieve from a Bailian knowledge base",
+  skipDefaultApiKeySetup: true,
   usage: "bl knowledge retrieve --index-id <id> --query <text> [flags]",
   options: [
     { flag: "--index-id <id>", description: "Knowledge base index ID (required)", required: true },
diff --git a/packages/cli/src/commands/mcp/call.ts b/packages/cli/src/commands/mcp/call.ts
@@ -32,6 +32,7 @@ function parseArgFlags(raw: string[]): Record<string, unknown> {
 export default defineCommand({
   name: "mcp call",
   description: "Call a tool on an MCP server (tools/call)",
+  skipDefaultApiKeySetup: true,
   usage: "bl mcp call <server-code>.<tool> [--arg k=v ...] [--json '{...}'] [--url <url>]",
   options: [
     {
diff --git a/packages/cli/src/commands/mcp/list.ts b/packages/cli/src/commands/mcp/list.ts
@@ -26,6 +26,7 @@ interface ServerSummary {
 export default defineCommand({
   name: "mcp list",
   description: "List MCP servers activated under your Bailian account",
+  skipDefaultApiKeySetup: true,
   usage: "bl mcp list [flags]",
   options: [
     { flag: "--name <text>", description: "Filter by server name (substring match)" },
diff --git a/packages/cli/src/commands/mcp/tools.ts b/packages/cli/src/commands/mcp/tools.ts
@@ -13,6 +13,7 @@ import { ensureApiKey } from "../../utils/ensure-key.ts";
 export default defineCommand({
   name: "mcp tools",
   description: "List tools exposed by an MCP server (tools/list)",
+  skipDefaultApiKeySetup: true,
   usage: "bl mcp tools <server-code> [--url <url>]",
   options: [
     {
diff --git a/packages/cli/src/commands/pipeline/run.ts b/packages/cli/src/commands/pipeline/run.ts
@@ -10,6 +10,7 @@ import { loadPipelineFile } from "./load-file.ts";
 export default defineCommand({
   name: "pipeline run",
   description: "Run a pipeline workflow definition",
+  skipDefaultApiKeySetup: true,
   usage: "bl pipeline run <file> [flags]",
   options: [
     { flag: "--input <json>", description: "Runtime input as inline JSON" },
diff --git a/packages/cli/src/commands/pipeline/validate.ts b/packages/cli/src/commands/pipeline/validate.ts
@@ -8,6 +8,7 @@ import { loadPipelineFile } from "./load-file.ts";
 export default defineCommand({
   name: "pipeline validate",
   description: "Validate a pipeline definition without executing",
+  skipDefaultApiKeySetup: true,
   usage: "bl pipeline validate <file>",
   options: [],
   examples: [
diff --git a/packages/cli/src/commands/quota/check.ts b/packages/cli/src/commands/quota/check.ts
@@ -250,6 +250,7 @@ function printTable(rows: CheckRow[], noColor: boolean): void {
 export default defineCommand({
   name: "quota check",
   description: "Check current usage against rate limits",
+  skipDefaultApiKeySetup: true,
   usage: "bl quota check [--model <model>] [flags]",
   options: [
     {
diff --git a/packages/cli/src/commands/quota/history.ts b/packages/cli/src/commands/quota/history.ts
@@ -100,6 +100,7 @@ function printTable(records: LimitApplicationItem[], noColor: boolean, total: nu
 export default defineCommand({
   name: "quota history",
   description: "View quota change history",
+  skipDefaultApiKeySetup: true,
   usage: "bl quota history [flags]",
   options: [
     {
diff --git a/packages/cli/src/commands/quota/list.ts b/packages/cli/src/commands/quota/list.ts
@@ -161,6 +161,7 @@ function printTable(models: ModelWithQpm[], noColor: boolean): void {
 export default defineCommand({
   name: "quota list",
   description: "View model RPM/TPM rate limits",
+  skipDefaultApiKeySetup: true,
   usage: "bl quota list [--model <model>] [flags]",
   options: [
     {
diff --git a/packages/cli/src/commands/quota/request.ts b/packages/cli/src/commands/quota/request.ts
@@ -82,6 +82,7 @@ async function fetchModelQpmInfo(
 export default defineCommand({
   name: "quota request",
   description: "Request a temporary quota increase",
+  skipDefaultApiKeySetup: true,
   usage: "bl quota request --model <model> --tpm <value> [flags]",
   options: [
     {
diff --git a/packages/cli/src/commands/update.ts b/packages/cli/src/commands/update.ts
@@ -28,6 +28,7 @@ function updateAgentSkill(colors: { green: string; yellow: string; reset: string
 export default defineCommand({
   name: "update",
   description: "Update bl to the latest version",
+  skipDefaultApiKeySetup: true,
   usage: "bl update",
   examples: ["bl update"],
   async run() {
diff --git a/packages/cli/src/commands/usage/free.ts b/packages/cli/src/commands/usage/free.ts
@@ -193,6 +193,7 @@ async function fetchAllModels(config: Config, token: string): Promise<ModelInfo[
 export default defineCommand({
   name: "usage free",
   description: "Query free-tier quota for models (all models if --model is omitted)",
+  skipDefaultApiKeySetup: true,
   usage: "bl usage free [--model <model>[,model2,...]] [flags]",
   options: [
     {
diff --git a/packages/cli/src/commands/usage/freetier.ts b/packages/cli/src/commands/usage/freetier.ts
@@ -105,6 +105,7 @@ export default defineCommand({
   name: "usage freetier",
   description:
     "Enable or disable auto-stop for free-tier models. Enables by default; use --off to disable",
+  skipDefaultApiKeySetup: true,
   usage: "bl usage freetier <--model <model>[,model2,...] | --all> [--off] [flags]",
   options: [
     {
diff --git a/packages/cli/src/commands/usage/stats.ts b/packages/cli/src/commands/usage/stats.ts
@@ -307,6 +307,7 @@ function printModelTable(
 export default defineCommand({
   name: "usage stats",
   description: "Query model usage statistics",
+  skipDefaultApiKeySetup: true,
   usage: "bl usage stats [--model <model>] [--days <days>] [flags]",
   options: [
     {
diff --git a/packages/cli/src/commands/workspace/list.ts b/packages/cli/src/commands/workspace/list.ts
@@ -87,6 +87,7 @@ function printTable(workspaces: WorkspaceInfo[], noColor: boolean): void {
 export default defineCommand({
   name: "workspace list",
   description: "List all workspaces",
+  skipDefaultApiKeySetup: true,
   usage: "bl workspace list [flags]",
   options: [
     {
diff --git a/packages/cli/src/main.ts b/packages/cli/src/main.ts
@@ -45,32 +45,6 @@ process.stdout.on("error", (e: NodeJS.ErrnoException) => {
   else throw e;
 });
 
-// 自己接管鉴权 或 根本不需要 API key 的命令
-const NO_AUTH_SETUP = [
-  ["auth", "login"],
-  ["auth", "logout"],
-  ["config", "show"],
-  ["config", "set"],
-  ["config", "export-schema"],
-  ["update"],
-  ["knowledge", "retrieve"],
-  ["pipeline", "run"],
-  ["pipeline", "validate"],
-  ["app", "list"],
-  ["console", "call"],
-  ["usage", "free"],
-  ["usage", "freetier"],
-  ["usage", "stats"],
-  ["mcp", "list"],
-  ["mcp", "tools"],
-  ["mcp", "call"],
-  ["workspace", "list"],
-  ["quota", "list"],
-  ["quota", "request"],
-  ["quota", "history"],
-  ["quota", "check"],
-];
-
 async function main() {
   let argv = process.argv.slice(2);
   if (argv[0] === "--") argv = argv.slice(1);
@@ -122,8 +96,8 @@ async function main() {
   config.clientName = "bailian-cli";
   config.clientVersion = CLI_VERSION;
 
-  const needsAuthSetup = !NO_AUTH_SETUP.some((cmd) => cmd.every((c, i) => commandPath[i] === c));
-  if (needsAuthSetup) {
+  // 默认执行 ensureApiKey；自行处理鉴权或仅需 Console/AK-SK 等的命令在 defineCommand 上设 skipDefaultApiKeySetup
+  if (!command.skipDefaultApiKeySetup) {
     await ensureApiKey(config);
     try {
       const credential = await resolveCredential(config);
diff --git a/packages/core/src/types/command.ts b/packages/core/src/types/command.ts
@@ -14,6 +14,12 @@ export interface Command {
   usage?: string;
   options?: OptionDef[];
   examples?: string[];
+  /**
+   * When true, the CLI entrypoint skips the default DashScope API key prompt
+   * (`ensureApiKey`) and the optional status bar credential resolution; the
+   * command implements its own auth (Console token, AK/SK, pipeline-only, etc.).
+   */
+  skipDefaultApiKeySetup?: boolean;
   execute: (config: Config, flags: GlobalFlags) => Promise<void>;
 }
 
@@ -23,6 +29,7 @@ export interface CommandSpec {
   usage?: string;
   options?: OptionDef[];
   examples?: string[];
+  skipDefaultApiKeySetup?: boolean;
   run: (config: Config, flags: GlobalFlags) => Promise<void>;
 }
 
@@ -33,6 +40,7 @@ export function defineCommand(spec: CommandSpec): Command {
     usage: spec.usage,
     options: spec.options,
     examples: spec.examples,
+    skipDefaultApiKeySetup: spec.skipDefaultApiKeySetup,
     execute: (config, flags) => spec.run(config, flags),
   };
 }

Original file line number	Diff line number	Diff line change
`@@ -13,6 +13,7 @@ const APP_LIST_API = "zeldaEasy.broadscope-bailian.app-control.list";`
`13`	`13`	`export default defineCommand({`
`14`	`14`	`name: "app list",`
`15`	`15`	`description: "List Bailian applications",`
	`16`	`+ skipDefaultApiKeySetup: true,`
`16`	`17`	`usage: "bl app list [flags]",`
`17`	`18`	`options: [`
`18`	`19`	`{`
Original file line number	Diff line number	Diff line change
`@@ -20,6 +20,7 @@ async function clearConsoleToken(): Promise<boolean> {`
`20`	`20`	`export default defineCommand({`
`21`	`21`	`name: "auth logout",`
`22`	`22`	`description: "Clear stored credentials",`
	`23`	`+ skipDefaultApiKeySetup: true,`
`23`	`24`	`usage: "bl auth logout [--console] [--yes] [--dry-run]",`
`24`	`25`	`options: [`
`25`	`26`	`{`
Original file line number	Diff line number	Diff line change
`@@ -13,6 +13,7 @@ export default defineCommand({`
`13`	`13`	`name: "config export-schema",`
`14`	`14`	`description:`
`15`	`15`	`"Export all (or one) CLI command(s) as Anthropic/OpenAI-compatible JSON tool schemas",`
	`16`	`+ skipDefaultApiKeySetup: true,`
`16`	`17`	`usage: 'bl config export-schema [--command "<name>"]',`
`17`	`18`	`options: [`
`18`	`19`	`{`
Original file line number	Diff line number	Diff line change
`@@ -53,6 +53,7 @@ const KEY_ALIASES: Record<string, string> = {`
`53`	`53`	`export default defineCommand({`
`54`	`54`	`name: "config set",`
`55`	`55`	`description: "Set a config value",`
	`56`	`+ skipDefaultApiKeySetup: true,`
`56`	`57`	`usage: "bl config set --key <key> --value <value>",`
`57`	`58`	`options: [`
`58`	`59`	`{`
Original file line number	Diff line number	Diff line change
`@@ -14,6 +14,7 @@ import { emitResult } from "../../output/output.ts";`
`14`	`14`	`export default defineCommand({`
`15`	`15`	`name: "console call",`
`16`	`16`	`description: "Call a Bailian console API via the CLI gateway",`
	`17`	`+ skipDefaultApiKeySetup: true,`
`17`	`18`	`usage: "bl console call --api <api> --data <json> [flags]",`
`18`	`19`	`options: [`
`19`	`20`	`{`