文档维护
1. 内容职责与唯一来源
文档与代码在同一仓库维护，在同一次变更中审查。网站由 Markdown 自动构建；不要直接修改生成的 site 目录，也不要另存一份网页正文。
| 内容 | 主要维护位置 | 其他入口的职责 |
|---|---|---|
| 项目用途、运行条件和首次体验 | README.md；英文为 docs/en/README.md | 网站复用原文，不复制文件 |
| 语言导航与用户索引 | docs/README.md；中文索引 docs/zh/README.md；英文索引 docs/en/index.md | 总入口只用于仓库导航，网站首页分别复用两种语言的用户索引 |
| 完整安装与首次调用 | docs/zh/getting-started/quick-start.md | README 保留准备好环境后的最短调用，并链接详细步骤 |
| 配置含义与部署操作 | docs/zh/getting-started/configuration.md | prod.yaml 为示例部署值来源，config.py 为字段和类默认值来源，二者分别说明 |
| 对外字段、消息、错误与时序 | docs/zh/api/ | 操作指南只保留必要示例，完整约定链接 API |
| 原理、模块职责与约束 | docs/zh/design/ | 用户指南链接相关解释，不复制实现细节 |
| 评测方法与公开报告 | docs/zh/evaluation/；reports/ 按时间归档报告 | 首页与维护入口链接指南和报告索引，历史结果不作为当前性能保证 |
| 用户可见的版本变化 | docs/zh/changelog/releases.md | README 保留摘要；工程流水从维护入口访问 |
| 任务方案、证据与历史 | docs/zh/specs/、docs/zh/changelog/、历史归档 | 保存当时上下文，不作为当前操作指南 |
以上路径相对于仓库根目录。用户入口按首次使用、具体操作、接口查询、原理理解组织；维护入口见开发与维护。网站工程集中在 docs/website，菜单在导航配置维护。用户索引中的任务表自动生成网站首页入口，API 字段和示例自动排版，不另存一份页面正文。
新增内容先确定读者和主要维护位置。共享事实优先用摘要与链接复用；命令应调用仓库已有示例。需要反复出现的机器字段先考虑从来源校验或生成，不将普通 Markdown 全面改成模板。生成或引用内容仍需考虑 GitHub 中直接阅读的效果。
2. 修改与验证流程
- 确认行为来源与影响范围，只更新受影响的指南、接口或设计。重要任务记录 Spec，一般文字调整按仓库约定记日志，不为每个小修建立完整方案。
- 对翻译范围内的变化复核对应语言；新增页面显式决定翻译范围。完整对应关系集中在同步映射，本页维护语言规则。
- 本地运行内容检查、生产构建与网页检查；需要审查本次变更影响时传入比较基线。完整命令见文档网站。
- 提交中说明验证结果与未测范围；PR 的 Actions 只验证，main 验证后自动发布。
2.1 自动检查的职责
- 配置表的字段必须存在于配置类，示例值必须与 configs/prod.yaml 相符；不把示例值当作类默认值。
- 同步范围中的 JSON、Python、Shell 代码块检查语法；Shell 只执行 bash -n，Python 只解析语法，不执行示例或导入服务。Shell 中的 Python heredoc 也检查语法。
- 简单协议客户端命令的选项与取值按其 argparse 声明检查，不启动客户端。
- 双语机器示例检查一致性，忽略 JSON 排版、Python 注释及 Shell 整行注释；其他示例差异需在源文档中修正，不用无关文字改动掩盖。
- 源码、配置或客户端改动提醒复核相关文档；只修改一侧语言时提醒检查另一侧。提醒不阻断构建，文件同时变化也不表示语义已验证。
- 生产构建与网页检查负责链接、锚点、资源及真实搜索索引。当前不自动检查外部链接可用性，也不自动判断自然语言叙述是否与代码一致。
2.2 人工与运行验收
接口和默认值变化需要人工核对语义。代表性首次调用在相关功能变更或发布验收时实际运行，记录版本、模型、配置、硬件、输入和输出；普通文案修改不重复运行 GPU 推理。语法检查不能证明示例执行成功，文档构建不能替代服务、音质或性能验收。
3. 多语言维护
文档先按语言、再按主题组织：中文原文集中在 docs/zh/，英文文档集中在 docs/en/。根 README.md、CONTRIBUTING.md、AGENTS.md 保留原位置，docs/README.md 作为语言导航，docs/website/ 为共用网站工程。翻译范围见下表，新增文档先在本页和同步映射中明确读者、语言和翻译范围，不自动增加英文版本或空目录。
| 内容 | 中文原文 | 英文译文 |
|---|---|---|
| 项目主页 | README.md | docs/en/README.md |
| 用户导航 | docs/zh/README.md 中的使用服务入口 | docs/en/index.md，仅维护用户导航和必要的进一步阅读链接 |
| 安装与运行 | docs/zh/getting-started/ 下的 quick-start.md、configuration.md、troubleshooting.md | docs/en/getting-started/ 下的同名文件 |
| API | docs/zh/api/ 下的 README.md、voice-conversion.md、system.md、session-data.md | docs/en/api/ 下的同名文件 |
- 原文与译文：中文作为维护原文和默认阅读入口，英文保持相同的事实、接口语义和示例；接口事实最终以源码和有效配置为准。英文用户索引只维护用户导航及必要的进一步阅读链接，不翻译工程维护规则。
- 同步更新：修改翻译范围内的行为、字段、默认值、命令或示例时，在同一改动中同步中英文。暂时无法同步的译文需用英文标注待同步范围并链接中文原文，不将旧内容默认为当前行为。
- 单页语言：每篇文档使用一种正文语言。代码、字段名、错误原文、专有名词及语言切换链接保留必要的原文形式，不属于逐段双语对照。未翻译内容通过链接说明，不把整段中文插进英文页面。
- 路径对应：除项目首页和用户索引外，英文文件在
docs/en/下保持中文文件相对于docs/zh/的路径，例如docs/zh/api/system.md对应docs/en/api/system.md。上述用户文档的普通文件名使用小写英文和连字符，目录入口使用README.md；英文用户索引使用index.md。 - 导航与资源：已翻译页面在页首链接对应语言版本，正文优先链接同语言页面。英文文档引用仅有中文的页面时明确标注中文；新增译文后同步相关导航。共享图片、音频、源码和配置引用仓库现有文件，不按语言复制。
AGENTS、CONTRIBUTING、设计、Spec、每日 changelog、todo 与评测入口以中文维护。AGENTS 仅保留根目录一份，不在译文目录复制协作规则。历史归档和报告随其中文索引存放，正文保留原语言；中英文版本历史分别位于 docs/zh/changelog/releases.md 和 docs/en/changelog/releases.md，不因此扩大自动翻译检查范围。迁移时仅修正必要链接，历史记录中的日期、路径描述、结论与依据保留。
语言目录与网页地址分开维护：中文页面继续使用网站根路径，英文继续使用 en/ 路径；英文版本历史保留原网页地址。具体映射见网站路径适配。移动文档时必须同步相对链接、翻译与源码复核映射，并核对网页地址兼容性。
4. 文档版本与历史
在线文档持续跟随 main 开发分支，不能视为某个发布标签的固定快照。网站各页统一显示分支说明；Spec、每日记录与历史报告同时标明其历史性质。仓库首页与双语用户索引提供同样的版本说明，方便直接阅读 Markdown 的用户。
使用已发布版本时，从 GitHub Releases 进入对应标签，阅读该标签内的 Markdown。发布说明记录版本变化，不替代该版本的接口和操作指南。存在需要同时维护的不同接口版本时再评估多版本网站，本次不引入版本分支或版本目录。
旧文档路径与已公开锚点尽量保留；迁移时更新维护中的引用，兼容入口按具体迁移方案处理，不重写历史记录。设计中的演进方向与当前实现分开描述，历史性能结果保留日期与测量条件。