[Bug] HTTP 403 授权拒绝被归类为 AUTH，UI 显示 "API key is invalid"，原始错误不可见

[MwumLi]

现象

配置了自定义网关 baseURL 后，模型请求返回 403，但 UI 只显示"本轮运行失败 API key is invalid"，看不到真实原因。实际密钥是有效的（GET /models 可正常返回模型列表）。

复现步骤

1. settings.yaml 配置 llm-deepseek 或 llm-pi-ai 的自定义 baseURL（指向某网关），并配置有效 API key
2. 发起一次对话请求
3. 网关返回 HTTP 403，UI 显示"API key is invalid"

网关实际响应

HTTP 403
{"error":{"message":"this User-Agent is not allowed by configured policy","type":"forbidden_client"}}

根因

1. packages/llm/llm-deepseek/src/adapter.ts 的 httpErrorCode()：401 和 403 都被映射为 AUTH
2. packages/llm/llm-pi-ai/src/stream.ts 的 classifyPiAiError()：同样把 401/403 文本归类为 AUTH
3. packages/client/runtime/src/client/sessions/failure-display.ts：对 AUTH 掩码为固定文案 "API key is invalid"（注释说明是为避免 401 消息回显凭据）

影响

• 403（密钥有效、请求被网关策略拒绝）与 401（密钥无效）完全无法区分
• UI 展示误导性文案，用户无法得知真实失败原因；原始 provider 消息只留在 session log，普通用户不可见
• 排查网关策略问题（如 User-Agent 白名单、权限不足）时成本很高

建议修复

• 拆分错误码：401 → AUTH，403 → FORBIDDEN
• FORBIDDEN 在 UI 直接展示 provider 原始消息（403 表示凭据已被接受，仅被策略拒绝，消息不会回显凭据，安全）
• AUTH 保留现有掩码（401 消息可能回显凭据片段）

备注

本地已有该修复的实现草稿（拆分后 FORBIDDEN 自动暴露原始消息），如有需要可整理成 PR。

环境：@deepseek-ai/dsh@0.1.0-rc.7（npx @deepseek-ai/dsh web）

[MwumLi]

补充本地已验证的方案，望觉得合适尽快合入，不然大家看到错误就是统一的 「API key is invalid」，和瞎子一样

修改方案：HTTP 403 授权拒绝被归类为 AUTH 并被掩码

问题本质

403（凭据有效、请求被策略拒绝）与 401（凭据无效）在错误分类上被合并为 AUTH，而 UI 展示层对 AUTH 统一掩码为固定文案 "API key is invalid"，导致真实失败原因（如网关的 User-Agent 策略）不可见。

修改一：packages/llm/llm-deepseek/src/adapter.ts（httpErrorCode()）

修改前：

