alapi

ALAPI 接口对接助手。帮助开发者搜索 ALAPI 接口、读取 ALAPI 文档、提取参数、生成 ALAPI 对接代码，并在用户明确提供 token 且确认后调用 ALAPI 接口。当用户提到 "ALAPI"、"alapi.cn"、ALAPI 文档 URL、ALAPI token、ALAPI 接口示例、或希望接...

Security Scan

The skill's code, docs, and runtime instructions match its stated purpose (searching ALAPI docs, generating code, and optionally calling ALAPI when the user supplies a token); nothing requests unrelated credentials or installs arbitrary code.

Purpose & Capability

Name/description describe ALAPI integration; included CLI script and templates implement exactly that. The skill does not request unrelated credentials or tools. Minor note: registry metadata lists no required env vars while the skill supports an optional ALAPI_TOKEN — this is reasonable (token is optional) but slightly inconsistent with a strict 'required' list.

Instruction Scope

SKILL.md accurately describes the CLI usage and limits scope to ALAPI operations (search/openapi/explore/call). It explicitly forbids echoing tokens and limits real calls to cases where the user explicitly requests a live call and provides a token. The instructions do not ask the agent to read unrelated system files or exfiltrate data.

Install Mechanism

There is no install spec — this is an instruction-only skill with included Python script and tests. No downloads or archive extraction are performed by the skill itself, so install risk is low. The README suggests an optional 'npx skills add' install, but that's ordinary package acquisition and not part of the skill's runtime.

Credentials

The only credential surface is ALAPI token usage (ALAPI_TOKEN or explicit --token). That is proportional to the skill's purpose; no unrelated secrets or broad environment access are requested. The SKILL.md/code enforce explicit-token precedence and avoid echoing tokens.

Persistence & Privilege

Skill does not request always:true, does not modify other skills or global agent configuration, and has no persistent privilege escalation behavior. Agent autonomy remains platform-default and is not compounded by special privileges.

Assessment

This skill appears internally consistent and implements exactly what it claims: searching ALAPI, reading OpenAPI/docs, generating example code, and only performing live calls when you explicitly ask and provide a token. Before installing: (1) only provide your ALAPI token when you explicitly ask the agent to perform a live call; avoid pasting tokens into free-form chat messages; (2) review the included scripts (scripts/alapi.py) locally if you want extra assurance — they perform plain HTTPS requests to v3.alapi.cn and honor ALAPI_TOKEN or --token; (3) prefer installing from the official/expected repository URL instead of an unknown source; (4) if you plan to allow autonomous agent actions, remember a live-call will use any ALAPI_TOKEN in the environment or an explicit token you pass — ensure that environment variable is scoped appropriately. Overall: coherent and proportionate, but exercise normal caution with any token you hand to an agent.

ALAPI 接口对接助手

Overview

使用这个 skill 处理 ALAPI 平台的接口检索、文档读取、参数提取、代码生成和按需真实调用。

ALAPI 的关键平台约定：

{
  "success": true,
  "code": 200,
  "message": "success",
  "data": { ... },
  "request_id": "xxx",
  "time": 1700000000
}

• Base URL: https://v3.alapi.cn
• 文档页: https://www.alapi.cn/api/{id}/introduction
• Token 创建: https://www.alapi.cn/dashboard/data/token
• 所有接口都要传 token 参数，通常放在 GET query 或 POST body
• token 优先级：显式 --token 高于环境变量 ALAPI_TOKEN

所有接口数据获取通过 alapi.py 完成。脚本零依赖，优先用它，不要手工拼 ALAPI 的内部文档接口。

不要假设当前工作目录一定是 skill 仓库根目录，也不要写死旧的仓库内相对路径。优先从当前 skill 目录推导脚本路径：

SKILL_DIR=/absolute/path/to/alapi
SCRIPT="$SKILL_DIR/scripts/alapi.py"
python3 "$SCRIPT" --json search "IP查询"

Quick Workflow

用户给了 ALAPI 文档 URL

从 URL 中提取 api/{id}，然后直接读取 OpenAPI：

python3 "$SCRIPT" --json openapi {id}

用户只描述了功能

先搜索，再决定是否继续：

python3 "$SCRIPT" --json search "用户描述的关键词"

如果搜索结果为空，不要立刻放弃。按这个顺序做关键词回退：

1. 去掉修饰词，只保留核心名词
2. 改用更短的同义词或上位词重新搜索
3. 对组合词拆词搜索，例如先搜“视频”，再搜“解析”，再搜“短视频”

只有在 2 到 3 轮回退后仍然没有结果时，才告诉用户当前没有匹配接口。

如果命中多个结果，先列出 2 到 5 个候选，不要擅自选一个。用户确认后再读取 OpenAPI：

python3 "$SCRIPT" --json openapi {id}

用户要浏览全部接口

python3 "$SCRIPT" --json explore

用户要代码，不要真实请求

