前言¶
在 DeepSeek Harness（DSH）里接第三方 LLM 网关时，失败原因往往藏在提供方返回的原文里：渠道不可用、余额耗尽、令牌无权访问某模型，和真正的密钥错误，在网关侧可能是不同的 HTTP 状态与文案。若 UI 一律展示同一句「API 密钥无效」，排查会走偏——例如网关明明在说「当前分组下没有可用渠道」，界面却提示换密钥。
下面介绍社区插件 dsh-llm-error-classify（维护者 lxl8182，SkillHub 分类 admin-security）。它在 llm/stream 链路上改写终态失败分类，使非纯认证类 401/403 的提供方原文能进入界面，同时按形状清洗可能回显的凭证片段。
这是什么¶
dsh-llm-error-classify 是 DSH Web 侧的错误分类修正插件：把 pi-ai 适配器因文本规则过早判成 AUTH 的提供方失败，改写为 PROVIDER_ERROR，并保留（经清洗后的）原始报错文本。
宿主里 AUTH 是 UI 唯一会清空正文、并替换为固定「API 密钥无效」文案的 code；PROVIDER_ERROR 不在该特判集合内，界面会直接显示 message 内容。插件不修改重试策略，也不改动非 AUTH 的分类。
问题从哪来¶
pi-ai 适配器在 classifyPiAiError 中有一条优先规则：消息文本里出现 401 或 403 即返回 AUTH，且排在更具体的配额、渠道等判断之前。因此多种网关失败在到达 UI 前都被标成同一 code。
UI 侧对 AUTH 的处理包括：在 event projection 中清空展示用正文，在聊天与轨迹组件中用 failure.auth 文案覆盖。结果是网关原文在界面上不可见。
核心功能¶
插件通过 cordis.patch.yml 挂到 llm/stream waterfall，包裹适配器 chunk 迭代器，在 agent loop 落盘前拦截终态 finish chunk。
规则只有一条：终态失败若 code === 'AUTH'，改为 PROVIDER_ERROR，并保留原始文本（经凭证清洗）。
PROVIDER_ERROR 刻意避开 UI 特判集合与默认可重试集合（后者仅含 EMPTY_RESPONSE、RATE_LIMIT、SERVER、TIMEOUT、TRANSPORT），因此展示与原先 AUTH 的重试行为保持一致，不会因改写而多触发重试。
放行原文前，插件按形状替换可能泄漏凭证的子串为 [redacted]，例如常见厂商前缀密钥（sk-…、sk-proj-…、ghp_… 等）以及消息中的 Bearer <token>。这是形状匹配，不是读取真实密钥；无厂商前缀特征的裸密钥无法识别，README 中已说明为已知限制。
安装与启用¶
插件为零依赖纯 JavaScript，无 prepare 脚本，安装后无需单独 npm install。package.json 要求 Node >=22。
从 GitHub 安装：
dsh plugin --profile web add github:lxl8182/dsh-llm-error-classify
或从本地目录安装：
dsh plugin --profile web add /path/to/dsh-llm-error-classify
安装完成后重启 dsh web。
卸载：
dsh plugin --profile web remove dsh-llm-error-classify
若通过 github: 安装，升级可用：
dsh plugin --profile web update dsh-llm-error-classify
升级后同样需要重启 dsh web。
验证方式¶
仓库提供逻辑层与端到端探针（需在含完整仓库文件的副本中运行；dsh plugin add 装进 profile 的副本仅含 index.js、cordis.patch.yml、README.md）。
逻辑层：
node test.mjs
覆盖正向（多种 403/401 网关场景均 AUTH → PROVIDER_ERROR）、反向（其它 code 不变）、文本保留、凭证清洗与非 finish chunk 行为等。
经真实 waterfall 的端到端：
DSH_REPO=/path/to/dsh-checkout node probe-e2e.mjs
DSH_REPO 指向 DSH 源码检出目录，默认可为当前目录。
适用场景与注意¶
适合谁： 使用 DSH Web、经 pi-ai 接第三方网关，且经常遇到 401/403 被统一显示为「API 密钥无效」、需要看到提供方原文以便区分渠道、配额、权限与密钥问题的开发者或运维。
安全与信任： 插件以当前 dsh 进程权限运行，会改变失败信息进入 UI 状态的方式（在清洗后展示原文）。安装前应阅读 GitHub 仓库 源码与 MIT 许可证，确认符合你的安全策略。若网关会在报错中回显无常见前缀形态的裸密钥，不要依赖本插件的清洗能力。
生态说明： DSH 社区插件目录在 SkillHub 等独立站点维护，与 DeepSeek / 幻方无官方从属关系；安装命令以 README 为准。
版本与限制： 当前资料中 package 版本为 0.2.0。插件仅做 AUTH → PROVIDER_ERROR 与凭证形状清洗；宿主若调整 UI 特判或重试集合，可能需要同步调整插件所选 code。根因在宿主分类与 UI 策略，README 给出了上游三处修改建议，上游修好后可卸载本插件。
结尾¶
dsh-llm-error-classify 用最小改动把误标为 AUTH 的提供方失败改写成 PROVIDER_ERROR，让网关原文在界面上可见，减少「密钥无效」误导带来的无效换钥。目录与详情见 SkillHub 插件页，源码与安装说明见 GitHub：lxl8182/dsh-llm-error-classify。
