chore: auto release commit (2026-06-08 14:19:45)

references/RPA.md

@@ -28,33 +28,59 @@
 
 ## 1. 浏览器（标准已成熟）
 
-**选型：Playwright + 系统 Chrome/Edge。** 这是团队验证最充分的一条线（参考 `1688-scrape-contacts`、`disburse-payroll-icbc`）。
+**选型：Playwright + 系统 Chrome/Edge。** 这是团队验证最充分的一条线（标杆技能 `1688-scrape-contacts`、`receive-order` 已落地）。
+
+### 1.0 生产路径（优先）
 
 | 项 | 标准 |
 |----|------|
-| 驱动 | Playwright（Python） |
-| 浏览器 | 系统已装 Chrome/Edge，`channel="chrome"`；**不用内置 Chromium，无需 `playwright install`** |
-| 登录态 | `launch_persistent_context` + 用户 Profile 目录（由 account-manager 下发） |
-| 模式 | 默认有头；`OPENCLAW_BROWSER_HEADLESS=1` 转无头 |
-| 反反爬 | stealth 指纹注入 + 拟人输入/鼠标/延迟 + 滑块停下等人工（见下） |
+| 浏览器 | **优先系统 Chrome/Edge** + `launch_persistent_context`，`channel="chrome"` 或 Edge；不用内置 Chromium，**技能内不要 `playwright install`** |
+| 登录态 | 持久 Profile 目录；账号、profile、lease **统一走 account-manager**（或对应兄弟技能），不硬编码密码 |
+| CDP | **仅作诊断 / 桌面宿主类场景**；**不要**作为强风控站点的默认生产路径 |
+| 行为 | 模拟真实用户：真实点击、键盘、鼠标、地址栏输入；**不要**拼接搜索结果 URL、DOM 注入、`el.value=`、JS 跳转 |
+| 模式 | 默认有头 `OPENCLAW_BROWSER_HEADLESS=0`；无头仅 CI |
+| 反检测 | stealth 默认开 `OPENCLAW_PLAYWRIGHT_STEALTH=1`（见 1.1） |
 
-### 1.1 防反爬三件套（必做）
+### 1.1 Playwright 启动标准
 
-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`，轮询等人工通过或超时，**不自动操作滑块**。
+1. **默认有头**：`OPENCLAW_BROWSER_HEADLESS=0`（`.env.example` 默认值）。
+2. **stealth 默认开**：`OPENCLAW_PLAYWRIGHT_STEALTH=1`；通过 `add_init_script` 注入指纹淡化脚本。
+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. **强风控平台**：优先真实点击、键盘、鼠标、地址栏、持久 profile；**不要**直接拼接搜索结果 URL 或 DOM 注入。
 
-> 参考实现：`1688-scrape-contacts/scripts/service/anti_detect.py`、`util/playwright_stealth.py`、`service/login_service.py`（验证码等待）。已提升为共享库 `jiangchang_skill_core.rpa`（见 platform-kit）。
+指纹淡化（stealth）典型项：`navigator.webdriver=undefined`、`chrome.runtime`、`permissions.query`、`plugins`、`languages` 等。共享实现见 `jiangchang_skill_core.rpa`（platform-kit **>= 1.0.13**）。
 
-### 1.2 安装
+**拟人操作**（必做）：
+
+- 输入：逐字符 `keyboard.type(delay=90~240ms)`，**先真实点击聚焦再输入，绝不 `el.value=`**。
+- 鼠标：贝塞尔曲线轨迹 + 微抖动；进场随机晃动。
+- 导航：用真实点击触发，**不要 `window.location.href=` / JS 点击跳转**。
+- 翻页：真实点击翻页控件，注意排除禁用态。
+- 延迟：每步之间 `random_delay`（`.env` 中 `STEP_DELAY_MIN/MAX`）。
+
+### 1.2 页面启动标准
+
+优先级（高 → 低）：
+
+1. **launch args `start_url`**：浏览器启动即打开目标首页（推荐生产路径）。
+2. **profile preferences**：作为兜底（例如 homepage / startup URLs）。
+3. **程序化导航 `page.goto`**：仅最后兜底；强风控站点慎用裸 `goto` 深链。
+
+**生产路径不要依赖 CDP 接管现有页面**；CDP 仅用于诊断或桌面宿主已打开浏览器的场景。
+
+### 1.3 HITL / 验证码
+
+- 自动处理失败时**允许等待人工**：滑块、短信、人脸、U盾、动态口令等。
+- 等待人工验证时必须有：**字幕 step**（用户可见动作说明）、**结构化日志**、**超时**（`HUMAN_WAIT_TIMEOUT`）。
+- 检测到风控页（URL/DOM 特征）→ 抛 `ERROR:CAPTCHA_NEED_HUMAN`，轮询等待或超时，**不要强行绕过平台安全机制**。
+- **不要自动操作滑块**。
+
+> 共享库：`jiangchang_skill_core.rpa.wait_for_captcha_pass`；参考 `scripts/service/example_browser_rpa.py`。
+
+### 1.4 安装
 
 生产/宿主运行：`playwright` 由共享 runtime 提供，无需在技能内 `pip install`。
 
@@ -79,7 +105,7 @@ from jiangchang_skill_core.rpa import (
 from jiangchang_skill_core.rpa.stealth import stealth_enabled, STEALTH_INIT_SCRIPT
 ```
 
