@lionad/port-key-skills 0.6.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# 更新日志
+
+## v0.6.0
+
+- chore: sync version
+
+## v0.5.0
+
+- 增加 @lionad/port-key-skills

package/LICENSE

@@ -0,0 +1,7 @@
+ISC License
+
+Copyright (c) 2026 Lionad
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,20 @@
+# PortKey Skills
+
+本目录包含基于 `SKILL.md` 定义的 Agent Skills。
+
+## 目录结构
+
+所有技能按以下结构组织：
+
+```
+skills/<skill-name>/SKILL.md
+```
+
+## 使用方式
+
+如果你使用 `npx skills` 生态工具，可以通过 GitHub 仓库路径安装或列出技能：
+
+```bash
+npx -y skills add https://github.com/Lionad-Morotar/port-key/tree/main/packages/skills --list
+npx -y skills add https://github.com/Lionad-Morotar/port-key/tree/main/packages/skills --skill smart-port-allocation
+```

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@lionad/port-key-skills",
+  "version": "0.6.0",
+  "description": "Agent skills for PortKey",
+  "files": [
+    "skills",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "author": "Lionad",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lionad-Morotar/port-key.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Lionad-Morotar/port-key/issues"
+  },
+  "homepage": "https://github.com/Lionad-Morotar/port-key#readme",
+  "engines": {
+    "node": ">=16"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "echo 'skip build steps in packages/skills'",
+    "test": "echo 'skip test steps in packages/skills'"
+  }
+}

package/skills/smart-port-allocation/SKILL.md

