Dev Environment · Field Manual

一台 Mac
AI Agent
开发圣所

从零开机到多 Agent 并行作战。适用所有 Apple Silicon Mac —— MacBook、iMac、Mac Studio、Mac Mini。本指南遵循一条铁律:一切用代码声明 —— Brewfile、dotfiles、bootstrap 脚本,换机 30 分钟完整复原。终端是主战场,Claude Code / Kimi Code / Codex / DSH / PI / WorkBuddy / ZCode 七件套并存,各取所长。

macOS · Apple Silicon Homebrew + Brewfile Ghostty · zsh · Starship mise + uv Multi-Agent Workflow
🤖 我是 Agent —— 把这段话发给我
阅读 https://x5.github.io/new-mac-setting/mac-mini-ai-dev-setup.zh-CN.md ,
一步步为这台 Mac 完成开发环境配置。批量安装优先运行 setup.sh。
任何不可逆操作前先向我确认。
🧑 我是人类 —— 一键安装
curl -fsSL https://x5.github.io/new-mac-setting/setup.sh | bash
Scroll
01
macOS Layer

系统初始化defaults write

开机向导里开启 FileVaultFileVault · 全盘加密macOS 的全盘加密。Apple Silicon 的数据卷默认已加密,FileVault 把解密钥匙绑定到登录密码——不登录谁也读不了盘。你的 SSH 私钥和 API Key 全靠它兜底,性能损耗≈0,必开,并保管好恢复密钥。 磁盘加密;先别开 iCloud 桌面同步。然后用 defaults writedefaults writemacOS 偏好设置的命令行接口,直接读写应用配置。可脚本化、可进 dotfiles,新机器跑一次全部生效,不用手点系统设置。 把系统偏好调成开发者形态 —— 全部可进 dotfilesdotfiles以 . 开头的隐藏配置文件(.zshrc、.gitconfig、.config/…)。收进 git 仓库管理 = 配置即代码,新机器一键恢复全部设置,详见第 13 章。,换机自动生效。随后安装 Xcode 命令行工具Xcode CLT苹果独立的命令行开发工具包(git、clang、make 等),不用装完整 Xcode。Homebrew 和几乎所有编译工具都依赖它。,这是一切编译链的前提。

zsh — system defaults
# 键盘:最快的按键重复与最短延迟
defaults write NSGlobalDomain KeyRepeat -int 1
defaults write NSGlobalDomain InitialKeyRepeat -int 10

# 触控板:轻点即点击
defaults write com.apple.AppleMultitouchTrackpad Clicking -bool true

# Finder:显示扩展名 + 状态栏 + 路径栏
defaults write NSGlobalDomain AppleShowAllExtensions -bool true
defaults write com.apple.finder ShowStatusBar -bool true
defaults write com.apple.finder ShowPathbar -bool true

# Dock:自动隐藏、关掉最近使用
defaults write com.apple.dock autohide -bool true
defaults write com.apple.dock show-recents -bool false

# 截图统一存到 ~/Screenshots
mkdir -p ~/Screenshots
defaults write com.apple.screencapture location ~/Screenshots

killall Finder Dock
zsh — prerequisite
# Xcode 命令行工具:git、clang 等一切编译链的前提
xcode-select --install
02
Foundation

Homebrew:一切的地基brew

从这一刻起,不再用鼠标安装任何开发软件。全部走 brew install / brew install --cask,并记录进 Brewfile(见第 13 章)——这是「可复现」的核心。

zsh — install homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Apple Silicon 默认装在 /opt/homebrew,写入 PATH
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

brew update && brew doctor
03
Battle Station

终端与 Shell:Agent 的作战室ghostty · starship

