前言¶

在 Windows 上跑 SnowLuma 這類 QQ 機器人時，常見做法是單獨開終端執行 launcher.bat，再用肉眼盯控制台裏的 WebUI、OneBot 是否已監聽。DeepSeek Harness（DSH）本身支持插件化擴展；若你已經在 desktop profile 裏日常工作，把機器人進程管理收進設置頁，比來回切終端更省事。下面介紹客戶端插件 dsh-snowluma-control（維護者 Britneycode）：在宿主設置頁一鍵啓動、停止、重啓 SnowLuma 的 Node 進程，並用日誌驅動方式展示 WebUI 與 OneBot 就緒狀態。

這是什麼¶

dsh-snowluma-control 是 DSH 的 客戶端（web）插件，分類上屬於進程管理與面板集成。它不負責 QQ 登錄（仍由 SnowLuma 自身處理），只負責：發現安裝目錄、拉起/停下 launcher 子進程、解析標準輸出判斷服務是否就緒、在宿主 Browser 標籤打開真實 WebUI 端口。

平臺限定爲 Windows：停止流程使用 taskkill，進程查詢走 powershell.exe，Node 路徑探測走 where.exe。實現上僅依賴 Node 標準庫（node:*）與宿主機提供的 React，README 中稱爲零額外 npm 運行時依賴。當前倉庫版本爲 0.1.0（MIT 許可），要求 Node >= 22.5.0。

設置頁面板怎麼用¶

安裝並重啓宿主後，打開 設置 →「SnowLuma 控制台」。面板大致四塊：

典型操作順序可以是：先確認或自動識別安裝目錄 → 點啓動 → 看日誌與副行直到 WebUI、OneBot 顯示就緒 → 需要時在面板內打開 WebUI。日常改配置仍走 SnowLuma 自身；本插件只做進程與就緒展示。

核心能力（設計層面）¶

就緒判定來自日誌，不設固定端口¶

插件不假設 WebUI 一定停在 5099：SnowLuma 在端口被佔用時會靜默順延（5099 → 5100 …）。因此就緒與訪問地址一律從 stdout 解析，例如 [App] SnowLuma starting、[WebUI] listening …、各類 [OneBot.*] … listening、[App] Node integrity: pid=…、Shutting down (launcher disconnected) 等標記。進程 spawn 成功並不等同於服務可用。

三段式停止¶

① 先結束 launcher，讓子進程通過 IPC disconnect 嘗試優雅退出；② 最多等待 15 秒；③ 仍存活才 taskkill /T /F 強殺整棵進程樹。README 說明：SnowLuma 的 launcher 僅在子進程退出碼爲 75 時重拉，其他退出碼會自行退出，因此不宜一上來就整樹強殺。

孤兒進程對賬¶

若宿主曾被強殺，可能留下 SnowLuma 殘留進程。下次打開面板會標爲「殘留進程」，並允許一鍵強制停止。判定同時檢查 pid 存活、啓動時間與命令行匹配，避免僅憑 pid 誤判無關進程。

狀態與退出碼¶

停止後 WebUI / OneBot 就緒位會立即歸零，避免按鈕仍指向已死端口。用戶主動停止後，遲到的 exit 事件不會把界面改成「異常退出」。

安裝與啓用¶

從 npm 安裝（若包已發佈）：

dsh plugin --profile desktop add dsh-snowluma-control

使用本地源碼目錄：

dsh plugin --profile desktop add ./dsh-snowluma-control

手工等價方式：在 profile 的 package.json 裏把 dsh-snowluma-control 加入 dsh.profile.bundles，並在 dependencies 中寫 "dsh-snowluma-control": "link:/path/to/dsh-snowluma-control"，再執行 pnpm install。

插件向 webServer 注入路由，前綴爲 /api/plugins/snowluma-control，包含 GET /state、GET /logs、GET /detect，以及寫操作 POST /start、/stop、/restart、/config（寫操作校驗同源）。安裝後需重啓 DSH 宿主；若用 link: 掛載插件目錄，改代碼後同樣要重啓宿主，運行中的實例仍是啓動時加載的那份。

開發與自測¶

在插件源碼目錄執行：

node --test

README 記錄：69 個斷言約 2.5 秒通過。注意不要在 Windows 下寫 node --test test/（目錄參數會被當作入口模塊）。若在類 Unix 環境下跑測試，宿主會話 PATH 可能缺 C:\Windows\System32，可先補 PATH 再測，否則 lib/procs.js 調用裸名 powershell.exe 可能 ENOENT，導致進程時間戳爲 null、對賬相關邏輯誤判：

export PATH="/c/Windows/System32:/c/Windows/System32/WindowsPowerShell/v1.0:$PATH"

適用場景與注意¶

適合誰：已在 Windows 上使用 DSH desktop profile，並希望把 SnowLuma QQ 機器人啓停和就緒狀態集中在設置頁裏的開發者。

權限與安全：插件以當前 DSH 進程的身份啓動、查詢和結束本機進程；安裝前請閱讀 GitHub 倉庫 源碼與 MIT 許可證，確認與你的工作區策略一致。DSH 社區插件目錄（如 SkillHub 條目）爲社區站點，與 DeepSeek / 幻方無官方從屬關係，不宜理解爲官方應用商店。

環境：僅 Windows；需本機已安裝可被 where.exe 找到的 Node，且 SnowLuma 按常規方式安裝在可識別目錄中。

結尾¶

若你厭煩反覆開終端跑 launcher.bat，又需要對照日誌確認 WebUI 與 OneBot 是否真在監聽，dsh-snowluma-control 把這一過程收進 DSH 設置頁，並處理了優雅停止與殘留進程對賬等 Windows 下的細節。更多信息見目錄頁 SkillHub：dsh-snowluma-control 與源碼 github.com/Britneycode/dsh-snowluma-control。