S300 OS — 设计与验证

三个支柱，外加一层模拟验证

本文把眼镜 OS 拆成三个设计支柱来呈现。除开发者 SDK 仍是设计稿外，其余部分均已可运行。一套贴合 AP510 芯片的模拟器用于验证设计：内存能否放进 3 MB、交互是否够快。

相对 v0 的关键决策

本节假设读者已了解 v0 方案：有状态的云端 App Runtime 持有应用态并下发语义 diff；手机 Bridge（带缓存 + 预测）转发；眼镜渲染受限 DSL 并执行一小组预授权本地转移，让高频交互不上行。下面只列：保留了什么、改了什么、以及为什么。

总览对照

标 新增 的几项 v0 完全没有，展开见下文「v0 之外的新增」。

关键取舍与理由

App Host 放在手机，而非云端

v0：每会话一个有状态的云端 App Runtime（以 Phoenix-LiveView 为蓝本），手机是带缓存 + 预测的智能 Bridge（会话快照缓存、断网降级、部分乐观预测，是「边缘节点」而非哑中继）。本设计：手机即 App Host——承载应用、持有会话 / UI 态；UI 的状态回路不依赖云端、在手机本地闭环，云端只作 app 可选的网络资源（后端）。

理由：v0 自己的延迟预算里，蜂窝→云这一段是在 BLE 之上再加 ~50–150 ms。去掉它是体感延迟上最大的一项收益——应用态交互只付 BLE 往返（约一半延迟）、可离线工作、用户数据可留在手机（隐私 / 合规）。这也顺着 v0 已有的方向（把缓存与预测推向手机），把 Bridge 直接升格为 App Host。两种方案的权衡如下：

本地转移由组件类型自带，不下发逐视图的表

v0：云端在每个 ViewBundle 里下发显式 localTransitions 表，声明眼镜可本地处理哪些事件、以及如何处理（patch）。本设计：每个类型化组件自带预授权的本地行为——List 自带 focus / scroll，Text 自带 scroll——再加一条 on_edge 规则；不单独下发表。

理由：组件类型本身就蕴含其本地行为，把它编码进类型 → 线上更小（无需下发表）、不会与树脱节、眼镜端更简单（无需查表，渲染器即知）。v0 的原则被完整保留——眼镜无需业务逻辑即可处理本地交互——只是机制不同（用静态类型代替运行时表）。代价是逐实例的灵活性（App Host 无法单独为某个 list 重新授权转移），目前没有应用需要它。

v0 之外的新增

v0 假设单一全屏应用、应用都跑在云端；以下几块是它完全没有、而本设计补上的。

多应用桌面

v0 假设单一全屏应用。本设计加了一层桌面合成器：最多三个应用平铺，眼动追踪指针放大并聚焦被看的块。它是同一套视图态 / 应用态模式的第二层——桌面层管「哪个应用被聚焦」，每个应用管「哪个元素被聚焦」，所以眼动追踪与悬停放大都是本地视图态，永不往返。完整机制见 S300 OS。

多桌面与后台生命周期

v0 是单一全屏应用，没有「工作区」概念，也没有后台运行。本设计支持多页桌面（每页 3 个 tile，最多 4 页 / 12 应用），所有应用后台常驻运行（聊天新消息、AI 回复等都在后台推进），隐藏页只是不渲染、不接收交互；后台应用在眼镜上只留 DSL 树，多任务几乎不占内存。详见 S300 OS · 多桌面。

视图、导航与动作路由

v0 是单一全屏应用，没有应用内的视图层级与返回导航，也没回答「一个动作在没有指针的视图里交给谁」。本设计补上：应用由多个视图组成、共用一个系统视图栈（confirm 进入、double-tap 返回——pop 是系统原语，应用不必实现返回）；因为应用内没有眼动、手势没有空间目标，每个视图带一张动作映射，保证一个动作确定地落到唯一一个组件。详见 视图与导航 与 动作路由。

第三方应用打包

v0 的应用活在云端运行时里，没有处理外部开发者如何分发应用。把 App Host 移到手机后，这成了一个真实问题——由开发者体验设计回答（见 开发者体验）：应用是带声明式 manifest 的沙箱 WASM 包，像 APK 一样安装。已设计，未实现。

内存 / 显存管理——v0 没有，本设计做了一部分

v0 没有内存管理设计——它对显示是显示无关的，只标注了 ~1 MB RAM 的担忧，没有给出内存 / 显存的分配模型。本设计在这里补了一部分：据真实芯片把两块双缓冲 720p 帧缓冲从内部 SRAM 挪到 64 MB PSRAM，内部 3 MB SRAM 因此只剩 ~640 KB 的 UI 工作集——v0 的 1 MB 担忧也化解。RAM 上限（3 MB）是模拟器强制的硬约束、已验证。

但这只是开头。完整的内存 / 显存管理设计还没做——帧缓冲的确切放置与像素格式、SRAM / PSRAM 的分配策略、PSRAM 带宽 / 延迟对渲染的影响、字体与资产从 NAND 的分页、LVGL 池与栈预算，都待补。列入待确认问题。

S300 OS 的系统设计

本节是这套眼镜 OS 的完整设计：它如何分层、靠什么承重原理（view-state / app-state）运转、桌面与输入怎么组织、UI 用什么组件词汇（DSL）、以及渲染怎么做（全屏、增量更新）。

架构总览

S300 OS 是 server-driven-UI / 瘦客户端范式，App Host 在手机。整套系统是两层 + 中间一条 BLE 链路：

中间是 BLE——L2CAP CoC 走 diff 流、GATT 走控制 / 回告。手机承载应用逻辑与桌面合成两层，眼镜只负责渲染。

核心原理：view-state / app-state 划分

这是整套 OS 的承重设计：把交互分成两类，尽量多地在眼镜本地闭环。

• view-state（本地）——下一帧能由设备上已有的数据 + 这个事件确定算出（焦点移动、列表 / 文本滚动、切换已下发的局部）。眼镜本地解析、本地重绘，不上链路，<100 ms。
• app-state（上报）——需要应用逻辑或新数据（打开详情、提交、语音、跳到未下发的界面）。事件上报手机，手机回新视图，付一次往返。

