文档维护与同步检查
1. 背景与目标
现有 Markdown 与源码同仓维护，经 MkDocs 严格构建后由 GitHub Actions 发布到 Pages。用户已授权优化文档维护方式并提交、推送；主题外观与框架迁移留待后续讨论。
本次将用户阅读入口与维护约定分开，缩短 README 中重复的环境安装步骤，明确文档跟随 main，并以独立文档环境检查易失同步的配置和示例。保留原文档路径、历史内容与已有链接，不改语音服务行为。
2. 设计与取舍
- 用户首页按首次使用、任务操作、接口查询、原理理解组织；维护入口集中贡献、翻译、Spec、日志与历史资料。旧多语言维护锚点保留链接兼容，当前规则仅维护一份。
- README 保留已准备环境下的启动和首次调用，完整安装只在双语快速开始维护。各页面仍为普通 Markdown，在 GitHub 中可直接阅读。
- 网站构建时统一添加 main 开发分支说明，历史资料明确其记录性质；仓库首页和用户索引也用简短说明标明版本。版本发布记录不等于多版本文档，暂不引入版本站点。
- 同步映射集中在 tools/docs/content.toml：限定译文范围，记录源码改动应复核的文档。变更提醒仅供审查，不把“文件被修改”当作语义正确，也不强制无关译文改动。
- 离线检查核对双语配置表与 configs/prod.yaml，并核对字段是否存在于配置类；检查约定范围内 JSON、Python、Shell 示例语法与双语示例一致性，并按简单客户端 argparse 声明核对命令选项。Shell 只执行 bash -n，不执行命令；解析源码时不导入服务、不加载模型。
- 文档工作流增加相关源码、配置和示例触发，获取比较基线，运行内容检查、检查器回归用例、严格构建与网页检查。PR 只验证，main 验证后继续自动发布。
- 生成 HTML 不提交。文档依赖仍与服务隔离，不扩张为通用文档框架；不自动翻译、不新增 GPU 验收结论。
3. 实施步骤
- 整理双语入口、维护指南与导航，保留历史锚点。
- 添加版本提示、同步映射和内容检查，接入本地命令与 CI。
- 用错误配置、错误示例和单侧翻译变更验证检查与提醒边界；检查全站链接及历史内容保护。
- 更新当前设计、贡献说明和当日日志，提交、推送并确认 Pages 工作流完成。
4. 验收标准
- 双语首页有明确的阅读入口和 main 版本说明；维护规则有唯一入口，旧链接可达。
- README 的首次调用仍完整，安装步骤指向快速开始；中英文示例一致。
- 配置值或字段错误、示例语法错误和双语示例漂移会失败；源码或单侧译文变化给出明确提醒，不错误阻断纯文字变更。
- 验证不加载 Fast-VC 或模型，独立文档环境可完成；全站严格构建、站内链接与 git diff --check 通过。
- 源码、服务依赖、子模块、历史 Spec 正文保持不变；主题和框架不变。
5. 实际验证
5.1 本地验收
- 内容检查通过：9 对中英文文档、54 个机器示例、60 个配置值；简单客户端选项从源码声明离线核对。
- 17 个回归用例通过：生产配置变更、字段删除、JSON 和 Shell/Python heredoc 语法、双语示例漂移、客户端选项删除、单侧译文提醒、代码与文档同改提醒、历史日志隔离、示例不执行及版本提示兼容。
- MkDocs 严格构建通过，生成 56 个 HTML 页面；网页链接、资源、锚点和搜索索引检查通过。保留旧文档索引的六个章节锚点。
- 发现部分历史笔记没有 H1，已让构建时版本提示兼容该格式；所有内容页显示 main 说明，历史页显示日期/版本上下文提示，原始正文未改写。
- 工作流触发范围、完整历史与基线传递、PR 不部署、最小发布权限和无效比较基线拒绝检查通过；git diff --check 通过。
- 服务源码、配置、客户端、素材、根依赖与锁文件、子模块和已有历史 Spec 正文未改动。只更新独立文档环境的直接依赖声明，原 PyYAML 锁定版本保持不变。
- 未运行服务、GPU 推理、音质或压力测试；静态检查不声称示例运行成功，变更提醒不声称译文语义正确。未调整主题样式或更换框架。
5.2 发布验收
实现提交 ad3bb22 已推送到 main，上一轮 README 独立入口提交 6f6799d 一并推送。Actions 运行中的内容与同步检查、17 个回归用例、严格构建、生成网页验证和 Pages 部署全部成功。
中文首页、英文首页、维护入口、维护指南、语音转换 API 和搜索索引共六个线上地址返回 HTTP 200，内容 SHA-256 与该提交的本地构建完全一致。新导航与版本提示通过生成 HTML 验收，本轮未另行执行浏览器视觉或移动端交互验收。
本次文档维护优化已完成。主题与框架形式保留后续讨论，未作为本次任务的实施内容。