Mastra PR 审查智能体的 TypeScript 风格规范命名约定、导入排序与错误处理标准【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本文解析 Mastra 官方模板template-github-review-agent中作为 AI 代码审查裁判规则的样式指南文档 style-guide.md。该文件定义了命名约定、文件内代码组织顺序、导入排序、错误处理与注释规范五类硬性标准是审查智能体在 Step 3 Style Guide Conformance 阶段逐条核对的依据。读完后你将理解这份规范如何被 Workspace 技能机制加载进智能体指令、如何随 PR 规模自适应地生效以及如何按团队约定修改它。文档定位审查智能体技能体系的参考文件在 template-github-review-agent 模板中审查标准以Workspace 技能组织在workspace/skills/目录下包含code-standards、security-review、performance-review三个技能。每个技能由一个SKILL.md定义审查流程加references/下的详细清单文件组成。本风格指南就是code-standards技能的参考文件workspace/skills/code-standards/ ├── SKILL.md # 四步审查流程Critical → Quality → Style → Linting └── references/ └── style-guide.md # 本文档风格核对基准技能文件 SKILL.md 在 Step 3 中明确写道Check against the style guide inreferences/style-guide.md检查项包括命名约定、代码组织与导入排序、注释质量解释 why 而非 what。也就是说这份文档不是给人类看的软性建议而是被智能体逐条执行的核对基准。命名约定Naming Conventions原文档以表格形式给出了六类元素的命名标准完整继承如下元素约定示例变量与函数camelCasegetUserName、isActive常量UPPER_SNAKE_CASEMAX_RETRIES、API_BASE_URL类与类型PascalCaseUserService、PullRequestData文件kebab-caseuser-service.ts、pr-review.ts布尔值is/has/should 前缀isValid、hasPermission、shouldRetry事件处理器handle/on 前缀handleClick、onSubmit这套约定与 TypeScript 社区主流实践一致审查智能体在评审他人 PR 时会以它作为判断命名是否规范的客观依据——例如把一个命名为UserNameService的函数标识为违反函数用 camelCase的约定把一个名为doStuff的工具函数归入缺乏描述性命名的 Suggestions。值得注意的是模板自身也践行了其中一部分约定常量如SMALL_PR_MAX、MEDIUM_PR_MAX、BATCH_CHAR_BUDGET见 pr-review-workflow.ts均为 UPPER_SNAKE_CASE布尔返回字段hasMore使用 has 前缀文件采用 kebab-case 命名pr-review-workflow.ts、review-config.ts。文件内代码组织顺序原文档规定每个文件内部应按以下六个层次自上而下组织Imports导入——顺序为外部 → 内部 → 相对路径Constants and configuration——常量与配置Type definitions——类型定义Helper/utility functions——辅助/工具函数Main functions or class definition——主函数或类定义Exports——导出从源码结构看这个顺序在模板实现中被严格遵循。以 pr-review-workflow.ts 为例文件开头是导入区zod、GitHub 工具函数、审查配置随后是BATCH_CHAR_BUDGET、BATCH_FILE_LIMIT两个常量接着是prBaseSchema、prContextSchema等类型/Schema 定义然后是buildFileSection、batchFiles两个工具函数最后是各步骤与prReviewWorkflow的导出。这种配置在上、逻辑在下的布局让审查者可以快速定位一个文件的关注点也是智能体评判代码组织是否合理时的参照系。导入排序Import Ordering原文档给出了一段可直接复制的 TypeScript 示例展示四层导入顺序// 1. Node built-ins import { resolve } from node:path; // 2. External packages import { z } from zod; // 3. Internal/project imports import { myUtil } from /utils; // 4. Relative imports import { helper } from ./helper;即Node.js 内建模块最先其次是外部包再次是通过/别名的项目内部导入最后是./相对路径导入。这一约定与文件内Imports外部 → 内部 → 相对的组织原则一脉相承。模板的入口文件 index.ts 就是遵循该顺序的真实样本node:path内建导入排第一mastra/*外部包居中./agents/...、./workflows/...相对导入殿后。错误处理与注释标准原文档在 Error Handling 部分给出四条规则使用显式错误处理——不要静默吞掉错误优先使用具体错误类型而非泛化Error始终处理 Promise 拒绝记录错误日志时携带足够的调试上下文。在注释Comments部分则要求写 why 注释不写 what 注释——原文档给出的正反对照很有代表性// increment counter是坏的// Retry up to 3 times to handle transient network failures才是好的公共 API 函数使用 JSDoc删除被注释掉的代码——交给版本控制系统去留。这两组规则与技能文件 SKILL.md 的 Step 4 Linting Flags 形成互补后者负责标记var使用、遗留console.log/debugger、被注释掉的代码块、无命名常量的魔法数字、无 issue 引用的TODO/FIXME。从源码结构看错误处理规则在模板自身实现中同样有体现例如parseGitHubPRUrl工具在正则不匹配时抛出带完整期望格式的Error见 github.ts这正是携带足够上下文的显式错误的范例。风格指南如何被加载进智能体这份文档并非静态存在而是通过 Mastra 的 Workspace 机制进入智能体的上下文。入口文件 index.ts 创建了 Workspaceconst workspace new Workspace({ filesystem: new LocalFilesystem({ basePath: resolve(import.meta.dirname, ../../workspace), }), skills: [/skills], });LocalFilesystem以模板下的workspace/目录为根skills: [/skills]声明技能挂载点。code-review-agent.ts 的 instructions 中 Workspace Skills — Activate ALL of the Following 一段要求智能体对 Code Standards 技能强制执行一致的语言命名约定、格式与惯用模式标记死代码、未使用导入和不必要的复杂度——这些正是 style-guide.md 各项规则的自然语言表述。在 Workflow 模式下同一份标准通过提示词注入生效pr-review-workflow.ts 的buildPrompt中明确写着 Apply all workspace skills (code-standards, security-review, performance-review)随后逐批把文件 diff 与完整内容交给workflow-review-agent评审并用 Zod 的fileReviewSchema约束输出为结构化问题列表。自适应审查深度风格检查何时生效一个关键细节是风格指南的严格程度随 PR 规模自适应调整。review-config.ts 定义了阈值SMALL_PR_MAX 6、MEDIUM_PR_MAX 20并通过REVIEW_DEPTH_INSTRUCTIONS生成三档指令小 PR1–6 个文件DETAILED——逐行审查comment on style, logic, naming, and edge cases风格指南在此档被最严格地应用中 PR7–20 个文件FOCUSED——聚焦逻辑正确性与架构决策skip minor style nits风格问题降级处理大 PR20 个文件HIGH-LEVEL——只看关键问题bug、安全漏洞、重大设计缺陷命名与格式类建议基本让位于 Critical Issues。这意味着同一份 style-guide.md 在不同规模的 PR 上会产生不同强度的反馈——小 PR 会收到命名前缀、导入顺序级别的细粒度意见而大 PR 只会在命名严重误导理解时才被提及。调整SMALL_PR_MAX/MEDIUM_PR_MAX即可改变这一行为这在 README.md 的 Adjust thresholds 一节中也有说明。将规范改造为你团队自己的标准README.md 在 Change review standards 一节指出直接编辑workspace/skills/下的文件即可让审查标准匹配团队约定——SKILL.md定义审查流程references/文件提供详细清单。因此这份 style-guide.md 是模板中最适合按团队定制的文件之一若团队使用 snake_case 函数命名替换 Naming Conventions 表格对应行即可若团队要求文件名用 PascalCase组件导向的项目修改 Files 一行的约定与示例若需要补充React 组件必须函数式等语言级约定可在 Error Handling 或 Comments 之外新增小节并同步在 SKILL.md 的 Step 3 检查项中列出保证流程与清单一致。由于技能文件通过LocalFilesystem从本地目录直接读取修改references/style-guide.md后重启开发服务器npm run dev即可让新标准在 Agent 与 Workflow 两条审查路径上同时生效无需改动任何智能体或工作流代码。小结style-guide.md 篇幅不长却是 Mastra GitHub PR 审查模板中代码质量维度的最终裁决标准六类命名约定、六层文件组织顺序、四层导入排序、四条错误处理规则、三类注释要求共同构成智能体在 Step 3 逐项核对的清单而 review-config.ts 中的 PR 规模阈值决定这份清单在小、中、大 PR 上分别以多强的力度执行。对团队而言这份文件是现成的AI 审查规则起点——把它改造成自己的工程约定就能让 AI 代码审查输出与团队标准一致的反馈。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考