前言¶
DeepSeek Harness (DSH) 採取「一切皆插件」的理念。當版本升級導致第三方插件衝突，GUI 無法啓動時，常規修復手段失效。此時需要一種能在插件體系之外生效的工具，dsh-rescue 正是爲解決這一場景設計。
當 DSH 因插件衝突陷入死鎖，dsh-rescue 臨時摘除 profile 中所有第三方插件層，讓 dsh 以純核心啓動並自行修復；修完一條命令即可原樣還原。
是什麼¶
dsh-rescue 是 DeepSeek Harness (DSH) 的救援模式工具，由 Iliyasfiel 維護，採用 MIT 許可證。
它是一個啓動級工具，而非插件。其核心原理是直接編輯 profile 的 manifest（清單文件），剝離 dsh.profile.bundles 中定義的第三方 bundle。因爲內置核心層（如 @deepseek-ai/dsh-base）不在 dependencies 中，它們會被保留，從而確保 DSH 能以一個純淨的核心啓動。
核心能力¶
該工具提供以下核心功能：
- 臨時剝離：移除 profile stack 中所有第三方 bundle。
- 純核心啓動：允許 DSH 在沒有第三方插件干擾的情況下啓動，用於修復。
- 一鍵還原：修復完成後，通過一條命令恢復原始插件棧。
- 事務化備份：在修改 manifest 前先備份和記錄狀態，修改失敗會自動回滾。
- 協調式退出：
exit命令會智能還原，僅當插件包仍在dependencies時才恢復，已刪除的插件不會被強行復活。 - 零依賴離線：純 Node 實現，無需
pnpm，完全離線可用。 - 生態兼容入口：提供一個惰性的
cordis bundle入口（apply()爲空操作），使其可作爲插件被dsh plugin add安裝，但實際運行機制是 CLI。
安裝¶
全局安裝 CLI（推薦，這是救援路徑）：
npm install -g dsh-rescue
或者，將其註冊爲生態兼容的 bundle（可選）：
dsh plugin --profile web add dsh-rescue
典型用法¶
救援工具的工作目錄默認爲 $DSH_HOME/profiles（DSH_HOME 通常指向 ~/.dsh），默認 web GUI profile 名爲 web。
基本命令¶
dsh-rescue enter <profile> # 進入救援模式：僅保留核心層，隔離第三方插件
dsh-rescue exit <profile> # 退出救援模式：協調並還原原始插件棧
dsh-rescue status <profile> # 查看狀態：救援狀態、核心層與第三方層的拆分情況
dsh-rescue help
典型救援流程¶
當 DSH 無法啓動時，停止當前進程並執行以下步驟：
# 1. 進入救援模式
dsh-rescue enter web
# 2. 此時 profile 僅包含核心層，DSH 應能正常啓動
dsh web
# 3. 在 GUI 或 CLI 中修復插件衝突（例如移除衝突的包）
dsh plugin --profile web remove <conflicting-package>
# 4. 退出救援模式，還原插件棧
dsh-rescue exit web
# 5. 恢復正常啓動
dsh web
行爲細節¶
- 判定規則：工具僅依據
dependencies和dsh.profile.bundles的交集來判定第三方插件，不依賴包名前綴假設，因此對 DSH 核心形態的變化更穩健。 - 不可侵入性：救援工具不能作爲插件安裝在 DSH 內部運行（它會成爲被隔離的對象）。因此，其真正的機制是 CLI，而 bundle 入口是刻意設計爲惰性的（
apply()爲空），僅用於生態兼容。 - 狀態管理：
enter只精簡bundles，保留dependencies。exit會精確還原bundles，僅當插件包仍存在於dependencies中時才恢復。- 救援期間若宿主自動補寫了默認配置，
exit會精確移除這些自動寫入的配置，保持還原的乾淨。
適用場景與注意¶
- 適用場景：版本升級導致 GUI 無法啓動，需要在不啓動插件的情況下修復 profile 配置。
- 注意：
- 救援工具以當前 dsh 進程的權限運行，安裝前應檢查源碼。
- 不能在已經處於救援模式的 profile 中再次
enter，或對非 profile 目錄、無狀態目錄執行操作，系統會報錯並拒絕修改。 - 由於是直接編輯 manifest，操作前建議備份 profile 目錄。