判定一个交互能否本地化，用三条准则：闭包性（所需数据已在设备上）、确定性（下一帧 = f(本地态, 事件)）、可重放性（手机能用同一个 f 算出同样结果）。三条都满足才本地，否则上报手机。

边界旋钮是 onEdge：本地转移撞到数据边界时——clamp（停住）/ wrap（绕回）/ bubble（降级成 app-state 上报）。「撞边 → bubble」就是 view-state 与 app-state 的边界：固件实现了它，本地处理不了的情况就自动上报。

本地处理 vs 上报

每个输入先映射成语义动作（scroll-prev / scroll-next / confirm / double-tap 等）喂给 shared::apply()，可由眼镜就地解决就本地处理、否则上报手机：

应用态变化时手机下发整个 ViewBundle，外加一层 { b, proc_us }，让眼镜在 telemetry 里归因手机的处理时间。组件词汇表见下。

结合眼动的多任务桌面

OS 有一层桌面合成器：一页桌面放最多三个应用的平铺块（可多页，见下），一个眼动追踪指针（在模拟器里是鼠标）选中应用，被选中的块放大并聚焦。

桌面层是又一台视图态状态机，节点是应用窗口，叠在各应用的状态机之上。眼动追踪、悬停放大与聚焦都是本地桌面视图态——实时、永不往返。各应用内容仍按槽位走 ViewBundle / Patch 协议；桌面层合成各块、把手势路由给被聚焦的应用。

在增量合成之前，上述每一种都要把三个块整体重合成，约 ~57 ms。连续情形（指针跟着眼睛）现在便宜约 ~50×（~1 ms），而这恰是最需要顺滑的一类。跨应用是一次离散扫视，仍要重绘两个文本密集的块（~47 ms，在 100 ms 预算内）；改用扁平聚焦环叠加可让它也降到光标级，代价是失去放大。

多桌面

桌面分页，每页 3 个槽位，最多 4 页（12 个应用）。顶部一条页面切换条：眼动追踪停在上面时它高亮，此时滚动即切到相邻页；只有当前最后一页放满，才会多出一页可用。每页各自保留自己的 3 个应用，切页是瞬时的——current_desktop（当前显示第几页）是眼镜本地 view-state，切页不往返手机，和聚焦一样即时。

内存与运行实例

分页带出一个资源问题：隐藏的页，UI、状态、运行实例要不要都留着、还继续跑？划分两侧（眼镜 = 渲染端、手机 = App Host）答案不同。下表是隐藏页在两侧的处理：

眼镜侧：多任务几乎不占内存。贵的部分是 LVGL 对象（~256 KB 池、密集视图峰值 ~190 KB），只为可见页的 3 个 tile 存在。后台（非前台）应用在眼镜上只留一棵 DSL Node 树——每页几 KB，不是 LVGL 对象。所以应用再多、页数再多，眼镜的 SRAM / LVGL 池预算几乎不增长——这是对设备最关键的保证。

手机侧：所有应用后台常驻运行。每个已启动应用（跨所有页）都是活实例，不论在不在当前页都照常 tick——后台运行是特性而非负担：聊天的新消息、AI agent 的回复、实时转写、计时器、音乐，都要在你没看着时继续推进。隐藏页的应用只是收不到眼镜交互（你没在看它）。内存封顶 12 应用、不成问题；CPU / 电量随活跃应用数增长，但有上限（后续可按应用类别加后台限额）。

后台更新如何落到眼镜。后台应用产生的 Patch / ViewBundle 照常下发，眼镜把它应用到缓存的 DSL 树上，但不渲染成 LVGL——直到那一页被切到前台，才用最新的缓存树填回 tile。所以后台更新很便宜（只更新模型、不绘制），切回去看到的总是最新内容。

实现状态：多页桌面、切换条、切换与增长规则、眼镜按页缓存、所有应用后台 tick、隐藏更新「入树不绘制」——均已实现。

交互动作

真实设备有两类输入：镜腿触控板 + IMU 产生的手势，以及眼动追踪。手势在眼镜上识别、归一成一组语义动作，判定含义时从不等链路。每个动作要么被系统捕捉、应用无法截获，要么路由给被聚焦应用的当前视图。

交互动作 · 谁捕捉

系统捕捉 vs 路由给应用。只有两样是系统捕捉、应用无法截获：眼动追踪（聚焦）和 click+hold（上下文菜单）——后者保证用户在任何应用里都有一条系统逃生通道，即便应用改掉了其他动作。其余动作都路由给当前视图处理（怎么路由见动作路由）。

「按住」给出三个独立动作。press-start、long-press、press-end 是三个不同的动作，来自同一次按住的不同时刻：按下给 press-start、按住越过阈值给一次离散的 long-press、松开给 press-end。应用订阅它要的那个（们）——录音用 press-start + press-end 框出区间，「长按一下就触发」用离散的 long-press，三者互不依赖。语音只是 press-* 的一个订阅者，没有特殊地位——长按不绑定语音。

这三个都是应用动作（普通按住），别和 click+hold（先点一下再按住）混——后者是系统手势、固定打开上下文菜单。实现现状：press-start / press-end 已接线；离散的 long-press 在设计内、尚未单独下发，且代码里 Action::LongPress 目前指的是 click+hold/菜单（命名待理顺）。

视图与导航

一个应用由若干视图（View）组成，每个视图是一棵组件树。应用有一个视图栈（类似 iOS 的 NavigationStack）：confirm 进入下一层（push）、double-tap 返回上一层（pop）。例如 Chat：联系人列表视图 →（点进某联系人）push 出会话视图 →（双击）pop 回联系人。

视图栈两边都存：手机是源头，眼镜是缓存。手机（App Host）持有权威的视图栈；眼镜按槽位也缓存这条栈——每个视图就是一棵已下发的 DSL 树（几 KB）。这与多桌面、后台更新是同一套机制：眼镜缓存树、本地渲染，手机在背后按需 patch。

