Dotfiles

简洁、偏现代 CLI 工作流的个人开发环境。按三阶段安装：base → terminal → ai。

文档分层

正文（本层之上）只写稳定机制：怎么装、怎么托管、怎么回写。

具体装了哪些 brew 包、Pi npm 包、扩展职责等会随本机习惯变的内容，只放在文末 Living inventory（易变清单）。

AI 同步/回写配置时：先改源文件，再更新 Living inventory；不要把易变细节写回总览段落。

用法模型

方向	方式	作用
仓库 → 本机	`./install.sh [phase]`	按阶段把仓库托管配置复制到本机；装完后本机与仓库解耦
本机 → 仓库	AI agent（见 Sync from local）	按 `lib/managed-configs.sh` 清单 diff 并写回；提交前人工确认

要点：

使用真实文件副本，不依赖长期软链。日常改本机配置不会动仓库。
安装脚本按程序整组决策：一组内全部保留或全部替换，避免半套新旧混用。
覆盖确认默认 N（不覆盖）。

三个安装阶段

阶段	内容（机制）	依赖
`base`	Homebrew（官方安装脚本）	无；阻塞后续阶段
`terminal`	Ghostty cask + `terminal/Brewfile` + ghostty / zsh / starship 托管配置	base
`ai`	`ai/Brewfile` + Agent 全局规则 + Claude Code / Pi / pi-lens 托管配置 + `ai/skills.txt`（`npx skills`）	base；skills 需要本机 Node/`npx`

具体依赖与包名见 Living inventory，以对应 Brewfile / 配置文件为准。

./install.sh            # 等价 all：base -> terminal -> ai
./install.sh base
./install.sh terminal   # 会先检测 base
./install.sh ai         # 会先检测 base

阶段完成标记：~/.local/state/dotfiles/phases/（每阶段一个时间戳文件）。
门禁以真实检测为准：单独跑 terminal / ai 时只检查 Homebrew；Ghostty 属 terminal，不阻塞 ai。检测通过但 base 标记缺失时会自动补写。

Managed configuration

权威清单是 lib/managed-configs.sh（下表为其可读摘要）。

