`homemade-risc-v-64-vector-linux-emulator` MkDocs 双语文档站点 PRD¶

1. 文档目的¶

本文件定义 homemade-risc-v-64-vector-linux-emulator 的 MkDocs 文档站点建设要求，是后续实现、审查和验收文档站点的权威依据。

目标是把仓库根目录和 specs/ 中的权威工程文档，以相对符号链接接入一个结构一致、支持中英双语、可自动部署的文档站点，同时避免复制内容形成多套事实来源。

本 PRD 仅面向当前 RISC-V 全系统模拟器项目。其他仓库可以参考其结构，但不得以“通用性”为理由削弱本项目的导航、规格追踪或 symlink 约束。

2. 建设目标¶

需要建设一套独立的文档站点方案，满足以下要求：

使用 MkDocs 作为文档站点框架。
使用 i18n 方案支持中英双语。
文档站点独立放置在 docs-site/ 目录下。
文档入口按 docs-site/docs/zh/ 和 docs-site/docs/en/ 分别组织。
中文入口文件名使用 .zh.md 后缀，英文入口文件名使用 .en.md 后缀。
站点入口 Markdown 必须使用相对 symlink 指向仓库中的权威文档，不复制正文。
导航结构在中英文之间尽量保持一致。
页面顶部提供明确的“简体中文 / English”语言切换入口。
左侧目录按模拟器架构、CPU、ISA、RVV、MMU、总线、设备、VirtIO、引导、测试和任务组织。
提供可用于自动构建和部署的 GitHub Actions 工作流。
整体结构应具备通用性，便于迁移到其他仓库复用。

3. 适用范围¶

本 PRD 适用于以下本项目场景：

发布项目概览、免责声明和使用说明。
发布项目宪法、Agent 操作规则与可勾选任务清单。
发布 RV64GCV、Sv39、MMIO、VirtIO 和 Linux 引导规格。
为后续真实实现补充模块设计、维护说明和验证证据。
向中文和英文读者提供结构对应的文档入口。

本 PRD 不负责模拟器代码实现，也不允许文档站点构建流程修改宿主网络、下载 Linux 镜像或改变来宾运行状态。

4. 总体要求¶

4.1 工程独立性¶

文档站点必须作为独立工程存在于 docs-site/ 中。
文档相关配置、页面、资源和构建逻辑应尽量收敛在该目录内。
不应把文档站点实现分散到仓库多个无关位置。
应尽量减少对主项目目录结构的侵入。
GitHub Pages 工作流因平台约束必须位于 .github/workflows/，这是唯一允许放在 docs-site/ 外的站点工程文件。

4.2 双语一致性¶

必须同时支持中文和英文。
中文和英文文档应采用平行结构组织。
相同主题的页面在中英文中应尽量一一对应。
导航、栏目、层级和命名语义应保持一致。
不允许只完成单语结构后再以临时补丁方式拼接另一种语言。
中文文档是当前权威基线；英文页面必须来自真实英文权威文档，禁止把中文 symlink 放进 en/ 后声称完成翻译。
某个英文主题尚未翻译时，应在任务中保持未完成，并从英文导航中明确缺失，不得生成空白页或机器占位文本。

4.3 技术统一性¶

文档框架统一使用 MkDocs。
多语言实现统一采用 i18n 方式。
方案应优先选择成熟、主流、可维护的插件与配置方式。
避免引入与核心目标无关的复杂工程化定制。
主题采用维护活跃且支持顶部语言切换、左侧导航、搜索和响应式布局的 MkDocs Material。
i18n 采用与所锁定 MkDocs/Material 版本兼容的成熟插件，依赖必须在 docs-site/requirements.lock 中精确锁定。

4.5 固定目录结构¶

docs-site/
├── mkdocs.yml
├── requirements.lock
├── README.md
├── specs/
│   ├── mkdocs_prd.zh.md
│   └── github_action_prd.zh.md
├── docs/
│   ├── zh/                 # 只保存指向中文权威文档的相对 symlink
│   └── en/                 # 只保存指向英文权威文档的相对 symlink
├── overrides/
└── assets/

