derive-client

从录制的会话中推导出 API 客户端

在首次访问时，驱动浏览器是合适的工具；而在第一百次访问时，它就是错误的工具。本技能会在你使用某个网站时录制一次其网络流量，然后将捕获的请求转换为一个独立的客户端（脚本、命令行或库），直接与该网站的内部 API 通信。

仅录制内容本身就包含所需的一切：agent-browser 默认会将文本响应体（JSON/HTML/JS）嵌入 HAR 中，因此即使浏览器关闭，也可以离线研究端点的结构。

工作流

1. Record     Start HAR capture, drive the flows you want in the client
2. Identify   Find the real API endpoints among the noise
3. Extract    Pull request shapes, response schemas, and auth material
4. Generate   Write the client, one function per flow
5. Verify     Call every endpoint for real before declaring done

1. 录制

agent-browser network har start          # embeds text response bodies by default
# ... drive the site: search, open a detail page, paginate, etc. ...
agent-browser network har stop /tmp/site.har

• 演练 客户端应支持的每一条流程，并用不同的输入将每条流程至少运行两次（两个搜索词、两个详情页）。对比录制的 URL 可以揭示哪些部分是参数。
• 如果网站需要登录，请在启动 HAR 之前登录，以免凭据不必要地落入录制内容中。会话 cookie 会在第 3 步单独导出。
• --content all 也会嵌入二进制响应体（base64）；--content none 则禁用嵌入。每个响应体的上限为 2 MB。

在会话仍然打开时，agent-browser network requests 和 network request <id> 可以交互式地提供相同的数据——但只有 HAR 能在导航和浏览器关闭后保留下来，所以对于任何多页面操作，优先使用它。

2. 识别端点

用 jq 查询 HAR：

# All JSON API calls: method, URL, status
jq -r '.log.entries[]
  | select(.response.content.mimeType | test("json"))
  | "\(.request.method) \(.response.status) \(.request.url)"' /tmp/site.har

忽略分析类与基础设施类噪声：遥测端点（/collect、/track、/beacon、/log）、第三方域名（google-analytics、segment、sentry、datadog、intercom、hotjar）以及静态资源。真正的 API 通常是第一方的、JSON 格式的，并且与你执行的操作相关联。

3. 提取结构与认证

# Full detail for one endpoint: request headers, POST body, response body
jq '.log.entries[] | select(.request.url | test("api/search"))
  | {request: {method: .request.method, headers: .request.headers,
     postData: .request.postData.text},
     response: .response.content.text}' /tmp/site.har

• 响应 schema：读取 .response.content.text——这才是真正的载荷，用它来推导类型。
• 认证：比较各端点的请求头。查找 authorization、cookie、x-csrf-token、x-api-key 以及站点特定的 x-* 请求头。只重放真正重要的那些——在第 5 步中通过省略来测试。
• Cookie：用 agent-browser cookies get --json > cookies.json 导出实时会话，供客户端在运行时加载。切勿将 cookie 值硬编码到生成的源代码中。

4. 生成客户端

• 每条录制的流程对应一个函数（search(query)、getItem(id)），并根据观察到的响应体确定类型。
• 认证材料（cookie、bearer token）从文件或环境变量加载，并在其过期时给出清晰的错误，提示用户重新运行浏览器登录。
• 复现 API 实际要求的请求头——有些网站在缺少匹配的 user-agent、referer 或 x-requested-with 时会返回 403。
• 将出现在录制的查询字符串中的分页、排序和筛选参数保留为函数选项。

5. 验证

针对实时 API 调用每个生成的函数，并将响应结构与录制内容进行比较。常见故障：

症状	原因	修复
401/403	会话过期或缺失	通过 agent-browser 重新登录，重新导出 cookie
写入时 403/419	CSRF token 是按会话或按表单的	先请求 token 端点，或让该流程继续由浏览器驱动
先可用后失效	请求参数经过签名或会过期	该步骤回退到浏览器；其余部分自行推导
结构与 HAR 不同	A/B 测试或依赖地理位置的响应	重新录制，并将并集视为可选字段

注意事项

• 内部 API 不进行版本管理，且会在不通知的情况下发生变化——请保留 HAR，以便客户端可以重新推导。
• 遵守网站的服务条款和速率限制；批量抓取时添加延迟。
• HAR 文件包含实时会话凭据（cookie、token、POST 请求体）。请像对待机密一样对待它们：使其远离版本控制，并在完成后删除。