reverse-engineering-api

逆向工程 API 技能

此技能可帮助你通过以下方式对 Web API 进行逆向工程：

1. 使用启用了 HAR 录制的浏览器
2. 分析捕获的网络流量
3. 生成可用于生产环境的 Python API 客户端

前置条件

• Playwright MCP：必须能够使用 Playwright MCP 工具控制浏览器
• HAR 录制：必须将浏览器配置为录制 HAR 文件
• Python：用于运行分析脚本和生成的客户端

工作流概览

[User Task] -> [Browser Capture] -> [HAR Analysis] -> [API Client Generation] -> [Testing & Refinement]

阶段 0：准备（使用 HAR 辅助脚本）

可用的辅助脚本

此技能提供用于分析 HAR 的 Python 工具，位于：

脚本目录： plugins/reverse-api-engineer/skills/reverse-engineering-api/scripts/

可用脚本：

• har_filter.py - 仅将 HAR 文件筛选为 API 端点
• har_analyze.py - 提取结构化端点信息
• har_validate.py - 根据 HAR 分析结果验证生成的代码
• har_utils.py - 通用辅助函数

脚本使用流程

按顺序使用这些脚本，以获得最佳代码生成效果：

# 1. Filter HAR to remove noise (static assets, analytics, CDN)
python {SKILL_DIR}/scripts/har_filter.py {har_path} --output filtered.har --stats

# 2. Analyze endpoints and extract patterns
python {SKILL_DIR}/scripts/har_analyze.py filtered.har --output analysis.json

# 3. Read analysis for code generation guidance
cat analysis.json

# 4. Generate API client code based on analysis

# 5. Validate generated code
python {SKILL_DIR}/scripts/har_validate.py api_client.py analysis.json

为什么要使用这些脚本？

har_filter.py 的优势：

• 将 HAR 文件大小减少 80-90%（移除噪声）
• 专注分析实际的 API 调用
• 显著提升代码生成质量
• 输出统计信息，展示筛选了哪些内容

har_analyze.py 的优势：

• 提供结构化端点信息
• 自动检测身份验证模式
• 识别分页机制
• 提取请求/响应架构
• 按模式对端点分组

har_validate.py 的优势：

• 确保已实现所有端点
• 验证身份验证处理
• 检查错误处理是否恰当
• 计算覆盖率分数（必须 >= 90）
• 识别缺失的功能

任务跟踪

使用 TodoWrite 跟踪工作流进度：

• 将任务标记为 pending、in_progress 或 completed
• 一次只能有一个任务处于 in_progress 状态
• 完成所有任务——切勿提前停止

TodoWrite 使用示例：

TodoWrite([
  {"content": "Filter HAR using har_filter.py", "status": "in_progress", "activeForm": "Filtering HAR"},
  {"content": "Analyze HAR using har_analyze.py", "status": "pending", "activeForm": "Analyzing endpoints"},
  {"content": "Generate API client", "status": "pending", "activeForm": "Generating code"},
  {"content": "Validate using har_validate.py", "status": "pending", "activeForm": "Validating code"},
  {"content": "Test implementation", "status": "pending", "activeForm": "Testing API client"}
])

**重要：**任务跟踪可确保完整执行工作流。切勿跳过任务或提前停止。

阶段 1：通过 HAR 录制捕获浏览器流量

启动浏览器

启动浏览器会话以捕获 API 时：

1. 通过 Playwright MCP 启动启用了 HAR 录制的浏览器
2. 生成唯一的运行 ID：{run_id}
3. 配置 HAR 输出路径：~/.reverse-api/runs/har/{run_id}/recording.har

捕获期间

自主导航以触发所需的 API 调用：

• 登录流程（捕获身份验证）
• 数据获取（捕获 GET 端点）
• 表单提交（捕获 POST/PUT 端点）
• 分页（捕获查询参数模式）

关闭浏览器时

浏览器关闭后，记录 HAR 文件位置：

HAR file saved to: ~/.reverse-api/runs/har/{run_id}/recording.har

阶段 2：HAR 分析

读取 HAR 文件

HAR 文件是具有以下结构的 JSON：

{
  "log": {
    "entries": [
      {
        "request": {
          "method": "GET|POST|PUT|DELETE",
          "url": "https://api.example.com/endpoint",
          "headers": [...],
          "postData": {...}
        },
        "response": {
          "status": 200,
          "headers": [...],
          "content": {...}
        }
      }
    ]
  }
}

筛选相关条目

通过排除以下内容来过滤噪声：

• 静态资源：.js、.css、.png、.jpg、.svg、.woff、.ico
• 分析工具：google-analytics、segment、mixpanel、hotjar
• 广告：doubleclick、adsense、facebook.com/tr
• CDN 资源：cloudflare、cdn.、static.

