kalil0321/reverse-api-engineer

用于捕获浏览器流量并自动生成可用于生产环境的 Python API 客户端的 CLI 工具。
无需再手动逆向工程——只需浏览、捕获，即可获得整洁的 API 代码。

Agent mode

Manual mode

## 目录 - [功能](#-features) - [安装](#-installation) - [快速开始](#-quick-start) - [使用模式](#-usage-modes) - [手动模式](#manual-mode) - [工程师模式](#engineer-mode) - [智能体模式](#agent-mode) - [收集器模式](#collector-mode) - [配置](#-configuration) - [模型选择](#model-selection) - [智能体配置](#agent-configuration) - [SDK 选择](#sdk-selection) - [CLI 命令](#-cli-commands) - [Claude Code 插件](#-claude-code-plugin) - [示例](#-examples) - [开发](#-development) - [贡献](#-contributing) ## ✨ 功能 - 🌐 **浏览器自动化**: 基于 Playwright 构建，带有用于模拟真实浏览的隐身模式 - 🤖 **自主智能体模式**: 使用通过 MCP (Playwright MCP 或 Chrome DevTools MCP) 连接的 AI 智能体进行全自动浏览器交互 - 📊 **HAR 录制**: 以 HTTP Archive 格式捕获所有网络流量 - 🧠 **AI 驱动的生成**: 使用 Claude 4.6 分析流量并生成整洁的 Python 代码 - 🔍 **收集器模式**: 数据收集，自动导出 JSON/CSV - 🔌 **多 SDK 支持**: 与 Claude 和 OpenCode SDK 原生集成 - 💻 **交互式 CLI**: 极简终端界面，支持模式切换 (Shift+Tab) - 📦 **生产就绪**: 生成的脚本包含错误处理、类型提示和文档 - 💾 **会话历史**: 所有运行记录保存在本地，包含完整的消息日志 - 💰 **成本追踪**: 详细的 token 使用量和成本估算，支持缓存 ### 限制 - 此工具使用 Claude Code 在本地执行代码——请注意监控输出 - 某些网站采用高级机器人检测技术，可能会限制捕获或需要手动交互 ## 🚀 安装 ### 使用 uv (推荐) ``` uv tool install reverse-api-engineer ``` ### 使用 pip ``` pip install reverse-api-engineer ``` ### 安装后步骤 安装 Playwright 浏览器： ``` playwright install chromium ``` ### 定价 Reverse API Engineer 内置了最常见模型 (Claude 4.6, Gemini 3, GPT-4.1/5) 的定价。成本追踪使用两层回退机制： 1. **本地定价表** — 为常见模型内置的定价 2. **默认回退** — 对未知模型使用 Claude Sonnet 4.6 的定价 如果您的环境中独立安装了 `litellm`，系统会自动检测并支持 100 多个额外模型的扩展定价查询。我们不再附带 `[pricing]` 扩展安装项；如果您需要该覆盖范围，请直接安装 `litellm`。 ## 🚀 快速开始 启动交互式 CLI： ``` reverse-api-engineer ``` CLI 有四种模式 (使用 **Shift+Tab** 切换)： - **manual**: 浏览器捕获 + AI 生成 - **engineer**: 重新处理已有的捕获 - **agent**: 自主 AI 浏览器智能体 (默认：带有基于 MCP 的浏览器和实时逆向工程的自动模式) - **collector**: AI 驱动的网络数据收集 (目前是非常精简的版本) 示例工作流： ``` $ reverse-api-engineer > fetch all apple jobs from their careers page # 浏览器打开，导航并交互 # 完成后关闭浏览器 # AI 生成可用于生产环境的 API 客户端 # 脚本保存至：./scripts/apple_jobs_api/ ``` ## 📖 使用模式 ### 手动模式 包含手动浏览器交互的完整流程： 1. 启动 CLI：`reverse-api-engineer` 2. 输入任务描述 (例如：“获取 Apple 职位列表”) 3. 可选择提供起始 URL 4. 浏览并与网站交互 5. 完成后关闭浏览器 6. AI 自动生成 API 客户端 **输出位置:** - `~/.reverse-api/runs/scripts/{run_id}/` (永久存储) - `./scripts/{descriptive_name}/` (带有可读名称的本地副本) ### 工程师模式 对之前的捕获重新运行 AI 生成： ``` # 切换至工程师模式 (Shift+Tab) 并输入 run_id # 或使用命令行： reverse-api-engineer engineer ``` ### 智能体模式 使用 AI 智能体进行全自动浏览器交互： 1. 启动 CLI 并切换到智能体模式 (Shift+Tab) 2. 输入任务描述 (例如：“点击第一个职位列表”) 3. 可选择提供起始 URL 4. 智能体自动导航并进行交互 5. 自动捕获 HAR 6. 自动生成 API 客户端 **智能体提供商选项:** - **auto** (默认): 使用 Playwright MCP 浏览器自动化，结合 Claude Agent SDK 和 Opencode。在单一工作流中结合了浏览器控制和实时逆向工程。 - **chrome-mcp**: 使用 [Chrome DevTools MCP](https://www.npmjs.com/package/chrome-devtools-mcp) 驱动您真实的 Chrome 浏览器 (包含现有会话、cookies 和认证)。需要 Chrome 146+ 和 Node.js 20.19+。 在 `/settings` → "agent provider" 中更改智能体提供商。 ### 收集器模式 使用 Claude Agent SDK 进行网络数据收集： 1. 启动 CLI 并切换到收集器模式 (Shift+Tab) 2. 输入描述要收集的数据的自然语言提示 (例如：“查找 3 个 JS 框架”) 3. 智能体使用 WebFetch、WebSearch 和文件工具自主收集结构化数据 4. 数据自动导出为 JSON 和 CSV 格式 **输出位置:** - `~/.reverse-api/runs/collected/{folder_name}/` (永久存储) - `./collected/{folder_name}/` (带有可读名称的本地副本) **输出文件:** - `items.json` - JSON 格式的收集数据 - `items.csv` - CSV 格式的收集数据 - `README.md` - 收集元数据和 schema 文档 **模型配置:** 收集器模式使用 `collector_model` 设置 (默认: `claude-sonnet-4-6`)。可以在 `~/.reverse-api/config.json` 中进行配置。 示例工作流： ``` $ reverse-api-engineer > Find 3 JS frameworks # Agent 自主搜索并收集数据 # 数据保存至：./collected/js_frameworks/ ``` ## 🔧 配置 设置存储在 `~/.reverse-api/config.json` 中： ``` { "agent_provider": "auto", "claude_code_model": "claude-sonnet-4-6", "collector_model": "claude-sonnet-4-6", "opencode_model": "claude-sonnet-4-6", "opencode_provider": "anthropic", "output_dir": null, "output_language": "python", "real_time_sync": true, "sdk": "claude" } ``` ### 模型选择 从 Claude 4.6 模型中进行选择以生成 API： - **Sonnet 4.6** (默认): 性能与成本的平衡 - **Opus 4.6**: 针对复杂 API 的最强性能 - **Haiku 4.5**: 最快且最经济 在 `/settings` 中或通过 CLI 进行更改： ``` reverse-api-engineer manual --model claude-sonnet-4-6 ``` 如果您使用 Opencode，请查看 [models](https://models.dev)。 ### 智能体配置 配置 AI 智能体以进行自主浏览器自动化。 **智能体提供商:** - **auto** (默认): 结合实时逆向工程的 Playwright MCP 浏览器自动化。使用带有浏览器 MCP 工具的 Claude Agent SDK。在单一统一的工作流中结合了浏览器控制和 API 逆向工程。支持 Claude SDK (默认) 或 OpenCode SDK。 - **chrome-mcp**: 通过 [Chrome DevTools MCP](https://www.npmjs.com/package/chrome-devtools-mcp) 驱动您真实的 Chrome 浏览器。当您需要现有会话、cookies 或认证时非常有用。需要 Chrome 146+ 和 Node.js 20.19+；在 `chrome://inspect/#remote-debugging` 处启用自动连接。 智能体的推理模型与 SDK 模型相同 — 请参阅 [模型选择](#model-selection)。 在 `/settings` → "agent provider" 中更改 ### SDK 选择 - **Claude** (默认): 直接集成 Anthropic 的 Claude API - **OpenCode**: 使用 OpenCode SDK (要求 OpenCode 在本地运行) 在 `/settings` 中更改或直接编辑 `config.json`。 ### 输出语言 控制生成的 API 客户端的编程语言： - **python** (默认): 生成 Python API 客户端 - **javascript**: 生成 JavaScript API 客户端 - **typescript**: 生成 TypeScript API 客户端 在 `/settings` → "Output Language" 中更改或编辑 `config.json`： ``` { "output_language": "typescript" } ``` ### 实时同步 在工程会话期间启用或禁用实时文件同步： - **启用** (默认): 文件在生成时同步到磁盘 - **禁用**: 文件仅在会话结束时写入 启用后，您可以在 AI 生成文件时实时看到它们出现。这对于监控进度和调试非常有用。 在 `/settings` → "Real-time Sync" 中更改或编辑 `config.json`： ``` { "real_time_sync": false } ``` ## 💻 CLI 命令 在 CLI 中使用以下斜杠命令： - `/settings` - 配置模型、智能体、SDK 和输出目录 - `/history` - 查看过往运行记录及成本 - `/messages ` - 查看详细的消息日志 - `/help` - 显示所有命令 - `/exit` - 退出 ### 脚本化 / 智能体使用 CLI 子命令可由其他智能体或包装脚本驱动。传入 `--no-interactive` (和/或 `--json`) 以使其在遇到问题时快速失败，而不是打开 questionary 提示，并将结构化输出通过管道传递给 `jq`。 当设置了 `--json` 时：标准输出 (stdout) 恰好包含一个 JSON 文档 (最终结果)，Rich 日志和进度信息将重定向到标准错误 (stderr)，并且进程以稳定的代码退出。 ``` # 运行自主 Agent 捕获并在 stdout 获取单个 JSON 结果 reverse-api-engineer agent \ --prompt "capture the public jobs api" \ --url https://example.com/jobs \ --json | jq # 列出运行 / 以 JSON 格式检查运行 (空历史 -> []) reverse-api-engineer list --json reverse-api-engineer show --json # 非交互式运行生成的脚本 # --no-interactive : 从不打开 script-picker / 安装确认 # --auto-install : 重试时无需询问即可安装缺失的 deps reverse-api-engineer run --file api_client.py \ --no-interactive --auto-install -- --org acme ``` #### `agent --json` 输出 schema | 字段 | 类型 | 说明 | |------------------|---------------------|------------------------------------------------------------------------| | `schema_version` | `int` | 当前为 `1`。在发生破坏性更改时递增。 | | `status` | `"ok"` \| `"error"` | 顶层结果。 | | `run_id` | `string` \| `null` | 用于后续 `show` / `engineer` / `run` 调用的稳定 ID。 | | `prompt` | `string` | 传入的提示词。 | | `url` | `string` \| `null` | 可选的起始 URL。 | | `mode` | `string` \| `null` | 使用的提供商 (`"auto"` 对应 Playwright MCP, `"chrome-mcp"`)。 | | `har_path` | `string` \| `null` | 捕获的 HAR (`recording.har`) 的绝对路径。 | | `script_path` | `string` \| `null` | 运行逆向工程时生成的客户端的绝对路径。 | | `usage` | `object` | 来自工程师 SDK 的 token 和成本使用量 (`{input_tokens, output_tokens, total_cost}`)。| | `error` | `string` \| `null` | 当 `status == "error"` 时的人类可读错误消息。 | #### 退出代码 | 代码 | 含义 | |------|---------------------------------------------------------------------------| | `0` | 成功。 | | `1` | 运行时错误 (捕获或工程失败；详情见 `error`)。 | | `2` | 误用 — 在 `--no-interactive` / `--json` 下缺少所需参数。 | 对于 `run` 命令，成功时的退出代码是底层脚本的返回代码，如果没有找到脚本则为 `1`，或者在 `--no-interactive` 必须提示时为非零值。 ## 🔌 Claude Code 插件 在 [Claude Code](https://claude.com/claude-code) 中安装该插件： ``` claude # Open REPL /plugin marketplace add kalil0321/reverse-api-engineer /plugin install reverse-api-engineer@reverse-api-engineer ``` 有关命令、智能体、技能和用法示例，请参阅 [插件文档](plugins/reverse-api-engineer/README.md)。 ## 💡 示例 ### 示例：逆向工程职位看板 API ``` $ reverse-api-engineer > fetch all apple jobs from their careers page # 浏览器打开，您进行导航和交互 # 完成后关闭浏览器 # AI 生成： # - api_client.py (完整的 API 实现) # - README.md (文档) # - example_usage.py (使用示例) # 脚本已复制至：./scripts/apple_jobs_api/ ``` 生成的 `api_client.py` 包含： - 认证处理 - 整洁的函数接口 - 类型提示和 docstrings - 错误处理 - 生产就绪的代码 ## 🛠️ 开发 ### 设置 ``` git clone https://github.com/kalil0321/reverse-api-engineer.git cd reverse-api-engineer uv sync ``` ### 运行 ``` uv run reverse-api-engineer ``` ### 构建 ``` ./scripts/clean_build.sh ``` ## 🔐 要求 - Python 3.11+ - Claude Code / OpenCode (用于逆向工程) - 已安装 Playwright 浏览器 - 智能体模式所需的 API key (请参阅 [智能体配置](#agent-configuration)) ## 🤝 贡献 欢迎贡献！请随时提交 Pull Request。 ## 📄 许可证 本项目基于 MIT 许可证授权 - 详情请参阅 [LICENSE](LICENSE) 文件。

标签：API客户端生成, API文档生成, Claude, CVE检测, DLL 劫持, MIT许可, Playwright, Python, Python包, SDK生成, 云资产清单, 代理工具, 大语言模型, 威胁情报, 开发者工具, 开源, 无后门, 流量捕获, 浏览器自动化, 特征检测, 网络安全, 网络拓扑, 逆向工具, 逆向工程, 隐私保护