前言¶
在 DeepSeek Harness（DSH）裏用 llama-swap 做本地模型調度時，模型一旦加載就會長期佔着 VRAM。換模型、調試插件或暫時不用推理，若只能重啓整個 DSH 或手動找進程，既慢又容易誤關調度器。下面介紹社區插件 dsh-gpu-cleanup：在 Web UI 裏點一次，卸載 llama-swap 上已加載的模型並清掃陳舊引擎進程，同時保留 llama-swap 本身，下次對話仍可按需加載。
這是什麼¶
dsh-gpu-cleanup 是 fataldeity-lab 維護的 DSH Web UI 插件（MIT，當前包版本 0.2.1，peer 對齊 DSH 0.2.0-rc.2）。分類屬於模型推理相關能力：面向「本地 llama-swap + llama.cpp 系引擎」場景，解決顯存釋放與進程殘留不同步的問題。
瀏覽器無法直接調用 llama-swap（跨端口且無 CORS），因此插件在 DSH 宿主進程裏起本機控制服務，頁面只訪問 http://127.0.0.1:11436。
核心功能¶
兩個入口均爲一次點擊、無二次確認：
- 設置 → 插件配置 → dsh-gpu-cleanup：大按鈕「一鍵釋放顯存」，附帶控制服務健康狀態與完整日誌；
- 對話頁右上角（Session log 旁）「釋放顯存」小按鈕，結果在右下角浮層（Esc 關閉，成功約 12 秒後自動收起）。
點擊後宿主端大致執行：
- 對 llama-swap 調用
POST /api/models/unload，卸載全部已加載模型（不結束 llama-swap）； - 掃描並結束殘留的
llama-server/ninfer-serve/strata引擎，僅終止啓動超過 90 秒的進程，避免打斷剛啓動、正在生成的引擎； - 複覈清掃結果：
taskkill失敗會如實報「清理失敗，仍駐留」，不謊報成功； - 複查 llama-swap（默認
127.0.0.1:11435）仍在線，並把剩餘引擎信息寫入日誌。
不做的事：不關 llama-swap、不處理 comfyui / ollama、不殺 90 秒內的新引擎、不刪模型文件。
控制服務主要端點（資料原文）：
| 端點 | 作用 |
|---|---|
GET /health |
{ ok, version }，設置卡「控制服務：正常」來源 |
GET /status |
引擎列表、llama-swap 在線情況、已加載模型 |
POST /free-vram |
卸載 + 清掃 + 複查，返回逐步日誌（按鈕調用） |
GET /list-llama |
只讀列出引擎 PID（舊版兼容） |
POST /kill-llama |
僅清掃引擎（舊版兼容，同樣只殺 ≥90 秒） |
自 0.2.1 起的安全邊界：服務能結束進程，故不對外暴露——只綁定 127.0.0.1:11436、校驗 loopback 的 Host、不再對任意站點返回通配 CORS；所有 POST 須帶 X-DSH-Plugin: gpu-cleanup 頭。
安裝與啓用¶
先做安裝，再重啓宿主並強刷頁面（bundle 列表在啓動時讀取，僅刷新頁面不會加載新插件）。
方式一：從 GitHub 安裝（維護版推薦）
dsh plugin --profile web add github:fataldeity-lab/dsh-gpu-cleanup
包內已聲明 dsh.bundle.patch（cordis.patch.yml），dsh plugin add 會作爲 profile bundle 激活，無需再手動往 ~/.dsh/profiles/web/cordis.patch.yml 裏 insert（手動 insert 可能與 bundle 層重複掛載）。
方式二：本地源碼目錄（改代碼時用）
dsh plugin --profile web add I:/DPHs/dsh-gpu-cleanup
（路徑以你本機爲準，README 示例爲 Windows 盤符路徑。）
方式三：手動 clone 到 profile node_modules
mkdir -p ~/.dsh/profiles/node_modules/@princepainter
cd ~/.dsh/profiles/node_modules/@princepainter
git clone https://github.com/fataldeity-lab/dsh-gpu-cleanup.git
啓用檢查：
- 重啓 DSH Web 宿主；
- 瀏覽器強制刷新（
Ctrl+Shift+R）； - 對話頁右上角出現「釋放顯存」；設置卡顯示「控制服務：正常（v3）」表示宿主端控制服務已起來。
依賴要點（README）：DeepSeek Harness 0.2.0-rc.2（^0.2.0-rc.2，不支持 0.1.x）；llama-swap 在 127.0.0.1:11435（可選——未運行時按鈕仍可見，點擊會清掃孤兒引擎並提示）。宿主端僅使用 Node 內置模塊，無額外 npm 運行時依賴。
典型用法¶
- 打開 DSH Web UI（示例地址
http://127.0.0.1:3080）； - 點右上角 「釋放顯存」，或設置卡 「一鍵釋放顯存」；
- 按鈕顯示「釋放中…」及實時耗時，右下角浮層滾動逐步日誌；
- 出現「確認：當前沒有已加載模型，顯存已釋放」即完成——llama-swap 仍在運行，後續使用模型會按需加載。
請求超時約 210s（避免 llama-swap 卡住時按鈕永遠處於「釋放中」）；同一 /free-vram 在宿主端單飛，多標籤同時點擊不會重複跑兩遍。
適用場景與注意¶
適合：長期在 DSH Web 裏用 llama-swap 調度本地模型、需要頻繁騰 VRAM 又希望保留調度器的開發者。
注意：
- 插件邏輯在 當前 DSH 進程權限下執行（含
taskkill）；安裝前請自行查看 GitHub 源碼 與 MIT 許可證，確認符合你的安全策略。 - README 中進程枚舉與
taskkill路徑面向 Windows（PowerShell） 環境；若在 Linux 上部署，需以實際倉庫行爲爲準，勿假設與 Windows 完全一致。 - 社區插件目錄 skillhub.cn 爲獨立生態站點，與 DeepSeek / 幻方無官方從屬關係；DSH 本身倡導「一切皆插件」，本插件爲社區維護 fork。
結尾¶
dsh-gpu-cleanup 把「卸載 llama-swap 模型 + 清掃陳舊引擎 + 保留調度器」收成 Web UI 裏的一鍵操作，並通過 loopback 控制服務與請求頭約束降低誤用風險。需要安裝說明與變更記錄時，可看目錄頁 fataldeity-lab/dsh-gpu-cleanup 與倉庫 github.com/fataldeity-lab/dsh-gpu-cleanup。