AI Agent 时代,终端是第一界面。推荐组合:GhosttyGhostty · 终端模拟器提供窗口、渲染与交互层。GPU 加速渲染、原生 macOS 体验,全部设置收在单个配置文件里。(GPU 渲染、原生快)+ zshzsh · Shell 命令解释器你敲的每条命令(包括 AI Agent 执行的)都由 shell 解析后交给系统执行。macOS 默认 shell,全部配置在 ~/.zshrc。分工:Ghostty 是窗口,zsh 是窗口里的「语言」,Starship 是提示符外观,Nerd Font 负责图标。 + StarshipStarship · 提示符跨 shell 的 prompt 工具:把目录、git 分支、Node/Python 版本、命令耗时渲染在提示符上,一个 starship.toml 配置。 提示符 + Nerd FontNerd Font · 图标字体在编程字体上追加数千个图标的补丁字体集。Starship、eza 等工具输出的图标靠它显示,否则全是问号方块。 图标字体。

zsh — terminal stack
brew install --cask ghostty   # 推荐。备选:wezterm / iterm2
brew install --cask font-jetbrains-mono-nerd-font
brew install starship zsh-autosuggestions zsh-syntax-highlighting

echo 'eval "$(starship init zsh)"' >> ~/.zshrc
~/.config/ghostty/config
font-family = JetBrainsMono Nerd Font
font-size = 14
theme = catppuccin-mocha
background-opacity = 0.96
window-padding-x = 12
window-padding-y = 10
copy-on-select = clipboard
装机实战建议:第一、二节(系统设置 + Homebrew)必须手工;从本节开始,可以先装一个 Kimi Code(curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash),把本文档丢给它,让 Agent 按章节替你执行和验证——这是这套环境的第一场实战。
04
Runtimes

运行时管理:mise + uvnode · python · go

抛弃 nvm / pyenv / rbenv。misemise · 语言版本总管家不同项目要不同版本的 Node / Python / Go,mise 一个工具统一管理:项目里写 .mise.toml 声明版本,cd 进目录自动切换,提交 git 后团队版本一致。取代了 nvm / pyenv / rbenv 等一堆单语言管理器。类比手机:mise 管「系统版本」,uv 管「装哪些 App」。 一个工具管理所有运行时,按项目目录自动切换、版本写进 .mise.toml 团队共享;uvuv · Python 包管理器负责装第三方库(openai、anthropic…),Rust 编写,比 pip 快 10-100 倍。自动为每个项目建隔离的虚拟环境,各项目的库互不干扰;uv run 跑脚本自动用项目环境。 负责 Python 包与虚拟环境,比 pip 快 10-100 倍 —— AI 项目的标配。

zsh — mise + uv
brew install mise uv pnpm
echo 'eval "$(mise activate zsh)"' >> ~/.zshrc

mise use -g node@lts          # 全局默认
mise use -g python@3.12
mise use -g go@latest

# 项目内:mise use node@22 → 生成 .mise.toml,提交 git
zsh — python workflow
uv init my-agent && cd my-agent
uv add openai anthropic           # 加依赖
uv run main.py                    # 跑脚本(自动用项目 venv)
uv run --with ruff ruff check .   # 临时工具,不污染环境
05
Safety Net

Git 与 GitHub 工具链gh · lazygit · delta

AI Agent 会大量、快速地改代码,Git 是你唯一的安全网。习惯:让 Agent 动手前先 commit;用 git worktreegit worktree · 多工作区同一个仓库同时检出多个分支到不同目录,各有独立工作区但共享 .git。多 Agent 并行的基础:每个 Agent 一个 worktree,各改各的互不踩踏。 让多个 Agent 并行干活互不干扰。配套三件套:ghgh · GitHub 官方 CLI终端里完成 issue / PR / 仓库管理;gh auth login 一次登录,git push/pull 认证一并搞定。(GitHub 官方 CLI)、lazygitlazygit · Git 终端图形界面不用背命令,全键盘完成暂存、提交、分支、rebase、解冲突。Agent 改完一堆代码后,逐个文件过 diff、分批提交的审查利器。(Git 终端图形界面)、git-deltagit-delta · diff 渲染器给 git diff 加语法高亮、行号、并排对比。pager = delta 启用后,git diff / git log / lazygit 的变更视图全部生效。lazygit 管「操作」,delta 管「显示」。(diff 美化渲染器)。

zsh — git toolchain
brew install git gh lazygit git-delta
gh auth login   # 浏览器授权,一次搞定 git push 认证
~/.gitconfig
[core]
    editor = code --wait
    pager = delta               # 语法高亮的 diff
