跳转至

mcts-cpu-validate Markdown 树与 symlink 规划

1. 目的

本文件列出 docs-site 建设过程中会涉及的 Markdown 文件。

它回答两个问题：

  1. 哪些 Markdown 是新写的。
  2. 哪些 Markdown 不重写，而是通过 symlink 接入文档站。

这样做的原因很直接：这个项目要求 DRY。只要某个 Markdown 已经是权威来源，就不应该在文档站里再复制出第二份。

2. 约定

2.1 文件命名

  • 中文文件使用 .zh.md
  • 英文文件不加语言后缀

2.2 状态标记

  • 直写文件：直接编写或维护内容的文件
  • symlink：不重写内容，只建立符号链接的文件

3. 当前已经存在并已处理的 docs-site 规格文件

3.1 直写文件

  • docs-site/specs/mkdocs_prd.zh.md
  • docs-site/specs/mkdocs_prd.md
  • docs-site/specs/github_action_prd.zh.md
  • docs-site/specs/github_action_prd.md
  • docs-site/specs/md_tree.zh.md
  • docs-site/specs/md_tree.md

这些文件属于文档站自己的规格来源，不是项目训练逻辑 spec。

4. 根目录主 README 规划

4.1 直写文件

  • README.zh.md
  • 来源：由根目录现有 README.md 通过 mv README.md README.zh.md 改名得到

  • 说明：这是项目中文主 README，不重写历史内容来源

  • README.md

  • 说明：新增英文版主 README，作为 GitHub 仓库默认展示页

5. docs-site/docs 下计划新增的解释性页面

5.1 中文直写文件

  • docs-site/docs/zh/index.zh.md
  • 作用：中文首页
  • docs-site/docs/zh/project-overview.zh.md
  • 作用：解释项目是什么、为什么不是标准围棋引擎、核心闭环是什么
  • docs-site/docs/zh/training-loop.zh.md
  • 作用：解释 Rust、Python、MCTS、自博弈、训练之间如何衔接
  • docs-site/docs/zh/data-and-recovery.zh.md
  • 作用：解释 run 目录、checkpoint、棋谱、metrics 的输入输出与正常结果
  • docs-site/docs/zh/developer-notes.zh.md
  • 作用：给开发维护者说明文档边界、DRY 原则、specs 与 docs-site 的分工
  • docs-site/docs/zh/docs-specs.zh.md
  • 作用：作为文档站规格页入口，说明 PRD 和 md tree 在哪里

5.2 英文直写文件

  • docs-site/docs/en/index.md
  • 作用：English home page
  • docs-site/docs/en/project-overview.md
  • 作用：Explain what the project is and what the simplified rules are for
  • docs-site/docs/en/training-loop.md
  • 作用：Explain the Rust/Python/MCTS/training pipeline
  • docs-site/docs/en/data-and-recovery.md
  • 作用：Explain run outputs, checkpoints, records, and recovery
  • docs-site/docs/en/developer-notes.md
  • 作用：Explain docs boundaries and maintainer-facing rules in lighter English form
  • docs-site/docs/en/docs-specs.md
  • 作用：Entry page for docs-site specifications
  • docs-site/docs/en/configuration.md
  • 作用：作为英文配置入口页，解释配置在本项目里的职责，并指向中文权威源文件
  • docs-site/docs/en/step-by-step-guide.md
  • 作用：作为英文操作入口页，解释运行路径，并指向中文权威源文件
  • docs-site/docs/en/data-readme.md
  • 作用：作为英文数据目录入口页，解释 run 目录职责，并指向中文权威源文件

下面这些文件是已经存在的权威来源，文档站不应复制内容，而应建立 symlink。

  • README.zh.md -> docs-site/docs/zh/readme.zh.md
  • CONFIGURATION.md -> docs-site/docs/zh/configuration.zh.md
  • STEP_BY_STEP_GUIDE.md -> docs-site/docs/zh/step-by-step-guide.zh.md
  • data/README.md -> docs-site/docs/zh/data-readme.zh.md
  • docs-site/specs/mkdocs_prd.zh.md -> docs-site/docs/zh/specs/mkdocs-prd.zh.md
  • docs-site/specs/github_action_prd.zh.md -> docs-site/docs/zh/specs/github-action-prd.zh.md
  • docs-site/specs/md_tree.zh.md -> docs-site/docs/zh/specs/md-tree.zh.md
  • README.md -> docs-site/docs/en/readme.md
  • docs-site/specs/mkdocs_prd.md -> docs-site/docs/en/specs/mkdocs-prd.md
  • docs-site/specs/github_action_prd.md -> docs-site/docs/en/specs/github-action-prd.md
  • docs-site/specs/md_tree.md -> docs-site/docs/en/specs/md-tree.md

7. 为什么英文侧有“入口页 + 中文权威源文件”的组合

CONFIGURATION.md、STEP_BY_STEP_GUIDE.md 和 data/README.md 目前仓库里只有中文权威源文件。

文档站最终要求是每个文档主题都有中英文入口。这里的处理边界是：

  1. 英文首页和解释性页面要存在。
  2. 如果某个权威原文目前只有中文，英文侧先提供解释性入口页，说明这份文档在项目里负责什么。
  3. 后续若需要完整英文权威版，再新增英文源文件，并把入口页替换成英文权威源文件或对应 symlink。

也就是说，英文侧这里不是复制中文源文件，而是用“英文解释页 + 中文权威源文件”保持 DRY 和双语入口。

8. 本轮不会修改的 Markdown

  • specs/*.md

这些文件只读，不进入本轮修改范围。

9. 执行顺序

建议执行顺序如下：

  1. 完成 README.md -> README.zh.md 改名，并新增英文 README.md
  2. 创建 docs-site 的中英文解释性页面
  3. 创建所有 symlink
  4. 配置 MkDocs 导航，把所有页面纳入导航
  5. 为 GitHub Pages 增加部署工作流

10. 验收方式

如果下面三件事同时成立，说明 Markdown 树基本正确：

  1. 直写文件 和 symlink 文件职责清楚，没有重复来源。
  2. 每个文档主题在中英文导航里都能找到入口。
  3. symlink 都能明确看出“源文件”和“终点文件”。