用途：准备 Buildkite Agent 的发布流程，适用于 v4（从 main 分支发布，当前为预发布版本）和 v3（从 v3 分支发布）两条发布线。开始前需先让用户选择发布线，该选择决定后续所有操作的基础分支：v4 用 main，v3 用 v3。
主要步骤与能力： 一、确认当前提交与发布分支保持最新（v4 对应 origin/main，v3 对应 origin/v3）。 二、确定新版本号：先用 gh release list --repo buildkite/agent --limit 20 查找所选发布线的最新版本，注意单独使用 gh release view 只返回最新稳定版，会隐藏 v4 预发布版。v4 处于 beta 阶段时通常递增为下一个 beta（如 4.0.0-beta.14 到 4.0.0-beta.15）；v3 则需询问是次要版本还是补丁版本。 三、编辑 version/VERSION，填入不带 v 前缀的裸语义化版本号（如 3.136.4 或 4.0.0-beta.15）。 四、预览自动生成的发布说明，以便在 PR 描述中审阅：将 target_commitish 设为发布分支，通过 gh api -X POST repos/buildkite/agent/releases/generate-notes 生成说明并写入 tmp/release-notes.md。这是只读 API 调用，不会创建发布或标签。对 v4 beta，需显式传入 previous_tag_name（如 v4.0.0-beta.14），因为 GitHub 默认比较的是上一个稳定版（会与最新 v3.x 对比，对 v4 beta 不合适）。检查生成内容，若 PR 分类错误（如因缺少标签落入内部类别），修正标签后重新运行。 五、创建发布 PR：基于发布分支新建分支，提交 version/VERSION 变更并推送，用 gh pr create 向发布分支发起 PR（v4 用 --base main，v3 用 --base v3）。标题遵循惯例如 release: v3.136.4；正文使用上一步的 tmp/release-notes.md；必须添加 release 标签，以便 PR-labels 工作流通过，并让该发布 PR 被排除在自身自动生成的说明之外。示例命令：gh pr create --base v3 --title "release: v3.136.4" --body-file tmp/release-notes.md --label release。
限制：PR 正文仅供人工审阅，实际发布说明会在发布流水线运行 github-release.sh 时通过 gh release create --generate-notes 重新生成，因此会反映 PR 创建到发布之间所做的标签修正；无需手动编辑 GitHub 发布，但用户可能希望在发布后检查自动生成的说明。