move claude-marketplace to ai-proj-helper

2026-03-12 21:42:30 +08:00
parent d7b6835e1d
commit 43585b8504
188 changed files with 39510 additions and 0 deletions
--- a/plugins/dotfiles-plugin/skills/SKILL.md
+++ b/plugins/dotfiles-plugin/skills/SKILL.md
@@ -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 成都机器回归测试