[merge]
    conflictstyle = zdiff3
[pull]
    rebase = true
[alias]
    lg = log --graph --oneline --decorate --all
    st = status -sb
06
Toolbox

现代 CLI 工具箱rust 系全家桶

一套 rust/go 重写的现代替代品。ripgrep 是 Agent 搜索代码的底层引擎,其余工具则让你的日常操作全面提速。全部跨平台跨平台说明本章工具全是 Rust/Go 编写,Windows 用 winget / scoop 装同一批,命令一致。文档里 macOS 专有的是:Homebrew、Ghostty、zsh、Raycast 系效率应用、OrbStack——Windows 对应物分别是 winget、Windows Terminal、PowerShell 7、PowerToys、Docker Desktop + WSL2。,Windows 上也能提前练。

zsh — modern cli
brew install ripgrep fd bat eza fzf zoxide jq yq sd httpie \
  hyperfine dust duf bottom tlrc

# ~/.zshrc 收尾
eval "$(zoxide init zsh)"
source <(fzf --zsh)
alias ls='eza --icons' cat='bat --style=plain'
ripgreprg · grep 替代品,Agent 的搜索引擎替代 grep · 按内容搜代码在整个代码库里搜文本,快 10 倍+,自动跳过 node_modules 和 gitignore。例:rg "getUserInfo" 找函数在哪被调用。Claude Code 等 Agent 搜索代码的底层引擎就是它。
fdfind 替代品,语法友好替代 find · 按文件名找文件语法像人话:fd config,对比老命令 find . -name "*config*"。默认忽略 gitignore,不会翻进 node_modules。
batcat 高亮版,自动分页替代 cat · 看文件查看文件带语法高亮、行号、git 改动标记,终端里快速读代码的体验质变。
ezals 替代品,图标 + 树形替代 ls · 看目录彩色 + 图标列目录;lt 树形展示——进陌生项目,一条命令看懂目录结构。
fzf模糊搜索,Ctrl+R 历史神器模糊搜索器Ctrl+R 搜历史命令:只记得三天前那条命令里有 "docker",敲几个字母就捞回来。还能接管管道搜文件、进程、git 分支。
zoxidecd 智能跳转,越用越聪明会学习的 cd记住你去过的目录,之后 z proj 直接跳到最常去的匹配目录,不用敲全路径。用得越久越准。
jq / yqJSON / YAML 处理双雄结构化数据提取器API 返回一大坨 JSON,jq '.data[0].name' 只取你要的字段;yq 同理处理 YAML。和 Agent 的结构化输出打交道天天用。
httpiecurl 友好版,API 调试替代 curl · 调试 APIhttp POST api.x.com name=Tom——自动 JSON、自动高亮、自动格式化,不用背 curl 的参数旗标。
hyperfine命令耗时基准测试命令计时器hyperfine '方案A' '方案B' 各跑多次给平均耗时和对比,"哪个写法更快"从此有数据说话。
bottombtm · htop 替代品系统监控CPU / 内存 / 网络 / 进程一屏看全,图形化界面。Agent 满载跑长任务时开它盯负载。
dust / dufdu / df 的现代形态磁盘空间可视化dust 答"哪个目录最占地方",duf 答"各磁盘用量",都是直观的图形化进度条。
sdsed 替代品,正则即直觉替代 sed · 查找替换sd "旧文本" "新文本" 文件——语法就是直觉,不用记 sed 的正则转义和 -i 旗标。
tlrctldr 命令速查命令速查手册tldr tar 直接给最常用的 5 个例子,比啃 man 手册人性化一百倍。忘了某个命令怎么用先问它。
07
Editor

编辑器与 IDEvscode · zed

终端 Agent 是主力,编辑器只看 diff、做精细调整。策略:VS Code 主力(沿用既有习惯,生态最全)+ ZedZed · Zed IndustriesGitHub Atom 编辑器原班人马打造(他们还创造了 Tree-sitter 语法解析引擎)。Atom 停更后用 Rust 从零重写:GPU 加速、毫秒级启动、原生多人协作,2024 年开源,内置 AI 面板。 轻量备选(秒开大文件)。不装 Cursor:AI 主力已在终端 Agent,编辑器再叠 AI 订阅价值重叠。

