Mastra 文档审计评分标准（RUBRIC）全面解析：verdicts、五大审计维度与可复现的证据链要求

Mastra 文档审计评分标准RUBRIC全面解析verdicts、五大审计维度与可复现的证据链要求【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本文以 Mastra 仓库内 docs-audit 技能评分标准 为骨架系统拆解该文档审计框架的判定体系、严重级别、页面分类、五个审计维度与证据要求并结合其配套的 技能定义、审计报告模板 与 确定性检查脚本 说明其落地方式。读完本文你将掌握如何在 Mastra 文档变更评审中产出具备file:line证据、可复现、可排序的审计发现并理解判断型结论与确定性检查如何协同支撑最终的 pass / warn / fail 裁决。RUBRIC 的定位审计证据的所有者在 Mastra 的文档工程体系中写作规范与审计判据被刻意分离为两个职责边界写作规则由mastra-docs技能下的 canonical 参考文档拥有包括 STYLEGUIDE.md、INFORMATION_ARCHITECTURE.md、AUTHORING_WORKFLOW.md 等仓库根目录下的 docs/styleguides 目录保存了同一组规范的另一份副本而 RUBRIC.md 则负责审计侧的证据、严重级别、裁决与源码完整性预期——即这条规则该如何被检查、违反时如何定级、需要出示什么证据。RUBRIC 开头即声明了核心约束每一项发现finding都必须附上变更文档的file:line证据涉及准确性accuracy的发现还必须给出源码侧的file:line涉及规范遵循guidance的发现必须给出对应 canonical 指南的file:line。同时它要求将确定性发现deterministic findings与判断型发现judgment findings分开记录并将已证实与审计页无关的仓库噪音repository noise单独报告不得混入页面裁决。判定体系Verdicts 与 SeverityRUBRIC 定义了双层裁决模型页面级 verdict决定页面整体是否通过发现级 severity决定单条问题的影响权重。页面级裁决VerdictsVerdict含义pass审计范围内无实质问题No material issue in the audited scopewarn存在次要问题或验证局限降低了置信度但页面尚不至于误导或不可用fail页面存在实质性不准确、不完整、不安全、结构错误或不可遵循的问题发现级严重级别SeveritySeverity含义blocker发布或照做都不安全Unsafe to publish or followmajor很可能误导读者或导致实现失败minor页面仍可用但准确性、清晰度、完整性或可维护性受损nit局部小的一致性问题无实质性影响在实际执行时SKILL.md 给出的自主流程会要求先通过 diff 确定全部受审页面逐个分类并映射 canonical 指导再做有界的证据收集bounded evidence pass最后统一输出一份 AUDIT-REPORT.md 格式的报告并停止——审计是只读的、纯报告性质的不修改文档、不询问用户选择任务。必需的 canonical-guidance 覆盖RUBRIC 明确规定每一页审计都必须应用并记录以下规范依据STYLEGUIDE.mdINFORMATION_ARCHITECTURE.mdAUTHORING_WORKFLOW.md 中的验证指导适用页面类型的指南DOC.md、GUIDE_INTEGRATION.md或REFERENCE.md三者之一页面包含共享 MDX 或 llms-txt 感知组件时追加 COMPONENTS.md页面包含 Mermaid 或其他图表资源时追加 DIAGRAM.md。AUTHORING_WORKFLOW.md 中的 move / delete / redirect 指导仅在受审范围内确实发生这些操作时才使用。这一点在 SKILL.md 中同样被强调不要复述 canonical 规则的条文而是引用具体指南作为判据来源。页面变体五类页面的差异化审计侧重RUBRIC 按页面形态划分审计侧重避免用同一把尺子衡量所有页面Docs overview文档总览按DOC.md核对宽泛定位、canonical 所有权归属、层级关系、组件驱动的导航以及有用的下一步next steps。要求对总览讲授的 API 与行为做源码核对但不要求达到 reference 级别的枚举。Docs page普通文档页核对页面是否讲授一个连贯的概念或任务是否具备充分的前置条件、有序的指令、预期结果或验证方式以及相关导航对每个技术声明和用到的 API 做源码核对。Integration集成页按 GUIDE_INTEGRATION.md 核对安装与配置、包与 import 的正确性、provider 专属前置条件、任务或配方流程、验证方式与集成导航。Deployment integration部署集成页在集成检查之上追加部署关注点——公开展露前的认证、可复现的命令、环境变量与 secret 命名、生产依赖、扩缩容假设以及运维验证。Reference参考页应用 REFERENCE.md将页面声明的公共面与包导出、公共类型、实现与测试逐一对比核对参数、属性、重载、默认值、可选性、约束、错误、返回值、示例及相关的公共成员。超出页面声明的 API 面之外不强制要求内部实现细节。五大审计维度详解RUBRIC 将全部审计检查归并为五个维度每个维度都有独立的判定类型与三档结果pass / warn / fail维度 1Canonical-guidance compliance规范遵循类型针对mastra-docs的判断型检查。核对信息架构、页面形态、写作、链接、组件、图表、可访问性以及适用的作者工作流。判罚时引用具体指南而不是把指南条文抄进 rubric。pass页面遵循全部适用的 canonical 指导warn局部问题降低了清晰度或可维护性fail结构、归属、组件、图表、可访问性或写作问题实质性地损害了准确性或可遵循性。维度 2Deterministic checks确定性检查类型确定性检查。使用scripts/run-checks.sh对受审页面执行格式化、Remark、Vale 与仓库验证详见下文确定性检查的落地一节。只有能归因到受审路径、文档 ID 或路由的输出才计入页面工具缺失或归因模糊记为warn已证实的无关仓库失败单独报告。pass受审目标无错误warn某项检查无法运行或仓库验证的归因模糊fail存在可归因于受审页面的确定性错误。维度 3Contextual code accuracy上下文代码准确性类型针对源码与页面周边上下文的判断型检查。要求将每个代码块分类为standalone独立、incremental增量、illustrative示意、configuration-only仅配置、shell命令行或output输出之一只要求与角色相称的上下文完整度——相邻散文与前置代码块可以提供有意的省略。核对项包括imports、exports、符号、选项、必填字段、默认值、约束、异步行为、返回值、前置条件、命令与预期结果。部分片段不等于自动无效需要解释为何其上下文已足够或指出缺了什么具体上下文才使其误导。pass每个块对其角色而言准确且足够完整warn小的上下文缺失造成摩擦但不会教出错误行为fail页面讲授了过时、无效、误导或不可用的代码或命令。维度 4Source and public-surface completeness源码与公共面完整性类型针对导出源码的判断型检查。对 reference 页应用严格完整性与声明的导出 API 面完全对齐包括默认值、可选性、错误、约束、重载与返回行为对指南与总览页应用比例完整性需要源码支持其讲授的声明与 API而非穷举式 API 目录。pass声明的面与导出源码一致warn遗漏了不阻塞的默认值或边界情况fail页面缺失、陈旧、错误类型化或与源码矛盾的必需公共行为。维度 5Followability可遵循性类型情境判断。从页面推导出它所承诺的任务不要求用户代为选择核对前置条件、顺序、行话、凭据、外部服务边界、预期结果、验证方式以及散文与示例之间的一致性。不要求创建临时项目或独立编译每个代码块。pass读者能依据页面及其明确前置条件完成承诺任务或理解承诺的面warn存在轻微摩擦但任务基本可遵循fail指令缺失或错误阻塞了承诺任务或造成不安全结果。发现质量一条合格 finding 的七要素RUBRIC 对发现的可行动性提出了硬性要求一条有效发现必须拥有唯一 ID并包含严重级别与所属维度severity and dimension变更文档的file:line适用时的源码或 canonical 指南file:line精确的矛盾描述或缺失需求the precise contradiction or missing requirement读者影响reader impact有界补救方向a bounded remediation——即最小正确修复方向而非长篇修复计划。同时明确禁止三类行为不报告泛泛的偏好generic preferences不把同一问题复制到多个 ID 下one issue, one ID不把无关的仓库失败当作页面发现处理。SKILL.md 进一步规定accuracy 类发现必须附源码file:lineguidance 类发现必须附确立该规则的 canonical 指南file:line并始终优先使用当前源码与导出而非历史记录。确定性检查的落地run-checks.sh 的运行模型RUBRIC 维度 2 所依赖的 run-checks.sh 是一个只读检查器针对一个或多个受审文档运行bash .claude/skills/docs-audit/scripts/run-checks.sh \ --docs docs/src/content/en/docs/index.mdx # 多个文件可重复传入 --docs bash .claude/skills/docs-audit/scripts/run-checks.sh --docs docs/a.mdx --docs docs/b.mdx脚本头注释明确定义了三档退出码0表示受审目标通过可能存在警告或已证实的无关验证失败1表示受审目标或检查器执行失败2表示 CLI 用法错误如--docs缺少参数。从脚本实现看run-checks.sh它会依次执行四类检查每类产生一行状态输出最后打印五条摘要输出行检查工具关键参数format-targetpnpm exec oxfmt-mdx --check对受审文件做 MDX 格式化检查remark-targetpnpm exec remark --no-stdout --frail --quiet --ext mdxremark 静态检查--frail使警告升级为失败vale-targetscripts/vale/bin/vale --minAlertLevelerror --outputline散文风格检查仅在docs/scripts/vale/bin/vale存在时运行validate-targetpnpm validate仓库级验证见下文repo-wide-failures—已证实的无关失败取值为none/validate/validate-ambiguous其中pnpm validate在 docs/package.json 中定义为并行运行四个校验validate:frontmatter、validate:reference-sidebar、validate:sidebar-docs、validate:sidebar-new-tags。值得注意的归因逻辑若 Vale 二进制缺失vale-target记为warn并提示先运行pnpm vale:download或pnpm vale:sync对应 docs/package.json 中的脚本validate-target的判定最考究先检查诊断输出中是否提到受审目标路径、路由、doc ID提到了才判fail若诊断可归因到其他路径则判pass并把repo-wide-failures记为validate若归因模糊则validate-targetwarn且repo-wide-failuresvalidate-ambiguous。这套归因设计直接呼应 RUBRIC 的核心原则只有可归因于审计页面的确定性错误才计入页面裁决仓库级噪音单独记账。与审计报告格式的衔接RUBRIC 是判据而 AUDIT-REPORT.md 规定了产出的形状。最终报告固定为八个必需章节Audit scope记录 base/diff、受审页面、排除与限制Page classification and canonical-guidance compliance每页一行给出分类仅限docs overview/docs page/integration/deployment integration/reference与应用的 canonical 参考映射Source verification列出受审的包/API 面、实际检查过的源码路径区间与结果Contextual code-block outcomes逐块记录角色分类、上下文来源、源码检查项与结果明确记录合理的有意省略Reference completeness对 reference 页逐条核对声明的公共面与导出源码非 reference 场景写Not applicableDeterministic checks记录精确命令、四个-target状态与仓库级噪音Findings按唯一 ID 组织每条含 severity、dimension、三处证据变更文档 / 源码 / canonical 指南或确定性命令、问题、影响与有界补救Overall verdict汇总 verdict、各严重级别计数与一段结论。规则同样禁止在报告中出现临时工件路径、交互式任务选择流程、实施计划或审计后修复/执行章节——审计在报告产出后即停止任何修复请求都视为后续的独立实施任务。实践要点将 RUBRIC 用于 Mastra 文档评审先建证据再下结论任何页面不准确的说法都必须同时出示文档行号与源码行号规范类问题必须指向具体 canonical 指南而不是我印象里规范要求……。区分判断与确定性格式化、remark、Vale、sidebar 验证交给 run-checks.sh 输出可复现状态代码语义、公共面完整性、可遵循性则依赖人工对照源码Mastra 的 API 面可对照 packages/core 等包的导出实现。按页面角色定标对 overview 不强求 API 穷举对 reference 则必须逐参数核对默认值、可选性与返回行为避免一把尺子量所有页面。保持发现原子化一条发现只描述一个具体矛盾配一个唯一 ID 与一个有界补救方向无关仓库失败另列不稀释页面裁决。这套框架的价值在于把文档质量从主观感受转化为带证据、可复现、可排序的工程产物verdict 负责裁决severity 负责排序五个维度负责覆盖不同类型的缺陷而file:line证据要求则保证了每一条结论都能被审阅者一键回溯验证。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考