> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeus.agentspro.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 流程录制

> 浏览器操作录制、编辑、参数化与回放

# 流程录制

Zeus Desktop 提供完整的浏览器操作录制能力，支持将用户在浏览器中的操作自动捕获为可编辑、可重放的工作流。

## 概述

流程录制基于 **Chrome DevTools Protocol (CDP)** 实现，能够精确捕获 DOM 级别的浏览器操作事件，相比传统的坐标录制方案具有更高的准确性和稳定性。

### 核心能力

| 能力        | 说明                                |
| --------- | --------------------------------- |
| **精确录制**  | 基于 CDP 捕获 DOM 事件，支持选择器 + 语义特征双重定位 |
| **可视化编辑** | 拖拽排序、逐步编辑、插入/删除操作步骤               |
| **参数化**   | 将固定值标记为变量，支持动态注入                  |
| **带参回放**  | 测试回放时输入参数值，验证流程正确性                |
| **视频同步**  | 操作事件与录制视频时间戳对齐，点击步骤跳转视频           |

## 快速开始

### 1. 选择浏览器配置

录制前需要选择一个浏览器配置（Profile），每个配置拥有独立的 Cookie、缓存和登录状态。

### 2. 开始录制

1. 点击录制页面中的 **开始录制** 按钮
2. 选择浏览器配置
3. 可选开启视频录制（同时捕获屏幕画面）
4. 浏览器自动启动，进入录制模式

### 3. 执行操作

在浏览器中正常操作，系统会自动捕获以下事件：

* 页面导航（URL 跳转）
* 鼠标点击
* 文本输入与修改
* 键盘按键
* 页面滚动
* 表单提交
* 拖拽操作

### 4. 停止录制

点击 **停止录制** 按钮，录制的操作序列会展示在编辑器中，可进一步编辑和保存。

## 支持的操作类型

### 浏览器事件

| 类型         | 说明                  | 可参数化       |
| ---------- | ------------------- | ---------- |
| `navigate` | 页面导航到指定 URL         | ✅ URL 可参数化 |
| `click`    | 点击页面元素              | ❌          |
| `input`    | 在输入框中输入文本           | ✅ 输入值可参数化  |
| `change`   | 修改表单控件值（下拉框等）       | ✅ 值可参数化    |
| `scroll`   | 页面或元素滚动             | ❌          |
| `keypress` | 按下键盘按键（Enter、Tab 等） | ❌          |
| `wait`     | 等待指定时间              | ❌          |
| `submit`   | 提交表单                | ❌          |
| `drag`     | 拖拽元素到目标位置           | ❌          |

### 系统级事件（扩展）

| 类型                | 说明               |
| ----------------- | ---------------- |
| `system_click`    | 系统级鼠标点击          |
| `system_keypress` | 系统级键盘输入          |
| `app_switch`      | 应用切换             |
| `applescript`     | AppleScript 脚本执行 |
| `shell_command`   | Shell 命令执行       |

## 元素定位策略

录制时，每个操作的目标元素会采用多重定位策略，确保回放时的高准确率：

### 定位优先级

| 优先级 | 方法         | 置信度  | 说明                    |
| --- | ---------- | ---- | --------------------- |
| 1   | `testId`   | 1.00 | `data-testid` 属性精确匹配  |
| 2   | `exact`    | 0.95 | 语义特征完全匹配（role + name） |
| 3   | `selector` | 0.85 | CSS 选择器匹配             |
| 4   | `fuzzy`    | 0.70 | 模糊匹配（文本内容、aria 属性）    |
| 5   | `position` | 0.60 | 视觉位置匹配                |
| 6   | `nth`      | 0.50 | 索引兜底                  |

### 语义特征（ElementFeatures）

每个操作的目标元素会记录丰富的语义特征：

```typescript theme={null}
interface ElementFeatures {
  role?: string          // ARIA 角色
  name?: string          // 可访问名称
  testId?: string        // data-testid
  ariaLabel?: string     // aria-label
  text?: string          // 文本内容
  placeholder?: string   // placeholder 属性
  tagName?: string       // HTML 标签名
  type?: string          // input type
}
```

这些特征使得即使页面 DOM 结构发生变化，回放引擎仍然能够通过语义信息找到正确的目标元素。

## 编辑工作流

### 工作流编辑器

保存录制后，可在工作流编辑器中对操作序列进行修改：

* **拖拽排序**：调整操作步骤的执行顺序
* **编辑操作**：修改选择器、值、URL 等属性
* **插入步骤**：在任意位置插入新的操作步骤
* **删除步骤**：移除不需要的操作
* **视频同步**：点击步骤自动跳转到录制视频对应时间点

### 编辑操作详情

点击任意操作步骤，打开编辑对话框：

* **基础信息**：操作类型、描述
* **选择器**：CSS 选择器、XPath、元素特征
* **值**：输入值、导航 URL
* **参数化设置**：标记为变量、设置变量名和默认值

## 参数化

参数化是将录制中的固定值转换为可动态注入的变量，是实现 **AI Agent 驱动执行** 的关键能力。

### 什么是参数化

以登录流程为例：