zsh — editors
brew install --cask visual-studio-code    # 主力:生态最全
brew install --cask zed                   # 备选:极速启动,内置 AI 面板
08
Core · The Fleet

AI Agent 工具栈multi-agent

2026 年的共识:不押注单一 Agent。核心阵容七件套 —— 长任务用 Claude Code,交付 PR 用 Codex,插件编排用 DSH,自我扩展用 PI,桌面全场景用 WorkBuddy 与 ZCode。

主力 · Strongest

Claude Code

curl -fsSL https://claude.ai/install.sh | bash

综合能力最强:仓库理解、子 Agent、git worktree 并行、数小时无人值守的长任务。

开源 · MIT

Kimi Code CLI

curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash

Moonshot 出品的终端 Agent。内置 coder / explore / plan 子 Agent,MCP 用 /mcp-config 对话式配置,性价比高。亦可用 npm 安装。

交付 · PR

Codex CLI

npm install -g @openai/codex

OpenAI 的开源终端 Agent,任务以 Pull Request 形式交回,ChatGPT 订阅内含。

插件化 · 编排

DSH · DeepSeek Harness

npx -y @deepseek-ai/dsh

DeepSeek 的插件化 Agent 运行时:模型、工具、子 Agent 一切皆插件;bridge 插件可把 Codex / Kimi 变成它的「第二意见」。

自我扩展

PI · Agent Harness

npm install -g @earendil-works/pi-coding-agent

MIT 开源 coding agent,pi-ai 统一多家 LLM API。注意:无内置权限系统,敏感项目建议容器化运行。

桌面 · 全场景

WorkBuddy · 腾讯

官网下载桌面端

桌面 AI Agent 工作站:Coding Mode 写码、Work Mode 办公,支持本地模型配置接入 DeepSeek 等模型。

国产 · 桌面 ADE

ZCode · 智谱

zcode.z.ai/cn 下载 macOS 版

智谱桌面 Agent 开发环境:Goal 长程任务、微信/飞书/Telegram 远程唤起、GLM-5.3 深度集成,还能可视化管理其他 CLI Agent。首次启动选「连接 BigModel」(GLM Coding Plan),一个订阅还能给 Claude Code 等 20+ 工具用——正好配 cc-switch。

每个项目写 AGENTS.md写明构建命令、代码规范、目录结构、禁区。Agent 的表现上限 = 你给的上下文质量。Claude Code 同时认 CLAUDE.md。
配好权限与钩子在各 Agent 的配置(~/.claude/settings.json、kimi 的 config.toml)里声明权限模式与危险命令拦截,避免每次手动确认,也防止 Agent 越权。
API Key 集中管理Key 绝不写进项目文件、dotfiles 明文或 shell 历史 —— 见第 11 章。
配套:cc-switch —— Claude Code / Codex 的供应商总开关。开源桌面应用(Tauri + Rust),把各家 API 供应商(官方 / DeepSeek / GLM / 第三方网关)的 base URL、Key、模型做成图形化预设,一键切换,不用手改 settings.json;新版还集成 MCP / Skills 管理。安装:brew tap farion1231/ccswitch && brew install --cask cc-switch;若报 macOS 版本兼容错误(已知问题),改从 GitHub Releases 下载 DMG。
zsh — 多 Agent 并行工作流
# 用 git worktree 开隔离工作区,多个 Agent 并行不打架
git worktree add ../proj-feat-a feat-a
git worktree add ../proj-feat-b feat-b

