Files

guoym 43585b8504 move claude-marketplace to ai-proj-helper

2026-03-12 21:42:30 +08:00

11 KiB

Raw Blame History

name, description

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

dotfiles - macOS 新机快速部署

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

核心功能

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

子文档索引

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

快速开始

1. 克隆 dotfiles

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

2. 执行安装脚本

./install.sh

注意：

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

3. 配置 MCP Server

# 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 插件批量安装清单

格式要求（⚠️ 必须遵守）：

# ✅ 正确格式 - 统一 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

常见错误：

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

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

详细规范：见 config-formats.md

2. settings.json.template

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

格式要求（⚠️ 必须遵守）：

{
  "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

3. .env.example

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

必需变量：

# 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

检查完整性：

# .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)

验证部署结果

快速检查

# 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 回归测试经验）：

~/.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

常见问题

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

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

解决：

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

2. envsubst 命令未找到

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

解决：

brew install gettext

3. 插件安装失败

原因：

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

解决：

# 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 文件缺少对应变量
变量名拼写错误

解决：

# 检查 .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

最佳实践

1. 版本控制

提交内容：

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

检查 .gitignore：

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

2. 多机同步

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

策略：

# 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. 测试驱动配置

修改配置文件前：

在测试机上验证（如成都 Mac Mini）
运行回归测试脚本
确认所有测试通过后再提交

示例工作流（基于 REQ-20260220-0002）：

# 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: 段落格式

预防：

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

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

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

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

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

预防：

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

问题3: .env.example 不完整

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

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

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

预防：

# 完整性检查脚本（见 scripts/check-env-completeness.sh）
~/.dotfiles/scripts/check-env-completeness.sh

问题4: .env 未加入 .gitignore

现象：敏感 Token 被提交到 Git

原因：.gitignore 缺少 .env 条目

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

预防：

# 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 成都机器回归测试

11 KiB Raw Blame History Unescape Escape