dailo-devtools 0.1.0__tar.gz

dailo_devtools-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_devtools-0.1.0/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.4
+Name: dailo-devtools
+Version: 0.1.0
+Summary: 通过代劳 DevTools 调试单台 Android 设备的 Python API 与 CLI
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: playwright<2,>=1.58
+Requires-Dist: aiohttp<4,>=3.14
+Dynamic: license-file
+
+# DevTools
+
+```sh
+pip install dailo-devtools
+dailo-dev install
+dailo-dev serve --connection connection.json
+dailo-dev exec --code "from dailo import text; print(text())"
+dailo-dev exec --file main.py --config account.json
+```
+
+服务复用一条 WebRTC 连接，仅使用 DataChannel，截图按需获取，不持续传输视频。连接文件从设备开发入口取得，勿提交 Git。也可使用 `async with dailo_devtools.Device(connection)` 调用 `execute`、`run_file`、`inspect`、`screenshot`、`cancel`。默认会话30分钟；持久凭据在Python运行前时间不足时重新准入，授权覆盖本次执行、30秒停止收尾和10秒传输，合计最多7天。正式任务使用自己的执行期限。持久凭据支持断线后自动重新准入，中断操作不重放；`dailo-dev reconnect` / `Device.reconnect()` 可主动重连。
+
+`serve` 的 `status` / `cancel` 不触发重连；其他命令在连接失败时先自动重新准入。前检先请求设备状态，再读取服务状态和 `sessionId`，避免用重连前的 `closed` 快照判定当前连接；原设备线程是否退出仍以原生运行计数为准。
+
+长期 `serve` 和长脚本使用持久连接凭据。已配对桌面设备配置为 `{"baseUrl":"实际平台地址","deviceId":"准入返回的公开设备ID","desktopControllerCapability":"控制端凭据"}`；地址与设备 ID 取正式 App 的准入结果，每次重连通过平台公开接口取得新会话。PC 本地控制端口与 `android-local-*` 列表 ID 不提供此准入合同，不能填入该配置。
+
+连接文件也可写为 `{"url":"App 复制的 DevTools 链接"}`，仅用于一次建连。链接中的入场 capability 已消费后不能用于重连，URL 分支不使用 recoveryCapability；断线或到期需从 App 重新获取链接。入场有效期和已建立会话的有效期分别计算，不能把短入场期限当作会话期限。
+
+`log()` 按产生顺序实时保存到本机，每条文字及 PNG 落盘后才确认接收。连接文件可设 `"logDirectory":"D:/my-project/output/logs"` 指定根目录；默认位于用户缓存目录。Python 终态返回 `logDirectory`（请求目录）和 `logsPath`（该目录的 `logs.json`），不再返回 `logs` 数组。`exec` 和原始 Python `request` 使用同一流程；日志事件不会提前完成执行请求。
+
+`from dailo_devtools import read_logs; entries = read_logs(result['logDirectory'])` 读取图文清单；每项保留完整文字，`image.path` 指向原 PNG。也可用 `dailo-dev logs D:/output/logs/请求ID` 离线查看，无需启动服务或重新连接设备。自然结束、脚本失败和取消回执均保存 `execution.json`（stdout、stderr、错误栈及日志路径）。日志清单与 PNG 不依赖终态回执；断线的 `interruption.json` 同样给出路径，仅标记结果未确认。只保证已经落盘的图文，连接失效时未交付的帧不能补造。
+
+Python执行超时后发送停止请求，保留原响应并最多等待30秒完成清理；返回的stdout、stderr、错误栈与图文保存到该请求目录的`execution.json`。停止未响应时关闭旧通道，下一次重新连接；不能把发送停止当作运行已退出。
+
+CLI外层HTTP预算为设备预算+30秒停止收尾+10秒传输余量。升级Playwright后重新运行`dailo-dev install`；安装和服务使用同一个`PLAYWRIGHT_BROWSERS_PATH`，可指定共享目录，避免Store内外缓存视图不同。
+
+`exec --code` 与 `exec --file` 均自动上传仓库 Python 模块和 `assets/`，可使用 `--config`、`--assets`。内联代码默认属于当前目录，也可用 `--directory` 指定。复用仓库的设备工作目录，下载和写入的文件会保留；每次运行刷新源码导入和字节码，停止后重跑也生效，并移除已删除的模块、资源。
+
+请求按16KiB分片发送，缓冲超过64KiB时等待通道释放，避免多图或大资源堵满发送队列。发送超时或失败关闭旧通道，Python结果记为未确认；下一次调用重新准入，不重放请求。
+
+相同资源不重写，更新资源先移除旧文件，避免破坏已加载原生库的内存映射。原生库内容更新后需重启设备上的 Dailo 应用再运行。
+
+信令断开时立即关闭旧DataChannel，并保存请求目录的interruption.json，标记结果未确认。status的activeRun为空仅表示宿主已结束等待，不能作为原设备线程已退出或脚本成功的依据。

dailo_devtools-0.1.0/README.md

