fix: keep free-tier recovery behind confirmation gate

Author: hopelynd

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

@@ -26,8 +26,9 @@ export default defineCommand({
     reason: "billing",
     message: {
       "en-US":
-        "This changes free-tier auto-stop. Disabling it allows pay-as-you-go calls after free quota is exhausted.",
-      "zh-CN": "此操作会变更免费额度自动停止。停用后，免费额度用尽将继续按量计费调用。",
+        "This changes free-tier auto-stop. Enabling it makes calls fail once free quota is exhausted; disabling it allows pay-as-you-go charges after free quota is exhausted.",
+      "zh-CN":
+        "此操作会变更免费额度自动停止。启用后，免费额度用尽时调用将失败；停用后，免费额度用尽将继续按量计费调用。",
     },
   },
   usageArgs: "<--model <model>[,model2,...] | --all> [--off] [flags]",

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

@@ -13,6 +13,7 @@ describe("e2e: usage freetier", () => {
     expect(stderr).toContain("--yes");
     expect(stderr).toMatch(/Risk:\s*high/i);
     expect(stderr).toContain("This changes free-tier auto-stop");
+    expect(stderr).toContain("Enabling it makes calls fail once free quota is exhausted");
     expect(stderr).toContain("bl usage freetier --model qwen3-max --yes");
     expect(stderr).toContain("bl usage freetier --off --model qwen3-max --yes");
   });

packages/runtime/src/error-handler.ts

@@ -63,10 +63,11 @@ function isFreeTierOnlyExhausted(error: BailianError): boolean {
 /** Localized free-tier recovery steps; only call when the product exposes usage commands. */
 function freeTierRecoveryHint(commandPrefix: string, localize: Localize): string {
   const statusCommand = formatCommand(commandPrefix, "usage free --model <model>");
-  const disableCommand = formatCommand(commandPrefix, "usage freetier --off --model <model> --yes");
+  // 不带 --yes：调用方先撞确认门槛（exit 7），再按 skill 规范向用户确认。
+  const disableCommand = formatCommand(commandPrefix, "usage freetier --off --model <model>");
   return localize({
-    "en-US": `Check status: ${statusCommand}\nIf Auto-Stop is ON and you accept pay-as-you-go: ${disableCommand}`,
-    "zh-CN": `查看状态：${statusCommand}\n若 Auto-Stop 为 ON 且接受按量计费：${disableCommand}`,
+    "en-US": `Check status: ${statusCommand}\nTo keep calling after free quota runs out (pay-as-you-go), disable auto-stop — confirmation required: ${disableCommand}`,
+    "zh-CN": `查看状态：${statusCommand}\n若要在免费额度用尽后按量继续调用，请停用自动停止（需确认）：${disableCommand}`,
   });
 }
 
@@ -98,7 +99,12 @@ 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.
-  if (options.supportsFreeTierRecovery && isFreeTierOnlyExhausted(error)) {
+  // 已含恢复指引（命令自带或上游已追加）时不重复追加。
+  if (
+    options.supportsFreeTierRecovery &&
+    isFreeTierOnlyExhausted(error) &&
+    !hint?.includes("usage freetier")
+  ) {
     const recovery = freeTierRecoveryHint(commandPrefix, localize);
     hint = hint ? `${hint}\n${recovery}` : recovery;
   }

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

@@ -88,11 +88,13 @@ test("free-tier hint appends for AllocationQuota.FreeTierOnly when product suppo
   expect(payload.code).toBe(ExitCode.GENERAL);
   expect(payload.message).toBe(FREE_TIER_MESSAGE);
   expect(payload.hint).toContain("bl usage free --model <model>");
-  expect(payload.hint).toContain("bl usage freetier --off --model <model> --yes");
+  expect(payload.hint).toContain("bl usage freetier --off --model <model>");
+  expect(payload.hint).not.toContain("--yes");
   expect(payload.hint).not.toContain("--all");
   const text = render(error, "text", { commandPrefix: "bl", supportsFreeTierRecovery: true });
   expect(text).toContain("Hint:");
   expect(text).toContain("usage freetier --off");
+  expect(text).not.toContain("--yes");
 });
 
 test("free-tier hint uses message fallback when type shadows AllocationQuota.FreeTierOnly code", () => {
@@ -115,7 +117,8 @@ test("OpenAI-compat Free quota exhausted copy matches via use free tier only phr
   const payload = JSON.parse(
     render(error, "json", { commandPrefix: "bl", supportsFreeTierRecovery: true }),
   ).error;
-  expect(payload.hint).toContain("bl usage freetier --off --model <model> --yes");
+  expect(payload.hint).toContain("bl usage freetier --off --model <model>");
+  expect(payload.hint).not.toContain("--yes");
 });
 
 test("insufficient_quota TPS/TPM message does not get free-tier recovery", () => {
@@ -150,4 +153,17 @@ test("free-tier hint appends after an existing hint without replacing it", () =>
   ).error;
   expect(payload.hint?.startsWith(existing)).toBe(true);
   expect(payload.hint).toContain("usage freetier --off");
+  expect(payload.hint).not.toContain("--yes");
+});
+
+test("free-tier hint does not duplicate when existing hint already mentions usage freetier", () => {
+  const existing = "Already guided: bl usage freetier --off --model demo";
+  const error = new BailianError(FREE_TIER_MESSAGE, ExitCode.GENERAL, existing, {
+    api: { apiCode: FREE_TIER_ONLY_API_CODE },
+  });
+  const payload = JSON.parse(
+    render(error, "json", { commandPrefix: "bl", supportsFreeTierRecovery: true }),
+  ).error;
+  expect(payload.hint).toBe(existing);
+  expect(payload.hint?.split("usage freetier").length - 1).toBe(1);
 });

skills/bailian-cli/reference/usage.md

@@ -104,14 +104,14 @@ bl usage free --model qwen3-max --console-region cn-beijing
 
 ### `bl usage freetier`
 
-| Field              | Value                                                                                                    |
-| ------------------ | -------------------------------------------------------------------------------------------------------- |
-| **Name**           | `usage freetier`                                                                                         |
-| **Description**    | Enable or disable auto-stop for free-tier models. Enables by default; use --off to disable               |
-| **Authentication** | Console                                                                                                  |
-| **Usage**          | `bl usage freetier <--model <model>[,model2,...] \| --all> [--off] [flags]`                              |
-| **Risk**           | `high`                                                                                                   |
-| **Risk message**   | This changes free-tier auto-stop. Disabling it allows pay-as-you-go calls after free quota is exhausted. |
+| Field              | Value                                                                                                                                                                 |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Name**           | `usage freetier`                                                                                                                                                      |
+| **Description**    | Enable or disable auto-stop for free-tier models. Enables by default; use --off to disable                                                                            |
+| **Authentication** | Console                                                                                                                                                               |
+| **Usage**          | `bl usage freetier <--model <model>[,model2,...] \| --all> [--off] [flags]`                                                                                           |
+| **Risk**           | `high`                                                                                                                                                                |
+| **Risk message**   | This changes free-tier auto-stop. Enabling it makes calls fail once free quota is exhausted; disabling it allows pay-as-you-go charges after free quota is exhausted. |
 
 > **Agent safety:** Never add `--yes` automatically. On `type="requires_confirmation"`, stop and ask for explicit user confirmation of the same action and scope.
 

skills/bailian-protocol/SKILL.md

@@ -226,7 +226,7 @@ If the task actually ran one or more `bl` commands, **proactively add a one-line
 
 Examples (match the user's language):
 
-> I used `bl usage free` to check the free quota status, and then used `bl usage freetier --off --yes` to disable automatic deactivation.
+> I used `bl usage free` to check the free quota status, and then used `bl usage freetier --off` (after user confirmation) to disable automatic deactivation.
 > I used `bl image generate` to generate 3 posters to ./out/, and then used `bl video generate` to combine the header.
 > I first upgraded bl to the latest version, and then used `bl text chat` to complete the translation.