Metadata-Version: 2.5
Name: dailo-sdk
Version: 0.1.4
Summary: 代劳 Android 与 Windows 应用自动化脚本 API
Project-URL: DevTools, https://pypi.org/project/dailo-devtools/
License-Expression: MIT
License-File: LICENSE
Keywords: android,automation,dailo,scripting,windows
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
Provides-Extra: windows
Requires-Dist: maafw==5.14.2; (sys_platform == 'win32') and extra == 'windows'
Requires-Dist: opencv-python<5,>=4.10; (sys_platform == 'win32') and extra == 'windows'
Requires-Dist: psutil<8,>=7.2; (sys_platform == 'win32') and extra == 'windows'
Requires-Dist: pyvda<1,>=0.6; (sys_platform == 'win32') and extra == 'windows'
Requires-Dist: pywin32>=312; (sys_platform == 'win32') and extra == 'windows'
Requires-Dist: pywinauto<1,>=0.6.9; (sys_platform == 'win32') and extra == 'windows'
Requires-Dist: windows-capture<3,>=2.0.1; (sys_platform == 'win32') and extra == 'windows'
Description-Content-Type: text/markdown

# Dailo SDK

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

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

## 安装

需要 Python 3.11 或更新版本。

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

发行名是 `dailo-sdk`，Python 导入名是 `dailo`。在代劳中选择 Android 设备或本机 Windows 应用后运行脚本，执行环境由代劳提供。在电脑上安装此包可获得类型提示；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()` 固定一份画面，方便在同一帧读取文字、匹配图片或取色。

## Windows 应用

在代劳的设备页添加应用路径，或选择正在运行的窗口，然后开启“用于任务”。文字、图像、颜色和坐标操作沿用同一组 API，坐标按客户区等比例归一化到 720p。

```python
from dailo import node, platform, target_app, text

print(platform(), target_app())
text("确定", exact=True).click()
node(class_name="Edit", editable=True).fill("搜索内容")
```

`platform()` 返回 `"android"` 或 `"windows"`。`target_app()` 返回脚本绑定的应用，Windows 下为可执行文件路径。Windows 节点使用 UI Automation；自绘界面可用文字和图像定位。

后台模式在独立虚拟桌面运行，最小化窗口会在那里恢复以采集新画面；不接受后台保护的应用会报告错误。前台模式要求目标应用已经位于前台。

## 脚本配置

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

## 许可

MIT。
