refactor(flags): scope credential flags by command auth domain

- flags split into GLOBAL_FLAGS (all commands) plus MODEL_AUTH_FLAGS /
  CONSOLE_AUTH_FLAGS, parsed only for commands of the matching auth
  domain; cross-domain flags now fail with "Unknown flag" instead of
  being silently ignored
- all shadow redeclarations removed; the registry guard now rejects any
  own flag named after a reserved (global or visible-domain) flag
- --workspace-id joins the console domain (chain: flag > env > file);
  usage stats drops its private declaration and in-command priority
- auth login declares its credential args as own command parameters
  (--api-key / --base-url / --console-site, original behavior intact);
  auth status no longer accepts credential-domain overrides (use env or
  config set instead)
- command help and the generated reference both show Flags (own + auth
  domain) plus a full Global Flags section, replacing the footer hint
- breaking: pipeline run --timeout renamed to --step-timeout (collided
  with the global request timeout)

Author: XXPermanentXX

docs/config-flags-refactor.md

@@ -6,6 +6,8 @@
 >
 > 实施(2026-07-06):**已按本方案完成**——前置 baseUrl 翻转 + 阶段 0–6 全部落地(含 flags 收窄/分流/同名守卫、console/advisor/pipeline 收口、tracker 传值、边界守卫测试 `packages/commands/tests/boundaries.test.ts`)。全量 `vp check`/单测/关键 e2e 绿;**未 commit,待 review**。实施中的偏差:advisor 匿名调网关促使 `callConsoleGateway` 收 `ConsoleGatewayTarget`(token 可选)而非整个 credential;`describeAuth` 更名 `describeAuthState`;`ConfigStore.reset` 无消费者未实现。
 >
+> flag 边界轮(2026-07-06):**域化完成**——flag 拆 `GLOBAL_FLAGS` + `MODEL_AUTH_FLAGS`/`CONSOLE_AUTH_FLAGS`(按命令 `auth`/`authFlags` 可见),16 处遮蔽清零,跨域传 flag 报错,help 改为 Flags(自有+域)/Global Flags(全量)三段式,`pipeline run --timeout` 更名 `--step-timeout`,login 经 `AuthStore.flagInput()` 收凭证输入。workspaceId 已升入 console 域(链 flag > env > file),stats 命令内优先级删除。
+>
 > 修订(2026-07-04 评审后,均已拍板):§8 改 strangler 分阶段 + 阶段 0 行为锁定测试(已落地);§2 store 接口细化(write async / unset / AuthStore.login 揽登录落盘);§5 validate 收 ownFlags + 同名守卫 + authStage dry-run 双域容忍;§7 tracker/workspaceId 修法;§0/§9 优先级链保真口径。dry-run 决策:**保持"无需凭证"现状**,console 三元组归 Settings 服务 dry-run 展示(不引入 ConsoleTarget);dry-run 输出规范统一推后(§9)。
 >
 > 约束(务必遵守):
