client-commons/skill-template
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f52536bdccb86b37eab191833caf8ac25b31c613
skill-template/references/RPA.md
chendelian f52536bdcc
All checks were successful
技能自动化发布 / release (push) Successful in 5s
Details
chore: sync ffmpeg RpaVideoSession, remove Playwright recording 
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-02 14:07:02 +08:00

9.7 KiB
Raw Blame History

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 安装

pip install playwright   # 仅装包；用系统 Chrome，无需 playwright install chromium

引用方式

共享实现位于 jiangchang-platform-kit 的 jiangchang_skill_core.rpa；模板通过 vendor 拷贝引用：

# 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。
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。
# 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（默认开）控制。
  • 运行录屏成片：RPA 型技能默认 OPENCLAW_RECORD_VIDEO=1，表示 ffmpeg 录制运行过程 + 字幕 + 背景音乐 + 最终 MP4 一体开启。由 RpaVideoSession 统一触发，不在 CLI/E2E 单独实现。
  • Playwright 不负责录屏，仅浏览器自动化。
  • ffmpeg 是唯一录屏器（Windows：gdigrab + desktop）。
  • 最终视频：{skill_data_dir}/videos/{skill_slug}_{yyyyMMdd_HHmmss}_{batch_id}.mp4
  • 中间产物：rpa-artifacts/{batch_id}/capture.mp4、subtitles/、logs/ 等，不放最终 MP4。
  • 常见 tag：before_submit / after_submit / captcha / login_fail / error。

相关文档

  • ADAPTER.md — 真实/仿真 × API/RPA 的四档适配器模式
  • CONFIG.md — .env 配置规范与首次落盘机制
  • RUNTIME.md — 运行时目录与环境变量约定
Reference in New Issue View Git Blame Copy Permalink