通过迭代实验自动构建可靠的浏览器自动化技能

当需要为特定网站任务构建或改进浏览器自动化技能时，用「评估→读轨迹→改策略」循环反复迭代直到稳定通过。

适用场景

解决思路

1. 解析参数并确定模式：--task <name> 单任务模式；--tasks a,b,c 或 --all 多任务模式（派生子代理）；--iterations N 指定评估→改进循环次数（默认 5）；--env local|remote 指定浏览器环境（默认 local，反爬站点用 remote）；--browser-trace 启用 browser-trace 集成（默认关闭，隐含 --env remote，若与 --env local 同时显式传入则报错）。若用户传入自由文本或 URL，则匹配已有任务或新建 kebab-case 任务名并基于 references/example-task.md 创建 task.md。
2. 在当前工作目录（而非 ~/.claude/skills/）建立工作区：mkdir -p ./autobrowse/tasks ./autobrowse/traces ./autobrowse/reports；若任务目录不存在则 mkdir -p ./autobrowse/tasks/<task> 并从 ${CLAUDE_SKILL_DIR}/references/example-task.md 复制生成 task.md，再编辑描述 URL、输入、步骤和期望的 JSON 输出。技能源目录保持只读。
3. 多任务模式下用 Agent 工具为每个任务并行派生一个子代理，传入自包含提示：指定任务名、工作区绝对路径、迭代次数、--env 值，要求每次 evaluate.mjs 调用都传 --workspace；若父调用用了 --browser-trace 则必须走 traced-path 流程；毕业时写入 ~/.claude/skills/<task-name>/SKILL.md 并带 agentskills frontmatter；最后输出结构化摘要（任务名、最终通过与否、累计成本、迭代数、每轮表格、2-3 条关键学习）。
4. 确认 ANTHROPIC_API_KEY 在环境变量或 CWD 的 .env 文件中（evaluate.mjs 会自动加载），缺失时直接报错退出，不要到其他路径找密钥。
5. 默认路径（无 --browser-trace）运行内层代理：node ${CLAUDE_SKILL_DIR}/scripts/evaluate.mjs --task <task-name> --workspace ./autobrowse（反爬站点加 --env remote），轨迹写入 ./autobrowse/traces/<task>/latest/。
6. traced 路径（--browser-trace，仅 remote）每轮按顺序执行：先 preflight 检查 ${CLAUDE_SKILL_DIR}/../browser-trace/scripts/bb-capture.mjs 存在；用 browse cloud sessions create --keep-alive --verified --proxies 创建会话并解析出 id 与 connectUrl；设置 RUN_ID=run-NNN、TRACE_ROOT、O11Y_ROOT、O11Y_RUN_ID；后台启动 bb-capture.mjs 并 sleep 2；运行 evaluate.mjs 并传 --connect-url 与 --run-number；依次执行 stop-capture.mjs、bisect-cdp.mjs、unify-trace.mjs；最后 browse cloud sessions update "$sid" --status REQUEST_RELEASE。
7. 读取轨迹：先 cat ./autobrowse/traces/<task-name>/latest/summary.md 查看时长、成本、轮次、决策日志和最终 JSON 输出；失败时读 trace.json 定位失败轮次并查看失败点附近的截图。
8. 使用 --browser-trace 时优先读 unified-events.jsonl（按时间戳交错、带 source 标记的 NDJSON），失败原因通常在一两行相邻事件中；需要下钻时按需查 .o11y/<run-id>/cdp/summary.json（每页统计）、network/failed.jsonl（失败请求）、console/exceptions.jsonl（异常堆栈）、pages/<pid>/（按页切片）、trace.json（按 turn 过滤完整推理）、query.mjs（分组查询）。
9. 形成单一假设：定位出错的具体轮次，提出能避免该问题的单条启发式；使用 --browser-trace 时假设必须引用 unified-events.jsonl 中的具体事件（行号或时间戳）或指明下钻文件，例如「unified-events.jsonl 第 47 行 browse open 后 /api/checkout 返回 403，改用 --verified --proxies」。
10. 更新 ./autobrowse/tasks/<task-name>/strategy.md：保留有效内容，修复具体失败点，加入具体启发式；好策略应包含快速路径（直达 URL）、分步工作流（含时序说明）、站点特定知识（选择器 ID、表单字段名、成功标志）、失败恢复方案。
11. 判断结果：通过或有明确进展则保留并进入下一轮；无进展或回退则把 strategy.md 还原到上一版本并尝试不同假设。
12. 收敛后可选生成可运行脚本：node ${CLAUDE_SKILL_DIR}/scripts/codegen.mjs --task <name> --workspace ./autobrowse --frameworks playwright,stagehand --verify；每个框架在 tasks/<name>/<framework>/ 下生成脚本和自包含脚手架，可独立 npm install && npx tsx 运行；常用标志包括 --frameworks、--verify/--no-verify、--max-retries N、--cache-only、--force、--dry-run、--run <id>。
13. 所有迭代结束后若最近 3 轮中通过 2 次以上或已达最大迭代数，则毕业安装：mkdir -p ~/.claude/skills/<task-name>，写入自包含的 SKILL.md（含 frontmatter 的 name 与 description、Purpose、When to Use、Browse CLI Reference、Workflow 分步、Site-Specific Gotchas、Failure Recovery、Expected Output JSON schema）；不要直接复制 strategy.md；若在最大迭代数时未干净通过，记录已知失败点但仍记录所有学习。
14. 多任务模式结束后打印结果表格（Task、Iterations、Final Status、Graduated、Cost），并写入持久会话报告 ./autobrowse/reports/YYYY-MM-DD-HH-MM-<tasks>.md，包含日期、任务列表、环境、总成本、结果表、每任务学习、每轮迭代日志（轮次、turns、成本、状态、测试的假设）。
15. 遵守规则：只编辑 strategy.md，不动 task.md（除非从模板创建）或 evaluate.mjs；所有训练写入 ./autobrowse/，不写 ~/.claude/skills/autobrowse/；每轮只测一个假设；在成功基础上叠加；信任轨迹；毕业时只写最终 SKILL.md 到 ~/.claude/skills/；使用 --browser-trace 时每轮结束顺序不可变：stop-capture → bisect-cdp → REQUEST_RELEASE。

适用边界 · 注意事项

• 没有 Node.js 18+、browse CLI 或 ANTHROPIC_API_KEY 环境时无法运行。
• 使用 --browser-trace 时若未安装同级 browser-trace 技能或缺少 BROWSERBASE_API_KEY，会直接报错。
• --browser-trace 仅支持 remote 环境，与 --env local 同时显式传入会报错。