重点关注：

• API 端点：/api/、/v1/、/v2/、/graphql
• 响应为 JSON 的 XHR/Fetch 请求
• 带有身份验证标头的请求

提取模式

对于每个相关端点，提取：

1. URL 模式：基础 URL、路径、查询参数
2. 方法：GET、POST、PUT、DELETE、PATCH
3. 标头：
   • 必需标头（Authorization、Content-Type、自定义标头）
   • 可选标头（User-Agent、Accept）
4. 请求正文：JSON 架构、表单数据结构
5. 响应架构：JSON 结构、状态码
6. 身份验证：参见 references/AUTH_PATTERNS.md

阶段 3：生成 API 客户端

代码结构

生成一个 Python 模块，其中包含：

{output_dir}/
  api_client.py    # Main API client class
  README.md        # Usage documentation

api_client.py 模板

"""
Auto-generated API client for {domain}
Generated from HAR capture on {date}
"""

import requests
from typing import Optional, Dict, Any, List
import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)


class {ClassName}Client:
    """API client for {domain}."""
    
    def __init__(
        self,
        base_url: str = "{base_url}",
        session: Optional[requests.Session] = None,
    ):
        self.base_url = base_url.rstrip("/")
        self.session = session or requests.Session()
        self._setup_session()
    
    def _setup_session(self):
        """Configure session with default headers."""
        self.session.headers.update({
            "User-Agent": "Mozilla/5.0 (compatible)",
            "Accept": "application/json",
            # Add other required headers
        })
    
    def _request(
        self,
        method: str,
        endpoint: str,
        **kwargs,
    ) -> requests.Response:
        """Make an HTTP request with error handling."""
        url = f"{self.base_url}{endpoint}"
        try:
            response = self.session.request(method, url, **kwargs)
            response.raise_for_status()
            return response
        except requests.exceptions.RequestException as e:
            logger.error(f"Request failed: {e}")
            raise
    
    # Generated endpoint methods go here
    def get_example(self, param: str) -> Dict[str, Any]:
        """
        Fetch example data.
        
        Args:
            param: Description of parameter
            
        Returns:
            JSON response data
        """
        response = self._request("GET", f"/api/example/{param}")
        return response.json()


# Example usage
if __name__ == "__main__":
    client = {ClassName}Client()
    # Example calls

代码质量要求

所有生成的代码都必须包含：

1. 所有参数和返回值的类型提示
2. 所有公共方法的文档字符串
3. 使用 try-except 代码块进行错误处理
4. 用于调试的日志记录
5. 用于复用连接的会话管理
6. 根据检测到的模式处理身份验证

阶段 4：测试与优化

测试生成的客户端

生成客户端后：

1. 运行示例用法部分
2. 验证响应是否符合预期结构
3. 处理遇到的任何错误

迭代流程

你最多可以尝试 5 次来修复问题：

Attempt 1: Initial implementation
  - What was tried
  - What failed (if anything)
  - What was changed

Attempt 2: Refinement
  ...

常见问题

问题	解决方案
403 Forbidden	添加缺失的标头，检查身份验证
Bot detection	切换到启用隐身模式的 Playwright
Rate limiting	添加延迟，遵守 Retry-After 标头
Session expiry	实现令牌刷新逻辑
CORS errors	使用服务端请求（不适用于 Python）

域名发现（可选）

在抓取之前，你可以先映射域名，以了解其结构。

使用映射脚本

运行 scripts/mapper.py 可快速发现：

• 域名或子域名下的所有页面
• 子域名

这有助于在多租户网站上编写通用脚本。

例如，对于 Ashby ATS 或 Workday，在尝试编写通用脚本时，查找其他使用这些 ATS 的公司很有帮助。

python scripts/mapper.py https://example.com

使用站点地图解析器

运行 scripts/sitemap.py 从站点地图中提取 URL：

python scripts/sitemap.py https://example.com

输出位置

• HAR 文件：~/.reverse-api/runs/har/{run_id}/
• 生成的脚本：./{task_name}

示例会话

User: "Create an API client for the Apple Jobs website"


1. [Browser Capture]
   Launch browser with HAR recording
   Navigate to jobs.apple.com
   Perform search, browse listings
   Close browser
   HAR saved to: ~/.reverse-api/runs/har/{run_id}/recording.har

   Note: you can monitor browser requests with the Playwright MCP

2. [HAR Analysis]
   Found endpoints:
   - GET /api/role/search?query=...
   - GET /api/role/{id}
   Authentication: None required (public API)

3. [Generate Client]
   Create : {task_name}/api_client.py
   
4. [Test]
   Ran example usage - Success!
   
5. [Summary]
   Generated Apple Jobs API client with:
   - search_roles(query, location, page)
   - get_role(role_id)
   Files: ./{task_name}/