dsh-treekeeper：DSH 進程樹對賬與治理插件

DSH 任務賬本與實際運行的操作系統進程之間常出現偏差。可能是進程泄漏，也可能是孤兒進程，亦或是歸屬關係不清晰。dsh-treekeeper 旨在解決這些問題。它對賬 DSH 任務賬本與 OS 進程樹，定位歸屬、檢測泄漏並安全治理。

安裝與啓用¶

安裝該插件會將它註冊到指定的 DSH profile 中。

dsh plugin --profile web add dsh-treekeeper

安裝後需要重啓 DSH Web 才能生效。

核心功能¶

該插件提供以下功能：

• 進程採樣與歸屬：採樣當前 DSH 宿主的進程樹，把每個進程歸屬到創建它的任務。同時檢測重複命令、孤兒進程與長時間運行的插件子進程。
• 會話對賬：對照任務賬本與根 session 的 subagent 子代理樹，識別進程與任務的關係。
• 安全治理：提供受保護的整樹終止功能。
• 插件識別：從命令行中的 node_modules 路徑識別進程所屬插件。
• 面板展示：
  • DSH 宿主子進程分區默認收起，數量顯示在標題上。
  • 面板頭部顯示宿主類型（取自宿主進程的可執行路徑與命令行，不依賴環境變量）。
  • 桌面應用自身的 Electron 進程在未歸屬分區內單列爲一個進程組。
• Finding 置信度：finding 的置信度分三檔（exact、indicative、inferred），用於輔助判斷終止目標。

配置¶

配置僅在當前進程中生效，重啓後恢復默認值。

典型用法¶

• 打開面板：點擊頁面左下的 dsh-mini-utility-dock launcher 打開全局面板。也可以通過會話標題欄打開面板並聚焦該 session。
• 查看緩存：查看會話已緩存的事實。
• 終止操作：通過身份覈對確認終止目標。

安全與邊界¶

平臺與降級¶

• 平臺限制：僅支持 Windows。在非 Windows 平臺會報告 unsupported_platform。
• CIM 降級：CIM（Windows Management Instrumentation）不可用時，插件會降級爲只讀採樣，歸屬與終止功能將被禁用。

訪問控制¶

• 憑據複用：DSH 0.1.0-rc.7+ 版本複用 Connection 的簽名 cookie。
• 准入規則：
  • 宿主有 Connection：由 Connection 的 Host/Origin 校驗與簽名 cookie 決定。
  • 宿主無 Connection：由本插件守衛按 TCP 對端地址、Fetch Metadata、Origin 與 loopback Host 判定。
• 遠端可達：宿主配置 trustedHosts 且監聽 0.0.0.0 時，持有有效瀏覽器會話的遠端可調用包括 kill 在內的接口。
• 寫入限制：僅接受 POST 請求。

終止護欄¶

爲了防止誤殺，終止操作設有以下護欄：

1. 激活：第一次點擊激活按鈕，6 秒內有效。
2. 確認：第二次點擊彈出瀏覽器確認框。
3. 快照：要求 15 秒內的完整快照。
4. 身份覈對：請求進入時按快照覈對 PID 創建時間。
5. 執行前複覈：終止前重新採樣，再覈對一次創建時間。
6. 歸屬限制：僅歸屬根爲 DSH 宿主的進程可終止，未歸屬進程只用於排查。
7. 不可終止列表：系統關鍵進程、當前宿主、啓動鏈與 extraWhitelistPids 中的 PID 不可終止。
8. 白名單限制：額外白名單 PID 只作爲排查用的歸屬根，其子進程可見但不可終止。
9. 受保護子進程：終止前即時採樣的樹含任一受保護 PID 時，整個操作被拒絕。

限制說明¶

• PID 映射：Jobs 與 OS 進程之間沒有穩定的 PID 映射。
• 命令行匹配：命令行匹配只用於排查，不觸發自動操作。
• 日誌記錄：Findings 與終止結果寫入 $DSH_HOME/treekeeper/history.l。

總結¶

dsh-treekeeper 是一個專注於進程樹對賬與安全治理的工具。它通過嚴格的准入校驗和多層護欄，確保在清理泄漏或孤兒進程時不會影響系統關鍵服務或當前任務。對於需要精細化管理 DSH 進程環境的場景，該插件提供了必要的可視化與控制能力。

• 目錄頁：dsh-treekeeper
• GitHub 倉庫：xswt442-cmd/dsh-treekeeper