isa-rpa 0.4.0

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.3.x）。PyPI 上仍存在的 0.1.x 是旧 Python 3.8 兼容版本，仅作历史兼容保留、不再维护和上传 PyPI。

安装

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

uv add isa-rpa

作为 CLI 工具安装：

uv tool install isa-rpa

也可以使用 pip：

pip install isa-rpa

打包与发布

本模块位于 monorepo magicx-app/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 secret <command>：密码箱凭证管理（list/query/exists/create/update/delete）；调用方明文传入 / 获取, SDK 内部 SM2 加密后上送, name 主键、同租户唯一。详见 profile/skills/isa-rpa/references/secret.md。

• 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：通过 sidecar isa-pty-vnc-old(容器内 127.0.0.1:10913) 的 /api/auth/token 中转获取（需要 CLIENT_ID）。

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

  {
    "access_token": "xxxx"
  }
  

• 未设置或未识别 MAGICX_RUNTIME：直接抛 TokenError。可通过设置 MAGICAL_ACCESS_TOKEN 环境变量显式注入 token（最高优先级，跳过一切运行时探测）。

其中 <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 会被关掉，避免子进程泄漏

密码箱凭证

主推: SecretClient(对接 /api/password-credential/*, 与 web 端共用同一套 endpoint; 调用方明文传入 / 获取, SDK 内部用 SM2 公钥加密后上送, 网络上传输的密码字段始终是密文; name 主键、同租户唯一)。AI 在 main.py 中仅推荐用 query, 增删改请在场外通过 isa-rpa secret CLI 完成。

数据模型: 名称 + 账号 + 站点 + 密码 + 自定义字段 + 备注 + 共享范围; 密码与自定义字段至少其一非空。

from isa_rpa import SecretClient

detail = SecretClient().query(name="github_alice_login")
username = detail.get("username")
password = detail.get("password")
for f in detail.get("customFields") or []:
    print(f["key"], f["value"])

CLI 调试输出:

ISA_RPA_SECRET_DEBUG=1 isa-rpa secret query --name github_alice_login

完整字段、命名规范、工作流程见 profile/skills/isa-rpa/references/secret.md。

旧 CredentialClient(已下线)

CredentialClient 对接的是隔壁旧 RPA 的凭据接口(RSA/DES、assetName/assetValue 模型)。旧 RPA 控制台的凭据服务已全部下线, CredentialClient 仅保留导入、构造、close() 和上下文管理协议的兼容壳; 旧方法名仍在, 但 query / create / update / delete / list 调用都会抛出 CredentialError, 明确提示改用魔术师密码箱。CLI isa-rpa credential 子命令组在 0.3.0 起已下线。所有场景一律改用 SecretClient / isa-rpa secret。

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 的 CDP 解析按 MAGICX_RUNTIME 分流（详见上文「浏览器会话」环境变量说明）：纯本地开发（未设置 MAGICX_RUNTIME）下优先 MAGICX_CDP_URL、其次本地 9222、再探不到自动拉起 Chromium；docker 只连 MAGICX_CDP_URL、native（windows/macos/linux）改调客户端控制接口 /browser/open，两者探不到都直接报错、不本地兜底。
• 若你的运行环境不提供对应的网关、认证或共享组件，这些能力可能无法直接工作。

开发

uv sync
uv run pytest
uv run ruff check src/