源码教程：批量、配方、后台作业与维护

这些能力不增加新的浏览器原语，而是组合和管理已有命令。重点是避免 HTTP 超时被误认为执行失败，以及区分“取消后续步骤”和“撤销已执行操作”。

1. commands 批量入口

commands 是 ActionService.execute 特殊处理的入口，不包含在 116 个注册方法之中。同步批次逐项解析单命令对象，按顺序调用同一执行层，因此单条与批量应具有一致的截图和错误处理语义。

{
  "id":"1001",
  "method":"commands",
  "params":{
    "stopOnError":true,
    "commands":[
      {"go_to_url":{"url":"https://example.com"}},
      {"get_title":{}},
      {"get_browser_state":{"highlight":false}}
    ]
  }
}

批次不允许嵌套 commands，每项只有一个命令键，有最大步骤数限制。stopOnError 控制遇到失败是否停止，expect 则用来判断业务观察条件；条件失败不能被一次浏览器 API 返回成功掩盖。

页面变化不会自动终止整个批次。依赖新快照索引的点击应放到下一次请求中，不能在同一批次预先猜好未来页面索引。

2. 后台作业

params 加 async=true 时，JobRegistry.submit 将批次交给后台执行器，立即返回 jobId。注册表保存状态、耗时、步骤数、取消标志和最终结果。

状态为 running、done、failed 或 cancelled。记录保存在内存，服务重启后丢失；注册表会清理较旧的已结束作业，不能当成持久化消息队列。

当前 get_job 注册只读取 jobId 与 includeResult。不能因为某条提示提到长轮询，就自行增加未实现的参数并假定服务真的等待；客户端按实际接口查询即可。HTTP 客户端超时后先查询已存在作业，不能重发整个批次。

3. 配方复用

list_recipes 调用 RecipeStore.list，返回可用配方、数量和目录。run_recipe 按 name 读取配方，合并变量并生成 commands，随后仍由公共执行链执行。配方格式与示例见第 14 篇。

配方必须显式点名，不从网站地址猜测执行哪套流程。把稳定步骤放入配方，把需要新快照判断、短信验证或人工确认的分支保留在上层控制逻辑。变量是参数化工具，不是隐含扩大操作权限的机制。

4. 自省与清理

cleanup 真正删除前先核对候选和保留策略。截图、trace 与上传文件可能仍被任务引用，不应为了节省磁盘盲目清空。命令清理运行产物，与关闭浏览器、删除账号或注销商户无关。

5. 验证方法

使用本地页面构造成功、失败、条件不满足的三个步骤，检查 stopOnError 和 expect 的计数及结果。异步测试在第一步与第二步之间发出取消，确认已执行动作保留、后续动作不执行。配方测试对比变量替换结果，不访问真实业务站点。cleanup 先测试 dryRun 无副作用，再在专用临时目录验证筛选条件，禁止将用户真实产物作为清理测试样本。

注册参数与 Java 入口

以下按 CommandTable 实际读取参数整理。* 表示注册层使用必填读取器；其余字段省略后由服务决定默认行为。带条件的入口仍需满足正文说明，例如上传文件来源、元素定位二选一。外层 id 不重复列出。