GameDevMind 文档命名规范全解：编号体系、目录结构、标签字段与自动化校验

GameDevMind 文档命名规范全解编号体系、目录结构、标签字段与自动化校验【免费下载链接】GameDevMind最全面的游戏开发技术图谱(Game Development Map)。帮助游戏开发者们在已知问题上节省时间省出更多的精力投入到更有创造性的工作中去。项目地址: https://gitcode.com/GitHub_Trending/ga/GameDevMind本文以 GameDevMind最全面的游戏开发技术图谱仓库中的《文档命名规范》为核心完整拆解该图谱知识库mds/目录下的文档命名格式、目录组织方式、叶子文档结构、标签字段约定与图片/链接规则并结合 tools/check/ 中的真实校验脚本与 tools/config.yaml 配置说明每条规范如何被自动化工具落地检查帮助贡献者在提交新文档前一次性通过质量门禁。1. 规范的适用范围《文档命名规范》与 CONTRIBUTING.md 配套使用适用于mds/下新增或重命名的文档。它解决的是知识图谱型仓库的核心治理问题当文档规模达到数百篇时如何用一套可被脚本解析的命名规则同时保证人可读、机器可检索、链接可自动校验。该规范并非孤立存在它与仓库的三层基础设施对应层次承载物作用分类逻辑docs/知识结构分层规范.md六大能力模块1.基础能力6.运营能力的判定标准决定文档该放在哪命名与结构docs/文档命名规范.md决定文档叫什么名、长什么样自动校验tools/check/ tools/config.yaml用脚本检查命名与字段是否合规其中六大能力模块按价值链组织——基础知识 → 游戏专项技术 → 游戏产品研发 → 工业化生产 → 管理协作 → 上线运营与盈利文档文件名中的首位编号N16正是模块号。2. 文件命名五类文档格式规范定义了mds/下五种文件命名格式类型格式示例能力模块入口{模块号}.{模块名}.md1.基础能力.md子分类入口{模块号}.{子号}.{子类名}.md1.1.编程语言.md叶子文档{模块号}.{子号}.{序号}.{主题名}.md1.1.1.编程语言基础概念.md专题mds/topics/{主题名}.mdtopics/游戏开发新人.md归档/扩展x-{编号}.{主题}.mdx-1.开发技术.md规则细节使用中文主题名与现有文档保持一致仓库现有文档即如1.1.2.C语言.md、2.2.1.网络与通信.md等编号使用半角数字 点号不要在编号段之间插入空格扩展名统一.md文件名中避免/ \ : * ? |等字符。源码级印证叶子文档的判定规则被编码在 tools/config.yaml 中供所有检查脚本共用check: # 叶子文档文件名含三段编号如 1.1.1.标题.md leaf_doc_pattern: ^\d\.\d\.\d.\.md$ skip_filenames: - 阅读说明.md skip_dir_names: - topics - 一站式手游创业从 tools/check/check_docs.py 的is_leaf_doc()实现看脚本判定一篇文档是否为叶子文档即需要强制检查关键词/标签字段的文档的逻辑与命名规范完全对应文件名命中skip_filenames如阅读说明.md→ 跳过文件名以x-开头归档/扩展文档→ 跳过路径中任一部分命中skip_dir_namestopics/、一站式手游创业/→ 跳过否则用正则^\d\.\d\.\d.\.md$匹配——恰好三段编号前缀的文档才被判定为叶子文档。这就解释了为什么命名规范如此强调编号段之间不要插入空格命名一旦不符合三段数字点号模式该文档会静默脱离自动化检查范围。3. 目录结构编号文件名与目录的一一对应规范给出的目录骨架如下mds/ ├── {N}.{模块名}/ # N 16 │ ├── {N}.{模块名}.md # 模块入口 │ ├── {N}.{子}.{子类}.md # 子类入口可选 │ └── {N}.{子}.{序}.{主题}.md ├── topics/ # 跨模块专题 └── 阅读说明.md # 全局阅读指南关键约束模块目录名与模块入口文件名一致目录1.基础能力/内放入口1.基础能力.md保证目录即章节读者在文件树中看到的结构就是知识结构本身子类入口可选1.1.编程语言.md可存在但叶子文档也可以直接挂在模块目录下topics/只组织阅读路径和跨模块专题不复制正文该约定同时出现在 知识结构分层规范 的文档组织规则中因此检查脚本将topics/整体排除在叶子文档校验之外。仓库实际结构印证了这一骨架mds/1.基础能力/下既有入口1.基础能力.md也有子类入口1.1.编程语言.md、1.2.程序设计.md和叶子文档1.1.1.编程语言基础概念.md等。4. 叶子文档结构与正文内部层级4.1 标准结构七要素叶子文档参考 template/z.模板.md标准结构为## 标题 简介p.../p**关键词:**/**标签:**可选## 目录正文表格化「是什么 / 问题 / 要点」可选AI Coding 指南表格可选## 延伸实践## 更多资料模板骨架取自 template/z.模板.md## 文档标题 p一句话说明本文档覆盖的范围与读者对象。/p **关键词:**br/ *关键词1, 关键词2, AI Coding* **标签:**br/ *等级: 中级, 阶段: 开发, 分类: 技术能力, 角色: 客户端开发* ## 目录 可选 ## 小节一 | 维度 | 内容 | | **作用** | 是什么 | | **应用场景** | 在哪用 | | 问题 | 解决方向 | | **常见问题** | 解决思路 | | 类型 | AI Coding 指南 | | **提示词范例** | 「…」 | ## 更多资料 可选CONTRIBUTING.md 同时明确了 Markdown 格式约束允许在 Markdown 中混用少量 HTMLp、br、table、img等展示类标签以保持 GitHub 上的阅读样式与历史文档一致避免无意义的嵌套div、内联脚本和过时样式。4.2 正文内部层级规则命名规范对长文档的层级组织给出了量化约束这是防止知识文档平铺失控的关键文档标题使用##正文用领域分组 → 知识主题两级组织避免不同层级概念全部平铺在同一级标题下每篇较长正文建议设置37 个##领域分组每组包含28 个###知识主题##用于完整知识领域如关系数据库与 SQL###用于可独立检索的具体主题如事务图集是什么 / 在哪用会遇到哪些问题要点和思考方向AI Coding 指南等固定信息块保留在###主题内部不升级为标题####仅用于步骤、方案变体、算法细节或配置项正文嵌套通常不超过两层正文超过约 450 行时应先检查是否缺少领域分组单个主题超过250300 行且拥有独立读者或维护边界时再考虑拆成独立文件目录优先列出##领域分组长文档可在分组下列出关键###主题不必把每个信息块都列入目录模块入口文档、阅读路径和专题文档可以采用自己的结构不强行套用叶子文档的技术主题模板。5. 标签字段约定叶子文档必须包含标签字段格式固定**标签:**br/ *等级: 入门|初级|中级|高级, 阶段: 学习|开发|运营, 分类: {模块名}, 角色: 客户端开发|服务端开发*字段取值说明等级入门 / 初级 / 中级 / 高级可多选用\|分隔阶段学习 / 开发 / 运营读者所处价值链阶段分类与六大能力模块一致每篇文档只有一个主分类跨层关系通过正文链接和专题路径表达不在一个文档中填写多个主分类角色客户端开发 / 服务端开发 / 全栈 / 美术 / 运维 等面向岗位分类字段与 知识结构分层规范 中每篇正文只有一个主归属其他关系通过链接和标签表达的组织规则直接对应。这些字段不是装饰tools/check/check_docs.py 通过正则KW_RE匹配**关键词:**和TAG_RE匹配**标签:**对每篇叶子文档做强制检查缺失即报错退出。结合 tools/config.yaml 中require_keywords: true、require_tags: true两项配置可以确认关键词与标签字段是叶子文档的硬性必检项且大小写不敏感正则带re.IGNORECASE。6. 图片与链接规则规范对图片与内部链接的路径写法做了统一约定对象写法约定图谱图../../exports/{与文档同名的前缀}.png相对路径不加?rawtrue模块内链接相对路径如../2.技术能力/2.2.1.网络与通信.md配套资源链到code/gamedevmind/、cases/、ai-cases/时用相对路径从mds/子目录通常为../../code/gamedevmind/...以仓库中真实存在的例子验证mds/1.基础能力/1.1.2.C语言.md引用同前缀图谱图../../exports/1.1.2.C语言.png该图片确实存在于exports/目录。不加?rawtrue这条约定同样有脚本兜底check_docs.py 定义了RAW_TRUE_RE re.compile(r\?rawtrue)凡命中即输出警告contains ?rawtrue (prefer plain relative paths)。图片引用是否真实存在也会被逐一解析——脚本用与渲染一致的规则去 query、去锚点、按 md 文件所在目录解析相对路径检查每个...指向的文件缺失时报告missing image。7. 可选YAML Front Matter新文档不强制Front Matter。若需脚本或静态站点消费元数据可在文首添加--- title: 编程语言基础概念 category: 基础能力 last_updated: 2026-06-20 ---唯一约束与正文中的**关键词:**/**标签:**保持语义一致即可。也就是说Front Matter 是元数据的冗余投影不是权威来源——正文标签字段才是检查脚本校验的对象。8. 提交前自检规范的自动化落地8.1 标准命令规范给出的提交前自检流程在仓库根目录执行pip install -r tools/check/requirements.txt python tools/check/check_docs.py python tools/check/check_images.py三个脚本分工如下见 tools/check/README.md脚本用途check_docs.py必填字段关键词/标签、图片存在性、UTF-8、?rawtrue警告check_images.py缺失引用、未引用图片、大文件列表--compress优化 PNGgenerate_keywords.py汇总各文档关键词生成根目录 KEYWORDS.md8.2 check_docs.py 的完整检查项从源码看check_docs.py 对mds/下所有 Markdown 文件执行以下检查编码文件必须以 UTF-8 可读否则记 errornot UTF-8必填字段仅叶子文档判定逻辑见第 2 节缺**关键词:**或缺**标签:**均记 error图片存在性逐一解析本地路径不存在记 warningmissing image?rawtrue命中即 warning提示改用纯相对路径行尾空白warn_trailing_whitespace开启时报告首个含行尾空格/Tab 的行号每个文件最多报一处输出与退出码warning 最多打印 50 条超出显示... and N more有 error 时退出码为 1否则 0。支持--warn-only参数仅输出警告、不改变退出语义。配置加载链路为lib_config.py 读取 tools/config.yamlYAML 缺失或未安装 PyYAML 时回退到内置默认值默认值与当前 config.yaml 中的检查项一致mds_dir为mds。8.3 check_images.py 与关键词索引check_images.py 做双向审计正向mds/之外的README.md、cases/、ai-cases/、code/等位置引用的本地图片也会纳入解析缺失引用被报告反向扫描exports/、images/两个目录由 config.yaml 的images.scan_dirs指定中未被任何文档引用的图片体积超过large_file_kb默认 500 KB的 PNG 列入大文件清单--compress基于 Pillow 对可安全重写的 PNG 做optimizeTrue原地压缩并统计节省字节。generate_keywords.py 则把各叶子文档的关键词聚合为根目录 KEYWORDS.md供站点检索与搜索引擎消费——这解释了为什么命名规范要求每篇叶子文档必须提供关键词字段它是仓库级关键词索引的数据源。tools/check/README.md 中还列出了 CI 集成入口format-check.yml运行check_docs.py与check_images.pygenerate-index.yml在索引更新后运行generate_keywords.py即这套自检在本地与 CI 双端执行同一份脚本。9. 提交前检查清单把规范浓缩为可执行清单新增一篇mds/叶子文档时逐项核对文件名符合{模块号}.{子号}.{序号}.{中文主题名}.md编号为半角数字点号、段间无空格文件放在与编号一致的模块目录下如mds/2.技术能力/目录名与模块入口同名文档以## 标题p简介开头含**关键词:**与**标签:**字段标签四要素等级/阶段/分类/角色完整且分类与六大模块一致长正文按##领域分组37 个→###知识主题每组 28 个组织超过 450 行先补分组单主题超 250300 行考虑拆分图谱图使用../../exports/{同前缀}.png相对路径不加?rawtrue模块内与配套资源链接均使用相对路径需要站点消费元数据时才添加 YAML Front Matter并与正文标签语义一致本地运行python tools/check/check_docs.py与python tools/check/check_images.py确认 0 error 后提交。更多资料链接说明docs/文档命名规范.md本文规范原文docs/知识结构分层规范.md六大能力模块判定标准与边界CONTRIBUTING.md贡献流程、Markdown 格式与 PR 规范template/z.模板.md叶子文档标准模板tools/config.yaml检查脚本统一配置tools/check/README.md文档与图片检查工具说明docs/内容审核清单.md内容审核配套清单【免费下载链接】GameDevMind最全面的游戏开发技术图谱(Game Development Map)。帮助游戏开发者们在已知问题上节省时间省出更多的精力投入到更有创造性的工作中去。项目地址: https://gitcode.com/GitHub_Trending/ga/GameDevMind创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考