push 由应用、pop 在眼镜本地

• push 由应用驱动（只有应用知道点进去要载入什么）：confirm 上报手机，应用算出下一个视图，手机压栈、把它作为一次 push 下发，眼镜也压进自己的缓存栈。
• pop 在眼镜本地完成：double-tap（未被改绑时）眼镜弹自己的缓存栈、立刻重渲染上一视图——不走往返（与切桌面同理）；同时上报一个 {back}（fire-and-forget）。手机据此弹自己的栈、跑 on_pop；只有当上一视图的数据在期间变过，才回一条 Patch 把它刷新，否则什么都不发。

于是返回即时（本地渲染 + 可选的小 patch），不再是「往返 + 重发整棵上一视图」。应用不必实现返回。手机始终是源头：万一两边栈不一致，手机可直接下发完整视图重新对齐。

double-tap 是应用级事件，不是系统专属。应用可以在视图的动作映射里把它绑到自己的目标。但只要应用没有接管它，系统就默认捕获它执行返回（pop）——所以「后退」对应用是免费的（不写一行代码即得），需要时又能改绑成别的行为。这正是把返回做成系统原语的方式。

动作路由

应用内没有眼动追踪。眼动只在桌面层决定哪个应用被聚焦，进了应用就没有指针——一个手势在视图里没有空间目标，系统无从知道你「点的是哪个组件」。由此得到一条硬约束：同一个视图里，一个动作只能由一个组件响应。动作路由就是把每个动作确定地落到那唯一一个处理者。

每个视图一张动作映射

每个视图带一张「动作 → 目标」映射，每个动作至多一个目标。它是一张 map——「两个组件订阅同一个动作」从数据结构上就无法表达，而不是靠校验事后拦截。目标是三种之一：

• 一个组件 key——把动作交给该组件（如 confirm → 列表、press-start/press-end → 某个录音组件）；
• 一个应用动作 id——上报给应用的 on_action，由应用自己处理；
• 系统——交给系统默认行为（返回）。

View {
  body: <组件树>,
  actions: {                       // 至多一个目标 / 动作；省略的走默认
    confirm:       node(2),        // → 组件 2（列表）
    "press-start": node(5),        // → 组件 5 开始录音
    "press-end":   node(5),        // → 组件 5 停止录音
    "double-tap":  app("compose")  // 覆盖系统默认（不再是返回）
  }
}

默认让简单应用零配置

• 按组件类型推默认：视图里唯一的可聚焦组件（List / Text / RunningText）自动接 scroll + confirm。
• 系统默认：未绑定时，double-tap → 返回（pop）。
• scroll / confirm 始终自动绑到那个唯一可聚焦组件；double-tap / press-* 可显式绑定或覆盖。常见应用因此不写 actions，需要自由度时再写。

click+hold 不进这张映射：它由系统捕捉、固定打开上下文菜单，应用改不了（见交互动作）——这保证任何应用里都有一条返回 / 关闭的逃生通道。

现状：显式动作映射 + 类型 / 系统默认均已实现（apply() 按映射或默认路由，双击默认返回可被改绑）；click+hold 固定走系统上下文菜单；按住的 press-start / press-end 已接线（离散 long-press 待单独下发），语音只是 press-* 的默认订阅者。

组件 DSL 规格

DSL 是一棵类型化组件树，序列化成 JSON 下发到眼镜（serde 编码；将来可换二进制省字节），眼镜照它渲染、就地处理本地交互。它本质是一份 JSON 版的精简 HTML：节点 = 「元素」，布局 = 「盒模型 + flexbox-lite 的 CSS」，Screen 上的动作映射 = 「事件绑定」，整体收窄到一块单色 HUD 能承受的范围。共 15 个组件。

数据模型

顶层是 ViewBundle = version（单调版本号）+ 根节点 root。每个节点写成 { "类型名": { 字段… } }，且都带一个 key: u32。一棵以 Screen 为根的树就是一个视图。下面是一条「通知」视图、手机发给眼镜的完整报文：

{
  "version": 7,
  "root": {
    "Screen": {                        // 一棵 Screen 树 = 一个视图
      "key": 1,
      "title": "NOTIFICATIONS",
      "actions": {},                   // 动作映射（见「动作路由」）；留空 = 全走默认
      "body": {
        "List": {                      // 容器把别的节点嵌进来 → 一棵树
          "key": 2,
          "items": ["build passed", "battery 77%", "sarah: lunch at 1?"],
          "focus": 0,                  // 当前选中第几项（view-state，眼镜本地维护）
          "top": 0,                    // 首个可见行（view-state）
          "rows": 11,                  // 一屏显示几行（配置）
          "on_edge": "Clamp"           // 滚到底怎么办：停住（另有 Wrap / Bubble）
        }
      }
    }
  }
}

嵌套规则（内容模型 · 谁能装谁）

key 在一个视图内必须唯一——Patch 与增量重绘都靠它定位节点；重复或指向不存在的 key，对应的 Op 落空（不报错）。

view-state vs app-data（解释器必须分清）

字段分两类。app-data 是手机权威的内容（整树或 Patch 下发，眼镜只读、照渲）；view-state 是眼镜本地拥有、由本地交互就地改、且 Patch 必须保留的那几个字段——只有三个：

其余全是 app-data（items / lines / value / text / label / on / recording / rows / on_edge …）。所以一条 Patch 改 app-data（如 SetListItem 改某行文本）时，眼镜原样保留 focus / top；列表增删项时按规则把它们夹回有效范围（见增量更新）。

组件参考

15 个组件，分三组。每个都带 key: u32。「固有高度」是测量（measure）一遍给出的、布局据以排布的像素高（基准 ROW_H = 36、~28px 字体）。

容器与布局（无 view-state；把动作路由给可聚焦子节点）

可交互（持 view-state；本地解析焦点 / 滚动）

纯展示（无交互、无 view-state）

设计内、尚未补的组件 未实现

布局

DSL 里没有绝对坐标：一个组件放在哪、占多大，完全由它所在的容器和顺序决定。三个容器 + 三个布局控制就是全部规则——一套 flexbox-lite + 盒模型。

