| name | publish-version |
| description | 按开源项目标准发布 AstrCode 新版本。用户说“发版”“发布”“release”“publish”“发 patch/minor/major”“发布 0.x.y”“打 tag”“触发 release workflow”时使用；负责 SemVer 选择、发布前检查、CI gate、GitHub Actions 发版、精确版本 release PR、tag/发布跟踪与失败排查。 |
Publish Version
发布原则
按开源项目的默认标准执行：
- 从受保护的
main 发布，不从脏工作区、未推送提交或临时分支发布。
- 所有代码变更先经 PR 合入；发版动作只做版本 bump、tag、构建和发布。
- 优先用 GitHub Actions
Release workflow；不要本地手写改版本号。
- 推送 tag、触发 release workflow、npm publish 都属于发布动作，执行前必须获得用户明确确认。
- 失败后先看 CI 日志并修正根因；不要直接重跑掩盖问题。
分流
- 用户要求
patch / minor / major：走 workflow dispatch 标准路径。
- 用户只说“发版”：建议
patch，先确认 bump 类型。
- 用户指定精确版本号：走 release PR 路径；PR 合并后再 tag 或让用户改用 bump workflow。
- 用户说“检查能不能发版”：只做 preflight，不触发 workflow，不创建 tag。
- 只有用户明确要求维护者应急发版，才允许本地直接 tag push。
SemVer 选择
根据已合入 main 的变化选择版本：
| bump | 使用场景 |
|---|
patch | bug fix、文档、CI、内部重构、无兼容性影响 |
minor | 新功能、向后兼容的新 API/CLI/配置能力 |
major | 破坏兼容的 CLI、配置、协议、插件 SDK、持久化格式或 npm 分发变化 |
如果 commit 范围中出现 breaking change、协议/SDK/持久化迁移，默认提高到 major，除非用户明确决定不这样做。
Preflight
先收集状态：
git fetch origin main --tags
git status --short
git branch --show-current
git rev-parse HEAD
git rev-parse origin/main
git tag --sort=-v:refname | head -5
gh run list --branch main --limit 10
必须满足：
git status --short 为空。- 本地
main 与 origin/main 一致；否则先 fast-forward 或停止。
- 最近一次目标分支 CI 通过，或用户明确接受等待/风险。
- 没有同名
v<version> tag。
- 不覆盖、不删除、不 force-push 已发布 tag；需要修复坏版本时发布新 patch。
检查 release notes 输入：
LAST_TAG=$(git tag --sort=-v:refname | grep '^v' | head -1)
git log "${LAST_TAG}..origin/main" --pretty=format:'%s (%h)' --no-merges
确认重要变更会进入 release notes；若发现 breaking change 或迁移说明缺失，先补文档或 release note 内容。
本地最小检查：
cargo fmt --all -- --check
python3 scripts/check-deps.py
cargo check --workspace --all-features --exclude astrcode-desktop
bash -n scripts/bump-release-version.sh scripts/prepare-npm-packages.sh
git diff --check
完整发布前最好由 CI 覆盖：clippy、tests、audit/deny、frontend lint/typecheck/format/contract/build、多平台 release binary build。
标准路径：workflow dispatch
适合 patch / minor / major。不要在本地改版本号。
确认用户同意发布后执行：
gh workflow run release.yml --ref main -f bump=<patch|minor|major>
跟踪：
gh run list --workflow release.yml --limit 3
gh run watch <run-id> --exit-status
失败时：
gh run view <run-id> --log-failed
workflow 会计算下一个版本，运行 scripts/bump-release-version.sh，提交版本 bump，创建 v<version> tag，并发布 GitHub Release / npm 包。
精确版本：release PR 路径
适合用户要求“发布 0.x.y”。不要直接在本地 main 打 tag。
- 校验版本号和 tag：
VERSION=<version>
printf '%s' "$VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$'
! git rev-parse "v${VERSION}" >/dev/null 2>&1
- 创建 release 分支并同步版本：
git switch main
git pull --ff-only origin main
git switch -c release/v${VERSION}
bash scripts/bump-release-version.sh "$VERSION"
脚本负责同步 Cargo.toml、lockfile、Tauri、frontend、npm 主包与 s5r fixture 的版本。
- 验证：
cargo fmt --all -- --check
python3 scripts/check-deps.py
cargo check --workspace --all-features --exclude astrcode-desktop
bash -n scripts/bump-release-version.sh scripts/prepare-npm-packages.sh
git diff --check
- 提交并开 PR：
git add -A
git commit -m "chore: bump version to ${VERSION}"
git push -u origin release/v${VERSION}
gh pr create --base main --head release/v${VERSION} \
--title "chore: bump version to ${VERSION}" \
--body "Release version metadata sync for v${VERSION}."
- 等 PR CI 通过并合并后，再从最新
main 创建 tag：
git switch main
git pull --ff-only origin main
grep -q "^version = \"${VERSION}\"" Cargo.toml
grep -q "\"version\": \"${VERSION}\"" src-tauri/tauri.conf.json
grep -q "\"version\": \"${VERSION}\"" frontend/package.json
grep -q "\"version\": \"${VERSION}\"" npm/astrcode/package.json
git tag -a "v${VERSION}" -m "v${VERSION}"
推送 tag 前再次确认用户同意：
git push origin "v${VERSION}"
tag push 触发 release.yml 的 tag 路径；该路径只校验版本一致性，不自动 bump。
应急路径：直接 tag
只有维护者明确要求绕过 PR 时使用。仍必须保持工作区干净、CI 通过、版本文件已同步，并在最终回复中说明绕过了 PR gate。
git switch main
git pull --ff-only origin main
bash scripts/bump-release-version.sh "$VERSION"
cargo fmt --all -- --check
python3 scripts/check-deps.py
cargo check --workspace --all-features --exclude astrcode-desktop
git diff --check
git add -A
git commit -m "chore: bump version to ${VERSION}"
git tag -a "v${VERSION}" -m "v${VERSION}"
git push origin HEAD:main
git push origin "v${VERSION}"
发布后报告
回复用户时包含：
- 版本号和 bump 类型。
- 使用路径：workflow dispatch、release PR + tag，或应急直接 tag。
- GitHub Actions run URL 或 run id。
- 安装命令：
npm install -g @whatevertogo/astrcode@<version>
项目特定易错点
- 不要把
eval-tasks/fixtures/ 里的 fixture 版本随发版 bump。
src-tauri/Cargo.toml 使用 workspace 版本；桌面展示版本在 src-tauri/tauri.conf.json。- npm 主包和平台包 license 必须是
AGPL-3.0-only。
- Release notes 安装命令必须是
@whatevertogo/astrcode，不是裸 astrcode。
- Weekly Release 只在上一个
v* tag 后有新提交时发布，不发布空版本。
