PortGuard Init Skill
PortGuard 初始化当前项目的端口治理规则，解决 AI 编码工具在自测时旧进程没关闭、端口被占用、自动换端口，最终导致前后端地址不一致的问题。
核心原则
- 不强制所有项目使用统一端口。
- 每个项目维护自己的端口配置。
- 当前项目的端口以
config/dev_ports.env为准。 - Claude Code / Cursor 自测时必须通过
scripts/restart_dev.bat启动。 - 如果端口被占用，必须清理旧进程，不允许自动换端口。
- 不允许临时修改前端 API 地址、后端监听端口、Streamlit 端口或 Vite 端口来绕过问题。
重要上传限制
本 Skill 包自身只能包含纯文本文件，不包含 .bat、.ps1、.exe、.dll、.pyc、图片、音频、视频、压缩包内嵌压缩包等文件。
需要的 Windows 脚本由 scripts/portguard_init.py 在目标项目中按文本方式生成。
使用方式
在目标项目根目录调用本 Skill，执行初始化脚本：
python path/to/port-guard-init/scripts/portguard_init.py --project . --app-type auto
如果通过 Claude Code slash command 调用，请使用：
/port-guard-init
初始化后，目标项目会生成：
config/dev_ports.env
scripts/stop_dev.bat
scripts/start_dev.bat
scripts/restart_dev.bat
scripts/port_guard.ps1
.cursor/rules/port-management.mdc
.claude/settings.json
CLAUDE.md
README_PORT_GUARD.md
初始化规则
- 先检测项目类型：Streamlit、FastAPI、Vite、前后端分离或 generic。
- 读取已有端口配置：
config/dev_ports.env、.env.development、.env、vite.config.*、.streamlit/config.toml、README、已有启动脚本。 - 如果已有端口，沿用已有端口。
- 如果没有端口配置，按项目类型生成一个默认端口配置。
- 生成项目规则和启动脚本。
- 不覆盖用户已有重要内容，必要时追加 PortGuard 区块。
- 所有生成内容都是纯文本。
Claude Code / Cursor 后续自测要求
初始化完成后，AI 必须遵守：
先读取 config/dev_ports.env。
启动或自测必须运行 scripts/restart_dev.bat。
禁止直接运行裸命令，例如 streamlit run app.py、npm run dev、uvicorn main:app。
端口占用时必须执行 scripts/stop_dev.bat 清理旧进程。
禁止自动切换端口。
