docs: 沉淀AI+RPA合规与工业级风控规范

development/RPA.md

@@ -2,6 +2,8 @@
 
 > 本文是团队 RPA 开发的**统一标准**。任何需要"自动操作软件界面"的 skill，都应先读这份文档，按这里的选型和范式落地，不要每个项目重新踩坑。
 
+先读 [`AI_RPA.md`](AI_RPA.md)：Agent 负责理解、确认与编排，RPA 只负责授权范围内的确定性界面执行。RPA 是代替人完成正常业务操作的工具，**不是**破解、逆向、私有协议调用或对抗第三方安全机制的手段。
+
 网页账号 / Profile 依赖公开兄弟技能 **account-manager**；浏览器 RPA 原语来自 **jiangchang-platform-kit**。二者 Gitea 地址、clone 方式与红线见 [`SHARED_REPOS.md`](SHARED_REPOS.md)。
 
 我们开发的各类 skill，本质上都是在替人操作三类界面：**浏览器、桌面软件、手机软件**。三类的底层技术不同，但**工程范式相同**：可控会话（Profile）、有头运行、拟人操作、失败存证、人工兜底。
@@ -16,8 +18,8 @@
 |------|------|
 | **可控会话 / Profile** | 网页版见下方 **§0.2**（必须走 account-manager 的 `profile_dir`）；桌面/手机用对应持久会话，不硬编码密码 |
 | **有头运行** | 生产 RPA **必须有头**（见 §0.2）；禁止把无头当交付/联调常态 |
-| **拟人操作** | 真实事件（isTrusted=true），逐字输入、随机延迟、贝塞尔鼠标轨迹；严禁 JS 直接设值/JS 点击/JS 跳转 |
-| **步骤间随机等待** | 每两步操作之间 `random_delay(min,max)`，区间由 `.env` 配置（默认 1~5s） |
+| **正常人工节奏** | 真实点击、逐字输入、自然鼠标轨迹、分段滚动；严禁 JS 直接设值/JS 点击/JS 跳转绕过页面流程 |
+| **步骤间随机等待** | 每两个正常业务动作之间 `random_delay(min,max)`，真实环境默认 **1～3 秒**；状态等待另算，不得用固定睡眠代替 |
 | **人工兜底（HITL）** | 滑块 / 短信验证码 / 人脸 / U盾 / 动态口令 → **停下来轮询等人工**，超时报 `ERROR:XXX_NEED_HUMAN`，绝不自动硬闯 |
 | **失败存证** | 失败必截图，合规场景全程录屏，统一存 `{数据目录}/rpa-artifacts/{batch_id}/{tag}_{ts}.png` |
 | **选择器纪律** | 语义选择器优先（id/name/text/aria）；**F12 确认后再写，严禁凭记忆猜 DOM** |
