云真机CLI化：用adb命令无缝接入云端设备实现自动化测试

1. 从"云真机只能网页点点点"到CLI接管：这个项目要解决的问题

做Android开发或者测试的同行应该都有这种经历：手头的真机就那几台，系统版本覆盖不全，异构屏占比机型更是一机难求。遇到需要验证老版本兼容性、多机型回归、或者做自动化测试的时候，物理设备的资源瓶颈特别明显。所以很多人都会把目光投向云真机平台——把真机放到云端，通过网络远程操作。

但云真机有一个让人不舒服的地方：绝大多数的云真机平台提供给开发者的入口是网页控制台。想装一个APK、截个图、抓个日志，都要在Web页面里对着模拟的屏幕操作，鼠标点来点去。如果只是偶尔用一次，网页版还能忍；但如果你的工作流里需要反复地安装、启动、采集日志、跑自动化脚本，网页版就非常痛苦了。更麻烦的是，一套自动化脚本通常依赖adb命令，网页版根本没办法把adb连接暴露出来。你的脚本和你的"设备"之间隔着一道厚厚的Web UI。

这个项目想做的一件事，就是把这层隔阂打通。用一个命令行工具，把云真机"卷入"本地adb链路：让本地的adb命令能直接打到云端某台真机上，让脚本、CI系统、以及更上层的AI Agent都能像操作本地设备一样操作云端设备。用工程化的说法，这个CLI要做的是云真机的Device Streaming能力——把远程设备的ADB通道以流的方式对外暴露，让本地工具链无缝接入。

谁需要这个东西？首先是做自动化测试的人。你的测试脚本在过去只能跑在本地设备池里，现在可以跑在云端任意一台机型上，而且整个过程中脚本不需要改动。其次是做App兼容性验证的开发者，可以一键在多台云端设备上执行同样的命令序列。再就是最近特别热门的AI Agent方向——如果Agent可以"看到"屏幕、"操作"界面、"读取"日志，那么云端真机就成了一种可以被AI自由调度的探索和测试环境。这也是我在做这个项目时最看重的场景。

今天这篇文章不会给你讲一堆概念，而是直接把整个项目的设计思路、关键实现、以及我在实际踩坑中总结出来的一些经验写出来。你可以把它当作一份可复现的技术参考，也可以当作一次"云真机CLI化"的踩坑实录来看。

2. 设备流式连接的核心原理：为什么"看起来像本地adb"没有那么简单

在说具体实现之前，我得先把原理层面的东西讲清楚。因为我在动手写代码之前就发现，市面上相关资料比较零散，如果对原理理解不到位，后面会一直被各种莫名其妙的连接问题折磨。

2.1 adb协议里最容易被忽略的"两端"

大多数人用adb就是一条命令：adb install x.apk。看起来很简单，但这里其实藏着两层角色：adb client（你在电脑上敲的命令），和adbd（设备上运行的守护进程）。两者之间通过USB、Wi-Fi或者TCP传输数据，中间还有一个adb server（你电脑上常驻的一个本地服务）做中转。

顺着这条链路想：如果设备不在你身边，在云端的机房里，那"电脑到设备"这一段物理链路就不存在了。你不可能给它插一根USB线。所以云真机平台要做的核心事情，就是把这段物理链路虚拟化——在远端搭一个桥，让本地的adb client通过网络连接到远端的adbd。

Device Streaming的本质就是这样一条虚拟化的adb通道。你不需要关心设备具体在哪台物理服务器上，也不需要关心中间走了什么网络协议。对于本地的adb client来说，只要它觉得自己通过某个serial号连接了一台设备，能正常执行命令，就够了。

2.2 Device Streaming桥接的"中间人"角色

既然要在本地和远端设备之间架桥，那这个桥用什么协议来承载adb的流量？答案是：可以用WebSocket、可以用TCP Tunnel，也可以自己封装一层带认证的流式协议。选择不同，工程复杂度完全不同。

