VitePress 文档展示与酸橙主题

1. 背景与目标

现有 Markdown 内容职责、双语范围与内容检查继续沿用，将 MkDocs 网站迁移至 VitePress。网站依赖、配置、组件和构建适配统一放在 docs/website；普通作者继续修改原 Markdown，不维护第二份网页正文。

状态：已完成。实现提交 6e76304 已按用户授权推送至 main，GitHub Pages 构建与发布成功，线上验收见第 6.4 节。

2. 展示与内容设计

• 浅色主题采用纸白背景 #F6F7F2、白色内容表面、酸橙按钮 #D9F26F、深绿文字 #252A21 与链接 #627722；暗色主题采用深绿灰表面和同系酸橙强调，分别检查文字与按钮对比度。
• 首页突出开始使用、API 和按任务进入的文档入口，不显示左右目录。教程页采用章节导航、连续正文与页内目录。接口页突出协议流程，并在宽屏将初始化字段与示例并排，窄屏顺序阅读。
• 中文为默认语言；语言切换与主题切换位于工具栏。英文只覆盖已约定的译文；没有译文时提供英文索引入口，不制造空翻译页面。
• 正文 Markdown 为唯一内容来源。首页内容与 API 字段、示例从原文提取或在构建时排版，不在组件中重复维护协议事实。
• 页面展示 main 分支标识；历史记录保留历史提示。不引入稳定版站点、版本切换或在线 API 调试。

3. 构建与兼容

• 使用 VitePress 稳定版及默认主题扩展，Node 依赖在 docs/website 单独锁定；Python 文档检查环境仍在 tools/docs，服务依赖不变。
• VitePress 1.6.4 默认依赖的旧版 Vite 在 npm 审计中存在已知问题，显式覆盖到 Vite 6.4.5，并以构建、预览和依赖审计验证兼容性；保持稳定版 VitePress，不引入 2.0 alpha。
• 构建准备步骤生成被 Git 忽略的临时 Markdown；源文档不移动、不回写。临时目录只是自动生成产物，不是新的维护来源。
• 保留当前目录式网页地址、中文标题锚点及已有 HTML 锚点。根 README、CONTRIBUTING 和英文 README 继续映射为 project、contributing 和 en/project 页面。
• 仓库文档链接转为网页链接；源码、配置和音频指向公开 GitHub。只发布文档与站点资源，不自动复制仓库其他素材。
• 中文与英文使用本地搜索；历史 Spec、每日工程日志、归档和旧性能资料不进入搜索。中文分词与搜索结果需要浏览器验收。
• 保留内容、双语和源码变更提醒；迁移最终网页检查器，检查站内链接、锚点、资源及搜索记录。
• Actions 增加独立的 Node 构建步骤，PR 只验证，main 验证后继续通过现有 Pages artifact 发布。

4. 实施顺序

1. 建立网站工程、内容适配及兼容验证。
2. 实现浅色／暗色主题、首页、教程与 API 布局。
3. 迁移构建检查和工作流，移除替代完成的 MkDocs 配置与依赖。
4. 更新贡献指南、维护说明与当前设计，完成本地构建、链接、搜索和浏览器验证。

5. 验收与边界

验收包括内容检查及回归用例、站点适配回归、生产构建、网页链接与锚点、旧地址兼容、中文与英文搜索、语言切换、浅暗主题切换与持久化、桌面和窄屏阅读、git diff --check。

不执行服务联调、GPU 推理、音质或性能测试。本地验收与线上部署分别记录；未发布时不得标记线上验收完成。

6. 实际验证

6.1 内容与构建

• Python 内容检查通过：9 对文档、54 个机器示例、60 个配置值；内容与网页检查器共 18 个回归用例通过。
• Node 内容适配 9 个回归用例通过，覆盖目录式地址、中文和数字锚点、链接改写、缺失与越界拒绝、协议提取、原文保留、产物清理、搜索范围与导航文案保留。迁移移除 MkDocs 配置、适配钩子及其依赖，Python 环境仅保留检查所需依赖。
• 生产构建生成 56 个文档页面与 404 页面；最终 HTML 本地链接、锚点和资源检查通过。直接读取构建后的中英文搜索索引，验证 236 条记录，不以人工拼接的搜索清单代替真实索引。
• 与迁移前构建基线对比：原有 56 个 HTML 路径及正文锚点全部保留。文档网站设计第 6 节调整标题时保留旧锚点，避免历史 Spec 链接失效。
• 按锁文件执行 npm ci --ignore-scripts 后，回归与生产构建通过，依赖审计为 0 项已知漏洞。VitePress 1.6.4 与 Vite 6.4.5 在 Node.js 24 环境完成构建、开发与生产预览；生产预览明确绑定本机地址。git diff --check 通过。

6.2 浏览器与配色

• Chrome 本机生产预览：酸橙浅色、暗色、主题切换及刷新后保留选择通过；中文搜索“语音转换”可跳转 API，英文搜索 opus_frame_duration 包含初始化参数与简单协议字段。
• 中英文语音转换页互相切换到对应页面；没有英文译文的设计页进入英文索引。教程使用左侧章节导航和右侧页内目录，API 使用协议入口与并排字段／JSON 示例，复制按钮返回成功状态。
• 390 × 844 视口检查手机 API、教程、导航抽屉、章节跳转和主题切换。字段与示例自动堆叠，页面无横向溢出；长命令在代码块内部滚动。
• 开发入口实测启动于本机；修改原 Markdown 后，浏览器无需手动刷新即可看到新内容。测试页面无浏览器警告或错误。
• 按 sRGB 相对亮度计算，浅色正文／白底对比度 14.67:1，辅助文字 5.83:1，链接／纸白底 4.66:1，酸橙按钮文字 10.59:1；暗色正文 14.96:1，辅助文字 8.85:1，链接 13.88:1。这是主要配色检查，不表示已完成全面无障碍审计。

6.3 边界与后续发布

服务源码、服务依赖及子模块未修改；未执行服务联调、GPU 推理、音质或性能测试。工作流已迁移为独立 Node 构建与 Python 检查。本地验收时尚未运行云端 Actions，后续实际发布情况记录如下。

6.4 发布验收

2026-11-02，按用户授权提交并推送实现提交 6e76304。文档构建与发布工作流的构建和 GitHub Pages 部署均成功。

线上中文与英文首页、中文快速开始、双语语音转换 API、页面清单及搜索记录均返回 HTTP 200；首页引用的 CSS、图标与 JavaScript 资源也均可读取。五个 HTML 页面除构建资源文件名的哈希外，与本地验收产物一致；CSS 与图标内容哈希相同，页面清单一致，实际搜索记录集合一致，共 236 条。中英文搜索、主题切换、移动端与复制功能的交互验收沿用第 6.2 节本地结果，本轮未重复执行线上浏览器验收。