全系统架构总纲

Soke 操作系统的全系统架构总纲。子系统细设以本总纲为边界依据；桌面栈侧的唯一设计依据是 docs/design/desktop/（Soke Desktop Environment 桌面设计规范），总纲与桌面规范冲突时，进程边界与启动顺序以总纲为准，桌面内部协议以桌面规范为准。本总纲与 CLAUDE.md 规则冲突时，以规则为准。

• 文档版本：1.1
• 定稿日期：2026-09-05（1.1 修订：2026-09-16，按规则对齐内核形态、驱动模型、语言矩阵、引导器）
• 状态：内核地基已实现并通过 OVMF 实测（PMM/引导堆/VMM/CPU 底盘/调度器/SMP 枚举），其余子系统未开始

已定决策

§1 系统总览与设计原则

Soke 是 x86-64 桌面操作系统，整体分五层，每层只认相邻层的接口：

┌─────────────────────────────────────────────────────┐
│  应用层   Zig 应用 / Qt6 应用（桌面壳与工具）          │
├─────────────────────────────────────────────────────┤
│  桌面栈   Soke Desktop Environment（inputd / Soke Display Server /      │
│           wmshell / compositord / Soke Display Mgr）   │
├─────────────────────────────────────────────────────┤
│  系统服务层（全部 ring-3）                            │
│  initd · logd · devd · fsvrd(Btrfs) · posixd ·       │
│  netd(FreeBSD) · spe · updd · authd · timed           │
├─────────────────────────────────────────────────────┤
│  Soke64 API   libsoke64（C++ 实现 + C ABI 头）        │
├─────────────────────────────────────────────────────┤
│  SNMK 内核    SPT 宏内核（Zig + FASM）+ BSD 组件层    │
│               内核驱动（Zig，ring-0）内建于内核       │
├─────────────────────────────────────────────────────┤
│  Limine       上游 UEFI 引导加载器（vendor 最新版）   │
├─────────────────────────────────────────────────────┤
│  硬件   QEMU/virtio（一期）→ 真机（二期）             │
└─────────────────────────────────────────────────────┘

五条设计原则，后续所有章节由这五条推出：

1. 最小信任基。TCB 只有 Limine、SNMK 内核与 initd。设备驱动按规则运行在 ring-0（内核态），是内核的一部分、随内核一起受信任；文件系统、网络栈、POSIX 语义、桌面栈在 ring-3，崩了重启即恢复。
2. 能力即权限。进程拿到能力才能办事——文件、设备、IPC 端点都是能力对象。没有环境权限。
3. 独立执行体。每个职责一个进程/线程，输入、窗口管理、合成永远分家。
4. Unix 哲学。文本流、管道、组合小工具；/dev、/proc 由服务合成为 BSD 风格目录树。
5. 不声称未实现的东西。每个阶段的能力都有 QEMU/真机实测证据支撑，注入冒充验证直接违规。

§2 SNMK 内核架构

SNMK（SPT is Not Micro Kernel）是内核体系总名，自研宏内核，两个组成部分：

SPT 宏内核（Zig 主体 + FASM 汇编，ring-0），负责六件事：

• 调度器：抢占式多核调度，LAPIC timer 驱动，PIT 兜底；每 CPU 一套 TSS/GDT/GS 块。
• 虚拟内存：每地址空间独立 PML4，按需分页 + 大页拆分，用户/内核地址空间隔离。
• 能力管理：能力对象的创建、复制、传递、吊销，内核唯一权威。
• IPC：同步消息快路径 + 异步事件总线（§3）。
• 中断与异常：IDT/LAPIC/EOI 语义，中断处理在内核内完成，向用户态暴露事件而非中断线。
• syscall 门：SYSCALL/SYSRET，内核 syscall 面收敛在 40~60 个（线程、地址空间、能力、IPC、内存、时钟六个域）。

内核驱动：按规则第 30 条，设备驱动运行在 ring-0，是内核的组成部分，由 Zig 编写、静态链接进内核镜像，通过内核设备模型注册（§6）。内核里没有用户态文件系统、没有用户态网络栈。

GDT/IDT/TSS、每 CPU 变量、内核堆、物理页管理是内核自己的底盘。

