---
name: dotfiles
description: macOS 新机快速部署。用于 dotfiles 配置管理、install.sh 脚本维护、Claude Code 插件配置、MCP Server 配置。当用户提到新机部署、dotfiles、环境配置相关任务时自动激活。
---

# dotfiles - macOS 新机快速部署

自动化 macOS 开发环境配置，包括 Homebrew、Claude Code、插件、MCP Server 等。

## 核心功能

1. **配置文件管理** - dotfiles 符号链接、Git 配置同步
2. **Claude Code 配置** - 插件批量安装、MCP Server 配置模板
3. **开发工具安装** - Homebrew、mise、SSH 配置
4. **环境一致性** - 多台电脑配置同步

## 子文档索引

| 文档 | 说明 |
|------|------|
| [config-formats.md](docs/config-formats.md) | 配置文件格式规范（必读） |
| [testing.md](docs/testing.md) | 部署验证与测试方法 |
| [troubleshooting.md](docs/troubleshooting.md) | 常见问题与解决方案 |

---

## 快速开始

### 1. 克隆 dotfiles

```bash
git clone git@gitea.pipexerp.com:huangjun/dotfiles.git ~/.dotfiles
cd ~/.dotfiles
```

### 2. 执行安装脚本

```bash
./install.sh
```

**注意**：
- 需要 sudo 权限（安装 Homebrew）
- 需要手动输入密码（非交互式 SSH 无法自动化）
- 首次运行约 10-15 分钟

### 3. 配置 MCP Server

```bash
# 1. 复制环境变量模板
cp ~/.dotfiles/claude/.env.example ~/.dotfiles/claude/.env

# 2. 编辑填入真实 Token
vim ~/.dotfiles/claude/.env

# 3. 删除现有 settings.json（如果已存在）
rm ~/.claude/settings.json

# 4. 重新运行 install.sh 生成配置
cd ~/.dotfiles && ./install.sh
```

---

## 配置文件结构

```
~/.dotfiles/
├── install.sh                    # 主安装脚本
├── .zshrc                        # Zsh 配置
├── .gitconfig                    # Git 配置
├── Brewfile                      # Homebrew 软件清单
├── claude/
│   ├── plugins-list.yaml         # Claude Code 插件清单
│   ├── settings.json.template    # MCP Server 配置模板
│   ├── .env.example              # 环境变量示例
│   └── .env                      # 实际环境变量（不提交）
├── claude-skills/                # Claude Code 技能目录
└── mise/
    └── config.toml               # mise 全局配置
```

---

## 关键组件说明

### 1. plugins-list.yaml

**作用**：Claude Code 插件批量安装清单

**格式要求**（⚠️ 必须遵守）：
```yaml
# ✅ 正确格式 - 统一 plugins: 段落
plugins:
  - name: context7
    marketplace: claude-plugins-official
    description: 文档检索与上下文管理

  - name: req-plugin
    marketplace: claude-marketplace
    description: 需求工作流管理

# 市场源 URL 配置
marketplace:
  claude-marketplace:
    url: git@gitea.pipexerp.com:huangjun/claude-marketplace.git
    type: git
```

**常见错误**：
```yaml
# ❌ 错误格式 - 分段格式（install.sh 无法解析）
official_plugins:
  - name: context7
    marketplace: claude-plugins-official

private_plugins:
  - name: req-plugin
    marketplace: claude-marketplace
```

