browser-act-skill-forge

browser-act-skill-forge

将任意网站的数据提取或操作需求转化为 Agent 可调用的能力。用户描述要在哪个网站上获取什么数据或执行什么操作，本技能自动探索实现路径（优先 API 端点，无 API 时回退到 DOM），验证后生成可直接部署的技能包（SKILL.md + Python 脚本）。一次探索，永久复用——后续调用无需重复探索，大幅提升执行可靠性和效率。

对于大规模提取任务（数百或数千条记录、多个关键词、跨分页），正确的方法是：先探索构建已验证的技能，再大规模执行。没有经过验证的策略直接批量爬取是脆弱的——反爬检测、分页边界情况和会话中断会使其不可靠。

本工具的操作边界 = 用户能在浏览器中手动完成的操作。它通过用户已登录的浏览器访问，仅读取页面上已向用户展示的数据，绝不绕过身份验证或访问控制。相当于替用户复制粘贴——自动化仅节省手动操作。

所有数据保留在本地：流量检查、HAR 记录和提取结果存储在用户机器上——不会发送到目标站点之外。

语言

所有向用户输出的过程（计划确认、进度更新、流程通知）遵循用户的语言。生成的技能文件内容遵循本技能的语言。

---

阶段 0（工具检测）→ 阶段 1（需求分析与确认）→ [循环：阶段 2（能力探索）→ 阶段 3（技能生成）] → 交付

---

阶段 0 — 工具检测

当前会话中已完成 → 跳过。

通过技能工具调用 browser-act 加载使用说明。如果加载过程中出现安装或配置问题，按照其指引解决后重试。

成功加载后，确认 API Key 已配置（如果未配置 → 引导用户注册并配置，然后重试）。

---

阶段 1 — 需求分析与确认

1a. 解析业务意图

从用户输入中识别：

• 核心目标：获取什么数据 / 完成什么操作
• 目标网站：是否给出了具体 URL 或平台名称
• 执行意图：用户是否希望立即执行（不仅仅是构建一个技能供以后使用）。包括批量/数量需求（N 条记录、多个关键词）或暗示“立即执行”的单次请求
• 输出目录：默认为当前工作目录下的 output/，如果用户指定则覆盖

输入类型	示例	处理方式
明确（URL + 目标）	"抓取 news.ycombinator.com 的头版文章"	跳过 1b，进入 1c
半明确（已知平台，无 URL）	"帮我监控微博舆情"	执行 1b 研究路径
纯目标（仅业务意图）	"跟踪竞品价格变化"	执行 1b 研究候选网站

如果核心目标过于模糊无法继续，要求澄清。

1b. 目标网站研究（未提供明确 URL 时）

不要基于模型内部知识推荐——主动搜索以找到托管所需数据的网站：

1. 根据业务意图构建搜索查询，从结果中识别候选网站
2. 向用户推荐 1–5 个候选网站，按数据价值排序并附优缺点（包括数据可靠性）
3. 用户选择后，确认目标 URL

1c. 任务分解与执行计划确认

确认目标网站后，首先检查：是否已有针对该网站/能力的已安装技能？如果是 → 告知用户并跳转到交付步骤 4（批量执行）。

如果没有现有技能，完成分解并一次性向用户确认所有信息——之后不再逐个能力追问：

1. 识别涉及的独立阶段（搜索、列表页、详情页、登录、提交……）
2. 确定类型：提取（获取数据） vs 操作（执行动作）
3. 拆分标准：如果更换业务目标，该阶段能否独立复用？能 = 独立能力。 服务于同一业务目标的跨页面步骤（例如列表页收集 + 详情页提取）作为一个能力，通过复合组件编排
4. 设置 skill-name 和能力目录名称（小写英文，连字符分隔），在 output/{skill-name}/ 下创建目录（如果用户指定了路径则使用）
5. 向用户确认完整执行计划：

目标网站：{url}
输出：output/{skill-name}/

能力（按顺序执行）：
1. {site-slug}-{capability-slug}（提取/操作）— {一行描述}
2. {site-slug}-{capability-slug}（提取/操作）— {一行描述}
...

如果在 1a 中识别到执行意图，在计划中追加：

流水线：
1. 探索网站 → 发现并验证可行的 API 端点或 DOM 提取方法
2. 生成技能文件（SKILL.md + 脚本）
3. 自动化测试确认技能可用
4. 安装技能
5. 读取已安装技能 → 编写并运行批量脚本以完成用户的原始任务

展示计划并等待用户确认或调整。不要就具有合理默认值的项目（输出目录、命名约定等）单独提问。

用户确认后，进入执行循环，过程中不再提问。

---

下面的阶段 2 和阶段 3 对每个能力单元循环执行——完成一个后再开始下一个。

---

阶段 2 — 能力探索

根据能力类型读取相应的参考文件：

• 提取 → references/exploration_extraction.md
• 操作 → references/exploration_operation.md

目标：优先为目标能力寻找 API 端点；当 API 不可行时回退到 DOM 操作。记录完整的可复现调用方法。

成功标准：