HAL 硬件抽象层（Zig，独立层）：只暴露硬件事实与裸操作——memmap/HHDM 换算、页表原语、LAPIC/timer、ACPI 表解析、PCI 配置空间、串口；策略（地址空间生命周期、空闲页管理、调度、异常处置）留在内核。一期实现 virtio/QEMU 面，二期在同一接口下补真机面。

BSD 组件层（FreeBSD 最新 RELEASE 真源码，接入内核内）：

引导协议：内核由上游 Limine 引导，使用 Limine 官方引导协议（limine.h，逐字节上游原件）读取帧缓冲、内存图、HHDM、RSDP、模块列表与 SMP 信息。不自研引导协议。

版本唯一来源：仓库根 version.toml，构建期由 tools/gen-version.py 生成内核版本模块；UI、ISO 命名、包元数据一律取值于此，禁止硬编码版本串。

§3 IPC 与能力模型

IPC 是系统的唯一血管，两类通道各管一头：

同步 RPC（快路径）：请求-应答式，调用方挂起、服务方运行。小消息走寄存器直传（L4 式 fastpath：能力槽号 + 消息标签 + 若干寄存器字），大块数据用共享缓冲零拷贝——IPC 原语带「借用页」语义：发送方把页面临时映射进接收方地址空间，应答返回即收回，不复制。性能预算：同核往返真机目标 ≤ 1μs，QEMU 上以串口计时实测并记录基线。

异步事件总线：发布-订阅频道，设备事件、状态变化、通知走这里。频道本身是能力——订阅就是拿到一个频道的监听端点。inputd 的事件流建立在这层之上。

能力对象：64 位句柄 + 内核侧对象表（引用计数 + 权限位）。权限位按对象类型定义：文件能力有读/写/追加，端点能力有调用/应答，DMA 缓冲有映射/回收。能力可随消息传递（系统的授权方式：initd 把块设备能力递给 fsvrd，fsvrd 把挂载点能力递给 posixd），可吊销（服务崩溃重启时旧端点全部失效，调用方拿到明确错误码后经 hub 重绑）。

服务重启语义：initd 对每个服务执行声明重启策略——默认崩溃后按退避重启（3 次内立即，之后指数退避）。调用方持有的端点能力失效但引用不悬空，RPC 返回 ECONNRESET 等价错误，由 libsoke64 封装成重试或报错。

§4 进程/服务地图

全系统服务一张表，启动顺序即依赖顺序：

设备驱动不在本表内：按规则第 30 条它们是 ring-0 内核组件，随内核镜像一同加载，由内核设备模型登记；devd 负责的是用户态可见的设备枚举与服务匹配。

依赖红线从这张表机械化检查：wmshell 只准依赖 Soke Display Server/inputd 端点，永不直接碰块设备或网络能力；spe 装驱动包时只跟内核驱动注册表与 devd 说话。桌面侧组件（启动序 7–11）的进程协议细节以桌面规范五册为准，本表只锁进程边界和启动顺序。

服务间协议以接口描述文件（IDL）定义、生成 Zig / C++ 两种 stub，协议版本随四段版本的 Minor 走，向下兼容。

§5 Soke64 API 与 POSIX 面

Soke64 API = libsoke64，C++ 实现 + 纯 C ABI 头（规则：Soke64 API = C++）。C ABI 是唯一边界：句柄为值类型、错误用负返回值而非 errno、字符串带长度不假设 NUL 结尾；C++ 侧在其上提供 RAII 封装。它是应用唯一该对着的 API，内部分四块：

• 能力封装：能力句柄的类型安全包装，资源随 RAII 释放。
• IPC stub：IDL 生成的服务代理，同步 RPC 和事件订阅统一封装。
• 内核面：少量直接 syscall——线程、内存、时钟、能力操作。应用平时不碰。
• 系统门面：窗口、包查询、设备查询的高层封装。

内核 syscall 面收敛在六个域，共 40~60 个：线程域（spawn/yield/setname…）、地址空间域（map/unmap/clone…）、能力域（grant/revoke/dup…）、IPC 域（call/reply/subscribe…）、内存域（heap/借用页…）、时钟域（now/sleep…）。编号按域分组预留，Minor 版本只加不改；编号的单一来源是 libsoke64 的 syscall.h，内核侧表由它生成，防止两侧漂移。

POSIX 兼容由 posixd 承担，目标 POSIX.1-2024 主干子集：

