445 lines
30 KiB
Markdown
445 lines
30 KiB
Markdown
# RPA 操作标准（浏览器 / 桌面 / 手机）
|
||
|
||
> 本文是团队 RPA 开发的**统一标准**。任何需要"自动操作软件界面"的 skill，都应先读这份文档，按这里的选型和范式落地，不要每个项目重新踩坑。
|
||
|
||
先读 [`AI_RPA.md`](AI_RPA.md)：Agent 负责理解、确认与编排，RPA 只负责授权范围内的确定性界面执行。RPA 是代替人完成正常业务操作的工具，**不是**破解、逆向、私有协议调用或对抗第三方安全机制的手段。
|
||
|
||
网页账号 / Profile 依赖公开兄弟技能 **account-manager**；浏览器 RPA 原语来自 **jiangchang-platform-kit**。账号设计、查看、租约、多账号和验收标准先读 [`ACCOUNT_MANAGER.md`](ACCOUNT_MANAGER.md)；二者 Gitea 地址、clone 方式与红线见 [`SHARED_REPOS.md`](SHARED_REPOS.md)。
|
||
|
||
我们开发的各类 skill，本质上都是在替人操作三类界面：**浏览器、桌面软件、手机软件**。三类的底层技术不同，但**工程范式相同**：可控会话（Profile）、有头运行、拟人操作、失败存证、人工兜底。
|
||
|
||
**开始写界面操作代码前，必须先读 [`RPA_ELEMENT_LOCATING.md`](RPA_ELEMENT_LOCATING.md)，完成真实拾取、元素清单、唯一性和后置状态设计。** 分端实操：
|
||
|
||
- 浏览器：[`RPA_BROWSER.md`](RPA_BROWSER.md)
|
||
- Windows 桌面：[`RPA_DESKTOP.md`](RPA_DESKTOP.md)
|
||
- Android / iOS：[`RPA_MOBILE.md`](RPA_MOBILE.md)
|
||
|
||
---
|
||
|
||
## 0. 三端通用范式（先看这个）
|
||
|
||
无论操作哪类界面，都遵循同一套约定：
|
||
|
||
| 约定 | 说明 |
|
||
|------|------|
|
||
| **可控会话 / Profile** | 网页版见下方 **§0.2**（必须走 account-manager 的 `profile_dir`）；桌面/手机用对应持久会话，不硬编码密码 |
|
||
| **有头运行** | 生产 RPA **必须有头**（见 §0.2）；禁止把无头当交付/联调常态 |
|
||
| **正常人工节奏** | 真实点击、逐字输入、自然鼠标轨迹、分段滚动；严禁 JS 直接设值/JS 点击/JS 跳转绕过页面流程 |
|
||
| **步骤间随机等待** | 每两个正常业务动作之间 `random_delay(min,max)`，真实环境默认 **1～3 秒**；状态等待另算，不得用固定睡眠代替 |
|
||
| **人工兜底（HITL）** | 滑块 / 短信验证码 / 人脸 / U盾 / 动态口令 → **停下来轮询等人工**，超时报 `ERROR:XXX_NEED_HUMAN`，绝不自动硬闯 |
|
||
| **失败存证** | 失败必截图，合规场景全程录屏，统一存 `{数据目录}/rpa-artifacts/{batch_id}/{tag}_{ts}.png` |
|
||
| **选择器纪律** | 先真实拾取并填写 element map；语义/可访问性属性优先；关键动作唯一匹配；**严禁凭记忆猜 selector 或用 first/index 掩盖歧义** |
|
||
| **统一错误码** | `ERROR:REQUIRE_LOGIN` / `ERROR:CAPTCHA_NEED_HUMAN` / `ERROR:RATE_LIMITED` / `ERROR:LOGIN_TIMEOUT` 等，见下方错误码表 |
|
||
| **步骤可控制** | 每条 RPA 指令 = 一个 `@rpa_step` 或 `video.add_step`；等待用 `interruptible_sleep`；宿主通过 control.json 暂停/继续/停止（SRCP，见 [`LOGGING.md`](LOGGING.md) §2.5） |
|
||
| **幂等 / 断点续跑** | 批量操作记录"已处理到第几条"，崩溃后能续跑、不重复提交 |
|
||
|
||
> 三端各自实现一个会话抽象 `RpaSession`（launch / login / act / screenshot / close），上层 skill 不感知是浏览器还是手机。
|
||
|
||
### 0.0 合规红线
|
||
|
||
- 只使用用户或企业合法拥有、明确授权的账号、数据、设备和业务权限。
|
||
- 优先正常界面或获得授权的官方 API；只有破解、逆向或绕过安全机制才能实现时，停止并上报。
|
||
- 禁止反编译、私有协议、抓包拼装隐藏接口、Hook / 注入、客户端篡改、验证码破解、设备指纹伪造、撞库、养号、自动换号或代理池规避限制。
|
||
- 验证码、人脸、指纹、短信、U盾、动态口令必须交给人工；权限不足、账号风险、频控或封禁必须安全停止。
|
||
- 合规与完整职责边界以 [`AI_RPA.md`](AI_RPA.md) 为准。
|
||
|
||
### 0.1 步骤控制与进度（SRCP，platform-kit >= 1.2.0）
|
||
|
||
- **禁止** `scripts/util/progress.py` 或 `print({"type":"progress",...})`；进度只走 `emit` / Run Journal。
|
||
- **禁止** RPA 主路径裸 `asyncio.sleep`；用 `jiangchang_skill_core.activity.interruptible_sleep`。
|
||
- RPA 函数用 `@rpa_step("中文步骤名")` 拆分；或在 `RpaVideoSession` 内 `video.add_step("中文步骤")`。
|
||
- `cmd_run` 须 `with job_context(skill=SKILL_SLUG):`，所有出口 `finish(...)`。
|
||
- 暂停在步骤边界生效；浏览器会话暂停时不强制关闭，恢复后同进程继续。
|
||
|
||
```python
|
||
from jiangchang_skill_core.activity import emit, finish, job_context, interruptible_sleep, rpa_step
|
||
|
||
@rpa_step("打开登录页")
|
||
async def open_login(page):
|
||
await page.goto("https://example.com")
|
||
await interruptible_sleep(1.5)
|
||
```
|
||
|
||
规范权威定义：[`LOGGING.md`](LOGGING.md) §2.5。金样代码：[`scripts/service/task_service.py`](../scripts/service/task_service.py)。
|
||
|
||
### 0.2 网页版 RPA 硬规则（Profile / 有头 / 登录分平台）
|
||
|
||
凡**打开网页、用浏览器自动化**的技能（真实站或仿真站），必须遵守（`POLICY-RPA-004`）：
|
||
|
||
| 规则 | 要求 |
|
||
|------|------|
|
||
| **Profile 强制** | 启动浏览器前必须已从 **account-manager**（经本技能 `account_client`）拿到可用的 **`profile_dir`（及租约约定）**。只用该目录做 `launch_persistent_context`。 |
|
||
| **首启用 ensure** | 业务技能默认走 **`account ensure-web`**（或 `pick-web --ensure`），经 `account_client.pick_web_account` 封装。无匹配账号时自动 `add-web` 再返回；**有账号但均被租约占用 → `ERROR:LEASE_CONFLICT`，禁止再新建重复账号**。 |
|
||
| **拿不到就停** | 未拿到 `profile_dir`、ensure 失败、租约失败 → **立即失败退出，禁止开浏览器**。不得静默落到系统默认 Chrome/Edge 用户目录。 |
|
||
| **有头强制** | 生产与用户侧联调：**`OPENCLAW_BROWSER_HEADLESS=0`（有头）**。禁止把无头（`=1`）当作交付或真实站联调常态（无头易风控、难人工介入，且易污染身份）。 |
|
||
| **登录不全局强制** | **是否要在目标站完成登录**由平台决定（如部分公开页可不登录也能闭环）。由做该技能的同事在 `REQUIREMENTS.md` / 用户教程中约定；**模板不强制「所有网页 RPA 必须先登录」**。 |
|
||
| **登记 ≠ 登录** | `ensure-web` / `add-web` 只保证有账号记录与 Profile 目录；**不等于**目标站已登录。站点登录仍由本技能 `ensure_logged_in`（或等价）在有头浏览器中完成。 |
|
||
| **登录 ≠ Profile** | 「可不登录」**绝不等于**「可以不接 account-manager」。无论目标站要不要登录，网页操作都依赖账号管理下发的 **Profile**。 |
|
||
| **登录策略 = required 时** | 每轮业务主路径在 `goto` 后必须过登录门禁 + 验证码/人工等待（`HUMAN_WAIT_TIMEOUT`）；**禁止**把会话依赖型采集默认抄成 `optional`。 |
|
||
| **账号必须可见可查** | 创建后须能在宿主数据管理、`account list/get` 和实际 `profile_dir` 中核验；不得把“命令没报错”当作创建与登录验收。 |
|
||
| **一账号一 Profile** | 不同账号必须使用不同且稳定的 `profile_dir`；不得共用、临时创建或指向本机日常浏览器目录。 |
|
||
| **租约贯穿任务** | 所有账号选择路径（包括指定数字 ID）都必须取得非空 `lease_token`；成功、失败、取消和异常均在 `finally` 释放。 |
|
||
|
||
**反模式（禁止）：**
|
||
|
||
- 未拿到 `profile_dir` 仍 `launch` / 仍打开页面
|
||
- 用系统默认用户数据目录或随意空目录反复跑真实站 → **污染本机 Profile、加重风控**
|
||
- 把「本站可不登录」写成「可以不走 account-manager」
|
||
- 真实站联调默认无头狂跑
|
||
- 仅用哈希 class / 不稳定 CSS 作为**唯一**登录态判定（须结合稳定文案、`get_by_role`、URL/业务 DOM；F12 实页确认）
|
||
- 把「业务空结果」（如无评论）与 `LEASE_CONFLICT` / `REQUIRE_LOGIN` 混成同一错误码
|
||
|
||
**参考实现：** `examples/real_browser_rpa/`、`examples/simulator_browser_rpa/`（`pick_web_account` → ensure-web → RPA → `finally release_lease`）。
|
||
|
||
账号完整生命周期、数据目录、数据管理查看方式、矩阵场景和排障证据见 [`ACCOUNT_MANAGER.md`](ACCOUNT_MANAGER.md)。不得只测试单账号一两次就宣称支持批量或多账号。
|
||
|
||
---
|
||
|
||
### 0.3 工业级风控、等待与收尾
|
||
|
||
**状态等待优先：**页面加载、控件可用、弹窗消失、保存成功、下载完成和业务结果出现，必须等待真实条件并设置超时；禁止用固定 `sleep(3)` 假设成功。
|
||
|
||
**有界就绪等待（platform-kit ≥ 1.2.11 必用）：**
|
||
|
||
- 业务技能的状态等待统一使用共享 API：`jiangchang_skill_core.rpa.poll_until`（async）或 `poll_until_sync`。
|
||
- **禁止**在 service 主路径再发明平行的 `deadline + sleep` / 私有 `_wait_*` 轮询作为标准答案（HITL 专用等待除外，仍可用 kit 的 `wait_for_login` / `wait_for_captcha_pass`）。
|
||
- 必须区分：**还在加载**（超时内继续等）vs **真的不是目标页/目标态**（有界等待失败后再判）。
|
||
- 超时默认映射 `ERROR:UI_NOT_READY`（或业务等价就绪码）；**不要**把「慢」直接判成 `PAGE_TYPE_MISMATCH`、配置门禁失败或 `ERROR:RATE_LIMITED`。
|
||
- 超时秒数须允许环境变量 / `.env` 覆盖（慢机器、限频、轻量电源场景可调大）。
|
||
- 可选浏览器启动超时：`launch_persistent_browser(..., timeout_ms=...)` 或 `OPENCLAW_BROWSER_LAUNCH_TIMEOUT_MS`；超时码 `ERROR:BROWSER_START_TIMEOUT`。默认不开启，与历史行为兼容。
|
||
- `health` 可带只读 `machine_power`（供电/限频提示）；**不得**仅凭该信号 hard-fail 全技能。
|
||
|
||
**操作节奏：**
|
||
|
||
- 两个正常业务动作之间默认随机等待 `1～3` 秒。
|
||
- 输入采用逐字符随机延迟；鼠标使用自然轨迹；滚动采用分段操作。
|
||
- 同一账号、Profile、桌面会话或手机设备默认串行。
|
||
- 单批数量、单位时间操作量和运行时长必须有上限。
|
||
- 只对明确可重试错误做有限重试；普通网络错误可递增退避，风险提示和权限错误不得自动重试。
|
||
|
||
**前后缓冲：**
|
||
|
||
- 启动浏览器、桌面软件或手机会话后，先等待目标页面 / 窗口 / 控件真实就绪，再额外缓冲约 `1.5～2.5` 秒。
|
||
- 页面导航后，关键控件就绪再缓冲约 `1～2` 秒。
|
||
- 流程结束时，先确认业务结果、写日志并完成存证，再缓冲约 `2～3` 秒关闭会话。
|
||
- 付款、审批、发布等重要动作确认结果并截图后，可缓冲约 `3～5` 秒。
|
||
|
||
缓冲用于稳定界面和改善用户体验，**不能作为成功判断**。RPA 主路径使用 `interruptible_sleep` 等可控制等待，确保暂停与停止能够生效。
|
||
|
||
**风险信号：**
|
||
|
||
| 信号 | 标准处理 |
|
||
|------|----------|
|
||
| 验证码 / 人脸 / 指纹 / U盾 | 进入人工处理 |
|
||
| 频率限制 | 停止当前批次或长时间退避 |
|
||
| 账号风险 / 封禁 / 安全警告 | 立即停止，禁止换号继续 |
|
||
| 权限不足 | 明确失败，不尝试绕过 |
|
||
| 页面 / 控件结构变化 | 截图并停止，重新人工验证定位 |
|
||
| 提交结果不明确 | 查询业务状态，确认前禁止再次提交 |
|
||
|
||
---
|
||
|
||
## 1. 浏览器（标准已成熟）
|
||
|
||
**选型：Playwright + 系统 Chrome/Edge。** 这是团队验证最充分的一条线（标杆技能 `1688-scrape-contacts`、`receive-order` 已落地）。
|
||
|
||
元素拾取、定位优先级、iframe/弹窗/Shadow DOM、动态列表和唯一性标准见 [`RPA_BROWSER.md`](RPA_BROWSER.md)。本节继续定义会话、启动、HITL 和工程边界。
|
||
|
||
### 1.0 生产路径（优先）
|
||
|
||
| 项 | 标准 |
|
||
|----|------|
|
||
| 浏览器 | **优先系统 Chrome/Edge** + `launch_persistent_context`，`channel="chrome"` 或 Edge；不用内置 Chromium，**技能内不要 `playwright install`** |
|
||
| Profile / 账号 | **必须**经 account-manager **`ensure-web`**（或 `pick-web --ensure`）取得 `profile_dir`（见 §0.2）；密码不进 `.env`；**是否站点登录**按平台在需求/教程约定；登记 ≠ 已登录 |
|
||
| CDP | **仅作诊断 / 桌面宿主类场景**；**不要**作为强风控站点的默认生产路径 |
|
||
| 行为 | 模拟真实用户：真实点击、键盘、鼠标、地址栏输入；**不要**拼接搜索结果 URL、DOM 注入、`el.value=`、JS 跳转 |
|
||
| 模式 | **有头** `OPENCLAW_BROWSER_HEADLESS=0`（生产强制，见 §0.2） |
|
||
| 浏览器兼容配置 | `OPENCLAW_PLAYWRIGHT_STEALTH` 仅用于经评估的兼容配置；不得用于伪造身份或绕过平台限制 |
|
||
|
||
### 1.1 Playwright 启动标准
|
||
|
||
1. **有头**：`OPENCLAW_BROWSER_HEADLESS=0`（`.env.example` 默认；网页 RPA 生产路径禁止改成无头常态，见 §0.2）。
|
||
2. **stealth 须受控**：`OPENCLAW_PLAYWRIGHT_STEALTH` 仅在目标平台授权、规则与项目评估允许时启用；不得把它理解为规避风控或伪造设备身份。
|
||
3. **不要在技能里自行安装 playwright**；由宿主共享 runtime 提供。
|
||
4. **不要默认传 `--no-sandbox`**（除非特定容器环境且已评估风险）。
|
||
5. **不要默认传 `--disable-blink-features=AutomationControlled`**；platform-kit stealth 已覆盖，额外 flag 可能适得其反。
|
||
6. **可以** `ignore_default_args=["--enable-automation"]`（platform-kit `launch_persistent_browser` 已处理）。
|
||
7. **强风控平台**：优先真实点击、键盘、鼠标、地址栏、account-manager 持久 profile；**不要**直接拼接搜索结果 URL 或 DOM 注入。
|
||
8. **先 Profile 再开浏览器**：`user_data_dir` 必须来自 ensure/pick 到的 `profile_dir`；未拿到则不得进入本节后续步骤。
|
||
|
||
浏览器兼容配置由共享 `jiangchang_skill_core.rpa` 提供（platform-kit **>= 1.2.0**）。业务技能不得自行扩展指纹伪造、代理轮换或规避安全检测的代码；遇到明确风控信号时转人工或停止。
|
||
|
||
**拟人操作**（必做）：
|
||
|
||
- 输入：逐字符 `keyboard.type(delay=90~240ms)`，**先真实点击聚焦再输入，绝不 `el.value=`**。
|
||
- 鼠标：贝塞尔曲线轨迹 + 微抖动；进场随机晃动。
|
||
- 导航：用真实点击触发，**不要 `window.location.href=` / JS 点击跳转**。
|
||
- 翻页：真实点击翻页控件，注意排除禁用态。
|
||
- 延迟：两个正常业务动作之间 `random_delay`（`.env` 中 `STEP_DELAY_MIN/MAX`，默认 1～3 秒）；页面状态仍须显式等待。
|
||
|
||
### 1.2 页面启动标准
|
||
|
||
**`launch_persistent_context` 的 `args` 只能放 Chrome 启动参数**（例如 `--start-maximized`、`--disable-blink-features=AutomationControlled` 等）。
|
||
|
||
**绝对不要把 `https://...` 这类 URL 放进 `args`。** 否则 Playwright 会报错：
|
||
|
||
```
|
||
BrowserType.launch_persistent_context: Arguments can not specify page to be opened
|
||
```
|
||
|
||
**正确做法（生产路径）：**
|
||
|
||
1. `launch_persistent_context(user_data_dir=profile_dir, executable_path=chrome, args=chrome_args, ...)`
|
||
2. `page = await context.new_page()`
|
||
3. `await page.goto(start_url, wait_until="domcontentloaded", timeout=60000)`
|
||
|
||
对强风控站点，如果需要更拟人，可以启动后通过**地址栏输入 / 真实点击进入**目标页，但**仍然不能把 URL 塞进 launch args**。
|
||
|
||
完整参考实现见：
|
||
|
||
- `examples/real_browser_rpa/README.md`（**开发真实浏览器 RPA 类 skill 时必须先读**）
|
||
- `examples/real_browser_rpa/scripts/service/browser_session.py`
|
||
|
||
**生产路径不要依赖 CDP 接管现有页面**；CDP 仅用于诊断或桌面宿主已打开浏览器的场景。
|
||
|
||
### 1.3 HITL / 验证码
|
||
|
||
- 自动处理失败时**允许等待人工**：滑块、短信、人脸、U盾、动态口令等。
|
||
- 等待人工验证时必须有：**字幕 step**（用户可见动作说明）、**结构化日志**、**超时**（`HUMAN_WAIT_TIMEOUT`）。
|
||
- 检测到风控页（URL/DOM 特征）→ 抛 `ERROR:CAPTCHA_NEED_HUMAN`，轮询等待或超时，**不要强行绕过平台安全机制**。
|
||
- **不要自动操作滑块**。
|
||
|
||
> 共享库：`jiangchang_skill_core.rpa.wait_for_captcha_pass`；**真实浏览器 RPA 成功案例**见 `examples/real_browser_rpa/`：
|
||
>
|
||
> - 先读 `examples/real_browser_rpa/README.md`
|
||
> - 再参考 `examples/real_browser_rpa/scripts/service/human_verification.py`
|
||
> - 再参考 `examples/real_browser_rpa/scripts/service/task_rpa.py`
|
||
|
||
### 1.4 Playwright 与安装边界
|
||
|
||
- Playwright 是宿主共享 runtime 提供的通用 Python 包能力；**正式 skill 不负责安装**。
|
||
- skill 侧**禁止**在 `requirements.txt`、安装脚本、运行脚本、根 `README.md` 用户说明中加入 `playwright install`、`pip install playwright` 或任何自动安装浏览器驱动的逻辑。
|
||
- 真实浏览器 RPA 默认使用**系统 Chrome/Edge**，由宿主/runtime 管理。
|
||
- **不要**执行 `playwright install chromium`、`playwright install chrome` 等浏览器驱动安装命令。
|
||
- 仅当**本地独立开发环境排障**时，开发者可手工检查或补装 Python 包 `playwright`；该操作**不得**进入 skill 交付文件与自动流程。
|
||
|
||
页面启动仍遵循 1.2：`launch_persistent_context` 的 `args` 只能放 Chrome 启动参数，**不能把 URL 塞进 `args`**；打开页面必须通过 `new_page()` + `goto()`，或通过真实地址栏/点击进入。
|
||
|
||
### 引用方式
|
||
|
||
共享实现位于宿主共享 runtime 安装的 `jiangchang-platform-kit`（`jiangchang_skill_core.rpa`）。复制后的业务技能直接 import，**技能仓库不得保留 rpa 公共代码副本**：
|
||
|
||
```python
|
||
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
|
||
```
|
||
|
||
- `RpaVideoSession` 来自 platform-kit **>= 1.2.0**；ffmpeg、背景音乐、media-assets 由 platform-kit 统一解析；已提供前置/后置缓冲、字幕、TTS 旁白、背景音乐循环、结尾淡出。
|
||
- `health` 对上述资源做只读诊断，不下载、不修复。
|
||
|
||
### 1.5 真实浏览器 RPA 示例（必读）
|
||
|
||
开发**真实网站 + 浏览器操作 + 登录态/验证码/滚动采集**类 skill 时：
|
||
|
||
1. **必须先阅读** `examples/real_browser_rpa/README.md`
|
||
2. 再参考以下代码：
|
||
- `examples/real_browser_rpa/scripts/service/browser_session.py` — persistent context 启动
|
||
- `examples/real_browser_rpa/scripts/service/human_verification.py` — 人工验证等待
|
||
- `examples/real_browser_rpa/scripts/service/task_rpa.py` — RPA 主流程
|
||
- `examples/real_browser_rpa/scripts/service/account_client.py` — account-manager CLI 封装
|
||
|
||
仿真浏览器 RPA 的 adapter 分层权威参考见 `examples/simulator_browser_rpa/`（含 async `simulator_playwright.py`、薄 `simulator_rpa` adapter、`account_client.py` subprocess），**不能**替代真实浏览器 RPA 规范。
|
||
|
||
### 1.6 仿真浏览器 RPA 示例（必读）
|
||
|
||
开发**自有仿真页面 / sandbox / 可控 DOM 的浏览器 RPA**（表单填写、批量提交、弹窗确认）时：
|
||
|
||
1. **必须先阅读** `examples/simulator_browser_rpa/README.md`
|
||
2. 再参考：
|
||
- `examples/simulator_browser_rpa/scripts/service/browser_session.py` — async persistent context（**不含 goto**）
|
||
- `examples/simulator_browser_rpa/scripts/service/simulator_playwright.py` — RPA 主流程（厚）
|
||
- `examples/simulator_browser_rpa/scripts/service/adapter/`（薄 `simulator_rpa` + mock + dispatch）
|
||
- `examples/simulator_browser_rpa/scripts/service/account_client.py` — account-manager subprocess
|
||
- `examples/simulator_browser_rpa/scripts/service/task_service.py` — async 编排
|
||
- `examples/simulator_browser_rpa/sandbox/demo_app.html`
|
||
|
||
> **先选类型再写代码**：真实第三方网站 → `real_browser_rpa`；自有 sandbox / 行业仿真 → `simulator_browser_rpa`。不要跨类型照抄 selector 或业务流程。
|
||
|
||
### 1.7 行业仿真平台浏览器 RPA（jc2009 类）
|
||
|
||
适用：**自有或共享 `sandbox.jc2009.com` 等行业仿真平台**，不是真实高风控第三方站。
|
||
|
||
工程范式与 §1.5 相同：
|
||
|
||
| 项 | 标准 |
|
||
|----|------|
|
||
| Playwright | **async** 贯穿；禁止 sync Playwright 用于完整 RPA 主路径 |
|
||
| 分层 | **薄 adapter** + `{domain}_playwright.py`（示例：`simulator_playwright.py`）+ `account_client.py` subprocess |
|
||
| 登录 | **双层**：门户 HITL（`#portal-user` / `#portal-pass` 类泛化 DOM）+ 业务系统登录（技能内自写） |
|
||
| 账号 | `url` 用行业根，不用 `/login`；`auth_strategy=per_session_manual`；`pick_web_account`（底层 ensure-web）+ `release_lease` |
|
||
| 禁止 | **不要** `import account-manager` 的 `rpa_helpers` 等内部模块 |
|
||
| Selector | 用户可见文案 / `get_by_role` / `name` 优先；`data-testid` 有则用、无则 fallback；共享 sandbox **不要求**为技能加 testid |
|
||
| Profile | Chrome persistent profile 可能缓存旧 SPA → 联调排障：手工 `--user-data-dir` 清站点数据 |
|
||
|
||
权威 example：**修正后的** `examples/simulator_browser_rpa/`（不是任何生产技能仓库）。
|
||
|
||
---
|
||
|
||
## 2. 桌面软件（Windows 原生程序）
|
||
|
||
**选型：Windows UI Automation（UIA）为主 + 图像识别兜底。** 当前已验证成功案例 `add-friend-wecom` 使用 Python `uiautomation`；`pywinauto(backend="uia")` 是兼容方案。完整拾取、定位和降级标准见 [`RPA_DESKTOP.md`](RPA_DESKTOP.md)。
|
||
|
||
桌面端常见于 ERP 客户端、网银控件、银企直连等本地程序。优先走可访问性树（控件 ID/名字），坐标点击只做最后兜底。
|
||
|
||
| 技术 | 优先级 | 适用 / 说明 |
|
||
|------|--------|------|
|
||
| **uiautomation** | ✅ 已验证首选 | `add-friend-wecom` 真实成功案例使用；直接读取 UIA Window/Control 树 |
|
||
| **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`。
|
||
- **禁止侵入**：不注入或 Hook 第三方进程，不修改客户端文件，不反编译或调用未授权私有协议。
|
||
|
||
```bash
|
||
pip install uiautomation # 当前真实成功案例
|
||
# 或：pip install pywinauto # UIA backend
|
||
# 图像兜底：pip install pyautogui opencv-python
|
||
```
|
||
|
||
> 状态：UIA 技术路线已经 `add-friend-wecom` 真实项目验证。脱敏、收紧后的参考 example 见 `examples/real_desktop_rpa/`；目标软件 selector 仍必须重新拾取。
|
||
|
||
---
|
||
|
||
## 3. 手机软件（USB 连接电脑）
|
||
|
||
**选型：Android 用 uiautomator2（或 Appium）；iOS 用 Appium + WebDriverAgent（需 Mac）。** 底层都是经 USB 的 ADB / WDA。
|
||
|
||
设备准备、Appium Inspector/UIAutoDev 拾取、Native/WebView、定位优先级和失败 XML 留证见 [`RPA_MOBILE.md`](RPA_MOBILE.md)。
|
||
|
||
| 平台 | 技术 | 优先级 | 说明 |
|
||
|------|------|--------|------|
|
||
| **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`。
|
||
- **设备边界**：使用正常授权设备与官方 App；不 Root / 越狱，不 Hook，不修改 APK / IPA，不伪造设备身份或绕过签名、绑定与安全校验。
|
||
|
||
```bash
|
||
# Android（首选）
|
||
pip install uiautomator2
|
||
python -m uiautomator2 init # 初始化设备端 agent
|
||
# 或统一走 Appium：pip install Appium-Python-Client（另需 Appium Server）
|
||
```
|
||
|
||
> 状态：手机端标准已定义，但**尚无团队真实成功案例**。`examples/mobile_rpa/` 仅是 example 完成规格，不能作为已跑通代码照抄；收到成功案例后再升级状态。
|
||
|
||
---
|
||
|
||
## 4. 统一错误码（RPA 场景）
|
||
|
||
skill 退出/抛错统一用 `ERROR:` 前缀 + 稳定码，方便宿主与上层判断与重试：
|
||
|
||
| 错误码 | 含义 | 上层处理建议 |
|
||
|--------|------|------|
|
||
| `ERROR:REQUIRE_LOGIN` | 未登录 / 登录态失效 | 触发登录流程（有头等待人工） |
|
||
| `ERROR:LOGIN_TIMEOUT` | 等待人工登录超时 | 提示用户重跑并及时操作 |
|
||
| `ERROR:CAPTCHA_NEED_HUMAN` | 命中滑块/验证码拦截 | 暂停等人工，或转人工队列 |
|
||
| `ERROR:LEASE_CONFLICT` | 已有账号但均被租约占用（ensure 不新建） | 稍后重试或释放租约；**不是**「无账号」 |
|
||
| `ERROR:AMBIGUOUS_ACCOUNT` | `--login-id` / `--label` 匹配到多条 | 改用数字 id 或更精确标识 |
|
||
| `ERROR:RATE_LIMITED` | 触发频控 | 退避后重试 |
|
||
| `ERROR:MISSING_BROWSER` | 未检测到 Chrome/Edge | 提示安装 |
|
||
| `ERROR:BROWSER_START_TIMEOUT` | 浏览器启动超时（可选 timeout） | 可重试；检查机器负载/供电；可调大 `OPENCLAW_BROWSER_LAUNCH_TIMEOUT_MS` |
|
||
| `ERROR:UI_NOT_READY` | 有界等待内页面/控件未就绪 | **默认可重试**；勿与「页类型错误/配置未开」混用；勿轻易标 session fatal |
|
||
| `ERROR:ENV_DEGRADED` | 环境降级提示类（限频/供电不足等，技能选用） | 可重试；提示接电源/退出省电/减小并发；**不是**配置错误 |
|
||
| `ERROR:DEVICE_NOT_READY` | 手机未连接/未授权 | 检查 USB/ADB |
|
||
| `ERROR:WINDOW_NOT_FOUND` | 桌面目标窗口未找到 | 检查程序是否启动 |
|
||
|
||
业务空结果（如「本页无评论」）用业务码或成功空列表表达，**不要**复用上表账号/登录错误码。
|
||
|
||
**归因纪律（防误诊）：**
|
||
|
||
- 「未开 `ALLOW_REAL_RPA` / 档位门禁」必须用技能自己的配置类错误码，**禁止**与真实启动失败、启动超时共用一个 hint。
|
||
- 页面慢导致的超时优先 `UI_NOT_READY` / 业务就绪码；仅当有明确频控 DOM/文案时才用 `RATE_LIMITED`。
|
||
- 是否列入技能 `SESSION_FATAL` / `RETRYABLE` 由技能自定，但 **UI 未就绪 / 启动超时默认不应整批不可重试终止**（除非会话已明确不可恢复，如未登录、验证码人工超时）。
|
||
|
||
---
|
||
|
||
## 5. 存证与录屏规范
|
||
|
||
### 5.1 截图存证
|
||
|
||
- **路径**：`{JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/{slug}/rpa-artifacts/{batch_id}/{tag}_{timestamp}.png`
|
||
- **失败必截图**：受 `OPENCLAW_ARTIFACTS_ON_FAILURE`（默认开）控制。
|
||
- **Playwright 不负责录屏**，仅浏览器自动化。
|
||
- **常见 tag**：`before_submit` / `after_submit` / `captcha` / `login_fail` / `error`。
|
||
|
||
### 5.2 RPA 视频 step 标准
|
||
|
||
字幕是**用户可见动作说明**，不是技术日志。step 要贴近真实动作，不要只在大流程入口打点。
|
||
|
||
推荐关键动作示例（按业务裁剪）：
|
||
|
||
- 启动浏览器
|
||
- 打开首页
|
||
- 检查登录状态
|
||
- 定位输入框
|
||
- 输入关键词：xxx
|
||
- 点击搜索
|
||
- 等待结果
|
||
- 打开详情页
|
||
- 提取信息
|
||
- 写入结果
|
||
- 任务完成
|
||
|
||
技术诊断、重复跳过、DB 写入可以显示但**通常不需要旁白**。
|
||
|
||
`title` / `closing_title` 必须由 skill 传入**中文业务文案**（如「开始执行示例任务」「示例任务执行完成」）。
|
||
|
||
### 5.3 录屏成片标准
|
||
|
||
- **skill-template 默认 `OPENCLAW_RECORD_VIDEO=0`**（开发调试更快，不启 ffmpeg）。
|
||
- **`OPENCLAW_RECORD_VIDEO=1` 时启用录屏**：字幕、旁白、背景音、MP4 成片由 platform-kit 统一处理。
|
||
- 使用 platform-kit 的 **`RpaVideoSession`**；**skill 不要自行合成视频**（不要自己调 ffmpeg 拼 MP4）。
|
||
- **默认关闭 ≠ 可以删除录屏接入**：RPA / 长任务 **service 层**（`scripts/service/*.py`）**必须保留** `RpaVideoSession`、`video.add_step`、video artifact merge 进 `finish()`（见 `POLICY-RPA-003`）。
|
||
- `OPENCLAW_RECORD_VIDEO=0` 时 session **无副作用**（不启 ffmpeg、不写字幕文件、不生成最终 MP4），但 **`RpaVideoSession.add_step` 仍可同步 Activity 进度**。
|
||
- 生产留证 / 合规 / 客户现场复现时，由用户在 `.env` 或进程环境变量中开启 `OPENCLAW_RECORD_VIDEO=1`。
|
||
- **ffmpeg 是唯一录屏器**（Windows：`gdigrab` + `desktop`）。
|
||
- **最终视频**（`OPENCLAW_RECORD_VIDEO=1` 时）：`{skill_data_dir}/videos/{skill_slug}_{yyyyMMdd_HHmmss}_{batch_id}.mp4`
|
||
- **中间产物**：`rpa-artifacts/{batch_id}/capture.mp4`、`subtitles/`、`logs/` 等。
|
||
- 任务完成后 CLI / `finish()` 应包含 video 字段（开启录屏时有路径；关闭时仍保留 `video` 结构与诊断占位）：`video_path`、`raw_video`、`video_log`、`video_warnings`、`music_path`、`voiceover_path`、`audio_warnings`（见 `scripts/service/task_run_support.py`）。
|
||
|
||
模板最小示范见 `scripts/service/task_service.py` 的 `_run_template_demo()`。
|
||
|
||
---
|
||
|
||
## 相关文档
|
||
|
||
- `RPA_ELEMENT_LOCATING.md` — 三端共用的拾取、element map、唯一性、降级和 AI 编程约束
|
||
- `RPA_BROWSER.md` — 浏览器 Pick Locator、DOM 作用域和定位质量
|
||
- `RPA_DESKTOP.md` — Windows UIA 拾取与已验证桌面路线
|
||
- `RPA_MOBILE.md` — Android/iOS 拾取、context、设备与 XML 留证
|
||
- `ADAPTER.md` — 真实/仿真 × API/RPA 的四档适配器模式
|
||
- `CONFIG.md` — `.env` 配置规范与首次落盘机制
|
||
- `RUNTIME.md` — 运行时目录与环境变量约定
|