Skyvern 实战：完成带校验的多步骤表单草稿

多步骤表单难在动作之间有关联：填写数量后总额才更新，附件上传结束后才能继续，校验提示也可能把任务留在前一步。一个“任务成功”标签不足以证明草稿内容正确。

本文面向需要自动化业务表单的开发者。我们用自有测试系统中的三步采购申请作为任务：基本信息、采购明细、预览草稿。只保存草稿并进入预览，不进行正式审批或付款。示例描述的是需要你提供的测试表单，不虚构一个已部署的公共采购站。

准备本地运行环境

使用 Python 3.12，以下终端命令采用 Bash：

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install 'skyvern[all]==1.0.56'

配置当前版本支持的模型 provider。例如采用其 OpenAI 路径时，需要启用 provider、提供自己的 API key，并选择该版本模型注册表中的 LLM_KEY：

export ENABLE_OPENAI=true
export OPENAI_API_KEY='replace-with-your-key'
export LLM_KEY='replace-with-an-enabled-registry-key'
skyvern quickstart --no-postgres

LLM_KEY 是 Skyvern 的注册键，不一定等于服务商的模型 ID，不能直接填任意模型名。按 官方模型配置文档 选择当前版本支持且账户可用的组合。

本文选择不启动 Postgres 的本地路径，数据库与已有数据按 quickstart 配置保留。不要为了修复一次启动错误就删除旧数据库。基础安装与运行说明见 Skyvern 官方项目。

按启动输出进入本地工作台，确认 API、UI 与浏览器资源均可用。UI 能打开与模型调用成功仍是两个检查点。

把业务表单与输入写清楚

准备一个可重做的测试账号与表单。本文依赖的页面合同如下：

把测试数据单独列出，例如部门为“技术测试”、商品为“办公用品测试项”、数量 2、单价 12.50 CNY，预期行金额为 25.00 CNY。需要日期使用测试系统允许的日期，不让助手根据“下周”推算一个不确定值。

附件选择不含真实业务数据的小文件。上传文件必须从实际运行浏览器的环境可达；本机路径不一定能被云浏览器或容器看到。

在工作台创建明确任务

新建浏览器任务，填入你的测试表单入口与以下目标。URL 由你提供，不能原样使用占位地址：

打开指定的测试采购申请表，仅建立草稿。
部门：技术测试；联系人：Test User；需要日期：使用任务参数中的明确日期。
明细：办公用品测试项，数量 2，单价 12.50 CNY。
上传任务提供的测试说明文件，等待上传完成。
遇到必填提示，根据上述输入修正，不猜测其他业务信息。
完成后保存草稿并进入预览，读取草稿编号、状态、明细数量和金额。
不要正式提交审批，不付款，不创建第二份相同申请。
无法判断或缺少必填输入时停止并说明缺项。

在实际任务中把“需要日期”和附件作为明确输入填好，不把上述说明中仍待替换的内容留给模型猜。若使用 UI 任务参数，保存参数名、值和表单字段之间的映射，便于重复运行。

自然语言中的“不要提交”是任务约束，不是系统权限。选择没有正式提交权限的测试环境或账号，才能使草稿任务的边界与实际能力一致。

逐步处理校验，不一次性盲点下一步

先在小任务中观察基本信息页。若需要日期不合法，应该修改该字段并检查提示消失，不反复点击下一步。

到明细页后确认数量和单价进入了对应列。表格中第二个数字可能是税率或折扣，不能只根据输入框顺序猜字段。输入后读取更新后的行金额与币种。

附件阶段看上传完成状态与文件名，而不是仅看文件选择动作执行。多个步骤都完成后再保存草稿，避免把上传中的状态推进成失败。

最后检查预览页面上的实际数据。视觉动作成功、字段提取成功与业务草稿正确是不同条件。

规定结果结构，再独立核对

任务结束后保存草稿编号、预览 URL、状态和关键字段。可以用如下 JSON 作为结果合同：

{
  "draft_id": "从预览读取",
  "status": "draft",
  "department": "技术测试",
  "line_items": [
    {"name": "办公用品测试项", "quantity": 2, "unit_price": "12.50", "currency": "CNY"}
  ],
  "total": "25.00",
  "attachment_name": "任务提供的实际文件名",
  "preview_url": "实际预览地址"
}

这只是结构示意，不是 Skyvern 固定的任务响应，也不是模型实测输出。应用侧应将界面中的具体结果映射到该结构，不能假设所有 SDK 或 UI 都直接返回这些字段。

先用测试账号手工打开 preview_url，确认 draft_id 对应同一份草稿，状态确实为 draft，数量和金额一致，附件可辨认。若系统有草稿列表，再检查是否只创建了一份。

有结构化终态也要执行这些检查。Agent 自己宣布完成，无法替你证明没有重复申请、金额正确或附件完整。

失败恢复避免重复业务动作

任务在预览前中断时，先到草稿列表查找已有记录，而不是直接重跑创建流程。已经保存过的草稿，优先从它继续；未确认是否保存时，需要先确认副作用。

把“页面导航失败”和“保存动作结果不明”分开。前者可能安全重做，后者必须先查状态。重试预算不能代替幂等业务设计。

批量执行时，每份申请应有应用侧唯一任务标识，保存输入与已有 draft_id 的对应关系。页面只支持普通保存、不支持请求幂等时，应通过查询与人工确认避免重复，而不假装底层已经保证一次执行。

常见问题与修复

工作台运行但模型报错。 检查 provider 开关、注册键和账户权限。不要把模型不可用归为表单元素问题。

下一步一直不可点。 查看本步校验、必填字段和上传状态，修复明确原因，再继续。添加更强的点击提示不能消除业务校验。

附件路径不存在。 核对浏览器运行位置与文件传入方式。不要把宿主机绝对路径直接当成远程浏览器路径。

金额对不上。 区分单价、税额、折扣和币种；回到行项目核对，不用总额覆盖明细来凑数。

任务失败但已有草稿。 先查询并核对已有 ID，继续处理或人工结束，不无条件重新创建。

结果字段很多却没有草稿编号。 检查是否真正到达预览，还是只描述了计划。编号和状态必须来自实际页面。

表单自动化的完整性来自字段、校验、业务状态和副作用的共同核对。先把一份可重做的测试草稿处理清楚，再扩展到更多流程。