Astro 仓库 main→next 分支合并工作流：冲突解决、CI 修复与 Changeset 清理的 Agent 化实践

Astro 仓库 main→next 分支合并工作流冲突解决、CI 修复与 Changeset 清理的 Agent 化实践【免费下载链接】astroThe web framework for content-driven websites. ⭐️ Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/as/astro本文以 Astro monorepo 中定义的mergeAgent 技能.agents/skills/merge/SKILL.md为主体完整拆解将main稳定分支合并回next预发布分支的三个标准阶段解决 Git 冲突、清理过期的 changeset、修复合并后的 CI 失败。读完后你将掌握一套可直接复用的大仓库分支合并流程如何按文件类型制定冲突裁决规则、如何避免预发布版本号回退冲突以及如何在绝不重新安装依赖的前提下高效修复构建与测试失败。一、总体设计一个技能三个子技能一个编排器merge 技能的主文件本身是一个轻量级的入口文件其 YAML frontmatter 声明了技能名称与触发时机--- name: merge description: Handle main-to-next merge tasks including conflict resolution, changeset cleanup, and CI fix-ups. Use when merging main into next. ---它将完整的合并流程拆分为三个子技能由外部编排器orchestrator通过step参数决定当前执行哪一步resolve-conflicts.md —— 解决git merge origin/main产生的 Git 冲突fix-ci.md —— 修复构建错误、类型错误和测试失败clean-changesets.md —— 删除已在main上发布过的陈旧 changeset 文件。这个拆分本身体现了一个重要工程决策三个阶段的责任边界被显式切开。每个子技能都声明了相同的 SCOPE 约束——Do not spawn tasks/sub-agents不得再派生子任务并严格规定了哪些动作由自己完成、哪些动作留给编排器。例如冲突解决阶段明确依赖尚未安装不要运行pnpm install编排器会在你完成后执行而 CI 修复阶段则相反依赖已经装好绝对不要再跑pnpm install。把 install、commit、build 等重活统一收归编排器可以避免多个子任务各自为政地重装依赖树、破坏锁文件。二、阶段一解决合并冲突resolve-conflicts这一阶段的前提状态Prerequisites在 resolve-conflicts.md 中被逐条列出已知分支名如ci/merge-main-to-next、已知是否存在冲突hasConflicts、工作目录位于仓库根且检出在合并分支上、git merge origin/main已执行但尚未提交冲突标记仍在工作区中、依赖未安装。2.1 找出所有冲突文件第一步是用grep按文件类型批量扫描冲突标记而不是依赖git status逐个查看# List all files with conflict markers grep -rl . --include*.ts --include*.js --include*.mjs \ --include*.cjs --include*.md --include*.astro \ --include*.json --include*.yaml --include*.yml | grep -v node_modules | sort这个命令覆盖了 Astro monorepo 中的全部关键文件形态TypeScript 源码、Astro 组件、JSON 配置、YAML 工作区配置。之所以按扩展名枚举而非全量扫描是因为在含上千文件的 monorepo 中如packages/astro/test/fixtures下有大量测试 fixture限定类型能显著降低噪音。2.2 按文件类型制定裁决规则这是整个技能中最核心的部分不同文件类型采用不同的裁决策略而不是无脑选 ours/theirs。package.json文件规则见 resolve-conflicts.md 第 28–33 行字段规则version永远保留next的预发布版本号如6.0.0-beta.4绝不用main的稳定版本号依赖共享依赖保留next的版本若main新增了next没有的依赖则纳入若main把某个依赖替换成了另一个文档给出的例子是get-tsconfig→tsconfck以next源码实际 import 的那个为准scripts两侧合并保留next的脚本并加入main的新脚本其他字段默认偏好next除非main侧是明显的 bug 修复pnpm-lock.yaml明确规定不要手动解析锁文件直接丢弃冲突、交给编排器用pnpm install --no-frozen-lockfile重新生成git checkout --theirs pnpm-lock.yaml 2/dev/null || true这是务实的选择——手工合并数千行的 lockfile 既慢又极易出错而重新生成是可复现的确定性操作。源码.ts/.js/.mjs/.cjs/.astromain上的 bug 修复必须带到next必要时适配next的 APInext上发生的 API 变更保留next版本把main侧代码适配过来拿不准时默认选next——因为它是面向未来的分支。Markdown 与配置文件.changeset/*.md留给 clean-changesets 阶段处理冲突时先两侧都接受其余.md文件偏好next。2.3 收尾暂存与验证每解决一个文件立即git add resolved-file暂存然后再次全量扫描确认没有残留冲突标记grep -r \|$\| . --include*.ts --include*.js \ --include*.mjs --include*.cjs --include*.md --include*.astro \ --include*.json --include*.yaml --include*.yml | grep -v node_modules最后一条铁律不要 commit不要 install——提交、安装、构建全部交给编排器。技能的输出契约也很清晰返回已解决冲突的文件列表。三、阶段二清理过期 Changesetsclean-changesets这一阶段解决的问题非常具体其背景说明clean-changesets.md 第 12–14 行值得逐字理解当main合并进next时那些已经在main上被某次发布消费掉的 changeset 文件.changeset/*.md如果next分支在那次发布之前就分叉了它们仍会作为新文件出现在next上。这些陈旧 changeset 会导致next的预发布版本号包含已经以稳定版发布过的版本 bump从而产生版本冲突——例如在astrojs/sitemap3.7.0之后又发布了astrojs/sitemap3.6.1-beta.3这种版本号倒退的预发布包。这解释了 Astro 仓库为什么要采用 changesets 预发布模式结合 pnpm-workspace.yaml 与.changeset/目录。仓库中现有的 config.json 印证了发布配置baseBranch: origin/main决定了 changeset 以哪个分支为基准比对changelog使用changesets/changelog-github生成变更日志。而 great-moons-shine.md 这样的真实 changeset 文件则展示了标准格式——frontmatter 中声明包名与 bump 类型astro: patch正文是一句话的变更说明。清理步骤找出候选用git diff --diff-filterA列出相对origin/next新增的 changeset 文件# List changeset .md files that are new (not in next already) git diff --name-only --diff-filterA origin/next -- .changeset/逐个核查读取文件内容看它 bump 哪些包再对照origin/main上各包的package.json当前版本号与 changelog——只有当该 changeset 描述的 bump 已经发布时才判定为 stale陈旧。检查pre.json若.changeset/pre.json存在它记录预发布模式状态其changesets数组列出当前预发布待发布的所有 changeset 标识确保被删文件的标识也从数组中移除。删除git rm .changeset/stale-file.md。验证确认剩余的 changeset 文件格式合法frontmatter 包含包名与 bump 类型。不提交、不 install——同样留给编排器。保守原则文档用一整节Important Notes划定了禁止事项这些边界对防止 Agent过度清理至关重要不得删除next专属的 changeset描述主版本变更或next在研新特性的不得删除 .changeset/config.json不得删除.changeset/pre.json预发布模式依赖它;拿不准时宁可保留——err on the side of keeping it. A human reviewer can remove it later把误删的代价转移给低成本的人工复查。四、阶段三修复 CI 失败fix-ci此阶段的前提是冲突已解决并提交、锁文件已重新生成、pnpm install已执行、CI 日志已由编排器预先抓取进ciLogs参数。fix-ci.md 的核心是一套修复并推送fix and push的迭代循环修完推到 PRCI 自动重跑如果还有新失败就用更新后的日志再跑一轮。4.1 四条关键规则Critical Rules这四条规则fix-ci.md 第 15–23 行是整个技能最具实操价值的部分绝不运行pnpm install。依赖已正确安装锁文件是合并动作中带着全部已解决冲突生成的再次安装尤其是--no-frozen-lockfile会重新解析整棵依赖树、破坏传递依赖。文档还点破了一个常见误区如果测试因缺模块而失败那是源码问题不是依赖问题——应该修 import而不是装包。给调查设时间盒单个失败分析超过 5 分钟还没有动手尝试修复时停止调查按当前最佳猜测直接改、直接跑用跑一遍看结果代替从第一性原理追完整条调用链。先 diff后读码排查失败时先看合并改了什么git diff origin/next...HEAD -- relevant-files而不是通读源码——diff 直接展示了两分支的差异而合并后的失败几乎都源于这些差异。批量执行 bash 命令把相关的ls/grep/cat合并成一次调用减少往返。4.2 构建优先先修 build 再看测试CI 的第一步是构建构建错误会阻塞一切所以本地复现顺序也是pnpm build合并后的常见构建错误被归纳为三类及对应修法类型错误——两分支间 API 变更某分支改了类型签名或新增必填字段另一分支代码对不上按当前分支状态适配代码导入错误——文件被移动/重命名或导出被删除更新 import 路径或适配新 API重复声明——两分支都加了相似代码删掉重复项保留next版本。用 diff 定位变化修复后先构建受影响的包确认再全量构建git diff origin/next...HEAD -- path-to-failing-file pnpm -C packages/affected-package build pnpm build这里的pnpm -C dir command形式与仓库根 AGENTS.md Monorepo Structure 一节中的工作区约定一致所有包位于packages/包内命令一律通过-C定位且对源码的修改需要pnpm build重新构建后才生效node_modules中的构建产物映射回packages/下的 TS 源码。4.3 测试失败的归因与最小修复构建通过后从ciLogs参数中提取哪些测试文件失败、具体哪些用例失败、错误信息与断言 diff。注意沙箱内ghCLI 不可用所有 CI 信息都来自预取的ciLogs。对每个失败先跑 diff 归因文档归纳了四类常见成因快照/输出不匹配——next用了新编译器或有 API 变更期望的 HTML 输出变了更新期望值以匹配新行为导入/模块错误——main代码引用了next上已变更的模块或导出测试中的类型错误——跨分支 API 变更导致的 TS 编译失败配置不匹配——测试 fixture 使用了next上已变更的配置项更新 fixture。修复原则是最小化只修 CI 报的失败不重构无关代码不改测试意图只把期望值适配到当前分支状态。同时明确列出了不修清单合并在next上就已经失败的测试——不确定时用git log origin/next -- test-file查证Smoke 测试允许失败astro check失败允许存在。这一允许失败清单与仓库根 package.json 中的脚本结构相互印证test:smoke本质是turbo run build构建全部示例项目而astro check属于语言工具链的独立检查项二者波动性与合并正确性无关。4.4 本地验证只跑定向测试修完后只跑被修的具体测试而非全量套件pnpm -C package-directory exec astro-scripts test test/specific-test.test.js两个细节容易被忽视一是不要把输出管道接grep否则会吞掉真正的通过/失败结果二是这只是快速 sanity check完整验证交给 push 之后的 CI。若修改了packages/下的源码而非仅测试文件需重新执行第 4.2 节的定向构建再重跑对应测试。技能输出契约是否修复了全部已识别的 CI 失败构建 测试、修改过的文件列表、以及无法自动修复、需要更深层架构理解的残留失败清单。五、技能的可验证性evals 驱动的回归测试与大量写完即弃的 Agent 提示词不同这个 merge 技能自带结构化评测用例 evals/evals.json为三个阶段各定义了一个**输出型干跑output-only dry run**场景给定合成的人为冲突片段/changeset 快照/CI 日志要求 Agent 不触碰真实 checkout、不执行任何命令仅返回将会做的解析结果与命令序列并用assertions数组逐条校验行为边界。以 resolve-conflicts 的用例为例其断言精确到解析后的package.json必须保留6.0.0-beta.4预发布版本、vite 7.1.0、tsconfck纳入main新增的kleur与test:smoke脚本但不引入get-tsconfig源码解析必须调用loadTsconfig(path, { cache: false })next的新 API、保留main侧的 null 守卫、读取result.tsconfig而非main分支已过时的result.config——恰好覆盖了第 2.2 节API 变更保留 next、bug 修复保留 main两条规则的组合命令序列用git checkout --theirs处理 lockfile、暂存并扫描冲突标记且不得出现pnpm install或git commit。clean-changesets 与 fix-ci 的用例同样体现了边界纪律前者只删证据确凿已发布的 changeset、保留next专属与状态不明者后者只更新过期的 redirect 断言、明确将 smoke 与 astro-check 失败列入有意不修。这些 eval 由仓库根 package.json 的脚本驱动pnpm eval:skills # vitest run --config vitest.skills.config.ts pnpm eval:skills:validate # vitest list --config vitest.skills.config.ts配套的加载器在 .agents/evals/load-evals.ts 与 skills.eval.ts说明该仓库对技能行为本身做单元/回归测试。这是把 Agent 工作流工程化的关键一步提示词会改、模型会换只有可执行的断言能守住行为底线。六、总结从文档中可提炼的合并方法论把三个子技能合起来看这套 main→next 合并流程的可复用要点是阶段切分 单一职责冲突解决、依赖再生成、构建、提交各归其位子技能之间通过明确的前置条件Prerequisites与后置约束不 commit / 不 install / 绝不 install交接按文件类型裁决而非全局策略版本号、锁文件、源码、文档各有专属规则拿不准选 next只适用于源码层锁文件永远重生成不手解CI 修复先 diff 后读码、最小化改动、给调查设时间盒并把 smoke/astro check等允许性失败显式豁免版本发布安全靠证据链只有版本号 changelog 双重印证已发布的 changeset 才被删除其余一律保留交人工复查技能行为本身有测试以 dry-run 合成场景 断言数组的形式纳入 vitest 回归。对维护双分支稳定main 前瞻next预发布的大型 monorepo 而言这套流程把最易出错的合并环节变成了可编排、可断言、可回归验证的自动化流水线。【免费下载链接】astroThe web framework for content-driven websites. ⭐️ Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/as/astro创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考