企业官网建设流程全解析

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 与 Severity

RUBRIC 定义了双层裁决模型：页面级 verdict决定页面整体是否通过，发现级 severity决定单条问题的影响权重。

页面级裁决（Verdicts）

发现级严重级别（Severity）

在实际执行时，SKILL.md 给出的自主流程会要求：先通过 diff 确定全部受审页面，逐个分类并映射 canonical 指导，再做有界的证据收集（bounded evidence pass），最后统一输出一份 AUDIT-REPORT.md 格式的报告并停止——审计是只读的、纯报告性质的，不修改文档、不询问用户选择任务。

必需的 canonical-guidance 覆盖

RUBRIC 明确规定，每一页审计都必须应用并记录以下规范依据：

• STYLEGUIDE.md；
• INFORMATION_ARCHITECTURE.md；
• AUTHORING_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 按页面形态划分审计侧重，避免用同一把尺子衡量所有页面：

1. Docs overview（文档总览）：按DOC.md核对宽泛定位、canonical 所有权归属、层级关系、组件驱动的导航，以及有用的下一步（next steps）。要求对总览讲授的 API 与行为做源码核对，但不要求达到 reference 级别的枚举。
2. Docs page（普通文档页）：核对页面是否讲授一个连贯的概念或任务，是否具备充分的前置条件、有序的指令、预期结果或验证方式，以及相关导航；对每个技术声明和用到的 API 做源码核对。
3. Integration（集成页）：按 GUIDE_INTEGRATION.md 核对安装与配置、包与 import 的正确性、provider 专属前置条件、任务或配方流程、验证方式与集成导航。
4. Deployment integration（部署集成页）：在集成检查之上追加部署关注点——公开展露前的认证、可复现的命令、环境变量与 secret 命名、生产依赖、扩缩容假设以及运维验证。
5. Reference（参考页）：应用 REFERENCE.md，将页面声明的公共面与包导出、公共类型、实现与测试逐一对比；核对参数、属性、重载、默认值、可选性、约束、错误、返回值、示例及相关的公共成员。超出页面声明的 API 面之外，不强制要求内部实现细节。

五大审计维度详解

RUBRIC 将全部审计检查归并为五个维度，每个维度都有独立的判定类型与三档结果（pass / warn / fail）：

维度 1：Canonical-guidance compliance（规范遵循）

类型：针对mastra-docs的判断型检查。核对信息架构、页面形态、写作、链接、组件、图表、可访问性以及适用的作者工作流。判罚时引用具体指南，而不是把指南条文抄进 rubric。

• pass：页面遵循全部适用的 canonical 指导；
• warn：局部问题降低了清晰度或可维护性；
• fail：结构、归属、组件、图表、可访问性或写作问题实质性地损害了准确性或可遵循性。

维度 2：Deterministic checks（确定性检查）

类型：确定性检查。使用scripts/run-checks.sh对受审页面执行格式化、Remark、Vale 与仓库验证（详见下文"确定性检查的落地"一节）。只有能归因到受审路径、文档 ID 或路由的输出才计入页面；工具缺失或归因模糊记为warn；已证实的无关仓库失败单独报告。

• pass：受审目标无错误；
• warn：某项检查无法运行，或仓库验证的归因模糊；
• fail：存在可归因于受审页面的确定性错误。

维度 3：Contextual code accuracy（上下文代码准确性）

类型：针对源码与页面周边上下文的判断型检查。要求将每个代码块分类为standalone（独立）、incremental（增量）、illustrative（示意）、configuration-only（仅配置）、shell（命令行）或output（输出）之一，只要求与角色相称的上下文完整度——相邻散文与前置代码块可以提供有意的省略。

核对项包括：imports、exports、符号、选项、必填字段、默认值、约束、异步行为、返回值、前置条件、命令与预期结果。部分片段不等于自动无效：需要解释为何其上下文已足够，或指出缺了什么具体上下文才使其误导。

• pass：每个块对其角色而言准确且足够完整；
• warn：小的上下文缺失造成摩擦，但不会教出错误行为；
• fail：页面讲授了过时、无效、误导或不可用的代码或命令。

维度 4：Source and public-surface completeness（源码与公共面完整性）

类型：针对导出源码的判断型检查。对 reference 页应用严格完整性（与声明的导出 API 面完全对齐，包括默认值、可选性、错误、约束、重载与返回行为）；对指南与总览页应用比例完整性（需要源码支持其讲授的声明与 API，而非穷举式 API 目录）。

• pass：声明的面与导出源码一致；
• warn：遗漏了不阻塞的默认值或边界情况；
• fail：页面缺失、陈旧、错误类型化或与源码矛盾的必需公共行为。

维度 5：Followability（可遵循性）

类型：情境判断。从页面推导出它所承诺的任务（不要求用户代为选择），核对前置条件、顺序、行话、凭据、外部服务边界、预期结果、验证方式，以及散文与示例之间的一致性。不要求创建临时项目或独立编译每个代码块。

• pass：读者能依据页面及其明确前置条件完成承诺任务或理解承诺的面；
• warn：存在轻微摩擦，但任务基本可遵循；
• fail：指令缺失或错误，阻塞了承诺任务或造成不安全结果。

发现质量：一条合格 finding 的七要素

RUBRIC 对发现的"可行动性"提出了硬性要求：一条有效发现必须拥有唯一 ID，并包含：

1. 严重级别与所属维度（severity and dimension）；
2. 变更文档的file:line；
3. 适用时的源码或 canonical 指南file:line；
4. 精确的矛盾描述或缺失需求（the precise contradiction or missing requirement）；
5. 读者影响（reader impact）；
6. 有界补救方向（a bounded remediation）——即"最小正确修复方向"，而非长篇修复计划。

同时明确禁止三类行为：不报告泛泛的偏好（generic preferences）；不把同一问题复制到多个 ID 下（one issue, one ID）；不把无关的仓库失败当作页面发现处理。SKILL.md 进一步规定：accuracy 类发现必须附源码file:line，guidance 类发现必须附确立该规则的 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），它会依次执行四类检查，每类产生一行状态输出，最后打印五条摘要：

其中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-target=warn且repo-wide-failures=validate-ambiguous。

这套归因设计直接呼应 RUBRIC 的核心原则：只有可归因于审计页面的确定性错误才计入页面裁决，仓库级噪音单独记账。

与审计报告格式的衔接

RUBRIC 是判据，而 AUDIT-REPORT.md 规定了产出的形状。最终报告固定为八个必需章节：

1. Audit scope：记录 base/diff、受审页面、排除与限制；
2. Page classification and canonical-guidance compliance：每页一行，给出分类（仅限docs overview/docs page/integration/deployment integration/reference）与应用的 canonical 参考映射；
3. Source verification：列出受审的包/API 面、实际检查过的源码路径区间与结果；
4. Contextual code-block outcomes：逐块记录角色分类、上下文来源、源码检查项与结果，明确记录合理的有意省略；
5. Reference completeness：对 reference 页逐条核对声明的公共面与导出源码，非 reference 场景写Not applicable；
6. Deterministic checks：记录精确命令、四个-target状态与仓库级噪音；
7. Findings：按唯一 ID 组织，每条含 severity、dimension、三处证据（变更文档 / 源码 / canonical 指南或确定性命令）、问题、影响与有界补救；
8. 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