智能端口分配助手
任务目标
-
本 Skill 用于：根据项目名称自动生成可记忆且不易冲突的端口号
-
能力包含：键盘映射算法、端口合法性验证、候选端口智能选择、多端口策略支持
-
触发条件：启动本地多个服务、配置项目前后端端口、微服务架构端口分配
前置准备
-
无需安装额外依赖，使用 npx 直接调用 port-key 工具
-
确保系统已安装 Node.js 和 npm（port-key 通过 npx 自动下载和执行）
操作步骤
标准流程：
处理项目名称
-
短名称规则：如果项目名称较短（1-2 个单词或 1-8 个字母），直接使用完整名称
-
示例："dashboard" → "dashboard"
-
示例："myapp" → "myapp"
-
长名称规则：如果项目名称较长（多个单词或超过 8 个字母），提取每个单词的首字母
-
示例："我爱我家" → "wawj"
-
示例："user authentication service" → "uas"
-
示例："ecommerce payment gateway" → "epg"
-
示例："enterprise resource planning system" → "erps"
-
混合语言支持：自动识别中英文，提取拼音或英文字母的首字母
生成单个项目端口
-
使用 npx 调用 port-key 工具
-
示例：npx -y @lionad/port-key "myproject" → 默认配置下输出 7604
-
智能体将解析返回结果，向用户说明端口号及其含义
处理多组件场景
-
对于需要多个端口的项目（前端、后端、数据库等），使用以下两种策略之一：
-
角色前缀法：将角色放到名称开头，确保角色参与前缀映射（更容易产生不同端口）
-
前端：fe-<project>
-
后端：api-<project>
-
数据库：db-<project>
-
顺序分配法：使用基础端口，然后连续分配
-
Web 服务：基础端口
-
后端 API：基础端口 + 1
-
数据库：基础端口 + 2
端口冲突处理
-
检查生成的端口是否与本地运行服务冲突
-
如有冲突，将冲突端口加入 ~/.port-key/config.json 的 blockedPorts 后重试（或临时设置 PORTKEY_HOME 指向一个独立目录）
可选分支：
-
当项目名称很短（1-3 字母）：工具自动启用零填充策略生成指定位数端口
-
当项目名称很长（多个单词）：自动提取首字母（如 "我爱我家" → "wawj"）
-
当需要特定端口范围：通过 ~/.port-key/config.json 配置 minPort 、maxPort
-
当需要屏蔽某些端口：通过 ~/.port-key/config.json 配置 blockedPorts
资源索引
-
领域参考：见 references/port-key.md（何时读取：需要了解 port-key 工具的详细参数、使用方法或输出格式时）
-
领域参考：见 references/port-best-practices.md（何时读取：需要端口分配策略建议或避免冲突的最佳实践时）
注意事项
-
端口范围必须在 1024-65535 之间（系统端口 0-1023 被屏蔽）
-
生成的端口号仅作为建议，实际使用前请验证端口是否可用
-
端口分配策略应保持团队内部一致，便于记忆和管理
-
多项目开发时建议记录端口分配情况，避免重复
-
使用 npx -y 可自动确认下载，避免交互式提示
-
长项目名称处理：智能体会自动提取首字母，也可手动指定简短名称（如将 "用户认证服务" 指定为 "uas"）
-
首字母规则：英文单词取首字母，中文取拼音首字母，保持可读性和记忆性
使用示例
示例 1：单个项目端口分配（短名称）
场景：启动一个名为 "dashboard" 的新项目 执行方式：使用 npx 调用工具
npx -y @lionad/port-key "dashboard"
输出示例：
3126
智能体说明：默认配置下，项目名称 "dashboard" 通过键盘映射生成端口号 3126。工具只做端口范围与屏蔽列表校验，不检测端口是否被占用。
示例 1.1：单个项目端口分配（长名称 - 自动提取首字母）
场景：启动一个名为 "用户认证服务" 的新项目 智能体处理：自动提取首字母 "uas"（User Authentication Service） 执行方式：
npx -y @lionad/port-key "uas"
输出示例：
7120
智能体说明：项目名称 "用户认证服务" 较长，已提取首字母 "uas" 生成端口号 7120（短输入默认会尾部补 0 到 4 位）。
示例 2：多组件项目端口分配
场景：全栈项目需要前端、后端、数据库三个端口 执行方式：使用角色前缀策略（默认配置下更容易生成不同端口）
1. 生成基础端口
npx -y @lionad/port-key "myapp"
默认输出：7610
2. 前端：角色前缀
npx -y @lionad/port-key "fe-myapp"
示例输出：4376
3. 后端：角色前缀
npx -y @lionad/port-key "api-myapp"
示例输出：1087
4. 数据库：角色前缀
npx -y @lionad/port-key "db-myapp"
示例输出：3576
示例 3：避免端口冲突
场景：已知端口 3000、3001 已被占用 执行方式：将占用端口加入配置文件的屏蔽列表，然后重新生成
~/.port-key/config.json（示例）
{ "blockedPorts": [3000, 3001, 8080] }
npx -y @lionad/port-key "blog"
智能体说明：工具不会检测端口是否被占用；“已占用”需要由智能体用系统命令检查，并把冲突端口加入 blockedPorts 后再生成。
示例 4：指定位数和语言
场景：需要 5 位端口号，且希望显示英文输出 执行方式：使用 --digits 和 --lang 参数
npx -y @lionad/port-key "myproject" --digits 5 --lang en
示例 5：长项目名称处理（中文）
场景：处理中文项目名称 "我爱我家" 智能体处理：自动提取拼音首字母 "wawj" 执行方式：
npx -y @lionad/port-key "wawj"
输出示例：
2127
智能体说明：默认配置下，项目名称 "我爱我家"（Wǒ Ài Wǒ Jiā）已提取首字母 "wawj"，生成端口号 2127。
示例 6：长项目名称处理（英文）
场景：处理英文长项目名称 "Enterprise Resource Planning System" 智能体处理：自动提取首字母 "erps" 执行方式：
npx -y @lionad/port-key "erps"
输出示例：
3402
智能体说明：默认配置下，项目名称 "Enterprise Resource Planning System" 已提取首字母 "erps"，生成端口号 3402。