文档网站与自动发布

1. 背景与目标

现有 Markdown 已覆盖项目介绍、安装、接口、部署和设计，但读者需要在仓库文件间跳转。本任务复用这些内容，建立带导航、中文与英文搜索的 MkDocs 网站，并通过 GitHub Actions 构建、部署到 GitHub Pages。

服务源码、运行依赖、模型与子模块不属于本次修改范围。网站构建只安装独立的文档工具，不启动服务或执行推理。

2. 需求与设计

• 使用 MkDocs 和 Material 主题，中文为默认入口，英文使用现有译文，不扩大翻译范围。
• Markdown 仍为唯一正文来源；构建时适配目录首页、跨目录链接、GitHub 源码链接和已有图片引用，不维护第二份正文。
• 使用独立的文档 pyproject.toml、uv.lock 锁定工具版本，避免安装主项目的推理依赖。
• 本地支持预览和严格构建；构建产物被 Git 忽略，不提交 HTML，也不创建 gh-pages 分支。
• PR 只构建验证；main 分支推送及手动运行可部署。发布使用官方 Pages artifact 与 deploy action，写入权限仅授予部署任务。
• 网站只发布文档和主题资源；源码、配置、音频与仓库素材使用公开仓库链接，不批量复制到网站。
• Spec、每日工程日志、历史归档和旧性能报告保留网页链接，但不进入全文搜索，避免旧参数或实施记录排在当前接口指南之前。
• README 与中英文用户入口增加在线文档链接，贡献指南说明预览方法，发布配置与维护说明集中记录。

3. 实施步骤与兼容影响

1. 接入独立文档环境、站点导航与必要的构建适配。
2. 添加严格构建、PR 校验及 Pages 自动部署工作流。
3. 更新入口、维护说明、当前设计与索引。
4. 验证构建、站内链接与锚点、中英文页面、搜索及网页显示，再记录真实结果。

原有 Markdown 路径与 GitHub 阅读入口继续有效。首次上线需要提交工作流并将仓库 Pages 来源设置为 GitHub Actions；本地验证不等于云端发布成功。Git 提交、推送与线上部署分别记录。

4. 验收方法

• 使用 uv 锁定环境执行 MkDocs 严格构建。
• 检查生成网页中的站内链接、资源路径及锚点；确认项目子路径部署正确。
• 验证中文和英文搜索、桌面与窄屏导航、源文件跳转。
• 检查工作流触发、权限及部署条件；检查构建产物未包含业务源码、音频和凭据。
• 执行 git diff --check，确认服务代码、主项目依赖与子模块未改动。

5. 实施与验证记录

状态：已完成本地验收与 GitHub Pages 首次上线；发布记录见 5.4。

5.1 已实现内容

• 站点配置提供使用指南、API、设计与评测、开发与维护、English 五组导航，支持浅色/深色主题、代码复制和中英文搜索。
• 文档环境为 Python 3.12、MkDocs 1.6.1、Material 9.8.0，独立 uv.lock 锁定 31 个包（含文档项目）。根目录服务依赖未改动。
• 构建钩子在内存中映射根项目首页、贡献指南与英文项目首页；保留现有源文件路径，适配 Markdown 和原生 HTML 中的链接。docs 下只发布 Markdown，不自动复制其他文件。
• 工作流在 PR 验证，main 更新及 main 手动运行时发布；Action 引用按 GitHub 实际 tag 核对并固定到提交。main 工作流串行，PR 可取消旧运行，单任务超时 10 分钟。
• 维护方式见文档网站，README、中英文用户索引、贡献指南和当前设计已补充入口。

5.2 本地验收

• uv run --project tools/docs --locked mkdocs build --strict 通过，生成 53 个 HTML 页面；Markdown 站内链接和中文锚点无构建告警。
• uv run --project tools/docs --locked python tools/docs/check_site.py 通过，遍历全部生成页面、资源引用与搜索记录，检查项目子路径、文件存在性和锚点。
• 离线行为检查通过：生成页面链接映射、原生 HTML 图片/链接、行内与围栏代码保留、不存在和越界路径拒绝；网页检查器能拒绝缺失页面和锚点。
• 工作流 YAML 解析、触发类型、main/PR 部署条件、最小权限和 Action 提交固定检查通过。本地验收阶段未执行云端工作流；后续实际运行见 5.4。
• 浏览器实测中文“采样率”和英文“WebSocket”搜索能返回文档并跳转，英文入口正常；390 像素宽度的英文页面和抽屉导航可用。项目题图和徽章加载成功，检查时未见浏览器错误日志。
• 产物检查未包含业务 Python 源码、音频、依赖锁文件或 .env；历史归档和实施记录未进入搜索索引。
• git diff --check 通过；服务源码、根 pyproject.toml、根 uv.lock 和子模块没有改动。没有运行服务、GPU 推理或音质/压力测试。

5.3 首次发布与维护事项

本地验收结束时尚未发布。随后用户明确授权提交、推送并上线；实际配置与发布结果见 5.4。本地验收与线上验证分别记录。

Material 上游关键维护截止日为 2027-05-05；本次使用当前安全修复版本并保留 CLI 提示。依据与后续评估方向记录在维护周期，未将主题迁移作为本次已完成事项。

5.4 首次上线结果

• 实现提交 41fe6fe 已推送到 main。
• 仓库原先未启用 Pages；通过 GitHub API 创建站点并确认 build_type 为 workflow、HTTPS 已强制启用。
• 首次工作流整体成功，严格构建、网页检查、上传产物和 Pages 部署均通过。
• 正式地址：中文文档与英文文档。
• 线上中文/英文用户首页、中文/英文项目介绍、语音转换 API 和搜索索引六个地址均返回 HTTP 200，下载内容的 SHA-256 与本地对应产物完全一致。
• 搜索交互、题图加载和手机目录已在本地浏览器验收；线上页面完成 HTTP 与内容一致性检查，浏览器访问线上站点的工具超时，未将其记为线上浏览器交互通过。
• 本节及当日日志作为后续验收记录提交，不回写首次实现提交，也不修改已有日志条目的时间与结论。