isa-rpa 0.1.3

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

isa-rpa

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

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

安装

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

uv add isa-rpa

作为 CLI 工具安装：

uv tool install isa-rpa

也可以使用 pip：

pip install isa-rpa

打包与发布

本模块位于 monorepo rpa-code-agent/sdk/isa-rpa/。

uv build --no-sources
uv publish

构建产物位于 dist/ 目录：

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

CLI

查看帮助：

isa-rpa --help

如果在魔术师(magicx) docker 环境中运行，通常需要由运行时注入 MAGICX_RUNTIME=docker、CLIENT_ID 以及网关相关环境变量。

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")

验证码识别

from isa_rpa import CaptchaClient

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

适用范围

• OCR、验证码识别等能力可按各自接口配置独立使用。
• 浏览器会话、凭据、DocAgent、统一 token 获取等能力通常依赖 I-Search 平台环境，但 BrowserSession 在没有平台环境时会自动 fallback 到本地启动 Chromium，可用于纯本地开发。
• 若你的运行环境不提供对应的网关、认证或共享组件，这些能力可能无法直接工作。
• 旧 RPA 设计器 / 机器人（Windows + Python 3.8 + ubpa）环境的兼容逻辑已内置到 src/isa_rpa/_internal/legacy_ubpa/，运行时不再依赖外部 ubpa 包。旧环境完全下线时可整目录删除该子包。

开发

uv sync
uv run pytest
uv run ruff check src/