dailo-sdk 0.1.0__tar.gz

dailo_sdk-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+node_modules/
+dist/
+build/
+.ruff_cache/
+__pycache__/
+*.egg-info/
+connection.json
+account.json
+downloads/

dailo_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dailo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dailo_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.5
+Name: dailo-sdk
+Version: 0.1.0
+Summary: 代劳 Android 自动化脚本 API
+License-Expression: MIT
+License-File: LICENSE
+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
+
+# 代劳 Python API
+
+`pip install dailo-sdk`，从 `dailo` 导入 API。编辑器可补全、查看文档和跳转源码；脚本在代劳设备中执行。
+
+`execution()` 返回当前执行 ID 和 `retry_of_execution_id`。持久化连续失败计数时，只在重跑来源与上次执行 ID 一致时继承计数；手动重启、停止后再启动或更换账号应重新计数。
+
+默认诊断记录达到 1 秒的 API 调用或状态驻留，包含近期操作和同帧图文；每次驻留去重，状态改变后重新记录，异常即时记录。单次 `wait_until` 的等待过程最多报告一次耗时，最终调用诊断仍保留。应用安装、权限、启动和停止也纳入耗时记录。
+
+统计等待诊断时区分过程与最终异常；两者的 `operation` 都可能是 `wait_until`，`diagnostic` 都是 `slow_api`。按 `reason` 和原执行异常识别终态，不以总条数大于1判节流失败。
+
+诊断补采画面不再次执行业务观察守卫，避免同一次异常重复触发延期等状态修改；正常观察和动作仍执行守卫。
+
+拖拽轨迹包含起止坐标、移动交付完成、申请松手及松手完成的耗时；移动交付后才开始画面稳定判断，稳定等待失败仍执行松手。系统交付不代表游戏已处理输入，动作结果仍按真实画面确认。
+
+守卫实际返回False并阻塞到预算耗尽时才抛出 `ObservationGuardTimeout`，其 `observation` 保留最后拒绝的同帧画面。守卫允许画面但调用预算已耗尽时抛普通`TimeoutError`；不能把普通定位超时记为网络失败或账号延期。
+
+定位器的一次调用共用守卫、动作、until结果等待与诊断预算；`wait_until`、画面变化等待与守卫嵌套时继承较早deadline，内部等待只取得剩余时间。复制执行上下文的deadline互相隔离；晚到条件成功仍按超时处理。等待诊断使用本次操作提供的画面及缓存文字；无本次画面时，仅在剩余预算内补采新帧，不额外OCR。采帧/编码截图的时间计入同一预算；耗尽后不再补采，未取得字段为空。日志以`collection=budgeted`和`frameSource=operation / diagnostic / unavailable`说明来源。Python回调和原生调用不会因此被强制中断，不能把这个预算当作硬截止时间。
+
+`text` 使用当前画面文字，`region` 对指定区域执行局部文字块识别。数字字段可用 `text(region=区域, line=True)` 读取指定区域的一行文字；同帧区域识别使用 `frame.matches(..., region=区域)`。
+
+列表翻页可用 `text(".+", region=名单区域).drag(x1, y1, x2, y2)`，等待名单稳定后松手，避免惯性跨页。`settle=False` 等待系统完成手势，不等待画面稳定；侧视相机或过渡按钮仍需确认可操作状态。`until=目标界面` 按需等待动作结果。
+
+`image(path, size=(宽, 高))` 按画面中的尺寸匹配原图，尺寸使用 720p 坐标；缩放和缓存由宿主处理。
+
+`color_at(x, y)` 读取 RGB，可判断按钮高亮或可操作区域，不需要图像处理库。
+
+```python
+from dailo import app, get_config, node, text
+from dataclasses import dataclass
+
+@dataclass
+class Settings:
+    rounds: int = 5
+
+settings = get_config(Settings)  # 显式读取 UI 配置，属性可补全
+
+app("com.example.game").launch()
+node(text="登录").click()  # 默认隐式等待 30 秒
+print(text())             # 读取画面文字，输出显示在设备左下角
+```
+
+`text("登录")` 定位包含文字的行，`exact=True` 匹配整行；`node`、`image`、`color` 定位控件、图片、颜色，PNG 透明区域不参与匹配。定位结果支持 `click()`、`wait()`、`disappear()`、`is_visible()`；`all()` 立即读取全部目标，需要滚动稳定时显式使用 `settled()`。`入口.click(until=目标界面)` 等目标可操作后点击一次，再等目标界面；`click(offset=(0, 30))` 点击目标中心下方 30 像素。`wait_until(lambda: 条件)` 支持多个合法出口，默认 30 秒。使用 `httpx` 下载文件，`install_app(path)` 安装或更新并保留应用数据。`app(package)` 查询版本、启动、停止及授予权限。`stage(message)` 同步关键阶段；普通 `print` / loguru 日志更新设备，结束时同步结果。`status_position(x, y)` 调整状态行位置（左、下边距，dp）。
+
+`settled()`（含 `drag` 的 `settle`）只确认匹配位置稳定，结果可能为空，不保证目标存在或可操作。需要目标存在时先调用 `目标.wait()`；缩放或页面过渡期间，应先等待同帧实际字段或图像出现，再执行手势，并用 `until` 或实际画面条件确认结果。
+
+`frame = observe()` 固定一份画面；`frame.text()`、`frame.matches(pattern)`、`frame.images({名称: image(...)})` 和 `frame.pixel(x, y)` 读取同一帧。图像批量匹配可指定 `grayscale=True`，返回边界及相关度。匹配结果保存文字、边界、中心与相关度；取证时帧ID和时间使用所属 `frame.observation_id`、`frame.captured_at_us`。`observe(text=False)` 延后 OCR；`observe(source=path, text=False)` 读取保存的图像。`frame.crop(path, region)` 保存同帧模板，`log(message, image=frame.screenshot)` 保存对应图文日志。
+
+数字字段可用 `frame.text(region=区域, line=True, allow_chars="0123456789")`：在原识别模型每步分数上仅选择允许字符与CTC空白，再按原CTC解码；不删除或替换解码后的文字。默认 `allow_chars=None` 不限制字符，空字符串无效。调用方仍须校验完整字段；数字约束不保证业务数值正确。
+
+`set_observation_guard(callback)` 在动作前检查同帧画面；返回 False 阻止动作并等画面变化。SDK 默认记录慢调用和超过一秒的状态驻留，包括阶段、实际文字、最近调用及同帧截图。`defer_until(带时区的datetime, reason=原因)` 结束本次任务并表达最早重跑时间。
+
+点击、定位器滑动/拖动、填充及按键输入另留一条 `input_action` 文字日志，记录单调时钟微秒的开始/返回时间、目标和 returned/raised；不额外采帧。返回只代表输入 API 完成，业务成效仍需实际后续画面确认。
+
+`notifications(after=提交前的time.time(), package_name=包名)` 读取本次提交后的瞬时 Toast / 通知，每项包含文字、应用及 Unix 时间；服务最多保留最近32条，重启清空。提示属于独立事件，不代表当前截图内容。
+
+`network_proxy()` 读取 Android `ConnectivityManager` 当前实际生效的代理，返回 host、port、exclusions、pac_url；无代理时返回 `None`。系统设置字段为空不代表内存中的代理已清除。