export function httpErrorCode(status: number, error?: WireError['error']): string {
  if (status === 401 || status === 403) return 'AUTH'

修改后：

export function httpErrorCode(status: number, error?: WireError['error']): string {
  if (status === 401) return 'AUTH'
  if (status === 403) return 'FORBIDDEN'

修改二：packages/llm/llm-pi-ai/src/stream.ts（classifyPiAiError()）

修改前：

function classifyPiAiError(message: string): string {
  if (/\b(?:401|403)\b/.test(message)) return 'AUTH'

修改后：

function classifyPiAiError(message: string): string {
  if (/\b401\b/.test(message)) return 'AUTH'
  if (/\b403\b/.test(message)) return 'FORBIDDEN'

无需修改的部分：展示层

packages/client/runtime/src/client/sessions/failure-display.ts 只对 AUTH 掩码：

if (record.code === 'AUTH') return 'API key is invalid'
return typeof record.message === 'string' ? record.message : JSON.stringify(failure)

FORBIDDEN 不是 AUTH，会走第二行直接展示 provider 原始消息——所以拆分错误码后，UI 自动显示 "this User-Agent is not allowed by configured policy"，无需改 display 代码。

安全性依据：401 消息可能回显被掩码/部分保留的凭据，故保留掩码；403 表示凭据已被接受、仅被策略拒绝，消息不回显凭据，可安全投影到 UI。

测试修改

1. packages/llm/llm-deepseek/tests/adapter.spec.ts：

it.each([
  [401, 'AUTH'],
  [403, 'FORBIDDEN'],   // 原为 [403, 'AUTH']

2. packages/llm/llm-pi-ai/tests/adapter.spec.ts：it.each 中 [401, 'AUTH'] 后新增 [403, 'FORBIDDEN']
3. packages/llm/llm-pi-ai/tests/convert.spec.ts 新增：

expect(mapStopReason(assistant({ stopReason: 'error', errorMessage: 'HTTP 403: forbidden client' })))
  .toMatchObject({ kind: 'error', failure: { code: 'FORBIDDEN' } })

文档修改

• packages/llm/llm-deepseek/README.md + README.zh.md：错误码清单 AUTH (401/403) → AUTH (401), FORBIDDEN (403)

验证

• 定向测试：llm-deepseek 与 llm-pi-ai 两包 vitest 全绿
• typecheck、lint、doc-sync（含双语配对重录）全绿
• 用户可见效果：403 时 UI 从"API key is invalid"变为显示真实原因

[zoahdev]

核验通过（对照 main/master HEAD 99f6f02 rc.7）——根因定位准确，MwumLi 的修复方案方向正确，补两个增量点后即可 cherry-pick。

1. 三处代码主张全部成立。 packages/llm/llm-deepseek/src/adapter.ts:140-141：if (status === 401 || status === 403) return 'AUTH'；packages/llm/llm-pi-ai/src/stream.ts:39-40：if (/\b(?:401|403)\b/.test(message)) return 'AUTH'；packages/client/runtime/src/client/sessions/failure-display.ts:10-16：if (record.code === 'AUTH') return 'API key is invalid'，其他 code 走原始 message——所以拆分后 FORBIDDEN 会自动显示 provider 原文，无需改展示层。

2. 重试语义无回归（可以放心拆）。 packages/llm/llm/src/retry-policy.ts:19-25 默认可重试码 = EMPTY_RESPONSE/RATE_LIMIT/SERVER/TIMEOUT/TRANSPORT，AUTH 本就不在列；拆分出的 FORBIDDEN 同样默认不可重试——不会引入重试风暴。（若某网关把 403 用于限流，部署方可显式把 FORBIDDEN 加进 retryable codes，但默认保持不重试是对的。）

3. 增量点一（pi-ai 的消息正则本质是启发式）。 deepseek adapter 有结构化 status，分类是确定性的；pi-ai 的 classifyPiAiError 基于消息文本匹配，网关错误体若不包含 401/403 字样就走不到这个分支（落入 SERVER/其他）。拆分正则没问题，但建议在 pi-ai 侧优先从结构化错误信息取 status（若有），文本正则仅作兜底——否则"403 显示原文"只对带状态码文本的网关生效。

4. 增量点二（403 语义不唯一，FORBIDDEN 用原文展示恰好覆盖）。 部分网关把配额/权限不足也返回 403；FORBIDDEN 直显 provider 消息比掩码更通用（配额 vs 策略一眼可辨），你的安全性论证成立：403=凭据已被接受、仅被策略拒绝，不回显凭据片段。

结论：方案 + 测试改动 + README 错误码清单（AUTH (401), FORBIDDEN (403)）完整，cherry-pick 就绪。我来做一个基于 main 99f6f02 的验证分支（跑两包测试 + typecheck），然后贴链接。

[zoahdev]

分支已建好并验证，cherry-pick 就绪：

https://github.com/zoahdev/deepseek-harness/tree/fix/error-classify-403-forbidden

• 基于 main/master HEAD 99f6f02；改动 = 你的方案（adapter.ts httpErrorCode 拆分 + stream.ts classifyPiAiError 拆分 + 测试 ×3 + README 错误码清单），未加额外逻辑；
• 验证：vitest run packages/llm/llm-deepseek packages/llm/llm-pi-ai → 15 files / 373 tests 全绿；pre-push 全量 typecheck 通过；
• 已登记 zoahdev upstream patch queue（dsh-docs 来给CIL 端。来个TUI #45）。

补充说明：pi-ai 的分类目前仍依赖 SDK 错误消息文本含状态码（stream.ts:39-40 正则匹配）——本轮分支保持最小改动，结构化 status 路径可作为后续加固（已在 patch queue 备注）。PR 通道开放时可直接 cherry-pick，或由你按自己仓库流程提交，随意使用。

[MwumLi]

@zoahdev 为啥还不在合并到 dsh 主分支

[zoahdev]

这里补充说明一下：这个分支是我基于当时 main 做的社区验证/可 cherry-pick 分支，但我没有 deepseek-ai/deepseek-harness 上游仓库的合并权限，也无法直接把它合入主分支。外部 PR 通道当时也处于不接收状态，所以我能做的是把最小补丁、测试结果和分支准备好，交由维护者按上游流程采纳。此前没有把“验证就绪”和“有权合并”之间的边界说清楚，是我的疏忽。