桌面栈跑在 SNMK（SPT 宏内核）之上，全部系统服务与 UI 为独立执行体，进程间只经系统调用与 IPC 通信（POSIX 语义、Unix 哲学）。输入、窗口管理、合成三大职责分属三个进程，禁止合并。
- 文档版本：1.0
- 定稿日期：2026-09-05
组件分层
应用（Qt6 / QML + Vulkan 互操作，.spk 分发）
│ surface 协议
Soke Display Server ────────── wmshell（承载 Soke Window Manager）←── inputd
│ 合成树（每帧场景图） │ 输入事件流
compositord（Vulkan 合成 + 液态玻璃材质 + 10bit 输出）
│ Vulkan / DRM-KMS
Soke Display Driver Model（显示驱动程序模型）
│
GPU → 显存帧缓冲 → 完整显示输出
渲染链固定为：应用 → 合成引擎 → 显存帧缓冲 → GPU 驱动 → 完整显示输出，任何组件不得绕过中间层直写帧缓冲。
进程清单
| 进程 | 职责 | 语言 | 线程构成 |
|---|---|---|---|
inputd |
读取输入设备节点，产出统一输入事件流，识别手势 | Zig | 设备轮询线程（epoll，每设备组一个）、手势识别线程、分发线程 |
Soke Display Server |
surface 协议端：surface 生命周期、缓冲提交、输入按区域分发、输出热插拔与多屏协商 | Zig | 协议线程（每客户端连接一个执行体）、输入分发线程、输出管理线程 |
wmshell |
窗口管理 shell：焦点、层级、工作区、拖拽缩放策略；Dock、顶部状态条、启动器、通知中心 | C++ / QML（Qt 6.x，Vulkan 后端） | QML 主线程、窗口策略线程（Soke Window Manager）、IPC 线程 |
compositord |
接收合成树，Vulkan 渲染到每输出 swapchain，执行液态玻璃材质与 10bit 扫描输出 | Zig | 场景接收线程、渲染线程（每 GPU 一个）、呈现线程（vblank 驱动） |
Soke Display Manager |
显示管理器：启动根合成会话、绘制登录界面（greeter）、认证后拉起用户会话 | C++ / QML（Qt 6.x） | QML 主线程、会话监督线程 |
| 驱动（Soke Display Driver Model） | GPU/KMS 驱动程序模型：模式设置、页翻转、HDMI/DP 热插拔 | Zig | 内核驱动执行体 |
规则：任何一个守护进程内部，各线程是独立执行体；禁止把多任务塞进单个 idle 循环。Soke Window Manager 是 wmshell 进程内的窗口管理器模块；Soke Desktop Environment 是桌面侧整体（inputd、Soke Display Server、wmshell、compositord、壁纸管理器、通知中心）的组件总称，以 .spk 交付，spe 可安装/卸载。
IPC 通道与字段表
所有通道基于本地双向流（内核 IPC 系统调用，POSIX 套接字语义）承载控制消息，大块数据（像素缓冲、事件记录）走共享内存。消息只定义字段，不在此定义实现。
通用消息头
| 字段 | 类型 | 说明 |
|---|---|---|
| size | u32 | 整条消息字节数 |
| opcode | u32 | 请求/事件编号 |
| serial | u32 | 请求序号，用于应答配对 |
| object_id | u32 | 目标对象 id |
inputd → wmshell：输入事件流
共享内存环形缓冲承载记录，控制通道只传「可读量变更」通知。
环形缓冲头：
| 字段 | 类型 | 说明 |
|---|---|---|
| write_index | u64 | 原子写游标 |
| capacity | u32 | 缓冲容量（事件条数） |
| event_stride | u32 | 单条记录字节数 |
事件记录：
| 字段 | 类型 | 说明 |
|---|---|---|
| seq | u64 | 单调递增序号 |
| timestamp_ns | u64 | 事件时间戳（单调时钟） |
| type | u16 | 0 按键、1 按钮、2 绝对移动、3 相对移动、4 滚轮轴、5 手势、6 开关事件 |
| device_id | u16 | 设备标识 |
| code | u32 | 键码/按钮码/轴码 |
| value | f32 ×4 | 数值（位移、滚动量、手势位移等） |
| modifiers | u32 | Shift/Ctrl/Alt/Super/锁定键状态位 |
手势在 inputd 内识别（三指横滑、捏合、双指滚动），wmshell 只接收识别完成的 type=5 事件，窗口策略不接触原始设备数据。
应用 ↔ Soke Display Server：surface 协议
对象模型：display（连接根）、surface（窗口面）、toplevel（顶层面：标题/尺寸协商）、buffer（像素缓冲）、seat（输入座位：pointer/keyboard/touch）、text_input（文本输入：IME 预编辑与提交）、output（显示器）。
文本输入（中文输入法必经路径）：请求 text_input.enable / disable 开启预编辑；事件 text_input.preedit（预编辑串与光标位）、text_input.commit（上屏串）。IME 引擎在用户会话内运行，经 inputd 聚合后按键盘焦点转发至对应 surface。
请求（客户端 → Soke Display Server）：
| 请求 | 参数 | 说明 |
|---|---|---|
| surface.create | — | 新建 surface |
| surface.destroy | surface_id | 销毁 |
| surface.attach | buffer_id, x: i32, y: i32 | 挂接缓冲与偏移 |
| surface.commit | — | 提交挂接状态（双缓冲语义） |
| surface.set_input_region | rects[] | 输入命中区域 |
| surface.set_opaque_region | rects[] | 不透明区域（供合成器优化） |
| toplevel.set_title | title: 字符串 | 窗口标题 |
| toplevel.set_app_id | app_id: 字符串 | 应用标识（Dock 归类用） |
| toplevel.ack_configure | w: u32, h: u32, states[] | 接受尺寸协商结果 |
| buffer.create_pool | fd, size: u32 | 建共享内存池 |
| pool.create_buffer | offset, w, h, stride, format | 在池内建缓冲，format 固定 B8G8R8A8_UNORM（32 位真彩） |
事件（Soke Display Server → 客户端）：
| 事件 | 参数 | 说明 |
|---|---|---|
| surface.configure | w, h, states[] | 尺寸/状态协商（最大化、激活等） |
| surface.close | — | 请求关闭（用户点了右上圆点） |
| surface.focus | entered: bool | 键盘焦点进出 |
| pointer.motion / button / axis | 见事件流字段 | 按输入区域命中转发 |
| keyboard.key / modifiers | 键码、修饰位 | 同上 |
| output.geometry / mode / enter / leave | 连接器、模式、归属 | 多屏归属通知 |
Soke Display Server → compositord：合成树提交
每帧场景图，双缓冲（当前帧只读，下一帧可写），vblank 节奏提交。
场景节点 SceneNode：
| 字段 | 类型 | 说明 |
|---|---|---|
| node_id | u64 | 节点 id |
| parent | u64 | 父节点，0 为根 |
| surface_ref | u64 | 引用的 surface，0 表示无内容节点 |
| transform | f32 ×6 | 2×3 仿射矩阵（平移/缩放/旋转） |
| alpha | f32 | 节点不透明度 0.0–1.0 |
| clip | i32 ×4 | 裁剪矩形 x,y,w,h |
| corner_radius | f32 | 圆角半径（SDF 单一来源） |
| effect | u8 | 0 无、1 阴影、2 玻璃（强）、3 玻璃（弱） |
| glass_params | radius/depth/blur/aberration f32 ×4 | 液态玻璃参数，见 liquid-glass.md |
输出状态 OutputState：
| 字段 | 类型 | 说明 |
|---|---|---|
| connector_id | u32 | 连接器 |
| mode | w, h, refresh | 显示模式 |
| format | 枚举 | 固定 A2B10G10R10_UNORM_PACK32（10bpc） |
| hdr_metadata | 可选结构 | HDR 静态元数据 |
| rotation | u8 | 0/90/180/270 |
Soke Display Manager 会话通道
| 消息 | 方向 | 说明 |
|---|---|---|
| session.start | SDM → 会话监督 | 以用户身份拉起 inputd、wmshell |
| session.stop | SDM → 会话监督 | 结束会话，surface 在 Soke Display Server 侧保活回收 |
| session.auth_result | 认证模块 → SDM | 认证通过/失败与原因 |
启动顺序
- SNMK（SPT 宏内核）启动，加载 Soke Display Driver Model 驱动（Zig，ring-0），接管 UEFI GOP 遗留的显示输出。
Soke Display Server启动，枚举连接器与模式，建立 10bpc 输出。compositord启动，建立 swapchain，进入待机合成（黑场 + 徽标层由 SDM 注入）。Soke Display Manager启动，绘制登录界面（greeter，同为液态玻璃语言，输入由 inputd 转发）。- 认证通过，SDM 以用户身份拉起
inputd与wmshell，桌面就绪。
故障恢复
- 守护进程由所属监督者重启，退避 200ms 起步、每次翻倍、上限 10s，防止重启风暴。
compositord崩溃：SDM 冻结最后一帧输出，重建合成器后无缝恢复，客户端 surface 不失效。wmshell崩溃：窗口内容不丢（surface 在 Soke Display Server 侧保活），重启后重新协商窗口树。inputd崩溃：输入暂停，重启后重建设备监听。- 输出热插拔：Soke Display Server 感知后重协商模式，wmshell 重排窗口，compositord 重建对应 swapchain。
卸载边界
Soke Desktop Environment 整体是 .spk 组件：卸载后系统保留 SNMK 内核、驱动与 Soke Display Server 以下各层，终端会话仍可用；重装 .spk（spe install）即恢复桌面。