★ FEATURED ARTICLE 【免费下载链接】airsync-macAirSync macOS - Bring the forbidden macOS continuity to Android项目地址https://gitcode.com/gh_mirrors/ai/airsync-mac点击查看免费下载本文深入解析AirSync 协议基于一条 WebSocket 长连接与 23 种 JSON 消息类型带你从零构建自己的 AirSync 客户端——理解 Android 与 Mac 之间的通知镜像、文件传输、媒体控制等核心通信机制以及 AES-GCM 加密与心跳保活的完整实现。1. AirSync 是什么AirSync是一款开源的 macOS 应用目标是把 Apple Continuity接力 体验带到 Android 手机手机通知同步到 Mac 桌面、音乐状态镜像到控制中心、Mac 反向控制手机媒体、双端文件互传、剪贴板同步等。它的通信核心并不复杂Mac 端运行一个WebSocket Server基于 Swifter 库Android 端作为WebSocket Client主动连接所有业务数据都封装成统一的 JSON 消息走 AES-GCM 加密通道 如果你想在本地编译源码可以克隆仓库git clone https://gitcode.com/gh_mirrors/ai/airsync-mac2. 协议总览一条连接 一个信封整个协议可以浓缩成两句话连上ws://Mac的IP:6996/socket然后收发{type: 消息类型, data: {...}}这样的 JSON 信封。关键参数值说明默认端口6996定义于 Constants.swift可在设置页修改WebSocket 端点/socket注册于 WebSocketServer.swift消息信封{type: ..., data: {...}}全部消息的统一结构传输加密AES-GCM (256-bit)密文 Base64 后作为文本帧发送心跳间隔4.5 秒无活动 20 秒判定会话失效消息信封由两个字段组成类型枚举完整定义在 Message.swiftdata字段采用万能解码器策略见 AnyDecodable.swift允许各消息类型自由携带不同结构的 JSON 对象{ type: status, data: { battery: { level: 87, isCharging: true }, isPaired: true } }3. 第一步发现 MacBonjour 广播你的客户端首先需要找到Mac。AirSync 使用BonjourmDNS做局域网服务发现实现在 BonjourServiceAdvertiser.swift发现项内容服务类型_airsync._tcp服务名AirSync-设备名TXT 记录id稳定 UUID、name、port、ver在 macOS 或任意支持 mDNS 浏览的工具中搜索_airsync._tcp即可定位到 Mac 的 IP 与端口随后直接发起 WebSocket 连接。此外项目还内置了 UDP 广播UdpBroadcastDiscovery.swift作为补充发现手段。4. 握手device与macInfo消息对连接建立后第一条消息必须是device类型的手shake完成设备注册。核心字段如下{ type: device, data: { name: Pixel 9, id: 12345abc, ipAddress: 192.168.1.50, port: 8765, version: 2.0.0, adbPorts: [5555], wallpaper: base64..., bleAuthToken: token..., targetIpAddress: 192.168.1.20 } }Mac 收到后会回一条macInfo消息携带 Mac 的名称、机型modelIdentifier、版本、是否 Plus 订阅以及已保存的 Android 应用包列表见 WebSocketServerHandlers.swift。⚠️主会话机制Mac 只把第一个连接视为primarySession除device外的所有消息只接受来自主会话WebSocketServerHandlers.swift。若新的本地网段会话192.168./10./172.16-31发起握手会强制接管并断开旧会话——这是为了局域网优先的稳定性设计。5. 23 种 JSON 消息类型全解当前源码的MessageType枚举共定义了 31 个值其中消息路由器主动分发处理 23 种handleMessage 的 switch 分支其余 8 种主要是 Mac 主动发给 Android 的出站类型。按功能分组如下 连接与状态3 种类型方向核心 data 字段deviceAndroid→Macname / id / ipAddress / port / version / wallpaperstatus双向battery / isPaired / music播放状态、专辑封面、进度userDisconnectedAndroid→Mac用户主动断开前发送Mac 据此走手动断开流程 通知镜像5 种类型方向作用notificationAndroid→Mac推送通知id / title / body / app / package / priority / actions / progress / ongoingnotificationActionMac→Android在 Mac 上点通知按钮转发操作如回复notificationActionResponseAndroid→Mac操作执行结果id / action / successnotificationUpdateAndroid→Mac通知内容更新或消失actiondismissdismissalResponseAndroid→Mac取消通知的结果回执 媒体与通话7 种类型方向作用macMediaControlAndroid→Mac用 Android 控制 Mac 的音乐play / pause / next / previous / stop / playPausemacMediaControlResponseMac→AndroidMac 侧执行结果回执mediaControlResponseAndroid→MacAndroid 侧媒体操作结果回执callEventAndroid→Mac来电/去电事件eventId / number / direction / state / contactNamecallProgressAndroid→Mac通话中进度更新如振铃转接通callControlMac→AndroidMac 上接听/挂断accept / decline / endcallControlResponseAndroid→Mac通话控制结果action / success / message 应用与剪贴板2 种类型方向作用appIconsAndroid→Mac同步应用列表{包名: {name, icon(base64), systemApp, listening}}Mac 会落盘缓存图标clipboardUpdateAndroid→Mac剪贴板文本同步text 字段 文件传输6 种类型方向作用fileTransferInit双向开始传输id / name / size / mime / chunkSize / checksum / isClipboardfileChunk双向数据分片id / index / chunk(base64)fileChunkAck双向分片确认id / indexfileTransferComplete双向传输结束触发大小与 SHA256 校验transferVerifiedAndroid→Mac接收方校验结果verified 布尔值fileTransferCancel双向取消本次传输id消息模板的构造逻辑集中在 FileTransferProtocol.swift。️ 远程控制与文件浏览6 种类型方向作用remoteControlAndroid→Mac用 Android 遥控 Mac键盘keypress / type、鼠标mouse_move / mouse_click / mouse_scroll、音量、锁屏、屏保、亮度等 20 动作browseLsMac→Android请求列出 Android 目录path / showHiddenbrowseDataAndroid→Mac返回目录项列表items: [{name, isDir, size, time}]出错时返回errorremoteControl的完整动作表可参考 handleRemoteControl。 其余 8 种Mac 出站的另一半协议枚举中剩余的值——macInfo、volumeControl、macVolume、toggleAppNotif、wakeUpRequest、macMediaControlResponse等——主要由 Mac 发出如volumeControl让 Android 调音量、browseLs拉取目录以及少量双向复用类型。客户端实现时只需把 Mac 端 WebSocketServerOutgoing.swift 里的sendMessage调用当作待实现消息清单逐一对照即可。6. 加密层AES-GCM 如何工作协议的所有消息默认经过AES-GCM 256-bit加密CryptoUtil.swiftMac 首次启动时随机生成 256-bit 密钥Base64 后持久化保存发送时AES.GCM.seal→ 得到nonce(12B) 密文 tag(16B)的组合字节 → Base64 → 作为文本帧发送接收时Base64 解码 →AES.GCM.open还原出 JSON 明文调试技巧Mac 端在未加载密钥时会以明文收发消息WebSocketServer.swift开发阶段可以先用明文打通流程再接加密。7. 心跳机制4.5 秒 Ping20 秒超时保活逻辑在 WebSocketServerPing.swiftMac 每4.5 秒发送{type:ping,data:{}}客户端应回一条{type:status,data:{type:pong}}Mac 收到后直接忽略但任何入站文本帧都会刷新活跃时间戳超过12 秒无活动 → 标记弱连接UI 提示超过20 秒无活动 → 判定会话失效自动重启服务并重新广播 Bonjour 发现Android 会重新发现并连接这意味着你的客户端只要定期说话哪怕回一个空消息连接就能一直保持。8. 文件传输协议滑动窗口 校验文件传输是协议中最精巧的部分sendFile流程为Init(id, name, size, mime, chunkSize, checksum) → Chunk(index 0) → Ack(0) → Chunk(index 1) → Ack(1) ← 滑动窗口大小 8 → ... → Complete(id, size, checksum) → Verified(id, verified: true)参数默认值说明chunkSize64 KB每个分片的字节数窗口大小8最多 8 个分片在途收到 Ack 后推进Ack 超时2000 ms超时重发最多重试 3 次完整性SHA256Complete 时校验落盘到 Downloads 并自动去重重命名接收端Mac 侧按index * chunkSize偏移写入临时文件handleFileChunk所以分片乱序到达也没关系。9. 从零构建你的客户端5 步清单✅第 1 步建立连接通过 Bonjour 找到_airsync._tcp服务连接ws://IP:6996/socket✅第 2 步完成握手发送device消息name / id / ipAddress / port 必填等待macInfo回复✅第 3 步保持心跳收到ping后回status/pong并每几秒主动推送一次status电量 音乐状态✅第 4 步订阅核心事件处理notification渲染通知卡片、callEvent来电弹窗、appIcons应用网格✅第 5 步实现文件传输按 Init → Chunk/Ack → Complete → Verified 四步状态机收发文件记得做 SHA256 校验一个最简的能跑起来的客户端实际上只需要正确处理device、status、ping三类消息Mac 端就会认为配对成功并进入主页。10. 常见坑与调试建议坑原因与解决消息发了没反应你不在主会话上——非 primary 会话除device外的消息一律被丢弃先确认连接顺序数字精度丢失JSON 数字可能被解析为 Int/Double 混排如音乐的 duration/position 以毫秒计的整型建议按数值统一处理进度条漂移status.music.position是快照值协议携带positionTimestamp做类 NTP 的时间补偿播放中应自行累加连接突然重启Mac 检测到 IP 变化切换 WiFi/热点会 5 秒后重启服务并刷新二维码客户端要能自动重连大文件传输卡住确认按 index 顺序推进窗口、及时回 Ack2 秒超时会触发重发11. 源码文件速查模块路径消息类型枚举与信封定义Message.swiftWebSocket 服务主体路由/密钥/重启WebSocketServer.swift23 种消息的分发处理WebSocketServerHandlers.swift出站消息与文件发送WebSocketServerOutgoing.swiftPing 心跳与超时WebSocketServerPing.swift网络适配与 IP 变更监控WebSocketServerNetworking.swiftAES-GCM 加解密CryptoUtil.swift文件传输消息模板FileTransferProtocol.swiftBonjour 服务广播BonjourServiceAdvertiser.swift默认端口等常量Constants.swift结语AirSync 协议的精髓在于简单一条 WebSocket、一种 JSON 信封、23 种主动处理的消息类型、一套 AES-GCM 加密和 4.5 秒心跳就支撑起了通知镜像、来电提醒、文件互传、远程桌面控制等完整的跨设备体验。理解了device握手、status心跳与文件四步状态机这三块骨架你的自定义客户端就已经具备接入 AirSync 生态的全部能力——剩下的只是挑你想要的那些消息类型去实现而已。赞分享【免费下载链接】airsync-macAirSync macOS - Bring the forbidden macOS continuity to Android项目地址https://gitcode.com/gh_mirrors/ai/airsync-mac点击查看免费下载相关推荐从零构建 Taskwarrior Taskserver 客户端凭证、同步协议与消息格式权威指南从零构建 Taskwarrior Taskserver 客户端凭证、同步协议与消息格式权威指南 导读 本文以 Taskwarrior 官方 RFC 文档 do开发工具Ivy核心功能揭秘EDR免Hook与ETW补丁技术原理详解Ivy核心功能揭秘EDR免Hook与ETW补丁技术原理详解 Ivy作为一款强大的内存中VBA代码执行框架其核心功能在于能够绕过现代端点检测与响应EDR系Tutanota开发者指南如何从源码构建自己的邮件客户端Tutanota开发者指南如何从源码构建自己的邮件客户端 Tutanota是一款专注于安全隐私的端到端加密邮件服务让你在所有设备上都能加密邮件、联系人及日历即时通讯密码学前端移动开发创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
