unicorn-rpa/README.md

🦄 Unicorn RPA - 强大的跨域iframe自动化控制工具

# 🦄 Unicorn RPA

强大的跨域iframe自动化控制工具

## 新功能：接口响应捕获

### 1. clickAndWaitForResponse - 点击并等待接口响应

这个动作会点击指定元素，然后等待并捕获可能触发的接口响应。

```javascript
// 示例：点击提交按钮并等待接口响应
{
  "type": "clickAndWaitForResponse",
  "selector": ".submit-btn",
  "timeout": 10000, // 可选，默认10秒超时
  "delay": 1000     // 可选，动作完成后的延迟
}
```

### 2. waitForApiResponse - 等待接口响应

这个动作会等待并捕获接口响应，通常与 `click` 动作配合使用。

```javascript
// 示例：先点击按钮，再等待接口响应
[
  {
    "type": "click",
    "selector": ".submit-btn"
  },
  {
    "type": "waitForApiResponse",
    "timeout": 10000, // 可选，默认10秒超时
    "delay": 1000     // 可选，动作完成后的延迟
  }
]
```

### 响应数据格式

当捕获到接口响应时，会在 `results` 数组中添加以下格式的数据：

```javascript
// 成功响应
{
  "type": "apiResponse",
  "selector": ".submit-btn", // 仅 clickAndWaitForResponse 包含
  "data": {
    "type": "fetch", // 或 "xmlhttprequest"
    "url": "https://api.example.com/submit",
    "status": 200,
    "statusText": "OK",
    "responseText": "{\"success\": true, \"message\": \"提交成功\"}",
    "headers": {
      "content-type": "application/json",
      "cache-control": "no-cache"
    }
  }
}

// 请求失败
{
  "type": "apiError",
  "selector": ".submit-btn", // 仅 clickAndWaitForResponse 包含
  "error": "NetworkError: Failed to fetch"
}

// 等待超时
{
  "type": "apiTimeout",
  "selector": ".submit-btn", // 仅 clickAndWaitForResponse 包含
  "message": "等待接口响应超时"
}
```

### 使用场景

1. **表单提交验证**：点击提交按钮后验证接口返回结果
2. **数据加载确认**：点击加载按钮后确认数据是否正确返回
3. **操作结果验证**：执行操作后验证接口响应是否符合预期
4. **错误处理**：捕获接口错误并进行相应处理

### 注意事项

- 支持 `fetch` 和 `XMLHttpRequest` 两种请求方式
- 会自动恢复原始的请求方法，不会影响页面正常功能
- 响应文本会被完整记录，但日志中只显示前500个字符
- 超时时间可配置，默认10秒
- 可以捕获请求头信息

## 原有功能

## 简介

**unicorn-rpa** 是一个基于 postMessage 的跨域 iframe 自动化控制工具，支持多种 UI 自动化操作，适用于前端页面自动化测试、RPA 机器人、跨系统表单自动填充等场景。

- 支持多种常见 UI 操作（输入、点击、选择、滚动、批量勾选等）
- 支持跨域 iframe 自动化
- 内置安全校验（来源白名单、频率限制、动作类型校验、加密认证）
- 易于集成到 Vue/React/原生项目

---


## 安装

```bash
npm install unicorn-rpa
# 或
pnpm add unicorn-rpa
# 或
yarn add unicorn-rpa
```

---


## 主要特性

- **自动化动作丰富**：支持 fill、select、click、doubleClick、rightClick、hover、scroll、screenshot、waitFor、wait、treeSelect、checkAllCheckboxes、getText、getValue 等
- **安全机制完善**：
  - 来源域名白名单
  - 消息频率限制（每10秒同一来源只能发一次）
  - 动作类型白名单
  - AES+SHA256 加密认证（auth 字段）
- **高兼容性**：兼容主流浏览器和 Node.js 注入场景
- **可扩展**：支持自定义动作扩展

---


## 快速上手

### 1. 发送端（前端/Node）

```js
import CryptoJS from 'crypto-js';

const AUTH_AES_KEY = 'unicorn-rpa-2024-very-secret-key-1234'; // 与接收端一致
const authPlain = '优霓空(重庆)科技有限公司';
const authEncrypted = CryptoJS.AES.encrypt(authPlain, AUTH_AES_KEY).toString();

const fillData = {
  auth: authEncrypted,
  iframeSelector: '#targetFrame',
  actions: [
    { type: 'fill', selector: '.input', value: 'hello', delay: 500 },
    { type: 'click', selector: '.btn', delay: 500 }
  ]
};

const iframe = document.getElementById('targetFrame');
iframe.contentWindow.postMessage(fillData, '*');
```

### 2. 接收端（iframe页面/目标页面）

在目标页面引入 unicorn-rpa 并初始化：

```js
const injectRPA = require('unicorn-rpa');
injectRPA();
```

---


## 动作类型说明

| type                | 说明             |
|---------------------|------------------|
| fill                | 文本输入         |
| select              | 下拉选择         |
| click               | 点击             |
| doubleClick         | 双击             |
| rightClick          | 右键点击         |
| hover               | 悬停             |
| scroll              | 滚动             |
| screenshot          | 截图             |
| waitFor             | 等待元素出现     |
| wait                | 等待固定时长     |
| treeSelect          | 树形选择         |
| checkAllCheckboxes  | 批量勾选复选框   |
| getText             | 获取文本         |
| getValue            | 获取值           |

---


## 安全机制

1. **auth 加密认证**
   - 发送方用 AES 密钥加密明文（如公司名），生成 `auth` 字段
   - 接收方用同样密钥解密后做 SHA256 hash，与本地 hash 匹配才通过
2. **来源白名单**
   - 只允许配置的域名来源的消息
3. **频率限制**
   - 同一来源每10秒只能发一次消息
4. **动作类型白名单**
   - 只允许预设的动作类型

---


## 配置说明

### 1. 安全配置（unicorn-rpa/src/utils/security.js）

```js
const SECURITY_CONFIG = {
  ALLOWED_ORIGINS: [
    'http://localhost:5000',
    'http://localhost:5173',
    'http://localhost:8080',
    'http://127.0.0.1:5000',
    'http://127.0.0.1:5173',
    'http://127.0.0.1:8080'
  ],
  RATE_LIMIT: {
    INTERVAL: 10000 // 10秒
  }
};
```

### 2. AUTH 密钥和 hash
- 推荐用环境变量或外部配置文件隐藏密钥和 hash
- 例：
```js
const AUTH_AES_KEY = process.env.AUTH_AES_KEY;
const AUTH_HASH = process.env.AUTH_HASH;
```

---


## 常见问题 FAQ

**Q: 为什么我的消息被拒绝？**
- 检查来源域名是否在白名单
- 检查发送频率是否过快
- 检查动作类型是否支持
- 检查 auth 字段是否加密且密钥一致

**Q: 如何自定义动作？**
- 可在 unicorn-rpa/src/actions/index.js 中扩展 actionHandlers

**Q: 如何调试安全校验？**
- 控制台会输出详细的安全警告和失败原因

---


## 贡献与反馈

如需定制功能、发现 bug 或有建议，欢迎 issue 或 PR。

---


## License

MIT