@@ -27,6 +29,14 @@
 
 > 三端各自实现一个会话抽象 `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。
@@ -74,6 +84,40 @@ async def open_login(page):
 
 ---
 
+### 0.3 工业级风控、等待与收尾
+
+**状态等待优先：**页面加载、控件可用、弹窗消失、保存成功、下载完成和业务结果出现，必须等待真实条件并设置超时；禁止用固定 `sleep(3)` 假设成功。
+
+**操作节奏：**
+
+- 两个正常业务动作之间默认随机等待 `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` 已落地）。
@@ -87,12 +131,12 @@ async def open_login(page):
 | CDP | **仅作诊断 / 桌面宿主类场景**；**不要**作为强风控站点的默认生产路径 |
 | 行为 | 模拟真实用户：真实点击、键盘、鼠标、地址栏输入；**不要**拼接搜索结果 URL、DOM 注入、`el.value=`、JS 跳转 |
 | 模式 | **有头** `OPENCLAW_BROWSER_HEADLESS=0`（生产强制，见 §0.2） |
-| 反检测 | stealth 默认开 `OPENCLAW_PLAYWRIGHT_STEALTH=1`（见 1.1） |
+| 浏览器兼容配置 | `OPENCLAW_PLAYWRIGHT_STEALTH` 仅用于经评估的兼容配置；不得用于伪造身份或绕过平台限制 |
 
 ### 1.1 Playwright 启动标准
 
 1. **有头**：`OPENCLAW_BROWSER_HEADLESS=0`（`.env.example` 默认；网页 RPA 生产路径禁止改成无头常态，见 §0.2）。
-2. **stealth 默认开**：`OPENCLAW_PLAYWRIGHT_STEALTH=1`；通过 `add_init_script` 注入指纹淡化脚本。
+2. **stealth 须受控**：`OPENCLAW_PLAYWRIGHT_STEALTH` 仅在目标平台授权、规则与项目评估允许时启用；不得把它理解为规避风控或伪造设备身份。
 3. **不要在技能里自行安装 playwright**；由宿主共享 runtime 提供。
 4. **不要默认传 `--no-sandbox`**（除非特定容器环境且已评估风险）。
 5. **不要默认传 `--disable-blink-features=AutomationControlled`**；platform-kit stealth 已覆盖，额外 flag 可能适得其反。
@@ -100,7 +144,7 @@ async def open_login(page):
 7. **强风控平台**：优先真实点击、键盘、鼠标、地址栏、account-manager 持久 profile；**不要**直接拼接搜索结果 URL 或 DOM 注入。
 8. **先 Profile 再开浏览器**：`user_data_dir` 必须来自 ensure/pick 到的 `profile_dir`；未拿到则不得进入本节后续步骤。
 
-指纹淡化（stealth）典型项：`navigator.webdriver=undefined`、`chrome.runtime`、`permissions.query`、`plugins`、`languages` 等。共享实现见 `jiangchang_skill_core.rpa`（platform-kit **>= 1.2.0**）。
+浏览器兼容配置由共享 `jiangchang_skill_core.rpa` 提供（platform-kit **>= 1.2.0**）。业务技能不得自行扩展指纹伪造、代理轮换或规避安全检测的代码；遇到明确风控信号时转人工或停止。
 
 **拟人操作**（必做）：
 
@@ -108,7 +152,7 @@ async def open_login(page):
 - 鼠标：贝塞尔曲线轨迹 + 微抖动；进场随机晃动。
 - 导航：用真实点击触发，**不要 `window.location.href=` / JS 点击跳转**。
 - 翻页：真实点击翻页控件，注意排除禁用态。
-- 延迟：每步之间 `random_delay`（`.env` 中 `STEP_DELAY_MIN/MAX`）。
+- 延迟：两个正常业务动作之间 `random_delay`（`.env` 中 `STEP_DELAY_MIN/MAX`，默认 1～3 秒）；页面状态仍须显式等待。
 
 ### 1.2 页面启动标准
 
@@ -243,6 +287,7 @@ from jiangchang_skill_core.rpa.stealth import stealth_enabled, STEALTH_INIT_SCRI
 - **DPI/缩放**：图像识别方案必须固定显示缩放比例；UIA 方案不受影响（优先用 UIA 即是为此）。
 - **存证**：同样要失败截图（截目标窗口/全屏），存到 `rpa-artifacts`。
 - **人工兜底**：U盾插拔、动态口令、人脸 → 停下等人工，超时 `ERROR:XXX_NEED_HUMAN`。
+- **禁止侵入**：不注入或 Hook 第三方进程，不修改客户端文件，不反编译或调用未授权私有协议。
 
 ```bash
 pip install pywinauto        # UIA 自动化
@@ -271,6 +316,7 @@ pip install pywinauto        # UIA 自动化
 - **登录态**：靠 App 自身保持登录，必要时引导人工首登一次。
 - **人工兜底**：短信验证码、人脸、指纹 → scrcpy 投屏让人工完成，程序轮询等待。
 - **存证**：失败时 `adb screencap` / Appium 截图存 `rpa-artifacts`。
+- **设备边界**：使用正常授权设备与官方 App；不 Root / 越狱，不 Hook，不修改 APK / IPA，不伪造设备身份或绕过签名、绑定与安全校验。
 
 ```bash
 # Android（首选）