Metadata-Version: 2.5
Name: dailo-sdk
Version: 0.2.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
Description-Content-Type: text/markdown

# Dailo SDK

代劳的 Android 与 Windows 自动化脚本库，用 Python 定位文字、节点、图片和颜色，执行点击、输入与滑动。

## 使用

需要 Python 3.11+。安装 `dailo-sdk` 后，在代劳提供的执行环境运行：

```python
from dailo import *

app("com.android.settings").launch()
node(resource_id="com.example.app:id/search").fill("搜索内容")
text("确定", exact=True).click(until=text("首页"))
key_log("操作完成")
```

宿主也会向脚本入口注入这些函数，无需逐次写包名前缀。导入的业务模块使用普通 Python 导入。

## 查询与等待

优先使用node／text语义定位器，必要时使用img／color定位器，尽量省略可选参数。用简单流程和少量共享函数实现业务，避免直接处理整图、像素循环或手工遍历全部节点／文字；定位器结果不足时才调用显式OCR。不要为理论速度增加代码复杂度。设备无需预先横屏，应用自行旋转，脚本按实际业务状态推进。

`color`、`img`、`node`、`text`只读取宿主最新结果并登记更新需求；图像、节点、tiny全图文字独立更新。执行前由宿主预热，不要求三者同帧。没有新需求时不重复处理。脚本无需管理缓存、帧编号或快照。

```python
text("登录").click(until=text("首页"), timeout=20)
text("加载中").disappear(timeout=10)
print(text().text)
print(node())
screen = img()                 # color()同样返回当前图像
print(screen.pixel(100, 200))
screen.save("screen.png")
screen.crop("button.png", (10, 20, 110, 60))
```

字符串条件使用正则表达式。text默认匹配包含该文字的行，`exact=True`匹配整行；node条件匹配完整属性。定位器提供`is_visible()`、`all()`、`wait()`、`disappear()`、`settled()`及动作；唯一结果可直接读取`text`、`bounds`、`center`等属性。动作默认等待最多30秒，可用timeout指定预算。`wait_until(condition)`按结果变化唤醒，嵌套等待共用截止时间。

| 调用 | 默认行为 |
| --- | --- |
| `color("10,20,#FFFFFF|15,25,#000000")` | 原位比色 |
| `img("button.png")` | 全屏找图 |
| `node(text="登录")` | 查节点属性 |
| `text("登录")` | 查tiny全图识别结果 |
| `color()`／`img()` | 返回当前屏幕图像，像素内存只读 |
| `node()`／`text()` | 返回全部节点／文字结果 |

`location=(x,y)`为color指定首点、为img指定模板左上角；node和text筛选包含该点的候选。四坐标`(left,top,right,bottom)`要求完整包含整个目标，color／img在其中搜索。默认不必指定location或tolerance。

保存的图像用`Image.open("portrait.png")`读取；`image.img("patch.png", location=(20,20,150,170))`立即返回本图内的匹配结果元组。文件匹配复用Rust视觉，不读取设备画面；结果只含位置与分数，不执行动作或等待。

## 显式OCR

`ocr()`直接对当前图像执行一次推理，不使用text的全图结果。支持`model="tiny"`、`"small"`、`"medium"`，`line=True`表示单行识别；返回结果需由脚本处理。

```python
result = ocr(location=(100, 20, 300, 60), model="small", line=True)
print(result.text)
for line in result.lines:
    print(line.text, line.bounds)
```

## 模式与日志

```python
app("com.example.app").launch()
print("开发进度")
key_log("账号主页", image=True)
```

普通模式允许应用可见及移动光标；隐藏模式尽量减少干扰并静音目标。Android隐藏模式需要已授权root或shell；普通App权限支持普通模式。模式由宿主设置，脚本不读取或修改；结束后宿主恢复应用与声音。

print、标准logging及loguru按等级写入执行侧日志并显示在屏幕，print等同info；控制端请求时才读取。`key_log(message, image=True)`自动同步玩家关键日志，`True`附最新画面，`False`只记文字；也可传入`Image`，让日志附图与`image.ocr()`读取的画面一致。没有stage、log、observe、frame、ocr_line、pixel或color_at等重复入口。

## Windows与配置

Windows宿主、OCR和Python由代劳随附，无需自行安装视觉依赖。

```python
from dailo.windows import foreground_window, use, window, windows

target = window(hwnd=next(item.hwnd for item in windows() if item.title == "我的应用"))
use(target)
node(class_name="Edit", editable=True).fill("内容")
print(text().text)
```

window可按hwnd或executable选择应用；desktop()选择当前显示桌面，desktops()枚举虚拟桌面，desktop(id)选择桌面窗口集合。独立目标可调用node／text／img／color；公共函数使用use指定目标。state、restore、minimize、activate、set_rect、move_to为显式窗口操作。最小化应用通常没有可采集画面，隐藏模式会安排可渲染的窗口位置。

Windows的`press_key("ctrl+a")`可全选当前输入框，再用`type_text("新内容")`替换，或用`press_key("backspace")`清空。组合键修饰键支持`ctrl`、`shift`、`alt`。

Windows的`wait_until`由窗口／图像事件及各目标的查询结果发布唤醒，可直接等待`windows()`出现／消失或另一个目标的条件；没有界面事件的查询请求不会触发重复观察。

```python
from dataclasses import dataclass

@dataclass
class Settings:
    rounds: int = 5

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

`app(...).info()`、foreground_app、target_app、network_proxy、notifications及Windows窗口／桌面状态查询读取系统，不属于图像／节点／文字定位器。平台、配置和执行信息读取宿主状态。

## 许可

MIT。
