用途
UniFi 网络监控技能用于通过 UniFi Controller API 监控和查询 UniFi 网络基础设施，覆盖 USG 路由器/网关、Cloud Key Gen 2 控制器主机以及接入点、交换机等设备。资料中列出的用户环境为 UniFi Security Gateway（USG3）、Cloud Key Gen 2，接入点和交换机标注为“待发现”。
主要能力
该技能以只读查询为主，提供以下命令：
site-status：显示整体网络健康状况、控制器版本和站点信息。devices：列出所有 UniFi 设备（USG、AP、交换机）及其状态、运行时间和固件。clients：列出所有已连接客户端的主机名、IP、MAC、连接类型和带宽使用。health：显示所有设备的健康指标，包括 CPU、内存和运行时间。alerts：显示最近的网络告警和事件。wan：显示 WAN 连接状态、公网 IP、速率和运行时间。bandwidth：显示按客户端和整体网络的当前带宽使用。
使用方式
所有命令均通过 UniFi CLI 包装器执行，运行形式为：
bun ~/.claude/skills/Unifi/unifi-cli.ts <command>
首次使用需安装依赖并创建配置文件：
cd ~/.claude/skills/Unifi && bun install
cp ~/.claude/skills/Unifi/config.example.json ~/.claude/skills/Unifi/config.json
然后编辑 config.json，设置 Cloud Key 的 IP 地址、UniFi Controller 的用户名和密码；站点通常为 default，多站点环境除外。配置文件结构示例：
{
"controller": {
"host": "192.168.1.x",
"port": 8443,
"username": "admin",
"password": "your-password",
"site": "default"
}
}
完成后可运行 bun ~/.claude/skills/Unifi/unifi-cli.ts site-status 测试连接。
面向 AI 的使用流程：先检查 ~/.claude/skills/Unifi/config.json 是否存在，不存在则引导用户完成设置；再按问题选择命令，例如网络状态用 site-status、在线用户用 clients、设备健康用 health 或 devices、互联网状态用 wan、近期问题用 alerts；最后将结果整理为可读表格，突出高带宽、离线设备和告警等重要指标，并给出上下文解释。
适用场景
资料给出的示例查询包括：谁连接到了网络（clients）、互联网是否正常（wan）、网络出了什么问题（alerts 加 health）、网络运行状况如何（site-status 加 devices）。
限制与安全注意事项
- 仅支持只读操作，不进行配置更改。
- 需要本地网络访问 Cloud Key，并依赖 UniFi Controller 在线且可访问。
- 部分功能需要特定的 UniFi 设备类型。
- 配置文件包含凭据，绝不能提交到公开仓库；该目录应加入
.gitignore。 - 通过本地网络连接 Cloud Key，默认仅执行安全查询。
故障排查
- 连接失败：确认 Cloud Key 在线可访问、检查
config.json中的 IP、确认用户名密码正确、确认 8443 端口（HTTPS 到控制器）可访问。 - 认证失败：核对用户名密码、检查账户是否具备管理员权限、尝试用相同凭据登录控制器 Web UI。
- 命令未找到：运行
cd ~/.claude/skills/Unifi && bun install，用bun --version确认 bun 已安装，用ls -la ~/.claude/skills/Unifi/unifi-cli.ts检查文件存在。
暂未提供的功能
资料将端口转发管理、DHCP 租约信息、深度包检测（DPI）统计、访客网络管理、WiFi 配置查询、历史带宽趋势和告警通知列为未来可能的增强项，当前版本未提供这些功能。