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 有三条路，不是只有"杀"

先判断属于哪种，再决定动作。不无脑 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"

判读组合：

三种处置 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