前言¶
在本地編碼環境中，通過 bash 啓動長生命週期的進程常會遇到“殭屍進程”問題：智能體忘記了進程的 PID，端口保持佔用，下一次啓動時遇到 EADDRINUSE 錯誤。這往往導致智能體誤判爲代碼邏輯錯誤，而實際上只是端口衝突。
這是什麼¶
dsh-agent-processes 是 DeepSeek Harness Web UI 的一個插件，由 janpauldahlke 維護，旨在爲主機擁有的進程和端口提供完整生命週期管理。它爲智能體提供了第一流的控制能力，包括啓動/停止/列表/日誌/等待就緒，並通過 UI 提供持久化的存儲視圖和交互面板。
核心功能¶
該插件提供以下核心能力：
- 進程控制：支持
process_start、process_stop、process_list、process_logs、process_wait_ready和process_ping。 - 端口回收：啓動帶端口的進程時，會自動回收已被跟蹤的端口占用者；對於未被跟蹤的持有者，插件會拒絕連接，而非直接殺死進程。
- UI 面板：
- Processes Rightbar：跟隨聊天工作區，顯示狀態點、ID/端口、PID/運行時長、命令、工作目錄、日誌預覽，並提供 Kill/Restart/Clear 按鈕。
- Dock Chip：當右欄關閉且工作區有運行進程時，顯示芯片提示（如
Processes · :3000），點擊打開面板。
安裝與啓用¶
安裝此插件需要 DeepSeek Harness 的 Web 配置文件（dsh web）以及 Node.js 環境版本 ≥ 20。
dsh plugin --profile web add dsh-agent-processes
安裝後，重啓 dsh web 或依賴熱更新加載插件，並在瀏覽器端進行硬刷新以加載客戶端代碼。
典型用法¶
在智能體工作流中，使用插件提供的工具代替原始的 Shell 命令和 sleep，可以避免端口衝突和進程丟失。
- 啓動進程：使用
process_start啓動進程。如果該進程監聽端口，必須在參數中包含port。 - 等待就緒：使用
process_wait_ready替代sleep。它會輪詢直到端口可連接（或超時），確保進程已準備好接收流量。 - 檢查狀態：在假設端口空閒之前，使用
process_list檢查當前跟蹤的進程記錄。 - 停止進程：使用
process_stop停止進程。
適用場景與注意¶
- 適用場景：本地開發服務器、文件監控服務、長期運行的 Node.js 服務等需要保持運行的進程。
- 安全限制：插件僅能終止它所跟蹤的 PID；對於未被跟蹤的外部進程佔用端口，插件會拒絕連接（
refused），而不會強制殺死該進程。用戶需手動清理這些外部進程或切換到其他端口。 - 已知限制：插件不包含日誌輪轉功能；日誌爲追加模式；崩潰檢測依賴於存活探針，而非信號監聽；不存在基於會話的隔離，存儲庫是針對 Web 配置文件的。
結語¶
dsh-agent-processes 解決了本地編碼環境中進程生命週期管理的痛點，確保端口可用性和進程可控性。通過提供標準化的工具接口和直觀的 UI，它讓智能體在處理長任務時更加穩定。
