Alapi

__pycache__/
*.pyc

interface:
  display_name: "ALAPI 接口助手"
  short_description: "搜索 ALAPI 文档、提取参数并生成可直接使用的对接代码"
  default_prompt: "Use $alapi to find the right ALAPI endpoint, summarize its parameters, and generate a working integration example."

{
  "skill_name": "alapi",
  "evals": [
    {
      "id": 1,
      "prompt": "这是 ALAPI 的接口文档链接：https://www.alapi.cn/api/23/introduction 。别直接发请求，先帮我看一下这个接口是做什么的，需要哪些参数，返回结构大概是什么，再顺手给我一个 Python 调用示例。",
      "expected_output": "识别出文档 URL 中的接口 ID，读取对应 OpenAPI 或接口信息，概述接口用途、参数和响应结构，并生成最小可运行的 Python 示例代码。",
      "files": [],
      "expectations": [
        "The response identifies the ALAPI interface ID from the provided documentation URL.",
        "The response summarizes the endpoint purpose, required parameters, and response structure.",
        "The response includes a Python example for calling the ALAPI endpoint.",
        "The response does not perform or claim a live API call."
      ]
    },
    {
      "id": 2,
      "prompt": "我想接一个 ALAPI 的 IP 查询能力，目标 IP 是 8.8.8.8。先不要真的请求接口，帮我找到合适的接口，然后给我一份 cURL 和 Node.js 的调用示例，token 用环境变量 ALAPI_TOKEN。",
      "expected_output": "通过搜索找到合适的 IP 查询接口，在不发起真实调用的前提下，给出 cURL 和 Node.js 示例，并使用 ALAPI_TOKEN 作为 token 读取方式。",
      "files": [],
      "expectations": [
        "The response selects or recommends an ALAPI IP lookup endpoint.",
        "The response includes a cURL example that uses ALAPI_TOKEN rather than a hard-coded token literal.",
        "The response includes a JavaScript or Node.js example for the same endpoint.",
        "The response does not claim to have queried IP 8.8.8.8 live."
      ]
    },
    {
      "id": 3,
      "prompt": "帮我找 ALAPI 里跟视频解析相关的接口，并直接给我代码。如果有多个候选，不要替我做决定，先把候选列出来并说明差异。",
      "expected_output": "如果“视频解析”直接搜索无结果，应主动做关键词回退或拆词搜索；找到候选后应列出候选和差异，而不是直接假定某个接口；在用户确认前不应输出最终定稿代码。",
      "files": [],
      "expectations": [
        "If the original keyword search returns no result, the response falls back to better search terms instead of stopping immediately.",
        "If multiple candidate endpoints exist, the response presents multiple options instead of assuming one.",
        "The response explains at least one meaningful difference between candidates or explicitly states what is unknown.",
        "Before the user confirms a candidate, the response does not output a final committed code sample for a single endpoint."
      ]
    },
    {
      "id": 4,
      "prompt": "我已经有 ALAPI_TOKEN 环境变量了，帮我测试一下 hitokoto 接口，参数 type=a。你可以直接调用，但不要在最终结果里泄露我的 token。除了返回结果，也告诉我你是怎么拿到 token 的优先级规则。",
      "expected_output": "在允许真实调用的情况下使用环境变量中的 ALAPI_TOKEN 发起请求，不回显 token，并说明显式 token 高于环境变量的优先级规则。",
      "files": [],
      "expectations": [
        "The run uses a live API call only because the prompt explicitly allows it.",
        "The response does not print or expose the raw token value.",
        "The response mentions that explicit token input overrides ALAPI_TOKEN from the environment.",
        "The response includes the returned API result or a faithful summary of it."
      ]
    },
    {
      "id": 5,
      "prompt": "给我一个 ALAPI 的视频解析接口接入方案，后端是 PHP，前端是 Next.js。不要把 token 放到前端。先说明应该怎么分层，再给我一份后端最小可运行代码示例。假设文档里如果没写清楚参数，就明确告诉我哪里不确定。",
      "expected_output": "给出安全的服务端接入方案，强调不要在前端暴露 token，提供 PHP 后端最小示例，并在 OpenAPI 不清晰时明确标出不确定点。",
      "files": [],
      "expectations": [
        "The response recommends keeping the ALAPI token on the server side rather than in Next.js client code.",
        "The response includes a PHP example for the backend integration.",
        "The response distinguishes confirmed parameters from unknown or undocumented details.",
        "The response does not fabricate missing parameter names or default values."
      ]
    }
  ]
}

