前言¶
DSH 的適配器把 403 並進了鑑權那一支，排在額度判定之前。於是”免費額度用完即停”這類失敗在界面上只說密鑰有問題，原始原因看不見。這類失敗不能靠重啓、換密鑰或者看日誌解決，得先知道你這臺機器上裝的產物到底把 403 判成了什麼。
下面介紹 mengge237 維護的插件 dsh-error-doctor（分類：客戶端，0 星，MIT，個人項目，與上游 DSH 無關）。它只回答一個問題：你現在的產物判成了什麼。它不替你改代碼。
這是什麼¶
一句話定位：對已安裝的 DSH 做只讀體檢，判斷 403 的額度類回包會被判成 QUOTA 還是 AUTH，用退出碼給結論。
它修補的是診斷方式，不是 DSH 本身。上游 0.1.7-rc.1 的產物裏 403 仍排在額度判定之前，同一形狀在上游被報過 #3222 / #5715 / #3073 / #1127 / #1631。社區裏已有的做法是”讀源碼看 403 與額度判定誰先出現”，這個插件的作者第一版就是這麼寫的，實測連錯三次（下面一節說明原因）。
核心功能¶
判斷邏輯不是靜態掃源碼，而是把已安裝產物裏的 classifyPiAiError、httpErrorCode（0.1.7 線叫 providerError，會把判定鏈摳進同名殼子）連同 isQuotaExceededError 一起摳出來，喂一條真實的 403 額度報文，看它返回 QUOTA 還是 AUTH。不認註釋、不認行號、不認版本，別人打的補丁照樣認得出。
全程只讀：不寫文件、不髮網絡請求、不碰會話存檔、不讀密鑰。
判不出的形狀一律退出碼 2 並說明原因，不給綠色結論。實證過的形狀：0.1.5-rc.2 的 httpErrorCode、0.1.7-alpha.2 與 0.1.7-rc.1 的 providerError。上游再改形狀它會拒絕判斷，而不是給一個假結論。
安裝與啓用¶
當插件裝，也就是給 agent 一個工具面：
dsh plugin --profile web add dsh-error-doctor # 裝完要完全重啓 dsh web
dsh plugin --profile web remove dsh-error-doctor
工具名 dsh_error_doctor，參數只有可選的 root。
當庫用：
import { findRoot, probeInstall } from "dsh-error-doctor";
import { toolConfig } from "dsh-error-doctor/plugin-config";
plugin-config 不 import 任何宿主包，所以能在沒有 DSH 的機器上測。
依賴方面有兩點來自作者實測的記錄：宿主包 @deepseek-ai/dsh-tools 只能從 profile 樹內解析到，所以 lib/index.js 走動態 import 且失敗即降級——解析不到就留一條 warn、不註冊工具、CLI 照常可用。要工具面就用包安裝，別用 link: 把倉庫原地鏈進插件樹，靜態 import 會把整棵插件樹帶崩（cordis include 那類失敗法）。
典型用法¶
跑 CLI，它自己從 PATH 找 DSH 安裝目錄：
node bin/dsh-error-doctor.mjs
機器可讀輸出加 --json：
node bin/dsh-error-doctor.mjs --json
輸出順序是：先報 DSH 安裝路徑與版本，再逐個站點給出 403 額度報文被判成 QUOTA 還是 AUTH，最後一行給結論。退出碼就是判據：
| 碼 | 意思 |
|---|---|
| 0 | 兩處都已修（額度判定在前） |
| 1 | 兩處都還是出廠形狀——多半是升級把補丁靜默沖掉了 |
| 2 | 讀不出來或兩邊不一致：別硬打補丁，先覈對版本 |
跑測試不需要裝 DSH，夾具由 test/make-tree.mjs 在臨時目錄合成（兩種形狀的假裝機樹），倉庫裏不放上游產物副本：
npm test # 9 例：體檢 4 例 + 插件面 5 例
其中兩例值得留意：一例專門釘”跑完探針之後產物字節不變”，一例釘”讀不出來必須報錯、不給綠色結論”。
判據爲什麼不看源碼¶
這一節是這個插件最值錢的部分，也是它區別於”自己 grep 一下”的地方。作者按”源碼裏 403 與額度判定誰先出現”寫的第一版，實測連錯三次：
- 補丁自己的註釋裏寫着
…then 403，靜態掃字符串把已修的產物讀成沒修； - 有一類正確修法是把額度判定放進 403 分支內部，
if (status === 403) { if (isQuota(...)) return QUOTA; … }—— 文字上 403 在前，語義上已經修好； - 同一個產物文件裏還有另一處
status === 401 || status === 403，那是 Files API 的錯誤構造器，與分類無關；”取文件裏第一個匹配”會直接改錯地方（造對照夾具時真踩了）。
所以現在還有用運行期探針喂真實報文的做法，而不是文本匹配。
適用場景與注意¶
適合已經在用 DSH、遇到過”密鑰無效”提示但不確定是密鑰問題還是額度問題的開發者。也適合給 agent 掛一個體檢工具，讓它自己判斷環境狀態。
注意事項：
- 插件以當前 dsh 進程權限運行，安裝前應檢查源碼與許可證（MIT）。
- DSH 升級會覆蓋安裝目錄，補丁消失是不打日誌、不報錯的。所以”最近還能用”不算證據，跑一次這條命令纔算。
- 不要跳過退出碼 2 的情況直接打補丁，先覈對版本；讀不出來時降噪結論本身就是錯的。
- 這是個人項目，與上游無關，上游 issue 裏報的問題不等於它已經解決。
結尾¶
這個插件的價值不在於提供又一條診斷命令，而在於它選擇的判斷方式：不讀源碼文本，喂真實報文看返回。對”升級會靜默覆蓋安裝目錄”這個前提，它把”最近還能用”這種弱證據換成可復現的退出碼，代價是跑一條命令。目錄：https://www.skillhub.cn/plugins/mengge237/dsh-error-doctor ，源碼：https://github.com/mengge237/dsh-error-doctor 。