**详细规范**：见 [config-formats.md](docs/config-formats.md#plugins-listyaml)

### 2. settings.json.template

**作用**：MCP Server 配置模板，由 install.sh 使用 envsubst 渲染

**格式要求**（⚠️ 必须遵守）：
```json
{
  "mcpServers": {
    "ai-proj": {
      "command": "node",
      "args": [
        "${HOME}/coding/qiudl/new-ai-proj/mcp-task-bridge/dist/index.js"
      ],
      "env": {
        "TASK_API_BASE": "${AI_PROJ_API_BASE}",
        "TASK_API_TOKEN": "${AI_PROJ_API_TOKEN}"
      }
    }
  }
}
```

**占位符格式**：
- ✅ 使用 `${VAR}` (envsubst 兼容)
- ❌ 禁止使用 `{{VAR}}` (envsubst 不支持)

**详细规范**：见 [config-formats.md](docs/config-formats.md#settingsjsontemplate)

### 3. .env.example

**作用**：环境变量示例文件，用户复制为 `.env` 后填入真实值

**必需变量**：
```bash
# ai-proj MCP Server
AI_PROJ_API_BASE=https://ai.pipexerp.com/api/v1
AI_PROJ_API_TOKEN=your_token_here

# WPS MCP Server
WPS_APP_ID=your_wps_app_id
WPS_APP_KEY=your_wps_app_key

# 飞书 MCP Server
FEISHU_APP_ID=your_feishu_app_id
FEISHU_APP_SECRET=your_feishu_secret

# 工作区路径（可选，默认 ~/workspace）
WORKSPACE=~/coding/qiudl
```

**检查完整性**：
```bash
# .env.example 必须包含 settings.json.template 中的所有 ${VAR}
diff <(grep -oE '\${[A-Z_]+}' ~/.dotfiles/claude/settings.json.template | sort -u) \
     <(grep -oE '^[A-Z_]+=' ~/.dotfiles/claude/.env.example | sed 's/=$//' | sort)
```

---

## install.sh 工作流程

```
1. 检查/安装 Homebrew
   └─ 需要 sudo 密码（手动输入）

2. 安装 Homebrew 软件
   └─ 从 Brewfile 读取软件列表

3. 创建符号链接
   ├─ ~/.zshrc -> ~/.dotfiles/.zshrc
   ├─ ~/.gitconfig -> ~/.dotfiles/.gitconfig
   └─ ~/.config/mise/config.toml -> ~/.dotfiles/mise/config.toml

4. 配置 Claude Code 插件
   ├─ 添加私有市场源（claude-marketplace）
   └─ 批量安装 plugins-list.yaml 中的插件

5. 渲染 MCP 配置
   ├─ 检查 envsubst 是否安装
   ├─ 加载 ~/.dotfiles/claude/.env
   └─ 渲染 settings.json.template -> ~/.claude/settings.json

6. 创建本地配置
   └─ ~/.zshrc.local (MY_BRANCH, OTHER_BRANCH)
```

---

## 验证部署结果

### 快速检查

```bash
# 1. 检查符号链接
ls -la ~ | grep -E '\.zshrc|\.gitconfig'

# 2. 检查 Homebrew
which brew
brew --version

# 3. 检查 Claude Code
which claude
claude --version

# 4. 检查 MCP 配置
cat ~/.claude/settings.json | grep -E 'mcpServers|ai-proj'

# 5. 检查插件
claude /plugin list
```

### 完整验证

运行测试脚本（基于 REQ-20260220-0002 回归测试经验）：

```bash
~/.dotfiles/scripts/verify-deployment.sh
```

**测试内容**：
- TC-01: 私有市场源自动添加
- TC-02: plugins-list.yaml 格式验证
- TC-03: 插件批量安装验证
- TC-04: settings.json.template 格式验证
- TC-05: .env.example 完整性检查
- TC-06: .env 在 .gitignore 中
- TC-07: settings.json 模板渲染测试
- TC-08: 完整 install.sh 执行测试

详见 [testing.md](docs/testing.md)

---

## 常见问题

### 1. install.sh 执行时提示需要 sudo 密码

**原因**：Homebrew 安装需要管理员权限

**解决**：
- 本地执行：直接输入密码
- 远程 SSH：无法自动化，需用户在本地终端执行

### 2. envsubst 命令未找到

**原因**：envsubst 由 gettext 包提供，install.sh 会自动安装

**解决**：
```bash
brew install gettext
```

### 3. 插件安装失败

**原因**：
- 市场源未添加
- SSH 密钥未配置（私有仓库）
- 插件名称错误

**解决**：
```bash
# 1. 检查市场源
ls ~/.claude/marketplaces/

# 2. 手动添加市场源
claude /plugin marketplace add git@gitea.pipexerp.com:huangjun/claude-marketplace.git

# 3. 配置 SSH 密钥
cat ~/.ssh/config  # 检查 gitea.pipexerp.com 配置
ssh -T git@gitea.pipexerp.com  # 测试 SSH 连接
```

### 4. settings.json 渲染后仍有 ${VAR}

**原因**：
- .env 文件缺少对应变量
- 变量名拼写错误

**解决**：
```bash
# 检查 .env 是否包含所有必需变量
diff <(grep -oE '\${[A-Z_]+}' ~/.dotfiles/claude/settings.json.template | sed 's/[${}]//g' | sort -u) \
     <(grep -oE '^[A-Z_]+=' ~/.dotfiles/claude/.env | sed 's/=.*//' | sort)
```

更多问题见 [troubleshooting.md](docs/troubleshooting.md)

---

## 最佳实践

### 1. 版本控制

**提交内容**：
- ✅ 配置模板（.env.example, settings.json.template）
- ✅ 安装脚本（install.sh）
- ✅ 插件清单（plugins-list.yaml）
- ❌ 敏感信息（.env, *.pem, *.key）

**检查 .gitignore**：
```bash
# 确保以下条目存在
grep -E '^\\.env$|^claude/\\.env$|^\\.pem$' ~/.dotfiles/.gitignore
```

### 2. 多机同步

**场景**：澳洲电脑 + 中国电脑 + 成都 Mac Mini

**策略**：
```bash
# 1. 统一配置由 Git 同步
git pull origin main

# 2. 机器特定配置写入 ~/.zshrc.local
echo "MY_BRANCH=au-dev" >> ~/.zshrc.local
echo "OTHER_BRANCH=cn-dev" >> ~/.zshrc.local

# 3. .zshrc 自动加载 .zshrc.local
[ -f ~/.zshrc.local ] && source ~/.zshrc.local
```

### 3. 测试驱动配置

**修改配置文件前**：
1. 在测试机上验证（如成都 Mac Mini）
2. 运行回归测试脚本
3. 确认所有测试通过后再提交

**示例工作流**（基于 REQ-20260220-0002）：
```bash
# 1. 修改配置
vim ~/.dotfiles/claude/plugins-list.yaml

# 2. 提交到 Git
git add claude/plugins-list.yaml
git commit -m "fix: 统一 plugins-list.yaml 格式"

# 3. 推送到远程
git push origin main

# 4. 在测试机验证
ssh chengdu "cd ~/.dotfiles && git pull && ./scripts/verify-deployment.sh"
```

---

## 相关技能

| 技能 | 用途 |
|------|------|
| `ops-tools` | 服务器运维工具 |
| `dev-test` | 软件测试方法论 |
| `req` | 需求工作流管理 |
| `skill-manager` | 技能自我进化管理 |

---

## 经验教训（REQ-20260220-0002）

### 问题1: plugins-list.yaml 格式不兼容

**现象**：install.sh 无法解析插件列表

**原因**：使用了分段格式（official_plugins/private_plugins），install.sh 只解析 `plugins:` 段落

**解决**：统一使用 `plugins:` 段落格式

**预防**：
```bash
# 格式验证脚本
grep -E '^official_plugins:|^private_plugins:' ~/.dotfiles/claude/plugins-list.yaml && \
  echo "❌ 检测到旧格式" || echo "✅ 格式正确"
```

### 问题2: settings.json.template 占位符错误

**现象**：envsubst 渲染后仍有 {{VAR}}

**原因**：使用了 {{VAR}} 格式，envsubst 只支持 ${VAR}

**解决**：全局替换 `{{` -> `${`, `}}` -> `}`

**预防**：
```bash
# 检查占位符格式
grep '{{' ~/.dotfiles/claude/settings.json.template && \
  echo "❌ 使用了不兼容格式" || echo "✅ 格式正确"
```

### 问题3: .env.example 不完整

**现象**：渲染后 settings.json 包含未替换的 ${VAR}

**原因**：.env.example 缺少某些变量定义

**解决**：确保 .env.example 包含 settings.json.template 中的所有变量

**预防**：
```bash
# 完整性检查脚本（见 scripts/check-env-completeness.sh）
~/.dotfiles/scripts/check-env-completeness.sh
```

### 问题4: .env 未加入 .gitignore

**现象**：敏感 Token 被提交到 Git

**原因**：.gitignore 缺少 .env 条目

**解决**：添加 `.env` 和 `claude/.env` 到 .gitignore

**预防**：
```bash
# Git 提交前 hook 检查
git diff --cached --name-only | grep -E '\\.env$' && \
  echo "⚠️ 警告：尝试提交 .env 文件" && exit 1
```

---

## 部署检查清单

部署到新机器前，确认以下事项：

- [ ] dotfiles 仓库已克隆到 ~/.dotfiles
- [ ] SSH 密钥已配置（Gitea 访问）
- [ ] 用户有 sudo 权限
- [ ] 已复制 .env.example 为 .env 并填入真实 Token
- [ ] plugins-list.yaml 格式正确（统一 plugins: 段落）
- [ ] settings.json.template 使用 ${VAR} 格式
- [ ] .env 在 .gitignore 中
- [ ] 网络可访问 Homebrew、Gitea、MCP API

部署后验证：

- [ ] 运行 `~/.dotfiles/scripts/verify-deployment.sh`
- [ ] 检查所有测试用例通过
- [ ] 手动验证 Claude Code 能连接 MCP Server
- [ ] 手动验证插件已正确安装

---

**更新时间**: 2026-02-20
**维护者**: qiudl
**数据来源**: REQ-20260220-0002 成都机器回归测试