#!/usr/bin/env python3
"""
ALAPI CLI - 接口搜索、查询文档、直接调用的命令行工具。

用法:
    python alapi.py search <keyword>           搜索接口
    python alapi.py explore                    浏览全部接口（按分类）
    python alapi.py detail <id>                获取接口基本信息
    python alapi.py openapi <id>               获取接口 OpenAPI Spec
    python alapi.py call <path> [options]       调用接口

调用接口选项:
    --token <token>      API Token（最高优先级）
    --param <key=value>  请求参数（可多次使用）
    --method <GET|POST>  请求方法，默认 GET

环境变量:
    ALAPI_TOKEN          未指定 --token 时使用

示例:
    python alapi.py search "IP"
    python alapi.py openapi 27
    python alapi.py call ip --token ALAPI_TOKEN --param ip=8.8.8.8
    ALAPI_TOKEN=your_token python alapi.py call hitokoto --param type=a
"""

import json
import os
import sys
import urllib.error
import urllib.parse
import urllib.request

BASE_URL = "https://v3.alapi.cn"
OUTPUT_JSON = False


def _request(url, method="GET", data=None, headers=None):
    """发起 HTTP 请求，返回解析后的 JSON 或原始文本。"""
    if headers is None:
        headers = {}
    headers.setdefault("User-Agent", "ALAPI-CLI/1.0")

    body = None
    if data and method == "POST":
        body = json.dumps(data).encode("utf-8")
        headers["Content-Type"] = "application/json"
    elif data and method == "GET":
        url = url + ("&" if "?" in url else "?") + urllib.parse.urlencode(data)

    req = urllib.request.Request(url, data=body, headers=headers, method=method)
    try:
        with urllib.request.urlopen(req, timeout=15) as resp:
            raw = resp.read().decode("utf-8")
    except urllib.error.HTTPError as e:
        raw = e.read().decode("utf-8")
        try:
            err = json.loads(raw)
            print(json.dumps(err, indent=2, ensure_ascii=False))
        except json.JSONDecodeError:
            print(f"HTTP {e.code}: {raw}", file=sys.stderr)
        sys.exit(1)
    except urllib.error.URLError as e:
        print(f"网络错误: {e.reason}", file=sys.stderr)
        sys.exit(1)

    try:
        return json.loads(raw)
    except json.JSONDecodeError:
        return raw


def _emit(payload, render_text=None):
    """根据输出模式返回 JSON 或文本。"""
    if OUTPUT_JSON:
        print(json.dumps(payload, indent=2, ensure_ascii=False))
        return

    if render_text is None:
        print(json.dumps(payload, indent=2, ensure_ascii=False))
        return

    print(render_text(payload))


def _search_payload(result):
    payload = {
        "command": "search",
        "success": False,
        "keyword": None,
        "count": 0,
        "items": [],
        "raw": result,
    }
    if isinstance(result, dict) and result.get("data"):
        apis = result["data"].get("list", [])
        payload["success"] = True
        payload["count"] = len(apis)
        payload["items"] = [
            {
                "id": api.get("id"),
                "name": api.get("name"),
                "description": api.get("description"),
                "doc_url": f"https://www.alapi.cn/api/{api.get('id')}/introduction",
            }
            for api in apis
        ]
    return payload


def _render_search(payload):
    if not payload["items"]:
        return "未找到匹配的接口。"

    lines = [f"找到 {payload['count']} 个接口:\n"]
    for api in payload["items"]:
        lines.append(f"  ID: {api.get('id', '')}  | {api.get('name', '')}")
        desc = api.get("description")
        if desc:
            lines.append(f"           {desc[:80]}")
        lines.append(f"           文档: {api.get('doc_url')}")
        lines.append("")
    return "\n".join(lines).rstrip()


def _explore_payload(result):
    payload = {
        "command": "explore",
        "success": False,
        "categories": [],
        "groups": [],
        "raw": result,
    }
    if isinstance(result, dict) and result.get("data"):
        data = result["data"]
        payload["success"] = True
        payload["categories"] = data.get("categories", [])
        payload["groups"] = data.get("apis", [])
    return payload


def _render_explore(payload):
    if not payload["success"]:
        return json.dumps(payload["raw"], indent=2, ensure_ascii=False)

    lines = ["=== ALAPI 接口分类 ===\n"]
    for cat in payload["categories"]:
        lines.append(f"  {cat.get('name', '')} ({cat.get('apis_count', 0)} 个)")
    lines.append("")
    for group in payload["groups"]:
        lines.append(f"【{group.get('category', '')}】")
        for api in group.get("apis", []):
            lines.append(f"  ID: {api.get('id', '')}  | {api.get('name', '')}")
        lines.append("")
    return "\n".join(lines).rstrip()


