Agent RPA Runtime

基于 browser-use/browser-harness 的 Agentic RPA 运行时。 Browser Harness 通过 CDP WebSocket 直连 Chrome，让 AI Agent 驱动真实浏览器，替代传统 RPA 的复杂编排、脆弱选择器和高维护成本。

核心理念

传统 RPA（UiPath/影刀/八爪鱼）依赖硬编码的流程编排和固定选择器，一旦页面改版就全线崩溃。 Agent RPA 换了一个思路：

传统 RPA:  录制 → 硬编码流程 → 页面变了 → 崩溃 → 人工修复
Agent RPA: Agent 理解意图 → 动态执行 → 页面变了 → Agent 自愈 → 继续执行

三个关键能力：

Agentic 驱动 — Agent 理解任务意图，动态决策执行路径
自愈自迭代 — 选择器失效时 Agent 通过截图+JS 自动找到替代方案
分支决策 — 根据页面状态（验证码/登录墙/错误页）自动选择处理路径

架构

┌─────────────────────────────────────────────────────┐
│                    AI Agent                         │
│  (OpenClaw / Claude Code / Codex)                   │
│                                                     │
│  读取 SKILL.md → 规划任务 → 调用 rpa-harness.py       │
└─────────────────────┬───────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────┐
│  rpa-runtime (本项目)                                │
│                                                     │
│  rpa-harness.py    ← Python 桥接层                   │
│  ├─ 拼接 rpa-core.js + 场景脚本                       │
│  ├─ 调用 browser-harness CLI                        │
│  └─ 解析返回 JSON                                   │
│                                                     │
│  rpa-core.js       ← 浏览器内 RPA 核心库              │
│  ├─ 元素定位 (多策略降级)                             │
│  ├─ 人机行为模拟                                     │
│  ├─ 数据提取 / 表格解析                               │
│  └─ 分支判断 / 自愈                                  │
│                                                     │
│  scripts/          ← 场景脚本库                      │
└─────────────────────┬───────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────┐
│  browser-use/browser-harness                        │
│  (CDP 传输层)                                        │
│                                                     │
│  Chrome ← CDP WS → daemon.py → IPC → run.py         │
│                                                     │
│  核心能力:                                           │
│  • 截图驱动交互 (capture_screenshot → click_at_xy)    │
│  • JS 执行 (js()) — rpa-core.js 注入入口             │
│  • Tab 管理 / 导航 / 表单填充 / 文件上传               │
│  • Cloud Browser 支持 (可选)                         │
└─────────────────────┬───────────────────────────────┘
                      │
                      ▼
               ┌──────────────┐
               │  Real Chrome  │
               │  (v144+)      │
               └──────────────┘

Browser Harness 安装部署

什么是 Browser Harness

Browser Harness 是 browser-use 组织开源的轻量级浏览器控制工具（MIT 协议）。它通过 Chrome DevTools Protocol (CDP) WebSocket 直连 Chrome，提供截图→点击→验证的交互范式。

核心理念：

极薄 — ~1000 行 Python，4 个核心文件，无框架依赖
截图优先 — capture_screenshot() → 看图 → click_at_xy(x, y) → 再截图验证
Agent 自愈 — 执行中遇到缺失的 helper，Agent 当场编写并持久化到 agent_helpers.py
云端可选 — 支持 Browser Use Cloud（免费 tier: 3 并发浏览器）

对比传统方案：

	Selenium/Playwright	Browser Harness
安装	pip install + 驱动管理	`uv tool install -e .`
浏览器连接	启动新实例	连已有 Chrome（不丢登录态）
元素定位	CSS/XPath 选择器	截图 → 像素坐标
反检测	需 stealth 补丁	真实 Chrome，天然通过
自愈能力	无	Agent 写代码修复
代码量	数千行	~1000 行

环境要求

组件	最低版本	说明
Python	≥3.11	python.org
uv	任意	安装 uv
Chrome / Chromium	v144+	需开启远程调试
操作系统	macOS / Windows / Linux	—

