refactor(auth): enhance error handling in API key validation to prioritize meaningful error propagation

Author: hopelynd

docs/agents/auth-change.md

@@ -33,7 +33,7 @@ defineCommand({ auth }) → runtime/authStage → ctx.client → command.run(ctx
 
 `~/.bailian/config.json` 可同时保存 `api_key`、`access_token` 与 `access_key_*`。登录任一种方式不得删除另一种:
 
-- `bl auth login --api-key ...` 先通过只读 `GET /models` 校验 Key，校验成功后才原子写入 `api_key` 与实际匹配的 `base_url`。公共 DashScope 站点使用 `/api/v1/models?page_no=1&page_size=1`，`*.maas.aliyuncs.com`（Workspace 与 Token Plan）使用 `/compatible-mode/v1/models`。显式 `--base-url` 只校验该站点，不自动改写；未显式指定时，普通 `sk-*` / `sk-ws-*` 按“当前 Profile 已保存的同类站点 → 基于 `workspace_id` 构造的各地域 Workspace 专属站点 → 公共地域”顺序选择首个成功结果，`sk-sp-*` 并行探测国内站与新加坡 Token Plan，其他格式同时尝试两类候选。所有候选失败时按候选优先级透传首个原始错误；HTTP status、API code、request ID 与服务端 message 保持不变，不重新分类为 `AUTH`。任一失败都不落盘、不激活 Profile
+- `bl auth login --api-key ...` 先通过只读 `GET /models` 校验 Key，校验成功后才原子写入 `api_key` 与实际匹配的 `base_url`。公共 DashScope 站点使用 `/api/v1/models?page_no=1&page_size=1`，`*.maas.aliyuncs.com`（Workspace 与 Token Plan）使用 `/compatible-mode/v1/models`。显式 `--base-url` 只校验该站点，不自动改写；未显式指定时，普通 `sk-*` / `sk-ws-*` 按“当前 Profile 已保存的同类站点 → 基于 `workspace_id` 构造的各地域 Workspace 专属站点 → 公共地域”顺序选择首个成功结果，`sk-sp-*` 并行探测国内站与新加坡 Token Plan，其他格式同时尝试两类候选。所有候选失败时选择最有诊断价值的原始错误透传：无 HTTP status 的网络、超时或响应解析错误优先，其次为 HTTP 429/5xx，最后为其他 HTTP 错误；同级保持候选顺序。HTTP status、API code、request ID 与服务端 message 保持不变，不重新分类为 `AUTH`。任一失败都不落盘、不激活 Profile
 - 未显式传 `--config` 时，`sk-sp-*` 自动写入并激活 `token-plan`；普通 `sk-*` / `sk-ws-*` 仅在当前为 `token-plan` 时改写并激活 `default`，否则保留当前 Profile；其他格式不自动切换。显式 `--config` 始终优先。`sk-sp-*` 无论写入哪个 Profile 都会携带 Token Plan 的预设默认模型，并在保留已有项的基础上补齐 `api_key_capabilities`，不自动删除任何已有能力。登录仍不得删除其他鉴权域的凭证
 - `bl auth login --console` 更新 `access_token` 以及回调携带的 console 作用域字段；若所选 Profile 没有模型 API Key，会要求控制台页面创建并回传一个普通 API Key 与 Base URL 一并保存。该回调结果不重复执行 `/models` 校验，且不会创建或配置 Token Plan
 - `bl auth login --open-api ...` 调用 OpenAPI 生成 CLI `access_token`，通过目标 Console 网关的只读 `loginInfo` 校验后，才一并写入 `access_key_id` / `access_key_secret` / `access_token` 和实际 `console_region` / `console_site`；失败不覆盖原凭证、不激活 Profile。一次成功登录同时产生 `openapi` 与 `console` 域凭证

packages/commands/src/commands/auth/login-api-key.ts

@@ -1,4 +1,5 @@
 import {
+  BailianError,
   getApiKeyLoginKind,
   normalizeModelBaseUrl,
   requestJson,
@@ -162,6 +163,27 @@ export function apiKeyValidationCandidates(
   return candidates;
 }
 
+function validationFailurePriority(error: unknown): number {
+  if (!(error instanceof BailianError) || error.api?.httpStatus === undefined) return 0;
+  const status = error.api.httpStatus;
+  if (status === 429 || status >= 500) return 1;
+  return 2;
+}
+
+function selectValidationFailure(results: readonly { error?: unknown }[]): unknown {
+  let selectedError: unknown;
+  let selectedPriority = Number.POSITIVE_INFINITY;
+  for (const result of results) {
+    if (result.error === undefined) continue;
+    const priority = validationFailurePriority(result.error);
+    if (priority < selectedPriority) {
+      selectedError = result.error;
+      selectedPriority = priority;
+    }
+  }
+  return selectedError;
+}
+
 /** Validate a key without consuming model quota and return the first matching endpoint. */
 export async function validateApiKey(
   deps: ApiKeyValidationDeps,
@@ -187,8 +209,8 @@ export async function validateApiKey(
   const success = results.find((result) => result.error === undefined);
   if (success) return { baseUrl: success.candidate.baseUrl, kind: success.candidate.kind };
 
-  const failure = results.find((result) => result.error !== undefined);
-  if (failure?.error !== undefined) throw failure.error;
+  const failure = selectValidationFailure(results);
+  if (failure !== undefined) throw failure;
 
   throw new TypeError("API key validation completed without a success or failure result.");
 }

packages/commands/tests/auth-api-key.test.ts

@@ -257,11 +257,15 @@ test("显式 Base URL 返回 404 时保留状态和 request ID", async () => {
 test.each([
   { name: "5xx", status: 503, message: "temporary outage" },
   { name: "429", status: 429, message: "too many requests" },
-])("存在 $name 时校验结论不确定，不误报 Key 无效", async ({ status, message }) => {
+])("后续候选出现 $name 时优先透传该错误", async ({ status, message }) => {
   const originalFetch = httpTransport.fetch;
   httpTransport.fetch = async (input) => {
-    if (requestUrl(input).startsWith("https://dashscope.aliyuncs.com/")) {
-      return jsonResponse({ code: "TemporaryFailure", message }, status);
+    const url = requestUrl(input);
+    if (url.startsWith("https://dashscope-intl.aliyuncs.com/")) {
+      return jsonResponse(
+        { code: "TemporaryFailure", message, request_id: `req-${status}` },
+        status,
+      );
     }
     return jsonResponse({ code: "InvalidApiKey", message: "invalid key" }, 401);
   };
@@ -270,6 +274,62 @@ test.each([
     const error = await captureValidationError("sk-placeholder");
     expect(error.exitCode).toBe(ExitCode.GENERAL);
     expect(error.message).toBe(message);
+    expect(error.api).toEqual({
+      httpStatus: status,
+      apiCode: "TemporaryFailure",
+      requestId: `req-${status}`,
+    });
+  } finally {
+    httpTransport.fetch = originalFetch;
+  }
+});
+
+test("后续候选出现网络错误时优先透传该错误", async () => {
+  const originalFetch = httpTransport.fetch;
+  const networkError = new TypeError("fetch failed", {
+    cause: Object.assign(new Error("connection reset"), { code: "ECONNRESET" }),
+  });
+  httpTransport.fetch = async (input) => {
+    if (requestUrl(input).startsWith("https://dashscope-intl.aliyuncs.com/")) {
+      throw networkError;
+    }
+    return jsonResponse({ code: "InvalidApiKey", message: "invalid key" }, 401);
+  };
+
+  try {
+    const error = await validateApiKey({ identity, settings }, "sk-placeholder", {}).catch(
+      (caught) => caught,
+    );
+    expect(error).toBe(networkError);
+  } finally {
+    httpTransport.fetch = originalFetch;
+  }
+});
+
+test("同一优先级的 HTTP 错误保持候选顺序", async () => {
+  const originalFetch = httpTransport.fetch;
+  httpTransport.fetch = async (input) => {
+    const url = requestUrl(input);
+    if (url.startsWith("https://dashscope.aliyuncs.com/")) {
+      return jsonResponse(
+        { code: "FirstRejected", message: "first candidate rejected", request_id: "req-first" },
+        401,
+      );
+    }
+    return jsonResponse(
+      { code: "LaterRejected", message: "later candidate rejected", request_id: "req-later" },
+      404,
+    );
+  };
+
+  try {
+    const error = await captureValidationError("sk-placeholder");
+    expect(error.message).toBe("first candidate rejected");
+    expect(error.api).toEqual({
+      httpStatus: 401,
+      apiCode: "FirstRejected",
+      requestId: "req-first",
+    });
   } finally {
     httpTransport.fetch = originalFetch;
   }