简洁、偏现代 CLI 工作流的个人开发环境配置，按三个阶段组织：base（基础依赖）→ terminal（终端工具）→ ai（AI 服务）。
| 方向 | 命令 | 作用 |
|---|---|---|
| 仓库 → 本机 | ./install.sh [phase] |
按阶段把仓库里的托管配置复制到本机；装完后本机文件与仓库解耦 |
| 本机 → 仓库 | ./sync-from-local.sh |
在确认后，把本机托管配置写回仓库；不自动 git add / commit / push |
要点：
- 使用真实文件副本，不依赖长期软链。日常改本机配置不会改动仓库。
- 两个脚本都按程序整组决策：一组内全部保留或全部替换，避免半套新旧配置混用。
- 默认答案是
N（不覆盖）。
| 阶段 | 内容 | 依赖 |
|---|---|---|
base |
Homebrew（官方安装脚本） | 无；作为公共基础能力阻塞后续阶段 |
terminal |
Ghostty（brew install --cask ghostty）+ terminal/Brewfile（starship、antidote、eza、bat、zoxide、fd、ripgrep、neovim、字体）+ ghostty/zsh/starship 配置 |
base |
ai |
CLIProxyAPI（brew install cliproxyapi + 配置模板渲染 + brew services 常驻）+ Agent 全局规则（通用路径 + Codex / Claude Code / Pi / Grok）+ Claude Code 与 Pi 配置 + npx skills 按 ai/skills.txt 清单安装 skills |
base；skills 需要本机已有 Node/npx |
./install.sh # 等价 ./install.sh all：base -> terminal -> ai
./install.sh base # 只装基础依赖
./install.sh terminal # 只装终端工具（会先检测 base 是否就绪）
./install.sh ai # 只装 AI 服务（会先检测 base 是否就绪）阶段完成情况记录在 ~/.local/state/dotfiles/phases/（每阶段一个时间戳文件）。门禁以真实检测为准：单独运行 terminal / ai 时只检查公共基础能力 Homebrew；Ghostty 属于 terminal，不再阻塞 AI。检测通过但 base 标记缺失时会自动补写标记。
| 阶段 | 程序 | 仓库路径 | 本机路径 |
|---|---|---|---|
| terminal | Ghostty | terminal/ghostty/config |
~/.config/ghostty/config |
| terminal | Starship | terminal/starship/starship.toml |
~/.config/starship.toml |
| terminal | Zsh | terminal/zsh/.zshrc、terminal/zsh/.zsh_plugins.txt |
~/.zshrc、~/.zsh_plugins.txt |
| ai | Agent rules | ai/agent-rules/AGENTS.global.md（单文件） |
~/.agents/AGENTS.md、~/.claude/CLAUDE.md、~/.codex/AGENTS.md、~/.pi/agent/AGENTS.md、~/.grok/AGENTS.md |
| ai | Claude Code | ai/claude/settings.json、ai/claude/statusline-command.sh |
~/.claude/settings.json、~/.claude/statusline-command.sh |
| ai | Pi | ai/pi/settings.json、ai/pi/extensions/statusline.ts、ai/pi/web-search.json |
~/.pi/agent/settings.json、~/.pi/agent/extensions/statusline.ts、~/.pi/web-search.json |
Agent rules 是独立配置组：
- 安装：五个本机路径与仓库比较；任一路径缺失、内容不同、软链冲突或类型不匹配 → 整组需一次确认；选
y则五个路径全部写成仓库副本。 - 回写：先要求五个本机规则内容一致且可信；一致后与仓库比较，最多询问并写入一次。
~/.agents/AGENTS.md是跨 agent 的通用位置；Codex、Claude Code、Pi、Grok 的专用路径继续保留。
Agent 规则只保存跨项目个人习惯，不包含具体仓库结构。
Claude Code 配置只托管用户主动维护的设置和状态栏脚本；ai 阶段会检测状态栏所需的 jq，仅在缺失时通过 Homebrew 安装。~/.claude.json 以及 ~/.claude/ 下的 history、projects、sessions、cache、插件缓存等账号、实验和运行状态不纳入仓库。
Pi 配置只托管全局设置、状态栏扩展和当前 pi-web-access 的非敏感设置。auth.json、sessions、trust.json、models-store.json、配置备份以及 npm/git 包缓存不纳入仓库；后续若本机 Pi 配置出现 API Key、Token 或密码特征，回写脚本会阻止整组写入。
terminal/zsh/.zsh_plugins.zsh 是 antidote 生成的插件加载文件，不会安装或反向同步。
CLIProxyAPI 配置不在仓库里保存任何密钥，仓库模板用 {{VAR}} 占位。模板变量按归属分开读取：
- CLIProxyAPI 自身的
CLIPROXY_API_KEY、CLIPROXY_MANAGEMENT_PASSWORD存放在本机私有文件~/.config/cliproxyapi/credentials.env（权限强制为 600，KEY='value'格式）。该路径必须是普通文件，不能是软链；文件中缺失/为空的值回退读取终端里同名环境变量。 - 上游服务的
OPENCODE_GO_API_KEY只读取个人环境变量，不生成、不读取credentials.env中的同名字段。 - 安装：用上述来源渲染模板，再与本机文件比较/复制；任一所需值缺失时安装失败且不会写阶段完成标记，也不会写出半渲染的配置。
credentials.env不存在时只自动生成两个 CLIProxyAPI 自身的本地密钥。 - 管理密码部署成功后只在
~/.local/state/dotfiles/cliproxyapi/management-password.sha256保存权限为 600 的 SHA-256 指纹；后续指纹变化会自动重新部署配置并重启服务，状态文件不保存明文密码。
ai 阶段负责 CLIProxyAPI 的完整生命周期：
brew install cliproxyapi（homebrew-core formula），以brew services常驻（~/Library/LaunchAgents/homebrew.mxcl.cliproxyapi.plist）。- 配置模板
ai/cliproxyapi/cliproxyapi.conf.template渲染后部署到$(brew --prefix)/etc/cliproxyapi.conf（权限 600）。该路径不在$HOME下，也需要服务重启配合，所以不走通用托管清单，由安装脚本单独处理：缺失时直接安装；有差异时展示已脱敏的 diff 并确认（先备份到~/.dotfiles-backups/）；部署后brew services restart。 - 比较时忽略
secret-key行：服务启动时会把明文管理密码就地哈希，该行永远无法逐字节一致。 - 认证凭据目录
~/.cli-proxy-api/（OAuth token 等）不纳入仓库管理。 - cliproxyapi.conf 不参与
sync-from-local.sh回写；本机改动要进仓库时，手工把改动（密钥替换回{{VAR}}）写入模板。
skills 用 vercel-labs/skills（npx skills）统一管理。ai/skills.txt 每个非注释行会执行一次：
npx skills add <该行内容>例如 vercel-labs/agent-skills --skill frontend-design -a claude-code -a codex。清单为空时跳过。skills 只从仓库单向安装到本机，不参与 sync-from-local.sh 回写。
terminal/Brewfile 负责安装 Neovim；配置继续由独立的 specode/nvim-config 仓库管理。本仓库不会复制、同步或改动 ~/.config/nvim。
- macOS
rsync（macOS 自带，用于精确复制目录）- Homebrew 不需要预装：
base阶段会用官方脚本安装 ai阶段安装 skills 需要 Node（npx），可brew install node
git clone git@github.com:specode/dotfiles.git ~/Code/dotfiles
cd ~/Code/dotfiles
./install.sh每个阶段内，配置部署先只读比较全部托管路径，并按程序展示结果。决策单位始终是整个程序（该程序下全部托管路径一起保留或一起替换）：
- 可自动安装：该程序本机没有冲突（路径缺失，或仅有旧版指向本仓库的正确软链）时，整组直接复制，无需确认。
- 需确认覆盖：该程序任一托管路径内容不同、软链冲突或类型不匹配时，对该程序询问一次。
y：先把该程序已有托管路径移到~/.dotfiles-backups/<时间>/<程序>/，再整组写入仓库副本。N：整组全部不动——已有文件保持原样，同组里仍缺失的路径也不会单独补装。
- 标准输入无法提供选择时，会在修改文件前安全退出。
部署配置组时会先把整组仓库文件复制到临时暂存区，全部成功后才备份并替换本机路径；备份或替换中途失败时会自动恢复该组原配置，避免本机留下半套新旧文件。
装完后本机配置与仓库文件无关：编辑 ~/.zshrc 等不会改动 git 工作区。
仓库有更新时，用同一条安装命令把变更部署到本机（不是 sync-from-local.sh），可以只跑受影响的阶段：
cd ~/Code/dotfiles
git pull
./install.sh terminal # 或 base / ai / all- 与仓库已一致的程序：跳过。
- 本机有差异的程序：按组询问是否用仓库覆盖（同样先备份）。
sync-from-local.sh不会把远程更新拉到本机；它只负责本机 → 仓库。
仅在你想把本机上的配置改动晋升进仓库时运行：
cd ~/Code/dotfiles
./sync-from-local.sh- 先检查差异，再按程序确认；默认
N。 - 不会自动
git add、提交或推送。写回后请自行检查再提交：
git status
git diff
# 确认后再 add / commit / pushAgent rules：五个本机副本必须内容一致且可信，才会与仓库比较并最多写入一次；任一缺失、类型异常、不可信软链或内容互不一致，则整组阻止写回。
其它会阻止对应配置组写回的情况：
- 必需的本机路径缺失、类型错误，或是未指向本仓库源路径的软链。
- 对应仓库路径已经有暂存、未暂存或未跟踪改动。
- 本机配置中发现常见私钥、Token、API Key 或密码特征。
目录同步会精确镜像新增、修改和删除，同时忽略 .git/、node_modules/、.DS_Store、日志和常见编辑器临时文件。
.
├── install.sh
├── sync-from-local.sh
├── lib/
│ └── managed-configs.sh
├── terminal/
│ ├── Brewfile
│ ├── ghostty/
│ │ └── config
│ ├── starship/
│ │ └── starship.toml
│ └── zsh/
│ ├── .zsh_plugins.txt
│ ├── .zsh_plugins.zsh
│ └── .zshrc
└── ai/
├── agent-rules/
│ └── AGENTS.global.md
├── cliproxyapi/
│ └── cliproxyapi.conf.template
├── claude/
│ ├── settings.json
│ └── statusline-command.sh
├── pi/
│ ├── extensions/
│ │ └── statusline.ts
│ ├── settings.json
│ └── web-search.json
└── skills.txt