browser-to-api

Browser to API

基于回放的 API 发现。读取 browser-trace 捕获记录，配对 CDP 请求 / 响应事件，将观测到的 URL 模板化，根据样本推断 JSON 架构，并生成一份 OpenAPI 3.1 文档和一份易读的覆盖率报告。

此技能不会捕获流量。它只会对 browser-trace 的 cdp/network/*.jsonl 数据桶进行离线后处理。这两个技能可以组合使用：

browser-trace    →  .o11y/<run>/cdp/network/{requests,responses}.jsonl
browser-to-api   →  .o11y/<run>/api-spec/index.html + openapi.yaml + client.mjs

适用场景

• 用户需要为第三方网站或未公开文档的网站 API 生成 OpenAPI 文档。
• 用户有一次 browser-trace 运行记录，并希望从中提取端点和架构。
• 用户正在为未发布规范的网站构建客户端 / SDK。
• 用户需要一份覆盖率报告，以了解哪些流程可以扩展规范。

如果用户想要捕获流量，请先引导他们使用 browser-trace。

两步工作流

1. 使用 browser-trace 捕获（也可通过 browse network on 捕获响应体）

# Local example against an existing debuggable Chrome target
TARGET=9222

node ../browser-trace/scripts/start-capture.mjs "$TARGET" my-site
browse open about:blank --cdp "$TARGET"
browse network on                                    # capture request/response bodies
browse open https://example.com
# ...drive whatever flows you want covered...

# Snapshot the bodies dir BEFORE turning capture off (the temp dir is shared
# per-session, so subsequent `browse network on` runs would mix your bodies
# with whatever a future capture writes if you skip this step).
cp -r "$(browse network path | jq -r .path)" .o11y/my-site/cdp/network/bodies/
browse network off

node ../browser-trace/scripts/stop-capture.mjs my-site
node ../browser-trace/scripts/bisect-cdp.mjs my-site

browse network on 可选，但强烈建议使用——如果不启用，规范将没有响应体架构（browse cdp 使用的 CDP 数据流不会嵌入响应体）。启用后，请求体（已由 CDP 捕获）和响应体都会通过 CDP requestId 合并到跟踪记录中。

2. 生成规范

node scripts/discover.mjs --run .o11y/my-site
# → .o11y/my-site/api-spec/index.html          ← open this
#   .o11y/my-site/api-spec/client.mjs
#   .o11y/my-site/api-spec/openapi.yaml
#   .o11y/my-site/api-spec/openapi.json
#   .o11y/my-site/api-spec/report.md
#   .o11y/my-site/api-spec/confidence.json
#   .o11y/my-site/api-spec/samples/*.json
#   .o11y/my-site/api-spec/intermediate/*.jsonl

discover.mjs 会自动检测 <run>/cdp/network/bodies/。若要使用其他位置的响应体捕获记录（例如未创建快照，或想使用实时的 browse network 目录），请显式传入 --bodies <path>。

3. 打开 HTML 报告

discover.mjs 完成后，务必打开生成的 HTML 报告：

open .o11y/my-site/api-spec/index.html

该报告是一个独立的 HTML 文件（无需服务器），其中每个发现的操作都会显示为可展开的卡片，包含变量、客户端用法、请求 / 响应示例，以及底部生成的 client.mjs 代码片段。这是主要交付内容——务必为用户打开。

CLI 标志

标志	必需	含义
--run <path>	是	browser-trace 运行目录的路径
--out <path>	否	输出目录；默认为 <run>/api-spec/
--bodies <path>	否	要合并到跟踪记录中的 browse network 捕获目录（存在时会自动从 <run>/cdp/network/bodies/ 检测）
--include <regex>	否	仅包含与正则表达式匹配的 URL（可重复指定）
--exclude <regex>	否	排除与正则表达式匹配的 URL（可重复指定；在默认规则之外追加）
--origins <list>	否	以逗号分隔的来源允许列表（例如 api.example.com,example.com）
--format <yaml|json|both>	否	输出格式。默认为 both
--title <string>	否	OpenAPI info.title。默认根据主要来源生成
--redact <list>	否	要脱敏的额外标头名称 / JSON 键（以逗号分隔）
--min-samples <n>	否	要纳入的每个端点的最小样本数。默认为 1
--stage <name>	否	仅运行一个阶段：load、filter、normalize、infer、emit

输出布局

<run>/api-spec/
├── index.html                visual report — open this (self-contained, no server)
├── client.mjs                zero-dep fetch client with typed functions per operation
├── openapi.yaml              machine-readable spec
├── openapi.json              mirror
├── report.md                 markdown summary + curl examples
├── confidence.json           per-endpoint confidence + normalization flags
├── samples/                  redacted request/response examples
│   └── <method>__<path-hash>.json
└── intermediate/             pipeline byproducts (paired/filtered/endpoints jsonl)

browse cdp 和 browse network 的输出

两种互补的捕获来源：

来源	提供内容	局限
browse cdp（由 browser-trace 使用）	请求方法、URL、请求头、postData，响应状态、响应头、mimeType，以及完整的事件计时信息	不会嵌入响应正文。 必须通过 Network.getResponseBody 获取正文，而 firehose 不会这样做。
browse network on（单独的命令）	将请求正文和响应正文保存在磁盘上，并以 CDP requestId 为键	捕获目录由每个 browse 会话共享；在另一次 browse network on 覆盖它之前，请先保存快照。

如果传入 --bodies <path>，discover.mjs 会从 browse network 目录中获取正文（或者将它们存放在 <run>/cdp/network/bodies/ 下，系统会自动检测）。匹配依据是 requestId——browse network 会将其写入每个 request.json 的 id 字段，我们会直接按此进行关联。

存在正文时会有什么变化：

• ✅ 路径模板、查询参数架构、状态码、内容类型——两种情况都相同。
• ✅ 请求正文架构——CDP 中的 postData 已足够；对于不属于 postData 的情况，正文目录是很有用的补充。
• ✅ 响应正文架构——根据真实样本进行完整推断。没有正文时，会得到 { description, content: <mimeType> } 骨架。

报告会标记没有响应正文样本的所有端点。

自动过滤噪声

normalize 阶段会自动分类并丢弃基础设施噪声：

• 跟踪／分析——路径包含 /track、/pixel、/beacon、/impression、/pageview、/dag/v*
• 机器人防护——Akamai（/akam/）、指纹载荷（sensor_data）、混淆的多段路径
• 会话处理——/session、/authenticate/start、Cookie 同意、A/B 实验端点
• HTML 页面渲染——返回 text/html 的 GET 请求（渲染后的页面，而非 API）

通常会过滤掉 60-80% 的捕获流量。--include 标志可恢复被误判为噪声的内容。

GraphQL／多路复用端点拆分

当同一个端点（例如 /dapi/fe/gql）使用不同的 operationName 值进行调用时，该技能会自动将其拆分为独立的逻辑操作。每个操作都有自己的：

• OpenAPI 路径条目（例如 /dapi/fe/gql [Autocomplete]）
• 仅根据该操作的样本推断出的请求／响应架构
• 报告中的 Curl 示例和变量表

检测依据包括正文中的字段（operationName、method、action）和查询参数（opname、op）。这适用于 GraphQL（APQ 和内联）、JSON-RPC 及类似的分发模式。

局限性

• 覆盖范围受捕获的流量限制。 跟踪中未触发的端点不会出现。该技能无法证明覆盖完整。
• 架构是归纳得出的，并非契约。 即使每个样本都包含某个字段，该字段在服务端也可能是可选的。
• 观察到的是身份验证信息，而非规范。 该技能会在 x-observed-auth 扩展中记录类似身份验证的请求头，但不会声明安全方案。
• 路径模板采用启发式方式。 系统会按路径段检测数字、UUID、十六进制和 slug 模式。含义不明确的 URL 会在 confidence.json 中标记。
• 脱敏尽力而为。 默认脱敏规则会覆盖常见凭据，但特定于应用的密钥仍可能泄露；对于已知的自定义请求头／密钥，请使用 --redact。

最佳实践

1. 演练你希望记录的流程。 浏览器追踪越丰富，规范就越详尽。
2. 对于噪声较多的网站，使用 --origins。 营销页面会访问数十个分析主机；请将范围限制为你关注的 API 来源。
3. 先查看 report.md。 其中包含每个发现的操作对应的 curl 示例和响应样例，可直接使用。
4. **将 --min-samples 提高到 2 以上，**这样最终文档中只会包含结构明确的端点，并剔除长尾内容。
5. **与 browse network on 配合使用，**以便了解响应正文的架构。单靠 CDP 数据流只能获取请求正文，无法获取响应正文。

有关流水线内部机制和文件格式参考，请参阅 REFERENCE.md。