16. SimKit 文档发布与状态追踪方案调研¶
16.1. 背景¶
QIU-38 的目标是为 SimKit 提供类似 Read the Docs 的网页阅读体验，同时能跟踪功能开发状态、遗留问题，并在某个版本下保留图片或视频证据。当前仓库已经具备 Sphinx + MyST 文档基础：
入口：
docs/index.md配置：
docs/conf.py依赖：
pyproject.toml中已有sphinx、myst-parser、sphinx-simplepdf既有产物：
docs/_build/simplepdf/，说明已经跑过 simplepdf/html-like 构建
本调研只给出可落地方案，不把视频观感当作仿真成功证据；HSSD/R1Pro 类页面仍应链接到 JSON 指标、debug summary、overlay stats、force-chain 报告等可复验产物。
16.2. 需求拆解¶
网页阅读体验：支持章节目录、站内链接、搜索、代码块、图片、数学/表格。
版本化证据：每次实验或文档版本能固定引用对应图片、视频、JSON、summary。
开发状态跟踪：能在页面中看到 issue、功能状态、遗留问题与验证命令。
媒体支持：视频可在线播放或以外链方式打开；大文件不应进入 Git 仓库。
低维护成本：尽量复用现有 Sphinx/MyST，不重写文档栈。
可离线/内网部署：应能生成静态站点，放到任意 HTTP 文件服务或对象存储。
16.3. 方案对比¶
方案 |
优点 |
风险/缺点 |
对视频支持 |
结论 |
|---|---|---|---|---|
Sphinx + MyST + 静态 HTML |
已在仓库内；Python/uv 工作流一致；支持 API 文档、linkcode、PDF |
默认主题需配置；大媒体需外部托管 |
HTML 可嵌入 |
推荐主线 |
Read the Docs 托管 |
搜索/版本/构建体验成熟；天然支持 Sphinx |
公有托管与私有大媒体限制；视频大文件不适合放 Git |
可引用外部 URL，不能依赖 RTD 存视频 |
可作为公开文档镜像 |
GitHub Pages / 静态文件服务 |
部署简单；可以托管任意 Sphinx HTML |
版本切换和搜索需自己配置 |
可引用同域或对象存储视频 |
推荐发布目标之一 |
MkDocs Material |
UI/搜索很强；Markdown 体验好 |
需要迁移 Sphinx API/autodoc/simplepdf 生态 |
支持外链视频 |
不建议现在迁移 |
Docusaurus |
版本化和前端交互强 |
Node 生态迁移成本高，不适合当前 Python 文档 |
视频/React 组件强 |
后续如需产品化门户再考虑 |
阿里云盘/网盘复制每个版本 |
保留大文件方便 |
页面超链接、索引、自动化差；不可作为文档主站 |
视频下载/预览依赖网盘 |
只适合作原始归档，不适合作阅读入口 |
对象存储 + 静态 HTML manifest |
大媒体和版本化强；URL 稳定 |
需要约定路径和生成索引 |
最适合视频/JSON/图片 |
推荐作为证据资产层 |
16.4. 推荐架构¶
采用“双层发布”而不是二选一：
文档层：Sphinx + MyST 生成静态 HTML。
证据资产层：每次实验把图片、视频、JSON、
experiment_summary.md放入可版本化的 artifact 目录，再由文档页面链接。
建议路径约定：
docs/ # Sphinx/MyST 文档源码
index.md
documentation-platform-research.md
debug/<experiment_name>/ # 本地实验记录，AGENTS.md 要求
experiment_summary.md
summary.json
overlay_stats/
*.mp4 / *.png
artifacts/simkit-docs/<version-or-date>/
html/ # sphinx-build -b html 输出
debug/<experiment_name>/ # 可选：复制精简证据包
manifest.json # 版本、commit、issue、artifact URL 索引
artifacts/ 可以映射到：
本机 HTTP 路径（当前项目已有
https://f.qiu.work/->/root的映射约定）；GitHub Pages / Nginx 静态目录；
S3/OSS/R2 等对象存储；
网盘只作为冷备份，不作为唯一入口。
16.5. 媒体和状态追踪规范¶
16.5.1. 页面中引用视频¶
在 MyST/Markdown 中可以使用原生 HTML：
<video controls width="720" src="https://example/artifacts/qiu5/run.mp4"></video>
若视频很大，文档页面应只放缩略图和链接：
[打开 MP4](https://example/artifacts/qiu5/run.mp4)
[查看 summary.json](https://example/artifacts/qiu5/summary.json)
16.5.2. 功能状态块¶
建议每个功能/issue 页面使用统一状态块：
## Status
- Linear: QIU-5
- State: In Progress
- Last verified: 2026-05-08
- Verification:
- `uv run python -m unittest ...` -> exit 0
- Evidence:
- `debug/.../experiment_summary.md`
- `debug/.../summary.json`
- Known blockers:
- table unloading gate not passed
这样页面能展示开发状态，但 Linear 仍是任务状态的事实来源；文档只保存验证证据和长期结论。
16.6. 最小落地计划¶
16.6.1. Phase 1：继续使用现有 Sphinx，补齐 HTML 构建¶
命令：
uv run sphinx-build -b html docs docs/_build/html
验收：
docs/_build/html/index.html存在；documentation-platform-research.html能打开；相对链接不破；
页面可以链接到 MP4/JSON/Markdown 证据。
16.6.2. Phase 2：增加 artifact manifest¶
新增一个轻量 manifest（JSON/YAML 均可），记录：
{
"version": "2026-05-08",
"git_commit": "...",
"linear_project": "simkit",
"issues": [
{
"identifier": "QIU-5",
"status": "started",
"evidence": [
"debug/qiu5_force_chain_table_unloading_20260508/experiment_summary.md"
]
}
]
}
16.6.3. Phase 3：发布到静态站点¶
推荐优先级：
本机/Nginx 或
https://f.qiu.work/...静态映射，用于快速内部查看；GitHub Pages 或对象存储，用于稳定外链；
Read the Docs 仅作为公开纯文档镜像，不承载大视频。
16.6.4. Phase 4：自动化但不递归 cron¶
可以新增普通脚本或 CI job，例如：
uv run sphinx-build -b html docs docs/_build/html
python scripts/build_docs_artifact_manifest.py --debug-root debug --output docs/_build/html/artifact_manifest.json
当前 cron worker 不应创建/更新 cron job；只维护脚本、文档和验证记录。
16.7. 决策建议¶
本仓库现阶段推荐：
保留 Sphinx/MyST 作为唯一文档源，避免迁移到 MkDocs/Docusaurus。
HTML 主站 + PDF 切片并存：网页用于导航和视频/JSON 链接，simplepdf 用于汇报材料。
大媒体放外部 artifact store，Git 中只保存文档、脚本、轻量 JSON 和实验 summary。
每个实验必须有
debug/<experiment>/experiment_summary.md，页面引用该 summary 和关键指标文件。Linear 继续管理待办状态，文档只记录验证证据、版本快照和长期结论。
16.8. QIU-38 验收建议¶
本 issue 可以在以下最小条件满足后关闭：
调研方案已落地到
docs/documentation-platform-research.md；该页面被加入
docs/index.mdtoctree；uv run sphinx-build -b html docs docs/_build/html成功；记录一份
debug/qiu38_documentation_platform_research_*/experiment_summary.md。
后续如要实现 artifact manifest 或部署流水线，应拆成新的 enhancement issue，而不是让 QIU-38 无限扩大。