# browser-work

**Repository Path**: tommyrunner/browser-work

## Basic Information

- **Project Name**: browser-work
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-19
- **Last Updated**: 2025-07-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 浏览器工作流 (Browser Work)

浏览器工作流是一个强大的 Chrome 扩展插件，能够自动记录和回放用户在网页中的操作，帮助您自动化重复性的浏览器任务。

## ✨ 核心功能

### 🎯 操作录制

- **智能录制**: 自动记录点击、输入、滚动等用户操作
- **精确回放**: 完美重现录制的操作序列
- **元素识别**: 智能 CSS 选择器生成，提高回放成功率
- **实时预览**: 录制过程中实时显示操作日志

### 🔧 高级特性

- **浮动控制**: 可拖拽的圆形按钮，方便快速操作
- **元素高亮**: 操作时元素闪烁提示，直观明了
- **调试模式**: 详细的控制台日志输出
- **速度控制**: 自定义回放速度，适应不同场景

### 📊 数据管理

- **JSON 导出**: 标准格式导出，便于分享和备份
- **文件导入**: 支持导入之前保存的操作记录
- **操作限制**: 可配置最大录制操作数量

## 🚀 快速开始

### 1. 安装插件

1. 下载插件文件到本地
2. 打开 Chrome 浏览器，进入扩展程序页面 (chrome://extensions/)
3. 开启"开发者模式"
4. 点击"加载已解压的扩展程序"，选择插件目录

### 2. 基本使用

1. **开始录制**: 点击插件图标，点击"开始录制"按钮
2. **执行操作**: 在页面中正常进行点击、输入、滚动等操作
3. **停止录制**: 完成后点击"停止录制"按钮
4. **导出记录**: 点击"导出录制文件"保存为 JSON 文件
5. **回放操作**: 点击"导入并回放"，选择 JSON 文件开始回放

### 3. 配置选项

- 进入插件设置页面调整各项参数
- 配置回放速度、显示选项等
- 启用或关闭特定功能

## 📄 JSON 格式规范

录制的操作数据采用标准 JSON 格式，便于程序处理和人工阅读。

### 文件结构

```json
{
  "version": "1.0.0",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "url": "https://example.com",
  "title": "示例页面 - 工作流录制",
  "actions": [...],
  "metadata": {...}
}
```

### 主要字段说明

| 字段        | 类型   | 说明                         |
| ----------- | ------ | ---------------------------- |
| `version`   | String | 录制格式版本号               |
| `timestamp` | String | 录制开始时间 (ISO 8601 格式) |
| `url`       | String | 录制页面的 URL               |
| `title`     | String | 录制文件的标题               |
| `actions`   | Array  | 操作记录数组                 |
| `metadata`  | Object | 元数据信息                   |

### 操作记录格式 (actions)

每个操作记录包含以下字段：

```json
{
  "type": "click",
  "timestamp": 1705315800000,
  "selector": "#login-button",
  "elementInfo": {
    "tagName": "button",
    "text": "登录",
    "value": "",
    "href": "",
    "className": "btn btn-primary"
  },
  "data": {
    "clientX": 150,
    "clientY": 300,
    "button": 0,
    "ctrlKey": false,
    "shiftKey": false,
    "altKey": false
  },
  "url": "https://example.com/login",
  "scrollPosition": {
    "x": 0,
    "y": 100
  }
}
```

### 操作类型说明

#### 1. 点击操作 (click)

- **type**: `"click"`
- **data**: 包含鼠标位置、按键状态等信息
  ```json
  {
    "clientX": 150, // 鼠标X坐标
    "clientY": 300, // 鼠标Y坐标
    "button": 0, // 鼠标按键 (0=左键, 1=中键, 2=右键)
    "ctrlKey": false, // Ctrl键状态
    "shiftKey": false, // Shift键状态
    "altKey": false // Alt键状态
  }
  ```

#### 2. 输入操作 (input)

- **type**: `"input"`
- **data**: 包含输入值和输入类型
  ```json
  {
    "value": "user@example.com", // 输入的值
    "inputType": "input" // 输入类型
  }
  ```

#### 3. 键盘操作 (keydown)

- **type**: `"keydown"`
- **data**: 包含按键信息
  ```json
  {
    "key": "Enter", // 按键名称
    "code": "Enter", // 按键代码
    "ctrlKey": false, // Ctrl键状态
    "shiftKey": false, // Shift键状态
    "altKey": false // Alt键状态
  }
  ```

#### 4. 滚动操作 (scroll)

- **type**: `"scroll"`
- **data**: 包含滚动位置信息
  ```json
  {
    "scrollX": 0, // 水平滚动位置
    "scrollY": 500, // 垂直滚动位置
    "scrollWidth": 1200, // 页面总宽度
    "scrollHeight": 2000 // 页面总高度
  }
  ```

### 元素信息 (elementInfo)

每个操作都包含目标元素的详细信息：

```json
{
  "tagName": "input", // 元素标签名
  "text": "点击这里", // 元素文本内容
  "value": "输入值", // 元素值 (适用于表单元素)
  "href": "https://...", // 链接地址 (适用于链接元素)
  "className": "btn btn-primary" // CSS类名
}
```

### 元数据 (metadata)

包含录制过程的统计信息：

```json
{
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
  "totalActions": 3, // 总操作数
  "duration": 2000 // 录制总时长 (毫秒)
}
```

### 完整示例

```json
{
  "version": "1.0.0",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "url": "https://example.com",
  "title": "示例页面 - 工作流录制",
  "actions": [
    {
      "type": "click",
      "timestamp": 1705315800000,
      "selector": "#login-button",
      "elementInfo": {
        "tagName": "button",
        "text": "登录",
        "value": "",
        "href": "",
        "className": "btn btn-primary"
      },
      "data": {
        "clientX": 150,
        "clientY": 300,
        "button": 0,
        "ctrlKey": false,
        "shiftKey": false,
        "altKey": false
      },
      "url": "https://example.com/login",
      "scrollPosition": {
        "x": 0,
        "y": 100
      }
    },
    {
      "type": "input",
      "timestamp": 1705315801000,
      "selector": "#username",
      "elementInfo": {
        "tagName": "input",
        "text": "",
        "value": "user@example.com",
        "href": "",
        "className": "form-control"
      },
      "data": {
        "value": "user@example.com",
        "inputType": "input"
      },
      "url": "https://example.com/login",
      "scrollPosition": {
        "x": 0,
        "y": 100
      }
    },
    {
      "type": "scroll",
      "timestamp": 1705315802000,
      "selector": "html",
      "elementInfo": {
        "tagName": "html",
        "text": "",
        "value": "",
        "href": "",
        "className": ""
      },
      "data": {
        "scrollX": 0,
        "scrollY": 500,
        "scrollWidth": 1200,
        "scrollHeight": 2000
      },
      "url": "https://example.com/login",
      "scrollPosition": {
        "x": 0,
        "y": 500
      }
    }
  ],
  "metadata": {
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
    "totalActions": 3,
    "duration": 2000
  }
}
```

## ⚙️ 配置说明

### 基本设置

- **启用浏览器工作流**: 总开关，控制插件是否启用
- **回放频率**: 控制固定间隔模式下的操作执行间隔，默认 500 毫秒
- **采用操作时间**: 使用录制时的真实时间间隔进行回放，默认启用，提供更自然的操作节奏
- **高亮触发元素**: 操作时是否高亮显示目标元素

### 界面设置

- **显示操作日志**: 是否在新窗口显示详细日志

### 界面设置

- **显示浮动按钮**: 是否显示页面上的快捷控制按钮
- **调试模式**: 在控制台输出详细调试信息

### 录制设置

- **记录滚动事件**: 是否记录页面滚动操作
- **记录键盘事件**: 是否记录键盘按键操作
- **智能选择器**: 使用优化的元素选择器策略

### 数据管理

- **最大录制操作数**: 单次录制的最大操作数量限制

## 🔧 开发指南

### 项目结构

```
browser-work/
├── manifest.json          # 扩展清单文件
├── popup/                 # 弹出窗口
│   ├── popup.html
│   ├── popup.js
├── options/               # 选项页面
│   ├── options.html
│   ├── options.js
├── content/               # 内容脚本
│   ├── content.js
├── background/            # 背景脚本
│   ├── background.js
├── styles/                # 样式文件
│   ├── popup.css
│   ├── options.css
│   └── content.css
├── utils/                 # 工具函数
│   └── common.js
├── icons/                 # 图标文件
│   └── icon.png
└── README.md
```

### 核心技术

- **Manifest V3**: 最新的 Chrome 扩展规范
- **Content Scripts**: 页面内容注入和操作
- **Background Service Worker**: 后台消息处理
- **Chrome Storage API**: 数据持久化存储
- **Chrome Tabs API**: 标签页管理

## ⚠️ 注意事项

1. **页面兼容性**: 不支持 Chrome 内置页面 (chrome://)
2. **元素稳定性**: 录制的操作依赖页面结构，页面变动可能影响回放
3. **安全提醒**: 回放前请备份重要数据
4. **网络环境**: 确保网络环境与录制时一致
5. **页面状态**: 回放时页面状态应与录制时相似
6. **回放模式**: 默认使用"采用操作时间"模式，按录制时的真实节奏回放，提供更自然的体验

## 🐛 故障排除

### 录制无法开始

- 检查是否在支持的页面 (非 chrome://页面)
- 刷新页面后重试
- 检查插件是否正确安装

### 回放失败

- 确认页面结构没有发生变化
- 尝试关闭"采用操作时间"选项，使用固定间隔模式
- 调整回放频率（在固定间隔模式下）
- 检查网络连接状态
- 查看控制台错误日志

### 元素找不到

- 页面结构可能已改变
- 尝试在相似的页面状态下回放
- 检查选择器是否准确

## 📋 版本历史

### v1.0.0

- 初始版本发布
- 支持基本的录制和回放功能
- 完整的配置选项
- JSON 格式数据导出

## 🤝 贡献指南

欢迎提交问题和功能建议！

### 开发环境搭建

1. 克隆项目到本地
2. 在 Chrome 中加载开发版本
3. 修改代码并测试
4. 提交 Pull Request

## 📄 许可证

本项目采用 MIT 许可证。