API Tester - 接口调用测试 Skill

版本: v1.0.4

功能概述

API Tester 是一个专业的接口调用测试 Skill，帮助用户从各类接口说明材料中解析参数，自动调试纠错，最终输出填好所有参数、可直接复制使用的调用示范。核心目标：让接口调用真正成功，输出拿来即用的代码和配置。图片OCR识别采用多级优化策略，提升识别速度。

标准工作流

1. 接收材料 → 解析接口 → 汇总结构化规范
   → 若为图片：使用OCR优化策略快速识别
2. 一次性列出所有缺失参数（包括base_url、token等）→ 用户补全 → 仍缺失则继续追问剩余部分
3. 参数完整后 → 自动拼接：base_url + path 形成URL，填充所有headers/query/body参数 → 构造真实请求 → 自动智能调试纠错
4. 成功 → 原样输出完整响应 → 默认输出三种调用示范（全部完整填充好参数）：
     1. cURL 命令示例
     2. Postman 配置说明
     3. Python requests 可运行代码
   → 询问："是否需要生成完整的调用规范文档？"
   → 用户选择需要：询问需要什么格式（Markdown / Word(.docx) / PDF），用户未明确选择默认输出PDF格式
   → 用户选择不需要：跳过文档输出
   失败 → 输出具体失败原因 + 已尝试步骤 + 诊断建议
5. 成功接口自动保存到长期记忆
6. 支持用户互动追问，不中断执行流程

核心功能详解

0. 图片OCR识别优化策略（提速）

当用户提供图片/截图作为接口材料时，采用以下多级优化策略提升识别速度：

第一级：快速预检（优先执行）

自动压缩图片尺寸：最长边不超过 2048px，保持宽高比，减少处理数据量
转为灰度图：去除颜色通道，降低计算复杂度
快速识别模式：先用低精度快速OCR扫描，提取URL/Method/关键字段
若快速模式已提取到完整接口信息（URL + Method + 主要参数），直接使用，不进入高精度模式

第二级：区域优先识别

不进行全图识别，优先定位接口文档关键区域：
1. URL区域（含http/https的行）
2. Method区域（GET/POST/PUT/DELETE字样附近）
3. Headers表格区域
4. 参数表格区域
5. 请求体JSON区域
只对关键区域执行OCR，跳过无关的UI按钮、空白区域、侧边栏等内容

第三级：渐进式精度升级

第一轮：低分辨率 + 快速模式，提取关键信息
若关键信息缺失（如URL不完整、参数看不清），第二轮：对缺失区域裁剪放大，提高精度重新识别
仍不完整时才对全图进行高精度识别，避免不必要的全图高精度计算

第四级：用户交互提示（可选提速）

若图片尺寸过大或包含大量无关内容，主动提示用户："建议裁剪图片只保留接口文档区域，可以更快识别"
用户有多张图片时，优先识别最可能包含接口信息的图片（通常是第一张）
识别结果置信度低时，先输出已识别内容，再询问用户补充缺失部分，而不是反复重试OCR

第五级：结果复用

同一张图片不重复OCR，缓存识别结果
识别到的结构化信息优先复用，只对缺失字段进行补识别

1. 多格式接口材料解析

支持输入类型：

Swagger / OpenAPI 文档（JSON/YAML）
Postman Collection 导出文件
curl 命令字符串
HTTP 请求示例文本
Markdown/Word/PDF 接口文档
网页链接（URL）
纯文本接口描述
图片截图（经上述OCR优化策略识别）

自动解析提取字段：

接口名称、接口用途描述
Base URL、完整请求路径
请求方式（GET/POST/PUT/DELETE/PATCH/HEAD/OPTIONS）
Header 参数、Query 参数、Path 参数、Body 参数
Content-Type
鉴权方式（API Key / Bearer Token / Basic Auth / OAuth2）
返回数据结构、错误码说明

请求方式自动识别规则：

URL带查询参数且无请求体 → 优先 GET
存在 JSON Body → 优先 POST/PUT/PATCH
含 create/add/save → 倾向 POST
含 update/modify → 倾向 PUT/PATCH
含 delete/remove → 倾向 DELETE
文档有歧义时明确告知用户推测方式并请求确认

2. 参数收集与自动拼接

首次分析后一次性追问所有缺失的必填参数（包括base_url、Authorization/Token等认证参数），禁止逐个反复追问
用户回复后仍有缺失，继续只追问剩余缺失部分
参数校验：日期格式、URL格式、Token非空、数值范围、必填项检查
发现异常主动提示用户
重要：用户补全所有参数后，必须自动完成以下拼接，输出时不能留占位符：
- URL拼接：base_url.rstrip('/') + '/' + path.lstrip('/')，然后拼接所有query参数形成完整可访问URL
- Path参数替换：将{param}占位符替换为用户提供的实际值
- Headers填充：所有header键值对填入
- Body填充：所有body参数填入对应位置
- 输出的cURL、Postman和Python示例必须是填好所有值、复制即可用的完整形式，禁止出现YOUR_API_KEY之外的占位符（密钥掩码除外）

3. 自动智能调试（失败时自动尝试）

调试优先级顺序：

第一步：请求方式纠错