坐标与几何

整块显示 1280×720 px。一个窗口视图渲染进一个 tile（三列之一，内容宽 ≈ tile_w − 2·CPAD，CPAD = 14）；聚焦的 tile 用全宽、未聚焦的按比例缩小（内容随之重排）。单位都是 px：基准字体 ~28px、按字数估宽 ≈ 15px/字，行高基准 ROW_H = 36。全屏模式下视图改为铺满整屏（见全屏模式）。

两遍布局算法（渲染器自己算 x/y，不依赖 LVGL flex）

1. measure（自底向上）：每个节点在给定内容宽下报出固有高度（即组件参考的「固有高度」列）。容器据此聚合——VStack 求子高之和、每两个之间加 8px；HStack 取最高的子节点、子宽用按字数的估算；Box = margin + 子高。
2. arrange（自顶向下）：容器在自己的可用空间里摆子节点——VStack 从上往下、HStack 从左往右；Spacer 吸收主轴余量（多个均分），没有 Spacer 时由 justify 分配余量；Box 把 child 按 margin 偏移。叶子节点直接画到算出的 (x, y)。

容器:决定排布方向

VStack = 竖直堆叠（V = vertical，孩子上下排）、HStack = 水平堆叠（H = horizontal，孩子左右排）。Screen 只放一个子节点，要在一屏放多个组件就装进 VStack 或 HStack；默认「每个组件占一行、上下排」就是把 body 设成一个 VStack。

布局控制:对齐与留白

例:把回复框钉到底部 + 左右留白(Chat 会话视图,已实现)

Box{ margin:{left:14, right:14, bottom:12}, child:
  VStack{[
    RunningText(消息),
    Spacer,                // ← 吃掉中间的空,把下面两个推到底
    Divider,
    VoiceInput("回复")
  ]} }

渲染结果:消息贴顶、回复框贴底(中间被 Spacer 撑开),整块离 tile 左右各留 14px。没有 Spacer 时,回复框只会紧贴在消息下面、飘在屏幕中上部。

局限与未实现 未实现

可用的「CSS」目前就是：stack 方向 + Spacer（flex-grow）+ justify + Box 的 margin。「靠右 / 靠底 / 居中 / 均分」用它们已经够；以下都还没有，按真实应用需求再补：

• 交叉轴对齐（align）——VStack 子节点现一律占满行宽、HStack 现一律顶对齐，没有「列内左 / 中 / 右」「行内顶 / 中 / 底」。
• 尺寸约束（width / height / min / max / 比例）——尺寸全由内容定，做不了「固定宽侧栏」或「居中的窄列」。
• padding——只有 Box 的外边距 margin，没有内边距。
• 文本换行 / 截断——长串行为未定义（现近似按窗口裁剪，不回绕、不加省略号）；HStack 子宽也只按字数估算，CJK 偏窄。
• 容器内滚动——只有 List / Text 自带窗口；比 tile 高的 VStack 会被裁掉，做不了可滚动的长表单。

交互与事件语义

交互模型已在前面三节讲全：交互动作（动作词汇、系统 vs 应用）、动作路由（每视图一张映射 + 默认）、视图与导航（视图栈、push / pop）。这里只补一张组件级的表：一个动作落到某类可聚焦组件时，apply() 判它本地解决还是上报。

解释器 shared::apply(root, action) 先用 first_interactive 从树根下钻到第一个可聚焦节点（穿过 Screen.body 与 VStack/HStack 的子节点），再按其类型裁决这个动作能否就地解决：返回 Local（就地改树、就地重绘、不上链路）或 Bubble(AppEvent)（上报手机定夺）。下表是路由给组件的动作；double-tap（系统返回）与 click+hold（上下文菜单）是系统动作、不在此表。

要点：List 把 focus（选中项）与 top（首个可见行）分开——焦点移出可见窗口时只滑动 top，全在端上；只有焦点移出数据本身才触发 on_edge。confirm 上报时随事件带上 focus，这就是「在 confirm 处回声」：手机无需盯着每一次滚动，也能在用户「点进去」的那一刻知道选中的是哪一项。

线缆格式

同一棵树既用于下行（手机 → 眼镜）也定义上行（眼镜 → 手机）。JSON 编码：枚举写成 { "变体名": { 字段… } }（无字段的单元变体直接是字符串），字符串 UTF-8。眼镜从不做树对账——手机知道改了什么、直接告知，眼镜照做。

// 下行：手机 → 眼镜（外层还裹一层信封，见下）
ViewBundle { version: u64, root: Node }            // 应用态变化：整棵树替换该槽位
Patch      { version: u64, ops: Vec<Op> }          // 同屏微更新：按 key 定位、就地改

Op = SetListItem    { key, index, text }           // 改 List 的某一行
   | InsertListItem { key, index, text }           // 往 List 插入一行（index = len 即追加）
   | RemoveListItem { key, index }                 // 删 List 的某一行
   | AppendText     { key, text }                  // 给 RunningText 追加一行（超 max 丢最旧）
   | SetVoice       { key, value, recording }      // 改 VoiceInput 的文本 / 录音态

// 上行：眼镜 → 手机
AppEvent { node_key: u32, action: Action, focus: usize }    // focus =「在 confirm 处回声」给手机
Action = ScrollPrev | ScrollNext | Confirm | DoubleTap      // 眼镜归一出的语义动作
       | LongPress | PressStart | PressEnd                  //（LongPress 系统捕捉，不上行）
Edge    = Clamp | Wrap | Bubble                    // List 焦点撞到数据边界时怎么办
Outcome = Local | Bubble(AppEvent) | Back | Menu | Ignore   // 解释器 apply() 对每个动作的裁决

实际报文外面还裹一层信封，指明槽位与意图。下行 full：{ full, slot, nav?, actions, listen, fullscreen? }——nav:"push" 表示这是一次导航 push（眼镜压栈，否则替换当前视图）、actions 是该应用的上下文菜单项、listen 表示要连续麦克风流、fullscreen 切全屏；另有 { patch, slot } 与 { clear: slot }。上行有 { event:{slot,action,node,focus} }（bubble）、{ back:{slot} }（系统返回）、{ action:{slot,id} }（菜单选项）、{ launch:{slot,id} }（启动器）。version 单调递增、手机每次变更 +1（眼镜目前只记录、不据此丢弃乱序补丁）。