@@ -343,9 +345,9 @@ const authStage = async (ctx, next) => {
 ## 9. 本次不做(已在钉钉文档记录,后续单独轮次)
 
 - **flag 清理**:`nonInteractive` 删 / `async` ↔ 各命令 `--no-wait` 去重 / `yes` 收窄到命令级 / `noColor` 修一致性(registry/progress/banner 里内联 `process.stderr.isTTY` 绕过了 `config.noColor`)。
-- **workspaceId 的 flag 源**:今天没有全局 `--workspace-id`,只有 `usage/stats` 自声明的命令级 flag(命令内做 flag > settings 覆盖)。是否提升为全局 flag,与下条同名遮蔽清理**同一轮**看——都是全局↔命令级 flag 的边界问题。(优先级链归一本身已完成:唯一异类 baseUrl 已前置翻转,见 §0。)
+- ~~workspaceId 的 flag 源~~ **已完成**(flag 边界轮):`--workspace-id` 升入 `CONSOLE_AUTH_FLAGS`,链为 flag > env > file;stats 删除自有声明与命令内优先级。(优先级链归一与同名遮蔽清理亦已完成:baseUrl 前置翻转见 §0,遮蔽经域化清零见 §5。)
 - **dry-run 输出规范统一**:各域输出现状不一致 —— model/app 域只打请求 body(不含 URL/baseUrl),console 域额外打 api 名 + region/site 路由信息。应一次定规范、跨域对齐(是否展示路由、展示哪些字段);届时若 console 域不再展示,console 三元组可从 Settings 撤出、收敛为纯 credential。**本次保持现状输出**(e2e 有断言)。
-- **全局↔命令私有 flag 同名遮蔽**清理(§5 提到的 ~15 个)。本次用"全局恒进 sources"规避,不动声明。
+- ~~全局↔命令私有 flag 同名遮蔽清理~~ **已完成**(flag 边界轮,经域化):16 处遮蔽全删,凭证 flag 按 `auth` 域可见,跨域报 Unknown flag,守卫升级为同名即抛。
 - **key ↔ baseUrl 强校验**(region 锁)。落点已就位:`resolveApiKey` 是唯一同时产出 `{token, baseUrl}` 的地方,校验加在它内部即可;baseUrl 不在 Settings,命令侧无法绕过绑定;`AuthStore.login` 已支持 `api_key` + `base_url` 成对落盘。
 - **多 profile / 多身份**(arkcli 式)。结构已留缝:单一 `ResolutionSources` 边界 + credential 封装。
 - **IOStreams 注入**(gh `Factory.IOStreams` / vercel `Client.stdout`);与 noColor 修复同属下一轮。

packages/cli/tests/e2e/auth.e2e.test.ts

@@ -161,22 +161,22 @@ describe("e2e: auth", () => {
   });
 
   test.skipIf(!isDashScopeE2EReady())(
-    "auth status --output json --quiet --base-url 国内",
+    "auth status --output json --quiet(base_url 经 env 指定;凭证域 flag 对 status 不可见)",
     async () => {
-      const { stdout, stderr, exitCode } = await runCli([
-        "auth",
-        "status",
-        "--non-interactive",
-        "--output",
-        "json",
-        "--quiet",
-        "--base-url",
-        "https://dashscope.aliyuncs.com",
-      ]);
+      const { stdout, stderr, exitCode } = await runCli(
+        ["auth", "status", "--non-interactive", "--output", "json", "--quiet"],
+        { DASHSCOPE_BASE_URL: "https://dashscope.aliyuncs.com" },
+      );
       expect(exitCode, stderr).toBe(0);
       const data = parseStdoutJson<{ authenticated?: boolean; api_key?: unknown }>(stdout);
       expect(data.authenticated).toBe(true);
       expect(data.api_key).toBeDefined();
     },
   );
+
+  test("auth status 不接受凭证域覆盖 flag(--base-url 报 Unknown flag)", async () => {
+    const { stderr, exitCode } = await runCli(["auth", "status", "--base-url", "https://x.test"]);
+    expect(exitCode).not.toBe(0);
+    expect(stderr).toMatch(/Unknown flag.*--base-url/);
+  });
 });

packages/cli/tests/e2e/console-flags.e2e.test.ts

@@ -23,15 +23,37 @@ describe("e2e: console global flags", () => {
     expect(stderr).not.toMatch(/^\s*--region\s/m);
   });
 
