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

examples/simulator_browser_rpa/README.md

@@ -0,0 +1,125 @@
+# Simulator Browser RPA Example
+
+这是一个**仿真浏览器 RPA** 的可复制参考实现：在可控 sandbox 页面上，通过 Playwright 完成登录、表单填写、弹窗确认、结果解析。
+
+本示例抽象自已跑通的「批量提交类」浏览器自动化 skill，但已去业务化，不包含真实银行/真实资金语义。
+
+## 适合什么场景
+
+- 自有 **仿真系统 / sandbox / training 页面**
+- 需要 **浏览器 RPA** 做端到端演示或回归
+- 表单较复杂：多步登录、Tab 切换、动态增行、PIN 弹窗、成功页解析
+- 需要 **adapter 分层**：mock（CI）与 simulator_rpa（半集成）可切换
+
+## 不适合什么场景
+
+- **真实第三方网站 + 高风控 + 人工验证码** → 优先看 [`../real_browser_rpa/README.md`](../real_browser_rpa/README.md)
+- 目标系统有稳定 **官方 API** → 不要硬写浏览器 RPA，后续参考 `real_api`
+- **不要把本示例的业务字段、selector、sandbox URL 原样复制**到你的 skill
+
+## 目录结构
+
+```
+simulator_browser_rpa/
+├── README.md
+├── sandbox/
+│   └── demo_app.html          # 本地仿真页面（稳定 data-testid / name）
+├── scripts/
+│   ├── service/
+│   │   ├── browser_session.py # 浏览器启动（URL 仅 page.goto）
+│   │   ├── account_client.py  # 账号来源集中封装
+│   │   ├── task_service.py    # 编排层
+│   │   └── adapter/
+│   │       ├── base.py        # BatchItem / BatchSubmitResult 契约
+│   │       ├── mock.py        # mock/unit 档
+│   │       ├── simulator_rpa.py
+│   │       └── __init__.py    # select_adapter
+│   └── util/
+│       ├── constants.py
+│       └── logging.py
+└── tests/
+    ├── test_adapter_dispatch.py
+    ├── test_simulator_rpa_unit.py
+    └── test_stop_reason.py
+```
+
+## 文件职责
+
+| 文件 | 职责 |
+|---|---|
+| `browser_session.py` | 系统 Chrome/Edge + launch args 规范；支持 profile / 无 profile |
+| `account_client.py` | 示例从环境变量读账号；真实 skill 可在此集中对接 account-manager |
+| `adapter/base.py` | 数据契约与 `BatchAdapterBase` |
+| `adapter/mock.py` | 不启浏览器，供 unit/mock/CI |
+| `adapter/simulator_rpa.py` | 仿真 RPA 主流程 |
+| `task_service.py` | 校验输入 → 选 adapter → 提交 → 返回 summary |
+| `sandbox/demo_app.html` | 可控 DOM，配合 selector 稳定 |
+| `tests/` | dispatch、URL 不进 launch args、失败转结果 |
+
+## 核心流程
+
+1. `task_service.run_batch_submit(target, items)` 校验参数
+2. `select_adapter()` 按 `OPENCLAW_TEST_TARGET` 选择 mock 或 simulator RPA
+3. simulator 档：`pick_simulator_account()` → `set_credentials()` → `submit_batch()`
+4. RPA：登录两步 → 批量页 → 填表 → 提交 → PIN → 解析 `batch_id`
+5. 失败截图（有 `artifacts_dir` 时）→ 返回 `BatchSubmitResult`
+
+## 复制到新 skill 时怎么做
+
+**保留：**
+
+- adapter 分层（base / mock / simulator_rpa / `select_adapter`）
+- `browser_session.py` 启动规范（**URL 不进 launch args**）
+- `account_client.py` 集中封装模式
+- 关键节点结构化日志 + 失败截图
+- 测试：dispatch、launch args、错误转 `BatchSubmitResult`
+
+**替换：**
+
+- `BatchItem` 字段与校验规则
+- `sandbox/demo_app.html` 或 `SIMULATOR_BASE_URL` 指向的页面
+- 全部 DOM selector（必须 F12 实测）
+- `task_service.py` 输入输出与 DB/任务日志
+- mock 返回字段、成功页 `batch_id` 解析逻辑
+
+## 明确禁止
+
+- 不要复制 `__pycache__`、`.pytest_cache`、`artifacts/`、`recordings/` 等生成物
+- **不要在技能侧**执行 `playwright install` / `pip install playwright`（Python 包由宿主共享 runtime 提供）
+- **不要把 URL 放进** `launch_persistent_context(args=[...])`
+- **不要在** `task_service.py` / RPA 主流程里散落 account-manager subprocess
+- **不要把真实生产系统**配置到 `simulator_rpa` 档位
+- 不要照抄 slug、logger 名、演示账号到生产 skill
+
+## 依赖说明
+
+- Python 3.10+
+- Python 包 `playwright`：由**宿主共享 runtime** 提供；技能侧不要写入 `requirements.txt`，不要 `pip install playwright`
+- 默认使用**系统 Chrome/Edge**，不使用 Playwright 内置 Chromium
+- 技能侧不要执行 `playwright install` / `playwright install chromium`
+- 本地独立开发若缺 Playwright Python 包，仅作开发机临时补装；生产由宿主解决
+- `jiangchang_skill_core.runtime_env.find_chrome_executable`（可选，用于查找系统浏览器）
+
+## 环境变量（示例）
+
+| 变量 | 说明 |
+|---|---|
+| `OPENCLAW_TEST_TARGET` | `mock`/`unit` → Mock；默认 → Simulator RPA |
+| `SIMULATOR_BASE_URL` | 仿真页 URL；默认本地 `sandbox/demo_app.html` 的 file URI |
+| `SIMULATOR_LOGIN_ID` / `PASSWORD` / `TOKEN_PIN` | 演示账号 |
+| `SIMULATOR_PROFILE_DIR` | 可选 persistent profile |
+| `OPENCLAW_BROWSER_HEADLESS` | `0` 默认有头；`1` 无头模式（CI 可用） |
+
+## 运行测试
+
+```bash
+cd examples/simulator_browser_rpa
+python -m pytest tests/ -v
+```
+
+测试为 mock/纯函数，**不需要启动真实浏览器**。
+
+## 当前状态
+
+- 示例代码与 sandbox 页面已就绪，可作为仿真浏览器 RPA 复制起点。
+- 未接入完整 CLI、数据库与 entitlement。