| 步骤    | 录制时                       | 参数化后          |
| ----- | ------------------------- | ------------- |
| 输入用户名 | `admin`                   | `{username}`  |
| 输入密码  | `123456`                  | `{password}`  |
| 导航到系统 | `https://sys.example.com` | `{systemUrl}` |

参数化后，这些值不再是固定的，而是在回放/调用时由外部传入。

### 单个操作参数化

1. 在工作流编辑器中点击操作步骤，打开编辑对话框
2. 开启 **参数化** 开关
3. 设置 **变量名**（如 `username`）
4. 可选填写 **参数描述**（如 "登录用户名"）
5. 可选设置 **默认值**（如 `admin`）
6. 保存

开启参数化后，操作的值字段会显示为变量引用（如 `{username}`），实际值在运行时通过变量注入。

### 批量参数化

对于包含多个输入操作的工作流，可以使用 **批量参数化** 功能：

1. 在工作流编辑器顶部，如果存在未参数化的 `input`/`change`/`navigate` 操作，会显示 **批量参数化** 提示
2. 点击后，系统会自动为这些操作生成变量名（基于元素的 `name`、`id`、`placeholder` 等属性）
3. 自动将当前值设为默认值
4. 可在编辑对话框中进一步调整

### 变量解析机制

回放引擎使用 `{variableName}` 语法进行变量替换：

```
输入值: "Hello, {username}! Your code is {verifyCode}"
传入变量: { username: "张三", verifyCode: "123456" }
实际执行: "Hello, 张三! Your code is 123456"
```

变量解析支持：

* 完整替换：`{username}` → `张三`
* 内嵌替换：`https://{host}/api` → `https://example.com/api`
* 未匹配的变量保持原样：`{unknown}` → `{unknown}`

## 回放测试

### 普通回放

对于没有参数化的工作流，直接选择浏览器配置后开始回放。

### 带参数回放

当工作流包含参数化操作时，点击回放会弹出 **参数输入对话框**：

1. 自动展示所有参数化字段
2. 显示参数名、描述和默认值
3. 必填参数（无默认值）标记为红色
4. 填入测试值后点击 **开始回放**

### 回放引擎

回放基于 CDP 执行，具备以下特性：

| 特性        | 说明                            |
| --------- | ----------------------------- |
| **元素等待**  | 自动等待目标元素出现（最长 10 秒）           |
| **重试机制**  | 操作失败自动重试（最多 3 次，间隔 1 秒）       |
| **超时保护**  | 单个操作超时 30 秒自动跳过               |
| **进度反馈**  | 实时显示执行进度和每步状态                 |
| **可视化状态** | 编辑器中高亮当前执行步骤（蓝色执行中/绿色成功/红色失败） |

## 视频录制

### 录制选项

| 选项         | 说明                        |
| ---------- | ------------------------- |
| **屏幕/窗口源** | 选择录制整个屏幕或指定窗口             |
| **分辨率**    | 720p / 1080p / 4K         |
| **帧率**     | 30fps / 60fps             |
| **麦克风音频**  | 录制语音解说                    |
| **系统音频**   | 录制系统声音（macOS 需 BlackHole） |

### 视频-操作同步

录制视频与操作事件通过时间戳对齐：

* 每个操作记录 `videoTimestamp`（相对于录制开始的秒数）
* 编辑器中点击操作步骤，视频自动跳转到对应时间点
* 回放时视频预览与操作执行同步

### 存储空间估算

| 分辨率   | 帧率    | 时长    | 文件大小         |
| ----- | ----- | ----- | ------------ |
| 720p  | 30fps | 10 分钟 | \~80-120 MB  |
| 1080p | 30fps | 10 分钟 | \~150-250 MB |
| 1080p | 30fps | 1 分钟  | \~15-25 MB   |

## 本地存储

工作流数据存储在本地文件系统中：

```
{userData}/workflows/
├── {workflow-id}.json          # 工作流定义（操作序列 + 元数据）
├── {workflow-id}/
│   ├── recordings/             # 录制视频文件
│   │   └── recording.webm
│   ├── screenshots/            # 关键帧截图
│   │   ├── action-001.png
│   │   └── action-002.png
│   └── metadata.json           # 同步元数据
```

### 工作流 JSON 结构

```json theme={null}
{
  "id": "wf-abc123",
  "name": "登录系统并查询数据",
  "actions": [
    {
      "id": "act-001",
      "type": "navigate",
      "url": "https://system.example.com",
      "timestamp": 1700000000000
    },
    {
      "id": "act-002",
      "type": "input",
      "selector": "#username",
      "value": "{username}",
      "isParameterized": true,
      "variableName": "username",
      "paramDescription": "登录用户名",
      "defaultValue": "admin",
      "elementFeatures": {
        "role": "textbox",
        "name": "用户名",
        "placeholder": "请输入用户名"
      }
    }
  ],
  "profileId": "profile-001",
  "toolName": "login_and_query",
  "toolDescription": "登录系统并查询指定数据",
  "isPublished": true
}
```

## 下一步

录制完成并参数化后，可以将工作流 [发布为 RPA 工具](/zh/desktop/rpa-workflow)，让 AI Agent 能够远程调用。