reverse-api-engineer

逆向 API 工程师

reverse-api-engineer（rae）会通过浏览器执行任务，读取网站发出的请求，并将它们转换为 API 客户端。chrome-mcp 提供方会在用户自己的 Chrome 中运行，因此用户的登录状态也会沿用。auto 提供方（Playwright）会使用全新的浏览器并录制 HAR 文件，因此之后无需再次浏览，就能根据一次运行重新工程化。具体使用哪一种取决于用户的配置和 rae 版本；第 3 步会介绍如何检查。

此技能仅提供操作说明。它通过脚本化、输出 JSON 的命令来调用 CLI。

1. 检查安装情况

reverse-api-engineer --version

如果找不到该命令，请先询问用户，再安装任何内容，然后：

uv tool install reverse-api-engineer   # or: pipx install reverse-api-engineer

Agent 模式还需要将 Node.js 20.19+ 添加到 PATH（它会通过 npx 启动浏览器工具）。有关模型访问和设置，请参阅设置与配置。

2. 如果有之前的采集记录，则重复使用

reverse-api-engineer list --search "<site or task>" --json

list 也会包含失败和中断的尝试，因此重复使用候选记录前，请先检查：

reverse-api-engineer show <run_id> --json

• file_count > 0 表示已生成客户端：请在第 5 步验证它，如果适用于当前任务，则重复使用。
• har_entries > 0 表示流量已保存：无需再次浏览，可以通过 engineer（第 6 步）改进客户端。chrome-mcp 运行不会保留 HAR（mode: "chrome-mcp"），因此无法重新工程化。
• 否则，请从第 3 步重新采集。

3. 运行前检查

reverse-api-engineer agent -p "<goal>" -u "<start url>" --dry-run

这会验证提示词、URL、配置和环境，而不会打开浏览器。运行前请修复所有 error 检查项。如果 SDK 通过其他方式进行身份验证（例如已登录的 Claude Code），API 密钥的 warn 可以忽略。

输出中的 would_run.agent_provider 表示本次运行将使用的浏览器。chrome-mcp 表示使用用户自己的 Chrome 和其登录状态；auto 和 agent-browser 会启动没有用户登录状态的全新浏览器。如果任务需要用户登录，而提供方不是 chrome-mcp，请在切换前征求用户同意（参见会话）。

对于 chrome-mcp，chrome-mcp:auto-connect 检查项用于确认能否连接到用户的 Chrome：

• ok：Chrome 可访问。运行开始时，用户仍需接受 Chrome 的连接提示。
• error：Chrome 不可访问。如果网站需要用户登录，请让用户打开 Chrome 146+，并在 chrome://inspect/#remote-debugging 中启用远程调试（“Enable auto-connect”），然后重新运行前检查。如果是公开数据，请添加 --headless：rae 随后会启动自己的无头 Chrome，不使用用户的会话，并跳过此项检查。
• warn：此 rae 版本无法测试连接。对于有头运行，请让用户确认 Chrome 已打开且已启用自动连接；如果是公开数据，则使用 --headless。

请将目标描述为用户想要的数据，而不是要执行的点击操作：“从招聘页面获取开放职位的职称、地点和团队信息，包括分页”比“点击招聘标签”效果更好。

4. 捕获并生成

一次运行需要几分钟，通常会超过 shell 工具的默认超时时间。请从一开始就在后台启动；如果 shell 工具有后台选项，请使用该选项，否则使用 &：

reverse-api-engineer agent -p "<goal>" -u "<start url>" --json-stream > rae-run.ndjson 2> rae-run.log &
echo $! > rae-run.pid

--json-stream 会为每个 NDJSON 事件写入一行，并以 {"event":"result",...} 行结束。当该行出现在 rae-run.ndjson 中，或 rae-run.pid 中的进程已退出（kill -0 "$(cat rae-run.pid)" 失败）时，运行即告完成。使用 tail rae-run.log 检查进度。运行仍在进行时，切勿启动第二次捕获：这会重复工作并产生额外费用。

• 如果不使用 --headless，chrome-mcp 会在用户的 Chrome 中打开自己的标签页，并且只关闭该标签页。由于它会操作用户的浏览器，启动前请告知用户，并请用户接受 Chrome 显示的连接提示：如果无人接受，运行会超时，且不会有客户端。
• 对公共网站或没有显示器的计算机，请添加 --headless。
• 添加 -o <dir>，将运行结果写入 ~/.reverse-api/runs 以外的位置。
• --json 会在最后将相同结果作为单个对象打印，不显示进度。只有在 shell 能等待整个运行完成时才使用它。
• 有关已登录的网站和提供商，请参阅会话与受阻网站。

最终结果行包含以下字段：

字段	含义
status	ok 或 error
run_id	engineer、run 和 show 使用的 ID
script_path	生成的客户端，位于 <runs>/scripts/<run_id>/ 中，与其 README.md 放在一起
har_path	原始捕获内容；对于 chrome-mcp 运行，该值为 null，因为这类运行不会保存 HAR
usage.total_cost_usd	本次运行的大模型费用；请告知用户
error_kind	失败时设置；请参阅故障排除

退出代码：0 表示成功，1 表示捕获或工程化失败，2 表示使用方式错误。

5. 验证客户端

运行任何内容之前，请先阅读生成的客户端及其 README.md：这是由模型编写的代码。然后运行它：

reverse-api-engineer run <run_id> --ls                       # list generated files
reverse-api-engineer run <run_id> --file <client file> --json -- <script args>

--auto-install 会在不提示的情况下安装缺失的依赖；请先征求用户同意。检查输出是否包含来自网站的真实数据，而不只是 200 状态码。

6. 基于同一次捕获进行迭代

reverse-api-engineer engineer <run_id> -p "add pagination and a typed Job model" --json
reverse-api-engineer engineer <run_id> --fresh -p "only the search endpoint" --json

不使用 --fresh 时，提示词会叠加在原始目标和现有客户端之上。使用 --fresh 时，会根据 HAR 重新生成客户端。engineer 需要 HAR，因此只适用于来自 auto 或 agent-browser 提供商的运行，以及手动模式的运行；对于 chrome-mcp 运行，它会以 2 退出，并显示 error_kind: misuse。对于这些运行，或捕获本身缺少端点时，请使用更具体的目标再次运行 agent。

7. 交接

客户端位于结果中的 script_path。启用 real_time_sync（默认设置）时，rae 也会将其复制到工作目录中的 ./scripts/<descriptive_name>/；如果该目录不存在，请从 script_path 复制。请根据代码库调整名称和类型，并保留生成的 README.md 作为使用说明。告知用户客户端封装了哪些端点，以及如何处理身份验证（Cookie、Bearer token、CSRF），因为捕获的凭据会过期。

使用边界

• 仅捕获用户有权访问的网站，并遵守网站的条款和速率限制。
• 捕获内容可能包含 Cookie 和 token。请勿将 HAR 内容粘贴到聊天、议题或提交中。
• 如果网站需要人工操作（验证码、2FA、异常登录），请让用户通过手动模式进行捕获，然后继续使用 engineer。请参阅会话与受阻网站。