move claude-marketplace to ai-proj-helper
This commit is contained in:
8
plugins/dotfiles-plugin/.claude-plugin/plugin.json
Normal file
8
plugins/dotfiles-plugin/.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"name": "dotfiles-plugin",
|
||||
"description": "macOS 新机快速部署。用于 dotfiles 配置管理、install.sh 脚本维护、Claude Code 插件配置、MCP Server 配置。当用户提到新机部署、dotfiles、环境配置相关任务时自动激活。",
|
||||
"version": "1.0.0",
|
||||
"author": {
|
||||
"name": "qiudl"
|
||||
}
|
||||
}
|
||||
469
plugins/dotfiles-plugin/skills/SKILL.md
Normal file
469
plugins/dotfiles-plugin/skills/SKILL.md
Normal file
@@ -0,0 +1,469 @@
|
||||
---
|
||||
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 成都机器回归测试
|
||||
Reference in New Issue
Block a user