@@ -0,0 +1,159 @@
+---
+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](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。

package/skills/smart-port-allocation/references/port-best-practices.md

@@ -0,0 +1,229 @@
+# 端口分配最佳实践
+
+## 目录
+- [端口分类与规范](#端口分类与规范)
+- [本地开发端口分配策略](#本地开发端口分配策略)
+- [避免端口冲突的方法](#避免端口冲突的方法)
+- [团队协作与文档管理](#团队协作与文档管理)
+- [常见问题排查](#常见问题排查)
+
+## 概览
+本文档提供端口分配的最佳实践指南，帮助开发者在本地开发和团队协作中有效管理端口资源，避免端口冲突，提升开发效率。
+
+## 端口分类与规范
+
+### 端口范围划分
+- **系统端口（0-1023）**：由 IETF 分配，需要 root 权限，严格禁止使用
+- **用户端口（1024-49151）**：由 IANA 分配，注册服务使用，谨慎使用
+- **动态/私有端口（49152-65535）**：未分配，临时使用最安全
+
+### 推荐端口范围
+- **常规开发**：`3000-3999` 或 `8000-8999`
+- **微服务集群**：`5000-5999` 或 `9000-9999`
+- **测试环境**：`10000-19999`
+- **注意（PortKey 默认）**：PortKey 默认会屏蔽一批常见端口（如 3000、3001、5173、8080 等）；若团队强制使用某些端口段，建议在 `~/.port-key/config.json` 中统一 `blockedPorts/minPort/maxPort`。
+
+## 本地开发端口分配策略
+
+### 单项目场景
+**原则**：一个项目使用一个主端口，根据项目特性选择范围
+
+- **前端项目**：推荐 `3000-3999`（如 3000, 3173, 3333）
+- **后端服务**：推荐 `8000-8999`（如 8000, 8080, 8765）
+- **数据库**：使用标准端口或 `5000-5999`（如 5432, 5701）
+
+### 多组件项目场景
+**策略 A：角色前缀法（推荐）**
+将角色放到名称开头，确保角色参与端口映射的前缀候选，减少“多个组件映射到同一端口”的概率。
+
+```
+示例项目 "shop"
+- 基础端口：2690（shop）
+- 前端：4326（fe-shop）
+- 后端：1082（api-shop）
+- 数据库：3526（db-shop）
+```
+
+**策略 B：顺序分配法**
+从基础端口开始连续分配
+
+```
+示例项目 "shop"
+- 基础端口：2690
+- 前端：2690
+- 后端：2691
+- 数据库：2692
+```
+
+**说明**：
+- PortKey 默认会优先取 4 位候选；当项目名本体已经足够生成 4 位候选时，简单追加后缀（如 `<project>-db`）可能不会影响“最先被选中的候选”，导致多个组件仍然得到同一个端口。
+- 如需使用“角色后缀法”，建议结合 `preferDigitCount: 5`（配置文件）或直接使用“角色前缀法”。
+
+### 微服务架构场景
+**原则**：使用命名约束 + 范围隔离
+
+1. **按功能模块划分端口段**
+   ```
+   用户服务：10000-10099
+   订单服务：10100-10199
+   支付服务：10200-10299
+   ```
+
+2. **使用项目前缀 + 功能标识**
+   ```
+   user-auth：10001
+   user-profile：10002
+   order-create：10101
+   order-query：10102
+   ```
+
+3. **预留端口段**
+   - 预留 20% 的端口空间用于扩展
+   - 使用高位端口作为备用（如 19990-19999）
+
+## 避免端口冲突的方法
+
+### 冲突预防
+1. **使用端口映射工具**
+   - 使用 `smart-port-allocation` Skill 生成基于项目名称的唯一端口
+   - 端口号与项目名称绑定，可预测且更少随机冲突（仍可能发生碰撞，需配合屏蔽列表/范围管理）
+
+2. **端口范围隔离**
+   - 不同类型服务使用不同端口段
+   - 开发/测试/生产环境使用不同范围
+
+3. **端口记录与追踪**
+   - 维护端口使用清单（见下文团队协作章节）
+
+### 冲突检测
+1. **启动前检查**
+   ```bash
+   # 检查端口是否被占用（Linux/Mac）
+   lsof -i :<port>
+
+   # 检查端口是否被占用（Windows）
+   netstat -ano | findstr :<port>
+   ```
+
+2. **定期审计**
+   - 定期扫描常用端口段（3000-3999, 8000-8999）
+   - 识别僵尸进程和未释放的端口
+
+3. **使用智能工具**
+   - 集成端口检测到启动脚本（PortKey 本身不检测端口占用）
+   - 冲突时将端口加入 `~/.port-key/config.json` 的 `blockedPorts`，再重新生成
+
+### 冲突解决
+1. **短期方案**：临时调整端口，记录变更
+2. **长期方案**：重新规划端口分配策略，统一调整
+3. **根本方案**：使用容器化技术（Docker）隔离端口空间
+
+## 团队协作与文档管理
+
+### 端口使用文档模板
+创建 `PORTS.md` 文件记录端口分配情况：
+
+```markdown
+# 项目端口分配清单
+
+## 项目概述
+- 示例项目：shop
+- 端口策略：角色前缀法（`fe-` / `api-` / `db-`）
+
+## 端口分配表
+
+| 服务名称 | 端口 | 说明 | 负责人 |
+|---------|-----|------|--------|
+| 前端商城 | 4326 | Vue3 应用 | 张三 |
+| 后端 API | 1082 | Node.js 服务 | 李四 |
+| 数据库   | 3526 | MongoDB | 王五 |
+| 缓存服务 | 4338 | Redis | 王五 |
+
+## 端口范围
+- 角色前缀法下端口可能分散，建议记录“具体端口”而不是强行划分连续端口段
+- 若使用顺序分配法，可将同一项目的一组端口规划为连续段（如 2690-2699）
+
+## 注意事项
+- 避免使用 3000, 8080 等常见端口
+- 新服务优先使用未分配端口
+- 端口变更需更新此文档
+```
+
+### 端口分配流程
+1. **新项目启动**
+   - 使用 `smart-port-allocation` Skill 生成端口
+   - 检查端口是否可用
+   - 更新 `PORTS.md` 文档
+
+2. **项目交接**
+   - 移交 `PORTS.md` 文档
+   - 说明端口分配策略和注意事项
+   - 交接后验证端口可用性
+
+3. **定期审计**
+   - 每季度检查端口使用情况
+   - 清理僵尸项目端口
+   - 优化端口分配策略
+
+## 常见问题排查
+
+### 问题 1：端口被占用
+**症状**：启动服务时提示 "Address already in use"
+
+**排查步骤**：
+1. 使用 `lsof -i :<port>` 查看占用进程
+2. 判断占用进程类型：
+   - 如果是同一服务的旧实例：kill 进程重新启动
+   - 如果是其他服务：选择新端口或调整其他服务
+3. 更新端口文档记录
+
+### 问题 2：端口映射不一致
+**症状**：不同机器上同一项目使用不同端口
+
+**原因**：
+- 未使用标准化端口分配工具
+- 团队成员各自随机选择端口
+- 使用了不同的用户配置（如 preferDigitCount、blockedPorts、minPort/maxPort）
+
+**解决方案**：
+1. 统一使用 `smart-port-allocation` Skill
+2. 将端口配置写入项目 `package.json` 或 `.env` 文件
+3. 纳入代码审查，确保端口配置正确
+4. 团队统一 `~/.port-key/config.json` 的关键配置（或在启动脚本中用 `PORTKEY_HOME` 指定同一份配置）
+
+### 问题 3：端口范围耗尽
+**症状**：可用端口用完，无法为新服务分配端口
+
+**解决方案**：
+1. 审计现有端口使用情况，清理僵尸服务
+2. 扩展端口范围（如从 3000-3999 扩展到 3000-4999）
+3. 使用容器化技术，通过端口映射复用端口
+
+### 问题 4：跨平台端口兼容性
+**症状**：Windows 和 Linux/macOS 端口行为不一致
+
+**解决方案**：
+1. 避免使用系统端口（0-1023）
+2. 使用 1024-65535 范围内的端口
+3. 在 CI/CD 中验证端口配置
+
+## 总结
+
+### 关键原则
+1. **可预测性**：端口分配应有规律可循，便于记忆
+2. **唯一性**：同一端口不应被多个服务占用
+3. **文档化**：所有端口分配都应记录在案
+4. **团队一致**：团队内部应使用统一的分配策略
+5. **自动化**：使用工具生成端口，减少人为错误
+
+### 推荐工作流
+1. 新项目启动 → 使用 Skill 生成端口
+2. 验证端口可用性 → 更新 PORTS.md
+3. 定期审计 → 优化端口分配策略
+4. 团队协作 → 保持文档同步
+
+### 工具推荐
+- **智能端口分配**：`smart-port-allocation` Skill
+- **端口检测**：`lsof`, `netstat`
+- **进程管理**：`kill`, `taskkill`
+- **容器隔离**：Docker, Docker Compose

package/skills/smart-port-allocation/references/port-key.md

@@ -0,0 +1,327 @@
+# PortKey 工具使用指南
+
+## 目录
+- [工具简介](#工具简介)
+- [安装与执行](#安装与执行)
+- [核心参数说明](#核心参数说明)
+- [使用示例](#使用示例)
+- [输出格式](#输出格式)
+- [高级用法](#高级用法)
+- [常见问题](#常见问题)
+
+## 工具简介
+
+PortKey 是一个基于键盘映射的端口生成工具，通过将项目名称的字母映射为数字，生成可记忆且不易冲突的端口号。
+
+### 核心原理
+- 使用标准 QWERTY 键盘布局，将字母映射到数字
+- 根据字母在键盘上的行列位置确定对应数字
+- 自动处理端口合法性验证（端口范围与屏蔽列表）
+- **名称处理**：长项目名称/中文名称的首字母提取由智能体或调用方完成
+
+### 键盘映射规则
+```
+1: qaz   2: wsx   3: edc   4: rfv   5: tgb
+6: yhn   7: ujm   8: ik    9: ol    0: p
+```
+
+示例：
+- `cfetch` → `c(3) f(4) e(3) t(5) c(3) h(6)` → `343536` → 默认输出 `3435`（取 4 位候选）
+
+### 项目名称处理规则
+- **短名称**（1-2 个单词或 ≤8 个字母）：直接使用
+  - `"dashboard"` → `"dashboard"`
+  - `"myapp"` → `"myapp"`
+- **长名称**（多个单词或 >8 个字母）：提取首字母
+  - `"我爱我家"`（Wǒ Ài Wǒ Jiā）→ `"wawj"`
+  - `"user authentication service"` → `"uas"`
+  - `"enterprise resource planning system"` → `"erps"`
+  - `"ecommerce payment gateway"` → `"epg"`
+- **混合语言**：自动识别中英文，提取拼音或英文字母首字母
+
+## 安装与执行
+
+### 使用 npx（推荐）
+无需预安装，直接使用 npx 自动下载和执行：
+
+```bash
+npx -y @lionad/port-key <project-name>
+```
+
+### 参数说明
+- `-y`: 自动确认，跳过下载确认提示
+- `@lionad/port-key`: npm 包名
+
+## 核心参数说明
+
+### 必需参数
+- **project-name**: 项目名称（必填）
+  - 支持字母和数字
+  - 自动转换为小写
+  - 推荐使用简短名称（1-8 个字母）以获得最佳效果
+  - 示例：`"myproject"`, `"dashboard"`, `"shop"`, `"wawj"`（"我爱我家"的首字母）
+  - **注意**：PortKey 工具本身不处理中文或长名称，首字母提取由智能体完成
+
+### 可选参数
+
+#### `--digits <count>` 或 `-d <count>`
+设置端口号的位数
+
+- **可选值**: 4, 5
+- **默认值**: 4
+- **说明**: 优先生成指定位数的端口号
+
+示例：
+```bash
+npx -y @lionad/port-key "myproject" --digits 4   # 生成 4 位端口
+npx -y @lionad/port-key "myproject" --digits 5   # 生成 5 位端口
+```
+
+#### `--lang <code>`
+设置输出语言
+
+- **可选值**: `en`, `cn`
+- **默认值**: `cn`
+- **说明**: 控制日志消息的语言
+
+示例：
+```bash
+npx -y @lionad/port-key "myproject" --lang en
+npx -y @lionad/port-key "myproject" --lang cn
+```
+
+#### `--map <object>`
+自定义键盘映射
+
+- **格式**: JSON 或 JS 对象字面量
+- **默认值**: 标准 QWERTY 映射
+- **说明**: 自定义字母到数字的映射关系
+
+示例：
+```bash
+npx -y @lionad/port-key "myproject" --map '{"1":"abc","2":"def"}'
+```
+
+## 使用示例
+
+### 基础用法
+```bash
+# 生成默认 4 位端口
+npx -y @lionad/port-key "myproject"
+# 输出: 7604
+
+# 生成 5 位端口（myproject → digits 760497335；5 位候选 76049 超出 65535 被拒，选中 60497）
+npx -y @lionad/port-key "myproject" --digits 5
+# 输出: 60497
+```
+
+### 首字母提取示例（智能体处理）
+```bash
+# 长项目名称：用户认证服务 → 提取 "uas"
+npx -y @lionad/port-key "uas"
+# 输出: 7120
+
+# 长项目名称：我爱我家 → 提取 "wawj"
+npx -y @lionad/port-key "wawj"
+# 输出: 2127
+
+# 长项目名称：Enterprise Resource Planning System → 提取 "erps"
+npx -y @lionad/port-key "erps"
+# 输出: 3402
+```
+**注意**：首字母提取由智能体完成，PortKey 工具只接收处理后的简短名称。
+
+### 端口范围与屏蔽列表（通过配置文件）
+PortKey CLI 不提供 `--min-port/--max-port/--blocked-ports` 参数；如需限制范围或屏蔽端口，请使用用户配置文件（见下文“配置文件”）。
+
+### 多组件项目
+```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
+```
+
+### 处理短项目名
+```bash
+# 短项目名会自动填充零
+npx -y @lionad/port-key "air" --digits 4
+# 输出: 1840
+
+# 长项目名截取指定位数
+npx -y @lionad/port-key "dashboard" --digits 4
+# 输出: 3126
+```
+
+### 处理长项目名（配合智能体）
+```bash
+# 智能体将长名称转换为首字母后调用
+# 例如："用户认证服务" → "uas"
+npx -y @lionad/port-key "uas"
+# 输出: 7120
+
+# 例如："电子商务支付网关" → "epg"
+npx -y @lionad/port-key "epg"
+# 输出: 3050
+
+# 例如："Customer Relationship Management System" → "crms"
+npx -y @lionad/port-key "crms"
+# 输出: 3472
+```
+
+## 输出格式
+
+### 标准输出
+默认情况下，PortKey 输出生成的端口号（纯数字）：
+
+```bash
+$ npx -y @lionad/port-key "myproject"
+# 输出 7604
+```
+
+首次运行且本机没有配置文件时，CLI 可能会在 stderr 打印一段提示信息；stdout 仍然只输出端口号，脚本中建议用命令替换读取 stdout（如 `PORT=$(...)`）。
+
+### 详细输出（MCP 模式）
+当作为 MCP server 使用时（`@lionad/port-key-mcp`），会返回 JSON 格式的详细信息：
+
+```json
+{
+  "digits": "760497335",
+  "port": 7604,
+  "rejectedCandidates": []
+}
+```
+
+字段说明：
+- `digits`: 映射后的数字序列
+- `port`: 最终选择的端口号
+- `rejectedCandidates`: 被拒绝的候选端口列表（如有）
+
+## 高级用法
+
+### 配置文件
+PortKey 会从 `~/.port-key/config.json` 读取用户配置：
+
+```json
+{
+  "preferDigitCount": 5,
+  "paddingZero": true,
+  "blockedPorts": [3000, 3001, 6666],
+  "minPort": 1024,
+  "maxPort": 49151
+}
+```
+
+也可以通过环境变量 `PORTKEY_HOME` 指定配置目录（目录下仍使用 `.port-key/config.json`）。
+
+### MCP Server 集成
+将 PortKey 作为 MCP server 使用：
+
+```json
+{
+  "mcpServers": {
+    "port-key": {
+      "command": "npx",
+      "args": ["@lionad/port-key-mcp"]
+    }
+  }
+}
+```
+
+### 批量生成端口
+在 Shell 脚本中批量生成端口：
+
+```bash
+#!/bin/bash
+projects=("project-a" "project-b" "project-c")
+
+for project in "${projects[@]}"; do
+  port=$(npx -y @lionad/port-key "$project")
+  echo "$project: $port"
+done
+```
+
+### 集成到启动脚本
+将端口生成集成到项目启动脚本：
+
+```bash
+#!/bin/bash
+PROJECT_NAME="myapp"
+
+# 生成端口
+PORT=$(npx -y @lionad/port-key "$PROJECT_NAME")
+
+# 启动服务
+export PORT=$PORT
+npm start
+```
+
+## 常见问题
+
+### Q1: 为什么生成的端口不在期望的范围内？
+**A**: 检查以下几点：
+1. 检查 `~/.port-key/config.json` 中的 `minPort/maxPort` 配置（如有）
+2. 检查 `blockedPorts` 是否屏蔽了范围内的端口
+3. 确认期望范围在 1024-65535 之间（0-1023 始终被屏蔽）
+
+### Q2: 短项目名生成的端口位数不足？
+**A**: 使用 `--digits` 参数指定位数，工具会自动填充零：
+```bash
+npx -y @lionad/port-key "air" --digits 4
+```
+
+### Q3: 长项目名称如何处理？
+**A**: 智能体会自动处理长项目名称：
+- **中文长名称**：提取拼音首字母，如 "我爱我家" → "wawj"
+- **英文长名称**：提取单词首字母，如 "User Authentication Service" → "uas"
+- 也可以手动指定简短名称，如使用 "uas" 代替 "用户认证服务"
+- 首字母提取后，由智能体调用 PortKey 生成端口
+
+### Q4: 如何验证生成的端口是否可用？
+**A**: 使用以下命令检查端口占用：
+```bash
+# Linux/Mac
+lsof -i :<port>
+
+# Windows
+netstat -ano | findstr :<port>
+```
+
+### Q5: 能否自定义键盘映射？
+**A**: 可以使用 `--map` 参数自定义：
+```bash
+npx -y @lionad/port-key "myproject" --map '{"1":"abc","2":"def"}'
+```
+
+### Q6: 多组件项目如何分配端口？
+**A**: 推荐两种方式：
+1. **角色前缀法**：`fe-myapp`, `api-myapp`, `db-myapp`
+2. **顺序分配法**：基础端口、基础+1、基础+2
+
+详细策略见 [port-best-practices.md](port-best-practices.md)
+
+### Q7: 生成的端口与现有服务冲突怎么办？
+**A**: PortKey 不检测端口占用；请先用系统命令确认冲突端口，然后将冲突端口加入 `~/.port-key/config.json` 的 `blockedPorts` 后重试（或换用不同的项目名/角色前缀）。
+
+### Q8: 如何在团队中统一端口分配？
+**A**: 建议遵循以下步骤：
+1. 使用相同的工具和参数
+2. 在文档记录端口分配
+3. 使用版本管理端口配置
+4. 定期审计端口使用情况
+5. **统一首字母规则**：团队内部统一长项目名称的首字母提取规则
+
+## 相关文档
+- [端口分配最佳实践](port-best-practices.md)：详细的端口分配策略和团队协作指南
+- PortKey GitHub：https://github.com/Lionad-Morotar/port-key