前言¶
在使用 DeepSeek Harness（DSH）開發智能體時，智能體經常會啓動後臺服務（如數據庫、API 服務）。這些進程通常通過 shell 命令或 Start-Process 啓動，開發者難以在 Web GUI 中直觀地看到“哪個對話啓動了哪些服務”，也無法快速查看日誌或進行啓停操作。
dsh-process-board 插件解決了這個問題。它是一個 DSH 服務面板插件，可以在 Web GUI 側邊欄查看服務歸屬、進行啓停管理、實時查看日誌，並支持啓動參數的重放。
核心能力¶
該插件提供以下功能：
- 會話歸屬：通過 DSH 宿主注入的
DSH_SESSION_ID環境變量，結合進程樹血緣，將每個服務歸屬到啓動它的對話。面板會按會話的中文標題分組顯示。 - 服務視圖：內置三道過濾邏輯（端口/日誌標記閘門、剔除 npm/cross-env 啓動器殼、合併 nginx master-worker），只展示真正的服務進程，避免刷屏。
- 三態探測：提供三種狀態展示。
running：端口處於監聽狀態。pid-alive：進程存在但端口未監聽（如 Java 冷啓動階段）。stopped：進程已結束。- 支持通過 HTTP 探測檢查服務的響應碼。
- 啓停管理：停止服務時採用禮貌終止（SIGTERM/taskkill），給予寬限期後對進程樹進行強殺。當服務狀態爲
stopped時，行內會出現「啓動」按鈕，可重放登記的啓動參數。 - 日誌查看：啓動時注入
DSH_PB_LOG環境標記。面板採用分欄設計，實時tail日誌流。支持 ERROR 紅色高亮和 WARN 黃色高亮，每 4 秒自動刷新，且支持滾動吸底。 - 全屏模式：面板 ⛶ 鋪滿視口；日誌 ⛶ 覆蓋整個面板。支持按 Esc 逐級退出（日誌全屏 → 面板全屏 → 關閉）。
安裝與啓用¶
前置條件是已安裝 DSH（dsh 命令可用）。
使用以下命令安裝插件：
dsh plugin --profile web add dsh-process-board
安裝完成後，必須重啓 DSH 宿主（重新執行 dsh web），並在瀏覽器刷新頁面。此時側邊欄會出現「進程面板」入口。
典型用法¶
要讓面板正確顯示服務和日誌，需要正確啓動服務。
1. 帶日誌標記啓動（Shell/Bash）
啓動服務時，通過環境變量 DSH_PB_LOG 指定日誌文件，並將標準輸出重定向到該文件。
export DSH_PB_LOG=/tmp/my-service.log
java -jar app.jar >> /tmp/my-service.log 2>&1 &
2. 顯式登記並啓動（API）
如果需要更精細的控制，可以通過 API 顯式登記服務信息（名稱、啓動參數、工作目錄、端口、日誌文件），之後面板可直接點擊「啓動」按鈕重放。
curl -X POST http://127.0.0.1:3080/api/plugins/process-board/start \
-H 'content-type: application/json' \
-d '{"name":"my-svc","argv":["java","-jar","app.jar"],"cwd":"/path/to/app","port":8080,"logFile":"/tmp/my-svc.log"}'
3. PowerShell 啓動
在 Windows PowerShell 中，可以使用 Start-Process 並配合重定向。
$env:DSH_PB_LOG = "$env:TEMP\my-service.log"
Start-Process java -ArgumentList '-jar','app.jar' -RedirectStandardOutput $env:DSH_PB_LOG -WindowStyle Hidden
注意事項¶
- Mac 平臺限制：當前版本在 Mac 上安裝後插件可加載，但掃描器返回空。原因是
scanner.js中存在process.platform !== 'win32'的提前返回邏輯。探測和停止層已跨平臺就緒，但進程掃描功能暫未在 Mac 上生效。 - 安裝路徑限制：使用
link:方式安裝時，只接受本地目錄路徑。例如dsh plugin --profile web add link:~/dsh-process-board是有效的，而link:https://...會被解析失敗。 - 運行時依賴：插件客戶端爲純 DOM 實現，零運行時依賴。
結語¶
dsh-process-board 是一個面向 DSH 開發者的實用工具，通過環境變量和進程樹分析，實現了服務歸屬的可視化與標準化管理。對於需要頻繁管理後臺服務的智能體開發場景，它能夠顯著提升調試和運維效率。
