browser-act-skill-forge

browser-act-skill-forge

由 BrowserAct 构建 — 您的个人数据抓取工程师 · GitHub

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

对于大批量提取任务（数百或数千条记录、多个关键词、跨页提取），正确的做法是：先探索并构建经过验证的 Skill，再大规模执行。未经验证便直接批量抓取很脆弱——反机器人检测、分页边缘情况和会话中断都会导致执行不可靠。

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

所有数据都保留在本地：流量检查、HAR 记录和提取结果都存储在用户的设备上，不会发送到目标网站以外的任何地方。

语言

所有面向用户的过程输出（计划确认、进度更新、过程通知）均使用用户的语言。生成的 Skill 文件内容使用此 Skill 的语言。

---

Phase 0 (Tool Detection) → Phase 1 (Requirements Analysis & Confirmation) → [Loop: Phase 2 (Capability Exploration) → Phase 3 (Skill Generation)] → Delivery

---

阶段 0 — 工具检测

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

通过 Skill 工具调用 browser-act 以加载用法。如果加载时出现安装或配置问题，请按照其指导解决后重试。

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

---

阶段 1 — 需求分析与确认

1a. 解析业务意图

从用户输入中识别：

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

输入类型	示例	处理方式
明确（URL + 目标）	"抓取 news.ycombinator.com 上的首页文章"	跳过 1b，转到 1c
半明确（已知平台，无 URL）	"帮我监测微博舆情"	执行 1b 研究流程
纯目标（仅业务意图）	"跟踪竞争对手的价格变化"	执行 1b，研究候选网站

如果核心目标过于模糊，无法继续，请询问用户以澄清需求。

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

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

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

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

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

如果没有现成的 Skill，完成拆解，并一次性向用户确认所有信息——此后不再针对各项能力单独追问：

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

Target site: {url}
Output: output/{skill-name}/

Capabilities (executed in order):
1. {site-slug}-{capability-slug} ({extraction/operation}) — {one-line description}
2. {site-slug}-{capability-slug} ({extraction/operation}) — {one-line description}
...

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

Pipeline:
1. Explore site → discover and verify viable API endpoints or DOM extraction methods
2. Generate Skill files (SKILL.md + scripts)
3. Automated testing to confirm Skill works
4. Install Skill
5. Read installed Skill → write and run batch scripts to fulfill user's original task

向用户展示计划，并等待用户确认或调整。对于有合理默认值的项目（输出目录、命名惯例等），不要单独提问。

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

---

以下阶段 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/）供生成的 Skill 的未来 Agent 使用——探索和生成阶段都不得读取或写入。

---

阶段 3 — Skill 生成

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

3a. JS 封装

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

1. 识别业务参数（关键词、页码、排序顺序等）→ 提取为 argparse 参数
2. 在 JS f-string 中将选择器、字段映射、端点 URL 写为固定值
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 / Network 捕获 / DOM / 混合）。

3d. 合规性自检

必须通过两项检查——阅读生成的文件并执行验证命令作为依据；仅凭主观判断不算：

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

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

---

交付流程

生成所有能力后，按以下顺序继续：

1. 自动化测试

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

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

Read {absolute path to SKILL.md} as your execution guide.

Test cases:
{auto-generated test case list, each annotated with which component it covers}

Execution requirements:
- Follow SKILL.md instructions strictly, don't use methods outside the guide
- Record specific issues if SKILL.md instructions are unclear and prevent progress

Report after execution:
1. Execution result per component (pass/fail)
2. Failure reasons (if any)
3. Unclear parts in SKILL.md instructions (if any)
4. Severe accuracy or performance issues (don't report non-severe)
5. Output data summary

测试失败 → 修复 Skill 并重新测试，直至通过。

2. 安装 Skill

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

3. 报告结果

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

• 生成的 Skill 列表（名称 + 路径 + 包含的文件）
• 数据覆盖情况（字段 + 状态，不列出数据源或实现方式）
• 覆盖不完整的缺口（失败的枚举参数、缺失的目标字段、未覆盖的筛选条件等）
• 测试结果摘要

4. 执行（如果第 1 阶段识别出执行意图）

如果第 1 阶段识别出执行意图：

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

如果未识别出执行意图（用户只想构建 Skill 以供日后使用），则到此结束。

---

工具约束

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

文件管理

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

browser-act

• 网络数据仅限当前页面 — 导航到新页面后，必须重新等待并读取
• 读取流量前等待网络稳定：无论是由页面导航还是 UI 交互触发，都要先使用 wait stable，再读取 network requests
• 操作异步 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（原因：生成的 Skills 旨在实现零配置部署，无需用户注册开发者 API 密钥或管理凭据）。解决方案必须通过浏览器直接访问目标网站，使用其前端内部端点或 DOM 数据 — 也就是已向经过身份验证的用户显示的相同资源。

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

JS 执行环境约束

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

结论标准

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

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

效率规则

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

规则	说明
复合求值	将多个相互独立的查询合并到一次求值中，用异步 IIFE 包装，并返回 JSON 摘要。每次求值都算一次浏览器往返——尽可能合并所有可合并的内容
优先运行时	信息获取优先级：JS 运行时状态 → 网络数据 → DOM。绝不要从 DOM 反向推断运行时数据
控制输出量	在浏览器内从大型响应中提取关键字段（数量、总数、样本）后再返回；避免输出被截断
合并异步等待	对等待条件使用 Promise + setTimeout 轮询（设置超时上限），不要通过多个工具反复轮询
快速识别权限限制	出现受限信号（升级提示、数据与未筛选时完全相同、控件已禁用）时，应将类似项目批量标记为受限，不要逐一验证
只获取一次，多次分析	同一来源的数据只获取一次，保存后再多次分析；为长文本添加换行，避免输出被截断
验证后立即停止	一旦确认 API 端点可用（请求成功且数据结构符合预期），就立即进入下一阶段，不要继续对同一端点进行冗余探索（例如反向搜索脚本标签、提取额外配置）
批量处理滑块／范围控件	范围滑块（例如 noUiSlider）和数值范围控件——与 input/select 一样，一次性为所有控件设置不同值 → 触发一次搜索 → 从请求中读取所有 numericFilters 映射，不要逐个测试控件