release

插件发布流程

在 MAG Claude Plugins 市场中发布插件新版本的完整指南。

关键认知

Claude Code 插件发现通过两个配置文件实现，必须同时更新：

1. plugins/{plugin-name}/plugin.json - 插件自身的版本元数据
2. .claude-plugin/marketplace.json - 市场目录（用户浏览时看到的内容）

为什么要同时更新？

• plugin.json - 定义插件本身（Agent、命令、版本）
• marketplace.json - Claude Code 用于发现插件的“目录”
• 用户运行 /plugin marketplace update 时会读取 marketplace.json
• 如果只更新 plugin.json，用户将看不到新版本！

---

发布检查清单

步骤 1：更新插件文件

• plugins/{plugin-name}/plugin.json - 更新 version 字段
• plugins/{plugin-name}/agents/*.md - 添加新 Agent（如有）
• plugins/{plugin-name}/commands/*.md - 更新命令（如有）
• plugins/{plugin-name}/skills/*/SKILL.md - 添加新技能（如有）

步骤 2：更新文档

• CHANGELOG.md - 在顶部添加新版本条目
• RELEASES.md - 在顶部添加详细的发布说明
• CLAUDE.md - 更新所有版本引用（6 处以上）

步骤 3：⚠️ 关键 - 更新市场目录

文件： .claude-plugin/marketplace.json

更新两个字段：

1. 市场元数据版本（第 ~10 行）：

   "metadata": {
     "version": "3.3.0"  // ← Update this
   }
   

2. 特定插件版本（在 plugins 数组中）：

   "plugins": [
     {
       "name": "frontend",
       "version": "3.3.0",      // ← Update this (CRITICAL!)
       "description": "..."     // ← Update if description changed
     }
   ]
   

步骤 4：提交并打标签

# Commit all changes
git add -A
git commit -m "feat({plugin}): v{X.Y.Z} - {Feature summary}"

# Create tag (format: plugins/{plugin-name}/v{X.Y.Z})
git tag -a plugins/{plugin}/v{X.Y.Z} -m "..."

# Push
git push origin main
git push origin plugins/{plugin}/v{X.Y.Z}

步骤 5：验证

/plugin marketplace update mag-claude-plugins
# Should show new version ✅

---

常见错误

❌ #1：忘记更新 marketplace.json

症状： 用户运行 /plugin marketplace update 后仍看到旧版本

修复方法：

# Update .claude-plugin/marketplace.json
vim .claude-plugin/marketplace.json
# Update plugins[].version field

git add .claude-plugin/marketplace.json
git commit -m "fix(marketplace): Update {plugin} version to v{X.Y.Z}"
git push origin main

❌ #2：git 标签格式错误

错误： frontend-v3.3.0、v3.3.0、frontend/v3.3.0 正确： plugins/frontend/v3.3.0 ✅

❌ #3：版本不一致

问题： plugin.json 显示 v3.3.0，但 marketplace.json 显示 v3.2.0

预防方法： 使用检查清单，搜索旧版本：grep -r "3.2.0" .

---

版本编号

MAJOR（X.0.0）： 破坏性变更（移除 Agent、更改行为） MINOR（x.Y.0）： 新功能（新增 Agent/命令，向后兼容） PATCH（x.y.Z）： 错误修复（无新功能，向后兼容）

---

快速参考

最简检查清单：

1. ✅ 更新 plugins/{plugin}/plugin.json 版本
2. ✅ 更新 .claude-plugin/marketplace.json 插件版本 ⚠️ 关键
3. ✅ 更新 CHANGELOG.md、RELEASES.md、CLAUDE.md
4. ✅ 提交：git commit -m "feat({plugin}): v{X.Y.Z} - {summary}"
5. ✅ 打标签：git tag -a plugins/{plugin}/v{X.Y.Z} -m "..."
6. ✅ 推送：git push origin main && git push origin plugins/{plugin}/v{X.Y.Z}
7. ✅ 验证：/plugin marketplace update 显示新版本

---

发布示例

# 1. Update versions
vim plugins/frontend/plugin.json          # version: "3.3.0"
vim .claude-plugin/marketplace.json       # plugins[0].version: "3.3.0"  ← DON'T FORGET!
vim CHANGELOG.md RELEASES.md CLAUDE.md

# 2. Commit
git add -A
git commit -m "feat(frontend): v3.3.0 - Multi-Model Plan Review"

# 3. Tag
git tag -a plugins/frontend/v3.3.0 -m "Frontend Plugin v3.3.0"

# 4. Push
git push origin main
git push origin plugins/frontend/v3.3.0

# 5. Verify
/plugin marketplace update mag-claude-plugins
# Output: frontend v3.3.0 ✅

---

故障排除

问：用户仍然看到旧版本 答： 检查 .claude-plugin/marketplace.json - 版本必须与 plugin.json 一致

问：标签已存在 答： 先运行 git tag -d {tag}，再运行 git push origin :{tag}，然后重新创建

问：如何在本地测试？ 答： /plugin marketplace add /path/to/claude-code

---

相关： RELEASE_PROCESS.md - 完整详细文档

最后更新： 2025 年 11 月 13 日