threejs-study-notes

name	threejs-study-notes
description	Generate structured Markdown study notes for Three.js WebGPU / TSL learning. Reads source files (HTML examples, JS modules, src/ code), traces API definitions, and outputs a note with optional Mermaid diagrams, Props/API tables, code snippets, principles, Q&A, and related references. Use when the user asks to take notes, summarize, or document a Three.js / WebGPU / TSL file or concept.

Three.js Study Notes Generator

为 Three.js WebGPU / TSL 学习过程产出结构化 Markdown 笔记。

When to Use

• 用户指定一个或多个文件（HTML 示例、.js 模块、src/ 源码）并要求产出学习笔记
• 用户要求总结某个 WebGPU / TSL 概念
• 用户在对话中提了多个问题，要求汇总为笔记

Execution Steps

Step 1 — Identify Input

确认用户指定的文件路径。可以是：

• examples/*.html（Three.js 官方示例）
• examples/jsm/**/*.js（addon / TSL 模块）
• src/**/*.js（Three.js 核心源码）
• 任意其他与 Three.js 相关的文件

Step 2 — Read & Analyze

1. Read the target file(s).
2. Identify key concepts: What does this file demonstrate? What APIs / props are involved?
3. Trace source: Use Grep to search src/ for API definitions, default values, and doc comments of the key props/classes found in Step 2. This provides authoritative information.
4. Collect Q&A: If the user asked questions in the conversation, include them. Also generate 2–3 common follow-up questions.

Step 3 — Mermaid（可选）

不要把 Mermaid 当作必选项。仅在「流程、管线、多组件数据流、生命周期」等用一张图能明显省字、省脑时再画。

建议省略 Mermaid 的情况包括：

• 笔记主体是 Props / API 罗列、字段表、默认值对照
• 用户只要 某一段具体 demo / 代码用法 的说明，没有复杂拓扑
• 内容用 几段话 + 代码 已经完整，硬画流程图没有增量

可以保留 Mermaid 的情况包括：

• 初始化顺序、多视图对照、渲染循环与外部系统的 时序
• 多个子系统之间的 数据流（例如 post-processing chain）
• 类/模块 关系 或状态机，表格式反而难读

若决定生成：根据内容选 一种 图（下表），每篇笔记最多一张，节点数建议少于 15。

Content Pattern	Recommended Diagram
Initialization / lifecycle	flowchart TD
Data flow between components	flowchart LR
Render pipeline / sequence	sequenceDiagram
Class / component relationships	classDiagram
Concept comparison / taxonomy	mindmap
State transitions	stateDiagram-v2

Step 4 — Generate Note

按下方 模板 组织内容；跳过 Step 3 未采用的章节（例如无 Mermaid 时删除「### Mermaid」整节，不要留标题或空代码块）。顶层标题从 ## 起。

Language rule: prose in Simplified Chinese (简体中文), tables / code / API names in English.

Step 5 — Save

Save to: docs/notes/<topic-name>.md

• <topic-name>: kebab-case English describing the core topic (e.g. logarithmic-depth-buffer, tsl-post-processing, compute-particles)
• If docs/notes/ does not exist, create it.

Step 6 — Inform User

Tell the user where the note was saved, and briefly list what's in it.

---

Note Template

## <Topic Title>

对应文件：`<source file path(s)>`

---

### Mermaid

<!-- 仅当 Step 3 判断「画图有净收益」时保留本节；否则整节删除（含标题），不要留空壳。 -->

```mermaid
<chosen diagram>
```

---

### Props / API

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| ... | ... | ... | ... |

---

### Code

#### Minimal Usage

```javascript
// shortest working snippet
```

#### Usage in This Example

```javascript
// how the example file uses it, with key lines annotated
```

---

### Principle

<Deep explanation: math, GPU pipeline, design rationale, trade-offs.
Use LaTeX formulas with $...$ for inline and $$...$$ for block. NEVER use \(...\) or \[...\] — Typora may not render them.>

---

### Q&A

**Q1: ...**

**A:** ...

**Q2: ...**

**A:** ...

---

### Related

- Source: `<path to relevant src/ file>`
- Examples: `<related example files>`
- Docs / external: `<links>`

---

Conventions

1. Simplified Chinese — all Chinese prose MUST be 简体中文. Never use 繁体.
2. LaTeX — use $...$ for inline math, $$...$$ for block math. NEVER use \(...\) or \[...\].
3. One note per topic — don't merge unrelated topics into one file.
4. Mermaid diagrams — optional（见 Step 3）。若生成：使用 mermaid 代码围栏，每篇最多一张，节点建议少于 15；不需要时整节省略，不要写「无图」占位。
5. Code snippets — show the minimal working version first, then the example-specific version.
6. Q&A — include user's actual questions from the conversation, plus 2–3 anticipated follow-ups.
7. Props table — trace to src/ for authoritative type/default info; don't guess.
8. Heading level — top-level sections use ##, sub-sections use ###. Never use #.

Example Output

See docs/notes/logarithmic-depth-buffer.md (generated from examples/webgpu_camera_logarithmicdepthbuffer.html) as a reference for the expected output style and structure.