• fork：内核提供 COW 地址空间克隆原语，posixd 编排语义——克隆地址空间、复制 fd 表能力、登记进程组。
• execve：ELF 加载器在内核内（ET_EXEC 与 ET_DYN 都支持，动态链接器随 ELF 一起加载），posixd 编排语义。
• 信号：posixd 把信号投递到目标进程的信号端点，libsoke64 提供栈上 trampoline，语义对齐 FreeBSD。
• 一切皆文件：fsvrd 的目录树里，/dev 由 devd 挂接（设备能力映射成文件节点）、/proc 由 posixd 挂接、/net 由 netd 挂接。管道与重定向由 shell + posixd 的 fd 传递实现。
• shell：交互 shell 是 zsh 的上游移植（.spk 组件，锚最新版），fd 传递走 posixd。

诚实声明：不承诺 System V 共享内存语义（用能力共享缓冲替代）、不承诺 fork 后继承全部线程（POSIX 本来也不承诺）。

§6 驱动模型

两级结构：SDF（Soke Driver Framework，内核内驱动框架）+ Soke Display Driver Model（SDF 的显示族规范）。

驱动是 ring-0 内核组件，由 Zig 编写、静态链接进内核镜像（规则：驱动 = Zig，内核驱动 = ring 0），通过内核设备模型注册，拿到的是内核内资源句柄：

• MMIO 窗口：基址 + 长度 + 权限位，经 HAL 显式映射（Limine 的 HHDM 不映射 MMIO 区域）。
• 中断：内核内注册向量处理，驱动在 ring-0 直接确认 EOI。
• DMA 缓冲：物理连续或 scatter-gather；QEMU 无 IOMMU 阶段由内核 DMA 池分配兜底，真机阶段接 IOMMU。

总线拓扑：总线驱动（PCI/PCIe 枚举，二期 ACPI 补全）在内核内枚举设备节点，内核驱动框架按设备 ID 匹配已注册的驱动。可加载内核模块形式（.spk 的 drv 类型，签名校验后加载）为远期形态，一期静态链接。

驱动生命周期状态机：probe → attach → ready → error → detach。error 走驱动内复位与退避重试；驱动崩溃是内核级故障，必须 panic 并留下诊断证据，不做"重启驱动进程"的假隔离。

显示族（Soke Display Driver Model）：KMD 接口固定为 connector/mode/scanout 三组对象 + present 队列；GPU 驱动同时暴露 Vulkan ICD 共享对象（经动态加载器接入用户态）。渲染链锁定：应用 → compositord → Soke Display Server → GPU 驱动 → 帧缓冲 → 输出。

§7 存储栈

Btrfs 实现：fsvrd 内的自研生产级实现，on-disk 格式严格遵循 Btrfs 官方格式规范（不拷贝 GPL 源码，格式兼容、代码自有）。范围明确：支持单盘、子卷、快照、CRC32C 校验和、zstd 透明压缩；不做 RAID（non-goals）。

VFS 路由层在 fsvrd 内，文件系统以插件注册：

合成目录树：/dev 由 devd 挂接、/proc 由 posixd 挂接、/net 由 netd 挂接、/pkg 由 spe 挂接（已装包的只读视图）。挂载协议统一：服务向 fsvrd 申请挂载点能力，再往里合成节点。

IO 路径：应用 open() → posixd（fd 语义）→ fsvrd（Btrfs 逻辑）→ 块设备能力 → 内核块驱动。全链路能力检查，任何一环拿不到能力就是明确的 EACCES。

快照与回滚：updd 每次系统更新前对根子卷打快照（命名 @snap/<四段版本>），升级失败或新基线起不来时，在 Limine 引导菜单里选旧快照直接回滚。

磁盘布局：GPT 分区表，ESP（FAT32，放 Limine 的 EFI 二进制、limine.conf、内核与首批模块）+ Soke 根分区（Btrfs，子卷划分 @（根）、@home、@snap、@pkg）。内核镜像与首批模块一期放 ESP（引导链最短、可验证），二期迁到 Btrfs 根 /system/boot/——快照回滚时内核版本跟着快照走。

§8 引导链

引导器是上游 Limine（最新版，vendor 接入，不自研）：UEFI 优先，BIOS/CSM 不支持——虚拟机走 OVMF，真机 UEFI 原生，不为 CSM 维护 16 位 legacy 路径。

启动顺序：

