dsh-ballute（Ballute 氣囊）：DeepSeek Harness 插件崩壞防護

DeepSeek Harness (DSH) 的插件系統在遇到故障時傾向於靜默失敗：條目崩壞後默默退位，面板留空，錯誤僅停留在控制台，難以排查。dsh-ballute 是一款崩壞防護插件，旨在將這種不可見的故障轉化爲可見、可歸因、可恢復的狀態。

安裝與啓用¶

通過官方 CLI 安裝插件：

dsh plugin add github:Zlyraz/dsh-ballute

安裝完成後，Ballute 會自動注入 L1-L4 防護能力，並在運行時提供崩潰觀測與恢復接口。

核心能力¶

插件通過五個層級（L1-L5）構建防護網，覆蓋從裝載前檢查到運行時恢復的全流程。

L1 預檢：靜態契約體檢¶

在插件裝載前，通過 GET /api/ballute/v1/inspect 接口進行靜態檢查。它能發現結構層面的故障，例如 bundle 註冊 ID 與包名不匹配、缺少必要導出或 name 字段缺失等。

L2 隔離：運行時崩卡展示¶

訂閱官方 ctx.slots.onEntryError 鉤子，在右下角展示崩卡。崩卡包含插件名、槽位 key、錯誤信息，將原本在控制台靜默發生的崩潰暴露在 UI 層面。

L3 觀測：黑匣子與歷史¶

記錄崩潰遙測日誌爲 JSONL 格式，存儲在 $DSH_HOME/ballute/crash-log.jsonl。日誌包含時間戳、堆棧、啓動版本哈希（rev）等信息，支持重啓後回溯。同時提供歷史列表接口供查詢。

L4 恢復：一鍵禁用¶

在崩卡 UI 中提供“關閉插件”操作，通過寫入補丁層（disabled: true）實現 HMR 卸載，無需重啓 DSH 實例即可讓壞插件失效。

L5 兜底：安全模式¶

當主 profile 壞死時，啓動一個包含最小 bundle 和 Ballute 自身的 safe profile，通過跨 profile API 體檢並禁用壞插件，實現外部救場。

安全模式搭建¶

官方 CLI 尚未提供 --safe-boot 旗標，需手動構建最小 profile。

在 $DSH_HOME/profiles/safe/ 目錄下放置以下文件：

package.json

{
  "name": "dsh-profile-safe",
  "private": true,
  "dependencies": {
    "dsh-ballute": "github:Zlyraz/dsh-ballute"
  },
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        "dsh-ballute"
      ]
    }
  }
}

cordis.yml（空樹即可）

[]

cordis.patch.yml（保持空數組）

[]

pnpm-workspace.yaml

packages:
  - .
nodeLinker: hoisted
autoInstallPeers: false

執行 pnpm install 後，使用以下命令啓動安全模式：

dsh --profile safe

啓動後，Ballute 會檢測到 safe profile，並在 UI 頂部顯示恢復區，允許對目標 profile 進行體檢或禁用操作。

自測與使用¶

夾具測試¶

使用插件自帶的夾具驗證體檢功能：

curl 'http://127.0.0.1:3080/api/ballute/v1/inspect?fixture=fault-mismatch'
curl 'http://127.0.0.1:3080/api/ballute/v1/inspect?fixture=fault-load'

常見夾具包括 fault-load（缺失文件）、fault-apply（apply 拋錯）、fault-mismatch（ID 不匹配）等。

開發模式安裝¶

建議先在隔離的 dev profile 中驗證，再安裝到日常 profile。

dsh plugin --profile dev add /path/to/dsh-ballute
dsh web --profile dev --port 3081

開發期推薦使用 link 方式修改代碼即生效。

注意事項¶

誠實邊界¶

插件主要覆蓋 L2 域（運行時條目崩潰）。
* Loader 級故障：如 client apply 拋錯導致啓動失敗、bundle 文件缺失導致 host 進程崩潰，此時 UI 尚未渲染，Ballute 無法捕獲，需依賴安全模式從外部恢復。
* SlotAssemblyError：該錯誤會穿透錯誤邊界導致整頁空白。此時 Ballute UI 不可見，無法捕獲，只能查看控制台日誌，刷新可恢復。

維護狀態¶

該插件爲業餘維護，響應可能較慢。歡迎提交 Issue 或 PR。

許可證¶

MIT。

插件目錄 | GitHub 倉庫