解释器

眼镜端解释器持有以下状态、按以下流程处理输入——与它具体怎么实现无关。（本模拟器把它拆成一个薄原生层 + 一段沙箱化的 wasm「大脑」，3 MB 上限、正是将来要落到 MCU 的那部分；那是模拟器的细节。）

解释器持有的状态

• 每个槽位一棵缓存的 DSL 树 + 一条视图栈（导航历史）；栈顶 = 当前视图。
• view-state（List.focus/top、Text.top）就存在树节点里，本地交互就地改。
• 从不持有 app-state、从不主动碰链路——只渲染、只解析能本地解析的，解析不了就发信号。

两个输入源

① 下行消息（手机 → 眼镜）：ViewBundle 替换 / push / pop 一个槽位的树；Patch 把 Op 套到缓存树上、保留 view-state；clear 清空槽位。后台槽位（不在前台）照常入树、但不渲染，直到被切到前台（与多桌面同理）。

② 输入（眼动 + 手势）：眼动追踪只在桌面层决定哪个 tile 被聚焦（从不上报）；其余手势归一成一个语义动作，对当前视图跑 apply()，按裁决处理：

手势 → 归一成 Action → apply(当前视图, action) → Outcome:
  Local            就地改 view-state、只重绘该 tile、不上行
  Bubble(AppEvent) 上行 { event } 给手机（confirm / press / 应用绑定的动作）
  Back             弹本地视图栈、重渲染上一视图；上行 { back }（fire-and-forget）
  Menu             本地打开上下文菜单（click+hold）
  Ignore           丢弃

渲染：树 → UI 对象树（这里用 LVGL）→ 只重绘受影响的 tile（脏矩形，见增量更新）。整套裁决逻辑（apply / apply_patch + 节点类型定义）放在 shared crate，手机与眼镜共用同一份——「什么算本地」只此一处。

一次往返示例：Chat —— 滚动本地、点按拉取

Chat 的入口是一个联系人 List。手机是唯一知道「会话里有什么」的一方，所以 Confirm 正是控制权交接的点——浏览列表零往返，点进会话正好一次往返：

focus:0 就是手机据以知道「点的是哪个联系人」而无需盯着每次滚动的字段——「在 confirm 处回声」。代码位置：gl_on_action / gl_out_* 在 crates/glasses-wasm；手势映射与上行转发在 crates/glasses 的 handle_gesture；handle_event / on_event 在 crates/phone。

错误处理与一致性

受限、封闭的词汇让出错面很小；解释器对异常一律安全降级、绝不崩：

• 未知节点类型 / 字段缺失：JSON 反序列化失败 → 整条消息丢弃，该槽位保留旧树。含义：眼镜的词汇必须 ≥ 手机所发；上新组件要先升级眼镜、再由手机下发——前向兼容靠版本协商（未做，见下）。
• Op 指向不存在 / 重复的 key：该 Op 落空——不报错、不动其它节点。
• 越界：focus / top / index 超范围一律夹回有效区间（增删列表项后即按此夹紧）；Progress.value 超 100 截断。
• version 倒退 / 乱序：目前不校验——眼镜套用收到的任何补丁。可靠有序由传输层（模拟器里是 TCP）保证；真机 BLE 上需要的重排 / 去重 未实现。
• 两侧视图栈不一致（push / pop 漏传）：手机是权威，可随时下发完整 ViewBundle 把该槽位重新对齐。

扩展与未覆盖

DSL 是个有意保持小的封闭集合：眼镜对每个节点类型、每个 Op 的处理都预先实现好，没有运行时解释。加能力 = 加一个类型 / 一个 Op（改 shared 一处，手机眼镜共享）。当前还没覆盖、标 未实现 的：

• 组件：Button / Disclosure / Gauge / Tabs / 光栅 Image（见组件参考的未实现组）。
• 布局原语：交叉轴对齐、尺寸约束、padding、文本换行 / 截断、容器内滚动（见布局一节的局限）。
• 增量 Op：现有 5 个只覆盖 List / RunningText / VoiceInput。SetText / SetProgress / SetToggle / SetKeyValue 等还没有——所以多数展示组件目前要整树重发才能更新；结构性增删节点（而非改数据）也只能整树重发。
• 样式：单色 HUD 固定，DSL 不带 per-node 颜色 / 字号 / 字重——这是有意的，不计划开放。
• 协议健壮性：版本协商 / 前向兼容、补丁重排去重、二进制编码（现 JSON），待补。
• 国际化：宽度按字数估算、CJK 偏窄；字体覆盖、RTL 未处理。

组件画廊

DSL 是一套受限、封闭、可 schema 校验的组件集——眼镜端一个递归渲染器把任意组件树变成 LVGL 对象树。下面是每个组件在绿色 HUD 上的渲染样子、规格与用途。（手机目录里有个「Components」应用可现场展示。）

每个组件自带本地转移，因此眼镜知道哪些手势在端上解决（list 焦点、text 滚动）、哪些必须上报（confirm）。Op 把同屏局部更新扩展到 List 行之外：AppendText（把一行流入 RunningText）与 SetVoice（录音状态 / 已填文本）。尚未实现的扩展组件：Button、Disclosure（展开/收起）、Gauge、Tabs，以及真正的位图（光栅）Image；一个 SetProgress/SetToggle op 可让这些指示器实时动起来。

全屏模式——可选开启、应用自供视图

应用可从上下文菜单接管整块 1280×720。它要主动开启（不支持的应用不显示该项），并自供全屏视图——桌面层只改几何：选中的块铺满、另两个隐藏、去掉边框、暂停眼动追踪切换（一个应用独占屏幕）。再点一次菜单项切回。

增量更新

「只改变化处」在两个独立层级上都成立；手机驱动的变化下两者叠加：

