dailo-devtools 0.1.3__tar.gz → 0.1.4__tar.gz

{dailo_devtools-0.1.3/src/dailo_devtools.egg-info → dailo_devtools-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dailo-devtools
-Version: 0.1.3
+Version: 0.1.4
 Summary: 通过代劳 DevTools 调试单台 Android 设备的 Python API 与 CLI
 License-Expression: MIT
 Project-URL: Script SDK, https://pypi.org/project/dailo-sdk/
@@ -19,7 +19,7 @@ Dynamic: license-file
 
 # Dailo DevTools
 
-在电脑上运行和调试代劳 Android 自动化脚本。提供 `dailo-dev` 命令行工具和异步 Python 客户端，可执行脚本、读取文字与控件、保存截图和查看日志。
+在电脑上运行和调试代劳 Android 与 Windows 自动化脚本。提供 `dailo-dev` 命令行工具与 Python 客户端，可执行脚本、读取文字与控件、保存截图和查看日志。
 
 - 命令行执行 Python 文件或短代码。
 - Python API 支持连接设备、截图、观察和停止运行。
@@ -55,6 +55,28 @@ dailo-dev serve --connection connection.json
 
 保持服务运行，在另一个终端执行后续命令。连接文件包含访问设备的凭据，请保存在本机；链接过期或重新连接时，从 App 获取新链接。
 
+## Windows 本机调试
+
+Windows 使用代劳安装目录中的 `runtime/windows-x64`，复用产品的 Rust 宿主和脚本执行通路，无需安装 Python 系统或视觉库。`--hwnd` 或 `--executable` 选择目标；省略时观察当前显示桌面。
+
+```sh
+dailo-dev windows --runtime "C:\Apps\代劳\runtime\windows-x64" applications
+dailo-dev windows --runtime "C:\Apps\代劳\runtime\windows-x64" desktops
+dailo-dev windows --runtime "C:\Apps\代劳\runtime\windows-x64" --hwnd 123456 inspect
+dailo-dev windows --runtime "C:\Apps\代劳\runtime\windows-x64" --hwnd 123456 screenshot screen.png
+dailo-dev windows --runtime "C:\Apps\代劳\runtime\windows-x64" --hwnd 123456 exec --file main.py --timeout 300
+```
+
+Python 客户端提供同一能力；`cancel()` 可由调用方其他线程停止正在执行的脚本：
+
+```python
+from dailo_devtools import Windows
+
+device = Windows(r"C:\Apps\代劳\runtime\windows-x64", hwnd=123456)
+print(device.inspect())
+device.run_file("main.py", config={"rounds": 5})
+```
+
 ## 运行脚本
 
 执行一段代码：
@@ -71,6 +93,13 @@ dailo-dev exec --file main.py --config settings.json
 
 脚本可使用 [dailo-sdk](https://pypi.org/project/dailo-sdk/) 的文字、控件和图片定位 API。文件模式会自动上传脚本目录中的 Python 模块和 `assets/`；`--timeout` 设置执行时限，单位为秒，默认 300。
 
+只携带本次所需资源时，使用 `--assets` 指定相对脚本目录的文件或目录；设备上保留相同相对路径。省略此参数时携带整个 `assets/`，单独使用 `--assets` 时不携带资源。Python 模块始终自动携带。
+
+```sh
+dailo-dev exec --file main.py --assets assets/battle.png assets/maps
+dailo-dev exec --code "from dailo import text; print(text())" --assets
+```
+
 ## 常用命令
 
 | 命令 | 用途 |
@@ -109,6 +138,17 @@ asyncio.run(main())
 
 `Device` 还提供 `run_file(path, config=...)`、`inspect()` 和 `cancel()`。使用 Python 客户端时无需启动 `dailo-dev serve`；异步上下文管理器负责建立和关闭连接。
 
+`run_file()` 和 `execute()` 的 `assets=None` 默认携带 `assets/`。传入显式列表会只携带选定资源，`assets=[]` 不携带资源，例如：
+
+```python
+await device.run_file("main.py", assets=["assets/battle.png", "assets/maps"])
+await device.execute("from dailo import text; print(text())", assets=[])
+```
+
+Windows 的 `run_file()`、`execute()` 每次生成独立 `devtools:windows:…` 执行 ID，脚本通过 `execution()` 读取。明确续接某次失败时传入 `retry_of_execution_id=原执行ID`；新调用默认不关联旧父。调试 ID 不代表产品任务记录。
+
+Android 的同名参数沿用Host提供的本父真实执行ID，只设置本次重试来源，退出后恢复原上下文。续接连续延期时，传入上一父脚本中`dailo.execution().execution_id`的完整原值；不要传请求短ID、sessionId或自行拼接ID。CLI使用`--retry-of-execution-id`，持久服务的`execute`／`run_file`请求使用`retry_of_execution_id`。省略参数表示新调用，不沿用旧延期链；该参数不修改原延期时间，也不绕过最早执行时间。
+
 ## 许可
 
 MIT。

dailo_devtools-0.1.4/README.md

@@ -0,0 +1,135 @@
+# Dailo DevTools
+
+在电脑上运行和调试代劳 Android 与 Windows 自动化脚本。提供 `dailo-dev` 命令行工具与 Python 客户端，可执行脚本、读取文字与控件、保存截图和查看日志。
+
+- 命令行执行 Python 文件或短代码。
+- Python API 支持连接设备、截图、观察和停止运行。
+- 自动携带脚本目录中的 Python 模块与 `assets/`。
+- 图文日志保存到电脑，可离线查看。
+
+## 安装
+
+需要 Python 3.11 或更新版本，以及已安装代劳 App、开启 DevTools 的 Android 设备。
+
+```sh
+python -m pip install dailo-devtools
+dailo-dev install
+```
+
+`dailo-dev install` 安装后台连接所需的 Chromium 运行时，只需执行一次。
+
+## 连接设备
+
+从代劳 App 的 DevTools 入口复制连接链接，保存为 `connection.json`：
+
+```json
+{
+  "url": "<从代劳 App 复制的 DevTools 链接>"
+}
+```
+
+启动连接服务：
+
+```sh
+dailo-dev serve --connection connection.json
+```
+
+保持服务运行，在另一个终端执行后续命令。连接文件包含访问设备的凭据，请保存在本机；链接过期或重新连接时，从 App 获取新链接。
+
+## Windows 本机调试
+
+Windows 使用代劳安装目录中的 `runtime/windows-x64`，复用产品的 Rust 宿主和脚本执行通路，无需安装 Python 系统或视觉库。`--hwnd` 或 `--executable` 选择目标；省略时观察当前显示桌面。
+
+```sh
+dailo-dev windows --runtime "C:\Apps\代劳\runtime\windows-x64" applications
+dailo-dev windows --runtime "C:\Apps\代劳\runtime\windows-x64" desktops
+dailo-dev windows --runtime "C:\Apps\代劳\runtime\windows-x64" --hwnd 123456 inspect
+dailo-dev windows --runtime "C:\Apps\代劳\runtime\windows-x64" --hwnd 123456 screenshot screen.png
+dailo-dev windows --runtime "C:\Apps\代劳\runtime\windows-x64" --hwnd 123456 exec --file main.py --timeout 300
+```
+
+Python 客户端提供同一能力；`cancel()` 可由调用方其他线程停止正在执行的脚本：
+
+```python
+from dailo_devtools import Windows
+
+device = Windows(r"C:\Apps\代劳\runtime\windows-x64", hwnd=123456)
+print(device.inspect())
+device.run_file("main.py", config={"rounds": 5})
+```
+
+## 运行脚本
+
+执行一段代码：
+
+```sh
+dailo-dev exec --code "from dailo import text; print(text())"
+```
+
+执行 Python 文件并传入任务设置：
+
+```sh
+dailo-dev exec --file main.py --config settings.json
+```
+
+脚本可使用 [dailo-sdk](https://pypi.org/project/dailo-sdk/) 的文字、控件和图片定位 API。文件模式会自动上传脚本目录中的 Python 模块和 `assets/`；`--timeout` 设置执行时限，单位为秒，默认 300。
+
+只携带本次所需资源时，使用 `--assets` 指定相对脚本目录的文件或目录；设备上保留相同相对路径。省略此参数时携带整个 `assets/`，单独使用 `--assets` 时不携带资源。Python 模块始终自动携带。
+
+```sh
+dailo-dev exec --file main.py --assets assets/battle.png assets/maps
+dailo-dev exec --code "from dailo import text; print(text())" --assets
+```
+
+## 常用命令
+
+| 命令 | 用途 |
+| --- | --- |
+| `dailo-dev status` | 查看连接和运行状态 |
+| `dailo-dev inspect` | 读取设备画面的文字与控件 |
+| `dailo-dev screenshot screen.png` | 保存设备截图 |
+| `dailo-dev cancel` | 停止当前脚本 |
+| `dailo-dev reconnect` | 使用持久连接配置重新连接设备 |
+| `dailo-dev logs <日志目录>` | 离线查看图文日志 |
+
+运行 `dailo-dev --help` 或 `dailo-dev exec --help` 查看完整选项。
+
+## Python API
+
+```python
+import asyncio
+import json
+from pathlib import Path
+
+from dailo_devtools import Device, read_logs
+
+
+async def main():
+    connection = json.loads(Path("connection.json").read_text(encoding="utf-8"))
+
+    async with Device(connection) as device:
+        result = await device.execute("from dailo import text; print(text())")
+        await device.screenshot("screen.png")
+        print(result)
+        print(read_logs(result["logDirectory"]))
+
+
+asyncio.run(main())
+```
+
+`Device` 还提供 `run_file(path, config=...)`、`inspect()` 和 `cancel()`。使用 Python 客户端时无需启动 `dailo-dev serve`；异步上下文管理器负责建立和关闭连接。
+
+`run_file()` 和 `execute()` 的 `assets=None` 默认携带 `assets/`。传入显式列表会只携带选定资源，`assets=[]` 不携带资源，例如：
+
+```python
+await device.run_file("main.py", assets=["assets/battle.png", "assets/maps"])
+await device.execute("from dailo import text; print(text())", assets=[])
+```
+
+Windows 的 `run_file()`、`execute()` 每次生成独立 `devtools:windows:…` 执行 ID，脚本通过 `execution()` 读取。明确续接某次失败时传入 `retry_of_execution_id=原执行ID`；新调用默认不关联旧父。调试 ID 不代表产品任务记录。
+
+Android 的同名参数沿用Host提供的本父真实执行ID，只设置本次重试来源，退出后恢复原上下文。续接连续延期时，传入上一父脚本中`dailo.execution().execution_id`的完整原值；不要传请求短ID、sessionId或自行拼接ID。CLI使用`--retry-of-execution-id`，持久服务的`execute`／`run_file`请求使用`retry_of_execution_id`。省略参数表示新调用，不沿用旧延期链；该参数不修改原延期时间，也不绕过最早执行时间。
+
+## 许可
+
+MIT。

{dailo_devtools-0.1.3 → dailo_devtools-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dailo-devtools"
-version = "0.1.3"
+version = "0.1.4"
 description = "通过代劳 DevTools 调试单台 Android 设备的 Python API 与 CLI"
 readme = "README.md"
 requires-python = ">=3.11"

{dailo_devtools-0.1.3 → dailo_devtools-0.1.4}/src/dailo_devtools/__init__.py

@@ -4,10 +4,13 @@ from typing import TYPE_CHECKING
 if TYPE_CHECKING:
     from .device import Device, DevtoolsError, read_logs
 
-__all__ = ["Device", "DevtoolsError", "read_logs"]
+__all__ = ["Device", "DevtoolsError", "read_logs", "Windows"]
 
 
 def __getattr__(name: str):
+    if name == 'Windows':
+        from .windows import Windows
+        return Windows
     if name not in __all__:
         raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
     from .device import Device, DevtoolsError, read_logs

{dailo_devtools-0.1.3 → dailo_devtools-0.1.4}/src/dailo_devtools/cli.py

@@ -76,12 +76,44 @@ def main():
     source.add_argument("--code")
     source.add_argument("--file")
     execute.add_argument("--config", help="脚本配置 JSON 文件")
-    execute.add_argument("--assets", action="append", default=[])
+    execute.add_argument("--assets", action="extend", nargs="*", default=None,
+                         help="仅携带指定资源；省略时携带 assets/，不提供路径时不携带资源")
     execute.add_argument("--directory", default=".", help="内联代码所属仓库，默认当前目录")
     execute.add_argument("--timeout", type=float, default=300, help="整个开发运行的传输时限，单位秒")
+    execute.add_argument("--retry-of-execution-id", help="明确续接的上一父真实执行ID；省略时新建延期链")
     raw = sub.add_parser("request", help="直接发送当前 DevTools 协议 JSON")
     raw.add_argument("body")
+    windows = sub.add_parser('windows', help='通过代劳随包 Rust 宿主调试本机 Windows')
+    windows.add_argument('--runtime', required=True, help='代劳安装目录中的 runtime/windows-x64')
+    windows.add_argument('--executable')
+    windows.add_argument('--hwnd', type=lambda value: int(value, 0))
+    commands = windows.add_subparsers(dest='windows_command', required=True)
+    commands.add_parser('applications')
+    commands.add_parser('desktops')
+    commands.add_parser('inspect')
+    commands.add_parser('screenshot').add_argument('path')
+    run = commands.add_parser('exec')
+    source = run.add_mutually_exclusive_group(required=True)
+    source.add_argument('--file')
+    source.add_argument('--code')
+    run.add_argument('--directory', default='.')
+    run.add_argument('--config')
+    run.add_argument('--timeout', type=float, default=300)
     args = parser.parse_args()
+    if args.command == 'windows':
+        from .windows import Windows
+        device = Windows(args.runtime, executable=args.executable, hwnd=args.hwnd)
+        if args.windows_command == 'exec':
+            config = json.loads(Path(args.config).read_text(encoding='utf-8')) if args.config else {}
+            callback = lambda value: print(json.dumps(value, ensure_ascii=False), flush=True)
+            events = (device.run_file(args.file, config=config, timeout=args.timeout, on_event=callback)
+                      if args.file else device.execute(args.code, directory=args.directory,
+                                config=config, timeout=args.timeout, on_event=callback))
+            sys.exit(0 if events[-1].get('status') == 'success' else 1)
+        result = (device.screenshot(args.path) if args.windows_command == 'screenshot'
+                  else getattr(device, args.windows_command)())
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return
     if args.command == "logs":
         from .device import read_logs
         print(json.dumps(read_logs(args.directory), ensure_ascii=False, indent=2))
@@ -108,7 +140,7 @@ def main():
     elif args.command == "inspect":
         body.update(pixels=args.pixels, nodes=not args.no_nodes, text=not args.no_text, raw=args.raw)
     elif args.command == "exec":
-        body.update(timeout=args.timeout, assets=args.assets)
+        body.update(timeout=args.timeout, assets=args.assets, retry_of_execution_id=args.retry_of_execution_id)
         if args.config:
             body["config"] = json.loads(Path(args.config).read_text(encoding="utf-8"))
         if args.file: