Metadata-Version: 2.4
Name: isa-rpa
Version: 0.2.3
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.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.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 内部运行环境、内部网关或平台侧注入的环境变量。公开安装不等于脱离这些运行条件即可直接使用。

## 安装

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

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

作为 CLI 工具安装：

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

也可以使用 `pip`：

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

## 打包与发布

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

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

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

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

## CLI

查看帮助：

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

```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 平台环境，但 `BrowserSession` 在没有平台环境时会自动 fallback 到本地启动 Chromium，可用于纯本地开发。
- 若你的运行环境不提供对应的网关、认证或共享组件，这些能力可能无法直接工作。
- 旧 RPA 设计器 / 机器人（Windows + Python 3.8 + `ubpa`）环境的兼容逻辑已内置到 `src/isa_rpa/_internal/legacy_ubpa/`，运行时不再依赖外部 `ubpa` 包。旧环境完全下线时可整目录删除该子包。

## 开发

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