cmautobuy/docs/task/149-内置并统一使用项目ADB.md

149 Client：内置指定 ADB 并统一运行路径和缺失提示

• 类型：需求
• 父级大工单：#1
• 所属 MVP / 版本：#2 / Client 可运行任务闭环
• 状态：已完成，待用户验收
• 日期：2026-08-11
• Gitea 工单：#149

背景与目标

Client 原来直接执行系统 Path 中的 adb，开发机和发布电脑可能使用不同版本或找不到命令。本任务把用户指定的 ADB 和两个配套 DLL 纳入项目，后续直接 ADB 与 uiautomator2 都使用同一项目文件；文件缺失时中断设备操作并弹窗提示。

最终方案

• 从 D:\Portable\adb 复制 adb.exe、AdbWinApi.dll、AdbWinUsbApi.dll 到 client/vendor/android-platform-tools/windows/，记录版本 1.0.32 和三个 SHA-256。
• 增加 adb_runtime.py，通过 app_dir() 返回源码或 PyInstaller 资源目录中的绝对路径，统一检查三个文件。
• 直接 subprocess ADB 命令全部使用绝对路径；设置 ADBUTILS_ADB_PATH，强制 adbutils/uiautomator2 使用同一文件，不回退系统 Path。
• 启动时发现文件缺失，在主窗口中央显示只有明显“知道了”按钮的中文弹窗；设置页禁用依赖 ADB 的设备命令，不自动恢复已保存设备。
• 打包脚本显式收集并逐个验证三个文件；诊断工具也改用统一路径。

改了哪些

• client/vendor/android-platform-tools/windows/：内置 ADB、DLL 和版本哈希说明。
• client/src/adb_runtime.py、client/src/db.py：统一只读资源路径与完整性检查。
• client/src/android_device_service.py：全部命令改用项目 ADB 绝对路径。
• client/src/pdd_device_service.py：uiautomator2 连接前固定 adbutils 的 ADB 路径。
• client/src/settings_ui_event.py、client/src/ui_main.py：缺失时禁用设备命令并显示启动弹窗。
• client/packaging/build.ps1：收集并检查三个文件。
• client/tools/、client/test/：统一诊断路径并增加回归测试。
• docs/client/：更新上手、发布结构和界面规则。

验收结果

验收标准	结果
项目只复制三个必要 ADB 运行文件	通过
生产 ADB 子进程使用项目绝对路径	通过
清空 Path 后仍解析项目 ADB	通过
adbutils/uiautomator2 固定使用同一项目 ADB	通过
打包脚本收集并检查 ADB 和两个 DLL	通过
实际发布包包含三个同哈希文件	通过
文件缺失时弹窗并禁用设备命令	通过（自动化测试）
缺失时不回退系统 Path	通过
USB/Wi-Fi 真机操作	未验证

测试

• 执行的命令：
  • C:/Python310/python.exe -m py_compile src/adb_runtime.py src/db.py src/android_device_service.py src/pdd_device_service.py src/settings_ui_event.py src/ui_main.py tools/measure_goods_open.py tools/test_pdd_home_deeplink.py
  • C:/Python310/python.exe -m unittest discover -s test -p "test_adb_runtime.py"
  • C:/Python310/python.exe -m unittest discover -s test -p "test_android_device_service.py"
  • C:/Python310/python.exe -m unittest discover -s test -p "test_pdd_device_service.py"
  • C:/Python310/python.exe -m unittest discover -s test -p "test_pdd_home_deeplink.py"
  • C:/Python310/python.exe -m unittest discover -s test -p "test_packaging.py"
  • $env:QT_QPA_PLATFORM='offscreen'; C:/Python310/python.exe -m unittest discover -s test -p "test_settings_ui_event.py"; C:/Python310/python.exe -m unittest discover -s test -p "test_pdd_ui_event.py"
  • 清空测试进程 Path 后调用 configure_bundled_adb_environment() 并核对 adbutils.adb_path()。
  • powershell -ExecutionPolicy Bypass -File packaging/build.ps1 -SkipInstall
• 结果：相关测试共 144 项全部通过，语法检查和 0.1.0 实际打包通过；发布目录中三个文件哈希与来源一致。PyInstaller 输出已有的 uiautomator2 扩展和 sip 收集警告，但构建成功。
• 没验证到的部分：没有运行项目 ADB 的 devices、USB 转 Wi-Fi 或 uiautomator2 真机连接，避免重启当前 ADB Server 后让已连接的 Wi-Fi 设备临时掉线；没有人工删除打包文件观察真实弹窗外观。

遗留问题

• 用户指定 ADB 为较旧的 1.0.32。若新 Android 设备出现兼容问题，应整体升级三个文件并重新验证，不能临时回退系统 Path。

相关提交

• 8f2037d feat: 内置并统一使用项目 ADB (#149)