Chrome 版本检查：/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --version（macOS）或 google-chrome --version（Linux）

安装步骤

Step 1 — 安装 browser-harness

git clone https://github.com/browser-use/browser-harness.git
cd browser-harness
uv tool install -e .
# 验证
command -v browser-harness

建议克隆到稳定路径（如 ~/Developer/browser-harness），不要放 /tmp。 Agent 编辑 agent_helpers.py 后下次调用即时生效。

Step 2 — 连接 Chrome

有两种方式：

Way 1（推荐 — 保留登录态）：在正在运行的 Chrome 中访问 chrome://inspect/#remote-debugging，勾选「Allow remote debugging for this browser instance」。此设置按 Profile 持久化，勾一次即可。Chrome 144+ 首次 attach 会弹出 Allow 确认框。

Way 2（自动化 — 无 popup）：以命令行参数启动 Chrome：

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-rpa-profile &

# 设置环境变量
export BU_CDP_URL=http://127.0.0.1:9222
# 或 IPv6 环境: export BU_CDP_URL='http://[::1]:9222'

Way 2 使用独立 Profile，不继承日常 Chrome 的登录态。如需登录态请用 Way 1。

Step 3 — 验证连接

browser-harness --doctor

预期输出：chrome running [ok]、daemon alive [ok]、active browser connections — ≥1

browser-harness -c 'print(page_info())'

预期输出当前标签页的 URL、标题、视口尺寸。

常用命令

操作	命令
健康检查	`browser-harness --doctor`
查看页面信息	`browser-harness -c 'print(page_info())'`
截图	`browser-harness -c 'capture_screenshot("/tmp/shot.png")'`
导航	`browser-harness -c 'new_tab("https://example.com"); wait_for_load()'`
执行 JS	`browser-harness -c 'print(js("document.title"))'`
点击坐标	`browser-harness -c 'click_at_xy(400, 300)'`
输入文本	`browser-harness -c 'type_text("hello")'`
填充表单	`browser-harness -c 'fill_input("#email", "user@test.com")'`
列出标签页	`browser-harness -c 'print(list_tabs())'`
重启 daemon	`browser-harness --reload`
更新版本	`browser-harness --update -y`

安装 rpa-runtime

方式一 — Agent 自动安装

将以下内容发给你的 AI Agent（OpenClaw / Claude Code / Codex）：

查阅 https://github.com/WW-AI-Lab/agent-rpa.git 并克隆到本地，安装skill，实测验证

Agent 会自动：下载仓库 → 安装 Skill → 验证 browser-harness 连接 → 运行测试。

方式二 — 手动安装

git clone git@github.com:WW-AI-Lab/agent-rpa.git
cd agent-rpa

# 确认 browser-harness 已安装
browser-harness --doctor

# 安装 Skill（Agent 用）
cp -r skills/agent-rpa ~/.openclaw/workspace/skills/
# 或 Claude Code 用户: echo '@~/path/to/agent-rpa/SKILL.md' >> ~/.claude/CLAUDE.md

验证安装

# 检查浏览器连接
python3 rpa-harness.py check

# 列出可用场景
python3 rpa-harness.py list

# 运行 Amazon 搜索场景
BU_CDP_URL='http://[::1]:9222' python3 rpa-harness.py run amazon/search-extract-detail.js \
  --params '{"kw":"wireless earbuds"}' \
  --url "https://www.amazon.com"

项目结构

