reverse-api-engineer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Reverse API Engineer

reverse-api-engineer

(rae) drives a browser through a task, reads the requests the website makes, and turns them into an API client. The

chrome-mcp

provider works in the user's own Chrome, so their logins carry over. The

auto

provider (Playwright) uses a fresh browser and records a HAR file, which lets a run be re-engineered later without browsing again. Which one runs depends on the user's config and rae version; step 3 shows how to check.

This skill only supplies instructions. It drives the CLI through its scripted, JSON-emitting commands.

reverse-api-engineer

（rae）驱动浏览器完成一项任务，读取网站发出的请求，并将其转换为 API 客户端。

chrome-mcp

provider 在用户自己的 Chrome 中运行，因此可以沿用用户的登录状态。

auto

provider（Playwright）使用全新的浏览器并记录 HAR 文件，从而无需再次浏览即可在后续重新生成客户端。实际使用哪个 provider 取决于用户配置和 rae 版本；步骤 3 说明了检查方式。

此 skill 仅提供操作说明。它通过脚本化、可输出 JSON 的命令来驱动 CLI。

1. Check the install

1. 检查安装情况

bash

reverse-api-engineer --version

If the command is missing, ask the user before installing anything, then:

bash

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

Agent mode also needs Node.js 20.19+ on

PATH

(it launches browser tooling through

npx

). See setup and configuration for model access and settings.

bash

reverse-api-engineer --version

如果命令不存在，应先征得用户同意再安装任何内容，然后执行：

bash

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

Agent 模式还需要在

PATH

中提供 Node.js 20.19+（它会通过

npx

启动浏览器工具）。有关模型访问权限和设置，请参阅安装与配置。

2. Reuse an earlier capture when one exists

2. 存在早期抓取结果时予以复用

bash

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

list

also includes failed and interrupted attempts, so check a candidate before reusing it:

bash

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

```
file_count > 0
```
means a client was generated: verify it in step 5 and reuse it if it covers the task.
```
har_entries > 0
```
means the traffic was saved: you can improve the client with
```
engineer
```
(step 6) instead of browsing again.
```
chrome-mcp
```
runs keep no HAR (
```
mode: "chrome-mcp"
```
), so they cannot be re-engineered.
Otherwise, capture again from step 3.

bash

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

list

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

bash

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

```
file_count > 0
```
表示已生成客户端：在步骤 5 中验证该客户端；如果它能够覆盖任务，则直接复用。
```
har_entries > 0
```
表示流量已保存：可以使用
```
engineer
```
改进客户端（步骤 6），无需再次浏览。
```
chrome-mcp
```
运行不会保留 HAR（
```
mode: "chrome-mcp"
```
），因此无法重新生成客户端。
否则，从步骤 3 重新开始抓取。

3. Preflight

3. 预检

bash

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

This validates the prompt, URL, config and environment without opening a browser. Fix every

error

check before running. A

warn

on the API key is fine when the SDK authenticates another way (for example a logged-in Claude Code).

would_run.agent_provider

in the output is the browser the run will use.

chrome-mcp

means the user's own Chrome with their logins;

auto

and

agent-browser

start a fresh browser without them. When the task needs the user's login and the provider is not

chrome-mcp

, ask before switching it (see sessions).

For

chrome-mcp

, the

chrome-mcp:auto-connect

check covers the connection to the user's Chrome:

```
ok
```
: Chrome is reachable. The user still has to accept Chrome's connection prompt when the run starts.
```
error
```
: it is not. If the site needs the user's login, ask them to open Chrome 146+ and enable remote debugging at
```
chrome://inspect/#remote-debugging
```
("Enable auto-connect"), then run the preflight again. For public data, add
```
--headless
```
: rae then starts its own headless Chrome, without the user's sessions, and skips the check.
```
warn
```
: this rae version cannot test the connection. Ask the user to confirm Chrome is open with auto-connect enabled before a headed run, or use
```
--headless
```
for public data.

Write the goal as the data the user wants, not the clicks: "fetch open roles with title, location and team from the careers page, including pagination" works better than "click the jobs tab".

bash

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

该命令在不打开浏览器的情况下验证提示词、URL、配置和环境。运行前应修复每个

error

检查项。当 SDK 通过其他方式进行身份验证时（例如使用已登录的 Claude Code），API key 出现

warn

是可以接受的。

输出中的

would_run.agent_provider

表示本次运行将使用的浏览器。

chrome-mcp

表示使用用户自己的 Chrome 及用户的登录状态；

auto

和

agent-browser

会启动一个不带用户登录状态的新浏览器。当任务需要用户登录，而 provider 不是

chrome-mcp

时，切换 provider 前应先征得用户同意（参阅会话）。

对于

chrome-mcp

，

chrome-mcp:auto-connect

检查项用于测试与用户 Chrome 的连接：

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

目标应描述用户想要的数据，而不是点击操作。例如，“从招聘页面获取包含标题、地点和团队的开放职位，并包含分页”比“点击 Jobs 标签页”效果更好。

4. Capture and generate

4. 抓取并生成客户端

