mcts-cpu-validate 文档站点 PRD¶

1. 目的¶

本 PRD 用来约束 mcts-cpu-validate 的 docs-site/ 文档站建设方式。

这个项目已经有一套面向开发实现的 specs/，但它们不是给第一次接触项目的人直接阅读的入口。docs-site/ 要解决的是另一件事：把项目目标、运行边界、规则简化、数据流、目录职责、训练恢复方式和文档站本身的维护方式解释清楚，让读者先能判断“这个项目到底在做什么”，再去读细节 spec。

这里的重点不是做一个好看的站，而是做一个能解释项目、能长期维护、且不会复制一堆 Markdown 的站。

2. 项目背景¶

mcts-cpu-validate 不是标准围棋引擎，也不是单纯的神经网络训练模板。它是一个围绕 15x15 简化围棋式规则构建的实验系统，目标是把下面几件事接起来：

Rust 侧负责规则、bitboard、MCTS、自博弈和棋谱记录。
Python 侧负责训练、checkpoint、metrics、硬件选择和恢复流程。
所有运行数据都要进入 data/runs/<run_id>/。
整个系统要支持长期运行、中断恢复、结果复查和工具渲染。

文档站必须把这条主线讲清楚。不能只列文件名，也不能只堆术语。

3. 本次建设目标¶

本次 docs-site/ 需要满足下面这些目标：

使用标准 MkDocs 结构。
启用 i18n，支持中文和英文切换。
中文文档放在 docs-site/docs/zh/，英文文档放在 docs-site/docs/en/。
所有进入站点的文档都必须进入 MkDocs 导航，不能存在“文件在目录里但导航没有入口”的情况。
顶部导航栏必须包含 GitHub 仓库链接。
文档内容遵守 DRY，优先通过 symlink 接入仓库已有 Markdown，不复制已有内容。
每个站内文档主题都要有中英文入口；中文使用 .zh.md，英文不加语言后缀。
根目录 README.md 改名为 README.zh.md 后，文档站应把它作为中文入口文档之一。
文档站需要明确区分三类内容：项目说明、开发者说明、文档站自身规格。
根目录中文主 README 必须通过 mv README.md README.zh.md 改名，不允许复制旧内容再伪装成改名。
除明确要求使用 mv 的改名操作外，其他文件修改都必须使用 patch 增量修改，不允许整文件重写。
docs-site/site/ 这类编译产物不能删除，同时需要加入 .gitignore。

4. 不要做什么¶

本次文档站不负责下面这些事情：

不修改 specs/ 原始内容。
不把 specs/ 改写成营销式说明。
不复制整套 specs/ 到 docs-site/ 里形成第二份真相来源。
不改动项目代码逻辑。
不引入与文档站无关的复杂前端定制。
不把构建产物 docs-site/site/ 当作源码文档去维护。

5. 目标读者¶

文档站面向三类读者：

5.1 第一次进入仓库的人¶

他们需要先知道：

这是什么项目。
为什么不是标准围棋引擎。
Rust 和 Python 各负责什么。
数据产物会落到哪里。
读完哪些文档后能开始理解项目。

5.2 运行项目的人¶

他们需要知道：

该看哪个入口文档。
配置文件控制什么。
训练和恢复的输入输出是什么。
如何判断一次运行是否正常。

5.3 开发维护者¶

他们需要一块中文开发者说明区域，用来解释：

specs/ 是实现宪法，但不是用户入口。
目录职责怎么划分。
为什么文档站不能复制已有 Markdown。
新文档应该放哪里，如何接入导航，如何保持双语结构。

这块内容主要服务中文读者，英文只需要说明存在这类开发者约束，并指向对等页面或简化说明。

6. 信息架构要求¶

文档站的信息架构必须围绕项目主线组织，而不是只按文件名平铺。

推荐一级栏目如下：

首页
项目概览
运行与配置
数据与恢复
开发者说明
文档站规格

6.1 首页¶

首页要回答五个问题：

这个项目是什么。
它解决什么问题。
为什么采用 Rust + Python 双栈。
文档站和根目录文档如何分工。
下一步应该读哪几篇文档。

6.2 项目概览¶

这一栏要把规则简化、训练闭环、MCTS 角色、数据记录目的讲明白。每个技术点都要写清楚：

它是什么。
为什么项目需要它。
它在本项目里承担什么边界。
输入输出是什么。
看到什么结果算正常。

6.3 运行与配置¶

这里要承接根目录 STEP_BY_STEP_GUIDE 和 CONFIGURATION，但不能复制内容。更合理的做法是：

站内提供解释性页面，说明这些文档各自负责什么。
通过 symlink 把原文接入站点。
在站内补充“读者该怎么用这些文档”的解释，而不是重复原文。

6.4 数据与恢复¶

这里要解释：

为什么所有产物必须进入 data/runs/<run_id>/。
一个 run 目录里有哪些核心文件。
checkpoint、棋谱、metrics 分别解决什么问题。
当运行正常时，读者应该看到哪些输出。

6.5 开发者说明¶

这里是给维护者看的中文说明区，不是项目根目录文档，也不是 specs/ 的替代品。它应该解释：

文档站为什么必须 DRY。
哪些文档用 symlink，哪些文档必须新写。
为什么 specs/ 不做英文同步改写。
新增页面时如何保持中英文导航稳定。

