dsh-smart-restart：DeepSeek Harness 的驗證型重啓方案

前言¶

重啓一個正在運行的進程本質上是破壞性的。現有的做法通常要麼需要 root 權限（調用 systemctl restart），要麼僅發送一條“服務已重啓”的通知。這種方式留下了兩個關鍵問題：服務重啓後是否真的健康，以及請求者之前正在進行的工作如何恢復。

dsh-smart-restart 插件旨在填補這兩個空白。它允許在無需特權的情況下重啓 Harness，並在重啓後進行健康檢查，將檢查結果和恢復指令反饋給發起請求的會話。

核心功能¶

1. 無特權重啓
   默認模式下，插件僅終止進程，讓 systemd 根據 Restart=always 配置將其拉起，不需要 sudo 或 polkit 權限。systemctl restart 作爲備選模式供已有權限的環境使用。
2. 啓動後健康檢查
   每次重啓後，插件會檢查服務狀態、註冊工具數量、單元的 ActiveState/MainPID/NRestarts，以及監聽端口是否由單元內的進程擁有（基於 cgroup 檢查）。最終輸出 ok 或 degraded 判決及失敗詳情。
3. 會話報告
   在重啓前記錄意圖（原因、恢復目標）。重啓後，該意圖和健康檢查結果會傳回發起請求的會話，使工作得以基於事實繼續，而非猜測。
4. 循環保護
   如果 10 分鐘內重啓次數超過 3 次，插件會拒絕新的重啓並報錯，防止重啓失敗被無限循環掩蓋。
5. 設置卡片
   在 DSH 插件列表中提供圖形化的設置界面，支持中英文配置。

安裝與啓用¶

通過 DSH 包管理器安裝該插件：

dsh plugin --profile <profile> add @goodandready/dsh-smart-restart

安裝後，插件會自動註冊其工具和啓動檢查機制。

典型用法¶

插件提供了兩個核心工具和兩種重啓模式。

1. 執行重啓 (dsh_restart)¶

調用該工具需要提供參數：

• reason: 重啓原因
• resume: 恢復時執行的指令或上下文
• confirm: 是否確認執行
• delayMs: 延遲毫秒數

示例：

await dsh_restart({
  reason: "manual_check",
  resume: "continue_last_task",
  confirm: true,
  delayMs: 3000
});

2. 查看狀態 (dsh_restart_status)¶

查看最近一次啓動信息、停機時間、健康報告、待處理的意圖以及窗口內的重啓次數。

3. 重啓模式 (restartMode)¶

• kill（默認）：僅終止進程，依賴 systemd 自動拉起。無特權，但會丟失當前未完成的 turn。
• systemctl：直接調用 systemctl restart <unit>。需要相應的權限，但能保留更多進程狀態（儘管文檔指出 kill 模式下 in-flight turn 仍會丟失）。

適用場景與注意¶

• 系統依賴：默認模式要求 Harness 由 systemd 管理（例如 dsh-web.service），且該單元必須配置了 Restart=always。插件會從進程的 cgroup 中自動檢測單元名稱。
• Linux 限制：端口和 cgroup 檢查僅支持 Linux 系統，在其他系統上這些檢查會自動跳過。
• 用戶單元：如果使用 systemd 用戶單元，插件會自動應用 --user 標誌。
• 狀態丟失：在 kill 模式下，當前未完成的 turn 會丟失，這是設計使然。恢復工作依賴於重啓後記錄的 resume 指令。

結語¶

dsh-smart-restart 解決了 DSH 環境中重啓操作“既不安全也不透明”的痛點。通過驗證型重啓和會話回傳機制，它爲智能體系統的運維提供了更可靠的保障。

• 插件目錄頁
• GitHub 倉庫