语言:English | 中文
适用对象:参与 CrewBee 仓库开发、维护和发布的开发者与维护者。如果只是安装或使用 CrewBee,请从安装指南开始。
本文覆盖本地维护者流程、GitHub Actions CI/CD、官方发布、npm publish 和发布后验证。普通 CrewBee 用户不需要阅读本文。
CrewBee 当前支持两条并行流程:
- 保留本地开发 pack / install 流程,用于日常开发验证。
- 提供 registry publish 流程,让 OpenCode 可以通过 package name
crewbee加载 CrewBee。
这与 oh-my-openagent 使用的 package-name-first 模型一致:
{
"plugin": ["crewbee"]
}当 OpenCode 支持 package-name plugin resolution 时,这份配置可以让它从已发布的 npm package 中解析 CrewBee。
本地开发与验证使用:
npm install
npm run pack:local
npm run install:local:user
npm run doctor产物:
- 稳定本地 tarball:
.artifacts/local/crewbee-local.tgz - OpenCode plugin config entry:
crewbee
当你正在本地迭代,并希望发布前测试 package 时使用该流程。
用于正式线上分发:
- npm package name:
crewbee - OpenCode config plugin entry:
crewbee - publish target:npm registry
- release automation:支持本地脚本和 GitHub Actions
当你希望在本机准备或手动发布时使用该路径。
npm run pack:release- 在
.artifacts/release/中构建带版本号的 tarball
- 在
node ./scripts/release-registry.mjs --dryRun- 计算下一个版本
- 更新本地 package 文件
- 运行
typecheck、test、doctor、simulators、pack:release和 package smoke - 不发布
node ./scripts/release-registry.mjs --publish- 执行相同验证
- 然后运行
npm publish --access public --provenance --tag <tag>
- Windows wrapper:
scripts\release-registry.bat
node ./scripts/release-registry.mjs --dryRunWindows:
scripts\release-registry.batnode ./scripts/release-registry.mjs --publish --bump patchnode ./scripts/release-registry.mjs --publish --bump minornode ./scripts/release-registry.mjs --publish --version 0.2.0node ./scripts/release-registry.mjs --publish --version 0.2.0-beta.1 --tag beta- 读取当前本地版本。
- 在可用时读取 npm registry latest version。
- 计算下一个版本。
- 更新
package.json和package-lock.json。 - 运行:
npm run typechecknpm run testnpm run doctornpm run simulate:opencodenpm run simulate:compactnpm run pack:releasenpm run smoke:package
- 可选发布到 npm。
注意:本地 publish 路径会请求 npm provenance。部分本地 shell 不会被 npm 识别为支持 provenance 的 provider。如果验证和
pack:release已通过,但 npm 报错Automatic provenance generation not supported for provider: null,可以在同一版本 checkout 下执行npm publish --access public --tag <tag>发布,并在发布记录 / handoff 中说明 provenance fallback。
本地脚本只关注 package preparation 和 npm publish。
本地发布成功后,仍应显式执行 Git 步骤:
git add package.json package-lock.json
git commit -m "Release vX.Y.Z"
git tag vX.Y.Z
git push origin main
git push origin vX.Y.Z
gh release create vX.Y.Z --generate-notes这样可以让本地手动路径保持显式和安全。
这是推荐的 official release path。人正常将功能 / 修复 PR 合并到 main,需要发布时手动运行 release-ci。release-ci 通过后,版本号 bump、tag、npm publish 和 GitHub Release 会自动继续执行。
该流程要求仓库 secret 中配置 CREWBEE_AUTOMATION_TOKEN。该 token 必须允许 push 到 main 并 push tag;默认 GITHUB_TOKEN 不够,因为 GitHub 会抑制由 GITHUB_TOKEN push 触发的后续 workflow。
文件:
.github/workflows/ci.yml
它运行:
npm cinpm testnpm run typechecknpm run buildnpm run simulate:opencodenpm run simulate:compactnpm run doctornpm run pack:release- 通过
scripts/smoke-packed-package.mjs执行 packed package smoke
| Workflow | 触发方式 | 职责 | 输出 |
|---|---|---|---|
.github/workflows/ci.yml |
push 到 main、任意 pull request |
验证普通开发改动 | 必要验证 checks |
.github/workflows/release-ci.yml |
release PR,或手动 workflow_dispatch |
验证 release candidate;手动发布时 gates 通过后 bump version | main 上的 Release vX.Y.Z commit |
.github/workflows/release-tag.yml |
push 到 main |
识别 version-only release commit,并创建不可变 tag | vX.Y.Z tag |
.github/workflows/publish.yml |
push vX.Y.Z tag |
发布 npm package,并创建 GitHub Release | npm release 与 GitHub Release |
普通功能 / 修复 PR 不应该修改 package version。维护者通过手动运行 release-ci 决定何时发布。
文件:
.github/workflows/release-ci.yml
触发方式:
- 目标分支是
main,且来源分支以release/v开头的 PR - 或目标分支是
main,且带有releaselabel 的 PR - 手动
workflow_dispatch,用于验证main、bump package version,并推送 release commit
Release PR 要求:
- PR 必须来自本仓库,而不是 fork
package.json、package-lock.json和 release 分支中的版本号必须一致- 目标版本不能已经存在于 npm
- PR 只能修改
package.json和package-lock.json
Release CI gates:
npm run typechecknpm testnpm run buildnpm run simulate:opencodenpm run simulate:compactnpm run doctornpm run pack:release- packed tarball smoke test
- 将本地 tarball 安装到 OpenCode 用户级 workspace
opencode models --print-logs --log-level DEBUGopencode agent list --print-logs --log-level DEBUG
手动发布行为:
- 在当前
main上运行同一套 release gates - 根据
patch、minor、major或指定版本计算下一版本 - 只更新
package.json和package-lock.json - 直接向
main提交Release vX.Y.Z - 让
release-tag.yml根据该版本号变更创建 release tag
文件:
.github/workflows/release-tag.yml
触发方式:
- push 到
main
行为:
- 如果 push 到
main时修改了package.json或package-lock.json,校验两者包含相同 release versionX.Y.Z - 如果
crewbee@X.Y.Z已经存在于 npm,则拒绝创建 tag - 当
vX.Y.Ztag 不存在时,自动创建并 push 该 tag - 未修改 package version 文件的 push 会被忽略
文件:
.github/workflows/publish.yml
触发方式:
- push tag
vX.Y.Z
- checkout 不可变 release tag。
- 校验 tag、
package.json、package-lock.json版本一致。 - 如果该 npm version 已经发布,跳过
npm publish,继续执行发布后 smoke、latestpromotion、latest 验证和 GitHub Release 创建。这用于同一个 tag 在 post-publish 步骤失败后的续跑。 - 运行完整 release gates:
typecheck、tests、build、simulators、doctor、pack、package smoke、真实 OpenCode loading smoke。 - 如果该 npm version 尚未发布,将已验证 tarball 发布到 staging dist-tag:
- stable release 先发布到
next - prerelease 发布到对应 prerelease tag,例如
beta
- stable release 先发布到
- 从 npm registry 拉回刚发布的 package 并 smoke-test。
- stable release 通过后,将
crewbee@X.Y.Zpromote 到latest。 - stable release promote 后,从 registry 安装并再次运行 OpenCode smoke。
- 创建 GitHub Release 并生成 notes。
- 正常将功能或修复 PR 合并到
main。 - 准备发布时,手动运行
release-ciworkflow。 - 选择
patch、minor、major,或填写指定版本。 release-ci在main上运行完整 release gates。- gates 全部通过后,
release-ci向main提交只修改package.json和package-lock.json的Release vX.Y.Z。 release-tag.yml检测main上的 package version bump 并自动创建vX.Y.Z。publish.yml自动发布该 tag。- 成功后验证:
- npm 存在
crewbee@<version> latest指向该 stable version- tag
v<version>存在 - GitHub Release 存在
- npm 存在
Release commit 刻意保持 version-only。这样既保留发布安全边界,也避免每次功能迭代都手写第二个 PR。
如果某次发布需要指定版本号,不要手改 package.json,也不要在 publish 失败后 bump 新版本。标准入口仍然是手动运行 release-ci,并填写 version 输入。
GitHub UI 操作:
- 打开 Actions ->
release-ci-> Run workflow。 - Branch 选择
main。 version填写目标版本,例如0.2.0或0.2.0-beta.1。bump会在填写version时被忽略,可以保留默认patch。- 运行后等待
release-ci、release-tag、publish完成。
如果让 Agent 执行,直接给出版本号即可,例如:
请发布 CrewBee 0.2.0
Agent 应执行以下流程:
- 确认工作区没有未提交的发布相关改动;不要读取或提交
.crewbee/、.crewbeectxt/、.local/。 - 触发
release-ci的workflow_dispatch,参数为version=<目标版本>,bump=patch。 - 等待
release-ci创建Release v<目标版本>commit。 - 等待
release-tag.yml创建v<目标版本>tag。 - 等待
publish.yml完成 npm publish、latestpromotion、GitHub Release 创建。 - 验证
npm view crewbee version、npm view crewbee dist-tags --json和 GitHub Release。
失败处理规则:
- 如果失败发生在
Publish npm package to staging dist-tag之前,修复 workflow 或环境后重跑同一个 tag / workflow,不增加版本号。 - 如果失败发生在
npm publish成功之后,但latestpromotion、latest 验证或 GitHub Release 创建之前,修复 workflow 或环境后重跑同一个 tag / workflow;publish.yml会检测到该版本已存在并跳过npm publish,继续补全后续步骤。 - 只有已经决定发布一个新的产品版本时,才指定新的版本号。
CrewBee 发布后,目标 OpenCode config 应直接引用 package name:
{
"plugin": ["crewbee"]
}CrewBee 当前写入和校验的 canonical plugin entry 是:
crewbee
而不是 file://.../opencode-plugin.mjs 路径。
这与 oh-my-openagent 的模型一致:config 引用 package name,host / plugin workspace 解析已发布的 npm package。
开发中或 package 尚未发布时,使用:
npm run install:local:user它仍会把本地 tarball 安装进 OpenCode 用户级 workspace,但 config entry 仍保持相同的 canonical package name:
{
"plugin": ["crewbee"]
}使用保留的本地流程:
npm run install:local:user使用本地 release preflight:
node ./scripts/release-registry.mjs --dryRun使用手动 release-ci 流程:
workflow_dispatch release-ci -> Release vX.Y.Z commit -> automatic tag -> automatic publish
这保留了单一人工入口,同时使用不可变 tag 作为 publish 边界。
发布前:
npm run typechecknpm run testnpm run doctornpm run simulate:opencodenpm run simulate:compactnpm run pack:releasenpm run smoke:package
发布后:
- npm 显示
crewbee@<version> - OpenCode config 可以使用
"crewbee" npm run install:registry:user成功npm run doctor健康