fix(runtime): preserve explicit --config default in recovery hints

Author: hopelynd

docs/agents/error-hint-change.md

@@ -109,7 +109,7 @@ process.exit(err.exitCode)
 - [ ] 追加时若已有 hint(如 video task id),拼接并按标记去重;不要 `hint` 非空就跳过
 - [ ] 渲染产品命令前须经能力门控(命令表是否暴露对应 path),不要对 `kscli` 等缺命令的产品硬拼 `usage freetier`
 - [ ] 命令名使用 `commandPrefix`,不要硬编码 `bl`
-- [ ] 恢复命令经 `recoveryCommand` 渲染：命名 Profile 激活时追加 `--config <name>`（default / 未指定不加）
+- [ ] 恢复命令经 `recoveryCommand` 渲染；Profile 名用 `resolveRecoveryConfigName`（显式 `--config default` 保留，隐式 default 不加）
 - [ ] URL 必须是 `import { API_KEY_PAGE } from "./urls.ts"`
 
 ### C. command / runtime 直接抛错

packages/commands/src/commands/knowledge/chunk-delete.ts

@@ -103,7 +103,12 @@ export default defineCommand({
         deletedCount += batchIds.length;
         completedBatches.push(batchIds);
       } catch (error) {
-        const original = normalizeError(error, formatCommand(ctx.identity), ctx.localize);
+        const original = normalizeError(
+          error,
+          formatCommand(ctx.identity),
+          ctx.localize,
+          ctx.settings.configName,
+        );
         const failedBatch = completedBatches.length + 1;
         const progress = [
           ctx.localize({

packages/commands/src/commands/usage/freetier.ts

@@ -58,30 +58,12 @@ export default defineCommand({
     },
   },
   exampleArgs: [
-    {
-      "en-US": "--model qwen3-max --yes",
-      "zh-CN": "--model qwen3-max --yes",
-    },
-    {
-      "en-US": "--model qwen3-max,qwen-turbo --yes",
-      "zh-CN": "--model qwen3-max,qwen-turbo --yes",
-    },
-    {
-      "en-US": "--all --yes",
-      "zh-CN": "--all --yes",
-    },
-    {
-      "en-US": "--on --model qwen3-max --yes",
-      "zh-CN": "--on --model qwen3-max --yes",
-    },
-    {
-      "en-US": "--off --model qwen3-max --yes",
-      "zh-CN": "--off --model qwen3-max --yes",
-    },
-    {
-      "en-US": "--off --all --yes",
-      "zh-CN": "--off --all --yes",
-    },
+    "--model qwen3-max --yes",
+    "--model qwen3-max,qwen-turbo --yes",
+    "--all --yes",
+    "--on --model qwen3-max --yes",
+    "--off --model qwen3-max --yes",
+    "--off --all --yes",
   ],
   notes: [
     {

packages/commands/tests/e2e/usage-freetier.e2e.test.ts

@@ -1,7 +1,15 @@
 import { describe, expect, test } from "vite-plus/test";
-import { runCommandE2e, runCommandHelp } from "./helpers.ts";
+import { parseStdoutJson, runCommandHelp, runCommandInProcess } from "./helpers.ts";
 import { USAGE_ROUTES } from "./topic-routes.ts";
 
+/** Clear host OpenAPI env so console auth cannot exchange a local AK/SK into a session. */
+const CLEAR_OPENAPI_ENV = {
+  BAILIAN_ACCESS_KEY_ID: undefined,
+  BAILIAN_ACCESS_KEY_SECRET: undefined,
+  ALIBABA_CLOUD_ACCESS_KEY_ID: undefined,
+  ALIBABA_CLOUD_ACCESS_KEY_SECRET: undefined,
+};
+
 describe("e2e: usage freetier", () => {
   test("usage freetier --help 展示 risk、--yes 与确认示例", async () => {
     const { stderr, exitCode } = await runCommandHelp(USAGE_ROUTES, [
@@ -19,7 +27,7 @@ describe("e2e: usage freetier", () => {
   });
 
   test("usage freetier 无 --yes 返回确认请求 (7)", async () => {
-    const { stderr, exitCode } = await runCommandE2e(USAGE_ROUTES, [
+    const { stderr, exitCode } = await runCommandInProcess(USAGE_ROUTES, [
       "usage",
       "freetier",
       "--model",
@@ -34,20 +42,54 @@ describe("e2e: usage freetier", () => {
   });
 
   test("usage freetier --yes 通过确认门槛后落到 AUTH (3)", async () => {
-    // Clear OpenAPI env so console auth cannot exchange a host AK/SK into a session.
-    const { stderr, exitCode } = await runCommandE2e(
+    const { stderr, exitCode } = await runCommandInProcess(
       USAGE_ROUTES,
       ["usage", "freetier", "--model", "qwen-plus", "--yes", "--output", "json"],
-      {
-        BAILIAN_ACCESS_KEY_ID: undefined,
-        BAILIAN_ACCESS_KEY_SECRET: undefined,
-        ALIBABA_CLOUD_ACCESS_KEY_ID: undefined,
-        ALIBABA_CLOUD_ACCESS_KEY_SECRET: undefined,
-      },
+      CLEAR_OPENAPI_ENV,
     );
     expect(exitCode).toBe(3);
     expect(JSON.parse(stderr)).toMatchObject({
       error: { code: 3 },
     });
   });
+
+  test("usage freetier --dry-run 跳过确认并输出计划（零网络）", async () => {
+    const { stdout, stderr, exitCode } = await runCommandInProcess(USAGE_ROUTES, [
+      "usage",
+      "freetier",
+      "--model",
+      "qwen-plus",
+      "--dry-run",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    expect(stderr).not.toContain("requires_confirmation");
+    const data = parseStdoutJson<{
+      api: string;
+      data: { BatchActivateFreeTierOnlyRequest: { models: string[] } };
+    }>(stdout);
+    expect(data.api).toBe("zeldaEasy.bailian-commerce.freeTrial.batchActivateFreeTierOnly");
+    expect(data.data.BatchActivateFreeTierOnlyRequest.models).toEqual(["qwen-plus"]);
+  });
+
+  test("usage freetier --off --dry-run 输出停用计划", async () => {
+    const { stdout, stderr, exitCode } = await runCommandInProcess(USAGE_ROUTES, [
+      "usage",
+      "freetier",
+      "--off",
+      "--model",
+      "qwen-plus",
+      "--dry-run",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{
+      api: string;
+      data: { BatchDeactivateFreeTierOnlyRequest: { models: string[] } };
+    }>(stdout);
+    expect(data.api).toBe("zeldaEasy.bailian-commerce.freeTrial.batchDeactivateFreeTierOnly");
+    expect(data.data.BatchDeactivateFreeTierOnlyRequest.models).toEqual(["qwen-plus"]);
+  });
 });

packages/runtime/src/create-cli.ts

@@ -40,7 +40,7 @@ import {
   Client,
 } from "bailian-cli-core";
 import { setupProxyFromEnv } from "./proxy.ts";
-import { handleError } from "./error-handler.ts";
+import { handleError, resolveRecoveryConfigName } from "./error-handler.ts";
 import { type OutputReporter, createOutputReporter } from "./output/reporter.ts";
 import { loadCommandPacks } from "./command-packs/load.ts";
 import { createCommandPackManager } from "./command-packs/manager.ts";
@@ -346,13 +346,14 @@ export function createCli(commands: Record<string, AnyCommand>, opts: CliOptions
       const cleanup = installProcessHandlers(() => reporter, localize);
       try {
         const sources = buildSources(flags, (warning) => warnings.push(warning));
+        const recoveryConfigName = resolveRecoveryConfigName(sources);
         translator = createTranslator(sources.file.language ?? DEFAULT_LANGUAGE);
         reporter = createOutputReporter({
           settings: buildOutputSettings(sources),
           localize,
           commandPrefix,
           supportsFreeTierRecovery,
-          configName: sources.configName,
+          configName: recoveryConfigName,
         });
         setupProxyFromEnv();
         const registry = await getRegistry(translator);
@@ -362,7 +363,7 @@ export function createCli(commands: Record<string, AnyCommand>, opts: CliOptions
             localize,
             commandPrefix,
             supportsFreeTierRecovery,
-            configName: sources.configName,
+            configName: recoveryConfigName,
           });
           for (const warning of warnings.splice(0)) reporter.output.warning(warning);
           return reporter;

packages/runtime/src/error-handler.ts

@@ -34,8 +34,23 @@ type Localize = (text: LocalizedText) => string;
 const english: Localize = (text) => (typeof text === "string" ? text : text["en-US"]);
 
 /**
- * 恢复命令统一入口：命名 Profile 激活时追加 `--config <name>`，
- * 避免用户按 hint 操作打到错误的凭证/计费配置。
+ * Config name for recovery hints (does not change IO-layer `configName` semantics).
+ * Explicit `--config default` is normalized to undefined in the loader; keep
+ * `"default"` here so copying the hint does not fall back to an active named profile.
+ */
+export function resolveRecoveryConfigName(sources: {
+  flags: { config?: unknown };
+  configName?: string;
+}): string | undefined {
+  if (sources.flags.config !== undefined) {
+    return sources.configName ?? "default";
+  }
+  return sources.configName;
+}
+
+/**
+ * Format a recovery command; append `--config <name>` when a profile must be pinned
+ * so following the hint does not hit the wrong credentials/billing config.
  */
 function recoveryCommand(commandPrefix: string, args: string, configName?: string): string {
   const withConfig = configName ? `${args} --config ${configName}` : args;
@@ -56,7 +71,10 @@ export interface ErrorHintOptions {
    * under this product's commandPrefix. Derived from the product command map.
    */
   supportsFreeTierRecovery?: boolean;
-  /** 当前命名 Profile；未指定或 default 时为 undefined，恢复命令不加 `--config`。 */
+  /**
+   * Profile to pin in recovery commands (via `resolveRecoveryConfigName`).
+   * Implicit default is undefined; explicit `--config default` is `"default"`.
+   */
   configName?: string;
 }
 
@@ -79,7 +97,7 @@ function freeTierRecoveryHint(
   configName?: string,
 ): string {
   const statusCommand = recoveryCommand(commandPrefix, "usage free --model <model>", configName);
-  // 不带 --yes：调用方先撞确认门槛（exit 7），再按 skill 规范向用户确认。
+  // Omit --yes so the caller hits the confirmation gate (exit 7) first.
   const disableCommand = recoveryCommand(
     commandPrefix,
     "usage freetier --off --model <model>",
@@ -120,7 +138,7 @@ export function errorHint(
   }
   // Append free-tier recovery before the AUTH-only early return so GENERAL
   // service errors (and async paths that already set a hint) still get guidance.
-  // 已含恢复指引（命令自带或上游已追加）时不重复追加。
+  // Skip when recovery guidance is already present (command-owned or upstream).
   if (
     options.supportsFreeTierRecovery &&
     isFreeTierOnlyExhausted(error) &&

packages/runtime/src/index.ts

@@ -27,7 +27,7 @@ export type { ParsePathResult } from "./args.ts";
 
 // Process-level setup / error handling
 export { setupProxyFromEnv } from "./proxy.ts";
-export { handleError, normalizeError, errorHint, type ErrorHintOptions } from "./error-handler.ts";
+export { handleError, normalizeError } from "./error-handler.ts";
 export { CLI_VERSION } from "./version.ts";
 
 // Console URLs referenced by commands (e.g. auth/status, banner)

packages/runtime/src/middleware.ts

@@ -1,4 +1,4 @@
-import { consoleRecoveryHint } from "./error-handler.ts";
+import { consoleRecoveryHint, resolveRecoveryConfigName } from "./error-handler.ts";
 import type {
   AnyCommand,
   CommandOutput,
@@ -190,7 +190,10 @@ export const authStage: Middleware = async (ctx, next) => {
   const base = {
     identity: ctx.identity,
     settings,
-    consoleRecoveryHint: consoleRecoveryHint(formatCommand(ctx.identity), sources.configName),
+    consoleRecoveryHint: consoleRecoveryHint(
+      formatCommand(ctx.identity),
+      resolveRecoveryConfigName(sources),
+    ),
     debug: (diagnostic: Parameters<CommandOutput["debug"]>[0]) => ctx.output.debug(diagnostic),
     ...resolveModelBaseUrlState(sources),
   };

packages/runtime/src/output/reporter.ts

@@ -25,7 +25,7 @@ export interface OutputReporterOptions {
   commandPrefix?: string;
   /** When true, free-tier recovery may render usage free / usage freetier commands. */
   supportsFreeTierRecovery?: boolean;
-  /** 当前命名 Profile；未指定或 default 时为 undefined。 */
+  /** Profile pinned in recovery hints (via resolveRecoveryConfigName). */
   configName?: string;
 }
 

packages/runtime/tests/error-handler.test.ts

@@ -1,6 +1,6 @@
 import { BailianError, ExitCode, mapApiError } from "bailian-cli-core";
 import { expect, test, vi } from "vite-plus/test";
-import { errorHint, handleError } from "../src/error-handler.ts";
+import { errorHint, handleError, resolveRecoveryConfigName } from "../src/error-handler.ts";
 import { createOutputReporter } from "../src/output/reporter.ts";
 import { ConfirmationRequiredError } from "../src/confirm.ts";
 
@@ -206,10 +206,29 @@ test("recovery hints append --config when a named profile is active", () => {
   expect(timeoutHint).toContain("bl auth status --config prod");
 });
 
-test("recovery hints omit --config for the default profile", () => {
+test("recovery hints omit --config for the implicit default profile", () => {
   const payload = JSON.parse(
     render(new BailianError("No key", ExitCode.AUTH), "json", { commandPrefix: "bl" }),
   ).error;
   expect(payload.hint).toContain("bl auth status");
   expect(payload.hint).not.toContain("--config");
 });
+
+test("recovery hints keep explicit --config default when active profile is named", () => {
+  // Loader normalizes explicit default to undefined; resolveRecoveryConfigName must restore it.
+  expect(resolveRecoveryConfigName({ flags: { config: "default" }, configName: undefined })).toBe(
+    "default",
+  );
+  expect(resolveRecoveryConfigName({ flags: { config: "prod" }, configName: "prod" })).toBe("prod");
+  expect(resolveRecoveryConfigName({ flags: {}, configName: "prod" })).toBe("prod");
+  expect(resolveRecoveryConfigName({ flags: {}, configName: undefined })).toBeUndefined();
+
+  const hint = JSON.parse(
+    render(new BailianError("No key", ExitCode.AUTH), "json", {
+      commandPrefix: "bl",
+      configName: "default",
+    }),
+  ).error.hint as string;
+  expect(hint).toContain("bl auth login --api-key <your-key> --config default");
+  expect(hint).toContain("bl auth status --config default");
+});