diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index c0aa32f..57223e7 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -174,18 +174,6 @@ ], "strict": false }, - { - "name": "dotfiles-plugin", - "source": "./skills/dotfiles-plugin", - "description": "macOS 新机快速部署。用于 dotfiles 配置管理、install.sh 脚本维护、Claude Code 插件配置、MCP Server 配置。当用户提到新机部署、dotfiles、环境配置相关任务时自动激活。", - "version": "1.0.0", - "category": "utility", - "keywords": [ - "utility", - "tools" - ], - "strict": false - }, { "name": "doubao-voice-plugin", "source": "./skills/doubao-voice-plugin", @@ -620,6 +608,18 @@ ], "strict": false }, + { + "name": "dotfiles-plugin", + "source": "./skills-personal/dotfiles-plugin", + "description": "macOS 新机快速部署。用于 dotfiles 配置管理、install.sh 脚本维护、Claude Code 插件配置、MCP Server 配置。当用户提到新机部署、dotfiles、环境配置相关任务时自动激活。", + "version": "1.0.0", + "category": "utility", + "keywords": [ + "utility", + "tools" + ], + "strict": false + }, { "name": "qiudl-personal-plugin", "source": "./skills-personal/qiudl-personal-plugin", diff --git a/skills/dotfiles-plugin/.claude-plugin/plugin.json b/skills/dotfiles-plugin/.claude-plugin/plugin.json deleted file mode 100644 index ee2a53e..0000000 --- a/skills/dotfiles-plugin/.claude-plugin/plugin.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "name": "dotfiles-plugin", - "description": "macOS 新机快速部署。用于 dotfiles 配置管理、install.sh 脚本维护、Claude Code 插件配置、MCP Server 配置。当用户提到新机部署、dotfiles、环境配置相关任务时自动激活。", - "version": "1.0.0", - "author": { - "name": "qiudl" - } -} diff --git a/skills/dotfiles-plugin/skills/SKILL.md b/skills/dotfiles-plugin/skills/SKILL.md deleted file mode 100644 index 72e54da..0000000 --- a/skills/dotfiles-plugin/skills/SKILL.md +++ /dev/null @@ -1,469 +0,0 @@ ---- -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 成都机器回归测试