概述
virgiling/dotfiles 统一管理我在 macOS 与 Arch Linux 上的个人配置与软件清单。三个组件的分工如下：
chezmoi管理配置，mpm登记软件，Git保存两者。
配置与软件按平台分开维护，只共享确实通用的部分；软件安装仍由 Homebrew、npm、Cargo 等原包管理器负责。
为什么选择这套工具
需求
- 同时覆盖 macOS 与 Linux 两套环境，配置按平台区分。
- 只保存文件，不引入一套会接管整个操作系统的机制。
- 能够从已经配好的电脑登记环境，而不是在新机器上重新安装一遍。
- 保留一份「配置 ↔ 软件版本」的基准，供换机 / 重装时对照。
排除的方案
- Nix：提供的是「可复现操作系统」级别的能力，会额外占据大量磁盘空间，且与已有的
Homebrew使用习惯冲突。本场景只需要「存文件 + 一定的可复现性」，不需要切换整个系统。 - Homebrew Bundle（Brewfile）：只能覆盖
Homebrew来源，管不到npm install -g、cargo install等全局安装；且官方明确 Bundle 没有版本锁文件，无法做版本冻结。 - mise：重心在「接管工具的安装」（
mise install会实际安装），而本场景要的是「登记已有环境」，方向相反。
最终分工
| 组件 | 职责 | 边界 |
|---|---|---|
chezmoi | 管理配置文件（dotfiles），按系统区分配置 | 只管文件，不装软件 |
mpm | 读取各包管理器的现有安装，导出成 TOML 清单 | 只登记，不安装、不升级 |
Git | 版本化配置与清单，跨机器同步 | 记录改动，不做后台实时双向同步 |
Homebrew / npm / Cargo | 继续负责原来的软件安装 | 不迁移到统一工具 |
「版本冻结」被拆成两件独立的事：记录当前已验证的版本（mpm 导出清单 + 提交）与阻止包管理器 / 应用改变版本（登记工具做不到，Homebrew 滚动更新也不支持任意历史版本恢复）。因此本仓库保存的是一份「经过验证的版本基准」，而非「永远不升级」的锁。
如何使用
配置：chezmoi
common/、macos/、linux/ 是同一个 Git 仓库里的三个独立 chezmoi source：先处理 common/，再处理当前系统的 source。dot_config 对应 ~/.config，common/dot_agents 对应 ~/.agents。
以 Mac 的 Ghostty 配置为例：
cd /path/to/dotfiles
# 把本机配置保存到仓库副本
chezmoi --source "$PWD/macos" --working-tree "$PWD" add --secrets=error ~/.config/ghostty/config
# 分别预览共用配置和 Mac 专用配置的差异
chezmoi --source "$PWD/common" --working-tree "$PWD" diff
chezmoi --source "$PWD/macos" --working-tree "$PWD" diff
# 需要把仓库配置写回本机时，确认差异后再执行
chezmoi --source "$PWD/macos" --working-tree "$PWD" apply ~/.config/ghostty/config两条基本语义：
add默认保存文件副本，不建立实时符号链接；apply才把仓库配置写到目标位置。文件不会在两者之间自动同步。- 仓库根目录不是 source，不使用
chezmoi init --apply virgiling自动应用整个仓库。
软件清单：mpm
根目录只有两个清单：macos.toml 与 linux.toml。其中 [brew]、[cask]、[npm]、[cargo]、[uvx] 由 mpm 导出，[manual] 手动登记所选本机应用。
Mac 上重新导出（mpm 8.0.0+）：
mkdir -p tmp
mpm --no-config --stop-on-error --jobs 1 --timeout 30 \
--brew --cask --npm --cargo --uvx dump --overwrite tmp/macos.toml导出只查询所选管理器，不安装或升级软件；确认差异后再用 git diff --no-index 对比、人工核对后替换。清单是现状登记：既不是「必须安装的清单」，也不是「保证完整复现环境的锁文件」。
配套提交：Git
一次升级被当作一个完整变更：选定新版本 → 更新对应平台配置 → 验证工具与配置能一起工作 → 把版本清单、依赖附属文件与 dotfiles 一并提交。回退时同样要同时恢复「软件」与「配置」两部分，仅回退 Git 文件不会自动回退已安装的软件。
搭建方式
本仓库由 agent 自动化搭建：目录结构、文档、测试与项目级 agent 约定，均在工具选型确定后自动生成与整理，人工只做核对与微调。
dotfiles/
├── AGENTS.md # 仅本项目的 agent 工作约定
├── .agents/ # 仅本项目的维护与配置同步 skills
├── common/ # Mac 和 Linux 共用的 ~/.agents 规则与 skills
├── macos/ # Mac 专用配置，包括 Fish、Ghostty
├── linux/ # Arch Linux / Hyprland 专用配置
├── macos.toml # Mac 软件清单（mpm TOML 格式）
├── linux.toml # Linux 软件清单，目前留空
├── docs/
│ ├── usage.md # 配置管理、软件登记和 Git 同步教程
│ ├── macos.md # Mac 软件及用法
│ └── linux.md # Linux 软件及用法
└── tests/ # 配置布局和清单检查几个关键点：
- 根目录的 TOML 清单、文档和项目
AGENTS.md/.agents/不会部署到家目录；common/dot_agents/里的全局用户规则与项目.agents/是两套独立内容。 - 项目级 skill（
maintain-dotfiles、sync）只用于维护本仓库；tests/用Python unittest校验配置布局与清单，验证时使用临时 home 与 source，不指向实际家目录。 - 之前的
hyprland-dotfiles仓库里的 Hyprland 配置，即现在linux/dot_config/hypr/那一套（另有 kitty、rofi、waybar、mako、swaylock、fusuma 等），旧仓库已删除。
完整的教程、Mac / Linux 的软件清单与用法见仓库的 docs。