Mastra 发布工程Alpha 版本化 PR 就绪检查与合并实战指南【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastraAlpha 版本化 PR 是 Mastra 仓库基于 Changesets 的多包 monorepo进入 alpha 预发布流程的必经关卡它由自动化流程生成统一为所有包提升版本号并回填 CHANGELOG。本文聚焦当该版本化 PR 仍处于打开状态时的完整处理流程——如何用 GitHub CLIgh定位 PR、检查 CI 与合并状态、对版本差异做专项抽查、给出合并建议并安全推进到发布环节。读完本文你将掌握一套可直接执行的 alpha 版本化 PR 就绪检查命令集并理解仓库侧 Changesets 配置与发布工作流对它的约束。本文基于 .claude/skills/mastra-smoke-test/references/alpha-versioning-pr.md 展开并辅以仓库内脚本、配置与工作流源码佐证。该文档是 Mastra smoke-test skill 的alpha 发布分支点参考之一当版本化 PR 仍打开时走本文档合并后则切换到 alpha-publish.md。一、Alpha 版本化 PR 在发布流程中的位置在开始任何 alpha 冒烟测试之前必须先确认版本化 PR 的当前状态。顶层 SKILL.md 中Alpha release branch point一节给出了标准分支逻辑优先使用 Changesets 标准发布分支定位 PRgh pr view changeset-release/main \ --json number,title,state,url,headRefName,baseRefName,isDraft,mergeable,reviewDecision,updatedAt,mergedAt,mergeCommit预期的 PR 形态是title: chore: version packages (alpha) head: changeset-release/main base: main若按分支名找不到回退为按标题搜索打开/已合并的 PRgh pr list --state open --search version packages alpha in:title --limit 20 gh pr list --state merged --search version packages alpha in:title --limit 20分支判断结果决定后续路径PR打开→ 阅读本文档alpha 版本化 PR 就绪检查PR已合并→ 阅读 alpha-publish.md验证自动发布不存在→ 报告该情况等待定时触发的 alpha 版本化流程或用户指示不要自行创建冒烟测试项目。注意alpha 冒烟项目必须在自动发布工作流完成、目标包可安装之后才能创建SKILL.md 中同样强调此顺序约束。二、将 PR 在浏览器中打开供用户审查当用户需要亲自审阅该版本化 PR 时推荐使用 GitHub CLI 而非浏览器自动化gh pr view pr-number --web原因在文档中写得很明确gh pr view --web会使用用户正常登录的浏览器/会话打开页面避免自动化浏览器带来的登录态、会话隔离等问题。这一步适合在用户明确需要时主动提出是否需要帮你打开这个版本化 PR。三、就绪检查状态、可合并性与 CI拿到 PR 编号后第一步是检查 PR 的整体就绪状态gh pr view pr-number --json number,title,isDraft,mergeable,reviewDecision,url gh pr checks pr-number --watchfalse重点关注四个维度字段含义就绪判据isDraft是否草稿必须是false草稿不可合并mergeable是否可合并无冲突期望为可合并状态reviewDecision评审结论结合仓库分支保护规则判断是否需要额外批准gh pr checks各检查项状态全部通过绿色若检查仍在运行使用--watch阻塞等待并设置轮询间隔gh pr checks pr-number --watch --interval 30--interval 30表示每 30 秒重新查询一次检查状态适用于 CI 耗时较长的 monorepo 全量构建。四、版本差异抽查Spot Check这是合并前的核心动作文档强调在告诉用户可以合并之前Agent 必须亲自抽查版本化 diff同时也要建议用户自己再抽查一遍。优先使用仓库内提供的辅助脚本.claude/skills/mastra-smoke-test/scripts/check-versioning-pr.sh pr-number --workspace $SMOKE_DIR脚本参数说明pr-number必填版本化 PR 编号--workspace dir可选工作目录用于存放日志与摘要产物默认$HOME/mastra-smoke-tests/$(date %F)。如果不想用脚本也可以手动检查gh pr diff pr-number --name-only gh pr view pr-number --json files --jq .files[].path \ | rg (package\.json|CHANGELOG\.md|\.changeset/) gh pr diff pr-number第一、二条命令用于确认改动文件集合是否干净——一个正常的 alpha 版本化 PR 只应触碰package.json、CHANGELOG.md与.changeset/pre.json第三条命令输出完整 diff 供逐行核对版本号。4.1 脚本在背后做了什么源码级拆解阅读 check-versioning-pr.sh 源码约 200 行 Bash 内嵌 Python可以看到它把人工抽查变成了结构化审计依赖前置检查require_cmd gh与require_cmd python3缺少任一依赖立即报错退出第 18-23 行收集产物将gh pr diff pr-number --name-only与完整gh pr diff pr-number分别写入$WORKSPACE/logs/pr-编号-files.txt和pr-编号-full.diff并剥离 ANSI 颜色转义第 74-88 行解析版本变化用正则匹配diff --git a/...package.json定位每个包的版本变更提取- version: x.y.z旧与 version: x.y.z新生成pr-编号-version-summary.tsv第 95-115 行解析 CHANGELOG 标题匹配## version形式的新增版本标题第 116-121 行识别非发布文件凡不属于.changeset/pre.json、根package.json、根CHANGELOG.md及各包package.json/CHANGELOG.md的变更都会被列入警告第 122-132 行三类高风险信号第 134-150 行major_bumps新版本主版本号大于旧版本即意外的主版本跃升non_alpha_new_versions新版本号中不含-alpha.前缀stable_to_alpha从无预发布后缀的稳定版本直接变为-alpha.版本。脚本输出格式为带数量统计的摘要例如Changed files: 42 Package version changes: 40 Changelog version headings: 40 Non release/version files: 0 Major version bumps: 0 New versions without -alpha: 0 Stable - alpha transitions: 2最后一行Summary:会在无任何警告时给出no major bumps, non-alpha new versions, or non-release files detected的结论否则提示逐条审阅警告。4.2 人工抽查必须覆盖的检查点无论用脚本还是手动方式以下检查点都必须逐一确认这也是合并前向用户汇报的内容包版本变化看起来是有意为之——版本号提升幅度与 changeset 声明的变更级别一致没有非预期的 major 版本跃升或 breaking-change 发布——若 alpha 流程中突然出现1.x → 2.x必须停下来向用户确认CHANGELOG 条目与本次 alpha 预期的 PR 集合吻合——对照 release-scope-discovery.md 中收集的合并 PR 列表检查每条 changelog 是否对应实际合入的变更CI 全绿且 PR 不是 draft。完成抽查后先向用户总结抽查发现包括任何警告项再让用户决定是否批准合并。五、仓库侧的 Changesets 配置如何支撑这次检查版本化 PR 的形态与检查规则并非凭空而来而是由仓库根目录的 Changesets 配置决定的。.changeset/pre.json 表明仓库当前正处于alpha 预发布模式{ mode: pre, tag: alpha, initialVersions: { ...: ... }, changesets: [] }mode: pretag: alpha意味着所有后续版本号都会带上-alpha.N预发布后缀——这正是脚本中新版本必须包含-alpha.这一判据的出处changesets: []为空说明上一次版本化 PR 已消费掉全部待发布 changesetinitialVersions记录进入 pre 模式时各包的基线版本例如mastra/core为1.65.0、mastra为1.28.0可供人工比对版本号是否有异常跃升。.changeset/config.json 则定义了版本化行为的边界fixed声明了两组固定版本包[mastra/core, mastra/server, mastra/deployer, mastra/deployer-cloud]与[mastra, create-mastra, internal/playground]——组内任一包升级整组版本号必须一起提升这是版本化 PR 中多个包同步改版本的来源baseBranch: main说明版本化 PR 的目标分支是main对应 SKILL.md 中base: main的预期ignore列表通过取反规则只放行mastra、create-mastra、mastracode、mastra/*等对外发布包其余内部工具包不参与版本化。六、合并指导Agent 的职责边界文档对合并环节有非常明确的职责划分用户必须亲自 review、approve 并 merge 版本化 PR。Agent 可以检查就绪状态并提供建议但在用户明确指示之前不得合并。实操建议若 PR 已就绪告诉用户去 GitHub 上批准并合并或者询问用户是否希望由你执行合并若分支保护规则拒绝了合并例如必须通过指定人数 review立即停止并请求所需的批准不要绕过分支保护合并动作本身涉及写权限与发布链路的触发属于必须由人类决策的环节。这一约束的背后是实际的发布连锁反应查看 .github/workflows/npm-publish.yml 可知Publish to npm 工作流在push到main且提交信息以chore: version packages开头、作者为dane-ai-mastra[bot]时会自动触发prerelease任务第 29-45 行该任务第一步就校验.changeset/pre.json必须存在且处于modepre, tagalpha状态第 72-88 行随后以--tag alpha执行全仓发布第 104-105 行。因此合并版本化 PR ≈ 触发自动 alpha 发布误合并的代价直接落到 npm 包上这正是需要人类把关的原因。七、合并完成后的下一步版本化 PR 合并后立即转入发布验证与冒烟测试阶段阅读 alpha-publish.md通过gh run list --workflow Publish to npm --branch main --limit 5确认自动发布已触发检查新 run 中prerelease任务执行、snapshot/stable/enter_prerelease跳过用npm view mastra/corealpha version、npm view mastraalpha version、npm view create-mastraalpha version确认 alpha 包已可安装。之后继续 release-scope-discovery.md 确定本次发布范围再按 SKILL.md 的强制检查清单执行全套本地冒烟测试。完整的分支导航也可以参考 release-smoke.md 这份索引。八、小结Alpha 版本化 PR 的就绪检查本质上是对自动生成的版本变更做一次结构化的人工审计先用gh pr view/gh pr checks确认状态与 CI再用辅助脚本或手动命令核实版本号、CHANGELOG 与改动文件集合是否干净最后把发现汇报给用户并交由用户决策合并。借助仓库中的 check-versioning-pr.sh 脚本、.changeset/pre.json 的 alpha 预发布标记与 .github/workflows/npm-publish.yml 的自动发布触发条件这套流程能够把版本化 PR 是否可合并从拍脑袋变成可复现、可审计的判断为后续 alpha 发布冒烟测试打下可靠基础。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考