完善模板，加入RPA标准
This commit is contained in:
171
references/RPA.md
Normal file
171
references/RPA.md
Normal file
@@ -0,0 +1,171 @@
|
||||
# RPA 操作标准（浏览器 / 桌面 / 手机）
|
||||
|
||||
> 本文是团队 RPA 开发的**统一标准**。任何需要"自动操作软件界面"的 skill，都应先读这份文档，按这里的选型和范式落地，不要每个项目重新踩坑。
|
||||
|
||||
我们开发的各类 skill，本质上都是在替人操作三类界面：**浏览器、桌面软件、手机软件**。三类的底层技术不同，但**工程范式相同**：保持登录态、有头运行、拟人操作、失败存证、人工兜底。
|
||||
|
||||
---
|
||||
|
||||
## 0. 三端通用范式（先看这个）
|
||||
|
||||
无论操作哪类界面，都遵循同一套约定：
|
||||
|
||||
| 约定 | 说明 |
|
||||
|------|------|
|
||||
| **保持登录态** | 复用持久化 Profile / session，避免每次重新登录触发风控；账号由 account-manager 下发，不硬编码 |
|
||||
| **有头运行** | 默认有头（headless 易被识别 / 难人工介入）；`OPENCLAW_BROWSER_HEADLESS=1` 仅给 CI |
|
||||
| **拟人操作** | 真实事件（isTrusted=true），逐字输入、随机延迟、贝塞尔鼠标轨迹；严禁 JS 直接设值/JS 点击/JS 跳转 |
|
||||
| **步骤间随机等待** | 每两步操作之间 `random_delay(min,max)`，区间由 `.env` 配置（默认 1~5s） |
|
||||
| **人工兜底（HITL）** | 滑块 / 短信验证码 / 人脸 / U盾 / 动态口令 → **停下来轮询等人工**，超时报 `ERROR:XXX_NEED_HUMAN`，绝不自动硬闯 |
|
||||
| **失败存证** | 失败必截图，合规场景全程录屏，统一存 `{数据目录}/rpa-artifacts/{batch_id}/{tag}_{ts}.png` |
|
||||
| **选择器纪律** | 语义选择器优先（id/name/text/aria）；**F12 确认后再写，严禁凭记忆猜 DOM** |
|
||||
| **统一错误码** | `ERROR:REQUIRE_LOGIN` / `ERROR:CAPTCHA_NEED_HUMAN` / `ERROR:RATE_LIMITED` / `ERROR:LOGIN_TIMEOUT` 等，见下方错误码表 |
|
||||
| **幂等 / 断点续跑** | 批量操作记录"已处理到第几条"，崩溃后能续跑、不重复提交 |
|
||||
|
||||
> 三端各自实现一个会话抽象 `RpaSession`（launch / login / act / screenshot / close），上层 skill 不感知是浏览器还是手机。
|
||||
|
||||
---
|
||||
|
||||
## 1. 浏览器（标准已成熟）
|
||||
|
||||
**选型：Playwright + 系统 Chrome/Edge。** 这是团队验证最充分的一条线（参考 `1688-scrape-contacts`、`disburse-payroll-icbc`）。
|
||||
|
||||
| 项 | 标准 |
|
||||
|----|------|
|
||||
| 驱动 | Playwright（Python） |
|
||||
| 浏览器 | 系统已装 Chrome/Edge，`channel="chrome"`；**不用内置 Chromium，无需 `playwright install`** |
|
||||
| 登录态 | `launch_persistent_context` + 用户 Profile 目录（由 account-manager 下发） |
|
||||
| 模式 | 默认有头；`OPENCLAW_BROWSER_HEADLESS=1` 转无头 |
|
||||
| 反反爬 | stealth 指纹注入 + 拟人输入/鼠标/延迟 + 滑块停下等人工（见下） |
|
||||
|
||||
### 1.1 防反爬三件套（必做）
|
||||
|
||||
1. **指纹淡化（stealth）**：启动时 `add_init_script` 注入，抹平自动化特征——
|
||||
`navigator.webdriver=undefined`、`chrome.runtime`、`permissions.query`、`plugins`、`languages`、`hardwareConcurrency`、`deviceMemory`、WebGL vendor。
|
||||
启动参数 `--disable-blink-features=AutomationControlled` + `ignore_default_args=["--enable-automation"]`。
|
||||
开关：`OPENCLAW_PLAYWRIGHT_STEALTH`（默认开）。
|
||||
2. **拟人操作**：
|
||||
- 输入：逐字符 `keyboard.type(delay=90~240ms)`，**先真实点击聚焦再输入，绝不 `el.value=`**。
|
||||
- 鼠标：贝塞尔曲线轨迹移动 + 微抖动；进场随机晃动 2~4 次。
|
||||
- 导航：用真实点击触发，**不要 `window.location.href=` / `el.click()` 这类 JS 跳转/点击**。
|
||||
- 翻页：真实点击翻页箭头，注意排除禁用态选择器。
|
||||
- 延迟：每步之间 `random_delay`。
|
||||
3. **风控页 = 停下等人工**：检测到滑块/拦截（URL 含 `punish/x5sec/baxia/tmd`，或 DOM 命中 `#nocaptcha/.nc-container/punish-component` 等）→ 抛 `ERROR:CAPTCHA_NEED_HUMAN`，轮询等人工通过或超时，**不自动操作滑块**。
|
||||
|
||||
> 参考实现：`1688-scrape-contacts/scripts/service/anti_detect.py`、`util/playwright_stealth.py`、`service/login_service.py`（验证码等待）。已提升为共享库 `jiangchang_skill_core.rpa`（见 platform-kit）。
|
||||
|
||||
### 1.2 安装
|
||||
|
||||
```bash
|
||||
pip install playwright # 仅装包；用系统 Chrome，无需 playwright install chromium
|
||||
```
|
||||
|
||||
### 引用方式
|
||||
|
||||
共享实现位于 `jiangchang-platform-kit` 的 `jiangchang_skill_core.rpa`；模板通过 vendor 拷贝引用：
|
||||
|
||||
```python
|
||||
# scripts/jiangchang_skill_core/rpa/ — vendored from platform-kit
|
||||
from jiangchang_skill_core.rpa import (
|
||||
launch_persistent_browser,
|
||||
anti_detect,
|
||||
wait_for_captcha_pass,
|
||||
capture_failure,
|
||||
errors,
|
||||
)
|
||||
from jiangchang_skill_core.rpa.stealth import stealth_enabled, STEALTH_INIT_SCRIPT
|
||||
```
|
||||
|
||||
完整示例见 `scripts/service/example_browser_rpa.py` 与 `scripts/service/example_adapter/sim_rpa.py`。
|
||||
|
||||
---
|
||||
|
||||
## 2. 桌面软件（Windows 原生程序）
|
||||
|
||||
**选型：pywinauto（UIA backend）为主 + 图像识别兜底。**
|
||||
|
||||
桌面端常见于 ERP 客户端、网银控件、银企直连等本地程序。优先走可访问性树（控件 ID/名字），坐标点击只做最后兜底。
|
||||
|
||||
| 技术 | 优先级 | 适用 / 说明 |
|
||||
|------|--------|------|
|
||||
| **pywinauto（`backend="uia"`）** | ✅ 首选 | 基于微软 UI Automation 树，拿控件 AutomationId/Name/ControlType，**稳定、不依赖屏幕坐标**，纯 Python |
|
||||
| **FlaUI**（经 pythonnet 调 .NET） | 备选 | UIA 拿不到的复杂/自绘控件时更完整，但需引入 .NET 运行时 |
|
||||
| **Playwright** | 特例 | 目标是 **Electron 套壳应用**（很多新 SaaS 客户端）时，可当浏览器驱动 |
|
||||
| **PyAutoGUI / SikuliX（图像识别）** | ⚠️ 兜底 | 控件树完全拿不到时（Flash/远程桌面/纯自绘 UI）；**靠截图找图+坐标，分辨率/缩放一变就崩**，仅最后手段 |
|
||||
|
||||
### 桌面端注意事项
|
||||
|
||||
- **窗口聚焦/置顶**：操作前确保目标窗口前置，避免误操作其它窗口。
|
||||
- **DPI/缩放**：图像识别方案必须固定显示缩放比例；UIA 方案不受影响（优先用 UIA 即是为此）。
|
||||
- **存证**：同样要失败截图（截目标窗口/全屏），存到 `rpa-artifacts`。
|
||||
- **人工兜底**：U盾插拔、动态口令、人脸 → 停下等人工，超时 `ERROR:XXX_NEED_HUMAN`。
|
||||
|
||||
```bash
|
||||
pip install pywinauto # UIA 自动化
|
||||
# 图像兜底：pip install pyautogui opencv-python
|
||||
```
|
||||
|
||||
> 状态：桌面端选型为推荐标准，**尚待真实项目实战验证**，落地时回补踩坑记录到本文。
|
||||
|
||||
---
|
||||
|
||||
## 3. 手机软件（USB 连接电脑）
|
||||
|
||||
**选型：Android 用 uiautomator2（或 Appium）；iOS 用 Appium + WebDriverAgent（需 Mac）。** 底层都是经 USB 的 ADB / WDA。
|
||||
|
||||
| 平台 | 技术 | 优先级 | 说明 |
|
||||
|------|------|--------|------|
|
||||
| **Android** | **uiautomator2**（python 原生） | ✅ 首选 | ADB over USB，直接拿控件树点击/输入，比 Appium 轻快，纯 Python |
|
||||
| Android | **Appium**（uiautomator2 driver） | 备选 | 需要跨平台统一接口、或团队已有 Appium 资产时用 |
|
||||
| Android | **Airtest + Poco**（网易开源） | 兜底 | 图像+控件混合，自带 IDE 可录制；控件树拿不到时用 |
|
||||
| **iOS** | **Appium + WebDriverAgent（XCUITest）** | 唯一可行 | **必须有一台 Mac 做中转**，Windows host 无法直接驱动 iOS |
|
||||
| 投屏/人工介入 | **scrcpy** | 辅助 | USB 投屏到电脑，配合人工过验证码/人脸 |
|
||||
|
||||
### 手机端注意事项
|
||||
|
||||
- **设备就绪检查**：`adb devices` 确认已授权连接；放进 `doctor` 自检。
|
||||
- **登录态**：靠 App 自身保持登录，必要时引导人工首登一次。
|
||||
- **人工兜底**：短信验证码、人脸、指纹 → scrcpy 投屏让人工完成，程序轮询等待。
|
||||
- **存证**：失败时 `adb screencap` / Appium 截图存 `rpa-artifacts`。
|
||||
|
||||
```bash
|
||||
# Android（首选）
|
||||
pip install uiautomator2
|
||||
python -m uiautomator2 init # 初始化设备端 agent
|
||||
# 或统一走 Appium：pip install Appium-Python-Client（另需 Appium Server）
|
||||
```
|
||||
|
||||
> 状态：手机端选型为推荐标准，**尚待真实项目实战验证**，落地时回补踩坑记录到本文。
|
||||
|
||||
---
|
||||
|
||||
## 4. 统一错误码（RPA 场景）
|
||||
|
||||
skill 退出/抛错统一用 `ERROR:` 前缀 + 稳定码，方便宿主与上层判断与重试：
|
||||
|
||||
| 错误码 | 含义 | 上层处理建议 |
|
||||
|--------|------|------|
|
||||
| `ERROR:REQUIRE_LOGIN` | 未登录 / 登录态失效 | 触发登录流程 |
|
||||
| `ERROR:LOGIN_TIMEOUT` | 等待人工登录超时 | 提示用户重跑并及时操作 |
|
||||
| `ERROR:CAPTCHA_NEED_HUMAN` | 命中滑块/验证码拦截 | 暂停等人工，或转人工队列 |
|
||||
| `ERROR:RATE_LIMITED` | 触发频控 | 退避后重试 |
|
||||
| `ERROR:MISSING_BROWSER` | 未检测到 Chrome/Edge | 提示安装 |
|
||||
| `ERROR:DEVICE_NOT_READY` | 手机未连接/未授权 | 检查 USB/ADB |
|
||||
| `ERROR:WINDOW_NOT_FOUND` | 桌面目标窗口未找到 | 检查程序是否启动 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 存证规范
|
||||
|
||||
- **路径**：`{CLAW_DATA_ROOT}/{user}/{slug}/rpa-artifacts/{batch_id}/{tag}_{timestamp}.png`
|
||||
- **失败必截图**：受 `OPENCLAW_ARTIFACTS_ON_FAILURE`（默认开）控制。
|
||||
- **全程录屏**：受 `OPENCLAW_RECORD_VIDEO`（默认关）控制；合规场景（如代发工资）建议开。浏览器用 Playwright `record_video_dir`。
|
||||
- **常见 tag**：`before_submit` / `after_submit` / `captcha` / `login_fail` / `error`。
|
||||
|
||||
---
|
||||
|
||||
## 相关文档
|
||||
|
||||
- `ADAPTER.md` — 真实/仿真 × API/RPA 的四档适配器模式
|
||||
- `CONFIG.md` — `.env` 配置规范与首次落盘机制
|
||||
- `RUNTIME.md` — 运行时目录与环境变量约定
|
||||
Reference in New Issue
Block a user