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