前言¶
在 DeepSeek Harness（DSH）裏跑智能體時，上游一旦返回 401 或 403，客戶端會把錯誤歸類爲 AUTH，界面統一顯示「API 密鑰無效」。token 過期、會話失效、目錄需要重新探測等真實原因都被同一句文案蓋住了，開發者只能猜是哪家 provider 出了問題、手動去續期。
dsh-api-heal 是社區插件，監聽認證類失敗，按 provider 調用各自的續期入口，再讓 agent loop 原地重發請求；多數情況下用戶看不到報錯。下面介紹它的定位、能力與安裝方式。
這是什麼¶
- 名稱：dsh-api-heal（npm 包名同目錄名）
- 維護者：YSwo-fei
- 分類：admin-security（SkillHub 目錄）
- 版本：0.1.0（MIT）
- 倉庫：https://github.com/YSwo-fei/dsh-api-heal
插件不改 DSH 本體，也不改那句「API 密鑰無效」的文案；它在錯誤冒到 UI 之前嘗試修好憑據鏈，並暴露只讀狀態路由與手動工具供模型或運維調用。
核心功能¶
自動自愈¶
監聽 agent/request-error。失敗若像認證問題，就地對對應 provider 重新續期或重取憑據，返回 { kind: "retry" }，讓 agent loop 原地重發同一個請求。
可通過 profile 裏 cordis.patch.yml 關閉自動行爲（autoHeal: false），此時仍可使用手動工具。
手動工具 heal_api¶
模型或腳本可主動調用。可選參數 provider：qoder、workbuddy-ai、our-free-model；不傳則三家依次處理。
狀態路由¶
只讀：GET /plugins/dsh-api-heal/status。路由在 DSH 進程啓動時註冊，重啓前訪問會 404。
三家 provider 的自愈動作¶
| provider | 自愈動作 |
|---|---|
qoder |
GET /plugins/dsh-qoder-connect/status 取 probeKey → POST /plugins/dsh-qoder-connect/probe body {"action":"refresh"}（觸發續期並刷新模型目錄） |
workbuddy-ai |
GET /plugins/dsh-workbuddy-connect/ai/status 取 probeKey → POST .../ai/probe {"action":"refresh"}（重新解密桌面憑據並重拉 catalog；CN 變體若 signed-out 直接跳過） |
our-free-model |
POST /api/our-free-model/refresh，須帶 connection 認證 cookie |
our-free-model 的 /api/our-free-model/* 掛在 connection 准入圍欄後，裸 POST 會 401。插件讀取 .credentials.yaml 裏 client-connection/browser-session 的簽名密鑰，按 dsh-client-connection 同樣算法（HMAC-SHA256 + base64url，payload {version:1, authority, issuedAt, expiresAt}）自鑄會話 cookie，無需瀏覽器或已登錄 Web 會話。
安裝與啓用¶
官方 README 面向 Windows：本機 PowerShell 5.1、執行策略 RemoteSigned 時，不宜直接用未簽名的 install.ps1，應使用 install.cmd：
E:\DSH CODE\dsh-api-heal\install.cmd
腳本會備份 profile 的 package.json，複製插件到數據目錄下的 .dsh/plugins/dsh-api-heal，以 file: 形式寫入 dependencies 並加入 dsh.profile.bundles，執行 pnpm install 並做裝後自檢。路徑以你本機克隆或解壓位置爲準，上例來自 README。
裝完後完全重啓 DSH（托盤也要退出）。驗證：
GET http://127.0.0.1:19387/plugins/dsh-api-heal/status
回滾：
E:\DSH CODE\dsh-api-heal\install.cmd -Uninstall
插件以當前 DSH 進程權限運行，安裝前請閱讀倉庫源碼與 MIT 許可證，確認符合你的安全策略。Node 引擎要求：^22.19.0 || >=24.0.0（見 package.json）。
配置¶
可在 profile 的 cordis.patch.yml 中覆蓋插件配置：
| 鍵 | 默認 | 說明 |
|---|---|---|
enabled |
true |
總開關 |
autoHeal |
true |
關閉後僅保留手動 heal_api |
cooldownMs |
60000 |
兩次自動自愈最短間隔（防抖） |
requestTimeoutMs |
30000 |
單次上游調用超時 |
webBaseUrl |
"" |
留空則依次用 webServer.port/host → $DSH_WEB_URL → http://127.0.0.1:19387 |
registerRoutes |
true |
是否註冊狀態路由 |
示例片段：
- id: api-heal
name: dsh-api-heal
config:
cooldownMs: 15000
autoHeal: true
典型用法與驗證¶
不裝插件，先探三家入口¶
設置 DSH_HOME 與 DSH 自帶的 node.exe，在插件目錄執行：
cd /d "E:\DSH CODE\dsh-api-heal"
set DSH_HOME=E:\dsh-data\.dsh
set NODE=D:\DSH\resources\runtime\primary-runtime\dependencies\node\bin\node.exe
%NODE% probe.mjs
成功時輸出類似：qoder / workbuddy-ai / our-free-model 各一行 [OK] 及耗時說明。
裝插件後的完整測試¶
%NODE% selftest.mjs
%NODE% smoke.mjs
%NODE% loadtest.mjs
loadtest.mjs 需從 app.asar 抽取真實依賴（README 中 stage_deps.mjs 步驟，只需一次）。
運行時若仍遇認證失敗，可讓 agent 調用 heal_api，或指定 provider 只修一家。
適用場景與邊界¶
適合：長期開 DSH 智能體、依賴 qoder / workbuddy-ai / our-free-model 之一或多家，且偶發憑據過期導致界面統一報「API 密鑰無效」的環境。
邊界（README 原文要點）：
- 只能救「流已建立之後才失敗」的請求。 連接階段就拋錯（
started === false）時，agent/request-error監聽器不會跑，需手動heal_api或重發消息。 probeKey每次進程重啓都會變，插件每次通過GET .../status現取，不硬編碼。- 自動自愈默認 60 秒冷卻，同一錯誤短時間內不會瘋狂打上游。
our-free-model的 cookie 用本機.credentials.yaml密鑰簽名，僅在 127.0.0.1 使用，不落盤、不外發。
DSH 生態強調「一切皆插件」；SkillHub 等社區目錄獨立於 DeepSeek / 幻方，本文介紹的是社區維護的 admin-security 類插件，非官方應用商店條目。
結尾¶
dsh-api-heal 把被 UI 吞掉的認證失敗拆回三家 provider 的可執行續期步驟，並在 agent loop 裏自動重試，減少誤讀「API 密鑰無效」帶來的排查成本。目錄與源碼：
