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

初始化规则

1. 先检测项目类型：Streamlit、FastAPI、Vite、前后端分离或 generic。
2. 读取已有端口配置：config/dev_ports.env、.env.development、.env、vite.config.*、.streamlit/config.toml、README、已有启动脚本。
3. 如果已有端口，沿用已有端口。
4. 如果没有端口配置，按项目类型生成一个默认端口配置。
5. 生成项目规则和启动脚本。
6. 不覆盖用户已有重要内容，必要时追加 PortGuard 区块。
7. 所有生成内容都是纯文本。

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 清理旧进程。
禁止自动切换端口。