@@ -0,0 +1,33 @@
+# DevTools
+
+```sh
+pip install dailo-devtools
+dailo-dev install
+dailo-dev serve --connection connection.json
+dailo-dev exec --code "from dailo import text; print(text())"
+dailo-dev exec --file main.py --config account.json
+```
+
+服务复用一条 WebRTC 连接，仅使用 DataChannel，截图按需获取，不持续传输视频。连接文件从设备开发入口取得，勿提交 Git。也可使用 `async with dailo_devtools.Device(connection)` 调用 `execute`、`run_file`、`inspect`、`screenshot`、`cancel`。默认会话30分钟；持久凭据在Python运行前时间不足时重新准入，授权覆盖本次执行、30秒停止收尾和10秒传输，合计最多7天。正式任务使用自己的执行期限。持久凭据支持断线后自动重新准入，中断操作不重放；`dailo-dev reconnect` / `Device.reconnect()` 可主动重连。
+
+`serve` 的 `status` / `cancel` 不触发重连；其他命令在连接失败时先自动重新准入。前检先请求设备状态，再读取服务状态和 `sessionId`，避免用重连前的 `closed` 快照判定当前连接；原设备线程是否退出仍以原生运行计数为准。
+
+长期 `serve` 和长脚本使用持久连接凭据。已配对桌面设备配置为 `{"baseUrl":"实际平台地址","deviceId":"准入返回的公开设备ID","desktopControllerCapability":"控制端凭据"}`；地址与设备 ID 取正式 App 的准入结果，每次重连通过平台公开接口取得新会话。PC 本地控制端口与 `android-local-*` 列表 ID 不提供此准入合同，不能填入该配置。
+
+连接文件也可写为 `{"url":"App 复制的 DevTools 链接"}`，仅用于一次建连。链接中的入场 capability 已消费后不能用于重连，URL 分支不使用 recoveryCapability；断线或到期需从 App 重新获取链接。入场有效期和已建立会话的有效期分别计算，不能把短入场期限当作会话期限。
+
+`log()` 按产生顺序实时保存到本机，每条文字及 PNG 落盘后才确认接收。连接文件可设 `"logDirectory":"D:/my-project/output/logs"` 指定根目录；默认位于用户缓存目录。Python 终态返回 `logDirectory`（请求目录）和 `logsPath`（该目录的 `logs.json`），不再返回 `logs` 数组。`exec` 和原始 Python `request` 使用同一流程；日志事件不会提前完成执行请求。
+
+`from dailo_devtools import read_logs; entries = read_logs(result['logDirectory'])` 读取图文清单；每项保留完整文字，`image.path` 指向原 PNG。也可用 `dailo-dev logs D:/output/logs/请求ID` 离线查看，无需启动服务或重新连接设备。自然结束、脚本失败和取消回执均保存 `execution.json`（stdout、stderr、错误栈及日志路径）。日志清单与 PNG 不依赖终态回执；断线的 `interruption.json` 同样给出路径，仅标记结果未确认。只保证已经落盘的图文，连接失效时未交付的帧不能补造。
+
+Python执行超时后发送停止请求，保留原响应并最多等待30秒完成清理；返回的stdout、stderr、错误栈与图文保存到该请求目录的`execution.json`。停止未响应时关闭旧通道，下一次重新连接；不能把发送停止当作运行已退出。
+
+CLI外层HTTP预算为设备预算+30秒停止收尾+10秒传输余量。升级Playwright后重新运行`dailo-dev install`；安装和服务使用同一个`PLAYWRIGHT_BROWSERS_PATH`，可指定共享目录，避免Store内外缓存视图不同。
+
+`exec --code` 与 `exec --file` 均自动上传仓库 Python 模块和 `assets/`，可使用 `--config`、`--assets`。内联代码默认属于当前目录，也可用 `--directory` 指定。复用仓库的设备工作目录，下载和写入的文件会保留；每次运行刷新源码导入和字节码，停止后重跑也生效，并移除已删除的模块、资源。
+
+请求按16KiB分片发送，缓冲超过64KiB时等待通道释放，避免多图或大资源堵满发送队列。发送超时或失败关闭旧通道，Python结果记为未确认；下一次调用重新准入，不重放请求。
+
+相同资源不重写，更新资源先移除旧文件，避免破坏已加载原生库的内存映射。原生库内容更新后需重启设备上的 Dailo 应用再运行。
+
+信令断开时立即关闭旧DataChannel，并保存请求目录的interruption.json，标记结果未确认。status的activeRun为空仅表示宿主已结束等待，不能作为原设备线程已退出或脚本成功的依据。

dailo_devtools-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=80"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dailo-devtools"
+version = "0.1.0"
+description = "通过代劳 DevTools 调试单台 Android 设备的 Python API 与 CLI"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+dependencies = ["playwright>=1.58,<2", "aiohttp>=3.14,<4"]
+
+[project.scripts]
+dailo-dev = "dailo_devtools.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+dailo_devtools = ["py.typed"]

dailo_devtools-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dailo_devtools-0.1.0/src/dailo_devtools/__init__.py

@@ -0,0 +1,16 @@
+"""独立 DevTools 客户端；不依赖代劳私有项目，使用后台 Chromium。"""
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .device import Device, DevtoolsError, read_logs
+
+__all__ = ["Device", "DevtoolsError", "read_logs"]
+
+
+def __getattr__(name: str):
+    if name not in __all__:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    from .device import Device, DevtoolsError, read_logs
+
+    globals().update(Device=Device, DevtoolsError=DevtoolsError, read_logs=read_logs)
+    return globals()[name]