1. Limine 从 ESP 读 limine.conf（菜单、超时、默认项），按配置装载内核 ELF 与首批模块（initd、logd、devd、fsvrd、posixd——一次性全加载，避免内核起来后依赖自己的引导 IO 栈）。
2. 内核经 Limine 引导协议取得硬件事实：内存图、HHDM 偏移（运行期值）、帧缓冲（含位深与通道掩码）、RSDP、可执行地址、模块列表、SMP 拓扑。
3. 内核把 Limine 响应收编为内部引导事实结构，随后自建内核地址空间与 per-CPU 结构。
4. SMP 由 Limine 的 MP 服务启动 AP（内核提供 AP 入口，Limine 负责 INIT-SIPI 与 trampoline），不使用自研 trampoline。

安全启动链：生产模式下由引导链与包管理器承担签名校验（根公钥随发布工程定义），失败拒绝引导/拒绝安装；开发模式由构建配置关闭校验并在引导事实里打标志。开发/生产的分界是构建时的策略，不是运行时旋钮。

安装介质：UEFI 可引导 ISO（xorriso 制作，El Torito UEFI 目录，limine-uefi-cd.bin），ISO 命名按规则格式 Soke{VERSION}_{pre/sv/beta}_{VERSION2}_{LANGUAGE}_{BIT}_{VERSION3}.iso（示例见 CLAUDE.md 规则 24，实际值取自 version.toml）。磁盘镜像工具与 ISO 制作脚本走 bash + python3（仅标准库），LF 强制，无 WSL。

§9 SPK / SPE 包体系

.spk 容器：zstd 压缩的 tar 流，确定性构建（固定文件顺序与 mtime，同输入必得同哈希），内含三部分——

• manifest（TOML）：包名、四段版本、ABI 目标（soke64-1）、架构、包类型、依赖（带版本区间）、能力声明（这个包需要哪些系统能力）、文件清单（逐文件 SHA-256）、发布者签名（ed25519，detached）。
• data/：文件树，按包类型映射安装路径——app → /pkg/apps、lib → /pkg/lib、drv（内核驱动）→ /pkg/drv、font → /pkg/fonts、locale → /pkg/share/locale。
• 触发器：纯声明式——注册系统服务、注册内核驱动设备 ID、刷新字体缓存。禁止在包里跑任意脚本，安装器不做脚本解释器。

spe 包管理器（Zig，CLI）：install / remove / upgrade / search / history / rollback。安装是事务——新文件落 staging 子卷，校验清单哈希与签名，通过后原子切换，updd 在事务前打系统快照，失败即回滚。驱动包安装后向内核驱动注册表登记设备 ID，设备出现时按需加载。

仓库：签名索引 + 包文件的 HTTP(S) 仓库，本地缓存 /var/cache/spe。仓库索引由发布者密钥签名，spe 只信验证过的索引。仓库服务端是配套工程（HTTP 服务 + 索引签名工具），接口在本总纲锁定，实现单独立项。

ABI 纪律：soke64-1 是 ABI 目标代号，Minor 版本迭代必须向下兼容，破坏性变更只能换 ABI 代号随 Major 走。

§10 安全模型

TCB 清单：Limine + SNMK 内核（含 ring-0 内核驱动）+ initd（能力根）。内核之外的用户态服务——文件系统、网络、POSIX 语义、显示栈——在 ring-3 隔离舱里，崩了重启，TCB 无恙。

纵深四层：

1. 能力即权限：文件句柄、设备、端点、DMA 缓冲全是能力对象，没有环境权限。initd 按 .spk manifest 里声明的能力授予，服务拿不到清单之外的东西——声明与授予是同一套机制，安装时用户可见。
2. 进程硬化：每服务独立地址空间；全程 W^X；内核栈与用户栈都开保护页；ASLR 熵由内核引导期收集；用户程序默认不带 JIT 权限（W^X 冲突的组件要显式申请可写可执行映射能力）。
3. 签名链：ed25519 根密钥 → 引导链校验内核与首批模块 → spe 校验包与仓库索引 → 内核在加载驱动模块前二次校验。开发模式整链可关，生产模式整链强制，分界在构建时。
4. 崩溃恢复：用户态服务三退避重启 + 端点重绑；单个服务被攻破拿不到别的服务的能力，最多瘫痪自己。内核驱动运行在 ring-0，失效即内核级故障，按 panic 处理并留诊断证据——这是规则第 30 条选定的取舍。

