Metadata-Version: 2.4
Name: isa-rpa
Version: 0.2.5
Summary: I-Search Agent RPA Python SDK，封装 OCR、验证码、DocAgent 等客户端能力
Keywords: rpa,ocr,captcha,docagent,sap
Author: isa
Author-email: isa <service@i-search.com.cn>
License-Expression: LicenseRef-Proprietary
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: httpx>=0.23
Requires-Dist: playwright>=1.60.0
Requires-Dist: pycryptodome>=3.20.0
Requires-Dist: pydantic>=2.0
Requires-Dist: requests>=2.28
Requires-Python: >=3.12
Project-URL: Homepage, https://www.i-search.com.cn/
Description-Content-Type: text/markdown

# 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 安装：

```bash
uv add isa-rpa
```

作为 CLI 工具安装：

```bash
uv tool install isa-rpa
```

也可以使用 `pip`：

```bash
pip install isa-rpa
```

## 打包与发布

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

```bash
uv build --no-sources
uv publish
```

构建产物位于 `dist/` 目录：

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

## CLI

查看帮助：

```bash
isa-rpa --help
```

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

- `isa-rpa browser <command>`：浏览器探索（探索 DOM 结构、定位元素、点击/填写、截图、执行 JS 等，每条命令独立连接 CDP，执行后退出）。命令清单见 `isa-rpa browser --help`，详细用法见 [profile/skills/isa-rpa/references/browser.md](../../profile/skills/isa-rpa/references/browser.md)。
- `isa-rpa credential <command>`：凭据管理（check/create/query/update/delete/list）。

如果在魔术师(magicx) docker 环境中运行，通常需要由运行时注入 `MAGICX_RUNTIME=docker`、`CLIENT_ID`、网关相关环境变量，以及浏览器会话所需的 `MAGICX_CDP_URL`（远程 CDP base，如 `http://192.168.11.23:8080`，不带 `/json/version`）。`MAGICX_CDP_URL` 不区分本地/docker，注入即优先使用：docker 环境下它是唯一来源，未注入或不可达会直接报错、不会本地拉起浏览器；本地注入则 `BrowserSession`/`isa-rpa browser` 优先连它，探测失败正常打日志后回退到本地 9222（探不到再本地拉起 Chromium）。

### 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` 读取，文件格式：

  ```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 等拿不到入口脚本路径的场景）。

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

### 凭据管理

```python
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 下也可以通过环境变量开启同样的调试打印：

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

### DocAgent

```python
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 流程代码只传业务参数。

```python
from isa_rpa import send_email

result = send_email(
    to=["alice@example.com"],
    cc=["manager@example.com"],
    subject="日报生成完成",
    body="请查看本次流程生成的报表。",
    attachments=["artifacts/report.xlsx"],
)
```

参数：

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

### 验证码识别

```python
from isa_rpa import CaptchaClient

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

## 适用范围

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

## 开发

```bash
uv sync
uv run pytest
uv run ruff check src/
```
