光照知识库·写作规范
本规范适用于团队光照知识库（OpenGL 2D/3D 光照）的所有文档撰写，
目标：让任何团队成员都能读懂概念、拿来即用代码。
一、文档类型
每篇文档属于且只属于其中一种类型，禁止混写。
| 类型 | 目的 | 标志性问题 |
|---|---|---|
| 概念理解型 | 搞懂"是什么"和"为什么" | 为什么漫反射会均匀散射？ |
| 实现参考型 | 搞定"怎么做" | 如何在 OpenGL 里配置点光源？ |
同一个主题（如"漫反射"）可以有两篇文档，分属两种类型。
二、思维导师分配
每篇文档由对应导师的方法论驱动写作风格，导师名字不出现在标题和正文中。
| 主题 | 导师 | 核心方法 |
|---|---|---|
| 颜色原理、色彩空间、线性工作流 | 费曼 | 第一性原理——从光的物理本质推导 |
| 光照模型（环境光/漫反射/镜面） | 福尔摩斯 | 观察真实光行为，归纳出公式规律 |
| Phong / Blinn-Phong 着色 | 狄仁杰 | 层层递进，拆解三个分量如何叠加 |
| 阴影（Shadow Map、PCF） | 包青天 | 深度测试即判案，通过/不通过 |
| 法线贴图、切线空间 | 柯南 | 真相只有一个——变换矩阵消去表象 |
| PBR / 微表面理论 | 费曼 | 能量守恒、物理第一原理 |
| 2D 光照（精灵法线图） | 狄仁杰 | 层层递进：精灵→法线→光源叠加 |
| OpenGL API / 光照管线配置 | 包青天 | 规则严明，配错即黑屏 |
三、每篇文档的固定结构
1. 导师引入 —— 用类比或场景建立直觉，不超过 100 字
2. 原理推导 —— 概念 + 公式（可视化优先，公式辅助）
3. 实现示例 —— 完整可运行的 OpenGL/GLSL 代码 + 关键行注释
4. 验证检查 —— "应该看到 X；若没有，检查 Y"
5. 延伸思考 —— 1~2 个开放问题，供团队讨论，不要求写答案概念理解型文档：重点在 1、2，3 作为辅助示意。
实现参考型文档：重点在 3、4，1 只需一句话交代背景。
四、写作前置流程（大纲先行）
适用条件：话题宽泛、用户用"等""相关知识""全面介绍"等词时，必须先出大纲。
步骤 1 · 生成完整话题树
列出该主题下所有应该覆盖的子话题，不只是用户明确提到的。
格式：二级树形结构，每项一行。
步骤 2 · 等待用户确认
说明：「以下是完整话题树，请确认要写哪些，或补充遗漏的。」
用户可以删减、合并、新增。
步骤 3 · 按确认后的范围写内容
不得遗漏已确认的任何子话题。话题树示例（颜色相关知识）：
颜色
├── 物理本质（电磁波、视锥细胞）
├── 颜色格式
│ ├── RGB（整数 / 浮点）
│ ├── RGBA 与 Alpha 通道
│ ├── HSV / HSL
│ ├── Lab / XYZ（感知均匀色彩空间）
│ └── YUV（视频领域）
├── 色彩空间与 Gamma
│ ├── sRGB vs 线性空间
│ ├── Gamma 校正原理
│ ├── 色域（sRGB / P3 / Rec.2020）
│ └── 颜色深度与色带（banding）
├── 亮度与感知
│ ├── 感知亮度公式（BT.709）
│ ├── 亮度 vs 明度 vs 辉度
│ └── 人眼对颜色的敏感度差异
├── 光对颜色的影响
│ ├── 光与物体颜色的乘法关系
│ ├── 色温（暖光 / 冷光 / 开尔文）
│ └── 白平衡与色适应
├── GLSL 中的颜色操作
│ ├── 变亮 / 变暗
│ ├── 饱和度调整
│ ├── 颜色插值（线性空间 vs sRGB 的陷阱）
│ ├── 曝光（Exposure）
│ ├── HDR 与 Tone Mapping（Reinhard / 指数 / ACES）
│ ├── 混合模式（正片叠底、滤色、叠加等）
│ └── LUT 颜色分级
└── 其他
├── Premultiplied Alpha vs Straight Alpha
└── 颜色对比度与可访问性五、核心约束
约束 1 · 主动扩展，不只写用户提到的
用户的提示是起点，不是终点。
生成大纲时，必须主动识别该主题下所有相关子话题，
包括用户未明确提及但属于该知识域的内容。
禁止"用户没说到就不写"的被动姿态。
约束 2 · 代码必须完整可运行
每段代码要么自含完整上下文，要么明确标注：
glsl
// 需配合：顶点着色器传入 fragPos、normal 变量不确定能否运行的代码，标注 // 待验证，禁止静默省略。
约束 3 · 概念先于代码
即使是实现参考型，第一段也必须用一句话说清楚"这段代码在做什么"，
禁止文档以代码块开头。
约束 4 · 是什么 vs 怎么做 不混写
单篇文档只回答一个问题。需要两个答案时，拆成两篇，互相链接。
约束 5 · 不写推测性内容
文档生成后自检：删除任何"可能""也许""一般来说"开头的推测性表述。
不确定的内容标注 [待确认] 并指定负责人。
约束 6 · 面向零前置知识的团队成员
每篇文档假设读者不熟悉该主题。专业术语首次出现时用括号给出一句话解释。
六、语言风格规范
- 句子：短句优先，单句不超过 30 字
- 类比：每个抽象概念至少配一个生活类比（费曼技巧）
- 代码注释：只注释"为什么"，不注释"是什么"（变量名已经说明）
- 标题：用动词或疑问句，如"漫反射为什么不随视角变化？"而非"漫反射介绍"
- 禁止：大段背景铺垫、"首先……其次……最后……"套话、未经验证的最佳实践
七、快速模板
概念理解型
# 理解：[概念]
> [用导师方法论建立直觉的引入句，不提导师名]
## 原理
[公式/图示/推导]
## 用代码看懂它
[辅助理解的最小代码示例]
## 验证你理解了
[1~2 个延伸思考问题]实现参考型
# 如何实现：[功能]
> 本文完成 [具体功能]，读完你将得到可运行的 [X] 代码。
## 完整实现
[代码 + 关键行注释]
## 验证结果
你应该看到：[预期现象]
如果没有，检查：[常见问题清单]
## 延伸
[相关文档链接]
评论