dailo_sdk-0.1.0/README.md

@@ -0,0 +1,56 @@
+# 代劳 Python API
+
+`pip install dailo-sdk`，从 `dailo` 导入 API。编辑器可补全、查看文档和跳转源码；脚本在代劳设备中执行。
+
+`execution()` 返回当前执行 ID 和 `retry_of_execution_id`。持久化连续失败计数时，只在重跑来源与上次执行 ID 一致时继承计数；手动重启、停止后再启动或更换账号应重新计数。
+
+默认诊断记录达到 1 秒的 API 调用或状态驻留，包含近期操作和同帧图文；每次驻留去重，状态改变后重新记录，异常即时记录。单次 `wait_until` 的等待过程最多报告一次耗时，最终调用诊断仍保留。应用安装、权限、启动和停止也纳入耗时记录。
+
+统计等待诊断时区分过程与最终异常；两者的 `operation` 都可能是 `wait_until`，`diagnostic` 都是 `slow_api`。按 `reason` 和原执行异常识别终态，不以总条数大于1判节流失败。
+
+诊断补采画面不再次执行业务观察守卫，避免同一次异常重复触发延期等状态修改；正常观察和动作仍执行守卫。
+
+拖拽轨迹包含起止坐标、移动交付完成、申请松手及松手完成的耗时；移动交付后才开始画面稳定判断，稳定等待失败仍执行松手。系统交付不代表游戏已处理输入，动作结果仍按真实画面确认。
+
+守卫实际返回False并阻塞到预算耗尽时才抛出 `ObservationGuardTimeout`，其 `observation` 保留最后拒绝的同帧画面。守卫允许画面但调用预算已耗尽时抛普通`TimeoutError`；不能把普通定位超时记为网络失败或账号延期。
+
+定位器的一次调用共用守卫、动作、until结果等待与诊断预算；`wait_until`、画面变化等待与守卫嵌套时继承较早deadline，内部等待只取得剩余时间。复制执行上下文的deadline互相隔离；晚到条件成功仍按超时处理。等待诊断使用本次操作提供的画面及缓存文字；无本次画面时，仅在剩余预算内补采新帧，不额外OCR。采帧/编码截图的时间计入同一预算；耗尽后不再补采，未取得字段为空。日志以`collection=budgeted`和`frameSource=operation / diagnostic / unavailable`说明来源。Python回调和原生调用不会因此被强制中断，不能把这个预算当作硬截止时间。
+
+`text` 使用当前画面文字，`region` 对指定区域执行局部文字块识别。数字字段可用 `text(region=区域, line=True)` 读取指定区域的一行文字；同帧区域识别使用 `frame.matches(..., region=区域)`。
+
+列表翻页可用 `text(".+", region=名单区域).drag(x1, y1, x2, y2)`，等待名单稳定后松手，避免惯性跨页。`settle=False` 等待系统完成手势，不等待画面稳定；侧视相机或过渡按钮仍需确认可操作状态。`until=目标界面` 按需等待动作结果。
+
+`image(path, size=(宽, 高))` 按画面中的尺寸匹配原图，尺寸使用 720p 坐标；缩放和缓存由宿主处理。
+
+`color_at(x, y)` 读取 RGB，可判断按钮高亮或可操作区域，不需要图像处理库。
+
+```python
+from dailo import app, get_config, node, text
+from dataclasses import dataclass
+
+@dataclass
+class Settings:
+    rounds: int = 5
+
+settings = get_config(Settings)  # 显式读取 UI 配置，属性可补全
+
+app("com.example.game").launch()
+node(text="登录").click()  # 默认隐式等待 30 秒
+print(text())             # 读取画面文字，输出显示在设备左下角
+```
+
+`text("登录")` 定位包含文字的行，`exact=True` 匹配整行；`node`、`image`、`color` 定位控件、图片、颜色，PNG 透明区域不参与匹配。定位结果支持 `click()`、`wait()`、`disappear()`、`is_visible()`；`all()` 立即读取全部目标，需要滚动稳定时显式使用 `settled()`。`入口.click(until=目标界面)` 等目标可操作后点击一次，再等目标界面；`click(offset=(0, 30))` 点击目标中心下方 30 像素。`wait_until(lambda: 条件)` 支持多个合法出口，默认 30 秒。使用 `httpx` 下载文件，`install_app(path)` 安装或更新并保留应用数据。`app(package)` 查询版本、启动、停止及授予权限。`stage(message)` 同步关键阶段；普通 `print` / loguru 日志更新设备，结束时同步结果。`status_position(x, y)` 调整状态行位置（左、下边距，dp）。
+
+`settled()`（含 `drag` 的 `settle`）只确认匹配位置稳定，结果可能为空，不保证目标存在或可操作。需要目标存在时先调用 `目标.wait()`；缩放或页面过渡期间，应先等待同帧实际字段或图像出现，再执行手势，并用 `until` 或实际画面条件确认结果。
+
+`frame = observe()` 固定一份画面；`frame.text()`、`frame.matches(pattern)`、`frame.images({名称: image(...)})` 和 `frame.pixel(x, y)` 读取同一帧。图像批量匹配可指定 `grayscale=True`，返回边界及相关度。匹配结果保存文字、边界、中心与相关度；取证时帧ID和时间使用所属 `frame.observation_id`、`frame.captured_at_us`。`observe(text=False)` 延后 OCR；`observe(source=path, text=False)` 读取保存的图像。`frame.crop(path, region)` 保存同帧模板，`log(message, image=frame.screenshot)` 保存对应图文日志。
+
+数字字段可用 `frame.text(region=区域, line=True, allow_chars="0123456789")`：在原识别模型每步分数上仅选择允许字符与CTC空白，再按原CTC解码；不删除或替换解码后的文字。默认 `allow_chars=None` 不限制字符，空字符串无效。调用方仍须校验完整字段；数字约束不保证业务数值正确。
+
+`set_observation_guard(callback)` 在动作前检查同帧画面；返回 False 阻止动作并等画面变化。SDK 默认记录慢调用和超过一秒的状态驻留，包括阶段、实际文字、最近调用及同帧截图。`defer_until(带时区的datetime, reason=原因)` 结束本次任务并表达最早重跑时间。
+
+点击、定位器滑动/拖动、填充及按键输入另留一条 `input_action` 文字日志，记录单调时钟微秒的开始/返回时间、目标和 returned/raised；不额外采帧。返回只代表输入 API 完成，业务成效仍需实际后续画面确认。
+
+`notifications(after=提交前的time.time(), package_name=包名)` 读取本次提交后的瞬时 Toast / 通知，每项包含文字、应用及 Unix 时间；服务最多保留最近32条，重启清空。提示属于独立事件，不代表当前截图内容。
+
+`network_proxy()` 读取 Android `ConnectivityManager` 当前实际生效的代理，返回 host、port、exclusions、pac_url；无代理时返回 `None`。系统设置字段为空不代表内存中的代理已清除。

