| name | smart-port-allocation |
| description | 根据项目名称通过键盘映射算法生成可记忆的端口号，解决本地开发多项目端口冲突问题；支持微服务架构端口分配、前后端组件端口规划 |
智能端口分配助手
任务目标
- 本 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
资源索引
注意事项
- 端口范围必须在 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：多组件项目端口分配
场景：全栈项目需要前端、后端、数据库三个端口
执行方式：使用角色前缀策略（默认配置下更容易生成不同端口）
npx -y @lionad/port-key "myapp"
npx -y @lionad/port-key "fe-myapp"
npx -y @lionad/port-key "api-myapp"
npx -y @lionad/port-key "db-myapp"
示例 3：避免端口冲突
场景：已知端口 3000、3001 已被占用
执行方式：将占用端口加入配置文件的屏蔽列表，然后重新生成
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。
