macOS 换机/重装时采集旧系统软件与配置生成 JSON…

适用于 macOS 换电脑、重装系统或从 Time Machine 恢复时，把旧机软件、包管理器和配置采集为清单，再在新机按清单还原。

适用场景

解决思路

1. 在旧系统上先做一次 Time Machine 全量备份，作为迁移安全网与还原阶段的数据来源；没有 Time Machine 全量备份就不要开始迁移。
2. 判断运行模式只看清单文件是否存在：执行 `ls ~/migration-manifest.json 2>/dev/null`。无清单文件为采集模式（旧系统），有清单文件为还原模式（新系统）。Time Machine 只作为还原阶段的数据来源，不参与模式判断；用户也可直接指定「采集」「备份」「还原」「迁移」。
3. 两种模式都先检查 Homebrew：执行 `which brew && brew --version || echo "NOT_INSTALLED"`。已安装则继续；未安装则引导用户在终端手动执行 `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"`，因为需要输入管理员密码（sudo），无法静默完成。
4. Homebrew 安装完成后，按提示把 brew 加入 PATH（Apple Silicon：`eval "$(/opt/homebrew/bin/brew shellenv)"`），再继续。
5. 模式 A：旧系统采集。在旧系统上运行，扫描所有软件、配置、开发环境，生成 `~/migration-manifest.json`。
6. A1 采集 Homebrew 软件包：执行 `brew list --formula`、`brew list --cask`、`brew tap`。
7. A2 采集系统 Applications：执行 `ls /Applications/`、`ls ~/Applications/ 2>/dev/null`，与 Homebrew cask 列表对比，标记哪些是 Homebrew 装的、哪些是手动/App Store 装的。
8. A3 采集 Mac App Store 应用：执行 `mas list 2>/dev/null || echo "mas not installed"`；如果 `mas` 未安装，提示用户是否安装（`brew install mas`）。
9. A4 采集 npm 全局包：执行 `npm ls -g --depth=0 2>/dev/null`。
10. A5 采集 uv 工具：执行 `uv tool list 2>/dev/null`。
11. A6 采集 pip/pipx 包：执行 `pip list 2>/dev/null`、`pipx list 2>/dev/null`。
12. A7 采集 Go 全局工具：执行 `ls ~/go/bin/ 2>/dev/null`。
13. A8 扫描配置文件：执行 `ls -la ~/`，重点采集 Shell 的 `.zshrc`、`.zshenv`、`.zprofile`、`.bashrc`、`.bash_profile`；Git 的 `.gitconfig`、`.gitignore_global`；SSH 的 `.ssh/`；编辑器的 `.claude/`、`.codex/`、`.config/`、`.cursor/`、`.zed/`；容器的 `.docker/`、`.kube/`；包管理器的 `.npm/`、`.nvm/`、`.bun/`、`.cargo/`、`.rustup/`；其他应用配置如 `.SwitchHosts/`、`.ollama/`、`.syncthing/` 等。
14. A8 敏感数据先问后采：`.ssh/`（私钥）、dotfiles 里可能含 token、`.aws/`、`.kube/`、钥匙串等都是密钥级信息。采集这些之前先问用户是否纳入。用户同意则正常采集，并明确提醒「清单和备份里含私钥/凭据，传输、存放、通过网盘或聊天工具发送时注意不要外泄」；用户拒绝则跳过这些项，在清单里记入 `"skipped_sensitive": [...]`，让用户日后自行手动迁移（差异报告里也会再列一次）。
15. A9 采集 LaunchAgents（自启动服务）：执行 `ls ~/Library/LaunchAgents/`。
16. A10 采集用户项目目录：执行 `ls -d ~/*/ 2>/dev/null`，排除系统目录（Library、Applications、Public 等），记录用户自建的项目/数据目录。
17. A11 采集 Shell 环境：执行 `zsh --version`，并执行 `grep -iE 'brew|nvm|fnm' ~/.zshrc` 查看 Homebrew 路径/版本管理器（nvm、fnm 等）配置。
18. A12 采集其他易漏项：执行 `code --list-extensions 2>/dev/null`、`cursor --list-extensions 2>/dev/null`、`ls ~/Library/Fonts/ 2>/dev/null`、`crontab -l 2>/dev/null`、`ls /usr/local/bin/ 2>/dev/null`、`ls /opt/ 2>/dev/null`。系统偏好（`defaults`）量大且与机型强相关，不自动采集；如用户在意，在还原差异报告里提醒手动核对键盘、触控板、Dock、快捷键等。
19. A13 生成清单文件 `~/migration-manifest.json`，写入以下结构：`version`、`captured_at`、`source_macos`、`source_hostname`、`homebrew`（`taps`、`formulas`、`casks`）、`applications`（`homebrew_casks`、`app_store`、`manual`）、`package_managers`（`npm_global`、`uv_tools`、`pip_packages`、`go_binaries`）、`configs`（`dotfiles`、`config_dirs`、`app_support_keys`）、`editor_extensions`（`vscode`、`cursor`）、`fonts`、`crontab`、`manual_bins`、`launch_agents`、`user_dirs`、`shell`（`shell`、`brew_in_path`、`nvm_installed`、`custom_env_vars`）、`skipped_sensitive`。
20. A14 采集完成：输出清单摘要，提示用户确认已有 Time Machine 全量备份，将 `migration-manifest.json` 复制到新系统，再次运行此 skill。摘要包括 Homebrew 数量、应用数量、npm 全局包数量、配置文件数量、编辑器扩展/字体/定时任务、自启动服务、用户目录、跳过的敏感项；若采集了 `.ssh` / dotfiles 中的凭据，提醒清单与备份含私钥，传输存放注意不要外泄。
21. 模式 B：新系统还原。在新系统上运行，读取 `migration-manifest.json` 并逐步还原。
22. B0 获取清单：执行 `ls ~/migration-manifest.json`。如果不存在，提示用户将旧系统上采集的清单文件复制到新系统 home 目录，例如 `scp old-mac:~/migration-manifest.json ~/migration-manifest.json`，或手动指定路径。
23. B1 安装 Homebrew 软件：前提是第零步已确认 Homebrew 装好。读取清单中的 `homebrew` 字段。逐个添加 taps：`brew tap <user>/<repo>`；信任第三方 taps：`brew trust <user>/<repo>`；批量安装 formulas：`brew install <formula1> <formula2> ...`（失败不回滚整批）；逐个安装 casks：`for cask in <cask1> <cask2> ...; do brew install --cask "$cask" 2>&1 | tail -3; done`。没装上的（需 sudo、网络失败等）先记下，最后在 B7 差异报告统一列给用户。
24. B2 安装其他包管理器：读取清单中的 `package_managers` 字段。执行 `npm install -g <pkg1> <pkg2> ...`、`uv tool install <pkg1> <pkg2> ...`、`pip install <pkg1> <pkg2> ...`、`go install <pkg1>@latest <pkg2>@latest ...`。
25. B3 恢复配置文件：读取清单中的 `configs` 字段。数据来源优先级为 Time Machine 直接复制（如果有挂载）、用户手动提供。设置 `TM="<Time Machine 用户目录路径>"`、`LOCAL="/Users/<username>"`；复制 dotfiles：`rsync -av --ignore-existing "$TM/.zshrc" "$LOCAL/"`、`rsync -av --ignore-existing "$TM/.gitconfig" "$LOCAL/"`、`rsync -av --ignore-existing "$TM/.ssh/" "$LOCAL/.ssh/"`；复制配置目录：`for dir in .claude .codex .config .docker .SwitchHosts ...; do rsync -av --ignore-existing "$TM/$dir/" "$LOCAL/$dir/"; done`。恢复 `.ssh/` 后确认权限：`chmod 700 ~/.ssh && chmod 600 ~/.ssh/id_*`。如无 Time Machine，提示用户提供配置文件的来源路径。
26. B4 恢复 Library 关键子目录：从 Time Machine 恢复（如果有）。Preferences、Keychains、Containers、Group Containers、Mail、Safari 均使用 `cp -rn` 复制。注意：rsync 在 Time Machine APFS 快照上会报 `io_read_flush` 错误，Library 用 `cp -rn`。
27. B5 恢复 LaunchAgents（自启动服务）：读取清单中的 `launch_agents` 字段。逐个检查并创建对应的 plist 文件，然后执行 `launchctl load`。
28. B6 还原其他易漏项：对应采集阶段的 A12。编辑器扩展逐个安装：`for ext in <清单 editor_extensions.vscode>; do code --install-extension "$ext"; done`；字体：`rsync -av --ignore-existing "$TM/Library/Fonts/" "$LOCAL/Library/Fonts/"`；定时任务先看新机器有没有现成的，再决定是否合并写入，避免覆盖：`crontab -l 2>/dev/null`。`/usr/local/bin`、`/opt` 里的手动安装工具无法自动还原，列入 B7 差异报告提醒用户。
29. B7 处理未安装项目：对比清单和实际安装结果，输出差异报告。报告分组包括：安装失败（需手动处理）如 docker-desktop 需要 sudo 则手动执行 `brew install --cask docker-desktop`、tailscale-app 需要 sudo 则手动执行 `brew install --cask tailscale-app`、android-platform-tools 网络问题则稍后重试；清单中有但无 Homebrew cask，如 Final Cut Pro 为 App Store 应用、DaVinci Resolve Studio 手动下载到 blackmagicdesign.com；App Store 应用需手动安装或用 `mas`；需手动核对（非软件）如系统偏好 `defaults` 的键盘/触控板/Dock/快捷键、`/usr/local/bin`、`/opt` 手动工具、拒绝采集的敏感项。
30. 踩坑 1：不要用 `brew bundle --file=Brewfile`，因为任何一个 cask 下载失败，整批已安装的包全部回滚。解决：taps 逐个添加，formulas 批量安装，casks 逐个安装。
31. 踩坑 2：Homebrew 6+ 要求显式信任第三方 taps，否则报 `Refusing to load cask from untrusted tap`。解决：执行 `brew trust <user>/<repo>`。
32. 踩坑 3：`rsync -av --ignore-existing` 复制 Library 子目录时在 Time Machine APFS 快照上报 `io_read_flush` 错误。解决：Library 子目录改用 `cp -rn`。
33. 踩坑 4：`cp -rn` 遇到 macOS SIP/TCC 保护的文件会报 `Operation not permitted`（系统 Preferences、Mail 数据库等）。不影响使用，系统或应用首次启动时自动重建。
34. 踩坑 5：`cp -rn` 遇到 Containers 中系统容器使用符号链接指向标准目录时会报 `Not a directory`。不影响使用，用户应用的容器数据已正确复制。
35. 踩坑 6：需要 sudo 的 casks 如 `docker-desktop`、`tailscale-app`、`adobe-creative-cloud` 安装时需要 sudo。解决：记录在差异报告中，让用户手动执行。
36. 踩坑 7：`brew install node@22` 后 `brew link` 失败。解决：执行 `brew link --overwrite node@22`。
37. 踩坑 8：Homebrew 检测不到非 Homebrew 安装的软件（通过 DMG/PKG/App Store 安装）。解决：采集阶段扫描 `/Applications/` 并与 `brew list --cask` 对比，标记手动安装的应用，还原时单独处理。
38. 原则 1：先有 Time Machine 全量备份再开始，这是出错时唯一的兜底，也是还原的数据来源。
39. 原则 2：Homebrew 由用户手动安装，需要输密码（sudo），引导用户在终端执行，装好再继续。
40. 原则 3：两阶段分离，采集和还原是独立步骤，通过 JSON 文件衔接。
41. 原则 4：敏感数据先问后采，私钥/凭据采不采由用户决定；采了就提醒外泄风险。
42. 原则 5：绝不覆盖已有文件，所有 rsync/cp 都带 `--ignore-existing` 或 `-n`。
43. 原则 6：先小后大，按目录大小排序复制，方便快速验证。
44. 原则 7：先做计划再动手，还原前输出清单摘要，让用户确认。
45. 原则 8：记录差异，还原后输出差异报告，列出需要手动处理的项目。
46. 原则 9：逐个安装 casks，避免 `brew bundle` 的回滚问题。
47. 原则 10：验证每一步，安装后 `brew list` 确认，复制后 `du -sh` 验证大小。
48. 原则 11：跳过缓存，Library/Application Support 中的缓存数据不恢复。

适用边界 · 注意事项

• 没有 Time Machine 全量备份，或无法提供配置文件来源路径时，不要开始迁移。
• 不是 macOS 环境，或无法在终端手动安装 Homebrew（需要 sudo）时，本技能不适用。
• 需要自动迁移系统偏好（defaults）、缓存数据或机型强相关设置时，本技能不自动处理，需手动核对。