# SimKit 文档发布与状态追踪方案调研

## 背景

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 报告等可复验产物。

## 需求拆解

1. **网页阅读体验**：支持章节目录、站内链接、搜索、代码块、图片、数学/表格。
2. **版本化证据**：每次实验或文档版本能固定引用对应图片、视频、JSON、summary。
3. **开发状态跟踪**：能在页面中看到 issue、功能状态、遗留问题与验证命令。
4. **媒体支持**：视频可在线播放或以外链方式打开；大文件不应进入 Git 仓库。
5. **低维护成本**：尽量复用现有 Sphinx/MyST，不重写文档栈。
6. **可离线/内网部署**：应能生成静态站点，放到任意 HTTP 文件服务或对象存储。

## 方案对比

| 方案 | 优点 | 风险/缺点 | 对视频支持 | 结论 |
|---|---|---|---|---|
| Sphinx + MyST + 静态 HTML | 已在仓库内；Python/uv 工作流一致；支持 API 文档、linkcode、PDF | 默认主题需配置；大媒体需外部托管 | HTML 可嵌入 `<video>` 或链接外部 MP4 | 推荐主线 |
| 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/图片 | 推荐作为证据资产层 |

## 推荐架构

采用“双层发布”而不是二选一：

1. **文档层**：Sphinx + MyST 生成静态 HTML。
2. **证据资产层**：每次实验把图片、视频、JSON、`experiment_summary.md` 放入可版本化的 artifact 目录，再由文档页面链接。

建议路径约定：

```text
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 等对象存储；
- 网盘只作为冷备份，不作为唯一入口。

## 媒体和状态追踪规范

### 页面中引用视频

在 MyST/Markdown 中可以使用原生 HTML：

```html
<video controls width="720" src="https://example/artifacts/qiu5/run.mp4"></video>
```

若视频很大，文档页面应只放缩略图和链接：

```markdown
[打开 MP4](https://example/artifacts/qiu5/run.mp4)
[查看 summary.json](https://example/artifacts/qiu5/summary.json)
```

### 功能状态块

建议每个功能/issue 页面使用统一状态块：

```markdown
## 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 仍是任务状态的事实来源；文档只保存验证证据和长期结论。

## 最小落地计划

### Phase 1：继续使用现有 Sphinx，补齐 HTML 构建

命令：

```bash
uv run sphinx-build -b html docs docs/_build/html
```

验收：

- `docs/_build/html/index.html` 存在；
- `documentation-platform-research.html` 能打开；
- 相对链接不破；
- 页面可以链接到 MP4/JSON/Markdown 证据。

### Phase 2：增加 artifact manifest

新增一个轻量 manifest（JSON/YAML 均可），记录：

```json
{
  "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"
      ]
    }
  ]
}
```

### Phase 3：发布到静态站点

推荐优先级：

1. 本机/Nginx 或 `https://f.qiu.work/...` 静态映射，用于快速内部查看；
2. GitHub Pages 或对象存储，用于稳定外链；
3. Read the Docs 仅作为公开纯文档镜像，不承载大视频。

### Phase 4：自动化但不递归 cron

可以新增普通脚本或 CI job，例如：

```bash
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；只维护脚本、文档和验证记录。

## 决策建议

本仓库现阶段推荐：

1. **保留 Sphinx/MyST 作为唯一文档源**，避免迁移到 MkDocs/Docusaurus。
2. **HTML 主站 + PDF 切片并存**：网页用于导航和视频/JSON 链接，simplepdf 用于汇报材料。
3. **大媒体放外部 artifact store**，Git 中只保存文档、脚本、轻量 JSON 和实验 summary。
4. **每个实验必须有 `debug/<experiment>/experiment_summary.md`**，页面引用该 summary 和关键指标文件。
5. **Linear 继续管理待办状态**，文档只记录验证证据、版本快照和长期结论。

## QIU-38 验收建议

本 issue 可以在以下最小条件满足后关闭：

- 调研方案已落地到 `docs/documentation-platform-research.md`；
- 该页面被加入 `docs/index.md` toctree；
- `uv run sphinx-build -b html docs docs/_build/html` 成功；
- 记录一份 `debug/qiu38_documentation_platform_research_*/experiment_summary.md`。

后续如要实现 artifact manifest 或部署流水线，应拆成新的 enhancement issue，而不是让 QIU-38 无限扩大。