⚡

发布管理Skill release

这个技能用于自动化管理npm包的版本发布和CI/CD工作流程，适用于monorepo项目如swarm-tools。它包括创建changesets、运行持续集成、自动发布到npm注册表、验证发布状态等。关键词：npm发布、changesets、CI/CD、自动化发布、版本管理、DevOps、monorepo管理。

DevOps 0 次安装 0 次浏览 更新于 3/19/2026

名称: 发布 描述: | 处理 swarm-tools monorepo（opencode-swarm-plugin, claude-code-swarm-plugin, swarm-mail, swarm-queue）的版本提升和 npm 发布。使用场景：创建 changesets、提升版本、准备发布、检查发布状态、调试发布失败、验证 npm 包或合并发布 PR。 触发器：“发布”, “发布”, “changeset”, “提升版本”, “交付”, “新版本”, “创建发布”, “检查 npm”, “验证发布”, “/发布”

发布工作流程

标准发布（CI驱动）

所有发布都经过 changesets → CI → npm。除非 CI 损坏，否则切勿手动发布。

1. 创建 changeset

cat > .changeset/<描述性名称>.md << 'EOF'
---
"opencode-swarm-plugin": patch
---

fix: 描述更改内容和原因
EOF

提升级别: patch（错误修复）, minor（新功能）, major（破坏性更改）。

包含哪些包 — 仅包含实际更改的包：

  • opencode-swarm-plugin — 主插件（CLI、MCP 服务器、群组编排）
  • claude-code-swarm-plugin — 薄 Claude Code 包装器（命令、代理、钩子、技能）
  • swarm-mail — 代理消息传递、内存、预订
  • swarm-queue — 任务队列

使用 pdf-brain 获取提交引用：

pdf-brain search "<相关主题>" --limit 1 --expand 500

2. 提交和推送

git add .changeset/<名称>.md <更改的文件>
git commit -m "feat: 描述"
git push origin main

3. CI 创建发布 PR

CI (publish.yml) 在推送到 main 时运行：

  1. 检测 changesets → 运行 changeset version + bun update
  2. 同步 plugin.json 版本（生命周期钩子在 .changeset/config.json）
  3. 在 changeset-release/main 分支上打开/更新 PR
  4. AI 通过 vercel/ai-action 生成 PR 标题

4. 合并发布 PR

gh pr merge <编号> --squash --delete-branch

CI 然后：

  1. 构建所有包
  2. 验证 tarball 包含预期工件
  3. 运行 scripts/ci-publish.sh — 使用 bun pm pack 打包（解析 workspace:*），通过 npm publish 发布
  4. 标记发布
  5. 生成并发布推文到 @swarmtoolsai

5. 验证

npm view opencode-swarm-plugin@latest dependencies
npm view claude-code-swarm-plugin@latest version

关键检查：验证已发布依赖中没有 workspace:*。如果找到，发布脚本的安全网失败 — 参见故障排除。

版本接触点

CI 通过 changesets 处理所有这些。对于手动提升，必须全部更新：

包 文件
opencode-swarm-plugin packages/opencode-swarm-plugin/package.json, claude-plugin/.claude-plugin/plugin.json
claude-code-swarm-plugin packages/claude-code-swarm-plugin/package.json, .claude-plugin/plugin.json
swarm-mail packages/swarm-mail/package.json
swarm-queue packages/swarm-queue/package.json

手动提升脚本：./scripts/bump-version.sh <版本>

故障排除

已发布的 npm 包中有 workspace:*

scripts/ci-publish.sh 使用 bun pm pack（解析工作区协议）+ python3 安全网，重写任何剩余的 workspace:* 为实际版本。如果仍然失败：

  1. 检查 bun 版本 — 根 package.json 中的 packageManager 必须 >= 1.3.5
  2. 验证安全网运行 — 如果工作区依赖泄漏，CI 日志应显示 “resolving from monorepo”
  3. 核选项：提升损坏的包（patch changeset），推送，合并发布 PR

CI 发布失败，错误 E403

版本已发布。重新运行发布时正常 — || true 捕获它。仅当版本未提升（changeset 未应用）时出现问题。

Plugin.json 版本不匹配

CI 生命周期钩子应同步这些。如果没有，手动：

VERSION=$(jq -r .version packages/opencode-swarm-plugin/package.json)
jq ".version = \"$VERSION\"" packages/opencode-swarm-plugin/claude-plugin/.claude-plugin/plugin.json > /tmp/p.json
mv /tmp/p.json packages/opencode-swarm-plugin/claude-plugin/.claude-plugin/plugin.json

发布 PR 未创建/更新

Changesets 操作仅当 .changeset/*.md 文件存在时运行（不包括 README.md）。如果没有 changesets，它跳过版本 PR 创建并直接转到发布（对于任何未发布版本的包）。

架构说明

  • 两个 Claude Code 插件: opencode-swarm-plugin（完整，捆绑 MCP 服务器 + CLI）和 claude-code-swarm-plugin（薄包装器，调用 swarm CLI）。两者注册为插件名称 “swarm”。
  • 发布脚本 (scripts/ci-publish.sh): 迭代所有 packages/*，跳过私有，打包，解析工作区依赖，发布 tarball。
  • Changeset 配置 (.changeset/config.json): 公共访问，GitHub 变更日志，忽略 @swarmtools/web。
  • 推文机器人: CI 通过 claude-opus 生成发布推文并通过 OAuth 发布到 X。包括 Cloudflare 重试逻辑。