贡献指南

感谢你对本项目的关注！欢迎通过以下方式贡献。

---

如何贡献

1. 报告问题

发现文档错误、链接失效、内容过时？请提交 Issue：

• 描述问题所在（文件名+行号）
• 说明正确的内容应该是什么
• 如果有相关论文/资料，请附上链接

2. 补充内容

想补充新的论文解读、实践指南或学习笔记？

1. Fork 本仓库
2. 在对应目录下创建新文件
3. 遵循现有文档格式（见下方模板）
4. 提交 Pull Request

3. 改进现有文档

发现表述不清、结构混乱、缺少图表？

1. Fork 本仓库
2. 修改对应文件
3. 提交 Pull Request，说明修改原因

---

文档格式模板

新建文档按下面的骨架来。既有文档的小节标题是按内容自拟的（多为 ## 1. 项目概述 这类编号小节），骨架里的 ## 核心内容 / ## 关键论文 只是占位、说明正文要覆盖这些内容，不必照抄标题；但 动手验证 / ## 延伸阅读 / ## 思考题 三节的标题与位置要求一致。

# 标题

> **预计阅读**：X 分钟 | **前置知识**：xxx

---

## 核心内容

（配图、配表、配公式简化版）

## 关键论文

（条目式列出，每篇含 arXiv 链接，写法见下方「索引层排版」；数据与基准篇写 `## 关键资源`）

## 动手验证：<要验证的那条结论>

（可选。只在"正文结论能用一个迷你实验量出来"时写，格式见下方「代码 demo 规范」）

## 延伸阅读

（相对路径链接到其他文档）

## 思考题

1. **对比分析**：问题一

2. **方法迁移**：问题二

<details><summary>参考答案</summary>

1. 答案一

2. 答案二

</details>

注：> 预计阅读： 有加粗与不加粗两种写法。新文档跟随同目录既有文档的写法；改动既有文档时保持该文件原本的写法，不要只为加粗而改。

## 思考题 有两套写法，按目录分、互不重叠，判据是 <details> 怎么写：Part 5–8 用单行，Part 1–4 用拆行。

单行（Part 5–8）：## 思考题（不编号）；编号列表出题，每题前缀一个粗体小标签；所有答案收在同一个 <details><summary>参考答案</summary> 里，答案按 1. 2. 编号。

拆行（Part 1–4 与 Part 9）：<details> 与 <summary> 拆行写；这一套内部各 Part 的出题形式不同，改动时照所在文件抄，不要"顺手统一"：

Part	## 标题	出题形式	答案块
1 基础概念	## 思考题	编号列表 + 粗体小标签	1 个，收全部答案
2 世界模型	## N. 思考题	### 题目 N：<标题>	每题 1 个
3 VLA	## N. 思考题	**题目 N：<标题>** 加粗段	每题 1 个
4 VLM	## N. 思考题	### 题目 N：<标题>	每题 1 个，<summary> 写 查看答案
9 专题自测	## N. 思考题	**题目 N：<标题>** 加粗段；题量 3，且必须跨篇才答得出	每题 1 个

写 ## N. 思考题 时，N 等于该文件 H2 的序号。

已知变体，改动时以所在文件为准：

• 05-综述论文精读/05-基准与评估.md：单行写法，但每个答案一个 <details>，不是全部收在一个里
• docs/00-导读与学习路线.md 是导航文档，没有 ## 思考题；正文里那个在代码块内，是在展示模板
• docs/09-专题自测与考察/ 下的三篇没有阅读节，是全仓仅有的「无阅读节 + 有 ## N. 思考题」组合；三道题必须跨篇综合

新文档跟随同目录既有文档的写法——往 Part 5–8 加用单行，往 Part 1–4 加用拆行。

单行写法的补充要求：

• 题量 5 题，每题前缀一个粗体小标签（如 **对比分析**：、**复现风险**：），同一篇里不要重复用同一个标签
• 题目考理解 / 对比 / 迁移 / 设计，不要考查表背诵
• 答案 2–4 句，可引用文档中出现过的数字与论文名，但不得引入文档里没有的事实——写不出有依据的答案就换一道题

位置统一在文件最后一个内容节之后、整个文件的末尾；若末尾有 --- 与页脚，插在页脚之前。那个内容节和标题形式都随所在 Part：

Part	阅读节	思考题标题
1 / 5 / 6 / 7 / 8	## 延伸阅读	## 思考题
2 / 3	## N. 延伸阅读	## N. 思考题
4	## N. 扩展阅读	## N. 思考题
9	（无阅读节，正文已逐节链回本卷各篇）	## N. 思考题

没有阅读节的有五篇：07-实践指南/01-环境搭建.md、07-实践指南/08-可复现项目候选清单.md，以及 09-专题自测与考察/ 下的三篇自测。

---

目录结构

