# NCCL 深度教程文章规范

本规范用于新版 36 章 NCCL 专家课程。文章不是环境记录或日志摘抄，而是一份可以独立完成学习、复现和验收的技术教程。

## 1. 每篇文章必须回答的五个问题

1. 这个机制解决什么问题，不存在它会怎样？
2. 数据、控制状态和同步信号分别如何流动？
3. NCCL 2.22.3 的真实源码在哪里做出关键决策？
4. 哪个实验可以证伪我们对源码的理解？
5. 结论在哪些版本、硬件和 workload 上成立？

## 2. 固定文章结构

```text
1. 本章问题与学习目标
2. 前置知识
3. 心智模型、数据布局、公式或状态机
4. 运行前假设与可证伪预测
5. 源码调用链总览
6. 关键源码原文、逐段注释和分支分析
7. 实验设计：自变量、控制变量、观测量、正确性 oracle
8. 完整可运行脚本与命令
9. 原始结果、统计表和路径证据
10. 用源码解释结果
11. 反例、常见误判和生产场景
12. 版本/硬件边界
13. 本章结论
14. 练习与验收题
```

## 技术图示规范

- 当对象关系、拓扑、时序、状态迁移、内存布局或数据流仅靠文字难以建立稳定心智模型时，必须配图。
- 图必须标明它表达的是 API 语义、源码实现、逻辑模型还是实测观测，不能把逻辑汇聚节点画成真实中心设备。
- rank、peer、方向、chunk、count 和状态名称必须能回到正文公式、源码摘录或实验输出核对。
- 优先使用可审查、可版本化的 Mermaid/SVG；生成式位图只用于不承担精确技术语义的封面或概念插画。
- 宽图必须放进 `diagram-scroll` 容器，移动端保持可读字号并在图内滚动，不能把整页撑宽。
- 按渲染后长宽比选择 `diagram-scroll--wide`（72rem）、`--xwide`（96rem）或 `--xxwide`（168rem）；以正文可读字号为准，不能为了消除滚动把十几个节点压成缩略图。
- 每次部署必须在 Chromium 中检查 SVG 数量、Mermaid 语法错误、MathJax 错误和页面横向溢出。

## 3. 源码展示规范

每段源码必须包含以下元数据：

```text
仓库：NVIDIA/nccl
版本：v2.22.3-1
提交：178b6b7
文件：src/...
符号：function / struct / enum
行号：以该提交为准
```

正文同时展示两层内容：

1. **原始源码**：裁剪到能保留语义的最小连续片段，不改变量名和条件。
2. **注释版源码**：复制同一片段并加入 `// [课程注释]`，明确注释不是上游代码。

### 3.1 证据标签必须准确

- `原始源码` 只用于固定 commit 中逐字可核对的连续片段，不能插入未说明的 `...`，也不能把伪代码混入其中。
- 裁掉函数参数、条件分支、错误处理或中间语句时，必须改称 `关键源码摘录` 或 `关键执行路径摘录`，并在标题中写明省略内容。
- public header、plugin ABI、函数指针表和 forward declaration 必须标成 `接口声明` 或 `ABI 声明`，不能称为函数实现。
- 如果实现位于当前开源仓库，接口声明后必须继续展示可执行函数体、决定性状态字段和下一跳调用。
- 如果实现属于闭源 vendor plugin 或硬件 fabric，必须明确源码证据边界，并展示 NCCL 侧的能力门控与实际函数指针调用位置。
- 只给文件路径和符号名属于导航信息，不属于实现证据。

### 3.2 “展示实现”的最低闭环

一段实现分析至少回答：

```text
caller
  -> executable function body
  -> decisive arguments/state mutation
  -> next-hop call
  -> experiment-visible log/trace/result
```

只贴函数声明、结构体定义或宏入口不能单独证明运行时行为。它们可以用于解释契约和 ABI，
但必须准确标注证据类型。

源码之后必须分析：

- 输入、输出和被修改的状态。
- 关键结构体字段的生命周期。
- 每个重要条件分支为何存在。
- 调用者和下一层被调用函数。
- 实验配置会命中哪个分支，以及日志如何证明。

禁止只列路径、只贴函数名、整文件复制，或贴代码后不解释。

## 4. 源码版本原则

- 本机行为使用 `third_party/nccl-2.22.3@178b6b7` 解释。
- 2026 年 master 只放在“版本演进”小节，不能倒推 2.22.3 行为。
- PyTorch 文章记录当前构建 commit，并固定 `ProcessGroupNCCL`、Reducer 和 FSDP 对应源码版本。
- 行号可能随版本变化，因此函数符号和 commit 是主定位键。

## 5. 实验最低要求

- 一个正确性实验：CPU reference、逐元素断言或 `#wrong == 0`。
- 一个机制实验：通过日志、trace 或源码插桩证明实际执行路径。
- 一个参数实验：主要自变量至少三个取值，其他条件固定。
- 一个反例实验：禁用机制、错误配置或故障注入。
- 正式性能数据至少五次独立运行；基线章节至少十次。
- 输出 median、P95、CV、原始值和样本数；CV 大于 5% 不下精确性能结论。

## 6. 结论强度

文章结论使用以下措辞：

- **源码证明**：条件分支和数据流可从固定版本源码直接推出。
- **本机实验验证**：当前硬件上有正确性、路径和统计证据。
- **合理推断**：证据间接且明确写出推断过程。
- **尚未验证**：缺少 RDMA、NVSwitch 或其他必要硬件。

不允许把“源码存在这个能力”写成“当前环境已启用”，也不允许把单次最快结果写成稳定收益。

## 7. 完成定义

一章只有同时满足以下条件才标记为 `VALIDATED`：

- 博客正文通过结构检查。
- 源码片段、commit、符号和行号可复核。
- 实验脚本可独立运行并具有 `--help` 或顶部用法说明。
- manifest、raw、summary.csv 和 summary.md 完整。
- 结论可由结果重算。
- Jekyll 构建成功，公网文章和附件均返回 200。