@baimingtao/lbs-agent 1.0.0

package/extensions/skills/builtin/creative/p5js/README.md

@@ -0,0 +1,64 @@
+# p5js 说明
+
+使用 [p5.js](https://p5js.org/) 生成交互式和生成式视觉艺术的生产流水线。
+
+## 它能做什么
+
+根据文本提示词创建基于浏览器的视觉艺术。Agent 负责处理整个流程：创意构思、代码生成、审查、导出和迭代优化。输出结果是一个独立的 HTML 文件，可以在任何浏览器中运行——无需构建步骤，无需服务器，除 CDN script 标签外没有任何依赖。
+
+输出的作品是真正的交互式艺术，而不是教程练习。生成系统、粒子物理、噪声场、shader 效果、动态排版——由精心设计的调色板、层次分明的构图和视觉层级组合而成。
+
+## 模式
+
+| 模式 | 输入 | 输出 |
+| ------ | ------- | -------- |
+| **生成艺术** | Seed / 参数 | 程序化视觉构图 |
+| **数据可视化** | Dataset / API | 交互式图表，自定义数据显示 |
+| **交互体验** | 无（由用户驱动） | 基于鼠标/键盘/触摸的 sketch |
+| **动画 / 动态图形** | Timeline / storyboard | 定时序列，动态排版 |
+| **3D 场景** | 概念描述 | WebGL 几何体，光照，shaders |
+| **图像处理** | Image 文件(s) | 像素操作，滤镜，点彩画法 |
+| **音频反应** | Audio 文件 / 麦克风 | 声音驱动的生成式视觉效果 |
+
+## 导出格式
+
+| 格式 | 方法 |
+| -------- | -------- |
+| **HTML** | 独立文件，在任何浏览器中打开 |
+| **PNG** | `saveCanvas()` — 按 's' 键捕获 |
+| **GIF** | `saveGif()` — 按 'g' 键捕获 |
+| **MP4** | 帧序列 + 通过 `scripts/render.sh` 调用 ffmpeg |
+| **SVG** | 使用 p5.js-svg renderer 输出矢量图形 |
+
+## 前置条件
+
+一个现代浏览器。这就是基本使用所需的全部。
+
+对于无头（headless）导出：Node.js, Puppeteer, ffmpeg。
+
+```bash
+bash skills/creative/p5js/scripts/setup.sh
+```
+
+## 文件结构
+
+```
+├── SKILL.md                      # 模式、工作流、创意指导、关键说明
+├── README.md                     # 本文件
+├── references/
+│   ├── core-api.md              # Canvas, draw loop, transforms, offscreen buffers, math
+│   ├── shapes-and-geometry.md   # Primitives, vertices, curves, vectors, SDFs, clipping
+│   ├── visual-effects.md        # Noise, flow fields, particles, pixels, textures, feedback
+│   ├── animation.md             # Easing, springs, state machines, timelines, transitions
+│   ├── typography.md            # Fonts, textToPoints, kinetic text, text masks
+│   ├── color-systems.md         # HSB/RGB, palettes, gradients, blend modes, curated colors
+│   ├── webgl-and-3d.md          # 3D primitives, camera, lighting, shaders, framebuffers
+│   ├── interaction.md           # Mouse, keyboard, touch, DOM, audio, scroll
+│   ├── export-pipeline.md       # PNG, GIF, MP4, SVG, headless, tiling, batch export
+│   └── troubleshooting.md       # Performance, common mistakes, browser issues, debugging
+└── scripts/
+    ├── setup.sh                 # 依赖验证
+    ├── serve.sh                 # 本地开发服务器（用于加载本地资源）
+    ├── render.sh                # 无头渲染流水线（HTML → 帧 → MP4）
+    └── export-frames.js         # Puppeteer 帧捕获 (Node.js)
+```

package/extensions/skills/builtin/creative/p5js/SKILL.md

@@ -0,0 +1,555 @@
+---
+name: p5js
+description: "p5.js sketches：生成艺术、shaders、交互式、3D。"
+version: 1.0.0
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [creative-coding, generative-art, p5js, canvas, interactive, visualization, webgl, shaders, animation]
+    related_skills: [ascii-video, manim-video, excalidraw]
+---
+
+# p5.js 生产流水线
+
+## 适用场景
+
+适用于 users request：p5.js sketches、creative coding、生成艺术、交互式可视化、canvas 动画、基于浏览器的视觉艺术、data viz、shader 效果，或任何 p5.js 项目。
+
+## 内容概览
+
+使用 p5.js 构建交互式与生成式视觉艺术的生产流水线。创建基于浏览器的 sketches、生成艺术、数据可视化、交互式体验、3D 场景、audio-reactive 视觉效果和动态图形——导出为 HTML、PNG、GIF、MP4 或 SVG。涵盖：2D/3D 渲染、noise 与粒子系统、flow fields、shaders (GLSL)、像素操作、kinetic typography、WebGL 场景、音频分析、鼠标/键盘交互，以及 headless 高分辨率导出。
+
+## 创作标准
+
+这是在浏览器中渲染的视觉艺术。canvas 是媒介；算法是画笔。
+
+**在编写任何一行代码之前**，请清晰地表达创作概念。这件作品要传达什么？是什么让观者停止滑动屏幕？是什么让它区别于代码教程示例？用户的提示词只是一个起点——用创作的雄心来诠释它。
+
+**首次渲染的卓越品质是不可妥协的。** 输出内容在首次加载时必须具有视觉冲击力。如果它看起来像一个 p5.js 教程练习、默认配置，或是“AI 生成的 creative coding”，那就是错的。在发布之前请重新思考。
+
+**超越参考词汇。** 参考文档中的 noise 函数、粒子系统、调色板和 shader 效果只是起步词汇。对于每个项目，都要去组合、分层和创新。目录只是一个颜料盘——而你来作画。
+
+**主动发挥创造力。** 如果用户要求“一个粒子系统”，请交付一个具有 emergent flocking behavior、trailing ghost echoes、palette-shifted depth fog，以及会呼吸的背景 noise field 的粒子系统。包含至少一个用户没有要求但会欣赏的视觉细节。
+
+**密集、分层、深思熟虑。** 每一帧都值得细看。绝不使用纯白背景。始终保持构图层级。始终保持有意图的色彩。始终包含只有在仔细检查时才会出现的微小细节。
+
+**审美连贯性重于功能数量。** 所有元素都必须服务于统一的视觉语言——共享的色温、一致的 stroke weight 词汇、和谐的运动速度。一个包含十个互不相关效果的 sketch，不如一个包含三个紧密相关效果的 sketch。
+
+## 模式
+
+| 模式 | 输入 | 输出 | 参考 |
+|------|-------|--------|-----------|
+| **生成艺术** | Seed / 参数 | 程序化视觉构图（静态或动画） | `references/visual-effects.md` |
+| **数据可视化** | 数据集 / API | 交互式图表、图形、自定义数据显示 | `references/interaction.md` |
+| **交互式体验** | 无（用户驱动） | 鼠标/键盘/触摸驱动的 sketch | `references/interaction.md` |
+| **动画 / 动态图形** | 时间线 / 故事板 | 定时序列、kinetic typography、过渡效果 | `references/animation.md` |
+| **3D 场景** | 概念描述 | WebGL 几何体、光照、相机、材质 | `references/webgl-and-3d.md` |
+| **图像处理** | 图像文件 | 像素操作、滤镜、马赛克、点画法 | `references/visual-effects.md` § Pixel Manipulation |
+| **Audio-reactive** | 音频文件 / 麦克风 | 声音驱动的生成视觉效果 | `references/interaction.md` § Audio Input |
+
+## 技术栈
+
+每个项目均为单一的自包含 HTML 文件。无需构建步骤。
+
+| 层级 | 工具 | 用途 |
+|-------|------|---------|
+| 核心 | p5.js 1.11.3 (CDN) | Canvas 渲染、数学计算、变换、事件处理 |
+| 3D | p5.js WebGL mode | 3D 几何体、相机、光照、GLSL shaders |
+| 音频 | p5.sound.js (CDN) | FFT 分析、振幅、麦克风输入、振荡器 |
+| 导出 | 内置 `saveCanvas()` / `saveGif()` / `saveFrames()` | PNG、GIF、帧序列输出 |
+| 捕获 | CCapture.js（可选） | 确定性的帧率视频捕获（WebM, GIF） |
+| Headless | Puppeteer + Node.js（可选） | 自动化高分辨率渲染，通过 ffmpeg 导出 MP4 |
+| SVG | p5.js-svg 1.6.0（可选） | 用于打印的矢量输出——需要 p5.js 1.x |
+| Natural media | p5.brush（可选） | 水彩、木炭、钢笔——需要 p5.js 2.x + WEBGL |
+| 纹理 | p5.grain（可选） | 胶片颗粒、纹理叠加 |
+| 字体 | Google Fonts / `loadFont()` | 通过 OTF/TTF/WOFF2 实现自定义排版 |
+
+### 版本说明
+
+**p5.js 1.x** (1.11.3) 是默认版本——稳定、文档齐全、库兼容性最广。除非项目需要 2.x 特性，否则请使用此版本。
+
+**p5.js 2.x** (2.2+) 新增了：`async setup()` 替代 `preload()`、OKLCH/OKLAB color modes、`splineVertex()`、shader `.modify()` API、可变字体、`textToContours()`、pointer events。对于 p5.brush 是必需的。参见 `references/core-api.md` § p5.js 2.0。
+
+## 流水线
+
+每个项目都遵循相同的 6 阶段路径：
+
+```
+CONCEPT → DESIGN → CODE → PREVIEW → EXPORT → VERIFY
+```
+
+1. **CONCEPT** — 清晰地表达创作愿景：情绪、色彩世界、运动词汇，以及使其独特的原因
+2. **DESIGN** — 选择模式、canvas 大小、交互模型、颜色系统、导出格式。将概念映射为技术决策
+3. **CODE** — 编写包含内联 p5.js 的单一 HTML 文件。结构：globals → `preload()` → `setup()` → `draw()` → helpers → classes → event handlers
+4. **PREVIEW** — 在浏览器中打开，验证视觉质量。在目标分辨率下测试。检查性能
+5. **EXPORT** — 捕获输出：`saveCanvas()` 导出 PNG，`saveGif()` 导出 GIF，`saveFrames()` + ffmpeg 导出 MP4，Puppeteer 用于 headless 批处理
+6. **VERIFY** — 输出是否符合概念？在预期的显示尺寸下是否具有视觉冲击力？你会把它装裱起来吗？
+
+## 创作指导
+
+### 审美维度
+
+| 维度 | 选项 | 参考 |
+|-----------|---------|-----------|
+| **颜色系统** | HSB/HSL、RGB、命名调色板、程序化和谐、渐变插值 | `references/color-systems.md` |
+| **Noise 词汇** | Perlin noise、simplex、fractal（octaved）、domain warping、curl noise | `references/visual-effects.md` § Noise |
+| **粒子系统** | 基于物理、flocking、trail-drawing、attractor-driven、flow-field following | `references/visual-effects.md` § Particles |
+| **形状语言** | 几何图元、自定义顶点、bezier 曲线、SVG 路径 | `references/shapes-and-geometry.md` |
+| **运动风格** | Eased、spring-based、noise-driven、物理模拟、lerped、stepped | `references/animation.md` |
+| **排版** | 系统字体、加载的 OTF、`textToPoints()` 粒子文本、kinetic | `references/typography.md` |
+| **Shader 效果** | GLSL fragment/vertex、filter shaders、post-processing、feedback loops | `references/webgl-and-3d.md` § Shaders |
+| **构图** | 网格、径向、黄金比例、三分法、有机散布、平铺 | `references/core-api.md` § Composition |
+| **交互模型** | 鼠标跟随、点击生成、拖拽、键盘状态、滚动驱动、麦克风输入 | `references/interaction.md` |
+| **混合模式** | `BLEND`、`ADD`、`MULTIPLY`、`SCREEN`、`DIFFERENCE`、`EXCLUSION`、`OVERLAY` | `references/color-systems.md` § Blend Modes |
+| **分层** | `createGraphics()` offscreen buffers、alpha compositing、masking | `references/core-api.md` § Offscreen Buffers |
+| **纹理** | Perlin surface、stippling、hatching、halftone、像素排序 | `references/visual-effects.md` § Texture Generation |
+
+### 单项目变量规则
+
+绝不使用默认配置。对于每个项目：
+- **自定义调色板** — 绝不使用原始的 `fill(255, 0, 0)`。始终使用包含 3-7 种颜色的设计调色板
+- **自定义 stroke weight 词汇** — 细强调 (0.5)、中等结构 (1-2)、粗重点 (3-5)
+- **背景处理** — 绝不使用单纯的 `background(0)` 或 `background(255)`。始终使用带纹理、渐变或分层的背景
+- **运动多样性** — 不同元素使用不同速度。主要元素 1x，次要元素 0.3x，环境元素 0.1x
+- **至少包含一个首创元素** — 一个自定义的粒子行为、一种新颖的 noise 应用、或一个独特的交互响应
+
+### 针对项目的独创性
+
+对于每个项目，至少发明以下之一：
+- 符合情绪的自定义调色板（非预设）
+- 新颖的 noise field 组合（例如：curl noise + domain warp + feedback）
+- 独特的粒子行为（自定义受力、自定义轨迹、自定义生成）
+- 用户未要求但能提升作品层次的交互机制
+- 能够创造视觉层级的构图技巧
+
+### 参数设计哲学
+
+参数应从算法中产生，而不是来自通用菜单。试问：“*这个*系统的哪些属性应该是可调的？”
+
+**好的参数**能展现算法的个性：
+- **数量** — 多少粒子、分支、细胞（控制密度）
+- **规模** — noise 频率、元素大小、间距（控制纹理）
+- **速率** — 速度、增长率、衰减（控制能量）
+- **阈值** — 行为何时改变？（控制戏剧性）
+- **比率** — 比例、力之间的平衡（控制和谐度）
+
+**坏的参数**是与算法无关的通用控制：
+- "color1"、"color2"、"size" — 没有上下文就毫无意义
+- 用于互不相关效果的切换开关
+- 仅改变外观而不改变行为的参数
+
+每个参数都应改变算法的*思考方式*，而不仅仅是*外观*。一个改变 noise octaves 的“turbulence”参数是好的。一个只改变 `ellipse()` 半径的“particle size”滑块则是肤浅的。
+
+## 工作流
+
+### 第一步：创作愿景
+
+在编写任何代码之前，请明确：
+- **情绪/氛围**：观者应该感受到什么？沉思？充满活力？不安？俏皮？
+- **视觉故事**：随着时间推移（或在交互时）会发生什么？构建？衰减？变形？振荡？
+- **色彩世界**：暖色/冷色？单色？互补色？主色调是什么？强调色是什么？
+- **形状语言**：有机曲线？锐利几何？圆点？线条？混合？
+- **运动词汇**：缓慢漂流？爆炸式迸发？呼吸般的脉动？机械般精准？
+- ***这*为何与众不同**：让这个 sketch 独一无二的那一点是什么？
+
+将用户的提示词映射为审美选择。“放松的生成背景”与“glitch 数据可视化”对一切的要求都截然不同。
+
+### 第二步：技术设计
+
+- **模式** — 上表 7 种模式中的哪一种
+- **Canvas 大小** — 横向 1920x1080、纵向 1080x1920、正方形 1080x1080，或响应式 `windowWidth/windowHeight`
+- **渲染器** — `P2D`（默认）或 `WEBGL`（用于 3D、shaders、高级混合模式）
+- **帧率** — 60fps（交互式）、30fps（环境动画），或 `noLoop()`（静态生成）
+- **导出目标** — 浏览器显示、PNG 静止图像、GIF 循环、MP4 视频、SVG 矢量
+- **交互模型** — 被动（无输入）、鼠标驱动、键盘驱动、audio-reactive、滚动驱动
+- **观者 UI** — 对于交互式生成艺术，从 `templates/viewer.html` 开始，它提供了 seed 导航、参数滑块和下载功能。对于简单的 sketches 或视频导出，请使用纯 HTML
+
+### 第三步：编写 Sketch
+
+对于**交互式生成艺术**（seed 探索、参数调整）：从 `templates/viewer.html` 开始。首先阅读模板，保留固定部分（seed 导航、操作），替换算法和参数控制。这为用户提供了 seed 的 prev/next/random/jump、带实时更新的参数滑块，以及 PNG 下载功能——全部已接好线。
+
+对于**动画、视频导出或简单的 sketches**：使用纯 HTML：
+
+单一 HTML 文件。结构如下：
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Project Name</title>
+  <script>p5.disableFriendlyErrors = true;</script>
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/1.11.3/p5.min.js"></script>
+  <!-- <script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/1.11.3/addons/p5.sound.min.js"></script> -->
+  <!-- <script src="https://unpkg.com/p5.js-svg@1.6.0"></script> -->  <!-- SVG export -->
+  <!-- <script src="https://cdn.jsdelivr.net/npm/ccapture.js-npmfixed/build/CCapture.all.min.js"></script> -->  <!-- video capture -->
+  <style>
+    html, body { margin: 0; padding: 0; overflow: hidden; }
+    canvas { display: block; }
+  </style>
+</head>
+<body>
+<script>
+// === Configuration ===
+const CONFIG = {
+  seed: 42,
+  // ... project-specific params
+};
+
+// === Color Palette ===
+const PALETTE = {
+  bg: '#0a0a0f',
+  primary: '#e8d5b7',
+  // ...
+};
+
+// === Global State ===
+let particles = [];
+
+// === Preload (fonts, images, data) ===
+function preload() {
+  // font = loadFont('...');
+}
+
+// === Setup ===
+function setup() {
+  createCanvas(1920, 1080);
+  randomSeed(CONFIG.seed);
+  noiseSeed(CONFIG.seed);
+  colorMode(HSB, 360, 100, 100, 100);
+  // Initialize state...
+}
+
+// === Draw Loop ===
+function draw() {
+  // Render frame...
+}
+
+// === Helper Functions ===
+// ...
+
+// === Classes ===
+class Particle {
+  // ...
+}
+
+// === Event Handlers ===
+function mousePressed() { /* ... */ }
+function keyPressed() { /* ... */ }
+function windowResized() { resizeCanvas(windowWidth, windowHeight); }
+</script>
+</body>
+</html>
+```
+
+关键实现模式：
+- **带 Seed 的随机性**：始终使用 `randomSeed()` + `noiseSeed()` 以保证可复现性
+- **颜色模式**：使用 `colorMode(HSB, 360, 100, 100, 100)` 进行直观的颜色控制
+- **状态分离**：CONFIG 用于参数，PALETTE 用于颜色，globals 用于可变状态
+- **基于类的实体**：Particles、agents、shapes 均作为包含 `update()` + `display()` 方法的类
+- **Offscreen buffers**：使用 `createGraphics()` 进行分层构图、轨迹、遮罩
+
+### 第四步：预览与迭代
+
+- 直接在浏览器中打开 HTML 文件——基础 sketches 无需服务器
+- 对于从本地文件加载的 `loadImage()`/`loadFont()`：使用 `scripts/serve.sh` 或 `python3 -m http.server`
+- 使用 Chrome DevTools Performance 标签页验证是否达到 60fps
+- 在目标导出分辨率下进行测试，而不仅仅是窗口大小
+- 调整参数，直到视觉效果与第一步中的概念相符
+
+### 第五步：导出
+
+| 格式 | 方法 | 命令 |
+|--------|--------|---------|
+| **PNG** | 在 `keyPressed()` 中使用 `saveCanvas('output', 'png')` | 按 's' 保存 |
+| **高分辨率 PNG** | Puppeteer headless 捕获 | `node scripts/export-frames.js sketch.html --width 3840 --height 2160 --frames 1` |
+| **GIF** | `saveGif('output', 5)` — 捕获 N 秒 | 按 'g' 保存 |
+| **帧序列** | `saveFrames('frame', 'png', 10, 30)` — 以 30fps 捕获 10 秒 | 然后 `ffmpeg -i frame-%04d.png -c:v libx264 output.mp4` |
+| **MP4** | Puppeteer 逐帧捕获 + ffmpeg | `bash scripts/render.sh sketch.html output.mp4 --duration 30 --fps 30` |
+| **SVG** | 结合 p5.js-svg 使用 `createCanvas(w, h, SVG)` | `save('output.svg')` |
+
+### 第六步：质量 验证
+
+- **符合愿景吗？** 将输出与创作概念进行比较。如果看起来很平庸，请返回第一步
+- **分辨率检查**：在目标显示尺寸下清晰吗？没有锯齿伪影？
+- **性能检查**：在浏览器中能保持 60fps 吗？（动画至少 30fps）
+- **色彩检查**：颜色搭配协调吗？在明亮和昏暗的显示器上都测试一下
+- **边缘情况**：在 canvas 边缘会发生什么？在调整大小时？在运行 10 分钟后？
+
+## 关键 实现 说明
+
+### 性能 — 优先禁用 FES
+
+Friendly Error System (FES) 会增加高达 10 倍的开销。在每个生产级 sketch 中禁用它：
+
+```javascript
+p5.disableFriendlyErrors = true;  // BEFORE setup()
+
+function setup() {
+  pixelDensity(1);  // prevent 2x-4x overdraw on retina
+  createCanvas(1920, 1080);
+}
+```
+
+在热点循环（particles, pixel ops）中，使用 `Math.*` 代替 p5 的包装函数——速度明显更快：
+
+```javascript
+// In draw() or update() hot paths:
+let a = Math.sin(t);          // not sin(t)
+let r = Math.sqrt(dx*dx+dy*dy); // not dist() — or better: skip sqrt, compare magSq
+let v = Math.random();        // not random() — when seed not needed
+let m = Math.min(a, b);       // not min(a, b)
+```
+
+绝不要在 `draw()` 中执行 `console.log()`。绝不要在 `draw()` 中操作 DOM。参见 `references/troubleshooting.md` § Performance。
+
+### 带 Seed 的随机性 — 始终需要
+
+每个生成式 sketch 都必须可复现。相同的 seed，相同的输出。
+
+```javascript
+function setup() {
+  randomSeed(CONFIG.seed);
+  noiseSeed(CONFIG.seed);
+  // All random() and noise() calls now deterministic
+}
+```
+
+绝不要在生成内容中使用 `Math.random()`——仅用于对性能要求极高的非视觉代码。视觉元素务必始终使用 `random()`。如果需要随机 seed：`CONFIG.seed = floor(random(99999))`。
+
+### 生成艺术平台支持 (fxhash / Art Blocks)
+
+对于生成艺术平台，将 p5 的 PRNG 替换为平台的确定性随机数：
+
+```javascript
+// fxhash convention
+const SEED = $fx.hash;              // unique per mint
+const rng = $fx.rand;               // deterministic PRNG
+$fx.features({ palette: 'warm', complexity: 'high' });
+
+// In setup():
+randomSeed(SEED);   // for p5's noise()
+noiseSeed(SEED);
+
+// Replace random() with rng() for platform determinism
+let x = rng() * width;  // instead of random(width)
+```
+
+参见 `references/export-pipeline.md` § Platform Export。
+
+### 颜色模式 — 使用 HSB
+
+在生成艺术中，HSB（Hue, Saturation, Brightness）比 RGB 更易于操作：
+
+```javascript
+colorMode(HSB, 360, 100, 100, 100);
+// Now: fill(hue, sat, bri, alpha)
+// Rotate hue: fill((baseHue + offset) % 360, 80, 90)
+// Desaturate: fill(hue, sat * 0.3, bri)
+// Darken: fill(hue, sat, bri * 0.5)
+```
+
+绝不硬编码原始 RGB 值。定义一个调色板对象，以程序化方式推导变体。参见 `references/color-systems.md`。
+
+### Noise — 多重 Octave，拒绝原始状态
+
+原始的 `noise(x, y)` 看起来像平滑的色块。叠加多个 octave 以获得自然的纹理：
+
+```javascript
+function fbm(x, y, octaves = 4) {
+  let val = 0, amp = 1, freq = 1, sum = 0;
+  for (let i = 0; i < octaves; i++) {
+    val += noise(x * freq, y * freq) * amp;
+    sum += amp;
+    amp *= 0.5;
+    freq *= 2;
+  }
+  return val / sum;
+}
+```
+
+对于流动的有机形态，使用 **domain warping**：将 noise 的输出反馈作为 noise 的输入坐标。参见 `references/visual-effects.md`。
+
+### createGraphics() 用于图层 — 不是 可选
+
+扁平的单次渲染看起来很平淡。使用 offscreen buffers 进行构图：
+
+```javascript
+let bgLayer, fgLayer, trailLayer;
+function setup() {
+  createCanvas(1920, 1080);
+  bgLayer = createGraphics(width, height);
+  fgLayer = createGraphics(width, height);
+  trailLayer = createGraphics(width, height);
+}
+function draw() {
+  renderBackground(bgLayer);
+  renderTrails(trailLayer);   // persistent, fading
+  renderForeground(fgLayer);  // cleared each frame
+  image(bgLayer, 0, 0);
+  image(trailLayer, 0, 0);
+  image(fgLayer, 0, 0);
+}
+```
+
+### 性能 — 尽可能向量化
+
+p5.js 的 draw 调用开销很大。对于成千上万的粒子：
+
+```javascript
+// SLOW: individual shapes
+for (let p of particles) {
+  ellipse(p.x, p.y, p.size);
+}
+
+// FAST: single shape with beginShape()
+beginShape(POINTS);
+for (let p of particles) {
+  vertex(p.x, p.y);
+}
+endShape();
+
+// FASTEST: pixel buffer for massive counts
+loadPixels();
+for (let p of particles) {
+  let idx = 4 * (floor(p.y) * width + floor(p.x));
+  pixels[idx] = r; pixels[idx+1] = g; pixels[idx+2] = b; pixels[idx+3] = 255;
+}
+updatePixels();
+```
+
+参见 `references/troubleshooting.md` § Performance。
+
+### 多 Sketch 的 Instance Mode
+
+全局模式会污染 `window`。在生产环境中，请使用 instance mode：
+
+```javascript
+const sketch = (p) => {
+  p.setup = function() {
+    p.createCanvas(800, 800);
+  };
+  p.draw = function() {
+    p.background(0);
+    p.ellipse(p.mouseX, p.mouseY, 50);
+  };
+};
+new p5(sketch, 'canvas-container');
+```
+
+在一个页面上嵌入多个 sketches 或与框架集成时是 必需 的。
+
+### WebGL 模式陷阱
+
+- `createCanvas(w, h, WEBGL)` — 原点在中心，而不是左上角
+- Y 轴反转（在 WEBGL 中正 Y 向上，在 P2D 中向下）
+- 使用 `translate(-width/2, -height/2)` 获取类似 P2D 的坐标系
+- 在每次变换前后使用 `push()`/`pop()` — 矩阵堆栈会悄无声息地溢出
+- `texture()` 必须在 `rect()`/`plane()` 之前调用 — 而不是之后
+- 自定义 shaders：`createShader(vert, frag)` — 需在多个浏览器中测试
+
+### 导出 — 快捷键绑定约定
+
+每个 sketch 都应在 `keyPressed()` 中包含这些内容：
+
+```javascript
+function keyPressed() {
+  if (key === 's' || key === 'S') saveCanvas('output', 'png');
+  if (key === 'g' || key === 'G') saveGif('output', 5);
+  if (key === 'r' || key === 'R') { randomSeed(millis()); noiseSeed(millis()); }
+  if (key === ' ') CONFIG.paused = !CONFIG.paused;
+}
+```
+
+### Headless 视频导出 — 使用 noLoop()
+
+对于通过 Puppeteer 进行的 headless 渲染，sketch **必须**在 setup 中使用 `noLoop()`。如果不这样做，当缓慢的截图程序还在工作时，p5 的 draw 循环会自由运行——sketch 会超前运行，导致你得到跳过或重复的帧。
+
+```javascript
+function setup() {
+  createCanvas(1920, 1080);
+  pixelDensity(1);
+  noLoop();                    // capture script controls frame advance
+  window._p5Ready = true;      // signal readiness to capture script
+}
+```
+
+内置的 `scripts/export-frames.js` 会检测 `_p5Ready`，并在每次捕获时调用一次 `redraw()`，以实现精确的 1:1 帧对应关系。参见 `references/export-pipeline.md` § Deterministic Capture。
+
+对于多场景视频，请使用 per-clip 架构：每个场景对应一个 HTML 文件，独立渲染，然后使用 `ffmpeg -f concat` 拼接。参见 `references/export-pipeline.md` § Per-Clip Architecture。
+
+### Agent 工作流
+
+在构建 p5.js sketches 时：
+
+1. **编写 HTML 文件** — 单一的自包含文件，所有代码均为内联
+2. **在浏览器中打开** — `open sketch.html` (macOS) 或 `xdg-open sketch.html` (Linux)
+3. **本地资源**（字体、图像）需要服务器：在项目目录中运行 `python3 -m http.server 8080`，然后打开 `http://localhost:8080/sketch.html`
+4. **导出 PNG/GIF** — 添加如上所示的 `keyPressed()` 快捷方式，告诉用户该按哪个键
+5. **Headless 导出** — `node scripts/export-frames.js sketch.html --frames 300` 进行自动帧捕获（sketch 必须使用 `noLoop()` + `_p5Ready`）
+6. **MP4 渲染** — `bash scripts/render.sh sketch.html output.mp4 --duration 30`
+7. **迭代优化** — 编辑 HTML 文件，用户刷新浏览器即可查看更改
+8. **按需加载参考文档** — 在实现过程中，使用 `skill_view(name="p5js", file_path="references/...")` 根据需要加载特定的参考文件
+
+## 性能目标
+
+| 指标 | 目标 |
+|--------|--------|
+| 帧率（交互式） | 持续 60fps |
+| 帧率（动画导出） | 至少 30fps |
+| 粒子数量（P2D 形状） | 60fps 下 5,000-10,000 个 |
+| 粒子数量（pixel buffer） | 60fps 下 50,000-100,000 个 |
+| Canvas 分辨率 | 最高 3840x2160（导出），1920x1080（交互式） |
+| 文件大小（HTML） | < 100KB（不包括 CDN 库） |
+| 加载时间 | < 2 秒首帧渲染时间 |
+
+## 参考资料
+
+| 文件 | 内容 |
+|------|----------|
+| `references/core-api.md` | Canvas 设置、坐标系、draw 循环、`push()`/`pop()`、offscreen buffers、构图模式、`pixelDensity()`、响应式设计 |
+| `references/shapes-and-geometry.md` | 2D 图元、`beginShape()`/`endShape()`、Bezier/Catull-Rom 曲线、`vertex()` 系统、自定义形状、`p5.Vector`、signed distance fields、SVG 路径转换 |
+| `references/visual-effects.md` | Noise（Perlin、fractal、domain warp、curl）、flow fields、粒子系统（物理、flocking、轨迹）、像素操作、纹理生成（stipple、hatch、halftone）、feedback loops、reaction-diffusion |
+| `references/animation.md` | 基于帧的动画、easing 函数、`lerp()`/`map()`、spring physics、状态机、时间线序列、基于 `millis()` 的计时、过渡模式 |
+| `references/typography.md` | `text()`、`loadFont()`、`textToPoints()`、kinetic typography、文本遮罩、字体度量、响应式文字尺寸调整 |
+| `references/color-systems.md` | `colorMode()`、HSB/HSL/RGB、`lerpColor()`、`paletteLerp()`、程序化调色板、色彩和谐、`blendMode()`、渐变渲染、精选调色板库 |
+| `references/webgl-and-3d.md` | WEBGL 渲染器、3D 图元、相机、光照、材质、自定义几何体、GLSL shaders（`createShader()`、`createFilterShader()`）、framebuffers、post-processing |
+| `references/interaction.md` | 鼠标事件、键盘状态、触摸输入、DOM 元素、`createSlider()`/`createButton()`、音频输入（p5.sound FFT/amplitude）、滚动驱动动画、响应式事件 |
+| `references/export-pipeline.md` | `saveCanvas()`、`saveGif()`、`saveFrames()`、确定性 headless 捕获、ffmpeg 逐帧转视频、CCapture.js、SVG 导出、per-clip 架构、平台导出（fxhash）、视频陷阱 |
+| `references/troubleshooting.md` | 性能分析、逐像素预算、常见错误、浏览器兼容性、WebGL 调试、字体加载问题、像素密度陷阱、内存泄漏、CORS |
+| `templates/viewer.html` | 交互式查看器模板：seed 导航（prev/next/random/jump）、参数滑块、下载 PNG、响应式 canvas。可探索的生成艺术请以此模板为起点 |
+
+---
+
+## 创意发散（仅在用户要求实验性/创意性/独特输出时使用）
+
+如果用户要求创意、实验性、令人惊喜或非传统的输出，请选择最合适的策略，并在生成代码之前理清其步骤。
+
+- **Conceptual Blending（概念融合）** — 当用户指定要结合两件事物或想要混合美学时
+- **SCAMPER（奔驰法）** — 当用户想要对已知的生成艺术模式进行改造时
+- **Distance Association（远距联想）** — 当用户给出单一概念并希望进行探索时（“做点关于时间的东西”）
+
+### Conceptual Blending
+1. 命名两个截然不同的视觉系统（例如：粒子物理学 + 手写体）
+2. 映射对应关系（粒子 = 墨滴，受力 = 笔压，场 = 字母形态）
+3. 选择性融合 — 保留那些能产生有趣 emergent visuals 的映射
+4. 将融合编写为一个统一的系统，而不是两个并排的系统
+
+### SCAMPER Transformation
+选取一个已知的生成模式（flow field、粒子系统、L-system、元胞自动机）并对其进行系统转换：
+- **Substitute（替代）**：用文本字符替换圆圈，用渐变替换线条
+- **Combine（合并）**：融合两种模式（flow field + voronoi）
+- **Adapt（调整）**：将 2D 模式应用于 3D 投影
+- **Modify（修改）**：夸张比例，扭曲坐标空间
+- **Purpose（目的）**：将物理模拟用于排版，将排序算法用于颜色
+- **Eliminate（消除）**：移除网格、移除颜色、移除对称性
+- **Reverse（反转）**：反向运行模拟，反转参数空间
+
+### Distance Association
+1. 以用户的概念为锚点（例如：“loneliness”）
+2. 在三个距离上生成联想：
+   - 近（显而易见）：空荡的房间、孤独的身影、死寂
+   - 中（有趣）：鱼群中向反方向游动的一条鱼、没有通知的手机、地铁车厢之间的间隙
+   - 远（抽象）：质数、渐近曲线、凌晨三点的颜色
+3. 深化中等距离的联想——它们具体到足以具象化，又出乎意料到具有吸引力