文档按中英文目录迁移

1. 背景与目标

现有 docs 将主题目录与 en 语言目录并列，中文的语言归属隐含在根层级。本次按维护者要求，将中文文档集中到 docs/zh，英文集中到 docs/en，同步链接、导航、内容检查与协作约定，保持现有网站地址和公开锚点不变。

状态：已完成。仅调整文档组织和网站适配，不修改服务、配置、客户端、模型或依赖版本。

2. 目录与行为

• 根 README.md、CONTRIBUTING.md、AGENTS.md 保持原位置；docs/README.md 成为仓库内的语言导航，不生成独立网页。
• 原中文用户索引迁到 docs/zh/README.md，继续生成网站首页；中文主题目录、设计、Spec、工程日志、评测和 todo 整体迁入 docs/zh。
• docs/en 的既有页面保持位置；英文版本历史从 docs/changelog/releases_en.md 移到 docs/en/changelog/releases.md，正文保留，其网站地址继续为 changelog/releases_en/。
• docs/website 保持共用，图片、音频、源码及配置不复制。历史归档保留其原语言，不为语言目录重新翻译历史正文。
• 已有翻译范围不扩大，中文用户索引与英文 index.md 继续成对；目录入口和英文项目主页保留各自职责。
• 所有现行相对链接按新位置更新；历史记录仅调整可点击链接，保留当时的路径描述、日期、结论和依据。

3. 网站兼容与设计取舍

构建来源仅包含根项目/贡献入口与 docs/zh、docs/en，排除仓库语言入口和网站工程。中文来源去掉 docs/zh 前缀映射到原网址；英文沿用 en 前缀，英文版本历史单独保留旧地址。保持一份正文来源，不复制兼容 Markdown。

页面的历史标记、搜索排除、首页布局和协议提取适配新的语言前缀；翻译映射与源码复核映射更新为新来源。网站导航继续使用既有公开网址，源码链接改为新路径。GitHub main 的旧文件路径随迁移改变，历史提交和标签仍可查看旧位置；本次保持的是网站地址。

4. 实施步骤

1. 保存迁移前全部页面的来源、网页路径及历史/搜索属性。
2. 移动文件，更新相对链接、现行路径文字、双语入口及文档约定。
3. 更新构建来源、路由、首页识别、翻译和检查脚本，补充路径兼容回归。
4. 执行文档内容检查、Python 与 Node 回归、生产构建、网页链接/锚点/搜索检查；逐页比对迁移前后的网页路径与属性。
5. 更新当前设计、Spec 验收、索引和当日 changelog；不提交、不推送、不发布。

5. 验收标准与边界

• 迁移前每个网页都有唯一的新 Markdown 来源，网址及公开锚点保留；不生成多余的 zh/ 站点层级。
• 仓库内链接、双语导航、源码链接、首页入口、历史提示和搜索范围正确；翻译示例与配置表校验继续通过。
• 旧 Spec、工程日志和历史资料除必要链接外保持原文；历史评测报告逐字节一致。
• git diff --check 通过，无服务源码、配置、模型、依赖或公开素材变更。
• 本地验证不代表 Pages 已部署；不进行服务联调、GPU 推理、音质或压力测试。

6. 实际验证与剩余事项

迁移前基线为 7c3f871；本地使用 Node.js 24.18.1、uv 0.11.23 和文档工具的 Python 3.12 环境，沿用现有锁定依赖。验证结果：

• 内容检查（含 --base origin/main 变更提醒）：9 对文档、54 个机器示例、60 个配置值通过。
• Python 检查器回归 18 项、Node 网站适配回归 11 项通过。新增回归覆盖语言入口排除、网站首页与历史页属性、双语导航目标，并扩展旧网址及跨语言链接断言。
• 生产构建、两种语言的实际搜索索引和网页本地链接/资源/锚点检查通过；最终产物包含 57 篇正文、404 页面和 237 条搜索记录。
• 逐项比对迁移前页面清单：55 个已有网页地址与历史/搜索属性全部一致；迁移前 HTML 中 900 个锚点全部保留。
• 全仓库 Markdown 相对链接与锚点检查通过，覆盖不参与网站生成的语言总入口、AGENTS、网站工程说明和品牌说明。
• 对生成 HTML 核对 9 对双向语言切换、源码链接及两个首页的任务入口，全部通过。
• 18 篇历史 Spec、每日记录、发布说明、归档笔记和报告除链接目标外保持原文；其中 3 篇历史评测报告逐字节及 SHA-256 一致。
• git diff --check 通过。服务源码、配置、客户端、模型子模块、依赖锁文件和图片/音频素材未修改。

可复核命令：

uv run --project tools/docs --python 3.12 --locked --offline python tools/docs/check_content.py --base origin/main
uv run --project tools/docs --locked --offline 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 --offline python tools/docs/check_site.py
git diff --check

离线命令使用本机已安装的文档依赖；新环境先按网站设计文档安装锁定依赖。CI 的 docs/** 触发范围已覆盖 zh/en，构建与检查入口保持不变，无需修改工作流或依赖。

目录迁移的本地验收阶段已完成实施，当时尚未提交、推送或发布；未执行浏览器交互复测、线上验收、服务联调、GPU 推理、音质或压力测试。后续提交与发布验收见第 7 节。

7. 提交、发布与线上验收

2026-11-04 根据维护者后续授权，将实施提交 48c07ee 推送至 main。提交只包含文档迁移及配套调整，迁移期间另外新增的待办保留为本地工作区修改。

对应 GitHub Actions 工作流的文档内容检查、Python/Node 回归、生产构建、网页验证、产物上传与 Pages 部署全部成功。

北京时间 11:02:18 完成线上 HTTP 与 HTML/索引核验：

• 线上页面清单与本次构建一致，57 个正式网页全部请求成功。
• 迁移前 55 个网页路径及其 900 个锚点全部保留。
• 9 对页面双向语言切换、Markdown 源码链接、两个首页任务入口正确。
• 237 条搜索记录的目标与锚点均可解析；中英文两个实际搜索索引包可访问并包含页面记录。
• 题图、导航图标和 favicon 三项品牌资源请求成功。

网站入口：中文文档 · English。本阶段未执行浏览器交互复测或服务/GPU 测试；HTTP 验收过程中出现的偶发 TLS 连接中断经有限重试后全部通过。