dailo_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,15 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "dailo-sdk"
+version = "0.1.0"
+description = "代劳 Android 自动化脚本 API"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+dependencies = ["httpx>=0.28,<1", "loguru>=0.7,<1", "dacite>=1.9,<2"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dailo"]

dailo_sdk-0.1.0/src/dailo/__init__.py

@@ -0,0 +1,516 @@
+"""Android 自动化：显式导入、隐式等待和设备本地进度。"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import wraps
+import json
+from pathlib import Path
+from time import monotonic
+from datetime import datetime, timezone
+from collections.abc import Callable
+from typing import Any, Generic, Literal, NoReturn, Protocol, TypeVar, cast, overload
+
+from dacite import from_dict
+
+from ._runtime import host, config, state, execution as _execution
+from ._diagnostics import call as _call, record as _record
+from ._observation import Observation, ObservedMatch as ObservedMatch, observe
+
+Region = list[int] | tuple[int, int, int, int]
+Key = Literal["back", "home", "recents", "notifications", "quickSettings", "volumeUp", "volumeDown", "mute", "rotate", "screenOn", "screenOff", "powerMenu"]
+_default_timeout = 30.0
+_default_tolerance = 0.05
+
+
+WaitCall = TypeVar("WaitCall", bound=Callable[..., Any])
+
+
+def _wait_budget(action: WaitCall) -> WaitCall:
+    """动作、守卫、结果等待和诊断共用一次调用的预算。"""
+    @wraps(action)
+    def perform(*args, timeout=None, **kwargs):
+        from ._runtime import deadline_scope
+        with deadline_scope(monotonic() + (_default_timeout if timeout is None else timeout)):
+            _remaining_timeout(timeout)
+            return action(*args, timeout=timeout, **kwargs)
+    return cast(WaitCall, perform)
+
+
+def _remaining_timeout(timeout: float | None) -> float | None:
+    deadline = state().deadline
+    if deadline is None:
+        return timeout
+    remaining = deadline - monotonic()
+    if remaining <= 0:
+        raise TimeoutError("等待界面条件预算已耗尽")
+    return min(remaining, _default_timeout if timeout is None else timeout)
+
+
+class Match(Protocol):
+    """匹配目标的文字和 720p 坐标。"""
+    @property
+    def text(self) -> str | None: ...
+    bounds: tuple[int, int, int, int]
+    center: tuple[int, int]
+    resource_id: str | None
+
+
+class TextMatch(Match, Protocol):
+    """文字定位结果始终含有字符串。"""
+    @property
+    def text(self) -> str: ...
+
+
+class Screenshot(Protocol):
+    """当前截图的尺寸和原始 PNG。"""
+    width: int
+    height: int
+    data_base64: str
+    content_type: str
+    sha256: str
+    frame_id: int
+
+
+MatchType = TypeVar("MatchType", bound=Match)
+
+
+class Locator(Generic[MatchType]):
+    """定位条件。动作自动等待可操作状态，默认 30 秒。"""
+    def __init__(self, native: Any, description: Any = "定位目标"):
+        self._native = native
+        self._description = description
+        self._image_query = None
+
+    @_wait_budget
+    def click(self, *, until: Locator | Callable[[], object] | None = None,
+              offset: tuple[int, int] | None = None,
+              timeout: float | None = None) -> None:
+        """目标唯一且可操作后点击一次；offset 相对中心，until 等待目标界面。"""
+        _guard(timeout)
+        _call("locator.click", {"locator": self._description, "offset": offset},
+              lambda: self._native.click(offset=offset, timeout=_remaining_timeout(timeout)))
+        if until is not None:
+            wait_until(until.is_visible if isinstance(until, Locator) else until, timeout=timeout)
+
+    @_wait_budget
+    def swipe(self, x1: float, y1: float, x2: float, y2: float, *,
+              duration: float = 0.3, timeout: float | None = None) -> None:
+        """等待目标后沿 720p 坐标滑动；duration 是手势时长。"""
+        _guard(timeout)
+        _call("locator.swipe", {"locator": self._description, "from": [x1, y1], "to": [x2, y2],
+                               "duration": duration},
+              lambda: self._native.swipe(x1, y1, x2, y2, duration=duration, timeout=_remaining_timeout(timeout)))
+
+    @_wait_budget
+    def drag(self, x1: float, y1: float, x2: float, y2: float, *,
+             settle: Locator | Literal[False] | None = None,
+             until: Locator | Callable[[], object] | None = None,
+             timeout: float | None = None) -> tuple[Match, ...]:
+        """拖动并返回稳定后的目标；settle=False 仅完成手势，不等画面稳定。"""
+        self.wait(timeout=timeout)
+        driver = host()
+        target = {"locator": self._description, "from": [x1, y1], "to": [x2, y2],
+                  "settle": False if settle is False else (settle or self)._description}
+        def perform():
+            started = monotonic()
+            _remaining_timeout(timeout)
+            try:
+                driver._drag_start(x1, y1, x2, y2)
+                target["moveDeliveredMs"] = round((monotonic() - started) * 1000, 1)
+                matches = () if settle is False else (settle or self).settled(timeout=timeout)
+            finally:
+                target["releaseRequestedMs"] = round((monotonic() - started) * 1000, 1)
+                driver._drag_end(x2, y2)
+                target["releasedMs"] = round((monotonic() - started) * 1000, 1)
+            if until is not None:
+                wait_until(until.is_visible if isinstance(until, Locator) else until, timeout=timeout)
+            return matches
+        return _call("locator.drag", target, perform)
+
+    @_wait_budget
+    def wait(self, *, timeout: float | None = None) -> None:
+        """等待目标出现。"""
+        _guard(timeout)
+        _call("locator.wait", self._description, lambda: self._native.wait(timeout=_remaining_timeout(timeout)))
+
+    @_wait_budget
+    def disappear(self, *, timeout: float | None = None) -> None:
+        """等待目标消失；不需要记忆字符串状态名。"""
+        _guard(timeout)
+        _call("locator.disappear", self._description, lambda: self._native.wait("hidden", timeout=_remaining_timeout(timeout)))
+
+    def is_visible(self) -> bool:
+        """立即判断是否存在匹配目标，不等待。"""
+        _guard()
+        return _call("locator.visible", self._description, self._native.is_visible)
+
+    @_wait_budget
+    def snapshot(self, *, timeout: float | None = None) -> MatchType:
+        """等待并读取匹配目标的文字、边界及中心坐标。"""
+        _guard(timeout)
+        return _call("locator.snapshot", self._description, lambda: self._native.snapshot(timeout=_remaining_timeout(timeout)))
+
+    def all(self) -> tuple[MatchType, ...]:
+        """立即读取当前全部目标；空列表返回空元组。"""
+        _guard()
+        return _call("locator.all", self._description, self._native.all)
+
+    @_wait_budget
+    def settled(self, *, timeout: float | None = None) -> tuple[MatchType, ...]:
+        """返回位置稳定的匹配，可能为空；需要目标存在时先wait()或等待同帧条件。"""
+        _guard(timeout)
+        return _call("locator.settled", self._description, lambda: self._native.settled(timeout=_remaining_timeout(timeout)))
+
+
+class NodeLocator(Locator[Match]):
+    """Android 无障碍控件定位。"""
+    @_wait_budget
+    def fill(self, value: str, *, timeout: float | None = None) -> None:
+        """等待可编辑控件并替换文字。"""
+        _guard(timeout)
+        _call("node.fill", self._description, lambda: self._native.fill(value, timeout=_remaining_timeout(timeout)))
+
+
+def node(*, text: str | None = None, resource_id: str | None = None,
+         description: str | None = None, class_name: str | None = None,
+         package_name: str | None = None, hint: str | None = None,
+         clickable: bool | None = None, editable: bool | None = None,
+         enabled: bool | None = None, checkable: bool | None = None,
+         checked: bool | None = None) -> NodeLocator:
+    """按 Android 控件属性定位；字符串为完整匹配的正则表达式。"""
+    params = locals()
+    return NodeLocator(host().node(**params), {"node": params})
+
+
+@overload
+def text(pattern: None = None, *, region: Region | None = None, exact: bool = False,
+         line: bool = False) -> str: ...
+@overload
+def text(pattern: str, *, region: Region | None = None, exact: bool = False,
+         line: bool = False) -> Locator[TextMatch]: ...
+
+
+def text(pattern: str | None = None, *, region: Region | None = None, exact: bool = False,
+         line: bool = False) -> str | Locator[TextMatch]:
+    """无参数读取文字，有参数定位文字。region 指定局部识别区域，exact 匹配整行。
+
+    line=True 将给定区域作为单行读取，适合计数、余额等数字字段。
+    """
+    if pattern is None:
+        _guard()
+        return _call("text", {"region": region, "line": line}, lambda: host().text(".+", region=region, line=line).read_text())
+    return Locator(host().text(pattern, region=region, exact=exact, line=line), {"text": pattern, "region": region})
+
+
+def image(path: str | Path, *, region: Region | None = None,
+          tolerance: float | None = None, size: tuple[int, int] | None = None) -> Locator[Match]:
+    """定位图片；size 指定模板在 720p 画面中的宽、高，PNG 透明区域不参与匹配。"""
+    resolved = str(Path(path).resolve())
+    locator = Locator(host().image(resolved, region=region, tolerance=tolerance, size=size), {"image": resolved, "region": region})
+    locator._image_query = {"path": resolved, "region": region, "tolerance": _default_tolerance if tolerance is None else tolerance, "size": size}
+    return locator
+
+
+def color(points: str, *, region: Region | None = None,
+          tolerance: float | None = None) -> Locator[Match]:
+    """定位颜色点组合，坐标使用设备等比例 720p 画面。"""
+    return Locator(host().color(points, region=region, tolerance=tolerance), {"color": points, "region": region})
+
+
+def color_at(x: int, y: int) -> tuple[int, int, int]:
+    """读取 720p 坐标处的 RGB（0–255），可判断高亮、灰色和可操作区域。"""
+    result = host().pixel(x, y)
+    if not result.found:
+        raise ValueError("取色坐标不在当前画面内")
+    return result.color.r, result.color.g, result.color.b
+
+
+def screenshot() -> Screenshot:
+    """取得当前等比例 720p 画面（width、height、data_base64）。"""
+    result = host().screenshot()
+    if not result.ok:
+        raise RuntimeError(result.error or "截图失败")
+    return cast(Screenshot, result)
+
+
+ConfigType = TypeVar("ConfigType")
+
+
+@overload
+def get_config(schema: type[ConfigType]) -> ConfigType: ...
+@overload
+def get_config(schema: None = None) -> dict[str, Any]: ...
+
+
+def get_config(schema: type[ConfigType] | None = None) -> ConfigType | dict[str, Any]:
+    """读取 UI 设置；传入 dataclass 类型即可获得属性补全、默认值和嵌套配置。
+
+    例如：settings = get_config(Settings)。配置不会注入脚本全局变量。
+    """
+    values = config()
+    return from_dict(schema, values) if schema is not None else values.copy()
+
+
+@dataclass(frozen=True)
+class AppInfo:
+    """已安装应用的版本；未安装时 installed=False。"""
+    package_name: str
+    installed: bool
+    version_name: str = ""
+    version_code: int = 0
+
+
+def _app_call(operation: str, **params: Any) -> dict[str, Any]:
+    def invoke():
+        result = json.loads(host()._app_operation(json.dumps({"operation": operation, **params})))
+        if not result.get("ok"):
+            raise RuntimeError(result.get("error", "应用操作失败"))
+        return result
+    return _call(f"app.{operation}", params, invoke)
+
+
+@dataclass(frozen=True)
+class NetworkProxy:
+    """Android 当前网络实际生效的 HTTP / PAC 代理。"""
+    host: str
+    port: int
+    exclusions: tuple[str, ...]
+    pac_url: str
+
+
+def network_proxy() -> NetworkProxy | None:
+    """读取 ConnectivityManager 的实际代理；无代理时返回 None。"""
+    value = _app_call("network_proxy")["proxy"]
+    return None if value is None else NetworkProxy(value["host"], value["port"],
+        tuple(value["exclusions"]), value["pacUrl"])
+
+
+@dataclass(frozen=True)
+class Notification:
+    """Android 无障碍收到的 Toast / 通知；timestamp 为 Unix 秒。"""
+    package_name: str
+    text: str
+    timestamp: float
+
+
+def notifications(*, after: float = 0.0, package_name: str | None = None) -> tuple[Notification, ...]:
+    """读取服务本次启动以来最近 32 条提示；after 排除该时间及更早事件。"""
+    result = _app_call("notifications", after=after, package=package_name or "")
+    return tuple(Notification(event["packageName"], event["text"], event["timestamp"])
+                 for event in result["notifications"])
+
+
+class App:
+    """宿主管理应用；安装、停止和权限自动选择 root 或无障碍方式。"""
+    def __init__(self, package_name: str):
+        self.package_name = package_name
+
+    def info(self) -> AppInfo:
+        """查询安装状态、versionName 和 versionCode。"""
+        value = _app_call("info", package=self.package_name)
+        return AppInfo(self.package_name, value["installed"], value.get("versionName", ""), value.get("versionCode", 0))
+
+    def launch(self) -> None:
+        """启动应用。"""
+        result = _call("app.launch", self.package_name, lambda: host().launch_app(self.package_name))
+        if not result.ok:
+            raise RuntimeError(result.error or "应用启动失败")
+
+    def stop(self) -> None:
+        """停止应用，保留数据；无 root 时在系统设置中强行停止。"""
+        _app_call("stop", package=self.package_name)
+
+    def grant_permissions(self) -> None:
+        """授予应用声明的运行时权限，宿主处理 Android 系统界面。"""
+        _app_call("permissions", package=self.package_name)
+
+
+def app(package_name: str) -> App:
+    """管理指定 Android 包名的应用。"""
+    return App(package_name)
+
+
+def install_app(path: str | Path) -> AppInfo:
+    """安装或更新本地 APK，保留应用数据并等待 Android 安装完成。"""
+    result = _app_call("install", path=str(Path(path).resolve()))
+    return app(result["package"]).info()
+
+
+def foreground_app() -> str:
+    """返回当前前台应用包名，区别于安装信息 app(package).info()。"""
+    result = host().current_app()
+    if not result.ok:
+        raise RuntimeError(result.error or "前台应用读取失败")
+    return result.package_name
+
+
+def stage(message: str) -> None:
+    """显示并同步关键任务阶段；高频进度使用 print。"""
+    state().expected = message
+    print(message, flush=True)
+    host()._progress(message, None, "{}")
+
+
+def status_position(x: int = 12, y: int = 12) -> None:
+    """设置状态行的左、下边距（dp）；默认左下角。"""
+    host()._status_position(x, y)
+
+
+class DailoScriptFail(Exception):
+    """携带宿主可识别的任务失败信息。"""
+
+
+class DailoTaskDeferred(Exception):
+    """任务到指定时间才允许重新执行；宿主持久化此约束。"""
+
+
+@dataclass(frozen=True)
+class ExecutionInfo:
+    execution_id: str | None
+    retry_of_execution_id: str | None
+
+
+def execution() -> ExecutionInfo:
+    """当前执行与重跑来源，用于区分连续延期链和重新开始的任务。"""
+    return ExecutionInfo(**_execution())
+
+
+def defer_until(when: datetime, *, reason: str = "") -> NoReturn:
+    """结束本次执行并设置任务最早重跑时间，when 必须包含时区。"""
+    if when.tzinfo is None:
+        raise ValueError("defer_until 时间必须包含时区")
+    raise DailoTaskDeferred(json.dumps({"message": reason, "notBeforeAtMs": int(when.astimezone(timezone.utc).timestamp() * 1000)}, ensure_ascii=False))
+
+
+def log(message: str, *, image: Screenshot | None = None) -> None:
+    """完整保存文字与提供的同帧PNG；单条文字为1—65536个UTF-8字节。"""
+    payload = None if image is None else json.dumps({"contentType": image.content_type,
+        "dataBase64": image.data_base64, "sha256": image.sha256, "width": image.width, "height": image.height})
+    host()._log(message, payload)
+
+
+def set_observation_guard(callback: Callable[[Observation], bool | None] | None) -> None:
+    """注册动作前的全局观察；返回 False 阻止动作，继续等待画面变化。"""
+    state().guard = callback
+
+
+class ObservationGuardTimeout(TimeoutError):
+    """全局观察阻塞超时；observation 是阻塞结束前的最后同帧证据。"""
+    def __init__(self, observation: Observation):
+        super().__init__("全局观察阻止动作，等待界面恢复超时")
+        self.observation = observation
+
+
+def _guard(timeout: float | None = None) -> Observation | None:
+    execution = state()
+    if execution.guard is None or execution.guarding:
+        return
+    execution.guarding = True
+    deadline = monotonic() + (_default_timeout if timeout is None else timeout)
+    try:
+        from ._runtime import deadline_scope
+        with deadline_scope(deadline) as deadline:
+            blocked = None
+            while True:
+                if monotonic() >= deadline:
+                    if blocked is not None:
+                        raise ObservationGuardTimeout(blocked)
+                    raise TimeoutError("等待界面条件预算已耗尽")
+                frame = observe(text=False)
+                permitted = execution.guard(frame) is not False
+                remaining = deadline - monotonic()
+                if permitted:
+                    if remaining <= 0:
+                        raise TimeoutError("观察守卫允许当前画面，但等待预算已耗尽")
+                    return frame
+                blocked = frame
+                if remaining <= 0:
+                    raise ObservationGuardTimeout(frame)
+                host().wait_for_frame(min(remaining, 1))
+    finally:
+        execution.guarding = False
+
+
+def fail(message: str, *, code: str = "script_failed",
+         failure_kind: Literal["product", "user"] = "product") -> NoReturn:
+    """以明确原因结束任务；user 表示用户配置或账号需要处理。"""
+    raise DailoScriptFail(json.dumps({"message": message, "code": code, "failureKind": failure_kind}, ensure_ascii=False))
+
+
+def wait_for_frame() -> None:
+    """隐式等待画面变化，避免状态机忙循环。"""
+    from ._runtime import deadline_scope
+    with deadline_scope(monotonic() + 30):
+        def wait():
+            if not host().wait_for_frame(_remaining_timeout(30)):
+                raise TimeoutError("等待画面变化超时")
+        _call("wait_for_frame", "画面变化", wait)
+
+
+WaitResult = TypeVar("WaitResult")
+
+
+def wait_until(condition: Callable[[], WaitResult | None], *, timeout: float | None = None) -> WaitResult:
+    """隐式等待条件返回真值并返回该值；用于界面有多个合法出口的状态机。"""
+    started = monotonic()
+    deadline = started + (_default_timeout if timeout is None else timeout)
+    def wait():
+        slow_reported = False
+        while True:
+            result = condition()
+            if monotonic() >= deadline:
+                raise TimeoutError("等待界面条件超时")
+            if result:
+                return result
+            if not slow_reported and monotonic() - started >= 1:
+                _record("wait_until", "界面条件", started)
+                slow_reported = True
+            remaining = deadline - monotonic()
+            if remaining <= 0:
+                raise TimeoutError("等待界面条件超时")
+            host().wait_for_frame(min(remaining, 1))
+    from ._runtime import deadline_scope
+    with deadline_scope(deadline) as deadline:
+        return _call("wait_until", "界面条件", wait)
+
+
+@_wait_budget
+def click(x: float, y: float, *, until: Locator | Callable[[], object] | None = None,
+          timeout: float | None = None) -> None:
+    """点击 720p 坐标一次；可用 until 等待目标界面，优先使用定位器。"""
+    _guard(timeout)
+    _call("click", [x, y], lambda: host().click(x, y))
+    if until is not None:
+        wait_until(until.is_visible if isinstance(until, Locator) else until, timeout=timeout)
+
+
+def press_key(key: Key | int) -> None:
+    """发送系统动作（如 'back'、'home'）或 Android 整数键码。"""
+    _guard()
+    _call("press_key", key, lambda: host().press_key(key))
+
+
+def swipe(x1: float, y1: float, x2: float, y2: float, *, duration: float = 0.3) -> None:
+    """沿 720p 坐标滑动；优先使用定位器的 swipe。"""
+    _guard()
+    _call("swipe", [x1, y1, x2, y2], lambda: host().touch_swipe(x1, y1, x2, y2, duration))
+
+
+def type_text(value: str) -> None:
+    """向当前输入控件输入文字；优先使用 node(...).fill。"""
+    _guard()
+    _call("type_text", "当前控件", lambda: host().type_text(value))
+
+
+def set_default_tolerance(value: float) -> None:
+    """调整图片和颜色定位的默认容差。"""
+    host().set_default_tolerance(value)
+    global _default_tolerance
+    _default_tolerance = value
+
+
+def set_default_timeout(seconds: float = 30) -> None:
+    """调整定位动作的默认隐式等待上限。"""
+    host().set_default_timeout(seconds)
+    global _default_timeout
+    _default_timeout = seconds

dailo_sdk-0.1.0/src/dailo/_diagnostics.py

@@ -0,0 +1,96 @@
+"""诊断区分本次操作帧与预算内补采帧，不复用之前操作的画面。"""
+from collections import deque
+from time import monotonic
+
+from ._runtime import state
+
+_INPUT_OPERATIONS = frozenset({
+    "click", "locator.click", "swipe", "locator.swipe", "locator.drag",
+    "node.fill", "press_key", "type_text",
+})
+
+
+class Trace:
+    def __init__(self):
+        self.recent = deque(maxlen=24)
+        self.actual = None
+        self.since = monotonic()
+        self.reported = False
+        self.reporting = False
+
+    def record(self, operation, target, elapsed, actual=None, frame=None, error=None, *, started=None):
+        if self.reporting:
+            return
+        now = monotonic()
+        self.recent.append({"operation": operation, "target": target, "ms": round(elapsed * 1000, 1)})
+        if actual is not None and actual != self.actual:
+            self.actual, self.since, self.reported = actual, now, False
+        dwell = now - self.since
+        diagnostic = error is not None or not (self.reported or (elapsed < 1 and dwell < 1))
+        input_action = operation in _INPUT_OPERATIONS
+        if not input_action and not diagnostic:
+            return
+        self.reporting = True
+        try:
+            from . import log
+            import json
+            if input_action:
+                log(json.dumps({"diagnostic": "input_action", "operation": operation,
+                    "target": target, "startedAtUs": round((now - elapsed if started is None else started) * 1000000),
+                    "finishedAtUs": round(now * 1000000), "elapsedMs": round(elapsed * 1000, 1),
+                    "outcome": "raised" if error is not None else "returned", "error": error}, ensure_ascii=False))
+            if not diagnostic:
+                return
+            self.reported = True
+            from ._observation import Observation
+            from ._runtime import host
+            # 诊断取图不重跑业务守卫，避免同一次异常再次触发延期等状态修改。
+            budgeted = state().deadline is not None
+            if budgeted:
+                # 只复用本次操作帧；无帧时在剩余预算内补采，不额外OCR。
+                captured = frame
+                if captured is None and monotonic() < state().deadline:
+                    captured = Observation(host()._observe(False, None), None)
+                lines = getattr(captured, '_lines', None)
+                current = None if lines is None else "\n".join(item['text'] for item in lines)
+                screenshot = getattr(captured, '_screenshot', None)
+                if captured is not None and screenshot is None and monotonic() < state().deadline:
+                    screenshot = captured.screenshot
+            else:
+                captured = frame if frame is not None else Observation(host()._observe(False, None), None)
+                # 未提供本次观察时，读取新观察的文字，不拼接旧文字与新图。
+                current = captured.text()
+                screenshot = captured.screenshot
+            log(json.dumps({"diagnostic": "slow_api" if elapsed >= 1 else "state_residency",
+                "expected": state().expected, "actual": current,
+                "observationId": captured.observation_id if captured is not None else None,
+                "capturedAtUs": captured.captured_at_us if captured is not None else None,
+                "sourcePath": str(captured.source_path) if captured is not None and captured.source_path else None,
+                "collection": "budgeted" if budgeted else "captured",
+                "frameSource": "operation" if frame is not None else "diagnostic" if captured is not None else "unavailable",
+                "remainingMs": max(0, round((state().deadline - monotonic()) * 1000, 1)) if budgeted else None,
+                "operation": operation, "target": target, "elapsedMs": round(elapsed * 1000, 1),
+                "residencyMs": round(dwell * 1000, 1), "reason": error or ("观察耗时" if elapsed >= 1 else "等待状态进展"),
+                "recent": list(self.recent)}, ensure_ascii=False), image=screenshot)
+        except Exception as diagnostic_error:
+            print(f"诊断画面读取失败：{diagnostic_error}", flush=True)
+        finally:
+            self.reporting = False
+
+
+def record(operation, target, started, actual=None, frame=None, error=None):
+    execution = state()
+    if execution.trace is None:
+        execution.trace = Trace()
+    execution.trace.record(operation, target, monotonic() - started, actual, frame, error, started=started)
+
+
+def call(operation, target, action, *, actual=None):
+    started = monotonic()
+    try:
+        result = action()
+    except Exception as error:
+        record(operation, target, started, error=str(error))
+        raise
+    record(operation, target, started, actual(result) if actual else None)
+    return result

dailo_sdk-0.1.0/src/dailo/_observation.py

@@ -0,0 +1,104 @@
+"""文字、图像与像素共享一份不可变画面。"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+from pathlib import Path
+import re
+from time import monotonic
+
+from ._runtime import host
+from ._diagnostics import record
+
+
+@dataclass(frozen=True)
+class ObservedMatch:
+    bounds: tuple[int, int, int, int]
+    text: str | None = None
+    score: float = 1.0
+    resource_id: str | None = None
+
+    @property
+    def center(self) -> tuple[int, int]:
+        left, top, right, bottom = self.bounds
+        return (left + right) // 2, (top + bottom) // 2
+
+
+class Observation:
+    """同帧读取；source_path 非空表示保存的图像，不代表当前设备画面。"""
+    def __init__(self, native, source_path: Path | None):
+        self._native = native
+        self.source_path = source_path
+        self._screenshot = None
+        self._lines = None
+
+    @property
+    def observation_id(self) -> int:
+        return self._native.frame_id
+
+    @property
+    def captured_at_us(self) -> int:
+        return self._native.captured_at_us
+
+    def _read(self, region=None, line=False, allow_chars=None):
+        started = monotonic()
+        value = json.loads(self._native.text_json(region, line, allow_chars))
+        if not value.get("ok"):
+            raise RuntimeError(value.get("error", "同帧文字读取失败"))
+        lines = value.get("lines", [])
+        if not line and region is None and allow_chars is None:
+            self._lines = lines
+        actual = "\n".join(item["text"] for item in lines)
+        record("observation.text", {"region": region, "line": line, "allow_chars": allow_chars}, started,
+               actual=actual if region is None and allow_chars is None else None, frame=self)
+        return value
+
+    def text(self, *, region=None, line=False, allow_chars: str | None = None) -> str:
+        """allow_chars 在原CTC分数上约束字符候选；默认不限制字符。"""
+        value = self._read(region, line, allow_chars)
+        return value.get("text", "") if line else "\n".join(item["text"] for item in value.get("lines", []))
+
+    def matches(self, pattern: str, *, region=None, exact=False) -> tuple[ObservedMatch, ...]:
+        expression = re.compile(pattern)
+        found = []
+        for item in self._read(region).get("lines", []):
+            if (expression.fullmatch if exact else expression.search)(item["text"]):
+                area = item["rect"]
+                found.append(ObservedMatch(tuple(area[key] for key in ("left", "top", "right", "bottom")), item["text"]))
+        return tuple(found)
+
+    def images(self, queries: dict, *, grayscale=False) -> dict[str, tuple[ObservedMatch, ...]]:
+        started = monotonic()
+        request = {name: locator._image_query for name, locator in queries.items()}
+        values = json.loads(self._native.images_json(json.dumps(request), grayscale))
+        result = {name: tuple(ObservedMatch(tuple(item["bounds"]), score=item["score"]) for item in matches)
+                  for name, matches in values.items()}
+        record("observation.images", list(queries), started, frame=self)
+        return result
+
+    def pixel(self, x: int, y: int) -> tuple[int, int, int]:
+        return tuple(self._native.pixel(x, y))
+
+    def crop(self, path: str | Path, region) -> Path:
+        target = Path(path).resolve()
+        self._native.crop(str(target), list(region))
+        return target
+
+    @property
+    def screenshot(self):
+        if self._screenshot is None:
+            self._screenshot = self._native.snapshot()
+            if not self._screenshot.ok:
+                raise RuntimeError(self._screenshot.error or "同帧截图失败")
+        return self._screenshot
+
+
+def observe(*, text=True, source: str | Path | None = None) -> Observation:
+    started = monotonic()
+    path = Path(source).resolve() if source is not None else None
+    from . import _guard
+    guarded = _guard() if path is None else None
+    value = guarded or Observation(host()._observe(text, str(path) if path else None), path)
+    actual = value.text() if text else None
+    record("observe", {"text": text, "source": str(path) if path else None}, started, actual=actual, frame=value)
+    return value

dailo_sdk-0.1.0/src/dailo/_output.py

@@ -0,0 +1,30 @@
+"""Capture print/loguru output without streaming each line to the controller."""
+from ._runtime import host
+
+
+class Output:
+    encoding = "utf-8"
+
+    def __init__(self):
+        self._value = ""
+        self._line = ""
+
+    def write(self, value: str) -> int:
+        self._value = (self._value + value)[-65536:]
+        self._line = (self._line + value)[-65536:]
+        while "\n" in self._line or "\r" in self._line:
+            line, separator, rest = self._line.replace("\r", "\n").partition("\n")
+            self._line = rest
+            if line.strip():
+                host()._status(line)
+        return len(value)
+
+    def flush(self) -> None:
+        if self._line.strip():
+            host()._status(self._line)
+
+    def getvalue(self) -> str:
+        return self._value
+
+    def isatty(self) -> bool:
+        return False

dailo_sdk-0.1.0/src/dailo/_runtime.py

@@ -0,0 +1,61 @@
+"""由设备宿主绑定执行上下文，编辑器和构建无需设备。"""
+from __future__ import annotations
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass
+from typing import Any
+
+_context: ContextVar[tuple[Any, dict[str, Any]]] = ContextVar("dailo_execution")
+_state: ContextVar[State] = ContextVar("dailo_execution_state")
+_execution: ContextVar[dict[str, Any]] = ContextVar("dailo_execution_info")
+_deadline: ContextVar[float | None] = ContextVar("dailo_wait_deadline", default=None)
+
+
+@dataclass
+class State:
+    guard: Any = None
+    guarding: bool = False
+    trace: Any = None
+    expected: str = ""
+
+    @property
+    def deadline(self) -> float | None:
+        return _deadline.get()
+
+
+@contextmanager
+def deadline_scope(deadline: float):
+    """嵌套等待共用较早的截止时间，诊断也读取同一预算。"""
+    previous = _deadline.get()
+    token = _deadline.set(min(previous, deadline) if previous is not None else deadline)
+    try:
+        yield _deadline.get()
+    finally:
+        _deadline.reset(token)
+
+
+def bind(host: Any, config: dict[str, Any], execution: dict[str, Any] | None = None) -> None:
+    _context.set((host, config))
+    _state.set(State())
+    _deadline.set(None)
+    if execution is not None:
+        _execution.set(execution)
+
+
+def host() -> Any:
+    try:
+        return _context.get()[0]
+    except LookupError:
+        raise RuntimeError("请在代劳设备中运行脚本，或使用 dailo-dev 调试。") from None
+
+
+def config() -> dict[str, Any]:
+    return _context.get()[1]
+
+
+def state() -> State:
+    return _state.get()
+
+
+def execution() -> dict[str, Any]:
+    return _execution.get()