优先读取 openapi，再从结果中提取：

• 请求路径
• 请求方法
• 必填参数
• 可选参数
• 响应结构
• 文档链接 https://www.alapi.cn/api/{id}/introduction

如果当前只是候选阶段，不要直接给“最终确定版代码”。最多只给：

• 候选列表
• 候选差异
• 确认后会生成哪种语言的代码

除非只有单一明确命中，或者用户已经确认了具体接口。

用户明确要求真实调用

仅在用户明确要求“直接调用/测试接口”且已提供 token 时执行：

python3 "$SCRIPT" --json call {path} --token {用户的token} --param key=value

如果用户没有 token，引导去创建：

请先在 https://www.alapi.cn/dashboard/data/token 创建 API Token。

如果用户没有显式给出 token，但环境里已经有 ALAPI_TOKEN，可以直接使用；如果两者都存在，始终以显式 token 为准。

Critical Rules

• 默认优先做只读操作：search、detail、openapi、explore
• 优先使用 --json，再基于 JSON 结果生成自然语言说明
• 不要手工猜 ALAPI 文档接口路径，优先使用 scripts/alapi.py
• 不要假设 cwd 一定在 skill 根目录
• 不要在最终回复中回显用户的真实 token
• 支持从环境变量 ALAPI_TOKEN 读取 token，但显式 --token 优先级最高
• 搜索结果不唯一时，先列候选，不要擅自决定接口
• 搜索 0 结果时，先做关键词回退，不要第一步就判定不存在
• 用户只要“文档”或“代码示例”时，不要真实调用接口
• 候选未确认前，不要输出“最终定稿代码”；先输出候选和差异
• 如果用户没有提供足够参数，不要猜值，明确指出缺失参数
• 如果 OpenAPI 没有写清楚，不要补脑生成不存在的参数名、默认值或响应字段
• call 失败时，优先保留平台原始错误结构，再结合错误码给出下一步建议
• 对需要真实参数才能调用的接口，如果用户未给足参数，先说明缺什么，不要猜值

Command Reference

命令	用途
search <keyword>	搜索接口
explore	浏览全部接口
detail <id>	读取接口基础信息
openapi <id>	读取 OpenAPI 规格
call <path>	发起真实请求
--json	输出稳定 JSON，供 agent 继续处理

Code Generation Rules

• Token 占位符统一使用 ALAPI_TOKEN
• 默认生成最小可运行版本，不要过度封装
• 保留响应解析和错误处理逻辑，覆盖 success/code/message/data/request_id/time
• Python 用 requests；JS/TS 用 fetch；PHP 用 curl；Go 用 net/http
• 不引入非必要依赖
• 如果用户在服务端项目中接入，优先建议把 token 放到环境变量或服务端配置，不要放前端
• 如果参数或方法来自 OpenAPI，就按 OpenAPI 生成；如果 OpenAPI 缺失，不要伪造
• 详细模板见 code-examples.md

前端/后端分层规则：

• 浏览器端或 Next.js Client Component 默认不要直连 ALAPI
• Node.js 服务端、PHP 后端、Python 后端可以直接读取 ALAPI_TOKEN
• 如果用户说“前端项目接入”，优先给服务端代理方案，除非用户明确说明是在纯后端环境运行

Reporting Template

当文档不完全、存在候选、或存在不确定字段时，优先按这个结构输出：

已确认

• 从 OpenAPI 或真实调用中明确确认的接口路径、方法、参数、返回字段

待确认

• 当前还需要用户确认的候选接口或业务选择

不要假设

• 文档未写清楚，因此不能主动编造的参数、默认值、返回字段或平台行为

Live Call Rules

执行真实调用后，优先保留这些信息：

• 接口名和路径
• token 来源：显式 --token 还是环境变量 ALAPI_TOKEN
• 请求里实际传入的业务参数
• 原始响应中的关键字段：success、code、request_id、data 摘要

不要保留这些信息：

• token 原文
• 不必要的敏感上下文
• 会导致凭证泄露的命令历史

Real Usage Examples

• 帮我查一下 IP: 8.8.8.8 先定位 IP 查询接口，再在用户明确要求真实调用且 token 可用时执行查询，或先给出查询代码。

• 帮我生成视频解析的代码 先搜索“视频解析”相关接口，若命中多个候选先列给用户确认，再基于对应 OpenAPI 生成最小可运行代码。

Failure Handling

code	含义	建议
200	成功	—
401	Token 无效或未传	检查 token
403	套餐不含此接口	升级套餐
422	参数校验失败	优先指出缺失或格式错误的参数
429	频率超限	降频、加缓存，必要时延迟重试
500	服务端错误	保留原始错误，建议重试

如果搜索结果为空，直接说明没有匹配接口，并提示改用更明确的关键词。

如果 openapi 缺失但 detail 或文档页存在，明确告诉用户规范不完整，并退回基础信息 + 文档链接。