dailo_devtools-0.1.0/src/dailo_devtools/cli.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import sys
+import subprocess
+from urllib.error import HTTPError
+from pathlib import Path
+from urllib.request import Request, urlopen
+
+
+async def serve(args):
+    from aiohttp import web
+
+    from .device import Device
+
+    connection = json.loads(Path(args.connection).read_text(encoding="utf-8"))
+    async with Device(connection) as device:
+        reconnecting = asyncio.Lock()
+        async def call(request):
+            try:
+                body = await request.json()
+                command = body.pop("command")
+                if command not in {"status", "cancel"}:
+                    async with reconnecting:
+                        if device.failure or command == "reconnect":
+                            await device.reconnect()
+                if command == "status":
+                    value = await device.status()
+                elif command == "reconnect":
+                    value = await device.status()
+                elif command == "request":
+                    value = await device.request(**body)
+                elif command in {"execute", "run_file", "inspect", "screenshot", "cancel"}:
+                    value = await getattr(device, command)(**body)
+                else:
+                    raise ValueError("不支持的调试命令")
+                return web.json_response({"ok": True, "result": value})
+            except Exception as error:
+                return web.json_response({"ok": False, "error": str(error)}, status=400)
+
+        app = web.Application(client_max_size=16 * 1024 * 1024)
+        app.router.add_post("/call", call)
+        runner = web.AppRunner(app, access_log=None)
+        await runner.setup()
+        await web.TCPSite(runner, "127.0.0.1", args.port).start()
+        print(json.dumps({"ok": True, "port": args.port, "deviceId": device.device_id}), flush=True)
+        try:
+            await asyncio.Event().wait()
+        finally:
+            await runner.cleanup()
+
+
+def main():
+    parser = argparse.ArgumentParser(description="单设备 DevTools 调试；后台 WebRTC，无前台窗口")
+    parser.add_argument("--port", type=int, default=3766)
+    sub = parser.add_subparsers(dest="command", required=True)
+    sub.add_parser("install", help="准备后台 Chromium 运行时（只需执行一次）")
+    server = sub.add_parser("serve", help="保持单台设备连接，为后续 CLI 提供本地 API")
+    server.add_argument("--connection", required=True, help="认证连接 JSON 文件；不输出凭据")
+    sub.add_parser("status")
+    sub.add_parser("reconnect", help="重新连接同一设备，不重复执行脚本")
+    sub.add_parser("cancel")
+    logs = sub.add_parser("logs", help="离线读取请求目录的图文清单，不连接设备")
+    logs.add_argument("directory")
+    screen = sub.add_parser("screenshot")
+    screen.add_argument("path")
+    observation = sub.add_parser("inspect")
+    observation.add_argument("--pixels", action="store_true")
+    observation.add_argument("--raw", action="store_true", help="包含内部诊断数据")
+    observation.add_argument("--no-nodes", action="store_true")
+    observation.add_argument("--no-text", action="store_true")
+    execute = sub.add_parser("exec", help="执行 Python 代码或文件，默认 Locator 隐式等待 30 秒")
+    source = execute.add_mutually_exclusive_group(required=True)
+    source.add_argument("--code")
+    source.add_argument("--file")
+    execute.add_argument("--config", help="脚本配置 JSON 文件")
+    execute.add_argument("--assets", action="append", default=[])
+    execute.add_argument("--directory", default=".", help="内联代码所属仓库，默认当前目录")
+    execute.add_argument("--timeout", type=float, default=300, help="整个开发运行的传输时限，单位秒")
+    raw = sub.add_parser("request", help="直接发送当前 DevTools 协议 JSON")
+    raw.add_argument("body")
+    args = parser.parse_args()
+    if args.command == "logs":
+        from .device import read_logs
+        print(json.dumps(read_logs(args.directory), ensure_ascii=False, indent=2))
+        return
+    if args.command == "install":
+        sys.exit(subprocess.call([sys.executable, "-m", "playwright", "install", "--only-shell", "chromium"],
+                                creationflags=subprocess.CREATE_NO_WINDOW if sys.platform == "win32" else 0))
+    if args.command == "serve":
+        try:
+            asyncio.run(serve(args))
+        except KeyboardInterrupt:
+            pass
+        except Exception as error:
+            # 网络异常可能携带含 capability 的握手 URL；CLI 不打印该 URL。
+            from .device import DevtoolsError
+            message = str(error) if isinstance(error, DevtoolsError) else "连接设备失败"
+            print(json.dumps({"ok": False, "error": message, "type": type(error).__name__},
+                             ensure_ascii=False), file=sys.stderr)
+            sys.exit(1)
+        return
+    body = {"command": args.command}
+    if args.command == "screenshot":
+        body["path"] = str(Path(args.path).resolve())
+    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)
+        if args.config:
+            body["config"] = json.loads(Path(args.config).read_text(encoding="utf-8"))
+        if args.file:
+            body.update(command="run_file", path=str(Path(args.file).resolve()))
+        else:
+            body.update(command="execute", source=args.code, directory=str(Path(args.directory).resolve()))
+    elif args.command == "request":
+        body["body"] = json.loads(args.body)
+    request = Request(f"http://127.0.0.1:{args.port}/call", data=json.dumps(body).encode(),
+                      headers={"Content-Type": "application/json"})
+    try:
+        # 设备预算耗尽后还需30秒接收停止结果，另留10秒传输余量。
+        with urlopen(request, timeout=getattr(args, "timeout", 30) + 40) as response:
+            result = json.load(response)
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        payload = result.get("result", {})
+        execution = payload.get("result") or {}
+        if not result["ok"] or payload.get("ok") is False or execution.get("ok") is False:
+            sys.exit(1)
+    except HTTPError as error:
+        print(error.read().decode(), file=sys.stderr)
+        sys.exit(1)
+    except Exception as error:
+        print(json.dumps({"ok": False, "error": str(error)}, ensure_ascii=False), file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

dailo_devtools-0.1.0/src/dailo_devtools/device.py

@@ -0,0 +1,693 @@
+from __future__ import annotations
+
+import asyncio
+import base64
+import contextlib
+import io
+import os
+import json
+import hashlib
+import math
+import re
+import traceback
+import uuid
+import zipfile
+from pathlib import Path
+from collections.abc import Iterable, Mapping
+from datetime import datetime, timezone
+from typing import Any
+from urllib.parse import parse_qs, quote, urlencode, urlsplit
+
+import aiohttp
+from playwright.async_api import async_playwright
+
+
+TRANSPORT = """async (iceServers) => {
+  const peer = window.peer = new RTCPeerConnection({iceServers});
+  window.localCandidates = [];
+  peer.onicecandidate = event => {
+    if (event.candidate) {
+      const {candidate, sdpMid, sdpMLineIndex} = event.candidate;
+      window.localCandidates.push({candidate, sdpMid, sdpMLineIndex});
+    }
+  };
+  const channels = window.channels = {};
+  for (const label of ['control', 'inspection']) {
+    const channel = channels[label] = peer.createDataChannel(label, {ordered:true});
+    channel.onopen = () => {
+      if (Object.values(channels).every(item => item.readyState === 'open')) window.transportEvent('ready');
+    };
+    channel.onclose = () => window.transportEvent('closed', {
+      source: 'channel', label, readyState: channel.readyState,
+      connectionState: peer.connectionState, iceConnectionState: peer.iceConnectionState
+    });
+  }
+  for (const channel of Object.values(channels))
+    channel.onmessage = event => window.transportMessage(event.data);
+  peer.onconnectionstatechange = () => {
+    if (['failed','closed'].includes(peer.connectionState)) window.transportEvent('closed', {
+      source: 'peer', connectionState: peer.connectionState, iceConnectionState: peer.iceConnectionState
+    });
+  };
+} """
+
+CREATE_OFFER = """async () => {
+  await peer.setLocalDescription(await peer.createOffer());
+  if (peer.iceGatheringState !== 'complete') await new Promise(resolve => {
+    peer.addEventListener('icegatheringstatechange', () => {
+      if (peer.iceGatheringState === 'complete') resolve();
+    });
+  });
+  return {sdp: peer.localDescription.sdp, candidates: window.localCandidates};
+} """
+
+SEND_REQUEST = """async wire => {
+  const channel = channels.inspection;
+  const bytes = new TextEncoder().encode(wire);
+  const upload = window.devtoolsUpload = {totalBytes: bytes.length, queuedBytes: 0, terminatorSent: false};
+  channel.bufferedAmountLowThreshold = 65536;
+  for (let offset = 0; offset < bytes.length; offset += 16384) {
+    if (channel.readyState !== 'open') throw new Error('DevTools inspection channel closed');
+    if (channel.bufferedAmount > channel.bufferedAmountLowThreshold) {
+      await new Promise((resolve, reject) => {
+        const clear = () => {
+          channel.removeEventListener('bufferedamountlow', drained);
+          channel.removeEventListener('closing', closed);
+          channel.removeEventListener('close', closed);
+          channel.removeEventListener('error', closed);
+        };
+        const drained = () => { clear(); resolve(); };
+        const closed = () => { clear(); reject(new Error('DevTools inspection channel closed')); };
+        channel.addEventListener('bufferedamountlow', drained);
+        channel.addEventListener('closing', closed);
+        channel.addEventListener('close', closed);
+        channel.addEventListener('error', closed);
+      });
+    }
+    channel.send(bytes.slice(offset, offset + 16384));
+    upload.queuedBytes = Math.min(offset + 16384, bytes.length);
+  }
+  channel.send(new Uint8Array());
+  upload.terminatorSent = true;
+} """
+
+TRANSPORT_SNAPSHOT = """() => ({
+  connectionState: peer.connectionState,
+  iceConnectionState: peer.iceConnectionState,
+  channels: Object.fromEntries(Object.entries(channels).map(([name, channel]) =>
+    [name, {readyState: channel.readyState, bufferedAmount: channel.bufferedAmount}])),
+  upload: window.devtoolsUpload
+})"""
+
+
+def _transport_error(error: Exception) -> str:
+    # 与持久serve一致，传输证据不保存带认证参数的连接URL。
+    return re.sub(r"(?:https?|wss?)://\S+", "<url>", str(error))
+
+
+def _exception_chain(error: Exception | None) -> list[dict[str, Any]]:
+    if error is None:
+        return []
+    trace = traceback.TracebackException.from_exception(error, lookup_lines=False, capture_locals=False)
+    chain = []
+    while trace is not None:
+        chain.append({"exceptionClass": type(error).__name__, "error": _transport_error(error),
+            "frames": [{"file": Path(frame.filename).name, "function": frame.name, "line": frame.lineno}
+                       for frame in trace.stack]})
+        if trace.__cause__ is not None:
+            trace, error = trace.__cause__, error.__cause__
+        else:
+            trace, error = (None if trace.__suppress_context__ else trace.__context__), error.__context__
+    return chain
+
+
+class DevtoolsError(RuntimeError):
+    pass
+
+
+def read_logs(directory: str | Path) -> list[dict[str, Any]]:
+    """离线读取已落盘日志；image.path 指向 PNG，不重新装载图像。"""
+    return json.loads((Path(directory) / 'logs.json').read_text(encoding='utf-8'))
+
+
+class Device:
+    """一个认证设备、一条持久 WebRTC 通道；所有识别在 Android 上执行。"""
+
+    def __init__(self, connection: dict[str, Any]):
+        self.connection = connection
+        self.pending: dict[str, asyncio.Future] = {}
+        self.chunks: dict[str, dict[int, str]] = {}
+        self.tasks: list[asyncio.Task] = []
+        self.log_tasks: set[asyncio.Task] = set()
+        self.active_python: str | None = None
+        self.send_lock = asyncio.Lock()
+        self.ready = asyncio.Event()
+        self.failure: Exception | None = None
+        self.failure_events: list[dict[str, Any]] = []
+        self.session_timeout = 1800.0
+
+    async def __aenter__(self) -> Device:
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *_):
+        await self.close()
+
+    async def connect(self) -> None:
+        """建立一次 WebRTC 连接；后续调用复用该连接。"""
+        self.http = aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=30))
+        try:
+            admission, signal_url, local = await self._admit()
+            self.connected_at = asyncio.get_running_loop().time()
+            self.session_id = admission["sessionId"]
+            self.device_id = admission.get("deviceId", self.connection.get("deviceId", ""))
+            self.playwright = await async_playwright().start()
+            self.browser = await self.playwright.chromium.launch(headless=True)
+            self.browser.on("disconnected", lambda _: self._fail(DevtoolsError("DevTools 后台浏览器已关闭"), source="browser"))
+            self.page = await self.browser.new_page()
+            await self.page.expose_function("transportEvent", self._transport_event)
+            await self.page.expose_function("transportMessage", self._message)
+            ice = [] if local else [{"urls": "stun:stun.cloudflare.com:3478"}]
+            await self.page.evaluate(TRANSPORT, ice)
+
+            self.socket = await self.http.ws_connect(signal_url)
+            self.tasks.extend([
+                asyncio.create_task(self._signals()),
+                asyncio.create_task(self._keepalive()),
+            ])
+            try:
+                await asyncio.wait_for(self.ready.wait(), 30)
+            except TimeoutError:
+                raise DevtoolsError("WebRTC 通道在 30 秒内未建立，请检查设备内 DevTools 服务与信令连接。") from None
+            if self.failure:
+                raise self.failure
+        except BaseException:
+            await self.close()
+            raise
+
+    async def _admit(self):
+        conf = self.connection
+        if conf.get("url"):
+            parsed = urlsplit(conf["url"])
+            params = parse_qs(parsed.fragment)
+            admission = {key: params[key][0] for key in ("sessionId", "capability", "deviceId")}
+            local = bool(params.get("signalBaseUrl"))
+            base = (params.get("signalBaseUrl") or params.get("signalFleetBaseUrl") or
+                    [f"{parsed.scheme}://{parsed.netloc}"])[0]
+        else:
+            base = conf["baseUrl"].rstrip("/")
+            device_id = conf["deviceId"]
+            local = bool(conf.get("local"))
+            if conf.get("operatorCredential"):
+                path = f"/api/operations/devices/{quote(device_id, safe='')}/sessions"
+                headers = {"X-Dailo-Operator": conf["operatorCredential"]}
+                body = {"scope": "devtools"}
+            else:
+                path = f"/api/devtools/devices/{quote(device_id, safe='')}/sessions"
+                if conf.get("desktopControllerCapability"):
+                    headers = {"x-dailo-desktop-controller-capability": conf["desktopControllerCapability"]}
+                else:
+                    headers = {"x-dailo-device-id": device_id,
+                               "x-dailo-devtools-credential": conf["credential"]}
+                body = {}
+            if self.session_timeout > 1800:
+                body["timeoutMs"] = math.ceil(self.session_timeout * 1000)
+            async with self.http.post(base + path, json=body, headers=headers) as response:
+                value = await response.json()
+                if response.status >= 400:
+                    raise DevtoolsError(value.get("error", f"DevTools 入场失败 HTTP {response.status}"))
+                admission = {**value, "deviceId": device_id}
+        parsed = urlsplit(base)
+        route = "/api/session/ws" if local else "/api/fleet/session"
+        signal_url = ("wss" if parsed.scheme == "https" else "ws") + "://" + parsed.netloc + route
+        return admission, signal_url + "?" + urlencode({"capability": admission["capability"]}), local
+
+    async def reconnect(self) -> None:
+        """重新入场并连接设备；保留设备当前画面，不重放断线时的操作。"""
+        await self.close()
+        self.ready.clear()
+        self.failure = None
+        self.failure_events.clear()
+        try:
+            await self.connect()
+        except Exception as error:
+            failure = error if isinstance(error, DevtoolsError) else DevtoolsError("重新连接设备失败")
+            self._fail(failure, source="reconnect")
+            raise failure from None
+
+    def _transport_event(self, event, details=None):
+        if event == "ready":
+            self.ready.set()
+        else:
+            self._fail(DevtoolsError("DevTools 通道已关闭"), source="transport", details=details)
+
+    async def status(self) -> dict[str, Any]:
+        """读取连接状态与当前运行标识。"""
+        try:
+            transport = await asyncio.wait_for(self.page.evaluate(TRANSPORT_SNAPSHOT), 1)
+        except Exception as error:
+            if self.failure is None:
+                raise
+            transport = {"errorClass": type(error).__name__, "error": _transport_error(error)}
+        signal_error = self.socket.exception()
+        return {"deviceId": self.device_id, "sessionId": self.session_id,
+                "connectionState": "closed" if self.failure else transport["connectionState"],
+                "activeRun": self.active_python,
+                "error": _transport_error(self.failure) if self.failure else None,
+                "diagnostics": {"failureEvents": self.failure_events.copy(), "transport": transport,
+                    "signal": {"closed": self.socket.closed, "closeCode": self.socket.close_code,
+                        "exceptionClass": type(signal_error).__name__ if signal_error else None,
+                        "exception": _transport_error(signal_error) if signal_error else None}}}
+
+    def _fail(self, failure, *, source="device", details=None):
+        self.failure_events.append({"recordedAt": datetime.now(timezone.utc).isoformat(),
+            "source": source, "errorClass": type(failure).__name__, "error": _transport_error(failure),
+            "details": details})
+        if self.failure is None:
+            self.failure = failure
+        self.ready.set()
+        self.chunks.clear()
+        for future in list(self.pending.values()):
+            if not future.done():
+                future.set_exception(self.failure)
+
+    async def _close_failed_peer(self):
+        with contextlib.suppress(Exception):
+            await self.page.evaluate("peer.close()")
+
+    async def _signal(self, kind, payload):
+        await self.socket.send_json({"type": "signal", "payload": {
+            "sessionId": self.session_id, "scope": "devtools",
+            "payload": {"kind": kind, "payload": payload},
+        }})
+
+    def _signal_details(self, phase, error=None):
+        socket_error = self.socket.exception()
+        return {"phase": phase, "closed": self.socket.closed, "localCloseCode": self.socket.close_code,
+                "socketExceptionClass": type(socket_error).__name__ if socket_error else None,
+                "exceptionChain": _exception_chain(error if error is not None else socket_error)}
+
+    async def _signals(self):
+        offered = False
+        try:
+            async for message in self.socket:
+                if message.type == aiohttp.WSMsgType.ERROR:
+                    self._fail(DevtoolsError(f"信令连接错误（{type(message.data).__name__}）：{_transport_error(message.data)}"),
+                        source="signaling", details={"messageType": "ERROR", "exceptionClass": type(message.data).__name__,
+                            "exception": _transport_error(message.data),
+                            **self._signal_details("receive_error", message.data)})
+                    break
+                if message.type != aiohttp.WSMsgType.TEXT:
+                    continue
+                if message.data == "dailo:signaling:pong":
+                    continue
+                envelope = json.loads(message.data)["payload"]
+                signal = envelope["payload"]
+                kind, payload = signal["kind"], signal.get("payload", {})
+                if kind == "agent_status":
+                    if not payload.get("ready"):
+                        raise DevtoolsError("设备服务未就绪：" + json.dumps(payload, ensure_ascii=False))
+                    if payload["status"] == "session_ready" and not offered:
+                        offered = True
+                        offer = await self.page.evaluate(CREATE_OFFER)
+                        await self._signal("offer", offer)
+                elif kind == "answer":
+                    await self.page.evaluate("sdp => peer.setRemoteDescription({type:'answer', sdp})", payload["sdp"])
+                    for candidate in payload["candidates"]:
+                        await self._candidate(candidate)
+                elif kind == "ice":
+                    await self._candidate(payload["candidate"])
+                elif kind == "ice_complete":
+                    await self.page.evaluate("peer.addIceCandidate(null)")
+                elif kind == "close":
+                    raise DevtoolsError("设备结束了开发会话")
+            code = self.socket.close_code
+            error = self.socket.exception()
+            self._fail(DevtoolsError(
+                "开发会话授权已到期。"
+                if code == 4008 else f"信令连接已关闭（{code}）" +
+                (f"；{type(error).__name__}：{_transport_error(error)}" if error else "")), source="signaling",
+                details=self._signal_details("iterator_ended", error))
+        except asyncio.CancelledError:
+            raise
+        except Exception as error:
+            self._fail(DevtoolsError(_transport_error(error)), source="signaling",
+                details=self._signal_details("receive_exception", error))
+        finally:
+            if self.failure:
+                # 信令已失效时立即关闭旧通道，不等下一条命令才释放。
+                await self._close_failed_peer()
+
+    async def _candidate(self, value):
+        await self.page.evaluate("candidate => peer.addIceCandidate(candidate)", value)
+
+    async def _keepalive(self):
+        try:
+            while True:
+                await asyncio.sleep(30)
+                await self.socket.send_str("dailo:signaling:ping")
+        except asyncio.CancelledError:
+            raise
+        except Exception as error:
+            self._fail(DevtoolsError(f"信令保活发送失败（{type(error).__name__}）：{_transport_error(error)}"), source="signaling_keepalive")
+            await self._close_failed_peer()
+
+    def _message(self, wire):
+        message = json.loads(wire)
+        body = message["body"]
+        request_id = body.get("id")
+        if message["type"] == "devtools_response_chunk":
+            chunks = self.chunks.setdefault(request_id, {})
+            chunks[body["chunkIndex"]] = body["data"]
+            if len(chunks) != body["chunkCount"]:
+                return
+            message = json.loads("".join(chunks[i] for i in range(body["chunkCount"])))
+            body = message["body"]
+            self.chunks.pop(request_id, None)
+        payload = body.get("body")
+        if isinstance(payload, dict) and payload.get("kind") == "execution_log":
+            owner = payload["requestId"]
+            if owner not in self.pending:
+                return
+            try:
+                self._store_log(payload["log"], owner)
+            except Exception as error:
+                self._fail(DevtoolsError(f"开发日志保存失败：{error}"), source="execution_log")
+                task = asyncio.create_task(self._close_failed_peer())
+            else:
+                task = asyncio.create_task(self._acknowledge_log(payload["log"]["logId"]))
+            self.log_tasks.add(task)
+            task.add_done_callback(self.log_tasks.discard)
+            return
+        request_id = body.get("id")
+        if request_id not in self.pending:
+            return
+        future = self.pending[request_id]
+        if not future.done():
+            if body["ok"]:
+                future.set_result(body["body"])
+            else:
+                future.set_exception(DevtoolsError(body["error"]))
+
+    async def request(self, body: dict[str, Any], *, timeout: float = 30,
+                      request_id: str | None = None) -> dict[str, Any]:
+        """复用连接发送请求；已断线时先重新入场，不重放此前请求。"""
+        if body["kind"] == "python":
+            required = timeout + 40
+            if required > 604800:
+                raise DevtoolsError("开发运行与清理预算不能超过 7 天")
+            if self.connection.get("url") and required >= self.session_timeout:
+                raise DevtoolsError("一次性开发链接不能延长授权，请使用持久连接凭据运行长脚本")
+            if self.connection.get("baseUrl"):
+                async with self.send_lock:
+                    if self.failure or asyncio.get_running_loop().time() - self.connected_at + required >= self.session_timeout:
+                        self.session_timeout = max(1800.0, required)
+                        await self.reconnect()
+            elif self.failure:
+                await self.reconnect()
+        elif self.failure:
+            if body["kind"] == "python_cancel":
+                raise self.failure
+            async with self.send_lock:
+                if self.failure:
+                    await self.reconnect()
+        request_id = request_id or uuid.uuid4().hex
+        future = asyncio.get_running_loop().create_future()
+        self.pending[request_id] = future
+        deadline = asyncio.get_running_loop().time() + timeout
+        request_evidence = {"kind": body["kind"], "timeoutSeconds": timeout, "sendComplete": False}
+        try:
+            if body['kind'] == 'python':
+                (self._log_folder(request_id) / 'logs.json').write_bytes(b'[]')
+            wire = json.dumps({**body, "id": request_id}, ensure_ascii=False).encode("utf-8")
+            request_evidence.update(wireBytes=len(wire), wireSha256=hashlib.sha256(wire).hexdigest())
+            if body["kind"] == "python_cancel":
+                await self.page.evaluate("wire => channels.control.send(wire)", wire.decode("utf-8"))
+            else:
+                async with self.send_lock:
+                    try:
+                        await asyncio.wait_for(self.page.evaluate(SEND_REQUEST, wire.decode("utf-8")),
+                                               max(0, deadline - asyncio.get_running_loop().time()))
+                    except Exception as error:
+                        try:
+                            # 失败后只取本地浏览器状态，不延长发送预算或重发请求。
+                            request_evidence["transport"] = await asyncio.wait_for(self.page.evaluate(TRANSPORT_SNAPSHOT), 1)
+                        except Exception as snapshot_error:
+                            request_evidence["transport"] = {"errorClass": type(snapshot_error).__name__,
+                                "error": _transport_error(snapshot_error)}
+                        self._fail(DevtoolsError(f"开发请求发送失败（{type(error).__name__}）：{_transport_error(error)}"), source="request_send")
+                        await self._close_failed_peer()
+                        future.exception()
+                        raise self.failure from None
+            request_evidence["sendComplete"] = True
+            if body['kind'] == 'python':
+                completed, _ = await asyncio.wait({future}, timeout=max(0, deadline - asyncio.get_running_loop().time()))
+                if not completed:
+                    raise TimeoutError
+                result = future.result()
+            else:
+                result = await asyncio.wait_for(future, max(0, deadline - asyncio.get_running_loop().time()))
+            if body['kind'] == 'python':
+                self._finish_logs(result, request_id)
+            return result
+        except TimeoutError:
+            if body["kind"] == "python":
+                await self.page.evaluate("wire => channels.control.send(wire)", json.dumps({
+                    "kind": "python_cancel", "id": uuid.uuid4().hex, "requestId": request_id}))
+                try:
+                    # 保留原响应future，接收停止后的stdout、栈和同帧日志。
+                    result = await asyncio.wait_for(future, 30)
+                except TimeoutError:
+                    failure = DevtoolsError(f"开发运行在 {timeout:g} 秒内未结束，停止30秒未响应，已关闭旧通道。")
+                    self._fail(failure, source="python_timeout")
+                    with contextlib.suppress(Exception):
+                        await self.page.evaluate("peer.close()")
+                    raise failure from None
+                except Exception as error:
+                    if self.failure:
+                        raise self._record_interruption(error, request_id, request_evidence) from None
+                    raise
+                self._finish_logs(result, request_id)
+                path = Path(result['logDirectory']) / 'execution.json'
+                raise DevtoolsError(f"开发运行在 {timeout:g} 秒内未结束，停止结果已保存：{path}") from None
+            raise DevtoolsError(f"设备未响应 {body['kind']}（{timeout:g} 秒超时）。") from None
+        except Exception as error:
+            if body["kind"] == "python" and self.failure:
+                raise self._record_interruption(error, request_id, request_evidence) from None
+            raise
+        finally:
+            self.pending.pop(request_id, None)
+            self.chunks.pop(request_id, None)
+
+    def _record_interruption(self, error, request_id, request_evidence):
+        folder = self._log_folder(request_id)
+        path = folder / 'interruption.json'
+        path.write_text(json.dumps({
+            "recordedAt": datetime.now(timezone.utc).isoformat(),
+            "requestId": request_id, "sessionId": self.session_id,
+            "deviceId": self.device_id, "outcome": "unconfirmed",
+            "error": _transport_error(error), "failureEvents": self.failure_events.copy(),
+            "request": request_evidence,
+            "logDirectory": str(folder), "logsPath": str(folder / 'logs.json'),
+        }, ensure_ascii=False, indent=2), encoding='utf-8')
+        return DevtoolsError(f"{error}；运行结果未确认，断线记录已保存：{path}")
+
+    async def _execute(self, source: str, *, timeout: float = 300) -> dict[str, Any]:
+        """执行 Python，返回运行结果；result 含 stdout、stderr 和执行状态。"""
+        if self.active_python:
+            raise DevtoolsError("设备已有一个开发脚本在运行")
+        request_id = uuid.uuid4().hex
+        self.active_python = request_id
+        try:
+            result = await self.request({"kind": "python", "command": source}, timeout=timeout, request_id=request_id)
+            return result
+        finally:
+            self.active_python = None
+
+    def _log_folder(self, request_id: str) -> Path:
+        root = Path(self.connection.get('logDirectory') or Path.home() / '.cache' / 'dailo-devtools' / 'logs')
+        folder = root.resolve() / request_id
+        folder.mkdir(parents=True, exist_ok=True)
+        return folder
+
+    def _store_log(self, entry: dict[str, Any], request_id: str) -> None:
+        folder = self._log_folder(request_id)
+        picture = entry.get('image')
+        if picture:
+            path = folder / (hashlib.sha256(entry['logId'].encode()).hexdigest() + '.png')
+            path.write_bytes(base64.b64decode(picture.pop('dataBase64')))
+            picture['path'] = str(path)
+        path = folder / 'logs.json'
+        if not path.exists():
+            path.write_bytes(b'[]')
+        # 原生等落盘收据才会发下一条；追加完整 JSON，不在 PC 累积图文数组。
+        with path.open('r+b') as output:
+            output.seek(-1, os.SEEK_END)
+            prefix = b',\n' if output.tell() > 1 else b'\n'
+            output.write(prefix + json.dumps(entry, ensure_ascii=False).encode('utf-8') + b'\n]')
+
+    async def _acknowledge_log(self, log_id: str) -> None:
+        try:
+            await self.page.evaluate("wire => channels.control.send(wire)", json.dumps({
+                "kind": "execution_log_stored", "logId": log_id}))
+        except Exception as error:
+            self._fail(DevtoolsError(f"开发日志落盘确认发送失败：{error}"), source="execution_log_ack")
+            await self._close_failed_peer()
+
+    def _finish_logs(self, result: dict[str, Any], request_id: str) -> None:
+        folder = self._log_folder(request_id)
+        result['logDirectory'] = str(folder)
+        result['logsPath'] = str(folder / 'logs.json')
+        (folder / 'execution.json').write_text(json.dumps(result, ensure_ascii=False, indent=2), encoding='utf-8')
+
+    async def cancel(self) -> dict[str, Any]:
+        """停止当前开发脚本，保持连接。"""
+        if self.active_python:
+            return await self.request({"kind": "python_cancel", "requestId": self.active_python})
+        return {"ok": True, "running": False}
+
+    async def screenshot(self, path: str | Path) -> dict[str, Any]:
+        """保存设备原图到 PC，返回图片尺寸等信息。"""
+        result = await self.request({"kind": "snapshot"})
+        Path(path).parent.mkdir(parents=True, exist_ok=True)
+        Path(path).write_bytes(base64.b64decode(result["dataBase64"]))
+        return {key: value for key, value in result.items() if key != "dataBase64"}
+
+    async def inspect(self, *, pixels: bool = False, nodes: bool = True,
+                      text: bool = True, raw: bool = False) -> dict[str, Any]:
+        """观察控件、文字和坐标；raw=True 包含识别耗时等内部诊断数据。"""
+        result = await self.request({"kind": "inspect", "pixels": pixels, "nodes": nodes, "text": text})
+        if raw:
+            return result
+        value = {"ok": result["ok"], "frameId": result["frameId"],
+                 "size": [result["width"], result["height"]]}
+        if text:
+            value["text"] = [{"text": line["text"], "bounds": [line["rect"][key] for key in
+                              ("left", "top", "right", "bottom")]}
+                             for line in (result.get("ocr") or {}).get("lines", []) if line["found"]]
+        if nodes:
+            value["nodes"] = (result.get("nodes") or {}).get("nodes", [])
+        if pixels:
+            value["snapshot"] = result.get("snapshot")
+        if result.get("errors"):
+            value["errors"] = result["errors"]
+        return value
+
+    async def run_file(self, path: str | Path, *, config: Mapping[str, Any] | None = None,
+                       assets: Iterable[str | Path] = (), timeout: float = 300) -> dict[str, Any]:
+        """运行入口，自动携带仓库 Python 模块和 assets；保留设备缓存，重跑加载新源码。"""
+        path = Path(path).resolve()
+        return await self._run_workspace(path, path.read_text(encoding="utf-8"), config, assets, timeout)
+
+    async def execute(self, source: str, *, directory: str | Path | None = None,
+                      config: Mapping[str, Any] | None = None,
+                      assets: Iterable[str | Path] = (), timeout: float = 300) -> dict[str, Any]:
+        """在当前仓库的设备工作目录执行代码；模块、相对路径和 assets 与 run_file 一致。"""
+        folder = Path(directory or Path.cwd()).resolve()
+        return await self._run_workspace(folder / ".dailo-repl.py", source, config, assets, timeout)
+
+    async def _run_workspace(self, path: Path, source: str, config: Mapping[str, Any] | None,
+                             assets: Iterable[str | Path], timeout: float) -> dict[str, Any]:
+        config = dict(config or {})
+        archive = io.BytesIO()
+        with zipfile.ZipFile(archive, "w", zipfile.ZIP_DEFLATED) as bundle:
+            files = set()
+            for folder, directories, names in os.walk(path.parent):
+                directories[:] = [name for name in directories if name not in {
+                    '.git', '.venv', 'node_modules', 'downloads', 'data', 'state', '__pycache__', 'dist',
+                }]
+                files.update(Path(folder) / name for name in names if name.endswith('.py'))
+            for entry in [path.parent / 'assets', *assets]:
+                asset = (path.parent / entry).resolve()
+                for item in (asset.rglob("*") if asset.is_dir() else [asset]):
+                    if item.is_file():
+                        files.add(item)
+            for item in sorted(files):
+                if item != path:
+                    bundle.write(item, item.relative_to(path.parent).as_posix())
+            bundle.writestr(path.name, source)
+        encoded = base64.b64encode(archive.getvalue()).decode()
+        workspace = hashlib.sha256(str(path.parent).encode()).hexdigest()[:16]
+        program = f'''def __run_local_file():
+    import os, sys, io, json, base64, zipfile, importlib.util
+    from pathlib import Path
+    from dailo._runtime import bind, host, config as get_config
+    native_host = host()
+    previous_config = get_config()
+    workspace = json.loads(native_host._app_operation(json.dumps({{"operation":"workspace", "name":{workspace!r}}})))
+    if not workspace['ok']:
+        raise RuntimeError(workspace['error'])
+    folder = workspace['path']
+    bundle = zipfile.ZipFile(io.BytesIO(base64.b64decode({encoded!r})))
+    manifest = Path(folder) / '.dailo-devtools-files.json'
+    previous_files = json.loads(manifest.read_text()) if manifest.exists() else []
+    for name in set(previous_files) - set(bundle.namelist()):
+        (Path(folder) / name).unlink(missing_ok=True)
+    for entry in bundle.infolist():
+        target = Path(folder) / entry.filename
+        if entry.is_dir():
+            target.mkdir(parents=True, exist_ok=True)
+            continue
+        content = bundle.read(entry)
+        if target.is_file() and target.read_bytes() == content:
+            continue
+        # 不截断已加载的原生库映射；同内容保留，更新使用新文件。
+        target.unlink(missing_ok=True)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_bytes(content)
+    manifest.write_text(json.dumps(bundle.namelist()))
+    # 停止会中断 Python 清理；下一次运行主动清除工作区导入与字节码。
+    workspace_root = Path(folder).resolve().parent
+    def clear_workspace_modules():
+        for name, module in list(sys.modules.items()):
+            module_path = getattr(module, '__file__', None)
+            if module_path and Path(module_path).resolve().is_relative_to(workspace_root):
+                del sys.modules[name]
+    clear_workspace_modules()
+    for name in bundle.namelist():
+        if name.endswith('.py'):
+            Path(importlib.util.cache_from_source(str(Path(folder) / name))).unlink(missing_ok=True)
+    previous_dir = os.getcwd()
+    sys.path[:] = [entry for entry in sys.path
+                   if not Path(entry or previous_dir).resolve().is_relative_to(workspace_root)]
+    previous_path = sys.path.copy()
+    os.chdir(folder)
+    bind(native_host, {config or {}!r})
+    try:
+        scope = {{'__file__': os.path.join(folder, {path.name!r}), '__name__': '__main__'}}
+        sys.path.insert(0, folder)
+        try:
+            with open(scope['__file__'], encoding='utf-8') as script:
+                exec(compile(script.read(), scope['__file__'], 'exec'), scope)
+        finally:
+            sys.path[:] = previous_path
+            clear_workspace_modules()
+    finally:
+        os.chdir(previous_dir)
+        bind(native_host, previous_config)
+try:
+    __run_local_file()
+finally:
+    del __run_local_file
+'''
+        return await self._execute(program, timeout=timeout)
+
+    async def close(self) -> None:
+        """结束开发会话并关闭后台 Chromium。"""
+        tasks = [*self.tasks, *self.log_tasks]
+        for task in tasks:
+            task.cancel()
+        for task in tasks:
+            with contextlib.suppress(asyncio.CancelledError, Exception):
+                await task
+        self.tasks.clear()
+        self.log_tasks.clear()
+        self.chunks.clear()
+        if hasattr(self, "socket"):
+            await self.socket.close()
+        if hasattr(self, "browser"):
+            await self.browser.close()
+        if hasattr(self, "playwright"):
+            await self.playwright.stop()
+        if hasattr(self, "http"):
+            await self.http.close()

