Dotfiles

Dotfiles

面向 100x 吞吐量的 AI Agent 编排基础设施。可在任意 harness（Claude Code、Amazon Q、Codex）上并行运行 Agent，通过可复现的配置落实各项原则，并让你的开发栈自我修复。

Dotfiles 理念

我们的 dotfiles 仓库遵循三项核心理念，指导我们进行配置管理：

打翻咖啡原则

“打翻咖啡原则”指出，任何人都应该能够在毁掉自己的机器后，当天下午就完全恢复工作状态。这一原则强调：

• 所有配置变更都应能跨机器复现
• 安装脚本应处理文件操作，而不是手动执行命令
• 安装脚本应检测并创建所需目录
• 符号链接应由安装脚本管理，而不是手动创建
• 依赖项和安装步骤应得到完整记录

❌ 常见违规做法——手动终端英雄主义：

就像《凤凰项目》里的 Brent 一样，我们常常因为成为那个“手动修复问题的救火英雄”而变成瓶颈。这些命令在脚本中完全合理，但直接在终端中输入时就成了反模式：

# IN TERMINAL (BAD - Makes you Brent, the bottleneck hero):
dotfiles (main) $ ln -s mcp/mcp.json .mcp.json      # Works today, forgotten tomorrow
dotfiles (main) $ mv .bashrc .bashrc.backup          # Your knowledge, lost when you leave
dotfiles (main) $ chmod 600 ~/.bash_secrets          # New teammate: "Why doesn't this work?"
dotfiles (main) $ mkdir -p ~/ppv/pillars             # "It worked on my machine..."
dotfiles (main) $ echo "alias q='q'" >> ~/.bashrc   # Snowflake environment alert!
dotfiles (main) $ curl -o tool.tar.gz https://...    # Downloaded where? What version?

# The exact violation that inspired this documentation:
dotfiles (feature/vendor-agnostic-mcp-692) $ ln -s mcp/mcp.json .mcp.json
# ↑ I actually did this! Then immediately undid it and wrote a script instead.

Brent 测试：如果你被公交车撞了（或者去度假），别人能重现你所做的事吗？如果它只存在于你的终端历史里，那你就是在当 Brent。

✅ 脚本中的相同命令（好——不再有 Brent！）：

# IN SCRIPTS (GOOD - Knowledge is codified, not tribal):

# setup-vendor-agnostic-mcp.sh
ln -s mcp/mcp.json "$REPO_ROOT/.mcp.json"  # Reproducible by anyone

# setup.sh  
mkdir -p "$HOME/ppv/pillars"                # Self-documenting
chmod 600 ~/.bash_secrets                   # Security automated

# install-tool.sh
download_and_install_tool() {
    curl -o "$TEMP_DIR/tool.tar.gz" https://...  # Version controlled
}

凤凰原则：从“Brent 做了这件事”转变为“系统做了这件事”。每一条会改变状态的终端命令都应变成代码，从而消除对关键人员的依赖。

试金石：你能毁掉自己的笔记本电脑，换一台新的，运行 git clone && ./setup.sh，然后回到和之前完全一样的状态吗？如果不能，那你一直是个英雄，而不是一名管家。

这一原则确保系统在面对故障或搭建新环境时具备韧性和快速恢复能力。

滚雪球方法

参见 滚雪球方法——通过日复一日的积累获得复利回报。这一原则确保我们的开发环境通过每天进步 1%，随时间持续改善。

Agent 编排基础设施

该系统支持 宏观层面的 Agent 管理，而不是微观层面的文件编辑——你管理的是任务和项目，而不是 IDE 中的代码行。核心基础设施包括：

• 与 Harness 无关的配置：单个 .agent-config.yml 定义用户偏好、Agent 设置和路径——可在 Claude Code、Amazon Q 和 Codex 之间通用，无需重复配置（参见 config-architecture.md）
• 可复现的 Agent 流程：commands/ 目录中的斜杠命令（/close-issue、/create-issue、/extract-best-frame、/retro）在所有 AI harness 中落实一致的工作流
• 遥测与反馈：OpenTelemetry 可观测性栈配合 Grafana 仪表盘，提供实时性能监控和持续改进洞察（参见 observability/README.md）
• 并行执行：使用 tmux + git worktrees，你可以在并行任务中同时管理多个 AI Agent
• 原则落实：knowledge/procedures/ 和 knowledge/principles/ 会自动加载到 Agent 上下文中，以保持一致性

目标：通过 AI Agent 管理能力实现 100x-1000x 的开发者生产力。参见 吞吐量定义。

模块化 Shell 配置

本仓库对 shell 配置采用模块化方式：