6.6 文档站规格¶

把本文档和 GitHub Actions PRD 放在这一栏，作为 docs-site/ 自己的规格来源。它们说明的是文档工程怎么搭，不是项目训练逻辑怎么实现。

7. 文档来源策略¶

文档来源必须先分流，再接入导航：

7.1 直接复用的文档¶

下面这些现有 Markdown 应优先通过 symlink 接入站点，而不是复制：

根目录 README.zh.md
根目录英文 README.md
CONFIGURATION.md
STEP_BY_STEP_GUIDE.md
data/README.md

原因很简单：这些文件本来就是权威来源。文档站应该做导航和解释，不应该制造第二份内容。

如果某个文档源文件位于 docs-site/ 之外，仍然优先通过 symlink 接入，而不是复制到 docs-site/docs/ 里再维护一份。

7.2 站内新增的文档¶

下面这些内容应直接写在 docs-site/docs/ 下：

首页
项目概览页
规则与训练闭环解释页
数据目录与恢复解释页
开发者说明页
文档站规格导读页

这些页面的职责是解释，不是复制现成文本。

7.3 不进入复制链条的内容¶

specs/ 目录可以被文档站解释、引用、链接，但不应在 docs-site/ 里复制出一份平行版本。中文维护者说明中可以告诉读者先读哪些 spec、这些 spec 各自负责什么。

8. 双语要求¶

8.1 语言目录¶

必须使用下面的目录：

docs-site/docs/zh/
docs-site/docs/en/

8.2 文件命名¶

中文页面使用 .zh.md
英文页面不加语言后缀

例如：

index.zh.md
index.md
readme.zh.md
readme.md

8.3 双语一致性¶

这里的一致性不是要求每一段都逐字镜像，而是要求：

导航结构一致。
同一主题两种语言都能找到入口。
英文页至少能说明页面职责、适用对象和关键跳转。
每个进入站点导航的文档主题都必须同时有中文页和英文页，不能只留单语入口。

对于明显只服务中文开发维护者的细节，英文可以写成简化版本，但不能完全缺页。

9. MkDocs 与 i18n 要求¶

9.1 框架¶

使用标准 MkDocs 工程结构。

9.2 多语言¶

使用成熟的 i18n 插件，实现真实的语言切换开关，而不是两套互不相连的站。

9.3 导航¶

所有文档都必须出现在导航中，包括：

首页
解释性页面
通过 symlink 接入的已有 Markdown
文档站 PRD

9.4 GitHub 导航项¶

顶部导航栏必须包含：

GitHub 仓库链接：https://github.com/billzi2016/mcts-cpu-validate

文档中也要出现文档站链接：

https://billzi2016.github.io/mcts-cpu-validate/

10. GitHub Pages 部署边界¶

本项目文档站默认部署到：

https://billzi2016.github.io/mcts-cpu-validate/

因此文档配置要考虑：

site_url 指向该地址。
GitHub Actions 只在文档相关文件变化时触发。
站点构建输出目录与 Pages 部署兼容。

11. 内容写作要求¶

文档必须像能自己解释自己一样清楚。

写文档前，必须先读取 /Users/bizi/Desktop/humanizer-skill，把其中对 AI 写作痕迹、空话、假热情和术语堆叠的约束落实到文档表达里。

每个重要技术点都要回答：

它是什么。
为什么本项目需要它。
它在本项目里怎么工作。
输入是什么。
输出是什么。
怎样判断结果正常。

不要只抛出术语，例如 “MCTS”“bitboard”“checkpoint 三槽轮转” 然后不解释。读者应该能靠文档知道这些词在本项目里到底意味着什么。

同时，文风要避开下面这些问题：

空话和大话。
连续堆概念名词。
假装热情的介绍语。
明显 AI 腔的夸大表述。
只写“做了什么”，不写“为什么这样做”。
暴露写作意图的词，例如“科普”“HR”“面试”。

如果某段内容主要用于解释原理、边界、输入输出或结果判断，它应写在 docs-site/docs/ 下，而不是继续把这类解释堆回项目根目录。

12. 验收标准¶

满足下面条件，视为本 PRD 对应建设完成：

docs-site/ 形成可构建的 MkDocs 工程。
中英文语言切换可用。
所有站内文档都进入导航。
现有权威 Markdown 通过 symlink 复用，而不是复制。
中文开发者说明存在，且说明了 specs/、根目录文档和 docs-site/ 的职责边界。
两个主 README 都包含 GitHub Pages 文档站链接。
文档站顶部导航包含 GitHub 仓库链接。
文档内容能解释项目，而不只是罗列文件和术语。

13. 对执行者的明确要求¶

执行本 PRD 时，必须遵守下面这些约束：

不改 specs/。
不写第二份项目真相来源。
优先 symlink，避免复制。
中文开发者说明放在 docs-site/docs/zh/，不要污染项目根目录。
不要为了省事省掉英文入口页。
根目录 README.md 改名必须使用 mv README.md README.zh.md。
除明确要求的 mv README.md README.zh.md 外，其余文件改动使用 patch 增量修改。
不允许整文件重写替代 patch 增量修改。
不删除 docs-site/site/ 这类编译产物目录，同时要把它加入 .gitignore。