site/ 是本地构建产物，必须被 Git 忽略。任何 symlink 的解析目标都必须仍在仓库根目录内，禁止链接到用户目录或宿主机其他位置。

4.4 自动化要求¶

应提供标准的自动化构建与部署流程。
自动化流程应适用于 GitHub 仓库。
至少支持通过 GitHub Actions 完成文档构建和静态站点部署。
部署目标优先兼容 GitHub Pages。

5. 推荐信息架构原则¶

左侧导航固定按以下信息架构组织：

首页：项目定位、免责声明、当前实现状态和规格入口。
项目治理：AGENTS.md、项目宪法、标准基线、项目树和任务清单。
总体架构：产品总览、模块边界和实施路线图。
CPU 与 ISA：寄存器、特权态、CSR、标量指令和 Trap。
向量引擎：RVV 1.0 状态、指令和异常重启。
内存系统：物理总线、RAM/ROM、Sv39、TLB 和原子 A/D 更新。
外设：CLINT、PLIC、UART、VirtIO 公共层、块设备和网卡。
系统集成：OpenSBI、Linux、CLI、宿主 TAP 和生命周期。
质量保证：测试、编码规范、产物策略和真实验收。
文档站 PRD：本文件与 GitHub Actions PRD。

说明：

导航反映权威规格语义，而不是机械照搬文件目录。
新模块必须在对应分类下补充，不得另建相互竞争的导航体系。
不允许用占位页面冒充未完成内容；缺失页面保持未完成任务状态。

6. 内容组织要求¶

6.1 语言分层¶

站点入口按语言拆分，但正文权威来源仍位于站点目录之外的既有文档位置。
中文和英文分别拥有独立的内容入口。
每种语言均应具备独立首页。
每种语言均应具备对应的导航结构。
docs-site/docs/zh/ 与 docs-site/docs/en/ 下的 Markdown 必须是相对 symlink，不得复制源文件。

6.2 页面命名原则¶

页面命名应清晰、稳定、可预测。
同一主题的中文和英文页面应保持语义对应。
命名应优先表达文档用途，而不是使用随意缩写。
中文入口以 .zh.md 结尾，英文入口以 .en.md 结尾。
symlink 名称变化必须同步更新 MkDocs 导航和链接检查。

6.3 导航原则¶

导航应反映内容结构，而不是仅反映文件存放位置。
首页、入门、用户指南、专题内容、项目说明、PRD 内容等应有清晰分组。
导航层级不宜过深。
中英文导航结构应尽量镜像一致。

6.4 缺失内容与扩展¶

不允许用占位页、空翻译或自动生成的无审查文本冒充完成。
某语言页面缺失时，必须在 specs/tasks.md 的文档站任务中保持未勾选。
后续扩展优先补充既有分类，不频繁重构稳定 URL。

6.5 Symlink 完整性¶

所有链接必须使用从 symlink 所在目录计算的相对目标。
禁止绝对 symlink，禁止目标解析到仓库外，禁止循环和失效链接。
源文档重命名时必须在同一变更中更新 symlink、导航和交叉引用。
本地构建和 CI 必须在 MkDocs 启动前验证全部 symlink。

7. 配置要求¶

7.1 MkDocs 配置¶

实现方案中应包含完整的 MkDocs 配置，至少应覆盖：

站点基础信息
仓库 URL 与 GitHub Pages site_url
主题配置
导航配置
多语言配置
Markdown 扩展配置
插件配置
静态资源配置

7.2 i18n 配置¶

多语言方案必须满足以下要求：

明确声明支持的语言集合。
明确默认语言。
明确不同语言页面的映射关系或组织方式。
能支持中文与英文切换。
能支持未来继续扩展更多语言，而无需推翻现有结构。
默认语言为简体中文，英文为第二语言；顶部语言选择器必须在对应页面间切换。

7.3 可读性要求¶

配置文件应结构清晰，分段合理。
命名和注释应便于维护者理解。
不应把关键逻辑隐藏在难以追踪的脚本拼装中。

8. 自动化与部署要求¶

8.1 GitHub Actions¶

