> For the complete documentation index, see [llms.txt](https://docs.docbits.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.docbits.com/chinese/guan-li-yu-she-zhi/workflow/cards-overview/docoperator-script-guide.md).
# 运行 DocOperator 提示（自动化脚本）
***
将此卡片添加到 Workflow Builder 的 **Then** 组中——当 When/And 条件匹配时运行的操作：
通过 Add Card 将 Run DocOperator Prompt 卡片添加到 Then 组。
***
## 📌 版本信息
**当前版本：** v3（最新且推荐） **状态：** ✅ 活跃
**版本历史：**
* v2 → DocOperator 的原始实现
* **v3 → 当前版本**（新增执行控制参数）
* v4 → 已弃用（功能已回退）
**变更内容：** v3 新增了可选的“执行提示”参数，以便更好地控制执行。v4 曾尝试回退此功能，但该版本已弃用。
📖 [版本历史与变更](https://github.com/Fellow-Consulting-AG/docbits/tree/main/readme/administration-and-setup/changelog/release.md#3-action_run_docoperator_script--) | [完整卡片数据库](https://github.com/Fellow-Consulting-AG/docbits/tree/main/readme/DocFlow/docs/card_version.md#action_run_docoperator_script)
***
## 用途
此卡片使用 DocOperator 运行自动化浏览器操作或脚本。可以把它想象成一个机器人，能像人一样与网站或系统交互——点击按钮、填写表单、提取数据等。
\*\*实际示例：\*\*贵公司使用基于 Web 的采购系统。此卡片可以自动登录、搜索产品、检查库存情况并获取当前价格，全程无需人工操作。
***
## 何时使用此卡片
在以下情况下使用此卡片：
* 自动化操作没有 API 的网站
* 从网页提取数据
* 自动填写表单
* 登录系统并检索信息
* 自动执行重复性人工任务
* 与尚未集成的旧系统交互
**常见场景：**
* 登录供应商网站并获取实时库存
* 自动填写外部系统中的表单
* 从未提供 API 的网页提取数据
* 在快递公司网站上查询配送状态
* 从无法通过 API 访问的系统获取价格
***
## 工作原理
1. \*\*触发卡片：\*\*工作流运行到此卡片，且条件已满足
2. \*\*启动脚本：\*\*DocOperator 机器人开始运行自动化脚本
3. \*\*机器人执行操作：\*\*机器人执行点击、输入、滚动、提取等操作
4. \*\*提取数据：\*\*机器人从网页收集信息
5. \*\*返回数据：\*\*数据返回到 DocFlow，供后续卡片使用
6. \*\*超时处理：\*\*如果脚本运行时间过长，则会停止并返回已获取的数据
***
## 参数说明
### DocOperator 提示/脚本
用于准确指示 DocOperator 执行哪些操作的自动化脚本
**示例（自然语言）：**
```
1. 前往 https://supplier.com/login
2. 输入用户名：myuser
3. 输入密码：mypass
4. 点击 Login 按钮
5. 搜索产品 "ABC123"
6. 提取价格
7. 返回价格
```
### 变量
要传入脚本的数据
**示例：**
```
product_id: "ABC123"
supplier_code: "SUPP-001"
```
可在脚本中按如下方式使用这些变量：
```
搜索产品 "{product_id}"
查找供应商 "{supplier_code}"
```
### 最大步骤数
允许机器人执行的操作次数
**常见取值：**
* 简单任务（例如获取一个价格）：10–20 步
* 中等复杂度任务（填写表单并提取数据）：20–50 步
* 复杂工作流（登录、搜索并验证）：50–100 步
\*\*重要原因：\*\*防止脚本陷入无限循环或运行时间过长
### 最大重试次数
如果机器人执行某个操作失败，应重试多少次？
**示例：**
* 1：尝试一次，失败后继续
* 3：尝试 3 次后放弃
* 5：坚持重试 5 次
***
## 分步示例
### 场景：从网站获取供应商价格
**脚本定义：**
```
步骤 1：打开网站 https://prices.supplier-xyz.com
步骤 2：点击“Product Lookup”
步骤 3：输入产品代码：ABC-123
步骤 4：点击“Search”
步骤 5：等待结果加载（3 秒）
步骤 6：从页面提取价格
步骤 7：提取可用数量
步骤 8：返回这两个值
```
**传入的变量：**
```
product_code = "ABC-123"
supplier_name = "Supplier XYZ"
```
**使用变量的脚本：**
```
打开网站 https://prices.{supplier_name}.com
输入产品代码：{product_code}
提取价格和数量
```
**预期结果：**
```
price: 45.50
quantity_available: 500
```
***
## DocOperator 可执行的操作类型
### 导航
* 访问 URL
* 点击链接
* 按下按钮
* 滚动页面
### 填写表单
* 在字段中输入文本
* 选择下拉选项
* 勾选或取消勾选复选框
* 点击按钮
### 数据提取
* 读取页面文本
* 提取数字
* 获取表格数据
* 复制信息
### 等待
* 等待页面加载
* 等待元素出现
* 等待动态内容加载
### 条件逻辑
* 如果某项内容存在，则执行相应操作
* 如果文本匹配，则……
* 统计结果并据此执行操作
***
## 常见用例
### 1. 获取实时价格
\*\*场景：\*\*供应商没有 API，但网站上显示价格
**脚本：**
```
1. 前往供应商网站
2. 搜索产品
3. 从结果中提取价格
4. 将价格返回给 DocFlow
5. 使用价格验证发票
```
### 2. 检查库存情况
\*\*场景：\*\*需要了解供应商是否有库存
**脚本：**
```
1. 登录供应商门户
2. 搜索产品
3. 提取可用状态
4. 提取交付时间
5. 将两项信息返回给 DocFlow
```
### 3. 自动提交表单
\*\*场景：\*\*需要在外部网站上填写表单
**脚本：**
```
1. 前往表单页面
2. 填写 Company Name 字段
3. 填写 Contact Email 字段
4. 从下拉菜单中选择 Country
5. 上传附件
6. 点击 Submit 按钮
7. 获取确认消息
```
### 4. 验证数据录入
\*\*场景：\*\*验证两个不同系统中的数据是否一致
**脚本：**
```
1. 前往 System A
2. 搜索 Order #123
3. 提取订单金额
4. 前往 System B
5. 搜索 Order #123
6. 提取订单金额
7. 比较金额
8. 返回金额是否匹配的 true/false 结果
```
***
## 配置步骤
### 步骤 1：创建脚本
1. 定义要实现的目标
2. 将任务拆分为小步骤
3. 清晰地编写每个步骤
4. 先手动测试（打开网站并亲自操作）
5. 准确记录要点击的位置、要输入的内容以及要提取的数据
### 步骤 2：确定变量
1. 哪些数据会因文档而异？
2. 哪些数据需要传入脚本？
3. 定义变量名称
4. 指定变量在脚本中的使用位置
### 步骤 3：设置参数
* \*\*最大步骤数：\*\*根据脚本复杂度设置
* \*\*最大重试次数：\*\*设置机器人重试的次数
* \*\*超时：\*\*设置等待页面的最长时间
### 步骤 4：测试
1. 使用示例数据进行测试
2. 确认机器人可以访问网站
3. 确认提取结果正确
4. 检查变量是否正常工作
***
## 编写脚本的提示
### 使用清晰的语言
✅ **建议：**
```
1. 点击 "Login" 按钮
2. 在登录字段中输入用户名
3. 等待 2 秒，让表单完成处理
```
❌ **不建议：**
```
1. 执行登录操作
2. 输入所需内容
3. 等待处理完成
```
### 使用具体的选择器
✅ **建议：**
```
点击标有 "Submit Order" 的按钮
在占位符为 "Enter Email" 的字段中输入内容
```
❌ **不建议：**
```
点击某处
在字段中输入内容
```
### 错误处理
✅ **建议：**
```
1. 尝试点击 "Next" 按钮
2. 如果未找到按钮，则从当前页面提取数据
3. 返回已有内容
```
❌ **不建议：**
```
点击 "Next"（假定该按钮始终存在）
```
***
## 故障排除
### “脚本超时”
\*\*原因：\*\*脚本运行时间过长，未能及时完成
**解决方案：**
* [ ] 减少操作次数
* [ ] 增大“最大步骤数”
* [ ] 优化脚本以加快执行速度
* [ ] 简化要提取的内容
### “未找到元素”
\*\*原因：\*\*DocOperator 未能找到指定的按钮或字段
**解决方案：**
* [ ] 确认按钮或字段名称完全正确
* [ ] 检查网站布局是否已更改
* [ ] 点击前增加等待时间
* [ ] 检查该按钮是否只在特定条件下显示
### “登录失败”
\*\*原因：\*\*身份验证失败
**解决方案：**
* [ ] 确认用户名和密码正确
* [ ] 检查密码是否包含特殊字符
* [ ] 确认账户未被锁定
* [ ] 检查登录流程是否已更改
### “数据提取不正确”
\*\*原因：\*\*脚本已运行，但提取的信息有误
**解决方案：**
* [ ] 确认选择了正确的字段
* [ ] 检查数据是否位于预期位置
* [ ] 手动测试提取逻辑
* [ ] 添加调试步骤，以确认页面上显示的内容
### “脚本运行缓慢”
\*\*原因：\*\*步骤过多或网站响应缓慢
**解决方案：**
* [ ] 删除不必要的步骤
* [ ] 优化等待时间
* [ ] 检查互联网连接
* [ ] 考虑是否有可用的 API 替代方案
***
## 最佳实践
✅ **建议：**
* 部署前彻底测试脚本
* 保持脚本简单、专注
* 添加注释说明每个步骤
* 使用有意义的变量名
* 监控脚本性能
* 为脚本失败的情况准备备用方案
❌ **不建议：**
* 创建特别长的脚本（>100 步）
* 在日志中写入敏感密码
* 依赖精确坐标（网站可能会发生变化）
* 创建没有退出条件的循环
* 忽略错误消息
***
## 性能提示
* **删除未使用的步骤** - 每个步骤都会耗费时间
* **合并类似操作** - 将相关点击操作组合起来
* **优化等待时间** - 仅使用必要的延迟
* **缓存数据** - 避免重复提取相同数据
* **并行处理** - 尽可能同时运行多个脚本
***
## 安全注意事项
⚠️ **重要：**
* 不要在 DocFlow 中存储密码
* 使用安全方式传递凭据
* 不要记录敏感数据
* 监控提取的数据
* 确保机器人活动有日志记录且可审计
***
## 变量示例
### 可用变量：
```
{invoice_number} - 来自文档字段
{supplier_code} - 来自文档字段
{product_id} - 来自文档字段
{quantity} - 来自文档字段
{currency} - 来自文档字段
```
### 使用变量的脚本：
```
1. 前往 https://supplier.com/api/lookup
2. 输入供应商代码：{supplier_code}
3. 搜索产品：{product_id}
4. 输入数量：{quantity}
5. 提取以 {currency} 计价的价格
6. 返回提取的价格
```
***
## 对比：何时使用 DocOperator 与 API
| 情况 | 使用 DocOperator | 使用 API |
| -------- | -------------- | ------- |
| 网站提供 API | ❌ 否 | ✅ 是 |
| 网站支持交互操作 | ✅ 是 | ❌ 否 |
| 需要登录 | ✅ 是 | 视情况而定 |
| 需要极快速度 | ❌ 否 | ✅ 是 |
| 复杂工作流 | ✅ 是 | ❌ 可能不适用 |
| 数据每天变化 | ✅ 是 | ✅ 是 |
***
## 相关卡片
* **CALL\_API** - 有 API 时改用此卡片
* **ACTION\_HTTPS\_REQUEST** - 用于较简单的请求
* **ACTION\_SET\_FIELD\_TO\_TEXT** - 使用提取的数据
* **CONDITION\_HTTPS\_REQUEST\_STATUS** - 检查请求状态
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.docbits.com/chinese/guan-li-yu-she-zhi/workflow/cards-overview/docoperator-script-guide.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
