技能介绍

问题背景

用 Claude Code、Cursor 等工具做本地自测时，常见一套连锁故障：上一轮 dev 进程没关干净、端口仍被占用，工具或框架于是自动换端口；前端仍指向旧 API 地址，后端或 Vite/Streamlit 却监听新端口，报错看起来像「接口挂了」，实则是前后端地址不一致。手工改 .env、临时改 vite.config 只能掩盖一次，规则也不会写进项目里。

技能如何工作

port-guard-init 在目标项目根目录做一次 PortGuard 初始化，把端口治理写进仓库，而不是强加全局统一端口：

以项目为准：当前项目的 dev 端口以 config/dev_ports.env 为单一事实来源；会读取 .env.development、.env、vite.config.*、.streamlit/config.toml、README 与既有启动脚本，已有配置则沿用。
识别栈类型：区分 Streamlit、FastAPI、Vite、前后端分离或 generic，无配置时再按类型生成默认端口与文本规则。
生成可执行约定：产出项目规则与 Windows 启动脚本（由 scripts/portguard_init.py 在目标项目中按文本生成；Skill 包本身不含 .bat/二进制）。自测要求通过 scripts/restart_dev.bat 启动；端口被占用时清理旧进程，不允许自动换端口，也不允许临时改前端 API、后端监听、Streamlit 或 Vite 端口来绕过。
尽量不破坏现有内容：必要时以 PortGuard 区块追加，不粗暴覆盖用户已有重要文件。

适用边界

面向当前仓库的 dev 端口治理与 AI 自测纪律，不是跨项目端口编排平台。
Skill 包仅含纯文本；实际 .bat 等脚本在初始化时于目标项目内生成，需接受 PortGuard 的目录与启动约定。
初始化后，后续 AI 自测应持续遵守上述规则，否则仍可能回到「换端口 + 地址漂移」的老问题。

截图预览

使用场景

用 Cursor 自测 FastAPI 与 Vite 联调时，端口被占后框架自动换端口，需在项目根初始化固定端口与 `restart_dev.bat`。
新 clone 的前后端分离仓库还没有 `config/dev_ports.env`，要一次性生成 PortGuard 规则并让后续 AI 只按约定脚本启动。
Streamlit 本地反复调试后旧进程未退出，需初始化规则：占用端口时清理进程，禁止改 `config.toml` 端口绕过。
Claude Code 在项目根 slash 调用初始化，在保留现有 `.env` 与 vite 配置的前提下追加 PortGuard 区块与启动纪律。

适合人员

在 Windows 上用 Cursor/Claude Code 做本地自测的全栈工程师，希望端口冲突时清旧进程而非自动换端口导致 API 地址漂移。
维护 FastAPI、Vite 或 Streamlit 多仓库的维护者，需要每个项目独立维护 `config/dev_ports.env` 与统一自测启动方式。
经常让 AI 反复重启 dev 服务做联调验证的原型/数据应用开发者，受「前端仍指向旧端口」类假故障困扰。
从 SkillHub 引入 PortGuard 工作流、需在既有启动脚本和 env 文件上追加治理规则而不粗暴覆盖的仓库贡献者。