Port Manager

端口管理器（Port Manager）

为每个项目服务分配唯一的网络端口，并在启动开发服务器时通过环境变量注入，避免同一台机器上不同项目之间的端口冲突。

核心规则

当此 skill 被触发时，必须先通过 ~/.port-man 获取端口，然后将 PORT=<端口>（或框架对应的端口变量）前置到原启动命令中。

# 1. 为该服务分配或获取已有端口
PORT=$(python3 skills/port-manager/scripts/portman.py get $(pwd) frontend)

# 2. 注入端口并启动开发服务器
PORT=$PORT npm run dev

大多数前端工具（Vite、Next.js、CRA）都支持 PORT 环境变量。若框架使用其他变量，请按需调整：

• PORT — Vite、Next.js、Create React App、Express、Fastify
• VITE_DEV_PORT / SERVER_PORT — 部分自定义配置
• --port CLI 参数 — npm run dev -- --port $PORT

快速开始

分配端口并启动服务

PORT=$(python3 skills/port-manager/scripts/portman.py get $(pwd) frontend)
PORT=$PORT npm run dev

若该服务已有记录端口，脚本会直接返回；否则自动寻找下一个可用端口并持久化记录。

查看所有已分配端口

python3 skills/port-manager/scripts/portman.py list

释放端口占用

python3 skills/port-manager/scripts/portman.py free <项目路径> <服务名>

标准工作流

为项目启动任何开发服务器时：

1. 获取端口（必要时自动分配）：

   PORT=$(python3 skills/port-manager/scripts/portman.py get $(pwd) web)
   

2. 将端口注入启动命令：

   PORT=$PORT npm run dev
   

   同一项目多个服务可并行启动：

   FRONTEND_PORT=$(python3 skills/port-manager/scripts/portman.py get $(pwd) frontend)
   BACKEND_PORT=$(python3 skills/port-manager/scripts/portman.py get $(pwd) backend)
   
   PORT=$FRONTEND_PORT npm run dev:web &
   PORT=$BACKEND_PORT npm run dev:api &
   

3. 持久化配置（可选）：将分配的端口写入 .env 或 docker-compose.yml，方便团队或 CI 查看，但建议始终保留命令行注入的习惯以确保端口被真正预留。

数据格式

~/.port-man 为 JSON 文件：

{
  "version": "1.0",
  "projects": {
    "/Users/me/project-a": {
      "services": {
        "frontend": 3001,
        "backend": 5001
      }
    }
  }
}

注意事项

• 务必通过环境变量注入端口（PORT=xxx <命令>），不要依赖写死的默认端口。
• 脚本会自动跳过常用保留端口（如 80、443、8080），减少与系统默认服务的冲突。
• 始终以项目的绝对路径作为键值。
• ~/.port-man 是机器本地文件，不建议提交到共享仓库。