A run takes several minutes, often longer than a shell tool's default timeout. Start it in the background from the outset, with your shell tool's background option when it has one, or with

bash

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

--json-stream

writes one NDJSON event per line and ends with a

{"event":"result",...}

line. The run is finished when that line appears in

rae-run.ndjson

, or when the process in

rae-run.pid

has exited (

kill -0 "$(cat rae-run.pid)"

fails). Check progress with

tail rae-run.log

. Never start a second capture while one is still running: it repeats the work and the cost.

Without
```
--headless
```
,
```
chrome-mcp
```
opens its own tab in the user's Chrome and closes only that tab. Tell the user before starting, since it acts in their browser, and ask them to accept the connection prompt Chrome shows: if nobody accepts it, the run times out without a client.
Add
```
--headless
```
for public sites, or on machines without a display.
Add
```
-o <dir>
```
to write runs somewhere other than
```
~/.reverse-api/runs
```
.
```
--json
```
prints the same result as a single object at the end, with no progress. Use it only when the shell can wait for the whole run.
See sessions and blocked sites for logged-in sites and providers.

The final result line has these fields:

Field	Meaning
`status`	`ok` or `error`
`run_id`	Id for `engineer` , `run` and `show`
`script_path`	The generated client, inside `<runs>/scripts/<run_id>/` next to its `README.md`
`har_path`	The raw capture; `null` for `chrome-mcp` runs, which keep no HAR
`usage.total_cost_usd`	Model cost of the run; report it to the user
`error_kind`	Set on failure; see troubleshooting

Exit codes:

success,

capture or engineering failed,

misuse.

一次运行需要数分钟，通常会超过 shell 工具的默认超时时间。应从一开始就在后台运行；如果 shell 工具支持后台选项，应使用该选项，也可以使用

：

bash

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 可以等待整个运行完成时使用它。
有关登录网站和 provider，请参阅会话与受阻网站。

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

字段	含义
`status`	`ok` 或 `error`
`run_id`	用于 `engineer` 、 `run` 和 `show` 的 ID
`script_path`	生成的客户端，位于 `<runs>/scripts/<run_id>/` 中，旁边有 `README.md`
`har_path`	原始抓取结果；对于不保留 HAR 的 `chrome-mcp` 运行，该值为 `null`
`usage.total_cost_usd`	本次运行的模型成本；应向用户报告
`error_kind`	失败时设置；参阅故障排除

退出码：

表示成功，

表示抓取或客户端生成失败，

表示使用方式错误。

5. Verify the client

5. 验证客户端

Read the generated client and its

README.md

before running anything: it is model-written code. Then run it:

bash

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

--auto-install

installs missing dependencies without prompting; ask the user first. Check that the output contains real data from the site, not just a 200 status.

运行任何代码前，先阅读生成的客户端及其

README.md

：这是模型编写的代码。然后执行：

bash

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. Iterate on the same capture

6. 基于同一次抓取结果进行迭代

bash

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

Without

--fresh

, the prompt is layered on top of the original goal and the existing client. With

--fresh

, the client is regenerated from the HAR.

engineer

needs a HAR, so it only works on runs from the

auto

agent-browser

providers and from manual mode; on a

chrome-mcp

run it exits

with

error_kind: misuse

. For those, or when the capture itself is missing an endpoint, run

agent

again with a more specific goal.

bash

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

provider 的运行以及手动模式；对于

chrome-mcp

运行，它会退出并返回

，同时设置

error_kind: misuse

。对于这类运行，或抓取结果本身缺少 endpoint 的情况，应使用更具体的目标再次运行

agent

。

7. Hand it over

7. 交付客户端

The client lives at

script_path

from the result. When

real_time_sync

is on (the default), rae also copies it to

./scripts/<descriptive_name>/

in the working directory; copy it from

script_path

when that folder is missing. Adapt names and types to their codebase, and keep the generated

README.md

as usage notes. Tell the user which endpoints it wraps and how auth is handled (cookies, bearer token, CSRF), since captured credentials expire.

客户端位于结果中的

script_path

。当

real_time_sync

开启时（默认开启），rae 还会将其复制到工作目录中的

./scripts/<descriptive_name>/

；如果该文件夹不存在，则从

script_path

复制。根据用户代码库调整名称和类型，并保留生成的

README.md

作为使用说明。告知用户客户端封装了哪些 endpoint，以及身份验证如何处理（cookies、bearer token、CSRF），因为抓取到的凭据会过期。

Boundaries

边界

Only capture sites the user is allowed to access, and respect their terms and rate limits.
Captures can contain cookies and tokens. Do not paste HAR contents into chats, issues or commits.
When a site needs a human (captcha, 2FA, unusual login), ask the user to capture it in manual mode, then continue with
```
engineer
```
. See sessions and blocked sites.

仅抓取用户有权访问的网站，并遵守其服务条款和速率限制。
抓取结果可能包含 cookies 和 token。不要将 HAR 内容粘贴到聊天、issue 或 commit 中。
当网站需要人工操作（验证码、2FA 或非常规登录）时，请让用户在手动模式下完成抓取，然后使用
```
engineer
```
继续处理。参阅会话与受阻网站。