前言¶

在 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。