dsh-port-guard
DeepSeek Harness 插件 · 端口占用处置 / DSH plugin for triaging port conflicts
dev server 启动报 EADDRINUSE: address already in use——最常见的前置障碍。但不是所有 EADDRINUSE 都该 kill。
The classic blocker before any dev server starts. But not every EADDRINUSE should be killed.
核心洞察：EADDRINUSE 有三条路，不是只有"杀"
| 情况 | 占端口的是谁 | 正确动作 |
|---|
| A. 自己的、还在正常服务的 dev server | 上次会话遗留的同项目 dev server | 复用，比重启快 |
| B. 别人的项目 / 不该杀的进程 | 另一个项目 / 系统服务 | 换端口绕开，不抢杀 |
| C. 确认是僵尸/残留进程 | 已死但端口没释放 / 重复拉起的 | 精确 PID kill |
先判断属于哪种，再决定动作。不无脑 kill。
定位 + 取证 Identify & investigate
./scripts/port-guard.sh 8080
脚本会打印占用进程的完整身份信息：
# 定位
lsof -nP -iTCP:8080 -sTCP:LISTEN
# 身份：启动时刻/运行时长/有无控制终端
ps -o pid,ppid,lstart,etime,tty,%cpu,rss,command -p "$PID"
# 工作目录 → 属于哪个项目
lsof -a -p "$PID" -d cwd -Fn | grep '^n' | sed 's/^n//'
# 子进程（有子进程的别直接杀父，先看树）
pgrep -P "$PID"
判读组合：
| 观察 | 含义 |
|---|
PPID=1 | 父进程已退出，被 launchd 收养 —— 孤儿 |
tty=?? | 没有控制终端，不是人在终端里跑的 |
fd0 → /dev/null，fd1/fd2 → 某个 .log | nohup cmd > log 2>&1 & 指纹 → agent/脚本起的 |
tty=ttys00X | 人在终端窗口起的，杀之前更该问一声 |
etime 好几天 + %cpu 0.0 + rss 极小 | 挂了很久的僵尸 watcher（可能 watch 源码目录，某天突然醒来写产物） |
三种处置 Three paths
# A. 复用：确认进程还活着（kill -0 只检测不杀）
kill -0 "$PID" && echo alive
# B. 换端口绕开，不杀别人的
PORT=18080 node index.js
# C. 精确 kill（先 SIGTERM 给优雅退出机会，不行再 SIGKILL）
./scripts/port-guard.sh 8080 --kill
安全红线 Safety rules
- 先判断该不该杀——EADDRINUSE 不等于该杀（复用 > 重启）。
- 绝不
killall node / pkill -f node——精确 PID，不误伤其他正常服务。
- PID < 100 绝不杀——系统进程。
- 别人的进程不杀——换端口绕开。
- 命令行看不懂 / 不确定是什么——停下报告用户，不擅自杀。
安装 Install
# 发布到 npm 后
dsh plugin --profile demo add dsh-port-guard
# 或从 GitHub 安装
dsh plugin --profile demo add github:PangYiMing/dsh-port-guard
许可证 License
MIT
