架构说明
Quick App、Lua 后端与多端接收器如何协作
Shell++ 不是一个单独的应用，而是一条由多个组件组成的设备工作链路。
组件关系
| 组件 | 职责 |
|---|---|
| Vela Quick App | 展示界面、接收用户操作、呈现状态与任务结果 |
| Lua 后端 | 调用设备能力、执行命令、处理文件与截图任务 |
| Shell++ Android | 连接手环、同步截图、管理本地文件并提供远程终端 |
| AstroBoxV2 插件 | 在桌面与跨平台环境中连接设备、同步数据和执行命令 |
一次典型操作会经过以下路径：
用户操作
→ Vela Quick App
→ Lua 后端
→ 设备能力或系统命令
→ Lua 后端
→ Android / AstroBoxV2
→ 结果展示与保存手环内部的文件 IPC
Quick App 与外部执行器通过 internal://files/ 下的文件交换任务和结果：
| 文件 | 内容 |
|---|---|
cmd_request.json | 命令请求，包含 seq、cmd 和 timestamp |
cmd_result.json | 执行结果，包含 stdout、stderr 与对应请求信息 |
bridge_state.json | 当前连接与桥接状态 |
full_output.txt | 未经终端界面截断的完整输出 |
终端页面会轮询结果文件，并只接受 seq 与当前请求一致的结果。这可以避免较早任务的返回值
覆盖较新的命令结果。
设备之间的数据流
Android 端通过 Xiaomi Wearable 消息通道与手环通信，并提供截图分片、断点恢复、本地缓存和 同步进度管理。局域网场景还可以使用应用内的轻量 HTTP 服务接收 PNG 文件。
AstroBoxV2 插件通过设备与 Interconnect 能力完成握手、截图列表同步和命令执行。插件还可以 注册 Deeplink 动作，供本机自动化工具触发，但所有命令仍会复用原有设备通信和安全检查。
为什么拆成多个组件
Vela Quick App 适合提供清晰的手环交互界面，Lua 适合接触更底层的设备能力，Android 与 AstroBoxV2 则擅长存储、展示和继续处理设备产生的数据。将这些职责拆开，可以让每一端保持 清晰，也让不同平台共享同一套手环能力。
版本一致性
Quick App、Lua 后端和接收端会共同参与协议交互。升级其中一个组件后，如果出现连接失败、 字段缺失或任务无响应，请优先确认各组件是否来自相互兼容的版本。