isa-rpa 0.2.7

I-Search Agent RPA Python SDK，封装 OCR、验证码、DocAgent 等客户端能力

isa-rpa

I-Search Agent RPA Python SDK，封装 OCR、验证码、DocAgent、浏览器会话、凭据、邮件发送等客户端能力。

该包可从官方 PyPI 安装，但其中部分能力依赖 I-Search 内部运行环境、内部网关或平台侧注入的环境变量。公开安装不等于脱离这些运行条件即可直接使用。

版本线说明：本目录是 Python 3.12+ 线（0.2.x）。需要兼容 Python 3.8 时改用 sdk/isa-rpa-3-8/（0.1.x）。两者发布为同一个 PyPI 包名 isa-rpa，靠 requires-python 区分（0.1.x: >=3.8、0.2.x: >=3.12），uv add isa-rpa 会按当前 Python 自动选择兼容的最新版本。

安装

如果使用方没有修改 uv 的默认索引，可以直接从官方 PyPI 安装：

uv add isa-rpa

作为 CLI 工具安装：

uv tool install isa-rpa

也可以使用 pip：

pip install isa-rpa

打包与发布

本模块位于 monorepo magicx-runtime/sdk/isa-rpa/。

uv build --no-sources
uv publish

构建产物位于 dist/ 目录：

dist/isa_rpa-0.2.5-py3-none-any.whl
dist/isa_rpa-0.2.5.tar.gz

CLI

查看帮助：

isa-rpa --help

isa-rpa 是伞形命令，按命令组分子命令：

• isa-rpa browser <command>：浏览器探索（探索 DOM 结构、定位元素、点击/填写、截图、执行 JS 等，每条命令独立连接 CDP，执行后退出）。命令清单见 isa-rpa browser --help，详细用法见 profile/skills/isa-rpa/references/browser.md。

• isa-rpa credential <command>：凭据管理（check/create/query/update/delete/list）。

• isa-rpa rollout <input.jsonl> [-o output.md] [--full]：把大模型存档的 JSONL 转换为人读的 Markdown（自用调试工具）。

  isa-rpa rollout session.jsonl                 # 紧凑格式，生成 rollout-compact.md
  isa-rpa rollout session.jsonl --full          # 完整格式，生成 rollout-full.md
  isa-rpa rollout session.jsonl -o out.md       # 指定输出路径
  

  • 默认输出紧凑格式（rollout-compact.md），--full 输出完整 Markdown（rollout-full.md）。
  • 不指定 -o 时输出到当前工作目录，同名文件已存在时自动追加 (1)、(2) 等序号。

如果在魔术师(magicx) docker 环境中运行，通常需要由运行时注入 MAGICX_RUNTIME=docker、CLIENT_ID、网关相关环境变量，以及浏览器会话所需的 MAGICX_CDP_URL（远程 CDP base，如 http://192.168.11.23:8080，不带 /json/version）。

浏览器会话（BrowserSession / isa-rpa browser）按 MAGICX_RUNTIME 解析 CDP 地址，优先级如下：

1. MAGICX_CDP_URL（不区分运行环境，注入即优先）：探测 <base>/json/version 取 webSocketDebuggerUrl。
2. MAGICX_RUNTIME=docker：MAGICX_CDP_URL 是唯一来源，未注入或不可达直接报错，不本地兜底。
3. MAGICX_RUNTIME=windows|macos|linux（native）：客户端不注入 MAGICX_CDP_URL，改调本地客户端控制接口 GET http://127.0.0.1:<MAGICX_CONTROL_PORT>/browser/open?tenantId=<RPA_TENANT_ID> 拉起/复用本地 chrome 单例（MAGICX_CONTROL_PORT 默认 9876，由客户端 daemon 注入；控制接口内部已等 CDP 就绪），用返回的 cdpUrl 当远程 CDP 探测。控制接口是浏览器的唯一权威来源，调用失败（客户端没在跑 / 401 鉴权失败 / Chrome 拉起失败）直接报错，不本地兜底。若 native 环境也注入了 MAGICX_CDP_URL 则按第 1 条优先用它、失败同样直接报错。
4. 其它（未设置 MAGICX_RUNTIME 或非上述值）：注入了 MAGICX_CDP_URL 就优先连，探测失败回退本地 9222（探不到再本地拉起 Chromium）；未注入则直接探本地 9222。

Token 获取方式

统一 token 获取（get_token()）按 MAGICX_RUNTIME 自动适配运行环境：

• MAGICX_RUNTIME=docker：通过 app-server-http 的 HTTP 接口获取（需要 CLIENT_ID）。

