query-payslip-default/development/RPA.md

RPA 操作标准（浏览器 / 桌面 / 手机）

本文是团队 RPA 开发的统一标准。任何需要"自动操作软件界面"的 skill，都应先读这份文档，按这里的选型和范式落地，不要每个项目重新踩坑。

先读 AI_RPA.md：Agent 负责理解、确认与编排，RPA 只负责授权范围内的确定性界面执行。RPA 是代替人完成正常业务操作的工具，不是破解、逆向、私有协议调用或对抗第三方安全机制的手段。

网页账号 / Profile 依赖公开兄弟技能 account-manager；浏览器 RPA 原语来自 jiangchang-platform-kit。账号设计、查看、租约、多账号和验收标准先读 ACCOUNT_MANAGER.md；二者 Gitea 地址、clone 方式与红线见 SHARED_REPOS.md。

我们开发的各类 skill，本质上都是在替人操作三类界面：浏览器、桌面软件、手机软件。三类的底层技术不同，但工程范式相同：可控会话（Profile）、有头运行、拟人操作、失败存证、人工兜底。

开始写界面操作代码前，必须先读 RPA_ELEMENT_LOCATING.md，完成真实拾取、元素清单、唯一性和后置状态设计。 分端实操：

• 浏览器：RPA_BROWSER.md
• Windows 桌面：RPA_DESKTOP.md
• Android / iOS：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 §2.5）
幂等 / 断点续跑	批量操作记录"已处理到第几条"，崩溃后能续跑、不重复提交

三端各自实现一个会话抽象 RpaSession（launch / login / act / screenshot / close），上层 skill 不感知是浏览器还是手机。

0.0 合规红线

• 只使用用户或企业合法拥有、明确授权的账号、数据、设备和业务权限。
• 优先正常界面或获得授权的官方 API；只有破解、逆向或绕过安全机制才能实现时，停止并上报。
• 禁止反编译、私有协议、抓包拼装隐藏接口、Hook / 注入、客户端篡改、验证码破解、设备指纹伪造、撞库、养号、自动换号或代理池规避限制。
• 验证码、人脸、指纹、短信、U盾、动态口令必须交给人工；权限不足、账号风险、频控或封禁必须安全停止。
• 合规与完整职责边界以 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(...)。
• 暂停在步骤边界生效；浏览器会话暂停时不强制关闭，恢复后同进程继续。

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 §2.5。金样代码：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。不得只测试单账号一两次就宣称支持批量或多账号。

---

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。本节继续定义会话、启动、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 公共代码副本：

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。

桌面端常见于 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 第三方进程，不修改客户端文件，不反编译或调用未授权私有协议。

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。

平台	技术	优先级	说明
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，不伪造设备身份或绕过签名、绑定与安全校验。

# 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 — 运行时目录与环境变量约定