def _detail_payload(api_id, result):
    return {
        "command": "detail",
        "success": isinstance(result, dict) and bool(result.get("data")),
        "api_id": api_id,
        "data": result.get("data") if isinstance(result, dict) else None,
        "raw": result,
    }


def _openapi_payload(api_id, result):
    return {
        "command": "openapi",
        "success": isinstance(result, dict),
        "api_id": api_id,
        "spec": result if isinstance(result, dict) else None,
        "raw": result,
    }


def _call_payload(path, method, result):
    return {
        "command": "call",
        "success": isinstance(result, dict) and bool(result.get("success")),
        "path": path,
        "method": method,
        "response": result,
    }


def _resolve_token(explicit_token):
    """解析 token，显式参数优先，其次环境变量。"""
    if explicit_token:
        return explicit_token
    return os.environ.get("ALAPI_TOKEN")


def cmd_search(keyword):
    """搜索接口。"""
    url = f"{BASE_URL}/frontend/api/search"
    result = _request(url, data={"keywords": keyword})
    payload = _search_payload(result)
    payload["keyword"] = keyword
    _emit(payload, _render_search)


def cmd_explore():
    """浏览全部接口（按分类）。"""
    url = f"{BASE_URL}/frontend/api/explore"
    result = _request(url)
    _emit(_explore_payload(result), _render_explore)


def cmd_detail(api_id):
    """获取接口基本信息。"""
    url = f"{BASE_URL}/frontend/api/find/{api_id}"
    result = _request(url)
    payload = _detail_payload(api_id, result)
    _emit(payload["data"] if not OUTPUT_JSON and payload["success"] else payload)


def cmd_openapi(api_id):
    """获取接口 OpenAPI Spec。"""
    url = f"{BASE_URL}/openapi/{api_id}.json"
    result = _request(url)
    payload = _openapi_payload(api_id, result)
    _emit(payload["spec"] if not OUTPUT_JSON and payload["success"] else payload)


def cmd_call(path, token, params, method="GET"):
    """直接调用接口。"""
    token = _resolve_token(token)
    if not token:
        print("错误: 调用接口必须提供 --token 参数，或设置环境变量 ALAPI_TOKEN。", file=sys.stderr)
        print("创建 Token: https://www.alapi.cn/dashboard/data/token", file=sys.stderr)
        sys.exit(1)

    url = f"{BASE_URL}/api/{path}"
    params["token"] = token

    if method == "POST":
        result = _request(url, method="POST", data=params)
    else:
        result = _request(url, method="GET", data=params)
    payload = _call_payload(path, method, result)
    _emit(result if not OUTPUT_JSON else payload)


def main():
    global OUTPUT_JSON

    args = sys.argv[1:]
    if "--json" in args:
        OUTPUT_JSON = True
        args = [arg for arg in args if arg != "--json"]

    if len(args) < 1:
        print(__doc__)
        sys.exit(0)

    command = args[0].lower()

    if command == "search":
        if len(args) < 2:
            print("用法: python alapi.py search <keyword>", file=sys.stderr)
            sys.exit(1)
        cmd_search(args[1])

    elif command == "explore":
        cmd_explore()

    elif command == "detail":
        if len(args) < 2:
            print("用法: python alapi.py detail <id>", file=sys.stderr)
            sys.exit(1)
        cmd_detail(args[1])

    elif command == "openapi":
        if len(args) < 2:
            print("用法: python alapi.py openapi <id>", file=sys.stderr)
            sys.exit(1)
        cmd_openapi(args[1])

    elif command == "call":
        if len(args) < 2:
            print("用法: python alapi.py call <path> --token <token> [--param k=v ...]", file=sys.stderr)
            sys.exit(1)
        path = args[1]
        token = None
        params = {}
        method = "GET"
        i = 2
        while i < len(args):
            arg = args[i]
            if arg == "--token" and i + 1 < len(args):
                token = args[i + 1]
                i += 2
            elif arg == "--param" and i + 1 < len(args):
                kv = args[i + 1]
                if "=" in kv:
                    k, v = kv.split("=", 1)
                    params[k] = v
                i += 2
            elif arg == "--method" and i + 1 < len(args):
                method = args[i + 1].upper()
                i += 2
            else:
                print(f"未知参数: {arg}", file=sys.stderr)
                i += 1
        cmd_call(path, token, params, method)

    else:
        print(f"未知命令: {command}", file=sys.stderr)
        print(__doc__)
        sys.exit(1)


