fix: 探测失败原因改为可操作枚举，不再暴露 Python 异常类名

本地验证时界面显示「探测失败：UpstreamProtocolViolation」——这是实现细节
泄漏：用户从类名既判断不出问题，也不知道该做什么，而且重构时还会漂移。

- 新增 describe_probe_failure()：把异常翻译成稳定的机器可读枚举
  credential_rejected / rate_limited / upstream_unavailable /
  upstream_rejected / upstream_response_invalid / upstream_timeout / unknown_error
- 原始错误摘要移入 detail 字段，仅供排查
- 前端 probeFailureLabel() 翻成中文说明（如「凭证被上游拒绝，需要重新登录该账号」），
  未知枚举值兜底为「未知错误」；detail 单独展示在提示右侧
- TECHNICAL.md §6.5 记录该契约与原因对照表

本地真实进程 + 浏览器验证：
  reason=credential_rejected, detail="upstream http 401"，界面无类名泄漏

后端 562 测试 / 覆盖 100%；前端 74 测试 / tsc 零错误。

Author: RobbsLuo

TECHNICAL.md

@@ -245,6 +245,32 @@ class Scheduler:
 
 ---
 
+## 6.5 面向用户的错误语义
+
+管理端点返回的失败原因必须是**稳定的机器可读枚举**，不能是 Python 异常类名。
+类名是实现细节：用户既判断不出问题，也不知道下一步做什么，而且重构时会漂移。
+
+`POST /api/credentials/{id}/probe` 的失败响应：
+
+```json
+{ "probed": false, "reason": "credential_rejected", "detail": "upstream http 401" }
+```
+
+| `reason` | 含义 | 用户该做什么 |
+|---|---|---|
+| `credential_rejected` | 上游 401/403 拒绝凭证 | 重新登录该账号 |
+| `rate_limited` | 上游 429 | 稍后重试 |
+| `upstream_unavailable` | 上游 5xx | 等待上游恢复，与本账号无关 |
+| `upstream_rejected` | 其他 4xx | 检查账号状态 |
+| `upstream_response_invalid` | 响应结构不符 | 可能是官方接口变更 |
+| `upstream_timeout` | 请求超时 | 重试 |
+| `unknown_error` | 未归类 | 查 `detail` |
+
+`detail` 保留原始错误摘要**仅供排查**，界面不得把它当作主提示展示。
+前端 `probeFailureLabel()` 负责把 `reason` 翻成中文，并对未知值兜底。
+
+未识别的 `reason` 必须回退到 `unknown_error`，不得透传原始字符串。
+
 ## 7. 数据库（T-Q2 定稿）
 
 DDL 以 PROPOSAL §5 为准（users.txt 为用户唯一源、无 users 表、凭证加密列、usage_events.credit 可空），补充实现细节：

src/main.py

