14. 文档结构地图

本页是 QIU-50 的第一层文档整理入口：把现有顶层文档按用途分组，并明确关键实验记录应该放在哪里。它不替代各专题正文，只作为导航和防重复创建文件的约束。

14.1. 一级目录职责

路径

职责

维护规则

docs/index.md

Sphinx 文档入口与少量精选链接

只放稳定入口，不堆实验细节

docs/01-quick-install.md / docs/appendix-b-install.md

快速安装与详细安装

新依赖优先补到对应专题子目录，再在这里引用

docs/02-features.md / docs/04-modules.md

功能与模块概览

只保留摘要，长文移到专题页

docs/03-architecture.md

系统架构

跨后端长期架构决策才写入

docs/data-generation.md

数据生成主线

数据采集、trajectory、导出格式的单一事实来源之一

docs/guides/wishlist.md

Wish List / Roadmap

唯一官方 wishlist，不要新建其它 wish list 文件

docs/maniskill/

ManiSkill 后端与 HSSD scene-level 调试文档

HSSD scene / stage-only / object-inclusive 调试优先放这里或 docs/hssd-integration-report.md

docs/sapien/

SAPIEN 渲染与仿真文档

SAPIEN API/渲染问题放这里

docs/data-platform/

数据平台、LeRobot/Rerun/OBS/Artifact 相关文档

数据平台 issue 的独立研究页放这里

docs/behavior1k/

BEHAVIOR-1K 安装、probe、示例

EULA/资产下载边界必须写清楚

docs/superpowers/specs/

技术设计文档

新的设计提案放 specs，不与计划混写

docs/superpowers/plans/

实施计划文档

可执行计划放 plans，完成后在正文页沉淀长期结论

debug/<experiment_name>/experiment_summary.md

每次实验的人类可读记录

HSSD/R1Pro/渲染/抓取实验必须保留日期、scene、命令、参数、产物、结论、失败现象、下一步

14.2. 关键实验与长期结论入口

  • docs/hssd-integration-report.md：HSSD 集成长期结论和跨实验沉淀。

  • docs/data-generation.md：数据生成流程、数据格式和采集主线。

  • docs/maniskill/r1pro_scene_camera_capture.md：R1 Pro scene camera capture 与多视角诊断入口。

  • docs/maniskill/hssd_scene_type_naming.md：HSSD scene/stage/object 命名与数据层次说明。

  • docs/behavior1k-data-generation-methods.md：BEHAVIOR-1K、BDDL、MoMaGen 与 SimKit/HSSD 桥接方法。

  • docs/documentation-platform-research.md：文档发布、状态追踪、版本化证据资产方案。

  • docs/mainland-china-artifact-services.md：中国大陆 artifact hosting 服务对比。

  • docs/momagen-reproduction.md：MoMaGen 复现边界和 renderer-free probe。

  • docs/maniskill-pickcube-robotwin2-assets.md：RoboTwin2 manifest 到 ManiSkill PickCube 配置桥接。

14.3. 新文档放置规则

  1. 先搜索 docs/、docs/maniskill/、docs/data-platform/、docs/behavior1k/ 和 docs/superpowers/，确认没有同主题入口。

  2. Wish List / Roadmap 条目只编辑 docs/guides/wishlist.md。

  3. HSSD/R1Pro 实验结果先写 debug/<experiment_name>/experiment_summary.md；只有长期规则再沉淀到正式 docs 或 AGENTS.md。

  4. 文档平台、Rerun、LeRobot、OBS、Artifact 服务等数据平台内容放入 docs/data-platform/。

  5. BEHAVIOR-1K/OmniGibson 相关安装和 EULA 边界放入 docs/behavior1k/ 或 docs/behavior1k-data-generation-methods.md。

  6. 技术设计和执行计划分别放 docs/superpowers/specs/ 与 docs/superpowers/plans/，不要直接堆到 docs/index.md。

14.4. 后续一级目录迁移清单

当前结构地图已经把一级目录职责、专题入口和实验记录位置固定下来；真正迁移顶层页面时必须按以下顺序执行，避免丢失交叉引用或实验原始证据：

  1. 先列出待迁移页面和目标目录，确认是否属于 docs/maniskill/、docs/sapien/、docs/data-platform/、docs/behavior1k/ 或 docs/superpowers/。

  2. 不要直接移动或删除现有顶层页面；先新增目标入口、保留旧入口的跳转/说明，再在一次独立迁移中统一删除或合并。

  3. 每次移动后必须更新 Sphinx toctree 和所有 cross-reference，包括 docs/index.md、专题 example_index.md、设计文档和计划文档中的相对链接。

  4. 保留 debug/<experiment_name>/experiment_summary.md 作为实验原始证据；正式文档只沉淀长期结论和可复用规则。

  5. 迁移完成后运行结构合约测试、链接相关测试和 Sphinx HTML 构建，再把 warning 差异写入迁移记录。

14.5. 当前整理边界

本轮只增加结构地图并把它接入 Sphinx 首页，避免在已有未提交 docs-daemon 和 data-platform 改动存在时大规模移动文件。后续若要真正重排一级目录，应先开独立迁移计划并一次性更新所有交叉引用。