diff --git a/plugins/mipu-api/skills/mipu-api/SKILL.md b/plugins/mipu-api/skills/mipu-api/SKILL.md index 6565b0a..2bff3c3 100644 --- a/plugins/mipu-api/skills/mipu-api/SKILL.md +++ b/plugins/mipu-api/skills/mipu-api/SKILL.md @@ -20,6 +20,7 @@ allowed-tools: "Read,Grep,Glob" | 前缀 | 类别 | 内容 | |------|------|------| +| 01-01 | 解锁器 | Unlocker API（Agent/Request 模式、异步轮询、mipu_requests SDK） | | 02-xx | 缓存查询 | cache/search | | 03-01~03-05 | 报价相关 | search、select、baggage、seat、async-query | | 04-01~04-05 | 订单管理 | hold、payment、query、cancel、retry | diff --git a/plugins/mipu-api/skills/mipu-api/docs/01-01_unlocker.md b/plugins/mipu-api/skills/mipu-api/docs/01-01_unlocker.md new file mode 100644 index 0000000..e9f6d51 --- /dev/null +++ b/plugins/mipu-api/skills/mipu-api/docs/01-01_unlocker.md @@ -0,0 +1,381 @@ + +# 解锁器 (Unlocker) + +## 概述 + +解锁器是米普云的核心代理服务，允许你通过米普 API 代理发送 HTTP 请求到目标网站。所有请求经过米普网关转发，目标网站看到的是米普的 IP 和会话，而非你的真实信息。 + +### 典型用途 + +- 代理访问航司官网，模拟浏览器操作 +- 通过 Agent 机制维持登录态和会话 +- 获取航司网页数据（HTML、JSON） + +### 两种模式 + +| 模式 | 端点 | 适用场景 | +|------|------|----------| +| Agent 模式 | `/unlocker/agent` | 通过 Agent 代理，Agent 维持登录态和会话，适合需要身份验证的场景 | +| Request 模式 | `/unlocker/request` | 直接代理请求，无需 Agent，适合简单的 HTTP 代理场景 | + +## 认证 + +所有请求必须包含以下 Header： + +| 参数 | 值 | 说明 | +|------|-----|------| +| Content-Type | application/json | 固定值 | +| Accept-Encoding | gzip, deflate, br | 必填 | +| client-key | (由米普云提供) | 客户端 key | +| client-secret | (由米普云提供) | 客户端 secret | + +## 请求说明 + +### Agent 模式 + +| 项目 | 值 | +|------|-----| +| URL | `POST https://{endpoint}/unlocker/agent` | +| Content-Type | application/json | + +**请求体：** + +```json +{ + "url": "https://www.example.com/page", + "method": "GET", + "agent": "JQ", + "proxy": "res_mipu_xxx", + "async": true, + "headers": { + "user-agent": "Mozilla/5.0 ...", + "accept": "text/html" + }, + "sessionId": "" +} +``` + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| url | string | 是 | 目标 URL | +| method | string | 是 | HTTP 方法：GET、POST、PUT、DELETE 等 | +| agent | string | 是 | Agent 编码（在米普控制台创建） | +| proxy | string | 是 | 代理资源标识（在米普控制台获取） | +| async | boolean | 否 | 是否异步模式，默认 true | +| headers | object | 否 | 请求头（传递给目标网站） | +| body | string | 否 | 请求体（POST/PUT 时使用） | +| contentType | string | 否 | Content-Type 覆盖 | +| sessionId | string | 否 | 会话 ID（首次请求后自动返回，后续请求传入以保持会话） | + +### Request 模式 + +| 项目 | 值 | +|------|-----| +| URL | `POST https://{endpoint}/unlocker/request` | +| Content-Type | application/json | + +请求体与 Agent 模式相同，但**不需要 `agent` 字段**。请求直接到达网关，不经过 Agent。 + +## 响应说明 + +### 同步响应 + +当 `async=false` 或目标网站快速返回时，直接返回结果： + +```json +{ + "code": 0, + "sessionId": "abc123", + "statusCode": 200, + "responseBody": "...", + "responseHeaders": { + "content-type": "text/html" + } +} +``` + +| 字段 | 类型 | 说明 | +|------|------|------| +| code | int | 0 = 成功，其他见错误码 | +| sessionId | string | 会话 ID，后续请求传入以保持会话连续性 | +| statusCode | int | 目标网站返回的 HTTP 状态码 | +| responseBody | string | 目标网站返回的响应体 | +| responseHeaders | object | 目标网站返回的响应头 | + +### 异步响应 + +当 `async=true` 时，首次提交返回： + +```json +{ + "code": 202, + "agentRequestId": "req_xxx" +} +``` + +需要通过异步查询接口轮询获取结果。 + +## 异步查询 + +| 项目 | 值 | +|------|-----| +| URL | `GET https://{endpoint}/async/query/{agentRequestId}` | + +**请求头：** + +| 参数 | 值 | +|------|-----| +| client-key | 客户端 key | +| client-secret | 客户端 secret | + +**轮询策略：** + +1. 提交请求后等待 2 秒 +2. 每隔 3 秒查询一次 +3. 最多查询 20 次（约 62 秒） +4. 返回 `code=0` 表示完成 +5. 超过最大次数仍无结果则视为超时 + +## 错误码 + +| 码 | 含义 | 处理建议 | +|----|------|----------| +| 0 | 成功 | — | +| 100 | 鉴权失败 | 检查 client-key 和 client-secret | +| 102 | 超过限流 | 降低请求频率，稍后重试 | +| 103 | Proxy 错误 | 检查 proxy 标识是否正确，IP 是否可用 | +| 104 | Agent 不存在 | 检查 agent 编码，新创建的 Agent 需等待 5 分钟生效 | +| 202 | 异步处理中 | 继续轮询 /async/query/{id} | + +更多错误码请查阅 `10_error-codes.md`。 + +## 会话管理（sessionId） + +sessionId 用于保持与目标网站的会话连续性。工作流程： + +``` +第 1 次请求: 传入 sessionId = ""（空或不传） + ↓ +响应返回: sessionId = "abc123" + ↓ +第 2 次请求: 传入 sessionId = "abc123" + ↓ +响应返回: sessionId = "abc123"（相同会话） +``` + +- 首次请求不传 sessionId +- 从第一次响应中获取 sessionId +- 后续请求都传入该 sessionId +- 同一 sessionId 共享 Cookie、登录态等 + +## 直接调用示例 + +### cURL + +```bash +curl -X POST "https://api-eu.mipuyun.com/unlocker/agent" \ + -H "Content-Type: application/json" \ + -H "client-key: " \ + -H "client-secret: " \ + -d '{ + "url": "https://www.example.com/api/data", + "method": "GET", + "agent": "JQ", + "proxy": "res_mipu_xxx", + "async": true, + "headers": { + "user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" + } + }' +``` + +### Python (requests) + +```python +import requests + +API_URL = "https://api-eu.mipuyun.com/unlocker/agent" +HEADERS = { + "Content-Type": "application/json", + "client-key": "", + "client-secret": "", +} + +# 提交请求 +payload = { + "url": "https://www.example.com/api/data", + "method": "GET", + "agent": "JQ", + "proxy": "res_mipu_xxx", + "async": True, + "headers": {"user-agent": "Mozilla/5.0"}, +} +resp = requests.post(API_URL, json=payload, headers=HEADERS) +data = resp.json() + +# 异步轮询 +if data["code"] == 202: + import time + query_url = f"https://api-eu.mipuyun.com/async/query/{data['agentRequestId']}" + for _ in range(20): + time.sleep(3) + result = requests.get(query_url, headers=HEADERS).json() + if result["code"] == 0: + print(result["responseBody"]) + break +``` + +## 使用 mipu_requests SDK + +[`mipu-requests`](https://pypi.org/project/mipu-requests/) 是米普官方 Python SDK，兼容 `requests` 接口，封装了解锁器的提交、异步轮询、会话管理等细节。 + +### 安装 + +```bash +pip install mipu-requests +``` + +### 基础用法 + +```python +import mipu_requests + +# 创建 Session（凭据通过构造参数传入） +s = mipu_requests.session( + base_url="https://api-eu.mipuyun.com", + client_key="", + client_secret="", + agent="JQ", +) + +# 设置代理 +s.proxies = "res_mipu_xxx" + +# 发送 GET 请求（SDK 自动处理异步轮询） +resp = s.get("https://www.example.com/page", + headers={"user-agent": "Mozilla/5.0"}) + +print(resp.status_code) # 200 +print(resp.text) # 目标网站 HTML +print(resp.session_id) # 自动管理的 sessionId + +# 发送 POST 请求 +resp = s.post("https://www.example.com/api", + json={"key": "value"}, + headers={"content-type": "application/json"}) +print(resp.json()) +``` + +### Agent 模式 vs Request 模式 + +```python +# Agent 模式 — 通过 Agent 代理（默认） +s = mipu_requests.session(..., agent="JQ") + +# Request 模式 — 直接代理，无需 Agent +s = mipu_requests.session(..., mode="request") +``` + +### 异步模式 + +SDK 默认启用异步模式，自动处理提交和轮询： + +```python +# 默认异步（推荐） +s = mipu_requests.session(..., async_mode=True) + +# 关闭异步（同步等待，可能因长连接断连） +s = mipu_requests.session(..., async_mode=False) + +# 自定义轮询参数 +s = mipu_requests.session( + ..., + poll_interval=3, # 轮询间隔（秒） + poll_max=20, # 最大轮询次数 + submit_timeout=60, # 提交超时（秒） + poll_timeout=(5, 30), # 轮询超时 (connect, read) +) +``` + +### 会话管理 + +SDK 自动管理 sessionId，无需手动传递： + +```python +s = mipu_requests.session(...) + +# 第 1 次请求 — SDK 自动获取 sessionId +resp1 = s.get("https://example.com/login") +# s.session_id 已自动设置 + +# 第 2 次请求 — SDK 自动传入 sessionId，保持会话 +resp2 = s.get("https://example.com/dashboard") +``` + +### 错误处理 + +```python +import mipu_requests + +try: + resp = s.get("https://example.com/api") + resp.raise_for_status() # 目标网站 4xx/5xx 时抛出异常 +except mipu_requests.HTTPError as e: + print(f"目标网站错误: {e.response.status_code}") +except mipu_requests.APIError as e: + print(f"米普 API 错误: {e}") +except mipu_requests.PollTimeoutError as e: + print(f"异步轮询超时: {e}") +except mipu_requests.RequestException as e: + print(f"请求异常: {e}") +``` + +### 完整流程示例 + +```python +import mipu_requests + +with mipu_requests.session( + base_url="https://api-eu.mipuyun.com", + client_key="", + client_secret="", + agent="JQ", +) as s: + s.proxies = "res_mipu_xxx" + + # 访问首页 + resp = s.get("https://www.example.com/home") + resp.raise_for_status() + + # 提交表单（sessionId 自动传递） + resp = s.post("https://www.example.com/submit", + data={"field": "value"}, + headers={"content-type": "application/x-www-form-urlencoded"}) + resp.raise_for_status() + print(resp.json()) +``` + +## 从 requests 迁移 + +如果已有 `requests` 代码，迁移只需两步： + +```python +# ── 迁移前 ── +import requests +s = requests.Session() +s.proxies = {"https": "http://proxy:8080"} +resp = s.get("https://example.com/api") + +# ── 迁移后 ── +import mipu_requests +s = mipu_requests.session( + base_url="https://api-eu.mipuyun.com", + client_key="", + client_secret="", + agent="JQ", +) +s.proxies = "res_mipu_xxx" +resp = s.get("https://example.com/api") +``` + +`.get()`、`.post()`、`.json()`、`.raise_for_status()` 等方法完全兼容，其余代码无需改动。