client-commons/skill-template
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d17804e45b056e74dce3260e5816920a3e7702ca
skill-template/examples/simulator_browser_rpa
History
chendelian a3bd8faf87
All checks were successful
技能自动化发布 / release (push) Successful in 5s
Details
docs(config): unify config.get reads and remove ALLOW_* gates
2026-06-30 10:29:03 +08:00
..
sandbox
chore: auto release commit (2026-06-15 17:32:47)
2026-06-15 17:32:49 +08:00
scripts
docs(config): unify config.get reads and remove ALLOW_* gates
2026-06-30 10:29:03 +08:00
tests
chore: auto release commit (2026-06-15 17:32:47)
2026-06-15 17:32:49 +08:00
README.md
chore: auto release commit (2026-06-17 09:21:19)
2026-06-17 09:21:21 +08:00

README.md

Simulator Browser RPA Example

这是一个仿真浏览器 RPA 的可复制参考实现：在可控 sandbox 页面上，通过 Playwright 完成登录、表单填写、弹窗确认、结果解析。

本示例抽象自已跑通的「批量提交类」浏览器自动化 skill，但已去业务化，不包含真实银行/真实资金语义。

适合什么场景

  • 自有 仿真系统 / sandbox / training 页面
  • 需要 浏览器 RPA 做端到端演示或回归
  • 表单较复杂：多步登录、Tab 切换、动态增行、PIN 弹窗、成功页解析
  • 需要 adapter 分层：mock（CI）与 simulator_rpa（半集成）可切换

不适合什么场景

  • 真实第三方网站 + 高风控 + 人工验证码 → 优先看 ../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 时怎么做

按 copy map 选择性复制到 scripts/；不要整包照搬本目录，不要把本 README 当作新技能根 README。

Copy map（复制到新技能 scripts/）

来源（examples） 目标（新技能） 说明
examples/simulator_browser_rpa/scripts/service/browser_session.py scripts/service/browser_session.py URL 仅 page.goto，不进 launch args
examples/simulator_browser_rpa/scripts/service/account_client.py scripts/service/account_client.py 账号来源集中封装
examples/simulator_browser_rpa/scripts/service/task_service.py scripts/service/task_service.py 编排层，合并业务逻辑
examples/simulator_browser_rpa/scripts/service/adapter/ scripts/service/<domain>_adapter/ adapter 分层权威参考
examples/simulator_browser_rpa/scripts/util/constants.py scripts/util/constants.py 须替换业务常量
examples/simulator_browser_rpa/scripts/util/logging.py scripts/util/logging.py 可选
examples/simulator_browser_rpa/tests/ tests/ 可按需复制 dispatch / unit 测试
examples/simulator_browser_rpa/sandbox/demo_app.html — 仅仿真测试用，不进入生产 skill
examples/simulator_browser_rpa/README.md — 只读参考，不复制为新技能根 README

边界说明：

  • sandbox/ 只用于仿真测试与本地回归，不进入真实生产 skill
  • adapter/ 分层（base / mock / simulator_rpa）是仿真浏览器 RPA 的权威参考
  • mock / simulator_rpa 只用于测试与仿真，不要混入 real_browser_rpa 的真实站点逻辑
  • demo_app.html 是可运行沙箱页面，不是真实业务系统

保留：

  • 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 可用）

运行测试

cd examples/simulator_browser_rpa
python -m pytest tests/ -v

测试为 mock/纯函数，不需要启动真实浏览器。

当前状态

  • 示例代码与 sandbox 页面已就绪，可作为仿真浏览器 RPA 复制起点。
  • 未接入完整 CLI、数据库与 entitlement。
Reference in New Issue View Git Blame Copy Permalink