# Smart Port Allocation

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

- Skill: `lionad-morotar/smart-port-allocation` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add lionad-morotar/smart-port-allocation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lionad-morotar/smart-port-allocation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: lionad-morotar (https://skillmd.com/u/lionad-morotar)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lionad-morotar/smart-port-allocation

---


# 智能端口分配助手

## 任务目标
- 本 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](references/port-key.md)（何时读取：需要了解 port-key 工具的详细参数、使用方法或输出格式时）
- 领域参考：见 [references/port-best-practices.md](references/port-best-practices.md)（何时读取：需要端口分配策略建议或避免冲突的最佳实践时）

## 注意事项
- 端口范围必须在 1024-65535 之间（系统端口 0-1023 被屏蔽）
- 生成的端口号仅作为建议，实际使用前请验证端口是否可用
- 端口分配策略应保持团队内部一致，便于记忆和管理
- 多项目开发时建议记录端口分配情况，避免重复
- 使用 `npx -y` 可自动确认下载，避免交互式提示
- **长项目名称处理**：智能体会自动提取首字母，也可手动指定简短名称（如将 "用户认证服务" 指定为 "uas"）
- **首字母规则**：英文单词取首字母，中文取拼音首字母，保持可读性和记忆性

## 使用示例

### 示例 1：单个项目端口分配（短名称）
**场景**：启动一个名为 "dashboard" 的新项目
**执行方式**：使用 npx 调用工具
```bash
npx -y @lionad/port-key "dashboard"
```
**输出示例**：
```
3126
```
**智能体说明**：默认配置下，项目名称 "dashboard" 通过键盘映射生成端口号 3126。工具只做端口范围与屏蔽列表校验，不检测端口是否被占用。

### 示例 1.1：单个项目端口分配（长名称 - 自动提取首字母）
**场景**：启动一个名为 "用户认证服务" 的新项目
**智能体处理**：自动提取首字母 "uas"（User Authentication Service）
**执行方式**：
```bash
npx -y @lionad/port-key "uas"
```
**输出示例**：
```
7120
```
**智能体说明**：项目名称 "用户认证服务" 较长，已提取首字母 "uas" 生成端口号 7120（短输入默认会尾部补 0 到 4 位）。

### 示例 2：多组件项目端口分配
**场景**：全栈项目需要前端、后端、数据库三个端口
**执行方式**：使用角色前缀策略（默认配置下更容易生成不同端口）
```bash
# 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 已被占用
**执行方式**：将占用端口加入配置文件的屏蔽列表，然后重新生成
```bash
# ~/.port-key/config.json（示例）
# { "blockedPorts": [3000, 3001, 8080] }

npx -y @lionad/port-key "blog"
```
**智能体说明**：工具不会检测端口是否被占用；“已占用”需要由智能体用系统命令检查，并把冲突端口加入 blockedPorts 后再生成。

### 示例 4：指定位数和语言
**场景**：需要 5 位端口号，且希望显示英文输出
**执行方式**：使用 `--digits` 和 `--lang` 参数
```bash
npx -y @lionad/port-key "myproject" --digits 5 --lang en
```

### 示例 5：长项目名称处理（中文）
**场景**：处理中文项目名称 "我爱我家"
**智能体处理**：自动提取拼音首字母 "wawj"
**执行方式**：
```bash
npx -y @lionad/port-key "wawj"
```
**输出示例**：
```
2127
```
**智能体说明**：默认配置下，项目名称 "我爱我家"（Wǒ Ài Wǒ Jiā）已提取首字母 "wawj"，生成端口号 2127。

### 示例 6：长项目名称处理（英文）
**场景**：处理英文长项目名称 "Enterprise Resource Planning System"
**智能体处理**：自动提取首字母 "erps"
**执行方式**：
```bash
npx -y @lionad/port-key "erps"
```
**输出示例**：
```
3402
```
**智能体说明**：默认配置下，项目名称 "Enterprise Resource Planning System" 已提取首字母 "erps"，生成端口号 3402。