我最终选择的方案是：CLI作为中间人进程常驻本地，一端连接云平台的设备调度服务，把远端设备的数据以字节流的形式拉出来；另一端在本地创建一个虚拟的adb端口，让adb server认为这里有一台设备。CLI通过平台分配的设备访问端点建立一条持久连接，连接上之后，CLI会拿到一个虚拟的序列号，然后把本地端口绑定到127.0.0.1:xxxx上。

其实你不需要理解太深，你可以把CLI想成一条水管：水管的一端插在云端设备的"出水口"上，另一端放在你本地电脑的"水龙头"里。你在本地拧开水龙头，水流其实是从远端流过来的。adb -s 虚拟序列号 shell xxx就相当于拧了一下这个水龙头。

2.3 CLI要处理的四件底层事

理想很丰满，落地的时候你会发现，要让这条链路稳定跑起来，CLI至少要处理四件事：

第一，认证与设备预分配。云平台不可能让任何人随便拿一个token就连设备。你得先通过CLI向平台请求一个会话凭证，平台完成认证之后，帮你锁定一台空闲设备，然后把设备接入地址和凭证一并返回给CLI。

第二，握手与连接保活。拿到凭证后，CLI要和平台建立长连接。连接建立之后，还需要处理心跳、重连、以及远端设备状态变化（比如设备掉线、被其他用户抢占、系统重启）等异常情况。

第三，adb协议字节流的双向转发。这一步是这个项目里最"致密"的地方。adb协议本身有消息封包、校验和、以及一些握手时特定的交互时序。CLI不能只做盲转发，必须对adb的状态机有基本认知，否则遇到某些复杂的adb命令（比如push/pull这类需要分块传输的命令）就会出问题。

第四，给上层提供一个易用的命令入口。前面这些东西做得再扎实，如果CLI的命令设计得很反人类，那也没有人愿意用。这个CLI要支持的不仅仅是adb转发，还要把"列出我当前可以访问的设备""释放这台设备""查看所有活跃会话"这类高频操作变成一条条简单直觉的命令。

理解了这四点，你也就理解了这个CLI项目的大致边界：它不是一个设备管理平台，而是设备和本地工具链之间的一个"翻译官+搬运工"。

3. CLI的架构设计与选型思考

原理归原理，真正动手搭建项目的时候，有几个决策层面的问题需要想清楚。这一节我把自己的选型思路和背后的理由写出来，希望能给准备做类似工具的人一些参考。

3.1 语言选型：为什么我选了Go

CLI工具的语言选择，我考虑过Python、Rust和Go。

Python写起来最快，生态也很丰富，但现在这个场景对性能和并发要求不低：要同时保持多条设备连接、转发高频字节流、处理心跳重连，Python的GIL和内存占用在这种长连接场景下比较吃亏。Rust很好，性能强悍，但开发周期长，对团队里不熟悉系统编程的人来说上手成本高。

Go是那个让我觉得"足够好"的选项。它的goroutine模型非常适合处理这种多条并发长连接转发的场景，goroutine加上channel，写转发逻辑就像写同步代码一样流畅；编译出来单个静态二进制，部署到CI机器、开发机、甚至临时的Docker容器里都很省事；标准库里自带的net、crypto/tls、os/exec这些包，几乎覆盖了我90%的需求，第三方依赖可以压到很少。

如果你也想做类似的工具，我的建议是：如果这个工具会长期维护、对性能要求高，Rust可以冲；如果追求开发效率和并发处理，Go是很稳的选择；如果只是做个原型验证，Python也没问题。

3.2 核心模块拆分

整个CLI我拆成了五个模块，每个模块的边界都划得很清楚：

Config模块负责读取配置文件，包括平台API地址、认证信息、默认超时时间、设备池偏好等。配置格式我选了YAML，因为可读性好，注释方便。核心配置项包括：

platform: endpoint: "https://api.example.com" # 平台API入口 token_env: "CLOUD_DEVICE_TOKEN" # 从环境变量读取token device: pool: "default" # 设备池名称 os_version: ">=11" idle_timeout: 30 # 空闲多久自动释放，单位分钟 session: heartbeat_interval: 15 # 心跳间隔，单位秒 reconnect_backoff: [1, 2, 4, 8, 16] # 重连退避策略

