拆解方法¶

本项目参考 dg-ai-notes 对 pi-0.82.0 的讲解方式：不做文件清单式注释，而是从问题、心智模型和真实调用链进入实现，再回到设计取舍。内容与结构均针对 Omarchy 重新分析。

四层证据¶

每个结论尽量同时落在以下证据中的一层或多层：

入口证据：可执行文件、systemd unit、desktop session 或 IPC handler；
状态证据：文件、marker、锁、环境变量、快照或 QML property；
副作用证据：包事务、服务启停、配置生成、进程重启；
测试证据：CLI 契约测试、纯 JS 单测或图形验收脚本。

仅凭文件名推测的内容不写成确定结论。调用顺序以脚本中的 source / exec、QML Loader、systemd 依赖与测试断言为准。

分析步骤¶

flowchart LR
    Inventory[静态盘点] --> Entry[识别入口]
    Entry --> Trace[追调用与状态]
    Trace --> Boundary[标注权限/信任边界]
    Boundary --> Test[用测试反证]
    Test --> Explain[组织 why/how/what]

1. 静态盘点¶

统计顶层目录、脚本、QML/JS/Lua、迁移、主题、插件清单和测试入口。盘点的作用是确定系统重心，不用文件数量替代架构判断。

2. 入口优先¶

从以下入口反向追踪：

bin/omarchy 与具体 omarchy-* 命令；
omarchy-apply-system、用户 finalizer 和 first-run；
UWSM desktop session 与 shell.qml；
omarchy-update、迁移器和一次性 Quattro 升级器；
CLI、Shell 与 acceptance test runner。

3. 区分四类状态¶

将 packaged defaults、用户意图、生成结果和瞬态握手分开。许多错误来自把生成文件当配置改，或把 /etc/skel 当作持续同步源。

4. 用失败路径检验理解¶

成功路径常把边界藏起来。我们特别检查：

迁移失败时 marker 是否写入；
Shell 未运行时 CLI 是否自动拉起；
主题含 Lua 或符号链接时如何处理；
插件 manifest 非法或 ID 冲突时谁胜出；
升级验证失败时能否进入 reboot cutover。

数字如何产生¶

命令数来自 bin/omarchy-* 的前 80 行元数据解析；主题、插件、迁移和测试数来自固定快照的目录遍历。附录中的 CLI 命令全集由仓库脚本生成，减少人工抄录错误。

引用规则¶

所有上游源码链接固定到完整 commit SHA；
少量片段只用于解释接口，并链接回 MIT 许可的上游项目；
本站不复制上游整份文档，而是用自己的结构解释代码；
“为什么”若是从实现推导而非上游明说，会明确写成“这意味着”或“可以推断”。

已知限制¶

静态分析无法证明图形渲染、特定 GPU、音频拓扑与真实启动固件在所有机器上的表现。本文把这些内容标为需要验收的运行时假设，不把已有脚本等同于普遍硬件支持。