前言¶
當 Coding Agent 啓動多個本地服務後，用戶很難判斷當前機器上的端口屬於誰、爲何還在運行，以及是否可以安全關閉。在多服務聯調或後臺任務持續運行的 Session 中，這種信息缺失會導致端口衝突、誤殺其他服務或遺留殭屍進程。dsh-port-inspector 是 DeepSeek Harness Web 環境下的一個輔助插件，用於解決監聽端口來源追蹤與安全處理的問題。
核心功能¶
插件通過集中展示監聽端口、應用、PID 與監聽地址，並區分來源與處理方式，幫助開發者理清當前環境。
- 端口總覽：集中查看項目和系統中的監聽端口、應用、PID 與監聽地址。
- 來源識別：區分當前會話、其他 DSH 會話和普通外部進程。
- 安全停止：對 DSH 管理的進程執行經過身份校驗的停止操作。
- 結束進程：對身份信息完整的外部進程提供直接結束能力。
- 打開目錄：從端口詳情快速跳轉到關聯項目目錄。
- Compose 識別：展示 Compose 文件、服務、鏡像、容器和端口映射。
- 啓動鏈路：查看從根進程到監聽進程的完整啓動關係。
- 快速篩選：支持按端口、應用、PID、項目和會話搜索、篩選與排序。
- 複製詳情：一鍵複製端口、進程、來源和會話信息。
- 界面同步：自動跟隨 DSH 的語言、深淺色和設計風格。
- 只讀診斷：提供只讀
port_listTool，用於診斷端口衝突。
安裝與啓用¶
前置條件：
* Windows 操作系統
* Node.js >= 22.19.0
* 可運行的 DeepSeek Harness (DSH)
* PATH 中可用的 pnpm
* 目標 DSH Profile 爲 web
安裝方式：
- 通過 npm 安裝（推薦）
dsh plugin --profile web add dsh-port-inspector@latest
- 通過 GitHub Release 下載並安裝
gh release download --repo ianho7/dsh-port-inspector --pattern 'dsh-port-inspector-*.tgz' --output 'dsh-port-inspector-latest.tgz'
dsh plugin --profile web add '.\dsh-port-inspector-latest.tgz'
- 從源碼編譯並安裝
git clone https://github.com/ianho7/dsh-port-inspector.git
cd dsh-port-inspector
npm install
npm run build
npm pack --ignore-scripts
dsh plugin --profile web add ".\$PackageFile"
*注意：在首次安裝或使用 `koffi` 時，如果遇到 `ERR_PNPM_IGNORED_BUILDS`，需在對應 Profile 的 `pnpm-workspace.yaml` 中設置 `allowBuilds: koffi: true`。*
啓用：
安裝完成後啓動 DSH Web：
dsh web
瀏覽器打開後，創建新的 DeepSeek Harness Session，讓 Agent 啓動本地服務，然後在側邊欄打開 Port Inspector。
典型用法¶
- 查看端口信息：在 Port Inspector 面板中查看端口、PID、應用、項目、創建時間、來源和處理方式。
- 執行處理操作：
- 對於受管資源（DSH 啓動），選擇“停止 DeepSeek Harness 任務”。
- 對於符合安全條件的外部進程，選擇“結束該進程”。
- 確認結果：確認後等待 fresh scan，檢查界面報告的
portReleased結果，確認端口是否實際釋放。
注意事項與限制¶
- 平臺限制：僅支持 Windows 本地執行環境 和 TCP 監聽。
- 身份驗證：
Verified attribution需要具備 PID、創建時間和可驗證的 Windows 父進程鏈，不能僅憑命令、目錄、時間或端口號猜測。 - 生命週期管理：
- DeepSeek Harness 受管目標優先使用 Job/Terminal 生命週期；
Managed shutdown失敗時不會自動升級爲 PID 強殺。 - 外部目標只允許用戶確認後，重新校驗身份並結束明確選擇的單個同用戶 PID。
- DeepSeek Harness 受管目標優先使用 Job/Terminal 生命週期；
- 安全邊界：
- 不終止外部進程樹、不自動提權、不讀取環境祕密。
- 系統進程、其他用戶進程、受保護進程、身份不完整或權限不足的目標保持只讀。
- 歸因機制：
- 安裝或更新 Bundle 後必須重啓目標 Profile，並創建新的任務才能獲得來源歸因。
- 來源記錄只保留在當前 DeepSeek Harness 運行週期內，不會追溯歸因重啓前已經存在的進程。
- 兼容性：部分 Stock DeepSeek Harness 與 Windows ConPTY 組合會先返回 PID = 0 的 LocalTerminalHandle，僅在精確版本和精確句柄形狀均匹配時，兼容層纔等待 PTY 發佈正 PID。
- 卸載行爲：卸載插件只清理自身資源，不自動終止用戶進程。
總結¶
dsh-port-inspector 是一個專注於 Windows 本地開發的端口管理輔助工具，它通過連接 Windows 監聽端口、進程鏈與 DeepSeek Harness 的 Session/Tool Call，實現了對開發服務來源的可追溯與安全可控管理。適合需要在多項目並行開發中區分同名進程、解決端口衝突的開發者使用。
