Metadata-Version: 2.4
Name: rpa-skill-runtime
Version: 0.3.0
Summary: 面向独立 RPA Skill 的任务与 CloakBrowser 运行时
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: cloakbrowser[geoip]<0.5,>=0.4.10
Requires-Dist: playwright>=1.61.0

# rpa-skill-runtime

独立 RPA Skill 共用的任务与 CloakBrowser 运行时。它负责任务进程、BrowserContext、Page、
JSON 动作协议和 Playwright `storage_state`，不包含登录业务、系统选择器、UiTools、UI 框架
矩阵、Skill 生成器或页面探测工具。

## 安装

Python 最低版本为 3.10：

```bash
python3.12 -m pip install "rpa-skill-runtime>=0.3.0,<0.4"
python3.12 -m cloakbrowser install
```

Runtime 直接依赖 `cloakbrowser[geoip]>=0.4.10,<0.5` 和 `playwright>=1.61.0`。Playwright
仅提供控制 API，不安装或启动 stock Chromium。

系统 Skill 通过 `lifecycle_main` 启动任务，通过 `action_main` 执行自己的登录和业务动作。每个
`manage.py` 必须在代码中固定认证域，例如：

```python
lifecycle_main(__file__, auth_scope="example-system")
```

`auth_scope` 不能由 stdin 覆盖。任务默认有头、关闭拟人操作；Skill 可在自己的 `manage.py`
使用 `default_headless`、`default_humanize` 和 `fixed_browser_args` 声明固定默认值。调用方只可在
`manage.py start` 传入 `headless`、`humanize` 和额外 `browser_args`，任务创建后不可切换。
浏览器首次启动每次最多等待 30 秒，失败后按 2 秒、5 秒间隔自动重试两次；成功结果的
`startup` 字段给出尝试次数、是否恢复及总耗时，业务动作开始后不会自动重放。

账号登录成功后由对应登录动作调用保存接口。canonical 登录态按代码固定的 `auth_scope` 和
账号隔离，路径为：

```text
$RPA_SKILLS_HOME/auth/<auth_scope>/accounts/<account-hash>/auth.json
```

因此不同 Skill 可以在固定相同 `auth_scope` 时复用登录态，但仍各自启动独立任务、Browser、
Context、Page 和任务目录；0.3.0 不兼容未传 `auth_scope` 的旧 `manage.py`。已有登录态的任务
会在成功业务动作后自动刷新：首次变化立即写入，后续按 300 秒节流，并在正常关闭或 idle
timeout 前刷新待保存状态。失败动作不产生快照，同账号并发任务采用最后原子写入覆盖。

## 发布

发布脚本位于 `rpa-skill-runtime/`：

```bash
./publish.sh --dry-run
./publish.sh --dry-run --bump minor
./publish.sh --bump minor
./publish.sh --repository internal
./publish.sh --install-current
TWINE_REPOSITORY_URL=https://pypi.example.com/legacy/ ./publish.sh
```

默认递增 patch 并发布到公开 PyPI；`--bump minor` 递增 minor 并将 patch 归零。`--dry-run`
测试、构建和检查后恢复源码版本，不上传、不安装；`--install-current` 不递增、不上传，只
安装当前源码版本。认证信息只从 `~/.pypirc` 或 Twine 标准环境变量读取。

正式发布后，脚本把精确版本安装到开发 Python 和 Runtime `.venv`，从源码目录外验证核心
导入和 CloakBrowser 二进制。上传成功后的本地安装失败不会回退已经发布的版本。