• 能够稳定获取目标数据 / 触发目标操作（API 或 DOM 路径）
• 记录完整的调用/操作方法（端点 + 参数，或选择器 + 交互步骤）
• 收集所有有意义的枚举参数值

当某种方式失败时，按以下顺序进行：

1. 不要用不同参数重试（改变参数很少改变结果）
2. 回到目标本身
3. 列举所有可能实现目标的替代方式
4. 选择下一个并执行

确定性失败（明确错误码、结构不匹配）一次尝试即可确认方式不可行。临时性失败（超时、连接断开）可重试一次——但不要更多。

探索上限：100 个工具调用步骤。如果仍然无法推进，向用户报告已知障碍并询问下一步。

不要触碰经验笔记：经验笔记（browser-act-skill-forge-memories/）供生成的技能未来 Agent 使用——在探索和生成阶段既不读取也不写入。

---

阶段 3 — 技能生成

读取 references/output_template.md 了解文件格式规范。

3a. JS 封装

将探索中验证过的每个 JS 片段封装为独立的 Python 文件：

1. 识别业务参数（关键词、页码、排序方式等）→ 提取为 argparse 参数
2. 将选择器、字段映射、端点 URL 硬编码为 JS f-string 中的固定值
3. 转义 JS 花括号为 {{ }}（f-string 语法要求，否则 Python 会报错）
4. 写入 scripts/{feature-name}.py

3b. 封装验证

对每个 .py 文件进行端到端验证：

1. python scripts/{feature-name}.py {test-params} — 确认输出是有效的 JS 字符串
2. eval "$(python scripts/{feature-name}.py {test-params})" — 确认浏览器执行结果与探索阶段一致
3. 模拟错误场景（例如不存在的 ID、导航到错误页面），确认返回 {"error": true, "message": "..."} 而不是崩溃

验证失败 → 修复 .py 文件并重试，绝不跳过。

3c. 生成 SKILL.md