dailo_devtools-0.1.0/src/dailo_devtools.egg-info/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.4
+Name: dailo-devtools
+Version: 0.1.0
+Summary: 通过代劳 DevTools 调试单台 Android 设备的 Python API 与 CLI
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: playwright<2,>=1.58
+Requires-Dist: aiohttp<4,>=3.14
+Dynamic: license-file
+
+# DevTools
+
+```sh
+pip install dailo-devtools
+dailo-dev install
+dailo-dev serve --connection connection.json
+dailo-dev exec --code "from dailo import text; print(text())"
+dailo-dev exec --file main.py --config account.json
+```
+
+服务复用一条 WebRTC 连接，仅使用 DataChannel，截图按需获取，不持续传输视频。连接文件从设备开发入口取得，勿提交 Git。也可使用 `async with dailo_devtools.Device(connection)` 调用 `execute`、`run_file`、`inspect`、`screenshot`、`cancel`。默认会话30分钟；持久凭据在Python运行前时间不足时重新准入，授权覆盖本次执行、30秒停止收尾和10秒传输，合计最多7天。正式任务使用自己的执行期限。持久凭据支持断线后自动重新准入，中断操作不重放；`dailo-dev reconnect` / `Device.reconnect()` 可主动重连。
+
+`serve` 的 `status` / `cancel` 不触发重连；其他命令在连接失败时先自动重新准入。前检先请求设备状态，再读取服务状态和 `sessionId`，避免用重连前的 `closed` 快照判定当前连接；原设备线程是否退出仍以原生运行计数为准。
+
+长期 `serve` 和长脚本使用持久连接凭据。已配对桌面设备配置为 `{"baseUrl":"实际平台地址","deviceId":"准入返回的公开设备ID","desktopControllerCapability":"控制端凭据"}`；地址与设备 ID 取正式 App 的准入结果，每次重连通过平台公开接口取得新会话。PC 本地控制端口与 `android-local-*` 列表 ID 不提供此准入合同，不能填入该配置。
+
+连接文件也可写为 `{"url":"App 复制的 DevTools 链接"}`，仅用于一次建连。链接中的入场 capability 已消费后不能用于重连，URL 分支不使用 recoveryCapability；断线或到期需从 App 重新获取链接。入场有效期和已建立会话的有效期分别计算，不能把短入场期限当作会话期限。
+
+`log()` 按产生顺序实时保存到本机，每条文字及 PNG 落盘后才确认接收。连接文件可设 `"logDirectory":"D:/my-project/output/logs"` 指定根目录；默认位于用户缓存目录。Python 终态返回 `logDirectory`（请求目录）和 `logsPath`（该目录的 `logs.json`），不再返回 `logs` 数组。`exec` 和原始 Python `request` 使用同一流程；日志事件不会提前完成执行请求。
+
+`from dailo_devtools import read_logs; entries = read_logs(result['logDirectory'])` 读取图文清单；每项保留完整文字，`image.path` 指向原 PNG。也可用 `dailo-dev logs D:/output/logs/请求ID` 离线查看，无需启动服务或重新连接设备。自然结束、脚本失败和取消回执均保存 `execution.json`（stdout、stderr、错误栈及日志路径）。日志清单与 PNG 不依赖终态回执；断线的 `interruption.json` 同样给出路径，仅标记结果未确认。只保证已经落盘的图文，连接失效时未交付的帧不能补造。
+
+Python执行超时后发送停止请求，保留原响应并最多等待30秒完成清理；返回的stdout、stderr、错误栈与图文保存到该请求目录的`execution.json`。停止未响应时关闭旧通道，下一次重新连接；不能把发送停止当作运行已退出。
+
+CLI外层HTTP预算为设备预算+30秒停止收尾+10秒传输余量。升级Playwright后重新运行`dailo-dev install`；安装和服务使用同一个`PLAYWRIGHT_BROWSERS_PATH`，可指定共享目录，避免Store内外缓存视图不同。
+
+`exec --code` 与 `exec --file` 均自动上传仓库 Python 模块和 `assets/`，可使用 `--config`、`--assets`。内联代码默认属于当前目录，也可用 `--directory` 指定。复用仓库的设备工作目录，下载和写入的文件会保留；每次运行刷新源码导入和字节码，停止后重跑也生效，并移除已删除的模块、资源。
+
+请求按16KiB分片发送，缓冲超过64KiB时等待通道释放，避免多图或大资源堵满发送队列。发送超时或失败关闭旧通道，Python结果记为未确认；下一次调用重新准入，不重放请求。
+
+相同资源不重写，更新资源先移除旧文件，避免破坏已加载原生库的内存映射。原生库内容更新后需重启设备上的 Dailo 应用再运行。
+
+信令断开时立即关闭旧DataChannel，并保存请求目录的interruption.json，标记结果未确认。status的activeRun为空仅表示宿主已结束等待，不能作为原设备线程已退出或脚本成功的依据。

dailo_devtools-0.1.0/src/dailo_devtools.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/dailo_devtools/__init__.py
+src/dailo_devtools/cli.py
+src/dailo_devtools/device.py
+src/dailo_devtools/py.typed
+src/dailo_devtools.egg-info/PKG-INFO
+src/dailo_devtools.egg-info/SOURCES.txt
+src/dailo_devtools.egg-info/dependency_links.txt
+src/dailo_devtools.egg-info/entry_points.txt
+src/dailo_devtools.egg-info/requires.txt
+src/dailo_devtools.egg-info/top_level.txt

dailo_devtools-0.1.0/src/dailo_devtools.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

dailo_devtools-0.1.0/src/dailo_devtools.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dailo-dev = dailo_devtools.cli:main

dailo_devtools-0.1.0/src/dailo_devtools.egg-info/requires.txt

@@ -0,0 +1,2 @@
+playwright<2,>=1.58
+aiohttp<4,>=3.14

dailo_devtools-0.1.0/src/dailo_devtools.egg-info/top_level.txt

@@ -0,0 +1 @@
+dailo_devtools