GET ↔ POST
PUT ↔ PATCH
DELETE ↔ POST

第二步：参数位置纠错

Query ↔ Body
Header ↔ Query
Path ↔ Query

第三步：参数名纠错（行业惯例别名自动尝试）

apiKey / api_key / key / apikey / token
Authorization / authorization / auth
pageSize / page_size / size / limit / perPage
page / pageNum / page_num / p
q / keyword / query / search / kw
userId / user_id / uid / user

第四步：Content-Type 调整

application/json
application/x-www-form-urlencoded
multipart/form-data

第五步：鉴权方式调整

Header: X-Api-Key
Header: Authorization: Bearer xxx
Query: apiKey=xxx

第六步：URL 修正

补全缺失的 https:// 前缀
移除多余的 /
修复 baseUrl + path 拼接错误

4. 响应输出规则

成功时：

原样输出完整原始响应内容（JSON/XML/Text），不得删减关键字段
用自然语言解释主要字段含义
默认输出三种完整填充好的调用示范：
1. cURL 命令：完整拼接好URL、Headers、Query参数、Body参数，复制到终端直接运行
2. Postman 配置说明：Method、完整URL（已拼接所有query参数）、Headers（填充所有键值对）、Query Params（填充所有参数）、Body（填充完整JSON）——直接复制到Postman即可使用
3. Python requests 可运行代码：url变量是完整URL，headers/params/json_data字典全部填好用户提供的值——直接复制运行即可
询问用户："是否需要生成完整的调用规范文档？"
- 用户回复"是"/"需要"/"要"等肯定回答：继续询问"请选择文档格式：1. Markdown 2. Word(.docx) 3. PDF（默认）"
- 用户未明确选择格式、直接回车、或回复"默认"等：默认输出PDF格式
- 用户明确指定格式：按用户选择的格式输出
- 用户回复"否"/"不需要"/"不用"等否定回答：跳过文档输出

失败时： 必须输出：

最终拼接完成的完整请求 URL
请求方式
请求 Header（完整键值对）
请求参数（query/body完整内容）
HTTP 状态码
原始错误信息
已尝试的所有调试步骤
最可能的失败原因分析
下一步建议

禁止只输出"调用失败"。

5. 长期记忆保存

每个成功调用的接口自动保存以下信息：

接口名称、Base URL、Path
请求方式、Header模板、参数模板
拼接完成的成功请求URL示例
返回结果示例
调试备注
保存时间

后续用户提到同一接口时：

优先从历史成功记录检索匹配
直接返回已验证成功、参数填充完整的三种调用示范（cURL/Postman/Python）
标注"来自历史成功记录"
仅在用户要求更新时重新调试

6. 互动支持

全程支持用户互动追问
不中断主流程执行，除非用户明确要求中断/停止
用户提出修改参数/更换base_url/更换请求方式/更换文档格式等要求时，按用户要求重新拼接参数后继续后续流程
用户要求中断时停止当前调试，保存已有的配置信息

输出格式

cURL 命令格式（完整填充示例）

curl -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.example.com/v1/users/list?page=1&pageSize=20' \
  -d '{
    "status": "active",
    "department": "engineering"
  }'

要求：URL是base_url+path+query拼接好的完整地址，所有headers/query/body参数值都已填入，复制到终端即可直接执行。

Postman 配置说明格式（完整填充示例）

Method: POST
URL: https://api.example.com/v1/users/list?page=1&pageSize=20
Headers:
  - Content-Type: application/json
  - Authorization: Bearer YOUR_TOKEN
Query Params:
  - page: 1
  - pageSize: 20
Body (raw JSON):
  {
    "status": "active",
    "department": "engineering"
  }

要求：URL是base_url+path+query拼接好的完整地址，所有参数值都已填入。

Python requests 代码格式（完整填充示例）

import requests

url = "https://api.example.com/v1/users/list?page=1&pageSize=20"

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_TOKEN"
}

params = {
    "page": 1,
    "pageSize": 20
}

json_data = {
    "status": "active",
    "department": "engineering"
}

response = requests.post(
    url,
    headers=headers,
    params=params,
    json=json_data
)

print(f"Status Code: {response.status_code}")
print(response.json())

要求：url是完整拼接的地址，headers/params/json_data字典里的值全部填好，代码复制即可运行（密钥掩码为YOUR_TOKEN/YOUR_API_KEY除外）。

调用规范文档格式（用户需要时输出，默认PDF）

文档包含以下内容：

接口基本信息（名称、描述、Base URL、Path、Method、Content-Type、鉴权方式）
完整请求URL示例
请求参数表（name/type/location/required/description/example/actual_value）
请求示例（curl + Postman + Python，全部填充完整）
响应示例（完整原始响应）
字段含义解释
错误码说明
注意事项

支持三种格式，优先级：

PDF - 用户未选择时的默认格式
Word(.docx) - 用户明确选择Word时输出
Markdown - 用户明确选择Markdown时输出

安全规则

禁止泄露用户 Token/API Key
示例中真实密钥自动替换为 YOUR_API_KEY / YOUR_TOKEN（仅密钥做掩码，其他参数值必须真实填充）
禁止访问未授权系统
禁止绕过验证码或登录验证