文档网站
1. 内容与构建职责
网站使用 VitePress，发布到 GitHub Pages。Markdown 是唯一正文来源；网站工程集中在 docs/website，中文文档位于 docs/zh，英文文档位于 docs/en，根项目首页与贡献指南保持原位置。
网站使用独立的 Node.js 24 环境和 package-lock.json。Python 文档工具及其 uv.lock 只负责内容与网页检查。构建不导入语音服务，不加载模型，也不要求安装 CUDA 或初始化子模块；服务根目录的依赖与锁文件不变。
首页任务表由 Markdown 转为任务入口，首页不显示侧栏；教程页提供章节导航、正文与页内目录；语音转换页从原文的 JSON 示例和字段表提取协议展示，宽屏并排阅读、窄屏顺序排列。酸橙浅色与暗色主题共用布局，浏览器记住主题选择；字体使用系统字体，不请求外部字体服务。
导航与浏览器页签使用已选定的深绿白波形图标 A；导航以 40 CSS px 展示 128 px PNG，页签使用包含 16/32/48 px 的 ICO。中英文项目首页共用酸橙流动横版封面 D，正式素材及来源见品牌资产说明。
中文为默认语言，英文只覆盖维护约定中的译文范围。工具栏语言入口优先切换对应页，未翻译页面进入英文索引。中文和英文使用独立的本地搜索索引，支持中文分词；Spec、每日工程日志、历史归档和评测报告正文不参与搜索，评测指南与报告索引可检索。
在线文档跟随 main。网页以紧凑标识链接 GitHub Releases；历史页面额外注明记录性质。使用发布版本时从对应标签阅读 Markdown，当前没有稳定版网站或版本下拉切换。
2. 本地预览与验证
安装 Node.js 24 和 uv 后，在仓库根目录执行：
npm --prefix docs/website ci --ignore-scripts
npm --prefix docs/website run dev按终端显示的网址预览；默认仅监听本机 18127 端口，使用 /fast-vc-service/ 项目路径。开发入口监视正文、根 README 和 CONTRIBUTING 的变化，重新生成临时内容并触发页面更新。
完整验证命令：
uv run --project tools/docs --python 3.12 --locked python tools/docs/check_content.py
uv run --project tools/docs --locked python -m unittest discover -s tools/docs -p 'test_*.py'
npm --prefix docs/website test
npm --prefix docs/website run build
uv run --project tools/docs --locked python tools/docs/check_site.py
git diff --check查看生产构建结果：
npm --prefix docs/website run preview生产预览使用 Vite，仅监听 127.0.0.1:18127；开发与生产预览同时运行时，端口以终端输出为准。重新构建后刷新页面即可读取新产物。
生成网页放在被 Git 忽略的 site/。生产构建检查页面链接；网页检查补充最终 HTML 的站内链接、锚点、资源、页面清单和实际搜索记录，不联网检查外部网站。
内容检查器保留源码 AST、配置表、示例语法、客户端选项和双语机器示例检查，不导入服务或执行示例。用 --base origin/main 检查已提交、暂存、未暂存和未跟踪变更中的源码影响与单侧翻译提醒。提醒不等于语义验证，仍需人工审阅。
3. 路径与链接适配
内容准备脚本读取根 README、CONTRIBUTING 及 docs/zh、docs/en 中的 Markdown，在被忽略的 docs/website/.generated/ 生成临时页面。该目录可重新生成，不是另一套手工维护的正文。docs/README.md 仅作为仓库语言入口，不参与网页生成；docs/website 不作为正文来源。
| 来源 | 网页地址 |
|---|---|
| 根 README.md | project/ |
| 根 CONTRIBUTING.md | contributing/ |
| docs/zh/README.md | 网站首页 |
| docs/en/README.md | en/project/ |
| docs/en/index.md | en/ |
| docs/zh/api/voice-conversion.md | api/voice-conversion/ |
| docs/zh/evaluation/reports/README.md | evaluation/reports/ |
| docs/en/changelog/releases.md | changelog/releases_en/（保留既有地址） |
评测报告统一位于 evaluation/reports，按时间组织目录；网页使用对应目录式地址，报告正文显示历史记录提示并保留原标题格式。
中文来源去掉 docs/zh 前缀后生成原有目录式地址，不增加 zh/ 网页层级；英文沿用 en/，英文版本历史单独映射到既有地址。数字、中文标题及显式 HTML 锚点保持兼容。源码路径变化时同步翻译映射、源码复核映射、首页识别及历史/搜索规则；导航继续引用公开网址，查看 Markdown 的入口指向迁移后的 GitHub 路径。
本次目录迁移保留所有既有网站地址；GitHub main 中旧文件路径随迁移改变，历史提交与标签仍保留旧目录。迁移方案与逐页路径验收见文档目录迁移 Spec。
Markdown 适配根据原文件位置解析链接。已发布的 Markdown 指向网页；源码、配置和音频等指向 GitHub main；普通图片使用公开 raw 地址。题图、导航图标与 favicon 三项正式品牌资源例外：内容准备步骤从仓库复制到临时目录的 public/brand，VitePress 随站发布到项目路径下的 brand/，相关链接使用站内路径。原生 HTML 的 href/src 同样处理，代码块不改写。缺失或越出仓库的相对链接使构建失败。
仅文档、主题资源与生成的检查清单进入 site/；不会自动复制音频、模型、会话记录或其他仓库文件。新增素材按仓库公开内容规则核对。
4. 自动构建与发布
GitHub Actions 工作流执行以下步骤：
- 检出完整历史，准备独立的 Python 文档检查环境。
- 检查文档内容、翻译提醒与检查器回归。
- 使用 Node.js 24，按网站锁文件安装依赖，执行内容适配回归。
- 构建静态网页，读取真实中英文搜索索引并验证最终链接、锚点和资源。
- main 验证通过后上传 site/，由现有 GitHub Pages 部署任务发布；PR 只验证。
触发范围包含文档、网站工程、文档工具、协作规则、assets 中的素材，以及需要复核文档的服务源码、配置、WebSocket 示例和服务依赖声明。比较基线来自 PR 目标分支或 push 前的提交；手动运行不提供基线时只检查当前内容。
构建任务只读仓库；部署任务持有 pages: write 和 id-token: write，遵循 github-pages 环境规则。发布使用 Pages artifact，不提交生成 HTML，也不创建 gh-pages 分支。
Pages 的发布来源为 GitHub Actions，网站地址保持不变。只有云端工作流成功且线上页面验收通过，才记录为已上线；本地构建不等于部署完成。
5. 故障排查与验证边界
- 内容或双语检查失败：核对真实源码、prod.yaml 和原文，不为通过文档检查改变服务默认值。
- 相对链接或锚点失败：检查原 Markdown 的位置、目标与标题；不要关闭链接检查。
- 新页面未进入目录：修改导航配置；历史记录可以链接访问，但不必加入用户导航。
- 页面或资源 404：核对项目路径、目录式网页映射和 site/ 发布产物。
- 中文搜索失效：检查中英文索引是否生成、中文分词函数与浏览器加载结果。索引从原文提取，不能因展示组件丢失字段说明。
- 开发预览没有更新：确认使用 run dev 监视原文；run preview 只读取上一次生产构建。
本地构建、网页检查、浏览器验收与线上部署分别记录。上述检查不代表服务联调、GPU 推理、音质或性能测试。
6. 维护方式与依赖
日常修改正文只编辑原 Markdown；新增页面按需补充导航、翻译映射和相关入口。调整颜色或布局修改网站主题；协议字段和示例仍从原文提取，不写入 Vue 组件。
VitePress 使用稳定版 1.6.4，显式将其 Vite 构建依赖覆盖到 6.4.5，以处理旧依赖的已知审计问题。升级时一起检查覆盖项是否仍需要，重新执行构建、搜索、网页和浏览器验收。Node 依赖通过 npm 更新并提交 package.json 与 package-lock.json；Python 工具依赖通过 uv 更新声明和锁文件，不手工改锁。
迁移记录及实际验收见 VitePress 展示与酸橙主题 Spec。