
Mastra 仓库实战用 opencode gh CLI 自动修复 PR 分支的 Lint 与格式问题【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本文围绕 Mastra 仓库中面向 AI Agent 的 opencode 命令gh-fix-lint.opencode/command/gh-fix-lint.md展开完整讲解「拿到一个 GitHub PR 分支 → 检出 → 自动修复 lint 与格式 → 推送回贡献者 fork」的七步自动化流程。读完本文你将掌握如何使用gh pr view提取 PR 元数据、用git fetch pull/n/head检出 PR 分支、用 Mastra 仓库真实的oxfmt/oxlint/prettier脚本链自动修码以及如何在只暂存已跟踪文件的前提下安全地提交并推送到贡献者仓库从而把「帮 PR 修 lint」这一维护者日常操作固化为可复用、可交给 Agent 执行的命令。一、背景opencode 命令与 PR 维护自动化MastraTypeScript 实现的 AI 应用与 Agent 框架是一个大型 pnpm monorepo其根目录 package.json 中声明了大量 lint、format、test、build 脚本。仓库维护者在处理社区贡献的 Pull Request 时经常遇到「PR 分支 CI 挂在了 lint/format 检查上」的情况——改动逻辑没问题但格式不符合 oxfmt/oxlint/prettier 要求。为此仓库在 .opencode/command/ 目录下维护了一组面向 opencode AI Agent 的「slash command」定义把高频 PR 操作流程化为 Agent 可逐步执行的指令序列gh-fix-lint.md拉取 PR 分支并自动修复 lint 与格式问题本文主角gh-fix-ci.md诊断并修复 PR 关联的 GitHub Actions CI 失败gh-new-pr.md用ghCLI 在当前分支上创建新 PRpr.md先通过 changesets CLI 生成变更集再开 PR 的完整流程。这些命令配合 .opencode/mastra.json 中的模型配置google/gemini-2.5-flash、scope: thread一起使用维护者只需对 Agent 说一句「跑一下 gh-fix-lintPR 号是 11452」Agent 就会按文档中的步骤顺序执行 GitHub CLI 与 git 命令。gh-fix-lint命令的核心输入只有一个$PR参数且支持两种形式形式示例说明PR 编号11452直接传数字gh会基于当前仓库解析完整 PR URLhttps://github.com/mastra-ai/mastra/pull/11452传 URL 时命令第一步先从中提取 PR 编号无论哪种形式后续的gh pr view都会返回结构化的 JSON供 Agent 提取分支与仓库信息。二、Step 1提取 PR 元数据命令的第一步是用 GitHub CLI 获取 PR 的完整信息为后续检出分支和推送做准备gh pr view $PR --json headRefName,headRepository,headRepositoryOwner,number,url--json参数要求gh输出机器可读的 JSON而不是面向人类的渲染文本这是 Agent 能稳定解析的关键。从返回结果中需要提取三个字段headRefName贡献者的分支名后续git checkout和git push都会用到headRepositoryOwner.loginfork 仓库的拥有者。这一步很关键——推送的目标不是当前仓库而是贡献者的 forkheadRepository.namefork 仓库名与 owner 组合后构成推送 URL。如果$PR传入的是完整 URLAgent 需要先从中剥离出 PR 编号再执行gh pr view。这条命令是整条工作流的信息基石分支名、owner、仓库名全部来自这里后面的 fetch、checkout、push 都不能脱离这三个字段。三、Step 2确认工作区干净在切换分支之前必须先确保本地没有未提交的改动否则git checkout可能报错或把改动带到其他分支git status --porcelain--porcelain即机器可读的短格式是专门为脚本设计的输出模式每一行对应一个文件条目未修改时不产生任何输出。Agent 判断逻辑很简单输出为空 → 工作区干净可以继续输出非空 → 存在未提交改动不要擅自处理而是向用户说明情况并询问如何处理stash 暂存、commit 提交、还是中止流程。这是命令中少有的「停下来征求用户意见」的检查点目的是避免 Agent 在不知情的情况下把维护者本地的临时文件混入 PR 分支的提交中。四、Step 3Fetch 并检出 PR 分支使用 GitHub 提供的pull/PR 编号/head引用把 PR 分支抓取到本地并检出git fetch origin pull/$PR/head:branch-name-from-step-1 git checkout branch-name-from-step-1git fetch origin pull/n/head:本地分支名会把远程 PR 的 head 提交映射到一个本地分支名来自 Step 1 的headRefName这样后续的操作对象就是一个普通本地分支所有 git 命令都能正常工作。命令同时给出了失败兜底如果检出失败典型场景是同名分支已经存在则改用先检出再拉取的方式并强制快进合并以保证与远端一致git checkout branch-name-from-step-1 git pull origin branch-name-from-step-1 --ff-only--ff-only的作用是只允许快进合并如果本地分支已经被修改而无法快进命令会直接失败而不是创建合并提交从而避免污染 PR 分支的提交历史。这一兜底路径保证了「无论分支是否已存在于本地都能拿到 PR 的最新代码」。五、Step 4运行 lint 与格式自动修复这是整条命令的核心步骤在 PR 分支上依次执行仓库自带的两个修复命令pnpm oxfmt:format pnpm format这两条命令在 Mastra 仓库根目录 package.json 中有真实定义构成了「格式修复 → 风格修复」的两段式管线// package.json节选 format: pnpm format:eslint pnpm format:oxfmt, format:eslint: pnpm turbo --filter \!./examples/**/*\ --filter \!./docs/**/*\ --filter \!internal/playground\ lint:fix, format:oxfmt: pnpm oxfmt:format, oxfmt:format: oxfmt . !docs/**/* !examples/**/* !explorations/**/* !observability/_examples/**/*逐条拆解这条修复链pnpm oxfmt:format运行oxfmt对仓库全部源码做格式规范化缩进、引号、换行、行宽等并通过!docs/**/*、!examples/**/*、!explorations/**/*、!observability/_examples/**/*四个排除规则跳过文档、示例、探索性代码与可观测性示例目录避免误改这些受保护区域。pnpm format等价于format:eslint format:oxfmt。前半段format:eslint通过pnpm turbo对各子包批量执行lint:fix即 oxlint 的自动修复模式可安全修复 import 排序、类型导入风格、未使用变量等静态检查问题排除规则与 lint 脚本保持一致后半段format:oxfmt再次兜底格式。与修复链路配套的是仓库中对应的**只检查不修改**脚本用于验证修复结果// package.json节选 lint: pnpm turbo --filter \!./examples/**/*\ --filter \!./docs/**/*\ --filter \!./explorations/**/*\ --filter \!internal/playground\ lint lint:format, lint:eslint: pnpm turbo ... lint, lint:format: oxfmt --check . !docs/**/* !examples/**/* !explorations/**/* !observability/_examples/**/*也就是说Mastra 的 lint 体系由两层组成oxlint静态规则检查配置文件为根目录 oxlint.config.ts启用了import、unicorn、react、typescript、vitest插件并针对测试文件、源码文件做了细致的规则 override与 oxfmt格式化检查.prettierrc中声明了singleQuote、semi、trailingComma: all、printWidth: 120等代码风格约定。gh-fix-lint先修格式再修风格正是因为 oxfmt 的自动修复往往会影响代码排版若顺序颠倒格式修复后还需要重新过一遍 lint。值得说明的是gh-fix-lint使用的是全仓修复oxfmt . turbo 全量lint:fix而非仅对改动文件修复。这在 monorepo 场景下更稳妥PR 分支可能基于较旧的 main 检出改动文件之间、以及改动文件与周边代码之间的风格依赖全量修复都能一并覆盖代价是耗时更长但对一次性的「帮 PR 修 lint」操作完全可接受。仓库其实也提供了只针对本次改动文件的轻量脚本oxfmt:changed基于list-changed-files提取变更文件再逐个交给oxfmt如需对本地已开发的改动做快速修复可以选用。六、Step 5检查是否产生了改动修复命令执行完毕后检查工作区状态判断 PR 分支是否真的需要修复git status这里有两种结果分支无任何改动说明该 PR 分支本来就已经符合仓库的格式与 lint 规范Agent 直接告知用户「分支已经是干净、格式正确的」跳到 Step 7 收尾不产生任何提交存在改动进入 Step 6 提交并推送。七、Step 6提交并推送到贡献者 fork7.1 只暂存已跟踪的修改文件提交时有一个容易被忽略但非常重要的细节——只暂存被修改的已跟踪文件不暂存未跟踪文件git add -u git commit -m chore: fix lint and formatting issuesgit add -u--update只把「已跟踪文件」的修改和删除加入暂存区完全忽略未跟踪的新文件。这一步的意义在于PR 分支上往往有一些贡献者自己添加、但不应被维护者提交的文件比如本地生成物、临时脚本、调试文件。如果直接git add .这些未跟踪文件会被意外混入「chore: fix lint」提交并推送到贡献者的 fork造成噪音甚至冲突。提交信息统一使用 conventional commit 风格前缀chore:与仓库整体的提交规范见 gh-new-pr.md 中关于 conventional commits 的要求保持一致。7.2 推送回 fork提交完成后推送到贡献者的 fork 仓库owner 与仓库名均来自 Step 1git push https://github.com/owner-from-step-1/repo-name.git HEAD:branch-name-from-step-1这里的要点推送目标是https://github.com/owner/repo.git即headRepositoryOwner headRepository拼出的 fork 地址而不是当前维护者仓库HEAD:branch-name明确指定了推送的本地提交HEAD与远端目标分支避免依赖默认分支映射如果gh-fix-lint处理的是 Mastra 官方仓库的 PR那么owner/repo就是mastra-ai/mastra贡献者分支的 head 会直接推送回原 fork。7.3 推送失败的处理如果推送因权限不足而失败命令明确要求不要强行绕过告知用户两种后续方案——要么请贡献者给维护者授予 fork 的推送权限要么由贡献者自行修复 lint。这一约束保证了自动化流程始终在授权边界内操作不会尝试任何非法的凭据绕过手段。八、Step 7回到主分支并汇报结果无论是否产生了提交最后都要切回默认分支把工作区恢复到干净状态git checkout main随后向用户汇报本次执行的结果lint 修复是否已推送到 fork或者分支本来就是干净的。如果发生了推送建议顺带提醒用户 PR 的 CI 会因新提交而重新触发可以在 CI 通过后关闭对 lint 检查的异议。九、全流程回顾与安全边界把七个步骤串起来gh-fix-lint的完整执行流如下gh pr view $PR --json headRefName,headRepository,headRepositoryOwner,number,url提取 PR 元数据git status --porcelain确认工作区干净否则征求用户意见git fetch origin pull/$PR/head:branchgit checkout branch检出 PR 分支失败时--ff-only兜底pnpm oxfmt:formatpnpm format自动修复格式与 lintgit status判断是否真的有改动git add -ugit commit -m chore: fix lint and formatting issues然后推送到贡献者 forkgit checkout main收尾并汇报。整个流程贯穿了三条安全边界值得在复用到其他项目时保留操作前检查切换分支前必须确认工作区干净避免破坏维护者本地状态提交范围克制git add -u只暂存已跟踪文件的修改绝不把未跟踪文件混入提交权限边界明确推送到 fork 失败时不绕过权限而是转交用户与贡献者协商。十、与 gh-fix-ci 等命令协作完整的 PR 维护工作流gh-fix-lint并不是孤立存在的命令它与 .opencode/command/ 目录下的其他命令共同构成一套 PR 全生命周期自动化新 PR 落地先用 gh-new-pr.md 打开 PR 创建页面或按 pr.md 的流程先为各包生成 changesetpnpm changeset -s -m message --minor mastra/core --patch mastra这类按包指定版本增量再开 PRPR 打开后若 CI 失败用 gh-fix-ci.md 诊断gh pr status/gh pr checks并系统性修复CI 挂在 lint/format用gh-fix-lint直接拉分支、修码、推回把最机械的一步完全交给 Agent维护者回复配套的 gh-pr-comments.md 等命令负责与贡献者沟通闭环。对 Mastra 这类拥有上百个子包、lint 与格式规则极细oxlint 配置覆盖源码/测试/JS/TS 多类场景.prettierrc规定 120 列宽、单引号、全尾逗号的大型 TypeScript monorepo 来说把「帮 PR 修 lint」沉淀为 opencode 命令等于把最容易消耗维护者精力的重复劳动转交给了可审计、可复现的自动化流程——这也是 .opencode/command/ 目录存在的核心价值所在。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考