# 窗口 1:  cd ../proj-feat-a && claude
# 窗口 2:  cd ../proj-feat-b && kimi
运行时:herdrherdr · Agent 运行时一台后台常驻服务器,为 coding agent 托管真实终端会话——合盖、断网、重启都不中断,任意设备随时 reattach。读取每个窗格,把每个 Agent 标记为 working / blocked / idle;CLI + socket API 同一个面,Agent 可以自己分窗格、拉起彼此、互相 prompt、互相等待。开箱识别 21 种 Agent CLI,macOS / Linux / Windows 单二进制。年轻项目(YC 背景):留在 stable channel,优先 brew 安装。 —— Agent 阵容的栖身之所。上面七件套跑在 herdr 里,而不是一堆散落的终端窗口:它是 agent 时代的 tmux 继任者,整个阵容栖身的运行时层。
zsh — herdr agent 运行时
brew install herdr                            # 首选:更新随 brew upgrade 一起走
mise use -g herdr                             # 备选(旧版 mise:mise use -g github:herdrdev/herdr)
curl -fsSL https://herdr.dev/install.sh | sh  # 直接安装;只有这种方式才用 herdr update
09
Extension

MCP:给 Agent 装上「手」model context protocol

MCPMCP · Model Context ProtocolAgent 与外部工具之间的「标准化插座」,类比 USB-C:Agent 实现一次客户端、工具方实现一次 Server 即可互插。Server 暴露 tools(可调用函数,99% 的用途)/ resources(数据)/ prompts(模板);本地 Server 是 Agent 的子进程,远程走 HTTP。 让 Agent 接入外部工具。各 Agent 配置方式不同(Claude Code 用 claude mcp add,Kimi Code 用 /mcp-config)。只装当前项目真正用到的 —— MCP 越多,上下文越臃肿。

Playwright MCP浏览器自动化,Agent 自己验证前端页面
Context7实时拉取库的最新文档,消除过时 API 幻觉
GitHub MCPIssue / PR / 代码搜索操作
Figma MCP设计稿直达代码
统一管理多个 Agent 的 MCP:你已在用的 cc-switch 新版(v3.x)内置了 MCP 集中管理——一处配置、多处同步,兼管 Skills;专门的 CLI 方案还有 mcpmmcpm · MCP 包管理器像 Homebrew 管软件一样管 MCP Server:中央注册表搜索安装、profile 分组启停、多客户端同步,路由器聚合多个 Server 为一个端点。对 Claude Code 原生支持有限,需手动接线。安装:brew install mcpm。注意:这类工具本质是「一处维护、多处同步」的翻译层,各家 Agent 的 MCP 配置格式尚未完全统一。
10
Runtime Sandbox

容器与本地服务orbstack

OrbStackOrbStack · Danny Lin (kdrag0n)独立开发者一人公司的作品,2023 年发布。作者此前是 Android 定制内核圈知名开发者(Proton Kernel 作者),用 Swift / Rust 原生重写整套 Docker + Linux 虚拟化栈——「一个人打败了 Docker 官方产品」。个人免费,商用付费。 取代 Docker Desktop:macOS 上最快、最省电的 Docker / Linux 运行环境。数据库一律容器化,不污染系统。

zsh — containers
brew install --cask orbstack
brew install lazydocker   # 容器 TUI:lazygit 的 Docker 版

docker run -d --name pg -p 5432:5432 \
  -e POSTGRES_PASSWORD=dev postgres:17
docker run -d --name redis -p 6379:6379 redis:7
11
Security

密钥与安全管理1password · direnv

AI 时代你手里的 API Key 比信用卡还多。铁律:Key 不进 git、不进 dotfiles 明文、不进 ~/.zshrc 明文。免费路径先走,1Password1Password · 付费订阅个人版约 $3/月(按年付),无免费档,仅 14 天试用。独特价值:op run 运行时注入 API Key、跨设备体验。免费替代已够用——SSH 私钥用 macOS 钥匙串,密码管理用 Bitwarden(免费档,也有 CLI 和 SSH Agent)。 是可选付费项(订阅制约 $3/月)。

zsh — secrets(免费路径)
brew install direnv age sops     # .env 自动加载 + 敏感配置加密

# SSH 私钥用 macOS 原生钥匙串托管(免费、系统自带)
ssh-keygen -t ed25519
ssh-add --apple-use-keychain ~/.ssh/id_ed25519

