three-audit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Three.js / R3F Audit

Three.js / R3F 审计

Purpose

目的

A curated catalog of WebGL performance and correctness checks for Three.js and React Three Fiber projects. Each check is one self-contained file describing what to look for, why it matters, and how to fix it. The skill walks you through running them against a target codebase and producing a structured findings report.

This is not a linter — most checks need contextual judgment, not just pattern-matching. The agent is expected to read the offending code and reason about whether the pattern actually applies in this scene.

Detection commands assume

rg

(ripgrep) and

jq

are on

PATH

. Substitute

grep -rn

and a manual read of

package.json

where they are not.

这是一份针对Three.js和React Three Fiber项目的WebGL性能与正确性检查清单。每项检查都是一个独立文件，说明检查内容、影响原因及修复方法。本技能将引导你针对目标代码库执行这些检查，并生成结构化的审计结果报告。

这不是代码检查工具（linter）——大多数检查需要结合上下文判断，而非仅依赖模式匹配。Agent需要阅读问题代码并分析该模式是否确实适用于当前场景。

检测命令假设环境变量

PATH

中已配置

rg

（ripgrep）和

jq

。若未配置，可替换为

grep -rn

并手动读取

package.json

。

When to Use This Skill

适用场景

Reviewing a 3D scene's performance, or before shipping a Three.js / R3F build
Investigating a frame-rate regression, especially one that tracks window size
Reviewing a change that touches renderer setup,
```
useFrame
```
, materials, shadows, instancing, or texture loading

审查3D场景性能，或在Three.js / R3F项目发布前进行检查
排查帧率下降问题，尤其是与窗口大小相关的帧率回归
审查涉及渲染器设置、
```
useFrame
```
、材质、阴影、实例化或纹理加载的代码变更

Workflow

工作流程

Step 1 — Confirm the project actually uses Three.js / R3F

步骤1 — 确认项目是否使用Three.js / R3F

bash