• MAGICX_RUNTIME=windows|macos|linux：从 <MAGICX_HOME>/isa-auth.json 读取，文件格式：

  {
    "access_token": "xxxx"
  }
  

• 未设置 MAGICX_RUNTIME：回退到旧 RPA 设计器 / 机器人环境的兼容层。

其中 <MAGICX_HOME> 为魔术师(magicx)主目录，解析逻辑（多端兼容）：优先读取环境变量 MAGICX_HOME（支持 ~ 展开），未设置时回退到用户主目录下的 ~/.magicx。

Python SDK

浏览器会话

统一的 Playwright 浏览器入口，自动处理魔术师(magicx) docker 环境（连接已有 CDP）与本地开发环境（首次会启动有头浏览器并在 .cache/isa-rpa/chromium-profile/ 保留登录态）。本地启动时按优先级解析可执行文件：用户系统已安装的 Google Chrome → Playwright 自带的 Chromium；都没有则提示安装 Chrome 或执行 uv run playwright install chromium。

本地兜底启动时，profile 目录按以下顺序解析：

1. 环境变量 ISA_RPA_CHROME_PROFILE_DIR（绝对路径，用户自定义）；
2. 入口脚本所在目录下的 .cache/isa-rpa/chromium-profile/（即 main.py 旁边，不受当前工作目录影响）；
3. 兜底用户家目录 ~/.cache/isa-rpa/chromium-profile/（用于 REPL、python -c、Jupyter、pytest 等拿不到入口脚本路径的场景）。

import asyncio
from isa_rpa import BrowserSession

async def main():
    async with BrowserSession() as context:
        page = context.pages[0] if context.pages else await context.new_page()
        await page.goto("https://example.com")
        print(await page.title())

asyncio.run(main())

退出 async with 时由 SDK 自行决定是否关闭浏览器：

• 通过 CDP 连接的共享浏览器不关
• 本地兜底启动的 Chromium 会被关掉，避免子进程泄漏

凭据管理

from isa_rpa import CredentialClient

client = CredentialClient()
items = client.list()
detail = client.query(name="测试凭据")

# 排查非魔术师(magicx) docker 环境下的 token / header / 请求体 / 响应内容时可打开调试输出
debug_client = CredentialClient(debug=True)
debug_client.query(name="测试凭据")

CLI 下也可以通过环境变量开启同样的调试打印：

ISA_RPA_CREDENTIAL_DEBUG=1 isa-rpa credential query --name 测试凭据

DocAgent

from isa_rpa import DocAgentClient

client = DocAgentClient(token="your-token")
files = client.list_files(project_code="PRJ001")
bills = client.list_bills(project_code="PRJ001")

邮件发送

send_email() 通过平台内置发件箱发送邮件。SMTP 密钥、发件账号、权限、限流和审计由平台后端控制，Python 流程代码只传业务参数。

from isa_rpa import send_email

result = send_email(
    to=["[e-mail]"],
    cc=["[e-mail]"],
    subject="日报生成完成",
    body="请查看本次流程生成的报表。",
    attachments=["artifacts/report.xlsx"],
)

参数：

• to：必填，收件人邮箱，支持字符串或字符串列表。
• cc：可选，抄送人邮箱，支持字符串或字符串列表。
• subject：必填，邮件主题。
• body：必填，邮件正文。
• attachments：可选，附件路径，支持字符串或路径列表；路径必须指向当前运行环境可访问的文件。

验证码识别

from isa_rpa import CaptchaClient

client = CaptchaClient(
    api_key="your-api-key",
    secret_key="your-secret-key",
)

适用范围

• OCR、验证码识别等能力可按各自接口配置独立使用。
• 浏览器会话、凭据、DocAgent、统一 token 获取等能力通常依赖 I-Search 平台环境。BrowserSession 的 CDP 解析按 MAGICX_RUNTIME 分流（详见上文「浏览器会话」环境变量说明）：纯本地开发（未设置 MAGICX_RUNTIME）下优先 MAGICX_CDP_URL、其次本地 9222、再探不到自动拉起 Chromium；docker 只连 MAGICX_CDP_URL、native（windows/macos/linux）改调客户端控制接口 /browser/open，两者探不到都直接报错、不本地兜底。
• 若你的运行环境不提供对应的网关、认证或共享组件，这些能力可能无法直接工作。
• 旧 RPA 设计器 / 机器人（Windows + Python 3.8 + ubpa）环境的兼容逻辑已内置到 src/isa_rpa/_internal/legacy_ubpa/，运行时不再依赖外部 ubpa 包。旧环境完全下线时可整目录删除该子包。

开发

uv sync
uv run pytest
uv run ruff check src/