• 第一层 — 增量补丁 Patch（手机 → 眼镜，省字节）。同屏变化时，手机不发整个 ViewBundle，而发一个 Patch：一小列定点操作 Op，每个用目标节点的 key 定位、只改它的数据（写法下详）。是应用逻辑直接说「改这里」，不是对两棵树做 diff——所以眼镜无需对账。更少 BLE 流量 → 更少射频、功耗、延迟。
• 第二层 — 局部 LVGL 重绘（眼镜端，省 CPU）。眼镜收到一处变化后，只更新受影响的 LVGL 对象、只重绘它占的那块屏幕区域（脏矩形），而不是整树重建。更少 CPU / 渲染时间。

增量更新怎么写 —— Patch 与 Op

一个 Patch = 版本号 + 一列 Op。每个 Op 用目标节点的 key 定位、只改它的数据（不动树结构）；眼镜对缓存的那棵树原地套用（apply_patch），再只重绘受影响的 tile。现有五个 Op，按真实应用需求生长：

写法和视图一样是纯 JSON。下面这条 Patch 把通知列表（key = 2）的第 2 行改掉——整条报文约 100 B（对比整棵 ViewBundle 的 ~600 B）：

{
  "version": 8,                                   // 整条 UI 的单调版本号，手机每次变更 +1
  "ops": [
    { "SetListItem": { "key": 2, "index": 1, "text": "battery 64%" } }
  ]
}

每个 Op 写成 { "变体名": { 字段… } }（与节点同款）；一条 Patch 可带多个 Op，按顺序套用。在链路上外面再裹一层 slot，指明改哪个槽位。边界：Op 改的是某个节点的数据——也包括像 List.items 这种向量（增删列表项就是上面的 InsertListItem / RemoveListItem），但不改树的结构：增删组件节点、换布局才需要发整棵 ViewBundle。需要新能力时按组件加新 Op（如 SetProgress / SetToggle 让指示器实时动）；这是个有意保持小的封闭集合，眼镜对每种 Op 的处理都预先实现好，无需运行时解释。

应用运行时——手机端的 WASM 应用容器

这一节是给手机应用平台团队的架构设计。应用放在手机（而非云端），手机就是应用的 App Host——它承担三件事：

• 持有每个应用的状态 / 数据。应用的数据与业务逻辑都在这里，「现在显示什么、用户操作后变成什么」由它决定；眼镜本地处理不了的事件上报给它，由它算出下一个视图。
• runtime 容器。把应用的 wasm 加载进各自独立的 wasmtime 实例——沙箱隔离、内存硬上限、fuel 计量。
• 生命周期管理。安装 / 启动 / 挂起 / 恢复 / 关闭；所有应用后台 tick（隐藏页只是不渲染、不接收交互）。

下面是完整方案——当前以树内注册的 Rust 模块跑通，目标是把每个应用做成沙箱 WASM 容器。

手机即应用容器

应用编译成一个 WebAssembly 模块。手机运行时把每个已安装应用加载进它自己的 wasmtime 实例——独立线性内存、逐回调的 fuel 预算、除我们交给它的 import 外没有任何 capability。这正是眼镜大脑已经在用的方式：复用一个验证过的沙箱，而非另造一个。

容器 ABI：模块 ⇄ 宿主

契约对应今天的 trait：每个方法一个 wasm 函数，DSL 序列化为字节经一块共享缓冲传递——正是眼镜大脑已在用的 inbox_ptr / 长度 模式。宿主驱动模块；模块只能经被授予的 import 回调。

字节经共享缓冲往返（把参数写到 app_inbox_ptr()、调导出、读返回的指针 / 长度）——边界两侧不解引用指针，模块保持完全沙箱化。这里用 Node/Op 的二进制编码代替 JSON 以减小体积，下游的 BLE 预算也随之收紧。

安装、生命周期与治理

生命周期：installed → running ⇄ suspended → closed。启动把模块实例化进某槽位的 Store；挂起停 tick、切回即时恢复；关闭丢弃 Store、回收内存；持久状态靠 storage capability 存活。多桌面下所有应用后台常驻 tick，隐藏页只是不渲染、不接收交互（见多桌面）。手机的 App Manager 界面（独立 URL，:8081）是安装 / 启动 / 挂起 / 恢复 / 关闭 的入口。

上行通道：菜单 / 语音 / 导航 / 启动

这些应用交互共用一套上行机制——眼镜 → 手机的上行路径，与既有的下行视图并存：

模拟环境 vs 真实手机

模拟器跑在 Mac 上、用来验证设计（内存、延迟、交互），并非真实手机运行时本身——也不是开发手机应用的地方。共用、两边一致的那份——shared DSL、App trait、LVGL 渲染、view-state / app-state 划分——不在此列；下面只标当前模拟环境与真实手机实现的区别。

我们构建的应用

十个应用端到端地检验组件、OS 与运行时——每个专攻框架的不同部分。

开发者体验——构建与分发应用

开发者体验有三部分。组件 DSL是构建面——一套封闭、可 schema 校验的词汇表，应用用它拼出 UI。这套双进程模拟器是实时开发回路——跑一个应用，在查看器里看它的延迟、fuel 与内存。缺的一块是打包与分发：今天示例应用编译进 OS；为让别人能发布应用，我们设计了一个平台。下面是这个平台的完整设计——设计稿，尚未实现。

要做的四样东西

要成为一个真正的平台——让第三方无需我们的源码树即可构建应用、以自包含产物分发、用户像装 APK 一样安装（选取、授权、运行）——需要下面四样东西。均未开发

应用接口：一个 Rust trait

应用的接口就是一个 Rust trait：launch() 返回初始视图（受限 DSL 树 Node）；tick() 与事件钩子返回局部更新（Op）或新视图。眼镜渲染 DSL 并在本地解析视图态；只有应用态事件才上报到手机上的这段代码。这个 trait 小、声明式，已覆盖视图、更新、菜单、语音、导航与全屏——SDK 原样沿用它。