按照模板创建 SKILL.md，能力组件部分引用 scripts/*.py 的调用命令（不内联 JS）。

输出目录结构：

output/{skill-name}/{site-slug}-{capability-slug}/
├── SKILL.md
└── scripts/
    └── {feature-name}.py

生成后，简要告知用户：能力名称、输出路径、主要实现方式（API / 网络捕获 / DOM / 混合）。

3d. 合规自查

两项检查——必须读取生成的文件并执行验证命令作为证据；仅凭心理断言不算：

1. 过程：重新读取阶段 2 中使用的探索参考文件和上述输出步骤（3a–3c），确认每个定义的步骤确实已执行，未跳过
2. 输出：读取生成的 scripts/*.py 和 SKILL.md，对照 output_template.md 中的填充规范以及本技能前面定义的代码 / JS 执行环境 / DOM 操作约束进行检查

发现任何差距 → 返回，完成缺失步骤或修复输出，然后重新验证。

---

交付流程

所有能力生成后，按以下顺序进行：

1. 自动化测试

生成后立即开始测试——无需用户确认。根据生成的能力组件自动设计最小测试用例——使用最少的输入覆盖所有功能路径（每个原子组件至少调用一次，复合组件运行完整流程）。

必须通过子 Agent 执行测试——不要在主会话中直接测试。发送以下提示：

读取 {SKILL.md 的绝对路径} 作为你的执行指南。

测试用例：
{自动生成的测试用例列表，每个标注覆盖的组件}

执行要求：
- 严格遵循 SKILL.md 的指令，不要使用指南之外的方法
- 如果 SKILL.md 指令不明确导致无法推进，记录具体问题

执行后报告：
1. 每个组件的执行结果（通过/失败）
2. 失败原因（如有）
3. SKILL.md 指令中不明确的部分（如有）
4. 严重的准确性或性能问题（不报告非严重问题）
5. 输出数据摘要

测试失败 → 修复技能并重新测试直到通过。

2. 安装技能

从输出目录安装生成的技能。如果安装失败，技能保留在输出目录中，仍可在步骤 4 中直接使用。

3. 报告结果

测试通过后，向用户报告：

• 生成的技能列表（名称 + 路径 + 包含的文件）
• 数据覆盖范围（字段 + 状态，不要列出数据来源或实现方法）
• 未完全覆盖的差距（失败的枚举参数、缺失的目标字段、未覆盖的过滤条件等）
• 测试结果摘要

4. 执行（如果在阶段 1 中识别到执行意图）

如果在阶段 1 中识别到执行意图：

1. 通过技能工具调用已安装的技能以读取其完整内容。如果步骤 2 中安装失败，则直接从输出目录读取 SKILL.md
2. 按照技能的指令在当前会话中执行用户的原始任务
3. 对于批量/数量任务，根据技能的指导编写批量执行脚本

如果未识别到执行意图（用户只想构建一个技能供以后使用），在此结束。

---

工具约束

阶段 2（能力探索）、阶段 3（技能生成）和交付测试必须遵循以下规则。

文件管理

所有中间产物（HAR 文件、临时记录、调试输出）放入 tmp/ 目录。如果目录不存在，先创建。

browser-act

• 网络数据是页面范围的——导航到新页面后必须重新等待和重新读取
• 在读取流量前等待网络稳定：无论是页面导航还是 UI 交互触发，在读取 network requests 之前使用 wait stable
• 在操作异步 DOM 前等待元素：对于异步注入的内容（浏览器扩展、懒加载组件），在交互前使用 wait --selector "{target selector}" --state attached --timeout {ms}
• 不要进行 JS 级别的网络拦截：永远不要覆盖 XMLHttpRequest.prototype、window.fetch 等。使用 network requests / network request <id> 进行端点发现
• 仅在导航/重新加载前使用 network clear：清除流量会丢失所有观察到的请求记录。日常过滤使用 --filter，不要清除。要跟踪特定交互的请求，使用 network har start → 交互 → network har stop，而不是清除后重新读取

DOM 操作约束

适用于所有 DOM 操作场景（数据提取、枚举收集、分页控制、表单提交、API 字段补充）：

选择器优先级：data-testid > id > name > aria-label > structural path。除非结构确实稳定，否则避免纯位置索引（:nth-child / [1]）。

批量验证选择器：在单个 eval 调用中测试所有候选选择器，返回 JSON 摘要（每个选择器的命中数、第一个元素的关键属性、唯一性）。永远不要逐个 eval 选择器——每次 eval 都是一次浏览器往返。

Shadow DOM：当目标元素位于 Shadow Root 内时，通过 element.shadowRoot.querySelector 访问，将选择器分为两部分（宿主元素 + Shadow 内部路径）。

三层选择器验证：元素断言（预期属性匹配）→ 结果检查（非空、合理数量）→ 成功标准。必须在真实页面上测试，绝不能根据 DOM 结构推测编写。

控件扫描（枚举收集期间）：使用一次 eval 返回所有目标控件的完整映射（tag+type / name+id / placeholder / label）。从控件向上遍历找到最近的表单项容器以获取标签文本；不要硬编码组件库类名；组件库通过 DOM 层级嵌套关联标签和输入框，而不是 label[for="xxx"]。

state 索引动态分配：state 返回的元素索引是每个会话动态分配的——永远不要将其写入策略代码，仅在执行时实时使用。

代码约束

必须直接操作目标网站：绝不通过外部服务（包括第三方爬取平台、数据聚合 API、代理服务）获取数据，也绝不调用目标网站的官方开放平台 API（理由：生成的技能目标是零配置部署，无需用户注册开发者 API 密钥或管理凭据）。解决方案必须通过浏览器直接访问目标网站，使用其前端的内部端点或 DOM 数据——即已登录用户已经可见的相同资源。

框架内部状态快速失败：当尝试通过框架内部（__vue_app__、$data、React fiber、Angular ng 等）访问页面数据或元素信息时，一次失败后放弃，立即切换到 state 扫描 + 值填充触发方式。框架内部状态依赖于版本/实现，多次重试不会改变结果。

JS 执行环境约束

在 eval 中执行的代码是浏览器端 JS：只能使用浏览器原生 API 和页面加载的第三方库，不能 require/import 外部模块。违反此约束的代码在执行时必然出错。

结论标准

账户权限限制 ≠ 技术方案失败。付费功能、会员等级等同样影响所有方法；当 API 技术上可行但由于账户权限导致数据受限（分页截断、过滤条件无效）时，结论为“通过”，并在“已知限制”中注明权限依赖。

部分成功算成功：核心能力已验证可用（无论是 API 还是 DOM 路径）算通过——即使某些枚举参数标记为 [collection failed]、非核心字段缺失、某些过滤条件未覆盖。生成技能后，必须告知用户哪些部分未完全覆盖——绝不能默默忽略。

效率规则

核心标准：每次浏览器往返必须带来信息增益。 下表展示了常见的高效模式，但仅为示例——如果某种模式在实践中并未减少往返次数，则改变方法，寻找其他批量方式，而不是在同一方向上反复微调。

规则	描述
复合 eval	将多个独立查询合并为一次 eval，包装在异步 IIFE 中，返回 JSON 摘要。每次 eval 是一次浏览器往返——合并所有可合并的内容
运行时优先	信息检索优先级：JS 运行时状态 → 网络数据 → DOM。永远不要从 DOM 反向工程运行时数据
输出量控制	在浏览器内从大型响应中提取关键字段（计数、总数、样本）后再返回；避免截断
异步等待内聚	使用 Promise + setTimeout 轮询（带超时上限）实现等待条件，不要跨工具重复轮询
快速权限受限检测	当出现受限信号（升级提示、数据与未过滤时相同、控件禁用）时，批量标记类似项目为受限，不要逐个验证
一次获取，多次分析	从同一来源仅获取一次数据，保存后多次分析；用换行符格式化大文本以避免截断
验证即止	一旦 API 端点确认可用（获取成功 + 数据结构符合预期），立即进入下一阶段，不要继续对同一端点进行冗余探索（例如反向搜索脚本标签、提取额外配置）
滑块/范围控件批量	范围滑块（例如 noUiSlider）和数值范围控件——与 input/select 类似，将所有控件设置为不同值 → 触发一次搜索 → 从请求中读取所有 numericFilters 映射，不要单独测试每个控件