DeepSeek Harness 插件：dsh-agent-control

前言¶

DeepSeek Harness（DSH）採用插件化架構。在開發與調試過程中，刪除會話、刪除一輪對話，以及重啓或關閉實例，是三件典型的“破壞性操作”。這些操作通常分散在不同的模塊中，且缺乏統一的確認與失敗語義管理，容易在操作時產生誤判。

ventisyn/dsh-agent-control 插件將這三類操作整合在一起，提供了一套統一的確認機制和錯誤處理邏輯。它不依賴內核私有結構，僅使用公開 API，旨在爲開發者提供更可控的會話管理與進程控制能力。

核心功能¶

該插件主要包含以下能力：

刪除會話：將一個會話不留殘留地移除。它會遞歸清理該會話派生的所有子代理會話（包括目錄、工作區記賬、投影緩存）。如果子代理中仍有會話駐留在內存中，刪除操作會被拒絕。插件不會觸碰其他插件的數據（如審批類插件的事件記錄）或內容尋址共享的附件。
刪除一輪對話：從模型的可見上下文中移除一輪已結束的對話（問題、回覆及工具記錄）。這一過程類似 DSH 的手動壓縮，通過追加一筆獨立的事務來替換可見內容，讓模型無法再看到原內容。被刪除的輪次在日誌與附件中仍保留，不屬於安全刪除。
熱重啓：允許模型或用戶重啓 DSH 進程。重啓會在當前任務結束後執行，重啓後的會話會自動繼續。這主要用於宿主插件代碼修改後的生效。
關閉實例：乾淨地停掉整個 DSH 實例，與直接關閉窗口等價。這通常由用戶在設置頁觸發。
組件開關：插件列表中包含四行配置（core + session/turn/restart），每一行都可以單獨關閉。關閉後，對應的路由消失，界面入口也隨之消失。
狀態探針：提供 GET /api/agent-control/sessions 等只讀接口，用於查詢會話狀態或確認組件是否註冊成功。

安裝與啓用¶

使用 dsh 命令行工具安裝，指定 profile 名稱：

# 安裝最新版本
dsh plugin --profile <profile 名> add github:ventisyn/dsh-agent-control

# 鎖定到特定版本
dsh plugin --profile <profile 名> add github:ventisyn/dsh-agent-control#<完整版本號>

# 本地開發模式
dsh plugin --profile <profile 名> add link:<本地 clone 路徑>

注意事項：
* 如果 profile 中已安裝其他刪除類插件，請先移除，否則界面會出現重複的刪除按鈕。
* 安裝或修改 host 端代碼後，需要重啓 dsh web 才能加載新路由。

典型用法¶

界面操作¶

刪除會話：在會話列表的“…”菜單中選擇“刪除會話”，或在設置頁操作。
刪除一輪：在每條已結束的回覆旁點擊垃圾桶按鈕。
重啓/關閉：在設置頁的“Agent 控制”區域，點擊“重啓 DSH”或“關閉實例”。操作前需勾選確認框。

API 接口¶

插件提供 HTTP 接口，但沒有 harness 鑑權。建議僅綁定迴環地址或進行 Origin 校驗。

# 查詢會話列表
curl http://127.0.0.1:<端口>/api/agent-control/sessions

# 熱重啓
POST http://127.0.0.1:<端口>/api/agent-control/restart
Content-Type: application/json

{"reason": "修改了宿主插件代碼"}

# 關閉實例
POST http://127.0.0.1:<端口>/api/agent-control/shutdown

組件開關¶

在插件列表中，每一行右側都有一個開關。
* dsh-agent-control（core）：負責交付與初始化。
* dsh-agent-control/session：負責會話管理。
* dsh-agent-control/turn：負責輪次管理。
* dsh-agent-control/restart：負責熱重啓與關閉實例。

關閉某一行後，重啓實例即可生效。關閉“熱重啓”行會同時移除重啓和關閉按鈕。

注意事項¶

刪除一輪不是安全刪除：被刪除的輪次內容仍保留在會話日誌與附件存儲中，僅對模型不可見。
附件清理限制：刪除一輪不會清理附件，因爲內核沒有公開的清理接口。
HTTP 接口鑑權：接口沒有 harness 鑑權，僅依賴 Origin/自定義頭校驗。請勿將 webServer 綁定在 0.0.0.0 上，以免暴露重啓或關閉接口。
啓動器孤兒進程：如果實例是由桌面啓動器（DSHL）拉起的，重啓後進程會變成孤兒。啓動器無法識別新進程，需手動結束舊進程後重新啓動。
重啓與關閉：
- 重啓期間頁面會短暫不可用。
- 關閉實例會中斷所有會話與後臺任務，且不會自動重啓。
- 已壓縮的輪次可能無法單獨刪除。

總結¶

dsh-agent-control 通過將破壞性操作統一管理，簡化了 DSH 插件的開發與調試流程。它提供了靈活的組件開關，並在界面和 API 層面提供了統一的確認機制。開發者在使用時，需特別注意其非安全刪除的特性以及與啓動器的兼容性問題。