Skip to content

审核标准

文档审核的完整流程与标准——贡献者自检清单、维护者审核清单、PR 要求、审核时效与冲突处理

基础
官方•Dingding OvO · 2026-08-12

审核是保证 MCBECD 文档质量的关键环节。本文档定义了贡献者的自检流程和维护者的审核标准，确保每篇合并到主分支的文档都符合所有规范。

一、贡献者自检流程

在提交 Pull Request 之前，贡献者必须完成以下自检。维护者在审核时也将按此清单检查。

1.1 Frontmatter 自检

  • title 字段存在且格式正确
    • 命令文档：/command 中文名称（两个空格）
    • 社区文档：纯中文名称
  • description 字段存在且长度在 15-40 字之间
  • author 字段已填写
  • updatedAt 字段格式为 YYYY-MM-DD 且为近期日期
  • tags 字段已填写（命令文档和社区文档必填）
    • 命令文档：对照标签对照表检查
    • 社区文档：包含 1 个内容类型 + 1-2 个技术栈
  • 不存在未定义的 frontmatter 字段

1.2 内容自检

命令文档：

  • 开头段落存在（无标题）
  • ### 语法 章节存在
  • ### 参数 章节存在
  • ### 示例 章节存在，且至少 3 个示例
  • ### 基岩版注意 章节存在
  • 每个示例包含标题、代码块（mcfunction）、效果说明
  • 正文长度不低于 800 字（不含代码块）

社区文档：

  • 功能描述段落存在
  • 前置指令使用 <CmdChat> 组件
  • 命令方块指令使用正确的 <CmdXxx> 组件
  • 方块类型和设置已标注
  • 常见问题使用 <details> 折叠
  • 正文长度不低于 400 字（不含代码块）

通用检查：

  • 所有命令引用使用了 [`/command`](../command/) 格式
  • 交叉引用使用相对路径
  • 代码块使用了正确的语言标记（mcfunction、json 等）
  • 没有使用 Markdown 图片语法
  • 没有使用废弃的 frontmatter 值
  • 中英文之间有空格
  • 无错别字

1.3 文件自检

  • 文件扩展名为 .md
  • 命令文档在 commands/ 子目录下
  • 社区文档在根目录，文件名为纯数字
  • 基础文档在根目录
  • 文件名符合命名标准

二、维护者审核流程

2.1 审核清单

维护者在审核 PR 时，必须按以下清单逐项检查：

Frontmatter 审查：

  1. 对照Frontmatter 标准规范检查所有字段
  2. 对照标签对照表检查 tags 是否正确

内容审查： 4. 检查文档结构是否包含所有必须章节 5. 检查示例数量是否足够（命令文档 ≥ 3 个） 6. 检查交叉引用路径是否正确 7. 检查 MD 组件使用是否正确（<CmdXxx> 选择是否合理） 8. 检查内容是否有事实性错误 9. 检查命令语法是否正确（可实际执行） 10. 检查中文写作质量

文件审查： 11. 确认文件名符合命名标准 12. 确认文件位置正确（子目录或根目录）

2.2 常见审核问题

问题严重程度处理方式
缺少必须章节高要求补充后重新审核
tags 不符合对照表高要求修正
title 格式错误高要求修正
示例数量不足中建议补充
交叉引用路径错误中要求修正
描述太短/太长低建议修改
未定义 frontmatter 字段低建议移除

2.3 审核回复格式

维护者审核后应给出明确的回复：

  • 通过：直接合并
  • 需修改：列出需要修改的具体项目，使用清单格式
  • 拒绝：说明拒绝原因

三、PR 要求

3.1 PR 标题格式

add: /weather 命令文档
fix: 修正 /give 参数说明
update: 更新雪球菜单文档

前缀说明：

  • add：新增文档
  • fix：修复错误
  • update：更新内容
  • remove：删除文档

3.2 PR 描述

PR 描述应包含：

  • 修改了哪些文件
  • 修改的内容概述
  • 是否需要特别注意的变更

3.3 分支命名

add-weather-command
fix-give-params
update-snowball-menu

四、冲突处理

4.1 标签冲突

如果贡献者认为标签对照表中的标签不适合某个命令，应在 PR 中说明理由。维护者评估后决定是否调整对照表。

4.2 格式争议

如果贡献者认为某条格式规范不合理，应在 Issue 中讨论。在达成共识之前，以本文档为准。

4.3 内容准确性

如果对命令的实际行为有争议，应以游戏内测试结果为准。维护者应在游戏中实际执行命令验证文档内容。

五、自动化校验

5.1 校验脚本

MCBECD 项目提供校验脚本，可在提交前运行：

node scripts/validate-docs.mjs

校验规则：

  • 必填字段存在性（title、description、author、updatedAt）
  • updatedAt 日期格式
  • tags 数组格式

5.2 构建检查

站点构建时（next build），文档引擎会解析所有 .md 文件。解析失败的文件会产生警告日志，但不会阻止构建。

六、标准更新流程

当本文档或其他标准文档需要更新时：

  1. 在 MCBECD/docs 仓库提交 Issue 说明变更内容
  2. 维护者讨论批准后修改标准文档
  3. 更新标准文档的 updatedAt 字段
  4. 通知所有贡献者新标准
  5. 现有文档在合理时间内完成迁移