cmbuyer/docs/tasks/T-101.md

---
id: T-101
title: 验证 ADB 与 uiautomator2 双通道连接
phase: 1
deps: [T-002]
status: DONE
created: 2026-08-03
vikunja_task_id: 21
context_ref: 87591e8
work_branch: task/t-101-device-connectivity
needs_device: true
needs_human_review: true
write_paths:
  - docs/tasks/T-101.md
  - client/.gitignore
  - client/requirements.txt
  - client/src/cmbuyer_client/device/**
  - client/tests/device/**
  - client/scripts/capture_device_baseline.py
  - docs/evidence/T-101/**
  - docs/04-architecture.md
  - docs/03-tech-stack.md
  - docs/current-state.md
---

<!-- BEGIN VIKUNJA EXPORT id=21 synced=2026-08-04T01:02:36Z sha256=b6458effd879f2e258c861b1b7b99d1162fdbea586e3fa467d3a65178c900453 -->
## 问题 / 背景

T-002 已建立采购工具骨架，但本项目还没有对实际 Android 手机、ADB 通道或 uiautomator2 做过取证。后续所有拼多多页面判据都依赖稳定、显式且可审计的设备连接；若复用前序项目结论或自动猜设备，会把错误设备和旧页面事实带入生产流程。

## 关联需求与交互

- 功能：Phase 1 真机环境盘点，是 T-102/T-103 的前置。
- 用户故事 / 交互：采购工具配置页的显式设备 serial、连接检查与错误反馈。
- 架构 / API：只验证 ADB/uiautomator2 基础能力，不编写拼多多页面判据，不调用采购服务业务接口。

## 方案

1. 实现显式 serial 的设备连接边界与可替换命令执行器；禁止留空自动选择，离线测试覆盖无设备、多设备、unauthorized/offline 和同一手机 USB+WiFi 双通道冲突。
2. 提供只读取证命令：对指定通道连接 uiautomator2，获取设备型号/Android 版本/拼多多 App 版本，执行截图与 dump_hierarchy(compressed=False)，所有超时可配置。
3. 产物按稳定目录保存并记录 SHA-256；日志只记录设备标识与元数据，不记录 token、地址、手机号或页面全文。
4. 先完成 mock/fixture 离线测试；随后由人分别用 USB 与 WiFi 真机执行并把设备、Android、拼多多版本、截图/XML 路径和结论写入任务执行记录。
5. 同一手机两个通道同时在线必须明确拒绝，不能随机选一个继续。

## 验收要点

- USB 和 WiFi 均能显式指定并完成截图、compressed=False XML dump。
- 设备未授权、离线、超时、serial 不存在和双通道冲突有可区分错误。
- 取证记录含设备型号、Android 版本、拼多多 App 版本、通道、时间、截图/XML 路径及 SHA-256。
- 离线单测与 compileall 通过，不要求真机。
- needs_device=true：agent 完成代码后保持 DOING，只有人完成两通道真机验收后才能 DONE。

## 执行记录

### 2026-08-03T10:56:19Z · ila

T-101 已领取，Git 状态将提交为 DOING。只读环境盘点：adb 位于 D:\Portable\adb\adb.exe；当前同时列出 WiFi serial 192.168.0.173:5555 与 USB serial 3B65BD02H7F00000，二者 product/model/device 均为 PKG110/PKG110/OP5D2BL1。该现场必须由实现识别为同机双通道并 fail closed。尚未截图、dump 或操作手机，本记录不是人工真机验收；needs_device 规则继续生效。

### 2026-08-03T11:27:08Z · ila

2026-08-03 离线实现与主审完成：新增显式 serial 的 ADB 边界、USB/WiFi 同机多通道 fail-closed、禁止 uiautomator2 隐式重连的连接器，以及只读基线 CLI（型号、Android、拼多多版本、截图、compressed=false XML、manifest SHA-256）。主 agent 三轮审查后补齐：截图/XML JSON-RPC 可配置超时、adbutils/uiautomator2 类型化超时、完整硬件身份集合比对、非法截图/XML fail-closed、异常脱敏、暂存清理，以及人工安全页面/原始证据不入 Git 的操作要求。独立验证：init.ps1 通过；admin go test/vet/build 通过；client 27 项 mock 单测、compileall、wheel METADATA、validator、bash -n 与 diff check 通过。未连接或操作真机，T-101 继续保持 DOING；等待人分别完成 USB 与 WiFi 取证并记录 manifest 中的设备型号、Android、拼多多版本、路径与 SHA-256。已知边界：ADB/ADB socket/截图与节点树 RPC 超时可配置，uiautomator2 初始化仍受上游固定启动上限约束。

### 2026-08-04T00:36:03Z · ila

2026-08-04 人工进展：用户确认 WiFi ADB 已连接，serial 为 192.168.0.173:5555。主 agent 随后仅执行 `adb devices -l` 复核，WiFi 与 USB 3B65BD02H7F00000 当前均为 device，product/model/device 均显示 PKG110/PKG110/OP5D2BL1；本机尚无 `%LOCALAPPDATA%\cmbuyer\artifacts\T-101` 取证产物。该结果只证明 WiFi 通道在线，不是 T-101 完整人工验收。按 fail-closed 边界，人工进行 WiFi 取证前须先断开 USB，只保留 WiFi；USB 取证时须断开 WiFi，只保留 USB。仍等待两次截图、compressed=false XML 与 manifest 路径/SHA-256，任务保持 DOING。

### 2026-08-04T00:43:38Z · ila

2026-08-04 人工 WiFi 取证失败：用户在仅 WiFi serial 192.168.0.173:5555 在线时运行基线 CLI，工具返回“截图 RPC 返回的数据不是有效图像，拒绝发布不完整取证”。主 agent 只读复核：ADB 仅列出该 WiFi 通道为 device，T-101 产物目录为空，说明暂存清理与 fail-closed 生效。核对本机 uiautomator2 3.7.0 源码后发现其高层 screenshot 使用允许 Base64 空白的 `base64.b64decode`，而当前实现直接 `validate=True`，可能错误拒绝真实 RPC 返回中的 CR/LF/空格。已退回 client agent 修复为“只规范化 ASCII Base64 空白，再严格 validate=True；其他非法字符与非图像继续拒绝”，并补回归测试。该失败不是验收通过，T-101 继续 DOING；修复、主审、提交后由人重新执行 WiFi 取证。

### 2026-08-04T00:49:31Z · ila

2026-08-04 WiFi 截图兼容性修复已完成主审：实现只删除 RPC Base64 返回值中的空格、TAB、CR、LF，再使用 `validate=True` 严格解码；非法字符、错误 padding、vertical-tab、form-feed、data URI 与解码后非图像仍 fail closed，不增加 adb screenshot fallback。错误安全地区分为“Base64 语法无效”和“图像数据无效”，均不输出原始内容，失败继续清理暂存目录。新增真实 PNG Base64 空白兼容、非法字符、错误 padding、未白名单空白及非图像测试；client 共 30 项离线测试。主 agent 独立复核并运行 client 测试/compileall、admin test/vet/build、完整 init.ps1、validator、bash 语法与 diff check，均通过；Python 3.12 和主工作区 3.14 均已验证。未由 agent 连接或截图真机，T-101 保持 DOING，等待人工重新执行 WiFi 取证确认现场问题是否解决。

### 2026-08-04T00:55:14Z · ila

2026-08-04 WiFi 人工取证技术验收通过：用户报告基线命令成功，manifest 位于 `%LOCALAPPDATA%\cmbuyer\artifacts\T-101\wifi-baseline\manifest.json`。主 agent 仅读取 manifest 元数据并计算文件哈希，未打开或展示截图/XML 内容。manifest schema=1、channel=wifi、设备型号 PKG110、Android 16、拼多多包 com.xunmeng.pinduoduo、版本 8.17.0；serial 仅保存 64 位 SHA-256。`screenshot.png` 存在，SHA-256=`8f86c94700d93380805b275469123a31749d592d99c0c4d2bcfd540784d1620b`；`hierarchy.xml` 存在，SHA-256=`708182200e25085c07cbb546c9b0adbc7310022bb75a7285c5581bd262661573`；两者均与 manifest 一致。仍等待人工确认原始截图/XML 不含敏感信息，并完成仅 USB 通道的同等取证；T-101 保持 DOING。

### 2026-08-04T01:02:03Z · ila

2026-08-04 USB 人工取证与隐私验收通过：用户报告仅 USB 通道基线命令成功，manifest 位于 `%LOCALAPPDATA%\cmbuyer\artifacts\T-101\usb-baseline\manifest.json`。主 agent 仅读取 manifest 元数据并计算哈希，未打开或展示截图/XML：schema=1、channel=usb、设备 PKG110、Android 16、拼多多 8.17.0；`screenshot.png` SHA-256=`da66e27ef6df1d4b99a64590e9aa383069c8c3995eb9b3695e5daec3a0e7bcf6`，`hierarchy.xml` SHA-256=`e0817f26c07e6861f2ab80052995aff2622ce7cdb61f18689d55c5591bb2045a`，均与 manifest 一致。用户随后明确确认 USB 与 WiFi 两组截图/XML 均不含地址、手机号、支付信息或其他无关隐私。至此 USB/WiFi 显式 serial、截图、compressed=false XML、设备/Android/拼多多版本、路径和 SHA-256 的人工验收全部满足；T-101 可关闭，后续进入 T-102。
<!-- END VIKUNJA EXPORT -->

## 边界

- 本任务只建立并验证设备连接、元数据读取、截图和 `dump_hierarchy(compressed=False)`；不打开
  拼多多商品、不编写任何页面判据，不选择规格，不进入购买或订单页面。
- 设备 serial 必须显式提供；无设备、多设备、未授权、离线或同一手机 USB + WiFi 双通道并存时
  必须明确失败，不得随机选择或静默降级。
- 不使用 `/mnt/d/chengma/cmroubao`、`/mnt/d/chengma/cmpdd` 的设备常量、页面 XML 或结论作为
  本项目事实；所有真机结论都必须在本项目重新取证。
- 产物与执行记录不得包含 token、地址、手机号、支付信息或无关页面全文；页面 XML 原始文件只
  保存于明确的 T-101 取证目录，日志只记录路径、哈希与非敏感元数据。
- 不修改 `admin/`、业务 API、数据模型或产品 UI，不实现任务领取、采购执行、下单、提交订单、
  付款或支付逻辑。
- `needs_device: true`：agent 完成代码和离线门禁后仍必须保持 `DOING`；只有人完成 USB、WiFi
  两通道真机验收并记录设备型号、Android 版本、拼多多 App 版本、截图/XML 路径后才能标 `DONE`。