chore: auto release commit (2026-06-15 17:32:47)

development/RPA.md

@@ -63,11 +63,26 @@
 
 ### 1.2 页面启动标准
 
-优先级（高 → 低）：
+**`launch_persistent_context` 的 `args` 只能放 Chrome 启动参数**（例如 `--start-maximized`、`--disable-blink-features=AutomationControlled` 等）。
 
-1. **launch args `start_url`**：浏览器启动即打开目标首页（推荐生产路径）。
-2. **profile preferences**：作为兜底（例如 homepage / startup URLs）。
-3. **程序化导航 `page.goto`**：仅最后兜底；强风控站点慎用裸 `goto` 深链。
+**绝对不要把 `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 仅用于诊断或桌面宿主已打开浏览器的场景。
 
@@ -78,7 +93,11 @@
 - 检测到风控页（URL/DOM 特征）→ 抛 `ERROR:CAPTCHA_NEED_HUMAN`，轮询等待或超时，**不要强行绕过平台安全机制**。
 - **不要自动操作滑块**。
 
-> 共享库：`jiangchang_skill_core.rpa.wait_for_captcha_pass`；参考 `scripts/service/example_browser_rpa.py`。
+> 共享库：`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 安装
 
@@ -108,7 +127,31 @@ from jiangchang_skill_core.rpa.stealth import stealth_enabled, STEALTH_INIT_SCRI
 - `RpaVideoSession` 来自 platform-kit **>= 1.0.14**；ffmpeg、背景音乐、media-assets 由 platform-kit 统一解析；已提供前置/后置缓冲、字幕、TTS 旁白、背景音乐循环、结尾淡出。
 - `health` 对上述资源做只读诊断，不下载、不修复。
 
-完整示例见 `scripts/service/example_browser_rpa.py` 与 `scripts/service/example_adapter/sim_rpa.py`。
+### 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 封装
+
+模板内 adapter 仿真示例（`scripts/service/example_adapter/sim_rpa.py`）仅用于 **adapter 四档骨架**，不能替代真实浏览器 RPA 规范。
+
+### 1.6 仿真浏览器 RPA 示例（必读）
+
+开发**自有仿真页面 / sandbox / 可控 DOM 的浏览器 RPA**（表单填写、批量提交、弹窗确认）时：
+
+1. **必须先阅读** `examples/simulator_browser_rpa/README.md`
+2. 再参考：
+   - `examples/simulator_browser_rpa/scripts/service/browser_session.py`
+   - `examples/simulator_browser_rpa/scripts/service/adapter/`（base / mock / simulator_rpa / dispatch）
+   - `examples/simulator_browser_rpa/scripts/service/task_service.py`
+   - `examples/simulator_browser_rpa/sandbox/demo_app.html`
+
+> **先选类型再写代码**：真实第三方网站 → `real_browser_rpa`；自有 sandbox → `simulator_browser_rpa`。不要跨类型照抄 selector 或业务流程。
 
 ---