pub trait App: Send {
    fn manifest(&self) -> Manifest;                       // id、名称、图标
    fn launch(&mut self) -> Node;                          // 初始视图（DSL）
    fn tick(&mut self) -> Vec<Op> { vec![] }                // 周期性局部更新
    fn menu_actions(&self) -> Vec<(&str, &str)> { vec![] }   // 上下文菜单项
    fn on_action(&mut self, id: &str) -> Vec<Op> { vec![] } // 菜单项被选中
    fn on_voice(&mut self, phase: &str) -> Vec<Op> { vec![] }// 长按听写 → ASR
    fn on_event(&mut self, code: u32, focus: usize) -> Option<Node> { None } // confirm/back
    fn supports_fullscreen(&self) -> bool { false }        // 选择支持全屏
    fn set_fullscreen(&mut self, on: bool) -> Node { .. }   // 全屏视图
}

单有这个 trait 还不够成为平台：它要我们的源码才能编译、以宿主全信任运行、没有包与版本、目录在编译期写死——这正是上面四样东西要解决的。

语言与运行时：WASM 作契约，Rust 作一等 SDK

分开两个问题。包的载荷永远是 WebAssembly——那是安全与可移植的边界。SDK 是其上的开发者层，今天是 Rust 优先，因为代码库、DSL 类型与最好的 wasm 工具链都是 Rust。其他语言的 SDK 日后可叠在同一套 ABI 上。

关键性质：应用只能做它的 import 允许的事。没有 host_net import 的模块根本够不到网络——capability 是结构性的，不是策略。AssemblyScript / JS 支持对生态很有价值、在路线图上，但它走同一套 ABI，是叠加而非分叉。

应用包 .glsapp 与 manifest

一个包是已签名的归档。manifest 是声明式、可检视的——OS 据它列出应用、提示授权、构建上下文菜单，这些都先于模块执行。代码只在安装 + 授权之后才运行。

com.acme.chat-1.2.0.glsapp
├── manifest.toml      # 身份、capability、菜单、全屏——无需运行代码即可读取
├── app.wasm           # 编译后的模块（唯一可执行部分）
├── assets/            # 图标、矢量图、子集字体（由 DSL 寻址）
└── SIGNATURE          # 开发者密钥 → 完整性 + 来源

[app]
id      = "com.acme.chat"      # 反向 DNS，全局唯一
name    = "Chat"
version = "1.2.0"              # semver；商店与 OS 据此控制升级
icon    = "assets/icon.svg"
min_os  = "1.0"               # 宿主拒绝比自己更新的模块

[capabilities]                 # 模块获得的全部 capability；安装时提示授权
storage   = true               #   持久化键值存储，按应用隔离
voice_asr = true               #   可请求听写（驱动 VoiceInput）
network   = ["api.acme.com"]   #   宿主代理出网，仅允许列表
timers    = true               #   周期性 tick() 唤醒

[[menu]]                        # 上下文菜单项——静态声明
id = "mark_read"
label = "Mark all read"
[[menu]]
id = "mute"
label = "Mute 1 hour"

[fullscreen]                    # 选择支持全屏
supported = true

SDK：你的 handler 就是应用

Rust SDK 的要点：开发者写的还是今天那个 trait，一个宏生成 wasm 导出、缓冲管线与（反）序列化，ABI 对开发者不可见。

use gls_sdk::*;                       // SDK crate：App、Node、Op、host::*

struct Chat { open: Option<usize>, msgs: Vec<String> }

impl App for Chat {
    fn launch(&mut self) -> Node {
        Screen("CHAT", List(contacts()))         // DSL 构建器
    }
    fn on_event(&mut self, code: u32, focus: usize) -> Option<Node> {
        if code == CONFIRM { self.open = Some(focus); Some(self.conversation()) } else { None }
    }
    fn on_action(&mut self, id: &str) -> Vec<Op> {
        if id == "mark_read" { host::storage::set("unread", "0"); }   // 一项已授予的 capability
        vec![]
    }
    fn supports_fullscreen(&self) -> bool { true }
    fn set_fullscreen(&mut self, on: bool) -> Node { self.view(on) }
}

register_app!(Chat);                  // ← 生成 app_launch / app_on_event / … 等 wasm 导出

SDK 附带 shared DSL 类型、顺手的构建器（Screen、List、RunningText、VoiceInput…）以及 capability import 的薄封装（host::storage、host::asr）。C / AssemblyScript 的 SDK 会在同一套 ABI 上暴露相同形状。

工具链 glsdk CLI——模拟器即开发回路

开发体验最大的一块已经就绪：这套双进程模拟器（手机运行时 + 眼镜查看器 + 实时 telemetry）就是 glsdk sim。开发者无需硬件即可在真实 LVGL 渲染上看到自己的应用、驱动手势，并观察每次点击的延迟、BLE 字节、内存与 fuel。

因为眼镜大脑与应用共用同一套沙箱模型，validate 能精确测量将要发布的东西：每个视图的渲染 fuel、每个 bundle 的字节（BLE 在途时间）、以及模块内存峰值。

一套贴合真实硬件的眼镜模拟器

两个协作进程对照真实硅片建模眼镜：手机持有应用态并下发视图；眼镜大脑以沙箱 wasm 运行在芯片的真实约束下，用端上图形库绘制。本节先给整体流水线，再讲两件最关键的事——硬件约束如何做进模拟、以及这套模拟的限制；最后是它建模的设备与假定参数。

流水线

手机持有应用态并下发视图；眼镜在本地判断一个输入能否端上解决、还是必须上报。眼镜大脑编译成 wasm32 跑在 wasmtime 里，于是 RAM 与 CPU 都对照硬上限测量——这是同一份注定要上 MCU 的 no_std Rust。

视图态交互（聚焦、滚动）从不过链路——它们在沙箱里解决并本地重绘。只有应用态交互（打开、返回、提交、语音）才上报手机。

界面一瞥

模拟器左半边是真实尺寸的 1280×720 绿色 HUD（单绿 #3DFA44、4-bit），下面是代替镜腿触控 / IMU 的手势按钮；鼠标移到屏上 = 眼动追踪。下图是多应用桌面（三个平铺块，中间为被聚焦、放大聚焦的应用）。