-  test("quota check --help 不重复命令级 region，并提示全局 flags", async () => {
+  test("quota check --help:Flags 含 console 域鉴权 flag,Global Flags 全量列出", async () => {
     const { stderr, exitCode } = await runCli(["quota", "check", "--help"]);
     expect(exitCode, stderr).toBe(0);
-    expect(stderr).toMatch(/Global flags.*always available/i);
+    expect(stderr).toMatch(/Global Flags:/);
+    expect(stderr).toMatch(/--console-region <region>/);
     expect(stderr).toMatch(/--model <model>/);
     expect(stderr).toMatch(/--period <minutes>/);
+    expect(stderr).toMatch(/--output <format>/);
     expect(stderr).not.toMatch(/API region \(default: cn-beijing\)/);
   });
 
+  test("跨域 flag 拒绝:model 命令传 --console-region 报 Unknown flag", async () => {
+    const { stderr, exitCode } = await runCli([
+      "text",
+      "chat",
+      "--message",
+      "hi",
+      "--console-region",
+      "cn-hangzhou",
+      "--dry-run",
+    ]);
+    expect(exitCode).not.toBe(0);
+    expect(stderr).toMatch(/Unknown flag.*--console-region/);
+  });
+
+  test("跨域 flag 拒绝:console 命令传 --api-key 报 Unknown flag", async () => {
+    const { stderr, exitCode } = await runCli(["mcp", "list", "--api-key", "sk-test", "--dry-run"]);
+    expect(exitCode).not.toBe(0);
+    expect(stderr).toMatch(/Unknown flag.*--api-key/);
+  });
+
   test("console call --help 不暴露命令级 region/site，示例使用 --console-region", async () => {
     const { stderr, exitCode } = await runCli(["console", "call", "--help"]);
     expect(exitCode, stderr).toBe(0);
@@ -42,11 +64,14 @@ describe("e2e: console global flags", () => {
     expect(stderr).toMatch(/--console-region cn-beijing/);
   });
 
-  test("auth login --help 描述 --console 与 --console-site 配合", async () => {
+  test("auth login --help:自有 flag 含 --console-site,不含其余 console 域 flag", async () => {
     const { stderr, exitCode } = await runCli(["auth", "login", "--help"]);
     expect(exitCode, stderr).toBe(0);
-    expect(stderr).toMatch(/--console-site/);
-    expect(stderr).toMatch(/--console.*console-site|console-site.*domestic|international/i);
+    expect(stderr).toMatch(/--api-key <key>/);
+    expect(stderr).toMatch(/--base-url <url>/);
+    expect(stderr).toMatch(/--console-site <site>/);
+    expect(stderr).not.toMatch(/--console-region/);
+    expect(stderr).not.toMatch(/--workspace-id/);
   });
 
   test("console call --dry-run 默认 consoleRegion 为 cn-beijing", async () => {

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

@@ -23,13 +23,6 @@ export default defineCommand({
       valueHint: "<n>",
       description: "Results per page (default: 30)",
     },
-    consoleRegion: { type: "string", valueHint: "<region>", description: "Console region" },
-    consoleSite: {
-      type: "string",
-      valueHint: "<site>",
-      description: "Console site: domestic, international",
-    },
-    consoleSwitchAgent: { type: "number", valueHint: "<uid>", description: "Switch agent UID" },
   },
   exampleArgs: ["", "--name customer service", "--page 2 --page-size 10", "--output json"],
   async run(ctx) {

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

@@ -23,41 +23,48 @@ export default defineCommand({
       description:
         "Sign in via browser; use --console-site to choose domestic (default) or international",
     },
+    consoleSite: {
+      type: "string",
+      valueHint: "<site>",
+      description: "Console site: domestic, international",
+    },
   },
   exampleArgs: ["--api-key sk-xxxxx", "--console"],
   validate: (f) => (!f.console && !f.apiKey ? "Provide --api-key or --console" : undefined),
   async run(ctx) {
     const { identity, settings, flags } = ctx;
     const store = ctx.authStore();
     const deps = { identity, settings, authStore: store };
+    const key = flags.apiKey;
+    const baseUrl = flags.baseUrl || undefined;
+
     if (flags.console) {
       if (settings.dryRun) {
         emitBare(
           "Would bind a free port on 127.0.0.1 and open the console login URL in your browser.",
         );
         return;
       }
-      const hasApiKey = !!(flags.apiKey || store.stored().apiKey);
-      await runConsoleLogin(resolveConsoleOrigin(settings.consoleSite || "domestic"), deps, {
+      const hasApiKey = !!(key || store.stored().apiKey);
+      // 本次登录站点:参数缺省时用配置默认(file 里上次登录存的站点)。
+      const site = flags.consoleSite || settings.consoleSite || "domestic";
+      await runConsoleLogin(resolveConsoleOrigin(site), deps, {
         needApiKey: !hasApiKey,
       });
       return;
     }
 
     // --api-key path; validate() guarantees apiKey on the non-console branch.
-    if (flags.apiKey) {
-      const key = flags.apiKey;
-      const baseUrl = flags.baseUrl || undefined;
+    if (!key) return;
 
-      if (settings.dryRun) {
-        emitBare("Would validate and save API key.");
-        return;
-      }
-      if (baseUrl) {
-        await store.login({ base_url: baseUrl });
-      }
-      await validateAndPersistApiKey(deps, key, baseUrl || store.resolveBaseUrl());
-      printQuickStart();
+    if (settings.dryRun) {
+      emitBare("Would validate and save API key.");
+      return;
+    }
+    if (baseUrl) {
+      await store.login({ base_url: baseUrl });
     }
+    await validateAndPersistApiKey(deps, key, baseUrl || store.resolveBaseUrl());
+    printQuickStart();
   },
 });

packages/commands/src/commands/auth/logout.ts

@@ -4,15 +4,14 @@ import { emitBare } from "bailian-cli-runtime";
 export default defineCommand({
   description: "Clear stored credentials",
   auth: "none",
-  usageArgs: "[--console] [--yes] [--dry-run]",
+  usageArgs: "[--console] [--dry-run]",
   flags: {
     console: {
       type: "switch",
       description: "Only clear the console access_token, keep api_key intact",
     },
-    yes: { type: "switch", description: "Skip confirmation prompt" },
   },
-  exampleArgs: ["", "--console", "--dry-run", "--yes"],
+  exampleArgs: ["", "--console", "--dry-run"],
   async run(ctx) {
     const { settings, flags } = ctx;
     const store = ctx.authStore();

packages/commands/src/commands/auth/status.ts

@@ -6,15 +6,6 @@ export default defineCommand({
   description: "Show current authentication state",
   auth: "none",
   exampleArgs: ["", "--output json"],
-  flags: {
-    consoleRegion: { type: "string", valueHint: "<region>", description: "Console region" },
-    consoleSite: {
-      type: "string",
-      valueHint: "<site>",
-      description: "Console site: domestic, international",
-    },
-    consoleSwitchAgent: { type: "number", valueHint: "<uid>", description: "Switch agent UID" },
-  },
   async run(ctx) {
     const { identity, settings } = ctx;
     const format = detectOutputFormat(settings.output);

packages/commands/src/commands/console/call.ts

@@ -23,13 +23,6 @@ export default defineCommand({
       description: "Request data as JSON string",
       required: true,
     },
-    consoleRegion: { type: "string", valueHint: "<region>", description: "Console region" },
-    consoleSite: {
-      type: "string",
-      valueHint: "<site>",
-      description: "Console site: domestic, international",
-    },
-    consoleSwitchAgent: { type: "number", valueHint: "<uid>", description: "Switch agent UID" },
   },
   exampleArgs: [
     `--api zeldaEasy.broadscope-bailian.freeTrial.queryFreeTierQuota --data '{"queryFreeTierQuotaRequest":{"models":["qwen3-max"]}}'`,

packages/commands/src/commands/mcp/list.ts

@@ -37,13 +37,6 @@ export default defineCommand({
     },
     page: { type: "number", valueHint: "<n>", description: "Page number (default: 1)" },
     pageSize: { type: "number", valueHint: "<n>", description: "Results per page (default: 30)" },
-    consoleRegion: { type: "string", valueHint: "<region>", description: "Console region" },
-    consoleSite: {
-      type: "string",
-      valueHint: "<site>",
-      description: "Console site: domestic, international",
-    },
-    consoleSwitchAgent: { type: "number", valueHint: "<uid>", description: "Switch agent UID" },
   },
   exampleArgs: ["", "--name finance", "--output json"],
   async run(ctx) {

packages/commands/src/commands/pipeline/run.ts

@@ -31,7 +31,7 @@ const RUN_FLAGS = {
     description: "Emit lifecycle events: jsonl",
     choices: ["jsonl"] as const,
   },
-  timeout: {
+  stepTimeout: {
     type: "number",
     valueHint: "<seconds>",
     description: "Default step timeout in seconds",
@@ -70,7 +70,7 @@ export default defineCommand({
         concurrency: flags.concurrency,
         basePath,
         dryRun: settings.dryRun,
-        timeoutSeconds: flags.timeout,
+        timeoutSeconds: flags.stepTimeout,
       })) {
         process.stdout.write(JSON.stringify(event) + "\n");
       }
@@ -81,7 +81,7 @@ export default defineCommand({
       concurrency: flags.concurrency,
       basePath,
       dryRun: settings.dryRun,
-      timeoutSeconds: flags.timeout,
+      timeoutSeconds: flags.stepTimeout,
       onEvent: settings.verbose ? logEvent : undefined,
     });