# 可选付费:brew install --cask 1password 1password-cli
# 跨项目注入 Key:op run --env-file=.env.tpl -- claude
SSH Key 免费方案:macOS 钥匙串1Password + Keychain 组合流程分层分工:Keychain 管「系统自己要用的」(SSH passphrase 开机解锁一次、整天无感),1Password 管「你和 Agent 要用的」(网站密码、API Key)。跑 Agent 时项目里只放 .env.tpl 引用模板,op run 注入时指纹授权一次,Key 全程不落盘。纪律:两者的 SSH Agent 只启用一个,建议固定在 Keychain。 托管(上面命令);付费方案:1Password SSH Agent,私钥不落盘。密码管理免费替代:Bitwarden
12
Productivity

macOS 效率应用raycast & friends

zsh — productivity casks
brew install --cask raycast rectangle alt-tab stats karabiner-elements
Raycast启动器之王:剪贴板历史 / 窗口管理 / 快捷指令全包 · 免费档够用
Rectangle开源窗口分屏快捷键 · 免费
AltTabWindows 式窗口切换 · 免费开源
Stats菜单栏负载监控,跑 Agent 时看 CPU/内存 · 免费开源
Karabiner键盘改键:CapsLock → Esc/Ctrl · 免费开源
收费情况:Rectangle / AltTab / Stats / Karabiner 全部免费开源;Raycast 免费档已覆盖核心功能,Pro(约 $8/月)主要买 AI 与云同步——AI 需求都在终端 Agent 上,免费档够用

第二梯队(日常增强,参考 OmarchyOmarchy · DHH 的满配 LinuxRuby on Rails 作者 DHH 主导的 Arch 发行版,预装一整套精选开发/效率工具,2025 年很火。本梯队参考其清单做 macOS 映射;它清单里的 fzf / ripgrep / lazygit / Neovim 等本指南已覆盖。 清单做的 macOS 映射):

zsh — daily essentials
brew install --cask google-chrome obsidian shottr localsend iina tailscale
Chrome浏览器 · 前端调试基准 · 免费
ObsidianMarkdown 笔记 · 免费Agent 时代的知识库笔记存纯 .md 文件——你写的知识库,Agent 可以直接读、直接整理。这是 AI 时代笔记软件和普通文档的分水岭。
Shottr截图标注 · 滚动截图 / 打码 / 量尺寸 · 免费
LocalSend跨平台 AirDrop · 免费开源Windows ↔ Mac 互传同一局域网下直接拖文件,不用命令不用线。第 15 章迁移小文件的最省事路径。
IINA视频播放器 · macOS 原生最强 · 免费开源
Tailscalemesh VPN · 个人免费Mac 常开的绝配装好后,你在公司 / 外面能安全 SSH 回家里这台 Mac,跑在上面的 Agent 任务随时接管。
按需自选:LibreOffice(办公套件)、Typora(Markdown 写作,$15 买断)、Spotify、Dropbox。
13
Infrastructure as Code

自动化:一键复原整个环境brewfile · chezmoi

这是整套方案的灵魂:软件清单、配置、运行时全部代码化,存进 git 私有仓库。首次装机按 1-12 章顺序执行,本章在收尾时做一次;回报在下一台机器——只跑一条 bootstrap,30 分钟复原。dotfiles 用 chezmoichezmoi · dotfiles 管理器免费开源(Go 编写,Tom Payne 2019 年发布),该领域最主流。把散落的点文件收进 git 仓库,新机器一条命令还原;强在模板(多机器差异化配置)和加密(敏感配置 age 加密入库)。 管理。

zsh — snapshot & restore
# 装完所有软件后导出清单
brew bundle dump --file=~/dotfiles/Brewfile --force

# dotfiles 用 chezmoi 管理(支持模板与加密)
brew install chezmoi
chezmoi init --apply <你的dotfiles仓库>
bootstrap.sh — 新机器总入口
#!/bin/bash
# 新 Mac 只跑这一条
xcode-select --install 2>/dev/null
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
eval "$(/opt/homebrew/bin/brew shellenv)"
brew bundle --file=<你的Brewfile>
chezmoi init --apply <你的dotfiles仓库>
mise install
gh auth login
14
Verify

验收清单final check

