smart-port-allocation

name	smart-port-allocation
description	根据项目名称通过键盘映射算法生成可记忆的端口号，解决本地开发多项目端口冲突问题；支持微服务架构端口分配、前后端组件端口规划

智能端口分配助手

任务目标

• 本 Skill 用于：根据项目名称自动生成可记忆且不易冲突的端口号
• 能力包含：键盘映射算法、端口合法性验证、候选端口智能选择、多端口策略支持
• 触发条件：启动本地多个服务、配置项目前后端端口、微服务架构端口分配

前置准备

• 无需安装额外依赖，使用 npx 直接调用 port-key 工具
• 确保系统已安装 Node.js 和 npm（port-key 通过 npx 自动下载和执行）

操作步骤

• 标准流程：

  1. 处理项目名称

     • 短名称规则：如果项目名称较短（1-2 个单词或 1-8 个字母），直接使用完整名称
       • 示例："dashboard" → "dashboard"
       • 示例："myapp" → "myapp"
     • 长名称规则：如果项目名称较长（多个单词或超过 8 个字母），提取每个单词的首字母
       • 示例："我爱我家" → "wawj"
       • 示例："user authentication service" → "uas"
       • 示例："ecommerce payment gateway" → "epg"
       • 示例："enterprise resource planning system" → "erps"
     • 混合语言支持：自动识别中英文，提取拼音或英文字母的首字母

  2. 生成单个项目端口

     • 使用 npx 调用 port-key 工具
     • 示例：npx -y @lionad/port-key "myproject" → 默认配置下输出 7604
     • 智能体将解析返回结果，向用户说明端口号及其含义

  3. 处理多组件场景

     • 对于需要多个端口的项目（前端、后端、数据库等），使用以下两种策略之一：
       • 角色前缀法：将角色放到名称开头，确保角色参与前缀映射（更容易产生不同端口）
         • 前端：fe-<project>
         • 后端：api-<project>
         • 数据库：db-<project>
       • 顺序分配法：使用基础端口，然后连续分配
         • Web 服务：基础端口
         • 后端 API：基础端口 + 1
         • 数据库：基础端口 + 2

  4. 端口冲突处理

     • 检查生成的端口是否与本地运行服务冲突
     • 如有冲突，将冲突端口加入 ~/.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。