Metadata-Version: 2.5
Name: dailo-sdk
Version: 0.1.1
Summary: 代劳 Android 自动化脚本 API
Project-URL: DevTools, https://pypi.org/project/dailo-devtools/
License-Expression: MIT
License-File: LICENSE
Keywords: android,automation,dailo,scripting
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: dacite<2,>=1.9
Requires-Dist: httpx<1,>=0.28
Requires-Dist: loguru<1,>=0.7
Description-Content-Type: text/markdown

# Dailo SDK

代劳的 Android 自动化脚本库。使用 Python 定位文字、控件和图片，执行点击、输入与滑动，并读取画面和脚本设置。

- 文字、控件、图片和颜色定位。
- 自动等待目标出现，支持等待操作后的页面变化。
- 同一帧的文字识别、图片匹配与截图日志。
- 类型注解和配置模型，支持编辑器补全与源码跳转。

## 安装

需要 Python 3.11 或更新版本。

```sh
python -m pip install dailo-sdk
```

发行名是 `dailo-sdk`，Python 导入名是 `dailo`。自动化脚本在安装了代劳 App 的 Android 设备上执行；在电脑上安装此包可获得类型提示，运行和调试脚本请使用 [dailo-devtools](https://pypi.org/project/dailo-devtools/)。

## 快速开始

将以下代码保存为 `main.py`，在代劳中运行：

```python
from dailo import app, text

app("com.android.settings").launch()
print(text())
```

文字定位可直接执行操作：

```python
from dailo import node, text

text("确定", exact=True).click()
node(resource_id="com.example.app:id/search").fill("搜索内容")
```

`text("确定")` 定位包含该文字的行，`exact=True` 匹配整行。定位器默认等待最多 30 秒；可用 `timeout` 修改单次等待时限。

## 等待与页面切换

```python
from dailo import text

text("登录").click(until=text("首页"), timeout=20)
text("加载中").disappear(timeout=10)
```

`click(until=...)` 等待目标出现后点击，再等待指定页面。定位器还提供 `wait()`、`is_visible()` 和 `all()`。

## 读取画面与保存日志

```python
from dailo import log, observe

frame = observe()
print(frame.text())
log("当前画面", image=frame.screenshot)
```

`observe()` 固定一份画面，方便在同一帧读取文字、匹配图片或取色。

## 脚本配置

```python
from dataclasses import dataclass
from dailo import get_config


@dataclass
class Settings:
    rounds: int = 5


settings = get_config(Settings)
print(settings.rounds)
```

配置来自代劳任务的设置界面；`dataclass` 提供默认值与类型提示。

## 常用 API

| API | 用途 |
| --- | --- |
| `app(package_name)` | 启动、停止和查询 Android 应用 |
| `text(pattern)` | 定位文字；不传参数时读取当前画面文字 |
| `node(**attributes)` | 按 Android 控件属性定位 |
| `image(path)` | 用本地图片模板定位 |
| `color_at(x, y)` | 读取指定坐标的 RGB |
| `observe()` | 读取同一帧的文字、图片和像素 |
| `wait_until(condition)` | 等待自定义条件成立 |
| `get_config(schema)` | 读取任务设置 |
| `stage(message)` / `log(message)` | 显示进度和保存日志 |

## 许可

MIT。