@@ -330,7 +330,9 @@ async def probe_credential(credential_id: str,
             quota = await provider.probe_quota(data)
         except Exception as error:  # noqa: BLE001 - 探测失败 → unknown，不当作 0
             credentials.mark_probe_failed(credential_id)
-            return {"probed": False, "reason": type(error).__name__}
+            reason = describe_probe_failure(error)
+            logger.info("额度探测失败 %s: %s", credential_id, reason)
+            return {"probed": False, "reason": reason, "detail": str(error)[:200]}
         credentials.save_quota(credential_id, quota)
         return {"probed": True, "remaining": quota.remaining, "total": quota.total,
                 "cycle_end": quota.cycle_end}
@@ -481,6 +483,36 @@ def resolve_public_callback_url(settings: Settings) -> str:
     return settings.public_base_url.rstrip("/") + "/authorize"
 
 
+def describe_probe_failure(error: Exception) -> str:
+    """把探测异常翻译成用户能据以行动的原因。
+
+    不能直接暴露 Python 类名（如 UpstreamProtocolViolation）——那是实现细节，
+    用户看到它既判断不出问题，也不知道下一步该做什么。
+    """
+    from .provider.codebuddy.client import UpstreamHTTPError as CodeBuddyHTTPError
+    from .provider.codebuddy.events import (
+        UpstreamProtocolViolation as CodeBuddyViolation,
+    )
+    from .provider.trae.client import UpstreamHTTPError as TraeHTTPError
+    from .provider.trae.events import UpstreamProtocolViolation as TraeViolation
+
+    http_errors = (CodeBuddyHTTPError, TraeHTTPError)
+    if isinstance(error, http_errors):
+        status = getattr(error, "status", 0)
+        if status in (401, 403):
+            return "credential_rejected"      # 凭证失效，需要重新登录
+        if status == 429:
+            return "rate_limited"             # 上游限流，稍后再试
+        if status >= 500:
+            return "upstream_unavailable"     # 上游故障，与凭证无关
+        return "upstream_rejected"            # 上游拒绝该请求
+    if isinstance(error, (CodeBuddyViolation, TraeViolation)):
+        return "upstream_response_invalid"    # 响应结构不符，可能是上游改版
+    if isinstance(error, TimeoutError):
+        return "upstream_timeout"
+    return "unknown_error"
+
+
 def _upstream_auth(registry: dict, settings: Settings) -> dict:
     """返回支持 poll 轨道的 provider 的 OAuth 实现（当前仅 CodeBuddy）。"""
     flows: dict = {}

tests/test_deployment_assets.py

@@ -115,3 +115,40 @@ def test_ci_workflow_paths_match_repository():
         assert (ROOT / path).exists(), f"CI 引用 {path} 但它不存在"
     # 覆盖率门槛必须保留
     assert "--cov-fail-under=100" in workflow
+
+
+# ------------------------------------------------- 探测失败原因的分类
+
+def test_describe_probe_failure_maps_http_status_to_actionable_reason():
+    """探测失败原因必须可操作，不能是 Python 类名。"""
+    from src.main import describe_probe_failure
+    from src.provider.codebuddy.client import UpstreamHTTPError as CBHTTP
+    from src.provider.trae.client import UpstreamHTTPError as TraeHTTP
+
+    assert describe_probe_failure(CBHTTP(401, b"")) == "credential_rejected"
+    assert describe_probe_failure(CBHTTP(403, b"")) == "credential_rejected"
+    assert describe_probe_failure(TraeHTTP(429, b"")) == "rate_limited"
+    assert describe_probe_failure(TraeHTTP(503, b"")) == "upstream_unavailable"
+    assert describe_probe_failure(TraeHTTP(400, b"")) == "upstream_rejected"
+
+
+def test_describe_probe_failure_maps_protocol_violation():
+    from src.main import describe_probe_failure
+    from src.provider.codebuddy.events import (
+        UpstreamProtocolViolation as CBViolation,
+    )
+    from src.provider.trae.events import UpstreamProtocolViolation as TraeViolation
+
+    assert describe_probe_failure(CBViolation("x")) == "upstream_response_invalid"
+    assert describe_probe_failure(TraeViolation("x")) == "upstream_response_invalid"
+
+
+def test_describe_probe_failure_handles_timeout_and_unknown():
+    from src.main import describe_probe_failure
+
+    assert describe_probe_failure(TimeoutError()) == "upstream_timeout"
+    assert describe_probe_failure(RuntimeError("boom")) == "unknown_error"
+    # 任何情况下都不得把类名当 reason
+    for error in (RuntimeError("x"), ValueError("y"), KeyError("z")):
+        reason = describe_probe_failure(error)
+        assert type(error).__name__ not in reason

tests/test_m15_operations.py

@@ -1311,7 +1311,11 @@ async def probe_quota(self, _data):
 
     app.state.executor._deps.providers["codebuddy"] = Boom()
     body = client.post(f"/api/credentials/{credential_id}/probe").json()
-    assert body["probed"] is False and body["reason"] == "RuntimeError"
+    assert body["probed"] is False
+    # 不能把 Python 类名当作 reason 暴露给用户
+    assert body["reason"] == "unknown_error"
+    assert "RuntimeError" not in body["reason"]
+    assert body["detail"] == "boom"
     assert app.state.credentials.candidates()[0].health is None
 
 

web/src/api/__tests__/client.test.tsx

@@ -11,6 +11,7 @@ import {
   formatNumber,
   formatTime,
   healthView,
+  probeFailureLabel,
   quotaSemantics,
 } from "../display";
 import { makeCredential } from "../../pages/__tests__/helpers";
@@ -207,6 +208,13 @@ describe("display helpers", () => {
     expect(formatDuration(172800)).toBe("2.0 天");
   });
 
+  it("探测失败原因有中文文案，且未知值有兜底", () => {
+    expect(probeFailureLabel("credential_rejected")).toContain("重新登录");
+    expect(probeFailureLabel("upstream_unavailable")).toContain("与本账号凭证无关");
+    expect(probeFailureLabel(undefined)).toBe("未知错误");
+    expect(probeFailureLabel("something_new" as never)).toBe("未知错误");
+  });
+
   it("时间与数字格式化处理空值", () => {
     expect(formatTime(null)).toBe("—");
     expect(formatTime(1_700_000_000)).not.toBe("—");

web/src/api/client.ts

@@ -3,6 +3,7 @@ import type {
   ApiKeyCreated,
   CredentialsResponse,
   ModelInfo,
+  ProbeResult,
   ProviderStats,
   SessionInfo,
   StatsOverview,
@@ -64,10 +65,7 @@ export const api = {
   deleteCredential: (id: string) =>
     request<{ ok: boolean }>(`/api/credentials/${id}`, { method: "DELETE" }),
   probeCredential: (id: string) =>
-    request<{ probed: boolean; remaining?: number; total?: number; reason?: string }>(
-      `/api/credentials/${id}/probe`,
-      { method: "POST" },
-    ),
+    request<ProbeResult>(`/api/credentials/${id}/probe`, { method: "POST" }),
   checkinCredential: (id: string) =>
     request<{ ok: boolean; credit: number | null; code: number | null; message: string }>(
       `/api/credentials/${id}/checkin`,

web/src/api/display.ts

@@ -5,7 +5,7 @@
  * 展示层必须区分它们，否则探测失败会被误读成「没额度」。
  */
 
-import type { Credential, Health } from "../api/types";
+import type { Credential, Health, ProbeFailureReason } from "../api/types";
 
 export type HealthKind = "known" | "unknown" | "exhausted";
 
@@ -100,3 +100,18 @@ export function formatNumber(value: number | null | undefined): string {
   if (value === null || value === undefined) return "—";
   return value.toLocaleString("zh-CN");
 }
+
+
+export const PROBE_FAILURE_LABEL: Record<ProbeFailureReason, string> = {
+  credential_rejected: "凭证被上游拒绝，需要重新登录该账号",
+  rate_limited: "上游限流，稍后重试",
+  upstream_unavailable: "上游服务异常，与本账号凭证无关",
+  upstream_rejected: "上游拒绝了这次请求",
+  upstream_response_invalid: "上游响应格式与预期不符，可能是官方接口变更",
+  upstream_timeout: "上游响应超时",
+  unknown_error: "未知错误",
+};
+
+export function probeFailureLabel(reason: ProbeFailureReason | undefined): string {
+  return reason ? (PROBE_FAILURE_LABEL[reason] ?? "未知错误") : "未知错误";
+}

web/src/api/types.ts

@@ -93,6 +93,25 @@ export interface UpstreamAuthPoll {
   credential_id?: string;
 }
 
+/** 后端保证是稳定的机器可读枚举，不是 Python 异常类名。 */
+export type ProbeFailureReason =
+  | "credential_rejected"
+  | "rate_limited"
+  | "upstream_unavailable"
+  | "upstream_rejected"
+  | "upstream_response_invalid"
+  | "upstream_timeout"
+  | "unknown_error";
+
+export interface ProbeResult {
+  probed: boolean;
+  remaining?: number;
+  total?: number;
+  reason?: ProbeFailureReason;
+  /** 原始错误摘要，仅用于排查；界面不应直接展示给普通用户 */
+  detail?: string;
+}
+
 export interface ModelInfo {
   id: string;
   object: string;

web/src/pages/CredentialsPage.tsx

@@ -9,6 +9,7 @@ import {
   formatNumber,
   formatTime,
   healthView,
+  probeFailureLabel,
   quotaSemantics,
   STATE_LABEL,
   STATE_TONE,
@@ -40,6 +41,7 @@ export function CredentialsPage() {
   const [accounts, setAccounts] = useState<{ account_id: string; nickname: string; type: string }[]>([]);
   // 每个上游各自可能有进行中的登录（CodeBuddy 轮询 / TRAE 回调）
   const [loginProviders, setLoginProviders] = useState<Provider[]>([]);
+  const [probeDetail, setProbeDetail] = useState<string | null>(null);
 
   const credentials = data?.credentials ?? [];
   const isAdmin = data?.is_admin ?? false;
@@ -82,14 +84,21 @@ export function CredentialsPage() {
         setBusy(true);
         setError(null);
         setNotice(null);
+        setProbeDetail(null);
         try {
           const result = await api.probeCredential(credential.id);
-          // 探测失败表示「未知」，绝不能显示成额度为 0
-          setNotice(
-            result.probed
-              ? `探测成功：剩余 ${formatNumber(result.remaining)} / ${formatNumber(result.total)}`
-              : `探测失败：${result.reason ?? "上游未返回额度"}（健康度保持为「未探测」）`,
-          );
+          // 探测失败表示「未知」，绝不能显示成额度为 0。
+          // 失败原因用可操作的中文说明，不直接把后端枚举或异常类名丢给用户。
+          if (result.probed) {
+            setNotice(
+              `探测成功：剩余 ${formatNumber(result.remaining)} / ${formatNumber(result.total)}`,
+            );
+          } else {
+            setNotice(
+              `探测失败：${probeFailureLabel(result.reason)}（健康度保持为「未探测」）`,
+            );
+            if (result.detail) setProbeDetail(result.detail);
+          }
           await refresh();
         } catch (caught) {
           setError(caught instanceof Error ? caught.message : "探测失败");
@@ -204,7 +213,14 @@ export function CredentialsPage() {
       )}
       {notice && (
         <div data-testid="credentials-notice">
-          <Notice tone="ok">{notice}</Notice>
+          <Notice tone="ok">
+            {notice}
+            {probeDetail && (
+              <span className="ml-2 text-[var(--color-ink-muted)]" data-testid="probe-detail">
+                原始错误：{probeDetail}
+              </span>
+            )}
+          </Notice>
         </div>
       )}
 

web/src/pages/__tests__/CredentialsPage.test.tsx

@@ -159,13 +159,17 @@ describe("CredentialsPage", () => {
     );
   });
 
-  it("探测失败时提示「未探测」而非额度为 0", async () => {
+  it("探测失败时提示「未探测」而非额度为 0，并给出可操作原因", async () => {
     vi.stubGlobal(
       "fetch",
       vi.fn(async (input: RequestInfo | URL) => {
         const url = String(input);
         if (url.includes("/probe")) {
-          return jsonResponse({ probed: false, reason: "CredentialQuotaProbeError" });
+          return jsonResponse({
+            probed: false,
+            reason: "upstream_response_invalid",
+            detail: "quota response missing Accounts",
+          });
         }
         return jsonResponse(listBody([makeCredential({ id: "cred_1" })]));
       }),
@@ -178,6 +182,29 @@ describe("CredentialsPage", () => {
     const notice = await screen.findByTestId("credentials-notice");
     expect(notice).toHaveTextContent("探测失败");
     expect(notice).toHaveTextContent("未探测");
+    // 面向用户的是可操作的中文说明，不是枚举或异常类名
+    expect(notice).toHaveTextContent("上游响应格式与预期不符");
+    expect(notice).not.toHaveTextContent("upstream_response_invalid");
+    // 原始错误另置于折叠区，便于排查
+    expect(screen.getByTestId("probe-detail")).toHaveTextContent(
+      "quota response missing Accounts",
+    );
+  });
+
+  it("探测失败的未知原因有兜底文案", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (input: RequestInfo | URL) => {
+        const url = String(input);
+        if (url.includes("/probe")) return jsonResponse({ probed: false });
+        return jsonResponse(listBody([makeCredential({ id: "cred_1" })]));
+      }),
+    );
+
+    renderPage(<CredentialsPage />, ADMIN);
+    await settle();
+    await userEvent.click(screen.getByRole("button", { name: "探测" }));
+    expect(await screen.findByTestId("credentials-notice")).toHaveTextContent("未知错误");
   });
 
   it("探测成功展示剩余与总量", async () => {