@baimingtao/lbs-agent 1.0.0

package/extensions/skills/builtin/creative/p5js/references/troubleshooting.md

@@ -0,0 +1,532 @@
+# 故障排查
+
+## Performance
+
+### Step Zero — 禁用 FES
+
+Friendly Error System (FES) 会增加大量开销——导致高达 10 倍的性能下降。在每个生产环境的 sketch 中都应禁用它：
+
+```javascript
+// BEFORE any p5 code
+p5.disableFriendlyErrors = true;
+
+// Or use p5.min.js instead of p5.js — FES is stripped from minified build
+```
+
+### Step One — pixelDensity(1)
+
+Retina/HiDPI 显示器默认具有 2 倍或 3 倍的密度，这会将像素数量增加 4 到 9 倍：
+
+```javascript
+function setup() {
+  pixelDensity(1);        // force 1:1 — always do this first
+  createCanvas(1920, 1080);
+}
+```
+
+### 在 Hot Loops 中使用 Math.*
+
+p5 的 `sin()`、`cos()`、`random()`、`min()`、`max()`、`abs()` 都是带有额外开销的包装函数。在 hot loops（每帧数千次迭代）中，请使用原生的 `Math.*`：
+
+```javascript
+// SLOW — p5 wrappers
+for (let p of particles) {
+  let a = sin(p.angle);
+  let d = dist(p.x, p.y, mx, my);
+}
+
+// FAST — native Math
+for (let p of particles) {
+  let a = Math.sin(p.angle);
+  let dx = p.x - mx, dy = p.y - my;
+  let dSq = dx * dx + dy * dy;  // skip sqrt entirely
+}
+```
+
+在进行距离比较时，请使用 `magSq()` 而不是 `mag()`——这样可以避免开销昂贵的 `sqrt()`。
+
+### 诊断
+
+打开 Chrome DevTools > Performance 标签页 > 在 sketch 运行时进行 Record（录制）。
+
+常见的性能瓶颈：
+1. **FES 已启用** —— 每次 p5 函数调用都会产生 10 倍的开销
+2. **pixelDensity > 1** —— 像素数量增加 4 倍，速度慢 4 倍
+3. **过多的 draw calls** —— 每帧执行数千次 `ellipse()`、`rect()`
+4. **大画布 + 像素操作** —— 在 4K 画布上执行 `loadPixels()`/`updatePixels()`
+5. **未经优化的粒子系统** —— 检查所有粒子之间的距离 (O(n^2))
+6. **内存泄漏** —— 每帧创建对象而不进行清理
+7. **Shader 编译** —— 在 `draw()` 而不是 `setup()` 中调用 `createShader()`
+8. **在 draw() 中执行 console.log()** —— 每帧写入 DOM，严重破坏性能
+9. **在 draw() 中操作 DOM** —— 布局抖动（比 canvas 操作慢 400-500 倍）
+
+### 解决方案
+
+**减少 draw calls：**
+```javascript
+// BAD: 10000 individual circles
+for (let p of particles) {
+  ellipse(p.x, p.y, p.size);
+}
+
+// GOOD: single shape with vertices
+beginShape(POINTS);
+for (let p of particles) {
+  vertex(p.x, p.y);
+}
+endShape();
+
+// BEST: direct pixel manipulation
+loadPixels();
+for (let p of particles) {
+  let idx = 4 * (floor(p.y) * width + floor(p.x));
+  pixels[idx] = p.r;
+  pixels[idx+1] = p.g;
+  pixels[idx+2] = p.b;
+  pixels[idx+3] = 255;
+}
+updatePixels();
+```
+
+**用于邻居查询的空间哈希（Spatial hashing）：**
+```javascript
+class SpatialHash {
+  constructor(cellSize) {
+    this.cellSize = cellSize;
+    this.cells = new Map();
+  }
+
+  clear() { this.cells.clear(); }
+
+  _key(x, y) {
+    return `${floor(x / this.cellSize)},${floor(y / this.cellSize)}`;
+  }
+
+  insert(obj) {
+    let key = this._key(obj.pos.x, obj.pos.y);
+    if (!this.cells.has(key)) this.cells.set(key, []);
+    this.cells.get(key).push(obj);
+  }
+
+  query(x, y, radius) {
+    let results = [];
+    let minCX = floor((x - radius) / this.cellSize);
+    let maxCX = floor((x + radius) / this.cellSize);
+    let minCY = floor((y - radius) / this.cellSize);
+    let maxCY = floor((y + radius) / this.cellSize);
+
+    for (let cx = minCX; cx <= maxCX; cx++) {
+      for (let cy = minCY; cy <= maxCY; cy++) {
+        let key = `${cx},${cy}`;
+        let cell = this.cells.get(key);
+        if (cell) {
+          for (let obj of cell) {
+            if (dist(x, y, obj.pos.x, obj.pos.y) <= radius) {
+              results.push(obj);
+            }
+          }
+        }
+      }
+    }
+    return results;
+  }
+}
+```
+
+**对象池（Object pooling）：**
+```javascript
+class ParticlePool {
+  constructor(maxSize) {
+    this.pool = [];
+    this.active = [];
+    for (let i = 0; i < maxSize; i++) {
+      this.pool.push(new Particle(0, 0));
+    }
+  }
+
+  spawn(x, y) {
+    let p = this.pool.pop();
+    if (p) {
+      p.reset(x, y);
+      this.active.push(p);
+    }
+  }
+
+  update() {
+    for (let i = this.active.length - 1; i >= 0; i--) {
+      this.active[i].update();
+      if (this.active[i].isDead()) {
+        this.pool.push(this.active.splice(i, 1)[0]);
+      }
+    }
+  }
+}
+```
+
+**对开销大的操作进行节流（Throttle）：**
+```javascript
+// Only update flow field every N frames
+if (frameCount % 5 === 0) {
+  flowField.update(frameCount * 0.001);
+}
+```
+
+### 帧率目标
+
+| 场景 | 目标 | 可接受范围 |
+|---------|--------|------------|
+| 交互式 sketch | 60fps | 30fps |
+| 环境动画 | 30fps | 20fps |
+| 导出/录制 | 30fps 渲染 | 任意（离线） |
+| 移动设备 | 30fps | 20fps |
+
+### 逐像素渲染预算
+
+像素级操作（`loadPixels()` 循环）是开销最大的常见模式。预算取决于画布大小和每个像素的计算量。
+
+| 画布 | 像素 | 简单噪声（1 次调用） | fBM（4 八度） | Domain warp（3 层 fBM） |
+|--------|--------|----------------------|----------------|--------------------------|
+| 540x540 | 291K | ~5ms | ~20ms | ~80ms |
+| 1080x1080 | 1.17M | ~20ms | ~80ms | ~300ms+ |
+| 1920x1080 | 2.07M | ~35ms | ~140ms | ~500ms+ |
+| 3840x2160 | 8.3M | ~140ms | ~560ms | 会崩溃 |
+
+**经验法则：**
+- 在 1080x1080 分辨率下，每个像素 1 次 `noise()` 调用 = ~20ms/帧（在 30fps 下尚可）
+- 在 1080x1080 分辨率下，每个像素进行 4 八度 fBM = ~80ms/帧（处于临界点）
+- 在 1080x1080 分辨率下，多层 domain warp = 300ms+（对于实时渲染来说太慢，但对于 `noLoop()` 导出来说没问题）
+- **对于像素操作，Headless Chrome 比桌面端 Chrome 慢 2-5 倍**
+
+**解决方案：以较低分辨率渲染，填充块：**
+```javascript
+let step = 3;  // render 1/9 of pixels, fill 3x3 blocks
+loadPixels();
+for (let y = 0; y < H; y += step) {
+  for (let x = 0; x < W; x += step) {
+    let v = expensiveNoise(x, y);
+    for (let dy = 0; dy < step && y+dy < H; dy++)
+      for (let dx = 0; dx < step && x+dx < W; dx++) {
+        let i = 4 * ((y+dy) * W + (x+dx));
+        pixels[i] = v; pixels[i+1] = v; pixels[i+2] = v; pixels[i+3] = 255;
+      }
+  }
+}
+updatePixels();
+```
+
+Step=2 可带来 4 倍的加速。Step=3 可带来 9 倍的加速。在 1080p 下可见，但在视频中可以接受（运动可以掩盖它）。
+
+## 常见错误
+
+### 1. 忘记重置 blend mode
+
+```javascript
+blendMode(ADD);
+image(glowLayer, 0, 0);
+// WRONG: everything after this is ADD blended
+blendMode(BLEND);  // ALWAYS reset
+```
+
+### 2. 在 draw() 中创建对象
+
+```javascript
+// BAD: creates new font object every frame
+function draw() {
+  let f = loadFont('font.otf');  // NEVER load in draw()
+}
+
+// GOOD: load in preload, use in draw
+let f;
+function preload() { f = loadFont('font.otf'); }
+```
+
+### 3. 在进行 transform 时没有使用 push()/pop()
+
+```javascript
+// BAD: transforms accumulate
+translate(100, 0);
+rotate(0.1);
+ellipse(0, 0, 50);
+// Everything after this is also translated and rotated
+
+// GOOD: isolated transforms
+push();
+translate(100, 0);
+rotate(0.1);
+ellipse(0, 0, 50);
+pop();
+```
+
+### 4. 使用整数坐标以获得清晰的线条
+
+```javascript
+// BLURRY: sub-pixel rendering
+line(10.5, 20.3, 100.7, 80.2);
+
+// CRISP: integer + 0.5 for 1px lines
+line(10.5, 20.5, 100.5, 80.5);  // on pixel boundary
+```
+
+### 5. 像素密度混淆
+
+```javascript
+// WRONG: assuming pixel array matches canvas dimensions
+loadPixels();
+let idx = 4 * (y * width + x);  // wrong if pixelDensity > 1
+
+// RIGHT: account for pixel density
+let d = pixelDensity();
+loadPixels();
+let idx = 4 * ((y * d) * (width * d) + (x * d));
+
+// SIMPLEST: set pixelDensity(1) at the start
+```
+
+### 6. 颜色模式混淆
+
+```javascript
+// In HSB mode, fill(255) is NOT white
+colorMode(HSB, 360, 100, 100);
+fill(255);  // This is hue=255, sat=100, bri=100 = vivid purple
+
+// White in HSB:
+fill(0, 0, 100);  // any hue, 0 saturation, 100 brightness
+
+// Black in HSB:
+fill(0, 0, 0);
+```
+
+### 7. WebGL 的原点在中心
+
+```javascript
+// In WEBGL mode, (0,0) is CENTER, not top-left
+function draw() {
+  // This draws at the center, not the corner
+  rect(0, 0, 100, 100);
+
+  // For top-left behavior:
+  translate(-width/2, -height/2);
+  rect(0, 0, 100, 100);  // now at top-left
+}
+```
+
+### 8. createGraphics 的清理
+
+```javascript
+// BAD: memory leak — buffer never freed
+function draw() {
+  let temp = createGraphics(width, height);  // new buffer every frame!
+  // ...
+}
+
+// GOOD: create once, reuse
+let temp;
+function setup() {
+  temp = createGraphics(width, height);
+}
+function draw() {
+  temp.clear();
+  // ... reuse temp
+}
+
+// If you must create/destroy:
+temp.remove();  // explicitly free
+```
+
+### 9. noise() 返回的是 0-1，而不是 -1 到 1
+
+```javascript
+let n = noise(x);  // 0.0 to 1.0 (biased toward 0.5)
+
+// For -1 to 1 range:
+let n = noise(x) * 2 - 1;
+
+// For a specific range:
+let n = map(noise(x), 0, 1, -100, 100);
+```
+
+### 10. 在 draw() 中使用 saveCanvas() 会保存每一帧
+
+```javascript
+// BAD: saves a PNG every single frame
+function draw() {
+  // ... render ...
+  saveCanvas('output', 'png');  // DON'T DO THIS
+}
+
+// GOOD: save once via keyboard
+function keyPressed() {
+  if (key === 's') saveCanvas('output', 'png');
+}
+
+// GOOD: save once after rendering static piece
+function draw() {
+  // ... render ...
+  saveCanvas('output', 'png');
+  noLoop();  // stop after saving
+}
+```
+
+### 11. 在 draw() 中执行 console.log()
+
+```javascript
+// BAD: writes to DOM console every frame — massive overhead
+function draw() {
+  console.log(particles.length);  // 60 DOM writes/second
+}
+
+// GOOD: log periodically or conditionally
+function draw() {
+  if (frameCount % 60 === 0) console.log('FPS:', frameRate().toFixed(1));
+}
+```
+
+### 12. 在 draw() 中操作 DOM
+
+```javascript
+// BAD: layout thrashing — 400-500x slower than canvas ops
+function draw() {
+  document.getElementById('counter').innerText = frameCount;
+  let el = document.querySelector('.info');  // DOM query per frame
+}
+
+// GOOD: cache DOM refs, update infrequently
+let counterEl;
+function setup() { counterEl = document.getElementById('counter'); }
+function draw() {
+  if (frameCount % 30 === 0) counterEl.innerText = frameCount;
+}
+```
+
+### 13. 在生产环境中没有禁用 FES
+
+```javascript
+// BAD: every p5 function call has error-checking overhead (up to 10x slower)
+function setup() { createCanvas(800, 800); }
+
+// GOOD: disable before any p5 code
+p5.disableFriendlyErrors = true;
+function setup() { createCanvas(800, 800); }
+
+// ALSO GOOD: use p5.min.js (FES stripped from minified build)
+```
+
+## 浏览器兼容性
+
+### Safari 问题
+- WebGL shader 精度：务必声明 `precision mediump float;`
+- `AudioContext` 需要用户手势触发 (`userStartAudio()`)
+- 某些 `blendMode()` 选项的行为与其他浏览器不同
+
+### Firefox 问题
+- `textToPoints()` 返回的点数可能略有不同
+- WebGL 扩展可能与 Chrome 不同
+- 颜色配置文件处理可能会导致颜色偏移
+
+### 移动端问题
+- 触摸事件需要 `return false` 以防止页面滚动
+- `devicePixelRatio` 可能是 2 倍或 3 倍——建议使用 `pixelDensity(1)` 以提升性能
+- 推荐使用较小的画布（720p 或更低）
+- 音频需要明确的用户手势才能开始播放
+
+## CORS 问题
+
+```javascript
+// Loading images/fonts from external URLs requires CORS headers
+// Local files need a server:
+// python3 -m http.server 8080
+
+// Or use a CORS proxy for external resources (not recommended for production)
+```
+
+## 内存泄漏
+
+### 症状
+- 帧率随时间降低
+- 浏览器标签页内存无限增长
+- 页面在几分钟后变得无响应
+
+### 常见原因
+
+```javascript
+// 1. Growing arrays
+let history = [];
+function draw() {
+  history.push(someData);  // grows forever
+}
+// FIX: cap the array
+if (history.length > 1000) history.shift();
+
+// 2. Creating p5 objects in draw()
+function draw() {
+  let v = createVector(0, 0);  // allocation every frame
+}
+// FIX: reuse pre-allocated objects
+
+// 3. Unreleased graphics buffers
+let layers = [];
+function reset() {
+  for (let l of layers) l.remove();  // free old buffers
+  layers = [];
+}
+
+// 4. Event listener accumulation
+function setup() {
+  // BAD: adds new listener every time setup runs
+  window.addEventListener('resize', handler);
+}
+// FIX: use p5's built-in windowResized()
+```
+
+## 调试技巧
+
+### 控制台日志
+
+```javascript
+// Log once (not every frame)
+if (frameCount === 1) {
+  console.log('Canvas:', width, 'x', height);
+  console.log('Pixel density:', pixelDensity());
+  console.log('Renderer:', drawingContext.constructor.name);
+}
+
+// Log periodically
+if (frameCount % 60 === 0) {
+  console.log('FPS:', frameRate().toFixed(1));
+  console.log('Particles:', particles.length);
+}
+```
+
+### 可视化调试
+
+```javascript
+// Show frame rate
+function draw() {
+  // ... your sketch ...
+  if (CONFIG.debug) {
+    fill(255, 0, 0);
+    noStroke();
+    textSize(14);
+    textAlign(LEFT, TOP);
+    text('FPS: ' + frameRate().toFixed(1), 10, 10);
+    text('Particles: ' + particles.length, 10, 28);
+    text('Frame: ' + frameCount, 10, 46);
+  }
+}
+
+// Toggle debug with 'd' key
+function keyPressed() {
+  if (key === 'd') CONFIG.debug = !CONFIG.debug;
+}
+```
+
+### 隔离问题
+
+```javascript
+// Comment out layers to find the slow one
+function draw() {
+  renderBackground();      // comment out to test
+  // renderParticles();    // this might be slow
+  // renderPostEffects();  // or this
+}
+```