没有 setuid。系统管理操作（安装、更新、改服务清单）走 authd 认证后由能力授予完成，管理员是一个能力集合而不是一个用户 ID。POSIX 兼容层对传统应用呈现 fd/进程语义，但不把 setuid 语义放进内核。

§11 构建系统与工具链

统一编排：build.zig 是唯一构建入口，所有编译单元挂进同一棵依赖图——FASM（汇编桩）、Zig（HAL / 内核 / 驱动 / 用户程序）、C++（Soke64 API，-ffreestanding，无 libstdc++）、移植组件经各层构建单元挂入。交叉目标是 x86_64-freestanding-none（内核用 code_model=kernel）。

语言矩阵（规则，优先级高于一切）：汇编 = FASM、UEFI 引导加载器 = Limine（上游）、HAL = Zig、内核 = Zig、Soke64 API = C++、驱动 = Zig、用户程序 = Zig。

第三方 vendor 策略：一律锚定上游最新版（含预览版），vendor 目录固定版本并记录来源哈希，禁止降级，禁止自研冒充第三方。清单：Limine 最新版、FreeBSD 最新 RELEASE（只取所需子系统源码，白名单排除 CDDL/GPL/厂商固件）、Vulkan 头文件与加载器最新、Qt 6.x 最新、zstd。

模块化铁律：一个子系统一个目录一个构建单元，模块间只准走声明过的接口依赖；build.zig 按依赖图做增量，全系统禁止「编进一个大文件」。

开发环境：Linux 原生 + bash（禁止 WSL / Git Bash）。QEMU + OVMF 做验证闭环：tools/init-devenv.sh 做环境自检，tools/start-soke.sh 一条命令跑完构建 → 镜像 → 无头启动 → 串口日志，镜像由 tools/New-SokeDisk.py（python3，仅标准库）产出。CI 与开发主机同构，均为 Linux 无头构建与测试。文本文件全程 LF，.gitattributes 强制。

§12 版本与发布工程

四段版本 Major.Minor.Build.Revision，管理按六场景规则机械执行：月度累积更新 Build 小幅递增、Hotfix 只动 Revision、功能迭代 Build 大跳、次版本迭代 Minor+1、架构重构 Major+1、SP 只加介质标签不动四段。

唯一来源：仓库根 version.toml（Major/Minor/Build/Revision + settings.edition），构建期由 tools/gen-version.py 生成内核版本模块；UI、ISO 命名、包元数据一律取值于此，版本 bump 只发生在里程碑提交，提交信息写清改动与验证方式。

对外展示：设置「关于」页显示对外分代与季度代号（形如 OS 5 26H2，仅作宣传名称，不写入内核版本）+ 内部四段版本（+SP 标签）。用户可见界面一律不出现品牌、团队、内核与由来信息，版权行固定为 Copyright © 2026 Nexsteaduser. All Rights Reserved.

介质：ISO 命名按规则 24 格式 Soke{VERSION}_{pre/sv/beta}_{VERSION2}_{LANGUAGE}_{BIT}_{VERSION3}.iso，字段取自 version.toml；SP 整合介质只加介质标签，四段版本不动。

§13 路线图

口径：一期 = P0–P3（虚拟机线），二期 = P4（真机线），正文沿用此口径。

红线（实现时不可越）

1. TCB 是 Limine、SNMK 内核（含 ring-0 内核驱动）、initd；用户相关程序一律 ring-3，内核驱动一律 ring-0，两者不得互换。
2. 能力即权限：任何服务不得绕过能力检查获得资源。
3. 输入、窗口管理、合成三大职责独立进程，禁止回并。
4. 渲染链固定：应用 → 合成引擎 → 显存帧缓冲 → GPU 驱动 → 完整显示输出。
5. 全链路 10.7 亿色（10bit），任何环节不得引入调色板、VGA、VBE。
6. 液态玻璃逐项复刻 shuding/liquid-glass，禁止用「半透明 + 高斯模糊」冒充。
7. 不声称未实现的东西：每阶段验收以 QEMU/真机实测证据为准。
8. 版本管理按四段规则机械执行，Build 号永不回退、永不复用。

子系统细设册清单

总纲定稿后，子系统细设照桌面规范的模式逐个开册，每册独立定稿、独立验收：