一句话总结
Vibe Ports 的核心是给人和 AI Agent 一份共同的端口事实源：先查规则，再选端口，最后登记结果。
重点判断
- 端口是否空闲不能只看运行时监听状态，还要看是否被用户或项目规则保留。
- 给前端、API、Worker、Webhook、数据库和本地 AI Gateway 规划固定端口段，可以减少反复试错。
- Agent 规则里要明确：先查注册表，再检查运行时，最后登记端口，不要自动 kill 进程。
项目地址
GitHub：https://github.com/IcePeak8/vibe-ports-skill
为什么需要
Vibe coding 经常同时启动前端、API、Worker、Webhook、数据库面板和本地 AI Gateway。如果每个 Agent 都默认抢 3000 或随手换端口，冲突会很快出现。
端口当前没有监听，不代表它没有被用户或团队保留。端口管理要同时看运行时状态和注册表规则。
- 不要把端口选择交给报错后的临时猜测。
- 不要让 Agent 自动 kill 占用端口的进程。
- 端口规则应该能被人读懂，也能被 Agent 执行。
怎么设计
最小版本用一份 JSON 注册表就够。它记录端口段、端口状态、项目、服务、类型和备注，既可以放在项目里，也可以作为用户级规则保存在本地。
端口段建议按服务类型划分：前端、API、Worker、Admin、Webhook、Database、AI Gateway。这样 Agent 新建服务时有明确选择范围。
- reserved：用户或团队保留端口，即使当前空闲也不要随便占用。
- assigned：已经分配给某个具体服务。
- preferred：某个工具或服务的推荐端口，只有匹配场景时优先使用。
- blocked：明确不要使用的端口。
Agent 执行规则
把端口选择写成固定流程：先判断服务类型，再读注册表，接着检查候选端口，最后写配置并登记结果。
CLI 只需要提供几个稳定命令：list、check、next、reserve、doctor。命令越稳定，Agent 越不容易自由发挥。
- 先查注册表，再查运行时监听。
- 用 env、脚本参数或框架配置写端口，不要散落硬编码。
- 发现端口冲突时先报告，不要自动结束进程。
- 分配完成后更新注册表。
执行清单
| 环节 | 要做什么 | 注意事项 |
|---|---|---|
| 规划端口段 | 按 frontend、api、worker、admin 等类型分区 | 端口段少而清晰，比过度细分更好维护 |
| 注册表 | 用 JSON 记录状态、项目、服务、类型和备注 | 公开仓库只放示例，不放个人真实端口表 |
| 运行前检查 | 同时检查注册表和运行时监听 | 空闲端口也可能被保留 |
| 写入配置 | 优先写 env、脚本参数或框架配置 | 避免在多个文件里硬编码同一个端口 |
| Agent 规则 | 要求 AI Agent 分配前查询、分配后登记 | 不要允许 Agent 自动杀进程 |
我的判断
Vibe Ports 适合先做成轻量规则和 CLI。它不需要复杂后台，但能明显减少 AI Agent 开发里的端口冲突和上下文浪费。