back
loading skill details...
NexAPI 工具类接口调用。
--- name: NexAPI description: NexAPI 工具类接口调用。 --- ## NexAPI Skill(Production) 面向 NexAPI(`api.avrinbai.cn`)的高效调用技能,目标是 **少网络请求、少输出、少 token 消耗**。 本技能的接口目录 **仅来自**: - `GET /api/health/openclaw`(接口目录/基础信息;可包含 `docs`) 不做页面解析,不依赖本地 SQL。 ## 核心原则(必须遵守) 1. **直达优先** - 能确定要调用的接口 → 直接 `call` - **禁止** 无意义 `list` 2. **懒加载** - 不主动拉接口详情(除非必要) - 不主动全量输出 3. **缓存优先** - 有缓存 → 不请求网络 - 仅在必要时 `--refresh` 或 `ttl` 过期后刷新 4. **低输出** - 默认输出为精简结构(用于降低 token) - 需要完整响应才使用 `--verbose` ## 执行器工作流(龙虾必读 / SOP) ### 0) 意图识别(最高优先级) 若用户意图可直接映射到常用接口,**跳过** `list/init`,直接调用(示例映射,可按需扩展): | 用户意图 | 建议接口 | |---|---| | 视频/图集无水印解析 | `video-no-watermark-v2` | | IP 查询 | `ip-location` | | 历史上的今天 | `history-today` | | 手机号归属地 | `phone-area` | | 二维码生成 | `qrcode` | 命中后直接执行: ```bash python3 scripts/nexapi.py call ip-location ip=8.8.8.8 ``` ### 1) Key 检查与持久化 先检查 Key 状态: ```bash python3 scripts/nexapi.py auth status ``` 未配置则引导用户设置(会写入本地配置文件,不回显输入): ```bash python3 scripts/nexapi.py auth set ``` 说明: - **优先级**:环境变量 `NEXAPI_API_KEY` > 本地配置文件 `nexapi_RhJ4W/.nexapi_config.json` - **安全**:Key **不会**写进 `scripts/nexapi.py`(避免发布泄露) ### 2) 缓存检查(仅必要时初始化/刷新) 满足以下条件才建议执行 `init`: - 首次使用(无缓存) - 需要切换缓存策略/TTL - 或明确需要刷新目录(配合 `--refresh`) 推荐初始化(写入缓存策略,并拉取目录): ```bash python3 scripts/nexapi.py init --refresh --policy=ttl --ttl=1800 ``` 强约束: - **禁止** 每次任务都 `init` - 仅在 “确实需要目录且缓存不可用/过期” 时才初始化或刷新 ### 3) 接口选择(仅在无法确定接口时) 只有在无法确定接口名时,才执行: ```bash python3 scripts/nexapi.py list ``` 输出约束(执行器侧): - 返回给用户时只保留必要信息(例如:接口名 + 一句用途) - **禁止** 直接转发整份长列表(除非用户明确要看全部) ### 4) 参数确认(必要时) 若用户参数不明确: - 优先补问用户(不要盲猜) - 允许先用最小参数尝试一次调用,根据返回再补齐 ### 5) 执行调用(直达) ```bash python3 scripts/nexapi.py call <api> k=v k2=v2 ``` 也支持简写: ```bash python3 scripts/nexapi.py <api> k=v ``` ### 6) 输出控制(强制) - 默认:输出精简结构(降低 token) - 需要完整响应时才使用: ```bash python3 scripts/nexapi.py call <api> k=v --verbose ``` ## 适用场景 - 查询当前可用接口目录 - 调用工具类、数据类、内容类、开发运维类接口 - 以低输出开销执行常规调用 - 在本地按策略缓存接口目录,减少重复拉取 ## 前置要求 1. Python 3 可用 2. 已配置 API Key(推荐写入本地配置文件,或使用环境变量) 3. 不配置API key部分接口无法正常使用 推荐(写入本地配置文件,避免上下文丢失/环境变量不持久): ```bash python3 scripts/nexapi.py auth set python3 scripts/nexapi.py auth status ``` 环境变量方式(可选): ```bash export NEXAPI_API_KEY="nex_xxx" ``` PowerShell: ```powershell $env:NEXAPI_API_KEY="nex_xxx" ``` ## 初始化 首次使用执行一次初始化: ```bash python3 scripts/nexapi.py init --refresh --policy=ttl --ttl=1800 ``` 初始化行为: - 拉取 `GET /api/health/openclaw?sort=hot` 写入缓存(包含 `docs` 字段) - 写入接口缓存 - 写入本地策略配置 ## 缓存策略 - `manual`:只读缓存,不自动刷新 - `ttl`:缓存过期后自动刷新(推荐) - `always`:每次命令都刷新 本地文件(默认): - 接口缓存:`nexapi_RhJ4W/.nexapi_apis_cache.json` - 策略配置:`nexapi_RhJ4W/.nexapi_config.json` ## 常用命令 ```bash # Key 管理 python3 scripts/nexapi.py auth status python3 scripts/nexapi.py auth set # 列出接口 python3 scripts/nexapi.py list python3 scripts/nexapi.py list --refresh # 调用接口(简写) python3 scripts/nexapi.py ip-location ip=8.8.8.8 # 调用接口(显式) python3 scripts/nexapi.py call ip-location ip=8.8.8.8 # 调试模式:输出完整响应 python3 scripts/nexapi.py call ip-location ip=8.8.8.8 --verbose # 缓存管理 python3 scripts/nexapi.py cache status python3 scripts/nexapi.py cache refresh python3 scripts/nexapi.py cache clear ``` ## 输出约定 - 默认输出为精简结构(低开销) - `--verbose` 输出完整响应体 - 二进制接口(如图片)默认返回元信息而非原始二进制 ## 行为约束 - 接口目录仅使用 `/api/health/openclaw` - 目录排序固定使用 `sort=hot` - 健康接口不可用时不降级页面抓取 健康接口异常时的策略: - 有缓存:优先使用缓存,保证可用 - 无缓存:返回失败并提示执行 `init --refresh` ## 可选环境变量 - `NEXAPI_HEALTH_PATH`:健康接口路径(默认 `/api/health/openclaw`) - `NEXAPI_CACHE_FILE`:自定义缓存文件路径 - `NEXAPI_CONFIG_FILE`:自定义配置文件路径
don't have the plugin yet? install it then click "run inline in claude" again.