阶段	程序	仓库路径	本机路径
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/keybindings.json`、`ai/claude/statusline-command.sh`	`~/.claude/settings.json`、`~/.claude/keybindings.json`、`~/.claude/statusline-command.sh`
ai	Pi	`ai/pi/settings.json`、`ai/pi/keybindings.json`、`ai/pi/extensions/*`、`ai/pi/web-search.json`	`~/.pi/agent/settings.json`、`~/.pi/agent/keybindings.json`、`~/.pi/agent/extensions/*`、`~/.pi/web-search.json`
ai	pi-lens	`ai/pi-lens/config.json`	`~/.pi-lens/config.json`

各组边界（稳定规则）

Agent rules：独立配置组。安装时五路径任一冲突 → 整组确认一次；回写前五份本机内容必须一致，否则整组阻止。只放跨项目个人习惯，不含具体仓库结构。~/.agents/AGENTS.md 为通用位置，各 agent 专用路径保留。
Claude Code：只托管用户主动维护的 settings / keybindings / statusline 脚本。账号态、history、projects、sessions、cache、插件缓存、~/.claude.json 等不入库。
Pi：只托管全局 settings、keybindings、仓库内自写 extensions、以及 web-search 等非敏感设置。settings.json 的 packages 在启动时拉 npm 扩展；具体包名与扩展职责见 Living inventory。auth.json、sessions、trust、models-store、生成图目录、npm 包运行时状态与缓存不入库。回写时若本机出现 API Key / Token / 密码特征 → 阻止整组。
pi-lens：只托管用户偏好 config.json。运行时日志、probe 缓存、projects 状态不入库。
terminal/zsh/.zsh_plugins.zsh：antidote 生成物，不安装、不回写。

Skills（`ai/skills.txt`）

用 vercel-labs/skills（npx skills）管理。每个非注释行执行：

npx skills add <该行内容>

清单为空则跳过。skills 只单向仓库 → 本机，不参与回写。当前条目见 Living inventory。

Neovim

terminal/Brewfile 安装 Neovim 二进制；配置由独立仓库 specode/nvim-config 管理。本仓库不碰 ~/.config/nvim。

Requirements

macOS
rsync（macOS 自带；托管 directory 类型时需要）
Homebrew 可不预装（base 用官方脚本装）
ai 阶段 skills 需要 Node / npx（可 brew install node）

Installation（首次安装）

git clone git@github.com:specode/dotfiles.git ~/Code/dotfiles
cd ~/Code/dotfiles
./install.sh

每个阶段内先只读比较托管路径，再按程序决策（该程序下全部路径一起保留或一起替换）：

可自动安装：本机无冲突（路径缺失，或仅有指向本仓库的旧软链）→ 整组直接复制。
需确认覆盖：任一路径内容不同 / 软链冲突 / 类型不匹配 → 询问一次。
- y：已有路径先移到 ~/.dotfiles-backups/<时间>/<程序>/，再整组写入仓库副本。
- N：整组不动（含仍缺失的路径，也不会单独补装）。
标准输入无法作答时，改文件前安全退出。

部署走暂存区：整组复制成功后再备份并替换；中途失败会回滚该组，避免半套状态。
装完后本机与仓库无关：改 ~/.zshrc 等不会动 git 工作区。

Update from repository（仓库 → 本机）

cd ~/Code/dotfiles
git pull
./install.sh terminal   # 或 base / ai / all

已一致：跳过。
有差异：按组询问是否用仓库覆盖（同样先备份）。

Sync from local（本机 → 仓库）

回写由 AI agent 执行（无专用脚本）。晋升本机改动时：

以 lib/managed-configs.sh 为准，逐组对比本机 vs 仓库，先报告再写入。
按程序整组：要么全写回，要么全不动。
不自动 commit；git diff 确认后再由人 add / commit / push。
若改动了 Brewfile、settings.json 的 packages、自写扩展职责、skills 清单等易变面：同步更新文末 Living inventory。

必须阻止写回的情况：

本机路径缺失、类型错误，或软链未指向本仓库源路径。
对应仓库路径已有暂存 / 未暂存 / 未跟踪改动。
本机内容含常见私钥、Token、API Key、密码特征。
Agent rules：五份本机副本内容不一致。

目录同步需精确镜像增删改；忽略 .git/、node_modules/、.DS_Store、日志与常见编辑器临时文件。

Structure

.
├── install.sh
├── lib/
│   └── managed-configs.sh
├── terminal/
│   ├── Brewfile
│   ├── ghostty/config
│   ├── starship/starship.toml
│   └── zsh/
│       ├── .zsh_plugins.txt
│       ├── .zsh_plugins.zsh   # antidote 生成，不托管
│       └── .zshrc
└── ai/
    ├── Brewfile
    ├── agent-rules/AGENTS.global.md
    ├── claude/
    │   ├── settings.json
    │   ├── keybindings.json
    │   └── statusline-command.sh
    ├── pi/
    │   ├── extensions/          # 仓库内自写扩展及扩展配置；清单见 Living inventory
    │   ├── settings.json
    │   ├── keybindings.json
    │   └── web-search.json
    ├── pi-lens/config.json
    └── skills.txt

Living inventory（易变清单）

给 AI / 未来的自己
本节是「当前快照」，会随本机习惯频繁变。权威仍是各源文件；这里只是方便扫一眼的摘要。
更新触发：回写或提交改动了下列任一源文件时，必须改本节对应小节，并视情况改「最近核对」日期。
不要把本节细节抄回上文总览。

最近核对：2026-08-11

terminal / Brewfile

源：terminal/Brewfile

类型	包
formula	`starship`, `antidote`, `eza`, `bat`, `zoxide`, `fd`, `ripgrep`, `neovim`
cask	`font-maple-mono-nf-cn`（Ghostty 默认）, `font-jetbrains-mono-nerd-font`
另装	Ghostty：`brew install --cask ghostty`（install 脚本，不在 Brewfile）

ai / Brewfile

源：ai/Brewfile

包	用途
`jq`	Claude Code `statusline-command.sh`

不再通过 brew 安装 agent-browser：当前 Pi packages 无依赖，本机也未安装。浏览器自动化走 Kimi WebBridge 等包自身引导。

Pi — `settings.json` packages

源：ai/pi/settings.json → packages（启动时由 Pi 安装）。描述以已安装包的 package.json description 为准。

包	角色（一句话）
`npm:pi-web-access`	Web 搜索 / URL 抓取 / GitHub / PDF / 视频等；非敏感项见 `ai/pi/web-search.json`
`npm:pi-lens`	实时代码反馈（LSP / lint / 结构分析）；偏好见 `ai/pi-lens/config.json`
`npm:@juicesharp/rpiv-ask-user-question`	结构化问卷（避免模型瞎猜）
`npm:pi-subagents`	单 agent 委派与脚本化多 agent 工作流
`npm:pi-mcp-adapter`	MCP adapter
`npm:@specode/pi-kimi-cu`	Kimi Computer Use（本机 GUI）安装与 MCP 引导
`npm:@specode/pi-kimi-webbridge-bootstrap`	安装/更新官方 Kimi WebBridge runtime + skill
`npm:pi-antigravity`	Antigravity / Cloud Code Assist provider
`npm:@ogulcancelik/pi-codex-compaction`	复用 Pi compaction 生命周期，调用 OpenAI Codex 原生远程压缩
`npm:@diegopetrucci/pi-openai-fast`	为 ChatGPT 授权的 Codex 模型启用 OpenAI Fast service tier

其他 settings 字段（默认模型、TUI 等）以源文件为准，此处不展开。

Pi — 仓库内自写扩展及扩展配置

源目录：ai/pi/extensions/（清单内文件随 Pi 程序组整组安装 / 回写）

文件	职责（一句话）
`session-ui.ts`	会话层 UI：工具摘要、thinking 展示、剪贴板图片/长文本占位符、增强状态栏、标题 summary、`/effort` 等
`image-gen.ts`	按当前会话 provider 选后端的文生图（xAI 已接，OpenAI 预留）；凭据走 Pi auth，无独立配置文件
`openai-fast.json`	`pi-openai-fast` 扩展本地配置：启用 Fast 模式及状态栏提示

能力细节以各文件头注释或扩展包说明为准，不在 README 复制长列表。

pi-lens 偏好要点

源：ai/pi-lens/config.json

widget 默认隐藏（诊断仍供工具读）
contextInjection.enabled = false（避免打断 prompt cache）

Skills 清单

源：ai/skills.txt
当前：无有效条目（仅注释 / 示例）。

Navigation Menu

Repository files navigation

Dotfiles

用法模型

三个安装阶段

Managed configuration

各组边界（稳定规则）

Skills（`ai/skills.txt`）

Neovim

Requirements

Installation（首次安装）

Update from repository（仓库 → 本机）

Sync from local（本机 → 仓库）

Structure

Living inventory（易变清单）

terminal / Brewfile

ai / Brewfile

Pi — `settings.json` packages

Pi — 仓库内自写扩展及扩展配置

pi-lens 偏好要点

Skills 清单

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 40 Commits
ai		ai
lib		lib
terminal		terminal
README.md		README.md
install.sh		install.sh

Folders and files

Latest commit

History

Repository files navigation

Dotfiles

用法模型

三个安装阶段

Managed configuration

各组边界（稳定规则）

Skills（ai/skills.txt）

Neovim

Requirements

Installation（首次安装）

Update from repository（仓库 → 本机）

Sync from local（本机 → 仓库）

Structure

Living inventory（易变清单）

terminal / Brewfile

ai / Brewfile

Pi — settings.json packages

Pi — 仓库内自写扩展及扩展配置

pi-lens 偏好要点

Skills 清单

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Skills（`ai/skills.txt`）

Pi — `settings.json` packages