必须提供文档站点自动化工作流，至少包括：

检出仓库代码
安装构建依赖
构建 MkDocs 站点
部署生成后的静态文件

8.2 工作流质量要求¶

工作流应尽量简单、稳定、可维护。
命名应清晰，便于团队成员理解用途。
不应为了追求复杂能力而显著增加维护成本。
应优先采用 GitHub 官方或社区稳定方案。

8.3 部署目标¶

优先面向 GitHub Pages。
若后续迁移到其他静态托管平台，结构上也应尽量兼容。
部署方案应尽量减少与业务运行环境的耦合。

9. 非功能要求¶

9.1 通用性¶

配置应服务当前模拟器项目的真实信息架构。
公共构建逻辑可以保持简洁可迁移，但不得因此删除项目专有导航和规格追踪。

9.2 可维护性¶

新成员应能快速理解文档工程组织方式。
后续新增页面时，不应频繁改动核心结构。
中英文内容维护方式应清晰明确。

9.3 一致性¶

中英文结构一致。
页面风格一致。
配置风格一致。
自动化流程命名与职责一致。

9.4 可扩展性¶

允许未来增加新栏目。
允许未来增加更多语言。
允许未来增强主题、搜索、SEO、版本化等能力。
但本次实现不要求一次性覆盖所有高级功能。

10. 交付物要求¶

执行该 PRD 时，至少应交付以下内容：

docs-site/ 文档工程目录
MkDocs 主配置文件
支持 i18n 的多语言配置
中文文档入口页
英文文档入口页
指向现有权威 Markdown 的相对 symlink 页面
中文 .zh.md 与英文 .en.md 命名规则
静态资源目录
GitHub Actions 工作流文件
简要维护说明

11. 验收标准¶

满足以下条件时，视为该任务完成：

仓库中存在独立的 docs-site/ 文档站点工程。
文档站点基于 MkDocs 构建。
文档站点支持中文与英文两种语言。
多语言实现基于 i18n 方案，而非手工复制拼装。
中英文首页均来自真实权威文档，可作为独立入口使用。
中英文导航结构基本一致。
站点可通过 GitHub Actions 自动构建。
站点可通过 GitHub Actions 自动部署到 GitHub Pages 或兼容静态托管目标。
目录、配置和内容组织方式具备复用价值。
其他 AI 或开发者可基于该结构继续扩展，而无需重新设计底层方案。
所有站点 Markdown 入口均为仓库内相对 symlink，无复制正文、绝对链接、失效目标或越界目标。
顶部语言切换和左侧项目导航在桌面与移动布局均可使用。

12. 实施约束¶

执行者在实现时应遵守以下约束：

不要把项目专有规格简化成与当前仓库无关的通用占位模板。
不要复制 README.md、AGENTS.md 或 specs/ 正文到站点目录。
不要省略双语结构设计。
不要只完成页面文件而缺少自动化部署能力。
不要把目录结构设计成依赖执行者个人习惯才能理解。
不要引入明显超出需求范围的复杂系统。

13. 对执行者的明确指令¶

请基于本 PRD，为目标仓库设计并实现一套标准化文档站点方案。实现要求如下：

使用 MkDocs
使用 i18n 支持中英双语
所有文档站点相关内容放置于 docs-site/
使用相对 symlink 接入项目权威 Markdown
中文入口使用 .zh.md，英文入口使用 .en.md
顶部提供语言切换，左侧提供完整项目目录
输出结构清晰、可维护、可迁移
提供基础导航和占位页面
提供 GitHub Actions 自动构建与部署流程
优先兼容 GitHub Pages
尽量保持实现简单、稳定、通用

14. 期望结果¶

最终应得到一套服务本项目、支持中英双语、以 symlink 保持单一事实来源、可自动部署且适合长期维护的 MkDocs 文档站点。

该骨架应满足以下目的：

当前仓库可直接使用
未来可持续扩展
可作为其他仓库的模板
可作为其他 AI 的统一执行输入
尽量减少不同执行者之间的结果偏差

homemade-risc-v-64-vector-linux-emulator MkDocs 双语文档站点 PRD¶