版本与范围¶
固定快照¶
| 项目 | 值 |
|---|---|
| 上游仓库 | basecamp/omarchy |
| 分支语境 | quattro |
| commit | ef6d9e6605b121df15bf310e630e04f0c1119fc8 |
version 文件 |
4.0.0.alpha |
| commit 时间 | 2026-08-23 14:43:31 UTC |
| 上游许可 | MIT |
本地分析样本中的关键文件哈希与该上游 commit 一致，包括 bin/omarchy、shell/shell.qml、version 和 docs/file-layout.md。因此文档统一引用这个可复现快照，而不是会移动的分支头。
静态盘点¶
| 类别 | 快照值 | 注释 |
|---|---|---|
| 仓库文件 | 1,653 | 包含资源与文档 |
omarchy-* 命名文件 |
432 | 其中 430 个可执行并被 router 注册 |
| 注册命令可见性 | 361 / 69 | 可见 / 隐藏 |
| 注册命令声明 sudo | 84 | 另有 2 个非可执行文件也带 sudo 元数据 |
| CLI 分组 | 72 | 按路由首段聚合 |
| 迁移脚本 | 86 | 文件名按时间戳排序 |
| 内置主题 | 22 | $OMARCHY_PATH/themes |
| 插件 manifest | 37 | schemaVersion 1 |
| QML | 104 / 约 35,020 行 | Shell 主要 UI 与服务 |
| JavaScript | 30 / 约 4,745 行 | Shell 可独立测试逻辑 |
| Lua | 72 / 约 1,728 行 | Hyprland 模块配置 |
| Shell 测试文件 | 191 | 含公共 harness |
| Acceptance 文件 | 7 | 含公共 harness，6 条工作流 |
这些数字只用于帮助把握规模。架构结论依赖调用关系，不依赖行数排名。
包含什么¶
- Quattro 的 package-backed 文件布局；
- root 安装、延迟 provisioning、用户 finalization 和 first-run；
- UWSM、Hyprland Lua 加载与动态状态；
- CLI 元数据路由、帮助、校验和 dispatch；
- Quickshell、插件、菜单、主题和桌面服务；
- 包管理、更新、迁移、渠道、硬件和恢复；
- 旧版到 Quattro 的一次性升级器；
- CLI/Shell/图形验收的测试分层。
不包含什么¶
- 对未来 commit 的兼容承诺；
- 安装到具体物理机器的逐步教程；
- 每个 QML 组件的像素级视觉说明；
- 每个
omarchy-*命令的用户手册（附录只做结构化索引）； - 对 Arch、Hyprland、Quickshell 或 systemd 的通用入门。
上游变更提示¶
该快照的最后一个 commit 强化了主题安装边界：从远程安装的主题不能携带可执行 Lua、终端配置等代码型文件，并且 staging 不跟随符号链接。这是本文 主题 与 安全 两章的重要案例。
若阅读更新版本，应先比较以下高耦合文件：