Metadata-Version: 2.5
Name: dailo-sdk
Version: 0.1.10
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: 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`，导入名为 `dailo`。在代劳中选择 Android 设备或本机 Windows 后运行脚本，执行环境由代劳提供。电脑安装此包可获得类型提示；Android 远程调试使用 [dailo-devtools](https://pypi.org/project/dailo-devtools/)。

## 快速开始

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

```python
from dailo import app, node, text

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

字符串定位条件使用正则表达式。文字定位默认匹配包含该文字的行，exact=True 匹配整行；动作默认等待最多 30 秒，timeout 可修改单次等待时限。

## 等待与画面读取

```python
from dailo import log, observe, text

text("登录").click(until=text("首页"), timeout=20)
text("加载中").disappear(timeout=10)
frame = observe()
print(frame.text())
log("当前画面", image=frame.screenshot)
```

observe() 固定一份画面，支持同帧文字识别、批量图片匹配、取色和裁剪。定位器提供 wait()、is_visible()、snapshot() 和 all()。

## Windows 桌面与应用

在设备页开启本机 Windows 的“用于任务”。默认观察当前桌面，也可设置默认应用；脚本可自行发现和操作多个窗口。

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

current = foreground_window()
print(current.executable if current else "没有前台窗口")
target = window(hwnd=next(item.hwnd for item in windows()
                          if item.title == "我的应用"))
use(target)
node(class_name="Edit", editable=True).fill("搜索内容")
text("确定", exact=True).click()
```

window(hwnd=...) 或 window(executable=...) 创建独立窗口目标。desktop() 观察当前显示桌面；desktops() 发现任务视图中的虚拟桌面；desktop(id) 观察该桌面的应用窗口集合。集合不包含系统壁纸，state().source 为 desktop_windows。

```python
from dailo.windows import desktop, window

editor = window(executable=r"C:\Apps\editor.exe")
browser = window(hwnd=browser_hwnd)
editor.node(class_name="Edit").fill("内容")
print(browser.observe().text())
print(desktop().state())
```

独立目标保留各自绑定，use(target) 只改变公共 dailo API 的默认目标。用户可以随时查看、移动和缩放应用，任务退出保留当前布局。窗口与桌面坐标均按各自画面等比例归一化到 720p；OCR、图像和颜色识别与 Android 共用 Rust 核心。

默认输入定向发送给目标窗口，不使用物理键鼠。原生 Win32 输入框、按钮、复选框和单选框使用不改变焦点的窗口消息；其他控件使用其 UIA 接口，具体应用仍需验证。需要真实桌面键鼠时，明确指定 input_method="desktop"；窗口目标要求应用已经在前台，桌面目标要求当前可见桌面。

应用目标的节点包含所属弹窗，即使弹窗位于主窗口外。需要读取弹窗完整画面或按弹窗坐标操作时，通过 windows() 找到弹窗并创建独立 window(hwnd=...) 目标。

默认通过 WGC 采集窗口，可明确指定 capture="printwindow" 使用只读客户区采集。最小化窗口通常没有可用画面，截图抛出 FrameUnavailable，节点可单独操作；指定桌面没有可采集窗口时也会报告不可用。读取不会隐式恢复窗口。脚本可明确调用 restore()、minimize()、activate() 或 move_to(desktop_id)。用 state() 和观察帧的 captured_at_us 检查目标状态与帧时间。

platform() 返回 android 或 windows。target_app() 返回默认应用的可执行文件路径，桌面目标返回空字符串。

## 悬浮任务状态

Android 和 Windows 执行端显示最新一行输出；`stage()` 同时更新控制端的任务阶段。

```python
from dailo import stage, status_position

status_position(12, 12)  # 左、下边距，单位 dp
stage("正在读取关卡")
print("已完成 3 / 10", flush=True)
```

Windows 浮层默认位于主屏工作区左下角，点击穿透、不抢焦点，不进入任务栏，也不进入自动化截图或节点。多个目标共用任务状态，结束时自动移除；长文字显示省略号。

## 脚本配置

```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(points) | 图片模板与颜色组合定位 |
| observe() / color_at(x, y) | 同帧观察与坐标取色 |
| wait_until(condition) | 等待自定义条件 |
| stage(message) / log(message) | 显示进度与保存日志 |

## 许可

MIT。