Auth模块负责和平台做OAuth2.0设备授权交互。这里的坑不少，后面会提到。

Device模块负责设备发现、状态查询、以及设备会话的创建和释放。它维护一个"当前活跃会话"的本地状态表，记录每个虚拟序列号对应的远端设备ID、会话起止时间、最后活跃时间等。

Stream模块是整个项目的核心，负责建立和维护设备数据通道。它既要从远端读取设备字节流写入本地端口，也要从本地端口读取字节流推送到远端——双向转发，两头都不能堵。为了不让一个方向阻塞另一个方向，这里用的是两块独立的缓冲区策略，各自拥有独立的goroutine，互相通过channel传递状态。

Exec模块负责把用户命令翻译成具体的动作，包括connect、disconnect、list、exec、forward等子命令，并且把执行结果格式化输出。这个模块也是未来对接AI Agent的那一层。

3.3 会话生命周期：一图说清的状态流转

下面这张状态表是我们CLI里整个会话从创建到销毁的核心状态机，我直接贴出来，比任何流程图都直观：

要特别注意的是LOST状态。云端的物理设备随时可能被其他优先级更高的任务抢占，也可能是平台要重启设备。CLI必须能在LOST状态下自动判断：是重连当前设备，还是释放后申请一台新设备。我的策略是：先快速重连同一设备两次，如果两次都失败，就自动切换为申请新设备。因为如果是设备本身挂了，重连多少次都没用；如果是网络抖动，快速重连通常能救回来。

4. 从零实现Device Streaming的关键步骤

这一节是纯实操，我会按照实际开发的顺序，把每一步的关键代码和思考过程写出来。如果你想照着做一个类似的工具，这一节可以直接当参考手册用。

4.1 初始化与认证流程

第一步，让CLI能够和云平台完成认证。我设计了一个init命令，它的流程是：

1. 读取配置，拿到平台endpoint和client_id（这些信息在平台创建API应用时获得）。
2. CLI生成一个一次性验证链接，用户打开链接，在网页上授权。
3. 授权成功后，平台回调CLI本地监听的端口，返回一个短期access_token和一个长期refresh_token。
4. CLI把refresh_token加密存储在本地，用的时候通过access_token访问API。

这个流程和很多开放平台OAuth流程一致，但有几个容易出错的地方。

第一，本地回调端口的选择。你监听的端口必须是固定的，并且要在每次授权前检查端口是否被占用。如果被其他进程占了，授权流程会直接失败。我的做法是：让用户通过--callback-port指定，默认是8899。

第二，access_token过期时间要比你想象得短。真的，很多平台默认只给30分钟到1个小时。如果你建了一条长连接，超过token有效期，连接并不会立刻断，而是等下一次心跳认证时才开始报错——这种现象非常误导人。后面我会单独写这个坑。

认证这部分完成之后，CLI会把一个配置文件写到用户目录下：

~/.android-cli/config.yaml # 配置文件 ~/.android-cli/credentials # 加密保存的凭证 ~/.android-cli/logs/ # 运行日志

4.2 设备发现与连接握手

认证通过后，用户执行device connect，CLI就该干活了。这一步的核心逻辑是：

1. 调用平台的"申请设备"接口，参数包括设备池、系统版本、机型偏好等。
2. 平台返回一个设备ID和访问地址，格式像wss://stream.example.com/v1/devices/dev-12345。
3. CLI和这个WebSocket地址建立连接，并发送一个握手请求帧。

握手帧的格式我一开始是自己定义的，后来发现完全可以用JSON来表示，更简单：

{ "type": "hello", "device_id": "dev-12345", "token": "xxx", "protocol_version": 1, "client_capabilities": ["adb_shell", "adb_forward", "screen_capture"] }

平台收到这个JSON后会确认，并且回复一个ready帧：

