前言¶
本地起 dev server，最常碰到的第一個障礙就是 EADDRINUSE: address already in use。在智能體工作流裏，這個報錯往往出現在任務最開頭，而常見的處理方式很粗：直接 killall node 或 pkill -f node。結果是把機器上其他正常運行的 Node 服務一併殺掉。
但佔着端口的進程不一定是該殺的：可能是自己上次會話遺留、還在正常服務的 dev server，也可能是別的項目或系統服務。也就是說，EADDRINUSE 有三條處置路徑——複用、換端口、精確 kill——正確做法是先判斷屬於哪種，再決定動作。
dsh-port-guard 就是把這套判讀流程做成插件的一個 DSH 工具。DSH（DeepSeek Harness）的理念是「一切皆插件」，下面介紹它的定位、功能和用法。
這是什麼¶
dsh-port-guard 是一個 DeepSeek Harness 插件，作者是 PangYiMing，當前版本 0.1.0，許可證爲 MIT。一句話定位：端口占用處置——對佔端口的進程，按情況選擇複用、換端口或精確 kill。
它解決的問題是：把「端口被佔」從一次粗暴的 kill 變成一次有依據的判讀，既不誤殺別人的進程，也不白白重啓自己還活着的 dev server。
核心功能¶
定位與取證¶
./scripts/port-guard.sh 8080
把 8080 換成實際被佔的端口。腳本會打印佔用進程的完整身份信息：先用 lsof 定位監聽該端口的進程，再用 ps 查看啓動時刻、運行時長、有無控制終端、%cpu 和 rss；用 lsof 的 cwd 定位進程屬於哪個項目；最後用 pgrep 查子進程——有子進程的不要直接殺父進程，先看樹。
判讀組合¶
取證信息拿到後怎麼判斷？README 給出了幾組典型判讀：
PPID=1：父進程已退出，被 launchd 收養——孤兒進程tty=??：沒有控制終端，不是人在終端裏跑的fd0 → /dev/null且fd1/fd2 → 某個 .log：nohup cmd > log 2>&1 &的指紋，說明是 agent 或腳本拉起的etime好幾天，加%cpu 0.0，加rss極小：掛了很久的殭屍 watcher，可能一直 watch 着源碼目錄，某天突然醒來寫產物tty=ttys00X：人在終端窗口裏起的，殺之前更應該問一聲
三條處置路徑¶
先判斷屬於哪種情況，再選對應動作，不無腦 kill。
路徑 A，複用。佔端口的是自己項目的 dev server，還在正常服務，複用比重啓快。複用前先確認進程還活着，kill -0 只檢測、不殺：
kill -0 "$PID" && echo alive
路徑 B，換端口。佔端口的是別人的項目或不該殺的進程，繞開即可，不搶殺：
PORT=18080 node index.js
路徑 C，精確 kill。確認是殭屍或殘留進程後，用插件的 kill 模式。它會先發 SIGTERM 給進程一個優雅退出的機會，不行再 SIGKILL：
./scripts/port-guard.sh 8080 --kill
安全紅線¶
插件內置了五條紅線，是設計約束而不是靠使用者自覺：
- EADDRINUSE 不等於該殺，先判斷該不該殺，複用優先於重啓。
- 絕不
killall node/pkill -f node，只做精確 PID kill，不誤傷其他正常服務。 - PID < 100 絕不殺，那是系統進程。
- 別人的進程不殺，換端口繞開。
- 命令行看不懂、不確定是什麼時，停下報告用戶，不擅自殺。
安裝與啓用¶
兩種安裝方式。README 註明，第一種要等插件發佈到 npm 之後纔可用：
# 發佈到 npm 後
dsh plugin --profile demo add dsh-port-guard
# 或從 GitHub 安裝
dsh plugin --profile demo add github:PangYiMing/dsh-port-guard
兩條命令都會把 dsh-port-guard 裝進 --profile 指定的 profile。
典型用法¶
按一次真實的端口衝突走一遍：
1、先定位取證：
./scripts/port-guard.sh 8080
2、看輸出判讀。如果是自己項目上次遺留的 dev server，先確認它還活着，活着就直接複用，不必重啓：
kill -0 "$PID" && echo alive
3、如果佔端口的是別人的項目或系統服務，換端口繞開，不動別人的進程：
PORT=18080 node index.js
4、只有確認是殭屍或殘留進程，才走精確 kill：
./scripts/port-guard.sh 8080 --kill
適用場景與注意¶
適合經常在本機啓動 dev server 的智能體工作流和開發者，尤其是機器上同時跑着多個項目、不希望一次端口衝突演變成誤殺的場景。
兩點注意：
- 插件以當前 dsh 進程的權限運行，kill 模式操作的是真實進程。安裝前應檢查源碼與許可證（本插件爲 MIT）。
- 判讀規則是參考，不是免檢：遇到
tty=ttys00X這類「有人在終端裏跑」的進程，殺之前先向用戶確認。
小結¶
dsh-port-guard 的價值不在 kill 本身，而在 kill 之前的判讀：EADDRINUSE 有三條路，無腦 kill 只是其中最差的一條。把定位、取證、判讀、處置固化成腳本和安全紅線，端口衝突的處理就不再靠碰運氣。
- 社區目錄頁：https://www.skillhub.cn/plugins/PangYiMing/dsh-port-guard （第三方社區目錄，非官方應用商店）
- GitHub 倉庫：https://github.com/PangYiMing/dsh-port-guard