-- `RpaVideoSession` 来自 platform-kit；ffmpeg、背景音乐、media-assets 由 platform-kit 统一解析。
+- `RpaVideoSession` 来自 platform-kit **>= 1.0.13**；ffmpeg、背景音乐、media-assets 由 platform-kit 统一解析；已提供前置/后置缓冲、字幕、TTS 旁白、背景音乐循环、结尾淡出。
 - `health` 对上述资源做只读诊断，不下载、不修复。
 
 完整示例见 `scripts/service/example_browser_rpa.py` 与 `scripts/service/example_adapter/sim_rpa.py`。
@@ -161,16 +187,48 @@ skill 退出/抛错统一用 `ERROR:` 前缀 + 稳定码，方便宿主与上层
 
 ---
 
-## 5. 存证规范
+## 5. 存证与录屏规范
+
+### 5.1 截图存证
 
 - **路径**：`{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 不负责录屏**，仅浏览器自动化。
+- **常见 tag**：`before_submit` / `after_submit` / `captcha` / `login_fail` / `error`。
+
+### 5.2 RPA 视频 step 标准
+
+字幕是**用户可见动作说明**，不是技术日志。step 要贴近真实动作，不要只在大流程入口打点。
+
+推荐关键动作示例（按业务裁剪）：
+
+- 启动浏览器
+- 打开首页
+- 检查登录状态
+- 定位输入框
+- 输入关键词：xxx
+- 点击搜索
+- 等待结果
+- 打开详情页
+- 提取信息
+- 写入结果
+- 任务完成
+
+技术诊断、重复跳过、DB 写入可以显示但**通常不需要旁白**。
+
+`title` / `closing_title` 必须由 skill 传入**中文业务文案**（如「开始执行示例任务」「示例任务执行完成」）。
+
+### 5.3 录屏成片标准
+
+- RPA skill 默认 `OPENCLAW_RECORD_VIDEO=1`。
+- 使用 platform-kit 的 **`RpaVideoSession`**；**skill 不要自行合成视频**（不要自己调 ffmpeg 拼 MP4）。
+- `OPENCLAW_RECORD_VIDEO=0` 时 session 无副作用（不启 ffmpeg、不写字幕文件）。
 - **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`。
+- **中间产物**：`rpa-artifacts/{batch_id}/capture.mp4`、`subtitles/`、`logs/` 等。
+- 任务完成后 CLI / `result_summary` 应包含：`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()`。
 
 ---