设备端性能工件可靠导出：断点续传、哈希、manifest 与失败恢复

摘要：测试结束后"adb pull 一下"在小文件上够用，但面对数 GB Trace、截帧和多个设备时，会遇到传输中断、半文件、重名覆盖和设备空间耗尽。本文设计可靠导出协议，让每个工件从设备生成到主机归档都有明确状态和完整性证据。

一、导出状态机

text 复制代码

DISCOVER → STABLE → HASHED → TRANSFERRING → VERIFYING → COMMITTED
                ↘             ↘               ↘
                 RETRYABLE ← FAILED        QUARANTINED

只有设备端文件大小在连续检查中稳定、写入句柄已关闭，才允许传输。

二、设备端 manifest

json 复制代码

{
  "run_id": "run-demo-42",
  "artifacts": [
    {"name": "timeline.trace", "bytes": 183500800,
     "sha256": "...", "role": "system_trace"}
  ],
  "complete": true
}

路径使用任务根目录下相对路径，拒绝 .. 和绝对路径。

三、两阶段提交

主机先下载到 .partial，验证大小和哈希后原子改名为正式文件，再写主机 manifest。分析系统只消费 COMMITTED 工件。

四、断点续传

对于支持范围读取的通道，记录已确认偏移和分块哈希；恢复时先验证最后一个块，避免设备文件在重试期间被替换。若设备端哈希变化，放弃续传并创建新 artifact_id。

五、并发与背压

同时拉取多个大文件会占满 USB、网络和磁盘 I/O。调度器按设备、主机和目标盘设置并发与速率限制，优先传输摘要和崩溃证据，大型健康 Trace 可以延后。

六、设备空间保护

传输成功并确认主机归档后，设备端文件进入可清理队列。清理前再次核对 run_id、允许根目录和已提交哈希。传输失败时根据剩余空间决定保留、压缩或停止新采集。

七、错误分类

text 复制代码

SOURCE_STILL_WRITING
SOURCE_CHANGED
TRANSPORT_INTERRUPTED
HOST_NO_SPACE
HASH_MISMATCH
UNSAFE_PATH
COMMIT_FAILED

哈希不一致不能自动覆盖重试结果，应隔离两份候选并调查源文件是否仍在变化。

八、安全与脱敏

传输允许列表按工件角色配置，不允许打包整个应用目录。日志屏蔽设备 UUID、账号和真实路径；公开文章不附原始工件。

结语

可靠导出的核心是"生成完成、传输完整、身份未变、归档已提交"四个条件。状态机、分块校验、两阶段提交和安全清理让大工件不会因一次中断变成无法察觉的半份证据。