219 lines
7.7 KiB
Markdown
219 lines
7.7 KiB
Markdown
# rpa_helpers 库 — 业务 skill 同进程登录
|
||
|
||
`scripts/service/rpa_helpers/` 是 account-manager v2 提供给业务 skill 的 **同进程 Python 库**。业务代码调用 **`ensure_logged_in`**，库按账号记录的 **`auth_strategy`** 分发到对应登录流程（底层基于 Playwright）。
|
||
|
||
## 与 CLI 的关系
|
||
|
||
| 路径 | 职责 |
|
||
|---|---|
|
||
| **CLI subprocess** | 获取结构化账号 JSON、租约、`get-credential --reveal` 明文密码；进程隔离、易于跨语言 |
|
||
| **rpa_helpers** | 在已有 `BrowserContext`/`Page` 上执行登录编排与人类化输入 |
|
||
|
||
推荐组合：**CLI → pick / lease → get-credential → `launch_browser_with_profile` + `ensure_logged_in`**。
|
||
|
||
## 集成方式
|
||
|
||
### Import 路径
|
||
|
||
```python
|
||
import sys
|
||
|
||
AM_ROOT = r"D:\OpenClaw\client-commons\account-manager"
|
||
sys.path.insert(0, f"{AM_ROOT}/scripts")
|
||
|
||
from service.rpa_helpers import (
|
||
AuthStrategyError,
|
||
LoginResult,
|
||
close_browser,
|
||
ensure_logged_in,
|
||
launch_browser_with_profile,
|
||
)
|
||
```
|
||
|
||
**务必**：`sys.path` 追加的是 **`…/account-manager/scripts`**，因此模块命名空间为 `service.rpa_helpers`（**不要**写成 `from scripts.service.rpa_helpers …`）。
|
||
|
||
### 运行时依赖
|
||
|
||
- Python **3.10+**
|
||
- 已安装 **`playwright`** Python 包（宿主 runtime 提供）
|
||
- 本机已安装 **Chrome 或 Edge**（启动时使用 channel 模式，优先 Chrome，失败回落 Edge——见 `service.browser_service.resolve_chromium_channel`）
|
||
|
||
文档不提供 `pip install …` 指令；版本由匠厂宿主统一管理。
|
||
|
||
---
|
||
|
||
## 公开 API 一览
|
||
|
||
下列符号由 `service/rpa_helpers/__init__.py` **导出（共 19 个名字）**：
|
||
|
||
| 分类 | 符号 |
|
||
|---|---|
|
||
| **dispatcher + 策略函数** | `ensure_logged_in`，以及 `ensure_logged_in_password_auto`、`ensure_logged_in_password_with_captcha`、`ensure_logged_in_password_plus_2fa`、`ensure_logged_in_qr_code_manual`、`ensure_logged_in_per_session_manual`、`ensure_logged_in_device_bound`、`ensure_logged_in_client_certificate`、`ensure_logged_in_api_token`、`ensure_logged_in_sso_redirect` |
|
||
| **结果 / 异常** | `LoginResult`，`AuthStrategyError` |
|
||
| **浏览器** | `launch_browser_with_profile`，`close_browser` |
|
||
| **人类化输入** | `pause`，`human_type`，`human_click`，`human_select`，`human_scroll_to` |
|
||
|
||
---
|
||
|
||
## `browser` 模块
|
||
|
||
### `launch_browser_with_profile(profile_dir, *, channel=None, headless=False, extra_args=None, locale="zh-CN") -> tuple[BrowserContext, Page]`
|
||
|
||
- 创建持久化上下文（`user_data_dir=profile_dir`），注入可选 stealth 脚本。
|
||
- `channel` 默认为宿主检测结果（Chrome 优先）。
|
||
- **必须在 `finally` 中调用 `close_browser(context)`**，否则 playwright driver 可能泄漏。
|
||
|
||
### `close_browser(ctx) -> None`
|
||
|
||
关闭上下文并停止内部的 Playwright session manager。
|
||
|
||
---
|
||
|
||
## `human` 模块（人类化操作）
|
||
|
||
| 函数 | 行为 |
|
||
|---|---|
|
||
| `pause(min_ms=200, max_ms=800)` | 随机等待 |
|
||
| `human_type(locator, text, *, per_char_ms_range=(50, 200), pre_pause=True)` | 滚动进入视图 → 停顿 → `click` → 逐字符 `type` |
|
||
| `human_click(locator)` | 滚动 → 停顿 → `click` |
|
||
| `human_select(locator, value_or_label)` | 滚动 → 停顿 → `select_option`（依次尝试 value / label） |
|
||
| `human_scroll_to(locator)` | 平滑滚动到元素 |
|
||
|
||
_locator_ 均为 Playwright `Locator`。
|
||
|
||
---
|
||
|
||
## `auth_flows` 模块
|
||
|
||
### `ensure_logged_in(page, account, *, credentials=None, **kwargs) -> LoginResult`
|
||
|
||
1. 读取 `account["auth_strategy"]`。为空字符串 → 抛出 `AuthStrategyError(ERR_AUTH_STRATEGY_NOT_SUPPORTED)`。
|
||
2. 若策略需要密码则要求 `credentials["plaintext"]`；缺失 → `ERR_CREDENTIAL_MISSING`。
|
||
3. 分派到对应 `ensure_logged_in_*`。
|
||
4. 未知策略 → `AuthStrategyError(ERR_AUTH_STRATEGY_NOT_SUPPORTED)`。
|
||
|
||
附加 kwargs 会透传给具体策略（如 `captcha_value`、`wait_human_sec`）。
|
||
|
||
### `LoginResult`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `ok` | `bool` | 流程是否达到判定条件 |
|
||
| `needs_human` | `bool` | 是否需要人工协助（扫码 / OTP / SSO 等） |
|
||
| `message` | `str` | 描述信息（便于日志） |
|
||
|
||
### `AuthStrategyError`
|
||
|
||
属性：`code: str`，`message: str`。错误码与 CLI / [`ERRORS.md`](ERRORS.md) 对齐。
|
||
|
||
### 九个 `ensure_logged_in_*` 入口
|
||
|
||
业务代码通常只调用 `ensure_logged_in`。如需针对性 reuse，可直接 import `auth_flows` 中的同名函数；签名见源码 `scripts/service/rpa_helpers/auth_flows.py`。
|
||
|
||
---
|
||
|
||
## 已登录检测（`_is_already_logged_in`）
|
||
|
||
核心逻辑：
|
||
|
||
1. 读取当前 `page.url`；空白页 → **False**。
|
||
2. 仅在账号 `extra_json`（可为 dict 或 JSON 字符串）中出现以下 hook 之一才可能返回 True：
|
||
- **`logged_in_url_pattern`**：正则，匹配当前 URL。
|
||
- **`logged_in_selector`**：CSS/XPath selector，`locator.first.is_visible(timeout=500)`。
|
||
3. 若无任一 hook → **默认 False** → **除非已有持久化 session**，否则会完整跑登录流程。
|
||
|
||
### 接入建议
|
||
|
||
1. 首次上线：`auth_strategy=qr_code_manual` + 无 hook → 用户扫码登录。
|
||
2. 登录成功后记录典型 URL 片段或 DOM selector。
|
||
3. 写入账号 `extra_json`，例如：
|
||
|
||
```python
|
||
{
|
||
"logged_in_url_pattern": r"/user/",
|
||
"logged_in_selector": "div.avatar-wrapper"
|
||
}
|
||
```
|
||
|
||
4. 下次启动 → `_is_already_logged_in` 命中 → `needs_human` 可能降低。
|
||
|
||
### `per_session_manual` 的差异
|
||
|
||
该策略 **开场不会调用 `_is_already_logged_in`**，总是导航到业务 URL 并等待人工完成登录（适合强制会话）。
|
||
|
||
---
|
||
|
||
## 设备绑定策略（`device_bound`）
|
||
|
||
如账号设置了 `device_fingerprint`，库会使用 `_current_machine_fingerprint()`（hostname + MAC 派生）比对；不一致抛出 **`ERR_DEVICE_FINGERPRINT_MISMATCH`**。
|
||
|
||
---
|
||
|
||
## 客户端证书策略（`client_certificate`）
|
||
|
||
直接抛出 **`ERR_AUTH_STRATEGY_NOT_AUTOMATABLE`**；请在宿主机手动装载证书后使用其它路径衔接。
|
||
|
||
---
|
||
|
||
## 完整示例（CLI + rpa_helpers）
|
||
|
||
```python
|
||
import json
|
||
import subprocess
|
||
import sys
|
||
|
||
AM = r"D:\OpenClaw\client-commons\account-manager"
|
||
PY = sys.executable
|
||
MAIN = f"{AM}/scripts/main.py"
|
||
|
||
sys.path.insert(0, f"{AM}/scripts")
|
||
from service.rpa_helpers import launch_browser_with_profile, close_browser, ensure_logged_in
|
||
|
||
|
||
def am_json(argv: list[str]) -> dict:
|
||
proc = subprocess.run([PY, MAIN, *argv], capture_output=True, text=True, check=False)
|
||
line = (proc.stdout or "").splitlines()[0]
|
||
return json.loads(line)
|
||
|
||
|
||
acc = am_json(
|
||
["account", "pick-web", "--platform", "icbc_sim", "--lease", "--holder", "monitor-rates"]
|
||
)
|
||
|
||
cred = am_json(
|
||
[
|
||
"account",
|
||
"get-credential",
|
||
str(acc["id"]),
|
||
"--reveal",
|
||
"--lease-token",
|
||
acc["lease_token"],
|
||
]
|
||
)
|
||
|
||
plaintext = cred.get("plaintext")
|
||
if plaintext in (None, ""):
|
||
raise RuntimeError("no plaintext returned; check secret_storage / lease")
|
||
|
||
ctx, page = launch_browser_with_profile(acc["profile_dir"])
|
||
try:
|
||
result = ensure_logged_in(page, acc, credentials={"plaintext": plaintext})
|
||
if not result.ok:
|
||
raise RuntimeError(result.message)
|
||
# …业务代码…
|
||
finally:
|
||
close_browser(ctx)
|
||
subprocess.run([PY, MAIN, "lease", "release", acc["lease_token"]], check=False)
|
||
```
|
||
|
||
---
|
||
|
||
## 测试建议
|
||
|
||
- account-manager 仓库内置 **107** 个 pytest（截至 v2.0.0 文档修订时），覆盖 CLI / schema / rpa_helpers mock 路径。
|
||
- 业务 skill：
|
||
- **单元测试**：patch `ensure_logged_in` → 返回 `LoginResult(ok=True, …)`。
|
||
- **端到端**：在 Windows + 真浏览器环境标记 `@pytest.mark.integration`，禁止在 CI 泄露明文密码。
|
||
|
||
更多 CLI 细节参见 [`CLI.md`](CLI.md)、[`INTEGRATION.md`](INTEGRATION.md)。
|