一台 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 七件套并存,各取所长。
阅读 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
系统初始化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 和几乎所有编译工具都依赖它。,这是一切编译链的前提。
# 键盘:最快的按键重复与最短延迟 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
# Xcode 命令行工具:git、clang 等一切编译链的前提
xcode-select --install
Homebrew:一切的地基brew
从这一刻起,不再用鼠标安装任何开发软件。全部走 brew install / brew install --cask,并记录进 Brewfile(见第 13 章)——这是「可复现」的核心。
/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
终端与 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 等工具输出的图标靠它显示,否则全是问号方块。 图标字体。
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
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
curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash),把本文档丢给它,让 Agent 按章节替你执行和验证——这是这套环境的第一场实战。运行时管理: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 项目的标配。
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
uv init my-agent && cd my-agent uv add openai anthropic # 加依赖 uv run main.py # 跑脚本(自动用项目 venv) uv run --with ruff ruff check . # 临时工具,不污染环境
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 美化渲染器)。
brew install git gh lazygit git-delta
gh auth login # 浏览器授权,一次搞定 git push 认证
[core]
editor = code --wait
pager = delta # 语法高亮的 diff
[merge]
conflictstyle = zdiff3
[pull]
rebase = true
[alias]
lg = log --graph --oneline --decorate --all
st = status -sb
现代 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 上也能提前练。
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'
编辑器与 IDEvscode · zed
终端 Agent 是主力,编辑器只看 diff、做精细调整。策略:VS Code 主力(沿用既有习惯,生态最全)+ ZedZed · Zed IndustriesGitHub Atom 编辑器原班人马打造(他们还创造了 Tree-sitter 语法解析引擎)。Atom 停更后用 Rust 从零重写:GPU 加速、毫秒级启动、原生多人协作,2024 年开源,内置 AI 面板。 轻量备选(秒开大文件)。不装 Cursor:AI 主力已在终端 Agent,编辑器再叠 AI 订阅价值重叠。
brew install --cask visual-studio-code # 主力:生态最全 brew install --cask zed # 备选:极速启动,内置 AI 面板
AI Agent 工具栈multi-agent
2026 年的共识:不押注单一 Agent。核心阵容七件套 —— 长任务用 Claude Code,交付 PR 用 Codex,插件编排用 DSH,自我扩展用 PI,桌面全场景用 WorkBuddy 与 ZCode。
Claude Code
curl -fsSL https://claude.ai/install.sh | bash综合能力最强:仓库理解、子 Agent、git worktree 并行、数小时无人值守的长任务。
Kimi Code CLI
curl -fsSL https://code.kimi.com/kimi-code/install.sh | bashMoonshot 出品的终端 Agent。内置 coder / explore / plan 子 Agent,MCP 用 /mcp-config 对话式配置,性价比高。亦可用 npm 安装。
Codex CLI
npm install -g @openai/codexOpenAI 的开源终端 Agent,任务以 Pull Request 形式交回,ChatGPT 订阅内含。
DSH · DeepSeek Harness
npx -y @deepseek-ai/dshDeepSeek 的插件化 Agent 运行时:模型、工具、子 Agent 一切皆插件;bridge 插件可把 Codex / Kimi 变成它的「第二意见」。
PI · Agent Harness
npm install -g @earendil-works/pi-coding-agentMIT 开源 coding agent,pi-ai 统一多家 LLM API。注意:无内置权限系统,敏感项目建议容器化运行。
WorkBuddy · 腾讯
官网下载桌面端桌面 AI Agent 工作站:Coding Mode 写码、Work Mode 办公,支持本地模型配置接入 DeepSeek 等模型。
ZCode · 智谱
zcode.z.ai/cn 下载 macOS 版智谱桌面 Agent 开发环境:Goal 长程任务、微信/飞书/Telegram 远程唤起、GLM-5.3 深度集成,还能可视化管理其他 CLI Agent。首次启动选「连接 BigModel」(GLM Coding Plan),一个订阅还能给 Claude Code 等 20+ 工具用——正好配 cc-switch。
brew tap farion1231/ccswitch && brew install --cask cc-switch;若报 macOS 版本兼容错误(已知问题),改从 GitHub Releases 下载 DMG。# 用 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
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
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 越多,上下文越臃肿。
容器与本地服务orbstack
OrbStackOrbStack · Danny Lin (kdrag0n)独立开发者一人公司的作品,2023 年发布。作者此前是 Android 定制内核圈知名开发者(Proton Kernel 作者),用 Swift / Rust 原生重写整套 Docker + Linux 虚拟化栈——「一个人打败了 Docker 官方产品」。个人免费,商用付费。 取代 Docker Desktop:macOS 上最快、最省电的 Docker / Linux 运行环境。数据库一律容器化,不污染系统。
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
密钥与安全管理1password · direnv
AI 时代你手里的 API Key 比信用卡还多。铁律:Key 不进 git、不进 dotfiles 明文、不进 ~/.zshrc 明文。免费路径先走,1Password1Password · 付费订阅个人版约 $3/月(按年付),无免费档,仅 14 天试用。独特价值:op run 运行时注入 API Key、跨设备体验。免费替代已够用——SSH 私钥用 macOS 钥匙串,密码管理用 Bitwarden(免费档,也有 CLI 和 SSH Agent)。 是可选付费项(订阅制约 $3/月)。
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
macOS 效率应用raycast & friends
brew install --cask raycast rectangle alt-tab stats karabiner-elements
第二梯队(日常增强,参考 OmarchyOmarchy · DHH 的满配 LinuxRuby on Rails 作者 DHH 主导的 Arch 发行版,预装一整套精选开发/效率工具,2025 年很火。本梯队参考其清单做 macOS 映射;它清单里的 fzf / ripgrep / lazygit / Neovim 等本指南已覆盖。 清单做的 macOS 映射):
brew install --cask google-chrome obsidian shottr localsend iina tailscale
自动化:一键复原整个环境brewfile · chezmoi
这是整套方案的灵魂:软件清单、配置、运行时全部代码化,存进 git 私有仓库。首次装机按 1-12 章顺序执行,本章在收尾时做一次;回报在下一台机器——只跑一条 bootstrap,30 分钟复原。dotfiles 用 chezmoichezmoi · dotfiles 管理器免费开源(Go 编写,Tom Payne 2019 年发布),该领域最主流。把散落的点文件收进 git 仓库,新机器一条命令还原;强在模板(多机器差异化配置)和加密(敏感配置 age 加密入库)。 管理。
# 装完所有软件后导出清单 brew bundle dump --file=~/dotfiles/Brewfile --force # dotfiles 用 chezmoi 管理(支持模板与加密) brew install chezmoi chezmoi init --apply <你的dotfiles仓库>
#!/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
验收清单final check
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 —— 你的环境从此可复现、可迁移、可演进。附录:从 Windows 迁移到 Macworkspace → mac
总原则一句话:代码走 git,配置重建为主,依赖目录永不迁移。
# 在 Windows 的 Git Bash 里执行,把项目推到 Mac scp -r /c/Users/TUF/Workspace/<项目> user@<mac-ip>:~/Workspace/ # 大文件兜底:exFAT 移动硬盘(两边原生读写) # 或 Mac 开「文件共享」SMB → Windows 访问 \\<mac-ip> 拖拽
日常运维:装、删、改、更新dotsync
核心心智:两层资产,各有一条纪律——软件层对 Brewfile 负责,配置层对 chezmoi 负责。不是每步都要跑 chezmoi:一个 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
}
brew update && brew upgrade && brew cleanup 和 mise upgrade;懒人选项——把维护流程写成 prompt 让 Agent 定期执行,或用 launchd 定时跑 brew upgrade。