if __name__ == "__main__":
    main()

import json
import os
import sys
import unittest
from contextlib import redirect_stdout
from importlib.util import module_from_spec, spec_from_file_location
from io import StringIO
from pathlib import Path


SCRIPT_PATH = Path(__file__).resolve().parent.parent / "scripts" / "alapi.py"


class AlapiCliTests(unittest.TestCase):
    def _load_module(self):
        spec = spec_from_file_location("alapi_cli", SCRIPT_PATH)
        module = module_from_spec(spec)
        spec.loader.exec_module(module)
        return module

    def _run_main_with_stub(self, args, stub_result):
        module = self._load_module()

        def fake_request(url, method="GET", data=None, headers=None):
            return json.loads(json.dumps(stub_result, ensure_ascii=False))

        module._request = fake_request
        stdout = StringIO()
        old_argv = sys.argv
        try:
            sys.argv = ["alapi.py"] + args
            with redirect_stdout(stdout):
                module.main()
        finally:
            sys.argv = old_argv
        return stdout.getvalue()

    def test_search_json_outputs_machine_readable_payload(self):
        stub = {
            "success": True,
            "data": {
                "list": [
                    {
                        "id": 27,
                        "name": "IP 查询",
                        "description": "查询 IP 地址归属地",
                    }
                ]
            },
        }

        output = self._run_main_with_stub(["--json", "search", "IP"], stub)
        payload = json.loads(output)
        self.assertEqual(payload["command"], "search")
        self.assertEqual(payload["keyword"], "IP")
        self.assertEqual(payload["count"], 1)
        self.assertEqual(payload["items"][0]["id"], 27)
        self.assertIn("/api/27/introduction", payload["items"][0]["doc_url"])

    def test_call_json_wraps_live_response(self):
        stub = {
            "success": True,
            "code": 200,
            "message": "success",
            "data": {"city": "Shanghai"},
        }

        output = self._run_main_with_stub(
            ["--json", "call", "ip", "--token", "secret", "--param", "ip=8.8.8.8"],
            stub,
        )

        payload = json.loads(output)
        self.assertEqual(payload["command"], "call")
        self.assertEqual(payload["path"], "ip")
        self.assertEqual(payload["method"], "GET")
        self.assertTrue(payload["success"])
        self.assertEqual(payload["response"]["data"]["city"], "Shanghai")

    def test_call_uses_environment_token_when_flag_missing(self):
        module = self._load_module()
        captured = {}

        def fake_request(url, method="GET", data=None, headers=None):
            captured["data"] = data
            return {"success": True, "code": 200, "message": "success", "data": {}}

        module._request = fake_request
        old_env = os.environ.get("ALAPI_TOKEN")
        old_argv = sys.argv
        stdout = StringIO()
        try:
            os.environ["ALAPI_TOKEN"] = "env-token"
            sys.argv = ["alapi.py", "--json", "call", "ip", "--param", "ip=8.8.8.8"]
            with redirect_stdout(stdout):
                module.main()
        finally:
            if old_env is None:
                os.environ.pop("ALAPI_TOKEN", None)
            else:
                os.environ["ALAPI_TOKEN"] = old_env
            sys.argv = old_argv

        self.assertEqual(captured["data"]["token"], "env-token")

    def test_explicit_token_overrides_environment_token(self):
        module = self._load_module()
        captured = {}

        def fake_request(url, method="GET", data=None, headers=None):
            captured["data"] = data
            return {"success": True, "code": 200, "message": "success", "data": {}}

        module._request = fake_request
        old_env = os.environ.get("ALAPI_TOKEN")
        old_argv = sys.argv
        stdout = StringIO()
        try:
            os.environ["ALAPI_TOKEN"] = "env-token"
            sys.argv = [
                "alapi.py",
                "--json",
                "call",
                "ip",
                "--token",
                "flag-token",
                "--param",
                "ip=8.8.8.8",
            ]
            with redirect_stdout(stdout):
                module.main()
        finally:
            if old_env is None:
                os.environ.pop("ALAPI_TOKEN", None)
            else:
                os.environ["ALAPI_TOKEN"] = old_env
            sys.argv = old_argv

        self.assertEqual(captured["data"]["token"], "flag-token")


if __name__ == "__main__":
    unittest.main()