smart-port-allocation

Smart Port Allocation Assistant

Task Objective

This Skill is used to: automatically generate memorable and conflict-resistant port numbers based on project names
Capabilities include: keyboard mapping algorithm, port validity verification, intelligent candidate port selection, multi-port strategy support
Trigger conditions: starting multiple local services, configuring project frontend and backend ports, port allocation for microservice architectures

Prerequisites

No additional dependencies need to be installed; use npx to directly invoke the port-key tool
Ensure Node.js and npm are installed on the system (port-key is automatically downloaded and executed via npx)

Operation Steps

Standard process:
1. Process project name
  - Short name rule: If the project name is short (1-2 words or 1-8 letters), use the full name directly
    - Example:"dashboard" → "dashboard"
    - Example:"myapp" → "myapp"
  - Long name rule: If the project name is long (multiple words or more than 8 letters), extract the first letter of each word
    - Example:"我爱我家" → "wawj"
    - Example:"user authentication service" → "uas"
    - Example:"ecommerce payment gateway" → "epg"
    - Example:"enterprise resource planning system" → "erps"
  - Mixed language support: Automatically recognizes Chinese and English, extracting the first letter of pinyin or English letters
2. Generate a port for a single project
  - Use npx to invoke the port-key tool
  - Example:npx -y @lionad/port-key "myproject" → Under the default configuration, outputs 7604
  - The agent will parse the returned result and explain the port number and its meaning to the user
3. Handle multi-component scenarios
  - For projects that require multiple ports (frontend, backend, database, etc.), use one of the following two strategies:
    - Role prefix method: Place the role at the beginning of the name to ensure the role participates in prefix mapping (making it easier to produce different ports)
      - Frontend:fe-<project>
      - Backend:api-<project>
      - Database:db-<project>
    - Sequential allocation method: Use a base port, then allocate consecutively
      - Web service: base port
      - Backend API: base port + 1
      - Database: base port + 2
4. Handle port conflicts
  - Check whether the generated port conflicts with locally running services
  - If there is a conflict, add the conflicting port to ~/.port-key/config.json 's blockedPorts and retry (or temporarily set PORTKEY_HOME to point to a separate directory)
Optional branches:
- When the project name is very short (1-3 letters): the tool automatically enables the zero-padding strategy to generate a port with the specified number of digits
- When the project name is very long (multiple words): automatically extract the first letters (e.g., "我爱我家" → "wawj")
- When a specific port range is needed: configure via ~/.port-key/config.json configure minPort、maxPort
- When certain ports need to be blocked: via ~/.port-key/config.json configure blockedPorts

Resource Index

Domain reference: see references/port-key.md(When to read: when you need to understand the detailed parameters, usage, or output format of the port-key tool)
Domain reference: see references/port-best-practices.md(When to read: when you need port allocation strategy recommendations or best practices for avoiding conflicts)

Notes

The port range must be between 1024-65535 (system ports 0-1023 are blocked)
The generated port number is only a suggestion; please verify whether the port is available before actual use
The port allocation strategy should remain consistent within the team to facilitate memorization and management
During multi-project development, it is recommended to record port allocations to avoid duplication
Use npx -y to automatically confirm the download and avoid interactive prompts
Handling long project names: The agent will automatically extract the initials, and you can also manually specify a short name (for example, specifying "用户认证服务" as "uas")
Initials rule: For English words, take the initial letter; for Chinese, take the pinyin initial, maintaining readability and memorability

Usage Examples

Example 1: Port allocation for a single project (short name)

Scenario: Start a new project named "dashboard" Execution method: Use npx to invoke the tool

npx -y @lionad/port-key "dashboard"

Example output：

Agent explanation: Under the default configuration, the project name "dashboard" generates port number 3126 through keyboard mapping. The tool only validates the port range and the blocked list; it does not check whether the port is occupied.

Example 1.1: Port allocation for a single project (long name - automatic initial extraction)

Scenario: Start a new project named "用户认证服务" Agent handling: Automatically extract the initials "uas" (User Authentication Service) Execution method：

npx -y @lionad/port-key "uas"

Example output：

Agent explanation: The project name "用户认证服务" is relatively long, so the initials "uas" have been extracted to generate port number 7120 (short input will by default be padded with 0s at the end to 4 digits).

Example 2: Port allocation for a multi-component project

Scenario: A full-stack project needs three ports: frontend, backend, and database Execution method: Use the role prefix strategy (under the default configuration, it is easier to generate different ports)

# 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

Example 3: Avoiding port conflicts

Scenario: Ports 3000 and 3001 are known to be occupied Execution method: Add the occupied ports to the blocked list in the configuration file, then regenerate

# ~/.port-key/config.json（示例）
# { "blockedPorts": [3000, 3001, 8080] }

npx -y @lionad/port-key "blog"

Agent explanation: The tool does not detect whether a port is occupied; "occupied" needs to be checked by the agent using system commands, and the conflicting ports must be added to blockedPorts before regenerating.

Example 4: Specify the number of digits and language

Scenario: A 5-digit port number is needed, and English output is desired Execution method: Use --digits and --lang parameters

npx -y @lionad/port-key "myproject" --digits 5 --lang en

Example 5: Handling a long project name (Chinese)

Scenario: Handle the Chinese project name "我爱我家" Agent handling: Automatically extract the pinyin initials "wawj" Execution method：

npx -y @lionad/port-key "wawj"

Output example：

Agent description: Under the default configuration, the project name "我爱我家" (Wǒ Ài Wǒ Jiā) has had the initials "wawj" extracted, generating port number 2127.

Example 6: Long project name handling (English)

Scenario: Handle the long English project name "Enterprise Resource Planning System" Agent processing: Automatically extract the initials "erps" Execution method：

npx -y @lionad/port-key "erps"