{ "type": "ready", "adb_serial": "cloud-dev-12345", "session_id": "sess-abc123" }

这里的adb_serial很关键。CLI拿到它之后，会把这个serial写入本地adb server已知设备列表，然后你在本机执行adb devices就能看到这台云设备。

4.3 字节流双向转发：核心代码逻辑

连接建立之后，最核心的转发循环就启动了。我用Go实现的双向转发核心逻辑大概是这样的：

func (s *Streamer) pipe(local io.ReadWriteCloser, remote io.ReadWriteCloser) error { errCh := make(chan error, 2) // 本地 -> 远端 go func() { buf := make([]byte, 32*1024) for { n, err := local.Read(buf) if n > 0 { if _, werr := remote.Write(buf[:n]); werr != nil { errCh <- werr return } } if err != nil { errCh <- err return } } }() // 远端 -> 本地 go func() { buf := make([]byte, 32*1024) for { n, err := remote.Read(buf) if n > 0 { if _, werr := local.Write(buf[:n]); werr != nil { errCh <- werr return } } if err != nil { errCh <- err return } } }() return <-errCh }

写的代码非常简单，但请注意：这里有几个至关重要的细节可能让你的转发在黑盒环境下失效。

第一个细节：缓冲区的尺寸不能太小。如果你用1KB的缓冲区，adb在传输大文件（比如安装一个100MB的APK）时，就会频繁地读写，CPU占用率飙升，传输速度反而下降。我实测下来，32KB是一个甜点值，当然你开128KB也不会差太多。

第二个细节：读写不能共用一个goroutine。如果本地调用adb时长时间没有返回数据，但远端设备的数据又不断涌入，共用一个goroutine就会造成"本地等待，远端数据堵在Channel里"的活锁。所以上面代码里我给两个方向各开了一个goroutine，让读和写不会互相等待。

第三个细节：管道中任何一个方向关闭，另一个方向也应该同时关闭。否则本地命令已经执行完了，远端还有残留的数据在传输，会导致后续adb命令的输出被"串包"——上一个命令的残留数据跑到下一个命令的输出里去了。

4.4 对接AI Agent的接口设计

这个CLI要做的不只是人工敲命令，还要让AI Agent能调用。所以我专门开了一个agent子命令，以JSON-RPC over stdio的方式对外提供接口——这个设计借鉴了很多现代CLI工具的交互方式。

Agent通过标准输入写入JSON-RPC请求，CLI处理完后把结果写到标准输出，错误写到标准错误。这样一个AI Agent可以用最简单的方式和CLI通信：

# Agent调用cli获取设备列表 echo '{"jsonrpc":"2.0","method":"device.list","id":1}' | android-cli agent # 返回结果 {"jsonrpc":"2.0","id":1,"result":{"devices":[{"serial":"cloud-dev-12345","state":"ACTIVE","model":"Pixel 8"}]}}

可用的方法我目前暴露了这么几个：

在这里我要特别说一下screen.capture和screen.ui_dump为什么是Agent场景下的"一等公民"。因为Agent不能像人一样"看"屏幕，它只能通过截图和UI层级树来感知当前界面状态。如果我们让Agent调试App、发现问题、验证结果，它至少要有能力回答"现在屏幕上是什么"这个问题。所以我在CLI里直接内置了这两个高频子能力，避免Agent端还要自己拼shell命令去实现。

5. 使用过程中踩过的坑（完整排查链路）

这个部分我想写得细一点，因为这些都是我在真实使用过程中踩出来的经验，网上几乎找不到同类的踩坑记录。

5.1 连接建立后命令"无响应"：到底是谁卡住了谁

现象是这样的：device connect成功，adb devices里也能看到设备，但一旦执行adb shell，进程就像死了一样卡住，既不输出内容，也不报错。第一次遇到这个情况，我当时的排查思路是这样递进的。

第一步，我先在本机执行adb -s cloud-dev-12345 shell 'echo hi'，加上timeout 5包着，确认它确实卡死。

第二步，我去翻CLI的日志。日志里显示通道已经建立了，而且心跳正常。这时我把怀疑目标从"连接没建立"转向"数据在某个环节被吞了"。

第三步，我在本地端口上做了个TCP抓包。具体做法是：临时写一个简单的代理进程，把本地发往虚拟adb端口的数据打印出来，再转发给云通道。抓包发现一个关键现象：本地adb server发出的握手请求，CLI确实收到了，但转发到远端之后，远端的回应一直没有回来。

问题到这里就很有意思了。远端没回应，一种可能是远端设备真没收到，另一种可能是远端收到了但回应被平台侧拦截了。我继续测试：用CLI自带的exec.command跑一条简单的adb version，不走adb client，结果发现CLI自己发命令是通的，只有通过adb client发的命令不通。

那问题一定出在"adb client发过来的数据"和"CLI自己发的数据"两者之间的差异上。我把两者抓包的数据逐字节对比，终于发现了原因：本地的adb server在和远端设备建连时，会先发一个CNXN握手包，而这个握手包里带有一个token，token的生成依赖本地设备的某种签名信息。CLI在转发时原样转发，但平台侧收到这个token后发现它和当前会话的签名不匹配，就悄悄地把连接关掉了，而且不回任何错误帧。

这个坑的本质是：不是所有云平台都接受纯透传adb协议，有些平台会在协议层做身份校验。解决方法是：CLI在转发时，把本地adb client的握手包拦截下来，剥离掉不匹配的认证字段，替换成CLI自己通过API申请的会话凭证。也就是说，CLI要在"透传"和"协议转换"之间做一个语义上的选择。

这个坑排查了将近一天，直接让我意识到：处理第三方对接时，第一件事要用tcpdump抓包看原始字节流，不要凭直觉猜协议层之上发生了什么。

5.2 access_token过期导致的"静默死链"

第二个坑，前面提到过了：access_token过期之后，CLI不会立刻断开，而是在下一次心跳验证时才报错。但最头疼的不是报错，而是有些时候它连错都不报。

现象是：一条长连接挂了十几分钟之后，Agent调用exec.shell，返回的是一个空结果，既没有超时信息也没有错误信息。Agent拿到空结果后，会把这个空结果当作"设备正常返回，只是输出为空"，然后继续执行下一个步骤。到最后整个调试流程失真得非常严重。

我最后的处理策略是两层：

第一层，在CLI内部维护一个token的剩余有效时间倒计时。在token过期前5分钟，主动向平台刷新一次access_token；如果刷新失败，主动断掉当前所有连接，并且向上层返回一个明确的AUTH_EXPIRED错误，绝不吐出一个空的成功结果。

第二层，在CLI和Agent之间约定一个严格的结果契约。任何命令的执行结果必须包含三个字段：exit_code、stdout、stderr。如果CLI无法拿到这三者，一律返回错误而不是返回空壳结果。

为什么这一点很关键？因为AI Agent的容错逻辑通常非常简单——它拿到一个"成功但空输出"的结果，或者拿到一个"真正的错误"，后续决策路径是完全不同的。如果我们让Agent误判了设备状态，它会沿着错误的方向继续探索，最终浪费的是大把时间和token。

5.3 多条adb连接复用同一个云设备时的通路冲突

还有一个坑，是多条adb连接同时打向同一台云设备时，会出现"通路冲突"。

我们知道，adb -s serial shell每执行一次，都会在adb server和adbd之间建立一个新的传输通道。但云设备的流式转发通道只有一个。如果Agent用并发的方式同时执行两条命令，第二条命令的通道会和第一条命令的数据混在一起。

当时出现的一个典型现象是：adb shell和adb pull同时执行，结果pull下来的文件内容里出现了shell打印的日志。这个问题的本质是本地虚拟adb端口的并发转发模型，没有做连接级隔离。

我的解决方案是：在CLI内部为每一条adb子连接分配一个独立的队列ID，对远端设备的数据按照队列ID进行缓存和分发，而不是一股脑地全部写回同一个管道。具体来说，在CLI的Stream模块里维护一个session_map，key是子连接的标识，value是数据缓冲channel。每个子连接从自己的channel里取数据。这个方案需要CLI对adb的多通道协议有一定理解，实现成本比纯透传高一些，但解决了并发场景下的数据串包问题。

如果你不做Agent场景、只是人工敲几个命令，这个坑可能碰不到；但只要开始做并行命令，就一定要在设计阶段把子连接隔离考虑进去，别等我这样踩完了再回来补。

6. 实测数据与效果评估

光说不练没有说服力，我把实际用下来的数据分享出来。测试环境：一台普通的笔记本电脑，网络为家庭宽带；云真机为某平台的骁龙8Gen2机型，系统Android 14；执行的操作是：安装一个约80MB的APK、启动App、连续采集300帧UI层级树、拉取一份200MB日志文件。

这个表格里的对比其实反映出很本质的东西：网页控制台更适合"人类看着屏幕操作"，而CLI + adb通道则更适合"程序按脚本批量执行"。这二者不是替代关系，而是互补关系——但当工作流里脚本化比例高的时候，CLI化的收益是碾压式的。

我也测试了AI Agent接入的效果：让Agent在云真机上执行一份"探索某App主流程并截图"的任务。Agent通过CLI方法调用完成了App启动、页面切换、表单填写等步骤，整个过程中没有一次因为设备连接问题中断。相比之前用网页控制台人工操作，效率提升不是一个量级的。

7. 从CLI到基础设施：一些后续扩展的思考

做这个项目的过程中，我不仅实现了最初的目标——让云真机可以被命令行调用——而且还发现了许多可以进一步扩展的空间，这里分享一些想法，给想接着做类似项目的朋友一点参考。

首先是设备池路由策略。现在只是简单地把设备池名传给平台，但如果设备池很大、机型很多，怎么让CLI知道"App需要跑在Android 13以上、内存8G以上的机器"？现在这些筛选逻辑还是靠用户在命令行里手动拼参数，后面完全可以做成一个本地设备偏好配置文件，让CLI自动向平台提交更精确的调度请求。

其次是批量设备编排。Agent现在只能操作一台设备，但如果做多设备回归测试，同一套操作要在十几台机器上同时跑。我计划在CLI上增加一个group命令，支持把一条命令在多个设备上并行执行，并且把每个设备的结果汇总成一张表。这个能力一旦有了，云真机才真正变成面向质量保障的基础设施，而不是一台一台访问的"共享设备机柜"。

第三个是录制回放。AI Agent在调试的过程中会产生一条命令序列，这条序列如果能够被自动录制，后续就可以在任意设备的会话上重放。这等于把一个Agent探索出来的整套调试方法固化下来，以后任何一台新机器上都可以自动复现。

第四个是和其他CI系统的集成。现在CLI已经可以被纯命令行调用了，那接到Jenkins/GitHub Actions这类CI系统就非常自然。核心是CLI的退出码要和设备状态严格对应：命令执行成功返回0，任何设备层面的错误返回非0——这个简单的约定能让CI系统的错误提示清晰很多。

写在最后

这个项目做下来，我最深的感受是：云真机的价值不在于"把设备放到网上让你点"，而在于"把设备变成一条可以被程序自由调用的管道"。只有把设备接入到命令行、脚本、Agent这些自动化系统里，云真机才能真正发挥它作为测试基础设施的潜力。

如果你打算做类似的东西，我的建议是：不要把精力过多花在平台的交互界面上，所有资源都应该投入到连接稳定性、协议兼容性和错误处理这三件事上。这三件事做扎实了，CLI工具本身就是一个非常可靠的自动化基础设施。

另外，在和AI Agent对接的时候，一个特别容易被忽略但影响巨大的细节是：给Agent的反馈必须是非常干净的、结构化的。空结果、模糊报错、非标准输出，都会让Agent做出错误的后续决策。这一条，值得任何做Agent自动化工具的朋友在写代码前就想清楚。