reverse-eng-site-skill

逆向分析网站 API

遵循一个转换步骤：先监测，再重放。将已登录的浏览器用作经过监测的探针，以确定状态并触发请求。捕获目标请求后，立即停止通过 UI 导航，并改用直接 HTTP 执行。浏览器可以继续作为已认证的传输方式来发送直接请求，或刷新认证信息，但后续步骤不再通过点击网站来操作。

1. 定义操作

按以下格式写出一项可观察的操作：

Given <state>, perform <action>, obtain <exact result>.

将其归类为只读操作或状态变更操作。对于状态变更操作，选择一个可逆的测试对象，并确保批量执行不属于发现阶段。

**完成条件：**操作已归类为只读或状态变更，目标结果明确；对于状态变更操作，已确定一项可逆的测试操作。

2. 捕获一个请求

使用用户现有的已认证浏览器会话。先开始网络捕获，再执行操作；保留日志并清除无关流量，然后执行能产生目标结果的最小 UI 操作，且只执行一次。优先使用包含请求正文且能在导航后继续保留记录的 DevTools Protocol 或 HAR 捕获方式。

记录：

• 方法、完整 URL、查询参数、状态码和发起方
• 请求头和请求正文的结构，并对机密值进行脱敏
• 响应内容类型、大小、顶层结构以及两个非机密的 UI 校验项
• 是否存在 Cookie、授权标头、CSRF 令牌或请求签名

如果有 HAR，请运行：

python <skill-dir>/scripts/har_candidates.py capture.har

此处及下文中的 <skill-dir> 均指包含此 SKILL.md 的目录。

将 capture.har 写入仓库外的私有临时目录。文件可能包含未脱敏的 Cookie 和令牌。存储前请阅读 机密边界。

如果可用的浏览器工具会隐藏请求正文、在导航时丢失事件，或提供多种访问已登录会话的方式，请阅读 references/browser-capture.md。

**完成条件：**至少捕获到一个可能对应确切目标结果的请求，并保存至少一个 UI 校验项。如果 UI 提供两个校验项，则保留一个作为保真度留出项，不要用它来选择端点。如果只有一个校验项，则记录这一情况。已渲染的页面或 DOM 选择器不能作为请求证据。

3. 在 UI 之外重放请求

以捕获到的请求为起点，不要猜测端点。使用 curl、httpx 或网站的原生协议重现请求。首次重放时，准确保留其方法、编码、Cookie、标头和请求正文。以编程方式使用浏览器的 Cookie 存储或已认证请求上下文；在请求用户复制 Cookie 之前，应先用尽这些途径。

在请求用户提供 Cookie 之前，请阅读 references/browser-capture.md 中按顺序排列的认证获取流程。

使用状态码、字节长度、稳定键、项目数量和已捕获的校验项来比较捕获结果与重放结果。当仅限浏览器的反机器人机制或签名请求阻止独立 HTTP 请求时，请在已认证的浏览器中通过 fetch 重放，并记录这一限制，不要改用 DOM 自动化。

**完成条件：**可重复运行的命令返回相同的目标数据，或者通过请求证据证明了具体的浏览器绑定要求。

4. 精简并映射

逐个移除非必要标头。每次只改变一个输入，以映射以下内容：

• 身份与发布、工作区、账户或资源 ID
• 分页或游标、排序、筛选、搜索和限制
• 列表、详情、下载和变更端点
• REST、GraphQL 操作、持久化查询、RPC 批次或流式帧
• 身份验证有效期、CSRF 耦合和刷新行为

对比已通过身份验证和未经身份验证的重放。成功获取公开列表，只能证明该列表是公开的；这并不能说明完整详情、付费内容、私有字段或变更操作也是公开的。

如果请求涉及 GraphQL、框架 RPC、Server Action、批次或流，请阅读 references/protocols.md。

完成标准： 已记录已知的最精简请求，并且已知用户操作所需的每个输入的来源。

5. 验证保真度

在比较样本或测试写入之前，请阅读 references/security-and-validation.md。

将直接响应与第 2 步期间保存的 UI 金丝雀样本进行比较；如果有两个样本，则使用预留的留出样本。比较时不要再通过 UI 导航。报告确切的响应字段。在详情响应证实之前，将预览、摘要、搜索摘要和列表负载视为不完整。保留源数据；对其进行格式化，而不是重构缺失文本。

对于写入操作，使用一个可逆样本，检查响应，并通过独立端点将其读回。

完成标准： 两个受控样本均能重现预期结果，且已测定身份验证与否所产生的差异。对于写入操作，还必须通过读回验证样本。

6. 构建持久客户端

实现已验证的请求，并确保：

• 密钥来自环境变量或浏览器会话，绝不存放在源文件中
• 分页具有经过测试的停止条件
• 设置超时、有限重试和速率限制
• 明确指定输出格式，并保留原始 ID 和字段
• 提供低成本的身份验证检查，并按照验证参考中的失败分类处理
• 对更改状态和批量操作设置试运行或确认关卡

在清理采集产物之前，不要将其纳入版本控制。在持久化请求、处理写入端点或声明客户端已完成之前，请阅读 references/security-and-validation.md。

完成标准： 客户端可在全新进程中运行，已跟踪文件和日志中不含密钥，分页能正确终止，且失败时能指出需要重新发现的环节。更改状态和批量操作均设有试运行或确认关卡。

7. 打包特定站点的技能

复制 assets/site-skill-template 并替换每个占位符。包含已验证的操作、身份验证获取方式、可运行示例、证据日期，以及从重新采集流量开始的修复路径。将站点事实保留在该站点的技能中；本元技能应保持通用。

完成标准： 已替换模板中的每个占位符；全新的 Agent 无需点击 UI 即可运行一个只读操作，并能准确说明站点变更时如何重新采集。

交接

报告：

证据	必需内容
已采集的请求	操作、方法、已脱敏的 URL、状态
重放	命令或脚本路径，以及匹配的金丝雀样本
身份验证	机制、程序化来源、测得的身份验证与否差异
接口面	端点或操作、参数、分页
验证	两个样本，以及适用时的写入读回验证
产物	客户端路径、站点技能路径，以及密钥扫描结果
限制	反机器人、速率、账户、法律或浏览器绑定限制

完成采集后，声明结果为已发现；完成直接重放和保真度检查后，声明为已验证；仅当打包后的客户端能在全新进程中通过测试后，才声明为持久可用。