vphone-cli vphoned 协议设计length-prefixed JSON 帧完整详解Host 与 iOS 虚拟机的通信秘密【免费下载链接】vphone-cli项目地址: https://gitcode.com/GitHub_Trending/vp/vphone-cli在 vphone-cli 项目中主机macOS与虚拟机内的 iOS 系统需要一条可靠的命令管道注入按键、模拟触摸、读写文件、管理钥匙串……这些能力全部由运行在 iOS 虚拟机内部的守护进程vphoned完成而两者之间的通信规范就是本文的主角——vphone-control 协议基于 vsock 的 length-prefixed JSON 帧。这套协议用极简的4 字节长度头 UTF-8 JSON 载荷设计同时解决了流式字节流的帧边界、请求-响应匹配和大文件传输等难题是理解整个项目的关键一环。vphoned 是什么连接 Host 与 Guest 的桥梁vphoned是 vphone-cli 的VM guest agent它以 LaunchDaemon 形式常驻在 iOS 虚拟机内部见 vphoned.plist 中的com.vphone.vphonedRunAtLoadKeepAlive保证开机自启与崩溃自愈。它做的事情很简单在虚拟机的vsock 1337 端口上监听等待主机的连接。vsockVirtual Socket是虚拟化环境专用的套接字地址族天然打通了 Host 与 Guest无需配置 IP 路由。主机端则由 VPhoneControl.swift 作为客户端通过 Apple 的VZVirtioSocketDevice发起连接。一次典型交互你在 macOS 的 App 里点击安装 IPA → 主机序列化一条 JSON 命令 → 打上长度头写入 vsock → vphoned 收到后解析执行 → 把结果 JSON 写回。整条链路只依赖一个帧格式约定。帧结构三要素为什么必须length-prefixedvsock 是字节流协议就像 TCP你写入两条消息接收端可能一次读到、也可能被拆成三次。没有帧边界就无法知道一条消息从哪里开始、到哪里结束。vphone-control 的解决方案是经典的长度前缀分帧定义在 vphoned_protocol.h 的文件头注释里每条消息 [uint32 big-endian length][UTF-8 JSON payload]组成部分大小说明长度头4 字节载荷字节数大端序跨平台安全JSON 载荷N 字节完整 JSON 字典N 长度头值三个设计细节值得新手注意大端序使用htonl/ntohl显式转换见 vphoned_protocol.m 第 37、54 行无论两端字节序如何解读结果一致。长度上限 4MBvp_read_message中直接拒绝length 0 || length 4 * 1024 * 1024的帧防止损坏或恶意的长度头导致分配巨大内存。完全读写vp_read_fully/vp_write_fully循环调用read/write直到凑足指定字节数。字节流上单次read可能只返回一半数据这个读满/写满模式是任何自定义二进制协议的地基。消息的 3 个核心字段v、t、id每条 JSON 消息只约定了三个协议字段其余字段都是业务参数vversion协议版本号当前为1PROTOCOL_VERSION。握手时双方必须版本一致否则拒绝连接。ttype消息类型如hello、ping、hid、touch、file_get……分发全靠它。idrequest id可选的请求编号响应必须原样带回。这是请求-响应模型的关键。vphoned_protocol.m 中的vp_make_response展示了标准响应模板r[v] PROTOCOL_VERSION; r[t] type; // 如 ok / err / pong r[id] reqId; // 回显请求 ID握手流程hello 之后才能干活连接建立后主机发送第一条hello消息这是整个会话的门禁{v: 1, t: hello, bin_hash: 3f9a...}vphoned 在 vphoned.m 的handle_client中依次校验类型检查首条消息不是hello直接断开版本检查v ! 1则回复version mismatch并关闭连接哈希比对主机附带自身 vphoned 二进制的 SHA-256bin_hash与 Guest 内运行副本比对——不一致就触发自动更新后文详述。校验通过后vphoned 回复一份自我介绍包含能力清单caps{v:1, t:hello, name:vphoned, caps:[hid,devmode,file,keychain,location,ipa_install,url,settings,touch], ios:18.6.2, ip:172.x.x.x}能力清单是协议扩展性的核心新能力先由 Guest 上报主机端检查guestCaps后才决定是否发送对应命令。比如 iOS 26 以下的系统会启用 guest 侧触摸注入useGuestTouchInjection正是靠touch能力和ios版本字段联合判断的。命令分发与请求-响应模型握手完成后进入命令循环。vphoned 按t字段前缀分发到各功能模块前缀 / 类型功能实现模块hid/touch按键注入、触摸注入vphoned_hid.hdevmode开发者模式查询与启用vphoned_devmode.hfile_*列目录/上传/下载/删除vphoned_files.hkeychain_*钥匙串读取与写入vphoned_keychain.hclipboard_*剪贴板同步含图片vphoned_clipboard.happ_*应用列表/启动/终止vphoned_apps.hsettings_*/open_url/location系统设置、URL 打开、定位模拟vphoned_settings.h 等请求 ID 让并发成为可能。主机端为每条请求分配自增的十六进制 ID并把待处理请求挂进pendingRequests表后台读循环收到响应时按id取出对应的 continuation 回调见 VPhoneControl.swift 中addPending/removePending。响应乱序到达也不影响正确性。超时分级体现工程细节普通请求 10 秒devmode、file_list、keychain_list等慢操作 30 秒文件传输类file_get/file_put/ipa_install放宽到 180 秒。大文件怎么办JSON 之后的裸数据追加JSON 不适合装二进制Base64 会膨胀 33%。协议的第二个关键设计是混合帧先按正常格式发送一条 JSON 头声明大小{t:file_put, path:..., size:N}紧接着在同一连接上裸写 N 字节二进制数据不套任何长度头对端按 JSON 里声明的size精确消费完这些字节再继续读下一帧。update守护进程自更新、file_put/file_get文件传输、clipboard_set图片剪贴板都遵循这个模式。对端的读满 N 字节消费方式保证了字节流永不失步——这也是vp_drainvphoned_protocol.h 中专门提供的按大小丢弃字节工具函数存在的原因一旦某帧出错把已声明的数据量完整丢掉协议才能重新对齐。自动更新协议自带的OTAhello里的bin_hash比对失败时vphoned 在响应中标记need_update: true。主机随即推送完整的新二进制update帧 裸数据vphoned 将其原子写入/var/root/Library/Caches/vphoned后退出由 launchd 拉起主启动逻辑发现缓存副本存在就exec它。整个闭环完全由协议字段驱动无需额外基础设施。稳定性设计断线重连与错误语义重连主机端检测到连接丢失后 3 秒自动重连reconnectDelay握手超时 8 秒重连时重新上报bin_hash等于顺便完成一次更新检查。错误语义统一所有失败都走{t:err,msg:...}msg携带人可读原因如unknown type: xxx、XPC not available主机端直接转成ControlError.guestError抛出。fire-and-forget 兼容像hid、touch这类高频命令走同步写后不等路径查询类命令走异步sendRequest。两种风格共用一套帧格式。小结一个小而完整的协议范本vphone-control 协议总共只回答四个问题怎么分帧长度前缀、怎么识别v/t/id 三字段、怎么传大块数据JSON 头 裸数据追加、怎么演进版本号 能力清单。理解这套 length-prefixed JSON 帧设计不仅读懂了 vphoned也拿到了一个可以套用到任何Host ↔ Guest、App ↔ Daemon自定义通信用途的设计模板。 核心源码索引协议定义帧格式scripts/vphoned/vphoned_protocol.h、scripts/vphoned/vphoned_protocol.mGuest 端主逻辑监听、握手、分发、自更新scripts/vphoned/vphoned.mHost 端客户端连接、请求匹配、超时、重连sources/vphone-cli/VPhoneControl.swiftLaunchDaemon 注册scripts/vphoned/vphoned.plist【免费下载链接】vphone-cli项目地址: https://gitcode.com/GitHub_Trending/vp/vphone-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考