README.md                 # 项目说明与文档目录
README.en.md              # 英文门面（只做门面，正文保持中文）
CONTRIBUTING.md           # 贡献指南（本文件）
LICENSE
CHANGELOG.md              # 更新日志
CITATION.cff              # 引用元数据（GitHub 侧据此导出 BibTeX / APA）
mkdocs.yml                # 文档站配置（docs_dir 指向 build-docs/，见「文档站」）
docs/
├── 00-导读与学习路线.md
├── 01-基础概念/          # 基础概念解释
├── 02-世界模型专题/       # 世界模型深入
├── 03-VLA专题/           # VLA 深入
├── 04-VLM专题/           # VLM 深入
├── 05-综述论文精读/       # 综述逐章解读
├── 06-论文导读合集/       # 论文卡片
├── 07-实践指南/           # 复现指南
├── 08-研究前沿与开放问题/  # 从学习者到研究者
├── 09-专题自测与考察/      # 专题自测与考察（正文即题目集）
└── en/index.md           # 英文文档总览（英文标题 + 一句说明 + 链回中文正文）
code/                     # 可运行 demo（真实 PyTorch）
├── common/               # 共用部件：四旋翼仿真、出图工具
└── a_~x_*.py             # 每个 demo 一个脚本，与文档一一对应
mindmaps/                 # 思维导图
references/               # 参考资料
figures/                  # 由 code/ 脚本生成的配图
tools/                    # 自检与生成脚本（前沿追踪、站点构建、链接/nav 检查）
.github/                  # Issue 表单、PR 模板与 CI workflow

---

内容规范

• 语言：中文为主，技术术语保留英文
• 风格：结构化、有优先级标注。表格只承载可枚举的对照数据（平台参数、数据集规模、指标数值）；因果推理和优劣分析写成句子，不拆成表格
• 链接：使用相对路径，确保 GitHub 上可点击
• 图表：优先使用 Mermaid（GitHub 原生支持）
• 论文引用：必须包含 arXiv 链接或 DOI
• 术语统一：正文用 π₀ / π₀.₅ / RT-2；Mermaid 节点 id 允许写成 Pi0 / RT2（id 不能带特殊字符）

---

表达规范

风格基准取四个开源范本：d2l 中文版（讲方法）、Spinning Up（讲论文）、Distill 的 "How to Use t-SNE Effectively"（用可反驳的断言组织全篇）、Karpathy 的 A Recipe for Training Neural Networks（讲流程）。最可抄的是 d2l——它全页加粗 0 处、破折号 0 处、"本节将" 0 次。

硬性规则（可逐句核对）

规则	反例
不写"本节将介绍…"，正文直接进内容	~~本节将介绍将 VLA 部署到机载平台的关键技术。~~
过渡句必须带下一节的具体对象	~~接下来，让我们看看相关概念。~~ → 接下来看 GBDT 的回归流程。
写了"重要 / 显著 / 巨大 / 关键"就欠一个数字或条件，欠不出就删整句	~~展示了令人印象深刻的能力~~ → 在 A100 上 6 Hz，在 Orin NX 上 0.5–1 Hz
标题不用"引言 / 概述 / 简介"这类空壳，直接写能预判内容的句子或问句	~~## 1. 引言：什么是 VLA？~~ → ## 1. 什么是 VLA？
同一 Part 内不出现同位置、同句式的标题	15 篇同在第 7 行写 ## 1. 引言：… 即为反例
术语首现写 中文（English），之后固定用中文名	d2l 显式宣布"本书坚持用『预测』，『推断』是用词不当"
前置知识只给指针，不在原地重讲	~~（此处展开解释 Transformer）~~ → 见 什么是VLM
答案块里不写"启示 / 结论"这类不看材料也能说的收尾	~~启示：不能只看速度，准确率和速度需要平衡~~

排版

• 加粗：只给两类东西——术语首现（**动作 tokenization**）和正文里真正的结论。不给整句叙事加粗，"这就说明了 X 很重要"这类句子加粗只是把读者当扫描仪。表格首列与卡片字段标签（| **硬件需求** |）照常加粗，那是检索锚点，不受此条约束。
• 已知例外：09-专题自测与考察/ 三篇用 **M1** … 式题号当检索锚点，08-研究前沿与开放问题/04-最新进展与团队追踪.md 用整句加粗当阅读锚点，都属刻意选择，未统一。
• 破折号 ——：一段里最多一次
• 中英之间加半角空格（用 PyTorch 训练）；全角标点与字符之间不加；全角空格（U+3000）是机器痕迹，禁用
• 引号：简体正文统一用 “”，不混用 「」

索引层排版

索引层指 README.md 的核心论文清单、references/paper-list.md、docs/06-论文导读合集/ 的卡片，以及各卷的「关键论文」「关键资源」节。正文表格不在其中。

