Metadata-Version: 2.4
Name: isa-rpa
Version: 0.1.4
Summary: I-Search Agent RPA Python SDK，封装 OCR、验证码、DocAgent、VNC 等客户端能力
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.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: httpx>=0.23
Requires-Dist: playwright>=1.40
Requires-Dist: pycryptodome>=3.20.0
Requires-Dist: pydantic>=2.0
Requires-Dist: requests>=2.28
Requires-Python: >=3.8
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.8 兼容** 线（`0.1.x`）。Python 3.12+ 环境改用 `sdk/isa-rpa/`（`0.2.x`）。两者发布为**同一个 PyPI 包名 `isa-rpa`**，靠 `requires-python` 区分（`0.1.x: >=3.8`、`0.2.x: >=3.12`），`uv add isa-rpa` 会按当前 Python 自动选择兼容的最新版本（3.8 环境会落到 `0.1.x`）。

## 安装

如果使用方没有修改 `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-3-8/`。

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

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

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

## CLI

查看帮助：

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

如果在魔术师(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`/`VNCClient` 优先连它，探测失败正常打日志后回退到本地 9222（探不到再本地拉起 Chromium）。

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

### 验证码识别

```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/
```