zsh — acceptance
brew doctor && echo OK
git --version && gh auth status
mise ls                        # node / python / go 就位
uv --version && node -v && python3 -V
claude --version; kimi --version; codex --version; pi --version
npx -y @deepseek-ai/dsh --version   # DSH
# 桌面端:ZCode / WorkBuddy 首次启动完成模型登录
docker run hello-world         # OrbStack
rg --version && fzf --version
ssh -T git@github.com          # SSH 认证
全部通过后执行 brew bundle dump 并提交 dotfiles —— 你的环境从此可复现、可迁移、可演进
15
Appendix · Migration

附录:从 Windows 迁移到 Macworkspace → mac

总原则一句话:代码走 git,配置重建为主,依赖目录永不迁移

项目文件:git 优先能 push 的全部 push 到 GitHub,Mac 上 clone——历史、分支、remote 全在。未入库的走 scp / LocalSend / exFAT 硬盘(小文件 LocalSend 最省事,见第 12 章)。绝不迁 node_modules / .venv / target / __pycache__:x86 与 arm64 不通用,到 Mac 用 mise / uv / pnpm 一分钟重建,只迁源码 + .git。
配置文件:重建为主,少数可搬VS Code 开 Settings Sync(GitHub 账号)全自动同步;Agent 配置(~/.claude、config.toml)可直接复制,注意改掉 Windows 路径字段;SSH Key 在 Mac 重新生成,API Key 趁机录入 1Password / Keychain。
并行期:Syncthing + git 纪律需要实时同步目录就上 SyncthingSyncthing · 点对点同步免费开源的设备直连同步工具,无云端中转。Workspace 目录双向同步,务必加忽略规则排除 node_modules 等依赖目录。(免费开源、点对点)双向同步 Workspace;养成「换机器前 push」的习惯。终态:Mac 主力、Windows 备用、git 为中心,无需长期双向同步。
Windows Git Bash → Mac(Mac 需先开「远程登录」)
# 在 Windows 的 Git Bash 里执行,把项目推到 Mac
scp -r /c/Users/TUF/Workspace/<项目> user@<mac-ip>:~/Workspace/

# 大文件兜底:exFAT 移动硬盘(两边原生读写)
# 或 Mac 开「文件共享」SMB → Windows 访问 \\<mac-ip> 拖拽
16
Day-2 Operations

日常运维:装、删、改、更新dotsync

核心心智:两层资产,各有一条纪律——软件层对 Brewfile 负责,配置层对 chezmoi 负责。不是每步都要跑 chezmoi:一个 dotsync 别名把所有收尾动作打包。

软件层:装 / 删 / 更新brew install / uninstall / upgrade 之后,收尾动作永远一样:重新导出 Brewfile。清单不记版本号,upgrade 后 dump 一次即可。运行时归 mise(mise upgrade),Agent CLI 各自升级(kimi upgrade 等)。
配置层:只有改 dotfiles 才碰 chezmoi直接改源文件(如 ~/.zshrc),改完 chezmoi re-add 收进仓库;新纳管文件用 chezmoi add。除此之外的日常操作完全不用想 chezmoi。
dotsync:一条命令收尾装 / 删 / 改完任何东西跑一次:导出清单 + 收纳配置 + 提交推送。忘了跑也不会坏——只是下一台机器少一点变化。建议 chezmoi 源目录就用 ~/dotfiles,Brewfile 也放里面。
~/.zshrc — dotsync 收尾函数
dotsync() {
  brew bundle dump --file=~/dotfiles/Brewfile --force  # 软件清单
  chezmoi re-add                                       # 收纳配置变更
  git -C ~/dotfiles add -A
  git -C ~/dotfiles commit -m "chore: sync $(date +%F)"
  git -C ~/dotfiles push
}
节奏建议:随手 dotsync;每周或每月 brew update && brew upgrade && brew cleanupmise upgrade;懒人选项——把维护流程写成 prompt 让 Agent 定期执行,或用 launchd 定时跑 brew upgrade。
Crafted for the agentic era.
MAC × AI AGENT · SETUP FIELD MANUAL · 2026