阅读指南¶
这套拆解既可以从头读，也可以当作故障地图。最省时间的办法，是先确定你正在追哪一种状态变化。
先用三个问题定位¶
- 谁在执行？ root、普通用户、图形会话中的用户，还是 Quickshell 进程？
- 状态写到哪里？
/etc、~/.config、~/.local/state，还是$XDG_RUNTIME_DIR？ - 它是声明还是副作用？ JSON/QML/Lua 描述“应该是什么”，Bash 命令真正修改系统。
这三个问题能解释 Omarchy 中大部分看似重复的入口。例如系统安装完成，不代表用户级 systemd、DConf、音频或通知已经可用；因此 omarchy-apply-system、omarchy-provision-user 与 omarchy-first-run 必须分开。
按目标选择路径¶
| 你的目标 | 建议章节 | 最终应该能回答 |
|---|---|---|
| 理解全局架构 | 01 → 02 → 03 → 18 | 一次安装如何变成可交互桌面 |
| 增加一条命令 | 05 → CLI 命令全集 | 元数据、快速路由和帮助如何协作 |
| 修改 Hyprland 默认值 | 04 → 06 | 默认模块与用户模块谁覆盖谁 |
| 写 Shell 插件 | 07 → 08 | 何时加载、如何启用、哪些路径不可信 |
| 扩展菜单 | 09 → 06 | dotted ID 如何合并，guard 如何求值 |
| 制作主题 | 10 → 15 | 主题如何编译、原子切换、过滤代码 |
| 排查更新失败 | 13 → 15 → 18 | 锁、快照、事务屏障、迁移标记在哪里 |
| 适配新硬件 | 14 → 17 | 探测器、幂等脚本与验收边界 |
| 理解旧版升级 | 16 → 02 → 13 | 如何从 git 布局切到 package 布局 |
阅读每章时看什么¶
每章中的图有三种语义：
- 实线箭头表示直接调用或数据读取；
- 状态节点表示进程之间共享的持久事实；
- 边界节点表示权限、信任或生命周期发生变化。
源码链接固定到同一个 commit。链接中的行号是导航提示；如果 GitHub 后续改变渲染，文件内容仍由 commit 保证一致。
不要把目录名当成运行顺序
install/、default/、config/ 与 bin/ 是责任分区，不是生命周期顺序。真正的顺序要从入口脚本的 source、exec、systemd unit、UWSM 环境和 IPC 路由还原。
四个贯穿全文的对象¶
OMARCHY_PATH¶
“当前使用哪一份 Omarchy 程序和资源”的统一答案。生产环境通常是 /usr/share/omarchy；开发环境可通过 /etc/omarchy.conf 指向 checkout。
~/.local/state/omarchy/current¶
生成状态的活动视图。当前主题、动态 Hyprland 模块等都在这里；它不是用户手写配置。
done / migration marker¶
两种不同的完成事实。done marker 记录一次性生命周期动作，migration marker 记录某个版本迁移是否已成功执行。
Quickshell IPC¶
CLI 与常驻桌面进程之间的窄桥梁。命令只转发，不负责偷偷启动 Shell；因此“Shell 未运行”会作为真实失败暴露出来。
本文的边界¶
本文解释源码中可以证明的行为，不替代官方安装手册，也不假设所有硬件都已覆盖。视觉效果、GPU 行为和图形会话时序仍需要在真实或可丢弃虚拟机中验收。具体范围见 版本与范围。
下一章从最重要的心智模型开始：01 · 全景与心智模型。