jq -r '
  ((.dependencies // {}) + (.devDependencies // {}) + (.peerDependencies // {}))
  | to_entries
  | map(select(.key | test("^(three$|@react-three/)")))
  | .[].key
' package.json 2>/dev/null

If nothing matches, stop and tell the user the audit doesn't apply.

bash

jq -r '
  ((.dependencies // {}) + (.devDependencies // {}) + (.peerDependencies // {}))
  | to_entries
  | map(select(.key | test("^(three$|@react-three/)")))
  | .[].key
' package.json 2>/dev/null

若没有匹配结果，停止操作并告知用户本审计不适用。

Step 2 — Find renderer entry points

步骤2 — 查找渲染器入口点

These are the anchors most checks key off of:

bash

undefined

这些是大多数检查的核心锚点：

bash

undefined

Vanilla Three.js renderer construction

原生Three.js渲染器构造

rg -n 'new\s+(THREE.)?WebGLRenderer\b' --type ts --type tsx --type js --type jsx

React Three Fiber Canvas mounts

React Three Fiber Canvas挂载

rg -n '<\s*Canvas\b' --type tsx --type jsx

R3F imperative GL access

R3F命令式GL访问

rg -n "useThree(|gl\s*[:=]" --type tsx --type jsx


Note the file paths — each check refers back to them.

rg -n "useThree(|gl\s*[:=]" --type tsx --type jsx


记录文件路径——每项检查都会引用这些路径。

Step 3 — Decide which conditional checks apply

步骤3 — 确定适用的条件检查项

The convention checks encode project conventions, not Three.js rules. Running them against a project that never adopted the convention produces noise, so activate each one only on its signal:

bash

undefined

约定检查项基于项目约定而非Three.js规则。若项目未采用相关约定，执行这些检查会产生无效结果，因此仅在检测到信号时激活对应检查项：

bash

undefined

useframe-priority — is a priority argument used anywhere?

useframe-priority — 是否使用了优先级参数？

rg -n 'useFrame([^)]},\s-?\d' --type tsx --type jsx

scene-dom-separation — is there a scene directory distinct from components?

scene-dom-separation — 是否存在与components目录分离的scene目录？

ls -d src/scene src/three src/webgl src/components 2>/dev/null

store-wiring — is there an external atom store?

store-wiring — 是否使用外部原子状态库？

jq -r '((.dependencies // {}) + (.devDependencies // {})) | keys[]' package.json 2>/dev/null
| rg 'nanostores|zustand|jotai|valtio'


No signal → skip that check and say so in the report's skipped list. Each check
file restates its own activation condition; follow that over this summary if
they disagree.

jq -r '((.dependencies // {}) + (.devDependencies // {})) | keys[]' package.json 2>/dev/null
| rg 'nanostores|zustand|jotai|valtio'


若无信号→跳过该检查项，并在报告的跳过列表中说明。每个检查文件都会重新说明其激活条件，若与本摘要冲突，以检查文件中的条件为准。

Step 4 — Run checks from the catalog

步骤4 — 执行清单中的检查项

For each row in the Checks tables below, open

references/checks/<name>.md

and follow its detection and assessment guidance. If the user passed

--check=<name>

, run only that one.

Read every candidate site before reporting it. Most checks list legitimate uses of the pattern they detect — a grep hit is a candidate, not a finding.

对于下方检查项表格中的每一行，打开

references/checks/<name>.md

并遵循其检测和评估指南。若用户传入

--check=<name>

，则仅执行该检查项。

在报告前需阅读所有候选代码位置。大多数检查项会列出检测模式的合法使用场景——grep命中仅为候选，而非确定问题。

Step 5 — Report findings

步骤5 — 报告审计结果

Group findings by severity (

high

medium

low

) and emit one section per check that produced a finding. Format:

markdown

undefined

按严重程度（

high

、

medium

、

low

）分组结果，每个产生结果的检查项对应一个章节。格式如下：

markdown

undefined

<check-name> — <severity>

<检查项名称> — <严重程度>

Where: <file>:<line> [+ more]

What's wrong: <one sentence>

Suggested fix: ```<lang> <canonical pattern> ```

Why it matters: <one sentence on the user-visible impact>


Each check file ends with a **How to report this finding** section — use its
wording so findings from different checks read consistently.

Skip checks that produced no finding (don't pad the report). End with a tally:
`<N> findings: <high> high, <medium> medium, <low> low`, followed by one line
naming any conditional checks skipped for lack of a signal.

位置: <文件>:<行号> [更多位置]

问题描述: <一句话说明>

建议修复方案: ```<语言> <标准修复代码> ```

影响说明: <一句话说明对用户的可见影响>


每个检查文件末尾都有**如何报告该结果**章节——使用其中的表述，确保不同检查项的结果报告风格一致。

跳过未产生结果的检查项（不要填充报告）。结尾添加统计信息：`<N> 项问题: <high> 高风险, <medium> 中风险, <low> 低风险`，随后用一行说明因无信号而跳过的条件检查项。

Lens Mode

透镜模式

review:changes-review

invokes this skill as a stack lens when the diff touches Three.js or R3F files. In that mode:

The caller supplies the scope. Audit exactly the files it resolved and no more — a whole-scene audit returns findings the run cannot attribute to the change
Skip Step 1's project detection; the caller already matched on the imports
Return findings in the shape the caller asked for, not the report format above
Conditional convention checks map to the caller's lowest severity

Standalone invocation is unaffected and stays the primary path.

当代码变更涉及Three.js或R3F文件时，

review:changes-review

会将本技能作为堆栈透镜调用。在此模式下：

调用方会提供检查范围。仅审计其指定的文件，不要进行全场景审计（否则会返回无法归因于本次变更的结果）
跳过步骤1的项目检测——调用方已通过导入匹配确认项目类型
按照调用方要求的格式返回结果，而非上述报告格式
条件约定检查项映射为调用方指定的最低严重程度

独立调用不受影响，仍遵循主流程。

Checks

检查项

Catalog of checks. Each one is defined in

references/checks/<name>.md

检查项清单。每个检查项都定义在

references/checks/<name>.md

中。

Performance and correctness

性能与正确性

Check	Topic	Severity
`dpr-cap`	Cap `devicePixelRatio` by a pixel budget so Retina/fullscreen doesn't quadruple GPU fillrate	High (perf)
`fillrate-overdraw`	Stacked transparency and post-processing passes shading the same pixels many times over	High (perf)
`render-loop-allocations`	`new Vector3` and friends inside `useFrame` , producing GC hitches	High (perf)
`resource-disposal`	Geometries, materials, textures, and render targets leaking VRAM without `.dispose()`	High (memory)
`useframe-workload`	`setState` , scene lookups, and raycasts running every frame when they don't need to	High (perf)
`asset-reuse`	A distinct geometry/material per object where one shared instance would do	Medium (perf/memory)
`instancing`	Hundreds of identical meshes that should be one `InstancedMesh`	Medium (perf)
`shadow-cost`	Shadow map resolution, casting light count, and shadow cameras fitted to nothing	Medium (perf)
`material-recompiles`	Shader-define changes at runtime causing main-thread GLSL recompiles	Medium (perf)
`texture-budget`	Oversized or uncompressed textures, wrong colour space, mipmaps disabled	Medium (memory/perf)
`frustum-culling`	Culling disabled, stale bounding volumes, or one merged mesh spanning the scene	Medium (perf)

检查项	主题	严重程度
`dpr-cap`	通过像素预算限制 `devicePixelRatio` ，避免Retina/全屏场景下GPU填充率飙升至4倍	高（性能）
`fillrate-overdraw`	堆叠的透明效果和后期处理通道导致同一像素被多次着色	高（性能）
`render-loop-allocations`	在 `useFrame` 内执行 `new Vector3` 等操作，导致GC卡顿	高（性能）
`resource-disposal`	几何体、材质、纹理和渲染目标未调用 `.dispose()` 导致VRAM泄漏	高（内存）
`useframe-workload`	`setState` 、场景查找和射线检测在每帧执行，但实际无需频繁运行	高（性能）
`asset-reuse`	每个对象使用独立的几何体/材质，而实际上可共享单个实例	中（性能/内存）
`instancing`	数百个相同网格应合并为一个 `InstancedMesh`	中（性能）
`shadow-cost`	阴影贴图分辨率、投射光源数量及阴影相机设置不合理	中（性能）
`material-recompiles`	运行时修改着色器定义导致主线程GLSL重新编译	中（性能）
`texture-budget`	纹理尺寸过大、未压缩、颜色空间错误或禁用mipmaps	中（内存/性能）
`frustum-culling`	剔除功能禁用、边界盒过期或单个合并网格覆盖整个场景	中（性能）

Project conventions (conditional)

项目约定（条件性）

Run only when Step 3 found the activation signal.

Check	Topic	Severity
`store-wiring`	Atom store reads that don't subscribe, and unbatched related writes	Medium (perf/convention)
`useframe-priority`	Gameplay at priority 1, effects at priority 2, so effects don't sample stale transforms	Medium (correctness/convention)
`scene-dom-separation`	3D components under `src/scene/` , DOM/HUD under `src/components/` , never mixed in one file	Low (convention)

仅在步骤3检测到激活信号时执行。

检查项	主题	严重程度
`store-wiring`	原子状态库读取未订阅，以及相关写入未批量处理	中（性能/约定）
`useframe-priority`	游戏逻辑优先级设为1，特效优先级设为2，避免特效采样过时变换	中（正确性/约定）
`scene-dom-separation`	3D组件放在 `src/scene/` ，DOM/HUD放在 `src/components/` ，禁止在同一文件混合	低（约定）

Severity Guide

严重程度指南

High — measurable frame-rate or memory impact under realistic load, or a correctness bug that ships visible artifacts. Worth fixing before release.
Medium — perf hit on stress paths or older hardware, or a fragile pattern that's likely to break later. Worth scheduling.
Low — minor cleanup, style nit, or a pattern that's only suspect in unusual scenes. Note it; don't block on it.

The severity in the table is the check's default. Adjust it for the scene you are looking at and say why — 300 unshared materials in a 12-object scene is still low.

高风险 — 在实际负载下可测量到帧率或内存影响，或存在会导致可见缺陷的正确性问题。发布前必须修复。
中风险 — 在压力场景或旧硬件上存在性能损耗，或属于易出问题的脆弱模式。需安排修复。
低风险 — 轻微清理项、风格问题，或仅在特殊场景下存在风险的模式。记录即可，无需阻塞发布。

表格中的严重程度为检查项的默认值。可根据当前场景调整，并说明原因——例如在仅含12个对象的场景中，300个未共享材质仍属于低风险。

Adding a New Check

添加新检查项

Create
```
references/checks/<name>.md
```
using the existing checks as a template. Required sections: What it is, Why it matters, How to detect, Anti-patterns, Canonical fix, Notes, and How to report this finding.
Append a row to the appropriate Checks table above with topic and severity.
If the check is conditional on a project convention, state the activation signal in a
```
**Conditional:**
```
line in its header block and add the detection command to Step 3.
If the check needs special detection (beyond grep + read), describe it in the check file itself rather than baking shell scripts into the skill — keeps each check portable across Claude / Codex / future hosts.

以现有检查项为模板，创建
```
references/checks/<name>.md
```
。必填章节：检查内容、影响原因、检测方法、反模式、标准修复方案、注意事项和如何报告该结果。
在上方对应的检查项表格中添加一行，包含主题和严重程度。
若检查项为基于项目约定的条件性检查，在其头部块中添加
```
**条件:**
```
行说明激活信号，并将检测命令添加到步骤3中。
若检查项需要特殊检测（超出grep+人工阅读），在检查文件中说明，而非将shell脚本硬编码到技能中——确保每个检查项可在Claude/Codex/未来宿主环境中移植。

Out of Scope

超出范围

GLSL shader correctness (covered by shader-specific tooling)
Model authoring — mesh topology, UV layout, rigging, DCC export settings
Browser-level perf tracing (use Chrome DevTools / Spector.js directly)
General React patterns — effects, memoization, state architecture (use
```
react-audit
```
; this skill only covers React as it meets the Canvas)

The audit reads the JS/TS source. The one exception is

texture-budget

, which also sizes the texture files on disk, because how a texture is delivered — dimensions, format, colour space — is a renderer concern that the source alone cannot answer. How it was authored is not.

GLSL着色器正确性（由着色器专用工具覆盖）
模型创作——网格拓扑、UV布局、绑定、DCC导出设置
浏览器级性能追踪（直接使用Chrome DevTools / Spector.js）
通用React模式——副作用、 memoization、状态架构（使用
```
react-audit
```
；本技能仅覆盖与Canvas交互的React部分）

本审计仅读取JS/TS源码。唯一例外是

texture-budget

，它还会检查磁盘上的纹理文件大小，因为纹理的交付方式——尺寸、格式、颜色空间——属于渲染器相关问题，仅通过源码无法完全判断。但纹理的创作方式不在本审计范围内。