rpa-runtime/
├── rpa-core.js                ← 浏览器内 RPA 核心库（定位/操作/提取/分支）
├── rpa-harness.py             ← Python 桥接层（封装 browser-harness CLI）
├── rpa-audit.js               ← 审计日志模块（操作记录/合规追踪）
├── rpa-stealth.js             ← 反检测增强模块（指纹对抗）
├── scripts/                   ← 场景脚本库
│   ├── amazon/                ← Amazon（搜索、详情提取）
│   ├── jd/                    ← 京东
│   ├── tmall/                 ← 天猫/淘宝
│   └── erp/                   ← 内部系统（API 模式，gitignore）
├── outputs/                   ← 运行输出（gitignore）
├── test/                      ← 测试与脚手架
└── skills/agent-rpa/          ← AI Agent Skill
    ├── SKILL.md               ← Skill 主文档
    └── references/api.md      ← rpa-core.js API 参考

脚本存储规范

类型	路径模式	示例
Browser 模式脚本	`scripts/<平台>/<动作>.js`	`scripts/amazon/search-extract-detail.js`
API 模式脚本	`scripts/<系统>/<接口>.sh`	`scripts/erp/opsoa-api.sh`
输出文件	`outputs/<平台>-<任务>-<日期>.<格式>`	`outputs/amazon-tents-2026-05-04.csv`

两种执行模式

模式	适用场景	传输层	执行方式
Browser 模式	外部网站（需渲染、JS 执行、反爬）	browser-harness (CDP)	`browser-harness -c 'js(rpa_code)'`
API 模式	内部系统（纯 API、可逆向接口）	curl / shell	`.sh`（curl + 环境变量）

内部系统（内网 IP）受 browser-harness 安全策略限制，自动走 API 模式。

快速开始

1. 通过 rpa-harness.py 执行

# Amazon 商品搜索
python3 rpa-harness.py run amazon/search-extract-detail.js \
  --params '{"kw":"wireless earbuds","maxItems":10}'

# 京东搜索
python3 rpa-harness.py run jd/search-extract.js \
  --params '{"kw":"蓝牙耳机"}'

2. Agent 侧执行流程

Agent 读取 SKILL.md
  ↓ 确定场景脚本路径
  ↓ 调用 rpa-harness.py run <scene> --params '{...}'
  ↓ rpa-harness.py 拼接 rpa-core.js + 场景脚本
  ↓ browser-harness -c 'js(完整代码)' 
  ↓ Chrome 内执行 → 返回 JSON
  ↓ Agent 解析 success 字段 → 决策下一步

3. 自愈流程

当脚本返回 success: false（选择器失效/页面变化）：

success: false
  ↓ Agent 调用 screenshot → 查看当前页面
  ↓ Agent 分析截图 → 找到新选择器或坐标
  ↓ 更新场景脚本的选择器 / 策略
  ↓ 重新执行

4. 截图优先交互范式（Browser Harness 标准流程）

# browser-harness 标准交互模式
capture_screenshot("/tmp/step1.png")       # 1. 截图看页面
# Agent 分析图片 → 找到目标坐标
click_at_xy(x, y)                          # 2. 像素坐标点击
capture_screenshot("/tmp/step2.png")       # 3. 再截图验证
# 仅在截图无法解决时才用 DOM
data = js("document.querySelector('.result').innerText")

rpa-core.js API 速查

函数	说明
`locate(strategies, timeout?)`	多策略元素定位（css/xpath/text/aria/placeholder）
`withRetry(fn, opts?)`	自动重试 + 指数退避
`humanClick(el)`	模拟真人点击
`humanType(el, text, opts?)`	逐字符输入（兼容 React/Vue）
`humanScroll(dir?, px?)`	平滑滚动
`waitForPageReady(timeout?)`	等待页面加载
`extractData(extractors)`	通用 KV 数据提取
`extractTable(selector, opts?)`	HTML 表格 → JSON
`searchAndExtract(keyword, opts?)`	搜索并提取列表
`fillForm(fields)`	批量表单填写
`checkPageStatus()`	页面状态诊断
`evaluateBranch(branches)`	条件分支判断

browser-harness Python API（常用）