# Load modular alias files from .bash_aliases.d directory
if [ -d "$HOME/.bash_aliases.d" ]; then
  for module in "$HOME/.bash_aliases.d"/*.sh; do
    if [ -f "$module" ]; then
      source "$module"
    fi
  done
fi

这种模式提供：

• 关注点分离——每个文件专注于一个特定工具
• 懒加载——仅在文件存在时才进行加载
• 命名空间整洁——避免污染全局命名空间

模块存放在 .bash_aliases.d/<tool-name>.sh 中，并在存在时自动加载。

组织上下文：P.P.V 系统

本仓库通常位于 ~/ppv/pillars/dotfiles/，属于一个三层组织系统的一部分：

• Pillars：核心仓库和基础配置（你在这里）
• Pipelines：自动化脚本和工作流仓库
• Vaults：凭证和公司特定内部知识的安全存储

该结构在分离关注点的同时，保持跨项目和环境的布局一致。

系统工作的 80/20 法则

遵循《程序员修炼之道》中的“记住大局”——不要过于沉迷系统优化，以至于在核心工作上失去动力：

• 80% 工作：集成系统、自动化（打翻咖啡原则）、Agent 编排
• 20% 系统优化：完善配置、优化工作流、元工作

目标是让系统赋能工作，而不是让系统本身成为目的。在基础设施改进与实际价值交付之间取得平衡。

全局优先配置

这一原则确立了 dotfiles 中的配置应默认全局应用，除非明确标记为其他情况。这与 dotfiles 仓库的根本目的相一致——在整个系统中提供一致的配置。

核心原则：实现功能时，倾向于全局配置而非局部配置。Dotfiles 用于全局配置。

实施指南：

• 默认：让配置成为全局（系统级）
• 例外：如果某个配置必须是局部的，请说明原因，并添加使其成为全局的计划
• 模式：使用别名、符号链接或工具特定的全局配置位置

示例：

• ✅ 通过带有 --mcp-config 的 claude 别名进行 MCP 配置（默认全局）
• ✅ 从 ~/.bashrc 加载的 Bash 别名（处处适用）
• ⚠️ Claude Code 设置迁移到 ~/.claude/settings.json（进行中，见 #577）

文档区分：

• README.md：仓库特定的文档和原则（本文件）
• knowledge/ 目录：适用于所有仓库的全局上下文
  • 自动包含在 AI 助手上下文窗口中
  • 包含处处使用的原则、流程和模式
  • 可将其视为随身携带的“可移植智慧”

如有疑问，请自问：“这是否应适用于我编写代码的所有地方？”如果是 → 全局配置。如果它特定于这个 dotfiles 仓库的工作方式 → 将其记录在此处的 README.md 中。

仓库设计模式

本仓库遵循特定的组织模式，以保持一致性和清晰度：

基于平台的组织（顶层）

在根级别，配置按平台或环境组织：

• arch-linux/ - 特定于 Arch Linux 系统的配置
• raspberry-pi/ - Raspberry Pi 设备的配置
• nvim/ - 文本编辑器配置（旧版/可选）
• 等。

这种结构组织清楚地表明哪些文件适用于哪些环境。

混合组织（平台内）

在每个平台目录内，我们使用一种结合类别和特定用例的混合方法：

raspberry-pi/
├── home/                  # Home use cases
│   ├── home-assistant/    # Smart home hub
│   └── media-server/      # Media streaming
├── development/           # Development use cases
│   └── ci-runner/         # Self-hosted CI/CD
└── networking/            # Networking use cases
    └── network-monitor/   # Traffic analysis

这种方法：

• 按通用类别组织，便于维护
• 提供具体示例以提高清晰度
• 允许用户根据预期用例查找配置

基于功能的实现

功能的实际实现遵循以下原则：

1. 检测优于假设：脚本检测硬件能力，而不是假设特定用例
2. 可组合性：功能可以根据用户需求混合搭配
3. 自动优化：硬件特定的优化会自动应用
4. 清晰文档：每个功能都记录其目的和需求

这种多层次的组织方法使我们能够维护一个干净的仓库结构，同时为不同的用例提供灵活性。

快速设置

设置你的 Dotfiles

开始使用你的个性化环境：

# Clone the repository and run setup
git clone https://github.com/atxtechbro/dotfiles.git ~/ppv/pillars/dotfiles
cd ~/ppv/pillars/dotfiles
source setup.sh

设置脚本会自动处理：

• 软件包安装和依赖管理
• 创建所有必要的符号链接
• 从模板设置你的机密文件
• 立即应用配置
• 安装并配置必备工具（tmux、Amazon Q CLI、GitHub CLI 等）

遵循“打翻咖啡原则”——设置脚本确保你运行一次后即可完全投入使用。

自定义克隆位置

默认情况下，这些 dotfiles 假定你克隆到 ~/ppv/pillars/dotfiles。如果你想克隆到其他位置（例如 ~/dotfiles 或 ~/code/dotfiles），请在运行 source setup.sh 之前，在 ~/.bash_exports.local 中设置 DOT_DEN 环境变量：

# Clone to your preferred location
git clone https://github.com/atxtechbro/dotfiles.git ~/my/custom/path

# Create ~/.bash_exports.local with your custom path
echo 'export DOT_DEN="$HOME/my/custom/path"' >> ~/.bash_exports.local

# Now run setup
cd ~/my/custom/path
source setup.sh

~/.bash_exports.local 文件不受 git 跟踪（它是特定于机器的），因此每台机器都可以有自己的克隆位置。如果你不创建此文件，则使用默认的 ~/ppv/pillars/dotfiles。

使用 Worktree 进行并行开发

为了同时处理多个功能，我们支持 git worktree：

# Create a new worktree for your feature
cd ~/ppv/pillars/dotfiles
git worktree add -b feature/my-feature worktrees/feature/my-feature

# Set up the worktree environment
cd worktrees/feature/my-feature
source setup.sh

每个 worktree 都是自包含的，拥有自己的 MCP 服务、二进制文件和依赖项。详细说明请参阅 docs/worktree-development.md。

AI Harness 无关的上下文

此仓库会自动从单一事实来源为多个 AI 开发 harness 配置全局上下文：

• Amazon Q Developer CLI：使用自动 MCP 导入（q mcp import --file mcp/mcp.json global --force）
• Claude Code：使用直接配置引用（--mcp-config mcp/mcp.json）

所有上下文均来自 knowledge/ 目录，并且 MCP 服务在各个 harness 中的配置完全一致。

Harness 对称性

两个 AI harness 通过不同的集成方法使用相同的 MCP 服务配置：

# Single source of truth
GLOBAL_MCP_CONFIG="$DOT_DEN/mcp/mcp.json"

# Claude Code: Direct file reference
alias claude='claude --mcp-config "$GLOBAL_MCP_CONFIG" --add-dir "$DOT_DEN/knowledge"'

# Amazon Q: Automatic import
alias q='q mcp import --file "$GLOBAL_MCP_CONFIG" global --force >/dev/null 2>&1; command q'

危机韧性：当 Claude Code 遇到 500“Overloaded”错误时，Amazon Q 提供相同的 MCP 服务访问和能力。这种 harness 无关性确保服务中断期间工作流不中断。

可用的 MCP 服务：两个 harness 都可以访问 git 操作、GitHub 集成、文件系统操作、knowledge 目录上下文以及工作专用服务（当 WORK_MACHINE=true 时）。

Claude Code 设置

全局 Claude Code 设置通过 .claude/settings.json 管理。此文件由设置脚本符号链接到 ~/.claude/settings.json，确保设置在所有项目间持久保留。

要添加或修改 Claude Code 设置：

1. 在 dotfiles 仓库中编辑 .claude/settings.json
2. 运行 source setup.sh 以更新符号链接
3. 设置将全局应用于所有 Claude Code 会话

当前已配置的设置包括共同作者署名、MCP 服务、权限等。

Claude Code 插件

通过 Claude Code 的插件系统在仓库之间共享斜杠命令。

命令：/close-issue、/create-issue、/extract-best-frame、/retro

安装（在 Claude Code 聊天中）：

/plugin marketplace add atxtechbro/dotfiles
/plugin install dotfiles-commands@atxtechbro

然后重启 Claude Code，命令才会出现在自动补全中。

命令符号链接到 knowledge/procedures/，以实现单一事实来源。

全局 MCP 配置

这些 dotfiles 可从你系统上的任何目录全局访问 MCP（Model Context Protocol）服务。运行 source setup.sh 后，MCP 服务可通过 claude 命令别名自动使用。

工作原理

1. 集中配置：MCP 服务定义在 mcp/mcp.json 中
2. 全局别名：claude 命令被别名化，自动包含 --mcp-config
3. 随处可用：无需将 .mcp.json 文件复制到每个项目目录

可用命令

# Standard claude command (includes global MCP config automatically)
claude "What files are in this directory?"

# Check current MCP configuration
claude-mcp-info

# Use strict global config (ignores any local .mcp.json files)
claude-global "Run a command with only global MCP servers"

# Add user-scoped servers (persists across all projects)
claude mcp add my-server -s user /path/to/server

包含的 MCP 服务

这些 dotfiles 包含为以下用途预配置的 MCP 服务：

• Playwright 浏览器自动化（用于需要浏览器交互的任务）

注意：Git、GitHub 和网络搜索由 Claude Code 原生处理（实验 #1213）

Claude 模型偏好

个人计算机会自动使用 Opus 模型（claude-opus-4-20250514）以获得最大能力。这由 WORK_MACHINE 环境变量控制：

• 个人计算机：在 ~/.bash_exports.local 中设置 WORK_MACHINE="false" → 默认使用 Opus 模型
• 工作计算机：设置 WORK_MACHINE="true" → 标准模型选择

无需手动切换模型 —— 系统会根据你的计算机类型自动选择正确的模型。

密钥管理

API 令牌等敏感信息存储在 ~/.bash_secrets 中（不纳入 git 跟踪）。

# Create your personal secrets file from the example template
cp ~/ppv/pillars/dotfiles/.bash_secrets.example ~/.bash_secrets

# Set proper permissions to protect your secrets
chmod 600 ~/.bash_secrets

# Edit the file to add your specific secrets
nano ~/.bash_secrets

.bash_secrets 文件由 .bashrc 自动加载。它提供了一个用于管理密钥和环境变量的框架，并包含常见模式的示例。你应根据自己的需求对其进行自定义。

对于公司特定的密钥，可考虑在 Vaults 目录中维护一个单独的私有仓库。