真实运行界面的 HTML 复刻（非截图）。

如何做到硬件级模拟

「对照硬件」靠三个机制，把三种最关键的硬件约束变成可强制、可量化的指标：

这套模拟的限制

同样要讲清它做不到什么——三条最重要的：

Crate 结构

已验证 / 待办

设备究竟是什么

假定的参数

模拟器据以下参数对照硬件测量；完整逐参数理由见 docs/ASSUMPTIONS.md（参数的权威出处，与代码同步）。

实时开发者查看器

查看器相当于眼镜的浏览器 DevTools——每次交互都换算成数字。本节也讲它已经测到了什么。

如何看 telemetry

布局：左边是实时 1280×720 显示，右边是一摞面板——每个信号一块。逐一说明怎么读。

下图是右侧面板的 HTML 复刻（非截图）：事件日志（每行一次交互 + 四段延迟瀑布）、CPU（fuel → 估时）、内存（对 3 MB）、BLE 链路。

真实 telemetry 面板的 HTML 复刻（非截图）；数值用代表性样例。

显示

设备面板按真实尺寸——单绿 #3DFA44，4-bit（16 级）。鼠标移过去 = 眼动追踪：被聚焦的应用放大并聚焦。按钮 / 方向键发送被聚焦应用的手势。浮动 telemetry 面板可收起（右上角），以便看到整块显示。

事件日志——每次交互一行

最新在上，可滚动、有上限的历史。点任一行可内联展开其 DSL——当时过链路的确切 ViewBundle / Patch JSON；本地行会标注未发送任何东西。kind 告诉你工作发生在哪：

每行的延迟瀑布把体感延迟拆成四段——BLE-out · 手机 · BLE-in · 眼镜渲染——一眼看出某次交互是链路受限还是渲染受限。GAZE 或 LOCAL 行是纯渲染（一段绿）；PUSH 在它前面加一段青色 BLE-in。

CPU · 内存 · BLE 链路

• CPU——最近一次渲染的 wasm fuel → 估算的端上渲染时间，对照 100 ms「即时」预算绘出。fuel 是什么、ms 能信到几分，是关键，见下。
• 内存——wasm 线性 RAM 对照 3 MB SRAM 预算、两块 720p 帧缓冲（在 PSRAM）、以及 LVGL 池的已用 / 峰值（据此建议 LV_MEM_SIZE）。
• BLE 链路——链路的限速（带宽 · 连接间隔 · 单程延迟 · ATT MTU）与一份传输日志：每次突发的时间、载荷大小、BLE 包数（⌈(bytes+4)/MTU⌉）与建模在途时间。一个 449 B 的整应用视图是 2 包；一个局部 patch 是一个 80 B 包。

读延迟数字——以及为什么重要

这是模拟器价值的核心：据此能给方案排序、找出昂贵操作——脏矩形、局部更新、增量合成都在这里表现为 fuel 下降。但要知道信什么：

所以把延迟当作序数信号，而非毫秒承诺。要做成真正的延迟模拟：用真实 AP510 上测得的一次渲染校准 fuel/秒、计入 250 MHz GPU 绘制路径（最大的缺口——CPU 数字是软件上界，所以像动画放大这种 GPU 加速的工作在端上便宜得多），最终走到更高保真度的仿真（带真实内存映射的 Renode/QEMU，或开发板）。

模拟器的建议

• 内存——宽裕。帧缓冲在 PSRAM 后，内部 SRAM 只装 UI 工作集——~640 KB / 3 MB。LVGL 池峰值 11 KB → 建议 LV_MEM_SIZE ≈ 32 KB。帧缓冲用掉 64 MB PSRAM 中的 ~1.8 MB（4-bit 下 ~0.9 MB）。
• CPU——本地渲染现已便宜。有了脏矩形渲染，一次本地焦点移动增量渲染：端上 ~986 k fuel ≈ 4 ms，从整屏重绘的 ~28 ms / ~7 M 降下（~7×）。换屏（应用态）仍做一次 ~28 ms 的整屏渲染。
• 链路——视图态零开销。聚焦 / 滚动：0 字节，全本地。打开 / 返回：~40–45 B↑ / 0.5–0.9 KB↓，体感 ~80–110 ms。
• 手机推送的更新便宜——两层都是。一次实时同屏变化（电量 %）作为 Patch 发出（~100 B vs ~600 B 整视图），靠重写一行文本应用（~1.5 ms / ~370 k fuel，对比 ~28 ms / ~7 M 整树重建）。
• 本地化率。可按应用测量；下一步是用一组真实应用组合得到代表性比值。

需要各团队明确的问题

给固件 / 硬件团队

1. 确认 3 MB 内部 SRAM，以及要给 BLE 栈 + 应用 + OS 预留多少（剩多少给 UI）。
2. 帧缓冲放置与格式：两块 720p 帧都放 SRAM，还是卸到 64 MB PSRAM？L8 渲染 + 4-bit 发送，还是全程 4-bit？（帧缓冲 RAM 在 0.9–1.8 MB 间摆动。）
3. 完整的内存 / 显存管理设计：目前只做了一部分（两块 720p 帧缓冲放 PSRAM、SRAM 留 ~640 KB 工作集）。还需成体系的设计——SRAM / PSRAM 的分配策略、帧缓冲放置与格式（见上）、PSRAM 带宽 / 延迟对渲染的影响、字体与资产从 NAND 的分页、LVGL 池与栈预算。
4. Actions ATW6095 + 协议栈 实际能达到的 BLE 吞吐 / 连接间隔。
5. 渲染路径现实的栈预算。

给应用软件团队

1. 软件耗电预算：单个应用能用多少 CPU / 唤醒频率 / BLE 流量？这决定 tick 频率、刷新率与后台行为——需要一个明确的功耗上限（射频才是真正的功耗瓶颈，不是渲染）。
2. 后台运行限额：所有应用默认后台常驻运行——是否需要按应用类别限制后台 tick 频率 / 算力，避免 12 个应用都重度后台耗电？（见多桌面）