条目固定两行，中间不空行，第一行行尾留两个空格：

- **[NeurIPS'18] World Models** — *Ha & Schmidhuber* · ★★★
  [![arXiv](https://img.shields.io/badge/arXiv-1803.10122-b31b1b.svg)](https://arxiv.org/abs/1803.10122)

• 加粗位放系统名，斜体位放 arXiv API 返回的完整英文题名；论文没有系统名（如上面这条）时加粗位直接是完整题名，斜体位放作者。会议、年份、作者、题目一律不问记忆，只问 API 与 paper-list.md。
• 标签 [会议'年] 只写已正式发表的会议；只有预印本时写 [arXiv'年.月]，月份取 arXiv 号的 YYMM。数据/基准写 [Dataset]，工具写 [Tool]。
• 第二行缩进两格挂徽章。标签只有三个：arXiv（红底 -b31b1b.svg）、GitHub（黑底 -181717.svg?logo=github）、Website（蓝底 -0A66C2.svg）；消息位 arXiv 写编号、GitHub 写仓库名、项目页写域名或项目简称。徽章文字里 / 是 shields.io 的分隔符，不能出现；- 写 --、_ 写 __、空格写 _。
• 徽章只挂在索引层。 正文的表格与行内引用一律用纯文本链接，不挂徽章。
• 推荐度只用三星制（★★★ 必读 / ★★☆ 推荐 / ★☆☆ 了解），图例在 references/paper-list.md 出现一次；各卷「关键论文」节是书目，不带推荐度。

一条元规则

不靠删词求简洁。 改稿顺序：补回信息 → 调整成中文自然语序 → 收束过强判断。信息不足时注明局限，而不是把话删短。

---

代码 demo 规范

正文以"讲清楚"为主，代码不是必需的。只在一条结论光靠文字说不透、且能用一个小实验量出来时，才配 demo。

现状：code/ 下每个脚本对应文档里的一到多处 动手验证 节，多数脚本被多篇文档复用（o_budget 10 篇、g_eval_metrics 5 篇、f_control_loop 4 篇，其余 1–3 篇）。新增脚本时，在对应文档的 动手验证 节给出链接与运行命令。

一节 demo 固定五段：

1. 一句话说明本节验证正文的哪条结论
2. 精简代码片段（``python，25–40 行）：只留模型定义与训练循环核心，完整脚本放code/`
3. ### N.2 本地实测结果 贴真实跑出来的输出；数字必须来自实跑，禁止编造或凭印象填写
4. ### N.3 【待验证】接入 PX4 SITL：<自拟>（可选）：ROS2 + px4_msgs 骨架，必须显式标注"未在本地验证"及所需环境。只写在涉及飞控闭环的 demo 里，与飞控无关的题材（量化、四元数、统计检验等）不写这一节
5. ### N.4 运行完整脚本 指向 code/xx.py 的链接 + 运行命令 + 依赖

补充要求：

• 图必须由脚本真实生成并写入 figures/，不得手工绘制或臆造，并确保每张图都被至少一篇文档引用
• 段落标题统一为 动手验证：<主题>，位置在最后一个正文章节之后、## 延伸阅读 之前；编号与否跟随该文件既有 H2 习惯（Part 1–4 编号，写作 ## 8. 动手验证：…；Part 5–8 不编号，写作 ## 动手验证：…）
• 结论要如实描述：如果实验只支持"① 与 ④ 的对比"，就不要把中间几组的次序也说成结论
• 用了随机种子就要说明；单次实验的噪声要写进图题或正文，别把噪声当规律

---

补充新论文的标准

如果你想补充一篇新的论文解读，请确保：

1. 以无人机与机器人为主线：地面操作论文可以收入，但每处必须写明 对无人机的迁移点，或不可迁移的原因——只写"同样是 VLA"不算
2. 有足够的创新性：不是简单的增量工作
3. 包含以下信息：
4. 一句话总结
5. 核心贡献（3-5 点）
6. 方法要点
7. 实验结果亮点
8. 论文链接和代码链接（如有）

arXiv 号以 arXiv 官方页面为准，不要凭印象写。

前沿追踪

三卷各有词表，共用同一个内核：

py -3.9 tools/watch.py --list                 # 看各卷的节
py -3.9 tools/watch.py --volume wm --write    # 世界模型卷
py -3.9 tools/watch.py --volume vlm --write   # VLM 卷
py -3.9 tools/watch.py --volume vla --write   # VLA 卷

词表在 tools/watchlists.py，节 id 就是文档编号，uav 节是全场主线。 写出的 references/<卷>-watch-<年-月>.md 是生成物，重跑即可刷新， 不要手改。三条纪律写在内核的 docstring 里，最要紧的一条是： 429 / 超时 / 非 200 记 NULL，绝不记 0——把请求失败当成「没有命中」 会凭空造出一个空白。命中 0 的查询，复核过之后把结论钉进 watchlists.py 的 VERIFIED_ZEROS，否则它只活在对话里，下次重跑又变成裸的 0。

文档站

站点用 mkdocs-material。构建分两步，不要跳过第一步：

py -3.9 tools/build_docs.py     # 生成暂存树 build-docs/
mkdocs build --strict           # 或 mkdocs serve 本地预览

为什么要有 build_docs.py。 mkdocs.yml 的 docs_dir 指向 build-docs/，那是仓库的镜像。 直接把 docs_dir 设成仓库根不行：根目录有 1.1 GB 的 paper/，而 mkdocs serve 不遵守 exclude_docs，本地预览会被拖垮。镜像的好处是每个文件与仓库里的相对位置一致， 全仓 900 多条相对链接一条都不用改写。脚本还会给每个卷生成一个落地页， 让 README 与正文里那些指向目录的链接（docs/01-基础概念/）在站点上也有落点。

版本必须钉住：

pip install "mkdocs-material==9.7.*" "mkdocs<2" jieba

• jieba 一定要装。 中文分词在构建期做（把词用零宽空格连起来），但包本身不带 jieba； 缺了它会静默退回英文式切分——搜索框看起来正常，中文却搜不到。
• search 插件不要写 lang: zh。 写了会报 Option search.lang 'zh' is not supported， 而这条警告会让 mkdocs build --strict 直接失败。中文支持由 theme.language: zh 装好。
• material 自 2025-11 转入维护模式（EOL 2026-11-05），9.7.* 是最后一个免费开放中文分词 的版本。已发布的静态站点不受影响，但升级是另一件事。

use_directory_urls 是关掉的，别改回去。 仓库里有一批指向目录的链接，mkdocs 不会重写它们； 开着目录化 URL 会给每个页面多加一层，这类链接就少一层而 404。

toc.slugify 也别删。 mkdocs 默认的 slugify 会走一遍 NFKD + encode('ascii')， 中文标题的 id 因此只剩数字（## 7. 思考题 → id="7"），正文里几十条 [§7 思考题](#7-思考题) 这类页内锚点会全部落空——页面照常构建，--strict 也不报错， 只有读者点了没反应。配上 slugify_unicode 之后锚点算法与 GitHub 一致， 站点锚点与 GitHub 锚点同名，同一份正文两边都能跳。

edit_uri 是 edit/main/，不带 docs/。 它拼在「相对 docs_dir」的页面路径前面， 而 build-docs/ 是仓库镜像：README 的页面路径就是 README.md，卷文档是 docs/xx.md。 写 edit/main/docs/ 会让 README 的「编辑此页」指向仓库里并不存在的 docs/README.md。

提交前先跑这三条：

py -3.9 tools/check_links.py       # 全仓相对链接
py -3.9 tools/check_nav.py         # mkdocs.yml 的 nav 与仓库文档是否对得上
py -3.9 tools/gen_en_index.py --check   # 英文总览页是否覆盖了全部文档

新增文档忘了加进 mkdocs.yml 的 nav，check_nav.py 会把缺的那篇直接打印出来。

线上站点由 CI 发布。 推到 main 之后，.github/workflows/ci.yml 里 docs job 会跑 build_docs.py 加 mkdocs gh-deploy --force，把站点推到 gh-pages 分支，GitHub Pages 从那里发布。 改完文档不用手动发站。想在本机看效果仍可手动来一遍：

py -3.9 tools/build_docs.py && mkdocs serve

改 workflow 文件要留意凭据 scope。 GitHub 规定推送 .github/workflows/ 下的文件必须用带 workflow scope 的凭据，而默认的 classic PAT 只有 gist, read:org, repo。缺了会看到 refusing to allow an OAuth App to create or update workflow ... without workflow scope。 补法：gh auth refresh -s workflow（设备授权，需账号本人在网页确认），再 gh auth setup-git 让 git 用上 gh 这份凭据——否则 git 仍走凭据管理器里那份旧的。

英文门面：README.en.md 是英文首页，docs/en/index.md 是英文文档总览 （每篇的英文标题 + 一句英文说明 + 链回中文正文）；正文不翻译。 总览页里的英文是人写的，所以 tools/gen_en_index.py 只校验、不重写： --check 比对「总览页链接到的文件」与「仓库里该被覆盖的文件」，缺谁点名谁； --write 只是把当前文档树摊成骨架打到 stdout，供初次撰写或大改时抄。 增删文档、改文件位置之后跑 --check；只改正文不必管。

---

行为准则

• 尊重所有贡献者
• 保持专业和友善的讨论
• 不发布侵权内容
• 不发布与项目无关的广告

---

联系方式

有任何问题？请提交 Issue 或通过 GitHub 联系。