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

1. 先判断该不该杀——EADDRINUSE 不等于该杀（复用 > 重启）。
2. 绝不 killall node / pkill -f node——精确 PID，不误伤其他正常服务。
3. PID < 100 绝不杀——系统进程。
4. 别人的进程不杀——换端口绕开。
5. 命令行看不懂 / 不确定是什么——停下报告用户，不擅自杀。

安装 Install

# 发布到 npm 后
dsh plugin --profile demo add dsh-port-guard

# 或从 GitHub 安装
dsh plugin --profile demo add github:PangYiMing/dsh-port-guard

许可证 License

MIT