函数	说明
`new_tab(url)`	新标签页打开并切换到该 tab
`goto_url(url)`	当前 tab 导航
`wait_for_load()`	等待页面加载完成
`capture_screenshot(path)`	截图保存 PNG
`click_at_xy(x, y)`	像素坐标点击
`type_text(text)`	Input.insertText 粘贴文本
`fill_input(selector, text)`	框架感知表单填充
`press_key(key)`	按键（Enter/Tab/Escape...）
`js(expression)`	在页面执行 JS 并返回值
`page_info()`	当前页面 URL/标题/尺寸
`list_tabs()`	列出所有 tab
`scroll(x, y, dy)`	鼠标滚轮滚动

完整 API 文档见 skills/agent-rpa/references/api.md。

实测验证（2026-05-06）

测试项	结果	备注
browser-harness --doctor	✅ 通过	Chrome 147 + daemon 正常
导航 httpbin.org	✅ 0.5s	page_info() 正常返回
截图功能	✅ PNG 正常	capture_screenshot()
JS 执行	✅ js() 正常	document.title 提取
type_text + press_key	✅ 正常	搜索框输入不走 IME
Amazon 搜索+提取	✅ 5 条商品	wireless earbuds 搜索成功
表单填充 (httpbin)	✅ fill_input OK	React/Vue 兼容

与传统方案对比

	Playwright/Selenium	影刀/UiPath	Agent RPA (本项目)
浏览器	无头/有头，需管理	自带浏览器	真实 Chrome (browser-harness)
传输层	Python/Node SDK	桌面客户端	browser-use/browser-harness (CDP)
安装	pip install + 驱动	下载客户端	`uv tool install -e .`
反检测	需 stealth 补丁	有限	真实 Chrome，天然通过
流程编排	硬编码	可视化拖拽	Agent 动态决策
交互范式	选择器优先	录制回放	截图优先 → 坐标点击
自愈能力	无	无	Agent + screenshot 自愈
维护成本	高	中	低（Agent 自适应）

贡献

欢迎提交 PR！新增场景脚本请遵循：

脚本存放到 scripts/<平台>/ 目录
文件头注释包含 @path、@platform、使用说明
使用 rpa.reset() 开头，rpa.result() 返回
测试通过后提交

License

MIT

相关项目：

browser-use/browser-harness — CDP 浏览器控制层（本项目传输层）
Browser Use Cloud — 云端浏览器（可选）
龙虾 OpenClaw — AI Agent 运行时（Agent 侧）

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Agent RPA Runtime

核心理念

架构

Browser Harness 安装部署

什么是 Browser Harness

环境要求

安装步骤

常用命令

安装 rpa-runtime

方式一 — Agent 自动安装

方式二 — 手动安装

验证安装

项目结构

脚本存储规范

两种执行模式

快速开始

1. 通过 rpa-harness.py 执行

2. Agent 侧执行流程

3. 自愈流程

4. 截图优先交互范式（Browser Harness 标准流程）

rpa-core.js API 速查

browser-harness Python API（常用）

实测验证（2026-05-06）

与传统方案对比

贡献

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
outputs		outputs
scripts		scripts
skills/agent-rpa		skills/agent-rpa
test		test
.gitignore		.gitignore
README.md		README.md
rpa-audit.js		rpa-audit.js
rpa-core.js		rpa-core.js
rpa-harness.py		rpa-harness.py
rpa-stealth.js		rpa-stealth.js

Folders and files

Latest commit

History

Repository files navigation

Agent RPA Runtime

核心理念

架构

Browser Harness 安装部署

什么是 Browser Harness

环境要求

安装步骤

常用命令

安装 rpa-runtime

方式一 — Agent 自动安装

方式二 — 手动安装

验证安装

项目结构

脚本存储规范

两种执行模式

快速开始

1. 通过 rpa-harness.py 执行

2. Agent 侧执行流程

3. 自愈流程

4. 截图优先交互范式（Browser Harness 标准流程）

rpa-core.js API 速查

browser-harness Python API（常用）

实测验证（2026-05-06）

与传统方案对比

贡献

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages