企业官网建设流程全解析

iOS与Android严格同步：VisionClaw双客户端平行文件映射与工程规范解析

【免费下载链接】VisionClawReal-time AI assistant for Meta Ray-Ban smart glasses -- voice + vision + agentic actions via Gemini Live and OpenClaw项目地址: https://gitcode.com/gh_mirrors/vi/VisionClaw

VisionClaw 是一款面向 Meta Ray-Ban 智能眼镜的实时 AI 助手，通过语音 + 视觉 + 智能体动作让 Gemini Live "看见你所见、听见你所言"。它的仓库里同时维护着两个完全对等的客户端：iOS 的 CameraAccess/（Swift / SwiftUI）和 Android 的 CameraAccessAndroid/（Kotlin / Jetpack Compose）。本文带你解析这个开源项目如何通过"平行文件映射"和清晰的工程规范，保证双端行为严格同步。

为什么双端必须严格同步？

VisionClaw 的架构是：客户端把眼镜摄像头的视频帧（约 1fps JPEG）和麦克风音频（16kHz PCM）通过 LiveKit SFU 送给 Gemini Live，再由 OpenClaw 网关执行搜索、发消息等 56+ 种技能动作。

用户无论用 iPhone 还是安卓手机，预期看到的界面、听到的提示音、感受到的交互节奏都应该一致。为了把这条原则落到每一次提交上，项目在 samples/CLAUDE.md 中写下了硬性规则：

Rule: 对任一客户端的行为性或面向用户的修改，必须在同一次变更集中镜像到另一端。不允许只上线一端的功能、修复或 UX 微调而让另一端掉队。

如果某个改动确实只适用于单一平台（如系统 API 无对应物），必须在提交中明确说明原因，而不是默默跳过。

平行文件映射：一张表看懂双端结构

两端的数据流完全一致：client → LiveKit SFU → agent worker + gateway。CLAUDE.md 用一张"平行文件映射表"把每个功能模块在双端的对应文件一一对应起来：

这张表的价值在于：新人拿到任务时，只需要按表找到另一端对应文件，就知道"镜像修改"应该改哪里。CLAUDE.md 也要求文件移动或新增平行功能时保持这张表最新。

同步落到细节：以 Earcons 音频提示音为例

最能体现"严格同步"的是无障碍模式下的提示音（Earcons）。视障用户看不见通话界面，耳边的一声短音是唯一可靠的信号——"连接成功"和"通话丢失"必须听感明确区分。

iOS 版 Earcons.swift 的注释里写着：

The same note sequences are used on Android (livekit/Earcons.kt); keep the two in step so a cue means the same thing on both platforms.

对比 Android 版 Earcons.kt 的注释，两边互为镜像、措辞呼应。再看实现：

• iOS：connected=[(660, 0.09), (0, 0.03), (990, 0.12)]
• Android：CONNECTED(listOf(660.0 to 0.09, 0.0 to 0.03, 990.0 to 0.12))

音高、时长、节奏逐项一致，同一声"叮"在两个平台上意味着同一件事。这种"数据必须一致、实现各循惯例"的做法，正是平行文件映射规范的核心精神：SF Symbols 与 Material 图标可以不同，SwiftUI 手势与 Compose 指针输入可以不同，但行为和 UX 必须一致。

测试与配置也保持平行

同步不止于界面逻辑，测试资产和配置文件同样成对出现：

• 测试素材：双端自动化测试使用完全相同的plant.mp4/plant.png素材——iOS 在 CameraAccessTests/Assets/，Android 在 androidTest/assets/。同一株植物的视频和照片喂给双端，视觉理解结果才有可比性。

• 密钥配置：iOS 提供 Secrets.swift.example，Android 提供 Secrets.kt.example，字段一一对应（Gemini API Key、OpenClaw 网关地址与令牌等），双端均可在应用内设置页运行时修改。

无法同步的部分：显式声明而非默默跳过

严格同步不等于机械复制。映射表中有两行专门标注了"平台差异"：

1. Siri / 动作键控制（CallIntents.swift）：iPhone 有 Action Button 可快速挂断/接通，而 Android 没有对应硬件，改用"Hey Google, open VisionClaw"语音唤起 + 自动开始流来覆盖同样场景。
2. 学习提醒推送（NudgeScheduler.swift）：iOS 已实现，Android 标注为not yet ported，目前只有前台服务通知兜底。

这种"差异显式登记在案"的写法，比"假装同步"更健康——读者一眼就能看出哪些是有意的平台专属，哪些是待办，避免误以为另一端有 bug。此外，像启用眼镜开发者模式这类纯操作型步骤（见 assets/dev_mode.png 所示的 Meta AI 应用内路径），双端流程一致，文档中互相引用即可。

工程规范要点总结

VisionClaw 的双端同步机制，可以浓缩为四条可复用的实践：

• 📌一条硬规则：行为/UX 修改必须在同一变更集内双端镜像，单端改动必须说明理由
• 📌一张映射表：把"关注点 → 双端文件"固化成表格，并承诺随代码演进持续更新
• 📌数据对齐、实现自由：音符序列、配置字段、测试素材必须逐值一致；UI 库与手势 API 遵循各自平台惯例
• 📌差异显式登记：平台专属功能与"尚未移植"项直接写进映射表，不留模糊地带

这套规范几乎零额外成本，却能让双端客户端在长期迭代中不"分叉"。如果你想动手验证，可以克隆仓库对照阅读：

git clone https://gitcode.com/gh_mirrors/vi/VisionClaw

从 samples/CLAUDE.md 的映射表出发，逐行对比 Earcons.swift 与 Earcons.kt，你会发现"严格同步"不是一句口号，而是被具体到每一个音高和时长数字上的工程习惯。

【免费下载链接】VisionClawReal-time AI assistant for Meta Ray-Ban smart glasses -- voice + vision + agentic actions via Gemini Live and OpenClaw项目地址: https://gitcode.com/gh_mirrors/vi/VisionClaw