@baimingtao/lbs-agent 1.0.0

package/extensions/skills/builtin/creative/touchdesigner-mcp/references/operator-tips.md

@@ -0,0 +1,106 @@
+# Operator 使用技巧
+
+## Wireframe Rendering Pattern
+
+在黑色背景上渲染线框几何体的可复用设置：
+
+```python
+# 1. Material
+mat = root.create(wireframeMAT, 'wire_mat')
+mat.par.colorr = 1.0; mat.par.colorg = 0.0; mat.par.colorb = 0.0
+mat.par.linewidth = 3
+
+# 2. Geometry COMP
+geo = root.create(geometryCOMP, 'my_geo')
+geo.par.rx.expr = 'absTime.seconds * 30'
+geo.par.ry.expr = 'absTime.seconds * 45'
+geo.par.material = mat.path  # NOTE: 'material' not 'mat'
+
+# 3. Shape inside the geo
+box = geo.create(boxSOP, 'cube')
+box.par.sizex = 1.5; box.par.sizey = 1.5; box.par.sizez = 1.5
+
+# 4. Camera
+cam = root.create(cameraCOMP, 'cam1')
+cam.par.tx = 0; cam.par.ty = 0; cam.par.tz = 4; cam.par.fov = 45
+
+# 5. Render TOP
+render = root.create(renderTOP, 'render1')
+render.par.outputresolution = 'custom'
+render.par.resolutionw = 1280; render.par.resolutionh = 720
+render.par.bgcolorr = 0; render.par.bgcolorg = 0; render.par.bgcolorb = 0
+render.par.camera = cam.path
+render.par.geometry = geo.path
+
+# 6. Output null
+out = root.create(nullTOP, 'out1')
+out.inputConnectors[0].connect(render.outputConnectors[0])
+```
+
+**关键规则：**
+- 类名：`wireframeMAT` 而不是 `wireframeMat`（全大写后缀）
+- Geometry SOPs/POPs 需放置在 geo comp 内部
+- Material：使用 `geo.par.material` 而不是 `geo.par.mat`
+- 渲染几何体：`render.par.geometry = geo.path`（字符串路径）
+- 设置 `wireframeMAT.par.wireframemode = 'topology'` 可获得干净的线框（相比之下，`'tesselated''` 用于显示三角形边）
+- 替代方案：使用 `renderTOP.par.overridemat` 代替为每个 geo 单独指定 material
+
+## Feedback TOP
+
+### 基本结构
+
+```
+input (initial state) ──┐
+                        ├──→ feedback_top ──→ processing ──→ null_out
+                        │                                        ↑
+                        └── par.top = 'null_out' ────────────────┘
+```
+
+### 配置模式
+
+```python
+# 1. Processing chain
+glsl = root.create(glslTOP, 'sim')
+null_out = root.create(nullTOP, 'null_out')
+glsl.outputConnectors[0].connect(null_out.inputConnectors[0])
+
+# 2. Feedback referencing null_out
+feedback = root.create(feedbackTOP, 'feedback')
+feedback.par.top = 'null_out'
+
+# 3. Black initial state
+const_init = root.create(constantTOP, 'const_init')
+const_init.par.colorr = 0; const_init.par.colorg = 0; const_init.par.colorb = 0
+
+# 4. Wire: initial → feedback, feedback → processing
+feedback.inputConnectors[0].connect(const_init)
+glsl.inputConnectors[0].connect(feedback)
+
+# 5. Reset to apply initial state
+feedback.par.resetpulse.pulse()
+```
+
+### 常见错误
+
+| 错误 | 原因 | 解决方案 |
+| ------- | ------- | ---------- |
+| "Not enough sources specified" | 未连接输入 | 连接初始状态 TOP |
+| 出现意外的初始图案 | 初始状态错误 | 使用 Constant TOP（黑色） |
+
+### 技巧
+
+1. 模拟运算使用 float 格式：`glsl.par.format = 'rgba32float'`
+2. 设置完成后执行重置：`feedback.par.resetpulse.pulse()`
+3. 分辨率需匹配 —— feedback、processing 以及初始状态的分辨率必须保持一致
+4. 柔化边界可防止边缘瑕疵：
+   ```glsl
+   float edge = 3.0 * texel.x;
+   float bx = smoothstep(0.0, edge, uv.x) * smoothstep(0.0, edge, 1.0 - uv.x);
+   float by = smoothstep(0.0, edge, uv.y) * smoothstep(0.0, edge, 1.0 - uv.y);
+   value *= bx * by;
+   ```
+
+### 使用场景
+- **Wave Simulation（波浪模拟）** — R 通道为高度，G 通道为速度，黑色初始状态
+- **Cellular Automata（元胞自动机）** — 白色表示存活，黑色表示死亡，随机噪点初始状态
+- **Trail / Motion Blur（拖尾/运动模糊）** — 将当前帧与 feedback 混合，黑色初始状态

package/extensions/skills/builtin/creative/touchdesigner-mcp/references/operators.md

@@ -0,0 +1,239 @@
+# TouchDesigner Operator 参考手册
+
+## Operator Families 概览
+
+TouchDesigner 共有 6 个 operator families。每个 family 处理特定的数据类型，并在 UI 中以特定颜色进行区分。Operators 只能连接到属于同种 family 的其他 operators（跨 family 连接需要使用转换器作为桥梁）。
+
+## TOPs — Texture Operators (紫色)
+
+在 GPU 上进行 2D 图像/纹理处理。视觉输出的主力军。
+
+### Generators (无中生有创建图像)
+
+| Operator | Type Name | Key Parameters | 用途 |
+| ---------- | ----------- | --------------- | ----- |
+| Noise TOP | `noiseTop` | `type` (0-6), `monochrome`, `seed`, `period`, `harmonics`, `exponent`, `amp`, `offset`, `resolutionw/h` | 程序化噪声纹理 — Perlin, Simplex, Sparse 等。生成式艺术的基础。 |
+| Constant TOP | `constantTop` | `colorr/g/b/a`, `resolutionw/h` | 纯色。可用作背景或混合输入。 |
+| Text TOP | `textTop` | `text`, `fontsizex`, `fontfile`, `alignx/y`, `colorr/g/b` | 将文本渲染为纹理。支持多行、自动换行。 |
+| Ramp TOP | `rampTop` | `type` (0=horizontal, 1=vertical, 2=radial, 3=circular), `phase`, `period` | 用于遮罩、颜色映射的渐变纹理。 |
+| Circle TOP | `circleTop` | `radiusx/y`, `centerx/y`, `width` | 圆形、环形、椭圆。 |
+| Rectangle TOP | `rectangleTop` | `sizex/y`, `centerx/y`, `softness` | 带有可选柔化边缘的矩形。 |
+| GLSL TOP | `glslTop` | `dat` (points to shader DAT), `resolutionw/h`, `outputformat`, custom uniforms | 自定义 fragment shaders。用于自定义视觉效果的最强大 TOP。 |
+| GLSL Multi TOP | `glslmultiTop` | `dat`, `numinputs`, `numoutputs`, `numcomputepasses` | 带有 compute shaders 的多通道 GLSL。属于进阶应用。 |
+| Render TOP | `renderTop` | `camera`, `geometry`, `lights`, `resolutionw/h` | 渲染 3D 场景 (SOPs + MATs + Camera/Light COMPs)。 |
+
+### Filters (修改单个输入)
+
+| Operator | Type Name | Key Parameters | 用途 |
+| ---------- | ----------- | --------------- | ----- |
+| Level TOP | `levelTop` | `opacity`, `brightness1/2`, `gamma1/2`, `contrast`, `invert`, `blacklevel/whitelevel` | 亮度、对比度、伽马值、色阶。基础的颜色校正工具。 |
+| Blur TOP | `blurTop` | `sizex/y`, `type` (0=Gaussian, 1=Box, 2=Bartlett) | 高斯/盒状模糊。 |
+| Transform TOP | `transformTop` | `tx/ty`, `sx/sy`, `rz`, `pivotx/y`, `extend` (0=Hold, 1=Zero, 2=Repeat, 3=Mirror) | 平移、缩放、旋转纹理。 |
+| HSV Adjust TOP | `hsvadjustTop` | `hueoffset`, `saturationmult`, `valuemult` | HSV 颜色调整。 |
+| Lookup TOP | `lookupTop` | (input: texture + lookup table) | 通过查找表纹理进行颜色重映射。 |
+| Edge TOP | `edgeTop` | `type` (0=Sobel, 1=Frei-Chen) | 边缘检测。 |
+| Displace TOP | `displaceTop` | `scalex/y` | 使用第二个输入作为位移贴图进行像素位移。 |
+| Flip TOP | `flipTop` | `flipx`, `flipy`, `flop` (diagonal) | 镜像/翻转纹理。 |
+| Crop TOP | `cropTop` | `cropleft/right/top/bottom` | 裁剪纹理区域。 |
+| Resolution TOP | `resolutionTop` | `resolutionw/h`, `outputresolution` | 调整纹理大小。 |
+| Null TOP | `nullTop` | (none significant) | 直通。用于组织、引用、反馈延迟。 |
+| Cache TOP | `cacheTop` | `length`, `step` | 存储 N 帧历史记录。适用于拖尾、时间特效。 |
+
+### Compositors (合并多个输入)
+
+| Operator | Type Name | Key Parameters | 用途 |
+| ---------- | ----------- | --------------- | ----- |
+| Composite TOP | `compositeTop` | `operand` (0-31: Over, Add, Multiply, Screen, 等) | 使用标准合成模式混合两个纹理。 |
+| Over TOP | `overTop` | (simple alpha compositing) | 带有 alpha 通道的图层叠加。比 Composite 更简单。 |
+| Add TOP | `addTop` | (additive blend) | 加法混合。非常适合发光、光效。 |
+| Multiply TOP | `multiplyTop` | (multiplicative blend) | 乘法混合。适用于遮罩、变暗。 |
+| Switch TOP | `switchTop` | `index` (0-based) | 通过索引在多个输入之间切换。 |
+| Cross TOP | `crossTop` | `cross` (0.0-1.0) | 在两个输入之间进行交叉淡入淡出。 |
+
+### I/O (输入/输出)
+
+| Operator | Type Name | Key Parameters | 用途 |
+| ---------- | ----------- | --------------- | ----- |
+| Movie File In TOP | `moviefileinTop` | `file`, `speed`, `trim`, `index` | 加载视频文件、图像序列。 |
+| Movie File Out TOP | `moviefileoutTop` | `file`, `type` (codec), `record` (toggle) | 录制/导出视频文件。 |
+| NDI In TOP | `ndiinTop` | `sourcename` | 接收 NDI 视频流。 |
+| NDI Out TOP | `ndioutTop` | `sourcename` | 发送 NDI 视频流。 |
+| Syphon Spout In/Out TOP | `syphonspoutinTop` / `syphonspoutoutTop` | `servername` | 应用间纹理共享。 |
+| Video Device In TOP | `videodeviceinTop` | `device` | 网络摄像头/采集卡输入。 |
+| Feedback TOP | `feedbackTop` | `top` (path to the TOP to feed back) | 单帧延迟反馈。实现递归特效的必备工具。 |
+
+### Converters
+
+| Operator | Type Name | 方向 | 用途 |
+| ---------- | ----------- | ----------- | ----- |
+| CHOP to TOP | `choptopTop` | CHOP -> TOP | 将通道数据可视化为纹理 (波形、频谱显示)。 |
+| TOP to CHOP | `topchopChop` | TOP -> CHOP | 将纹理像素采样为通道数据。 |
+
+## CHOPs — Channel Operators (绿色)
+
+时变数值数据：音频、动画曲线、传感器数据、控制信号。
+
+### Generators
+
+| Operator | Type Name | Key Parameters | 用途 |
+| ---------- | ----------- | --------------- | ----- |
+| Constant CHOP | `constantChop` | `name0/value0`, `name1/value1`... | 静态命名通道。参数的控制面板。 |
+| LFO CHOP | `lfoChop` | `frequency`, `type` (0=Sin, 1=Tri, 2=Square, 3=Ramp, 4=Pulse), `amp`, `offset`, `phase` | 低频振荡器。动画驱动器。 |
+| Noise CHOP | `noiseChop` | `type`, `roughness`, `period`, `amp`, `seed`, `channels` | 平滑的随机运动。有机动画。 |
+| Pattern CHOP | `patternChop` | `type` (0=Sine, 1=Triangle, ...), `length`, `cycles` | 生成波形图案。 |
+| Timer CHOP | `timerChop` | `length`, `play`, `cue`, `cycles` | 带提示点的倒计时/正计时器。 |
+| Count CHOP | `countChop` | `threshold`, `limittype`, `limitmin/max` | 带有循环/钳制功能的事件计数器。 |
+
+### Audio
+
+| Operator | Type Name | Key Parameters | 用途 |
+| ---------- | ----------- | --------------- | ----- |
+| Audio File In CHOP | `audiofileinChop` | `file`, `volume`, `play`, `speed`, `trim` | 播放音频文件。 |
+| Audio Device In CHOP | `audiodeviceinChop` | `device`, `channels` | 实时麦克风/线路输入。 |
+| Audio Spectrum CHOP | `audiospectrumChop` | `size` (FFT size), `outputformat` (0=Power, 1=Magnitude) | FFT 频率分析。 |
+| Audio Band EQ CHOP | `audiobandeqChop` | `bands`, `gaindb` per band | 频段分离。 |
+| Audio Device Out CHOP | `audiodeviceoutChop` | `device` | 音频播放输出。 |
+
+### Math/Logic
+
+| Operator | Type Name | Key Parameters | 用途 |
+| ---------- | ----------- | --------------- | ----- |
+| Math CHOP | `mathChop` | `preoff`, `gain`, `postoff`, `chanop` (0=Off, 1=Add, 2=Subtract, 3=Multiply...) | 对通道进行数学运算。瑞士军刀级别的工具。 |
+| Logic CHOP | `logicChop` | `preop` (0=Off, 1=AND, 2=OR, 3=XOR, 4=NAND), `convert` | 对通道执行布尔逻辑运算。 |
+| Filter CHOP | `filterChop` | `type` (0=Low Pass, 1=Band Pass, 2=High Pass, 3=Notch), `cutofffreq`, `filterwidth` | 平滑、阻尼、过滤信号。 |
+| Lag CHOP | `lagChop` | `lag1/2`, `overshoot1/2` | 带有超调的平滑过渡。 |
+| Limit CHOP | `limitChop` | `type` (0=Clamp, 1=Loop, 2=ZigZag), `min/max` | 钳制或循环通道值。 |
+| Speed CHOP | `speedChop` | (none significant) | 积分值 (速度到位移，加速度到速度)。 |
+| Trigger CHOP | `triggerChop` | `attack`, `peak`, `decay`, `sustain`, `release` | 从触发事件生成 ADSR 包络。 |
+| Select CHOP | `selectChop` | `chop` (path), `channames` | 引用来自另一个 CHOP 的通道。 |
+| Merge CHOP | `mergeChop` | `align` (0=Extend, 1=Trim to First, 2=Trim to Shortest) | 合并多个 CHOPs 的通道。 |
+| Null CHOP | `nullChop` | (none significant) | 用于组织和引用的直通节点。 |
+
+### Input Devices
+
+| Operator | Type Name | 用途 |
+| ---------- | ----------- | ----- |
+| Mouse In CHOP | `mouseinChop` | 鼠标位置、按键、滚轮。 |
+| Keyboard In CHOP | `keyboardinChop` | 键盘按键状态。 |
+| MIDI In CHOP | `midiinChop` | MIDI 音符/CC 输入。 |
+| OSC In CHOP | `oscinChop` | OSC 消息输入 (网络)。 |
+
+## SOPs — Surface Operators (蓝色)
+
+3D 几何体：点、多边形、NURBS、网格。
+
+### Generators
+
+| Operator | Type Name | Key Parameters | 用途 |
+| ---------- | ----------- | --------------- | ----- |
+| Grid SOP | `gridSop` | `rows`, `cols`, `sizex/y`, `type` (0=Polygon, 1=Mesh, 2=NURBS) | 平面网格。置换、实例化的基础。 |
+| Sphere SOP | `sphereSop` | `type`, `rows`, `cols`, `radius` | 球体几何。 |
+| Box SOP | `boxSop` | `sizex/y/z` | 盒子几何。 |
+| Torus SOP | `torusSop` | `radiusx/y`, `rows`, `cols` | 圆环形状。 |
+| Circle SOP | `circleSop` | `type`, `radius`, `divs` | 圆形/环形几何。 |
+| Line SOP | `lineSop` | `dist`, `points` | 线段。 |
+| Text SOP | `textSop` | `text`, `fontsizex`, `fontfile`, `extrude` | 3D 文字几何。 |
+
+### Modifiers
+
+| Operator | Type Name | Key Parameters | 用途 |
+| ---------- | ----------- | --------------- | ----- |
+| Transform SOP | `transformSop` | `tx/ty/tz`, `rx/ry/rz`, `sx/sy/sz` | 变换几何 (平移、旋转、缩放)。 |
+| Noise SOP | `noiseSop` | `type`, `amp`, `period`, `roughness` | 使用噪声变形几何体。 |
+| Sort SOP | `sortSop` | `ptsort`, `primsort` | 重新排序点/图元。 |
+| Facet SOP | `facetSop` | `unique`, `consolidate`, `computenormals` | 法线、顶点合并、唯一化点。 |
+| Merge SOP | `mergeSop` | (none significant) | 合并多个几何输入。 |
+| Null SOP | `nullSop` | (none significant) | 直通。 |
+
+## DATs — Data Operators (白色)
+
+文本、表格、脚本、网络数据。
+
+### Core
+
+| Operator | Type Name | Key Parameters | 用途 |
+| ---------- | ----------- | --------------- | ----- |
+| Table DAT | `tableDat` | (edit content directly) | 类似电子表格的数据表。 |
+| Text DAT | `textDat` | (edit content directly) | 任意文本内容。Shader 代码、配置、脚本。 |
+| Script DAT | `scriptDat` | `language` (0=Python, 1=C++) | 自定义回调脚本和 DAT 处理。 |
+| CHOP Execute DAT | `chopexecDat` | `chop` (path to watch), callbacks | 在 CHOP 值更改时触发 Python 脚本。 |
+| DAT Execute DAT | `datexecDat` | `dat` (path to watch) | 在 DAT 内容更改时触发 Python 脚本。 |
+| Panel Execute DAT | `panelexecDat` | `panel` | 在 UI 面板事件触发时执行 Python 脚本。 |
+
+### I/O
+
+| Operator | Type Name | Key Parameters | 用途 |
+| ---------- | ----------- | --------------- | ----- |
+| Web DAT | `webDat` | `url`, `fetchmethod` (0=GET, 1=POST) | HTTP 请求。API 集成。 |
+| TCP/IP DAT | `tcpipDat` | `address`, `port`, `mode` | TCP 网络通信。 |
+| OSC In DAT | `oscinDat` | `port` | 接收 OSC 并作为文本消息处理。 |
+| Serial DAT | `serialDat` | `port`, `baudrate` | 串口通信 (Arduino 等)。 |
+| File In DAT | `fileinDat` | `file` | 读取文本文件。 |
+| File Out DAT | `fileoutDat` | `file`, `write` | 写入文本文件。 |
+
+### Conversions
+
+| Operator | Type Name | 方向 | 用途 |
+| ---------- | ----------- | ----------- | ----- |
+| DAT to CHOP | `dattochopChop` | DAT -> CHOP | 将表格数据转换为通道。 |
+| CHOP to DAT | `choptodatDat` | CHOP -> DAT | 将通道数据转换为表格行。 |
+| SOP to DAT | `soptodatDat` | SOP -> DAT | 提取几何数据作为表格。 |
+
+## MATs — Material Operators (黄色)
+
+用于在 Render TOP / Geometry COMP 中进行 3D 渲染的材质。
+
+| Operator | Type Name | Key Parameters | 用途 |
+| ---------- | ----------- | --------------- | ----- |
+| Phong MAT | `phongMat` | `diff_colorr/g/b`, `spec_colorr/g/b`, `shininess`, `colormap`, `normalmap` | 经典的 Phong 着色。简单、快速。 |
+| PBR MAT | `pbrMat` | `basecolorr/g/b`, `metallic`, `roughness`, `normalmap`, `emitcolorr/g/b` | 基于物理的渲染。逼真的材质。 |
+| GLSL MAT | `glslMat` | `dat` (shader DAT), custom uniforms | 用于 3D 的自定义 vertex + fragment shaders。 |
+| Constant MAT | `constMat` | `colorr/g/b`, `colormap` | 平面无光照颜色/纹理。没有阴影计算。 |
+| Point Sprite MAT | `pointspriteMat` | `colormap`, `scale` | 将点渲染为始终面向相机的精灵。非常适合粒子。 |
+| Wireframe MAT | `wireframeMat` | `colorr/g/b`, `width` | 线框渲染。 |
+| Depth MAT | `depthMat` | `near`, `far` | 将深度缓冲区渲染为灰度图。 |
+
+## COMPs — Component Operators (灰色)
+
+容器、3D 场景元素、UI 组件。
+
+### 3D Scene
+
+| Operator | Type Name | Key Parameters | 用途 |
+| ---------- | ----------- | --------------- | ----- |
+| Geometry COMP | `geometryComp` | `material` (path), `instancechop` (path), `instancing` (toggle) | 使用材质渲染几何体。实例化宿主。 |
+| Camera COMP | `cameraComp` | `tx/ty/tz`, `rx/ry/rz`, `fov`, `near/far` | Render TOP 的摄像机。 |
+| Light COMP | `lightComp` | `lighttype` (0=Point, 1=Directional, 2=Spot, 3=Cone), `dimmer`, `colorr/g/b` | 3D 场景的照明。 |
+| Ambient Light COMP | `ambientlightComp` | `dimmer`, `colorr/g/b` | 环境光照明。 |
+| Environment Light COMP | `envlightComp` | `envmap` | 基于图像的照明 (IBL)。 |
+
+### Containers
+
+| Operator | Type Name | Key Parameters | 用途 |
+| ---------- | ----------- | --------------- | ----- |
+| Container COMP | `containerComp` | `w`, `h`, `bgcolor1/2/3` | UI 容器。容纳其他 COMPs 用于面板布局。 |
+| Base COMP | `baseComp` | (none significant) | 通用容器。网络中嵌套网络。 |
+| Replicator COMP | `replicatorComp` | `template`, `operatorsdat` | 从表格克隆模板 operator N 次。 |
+
+### Utilities
+
+| Operator | Type Name | Key Parameters | 用途 |
+| ---------- | ----------- | --------------- | ----- |
+| Window COMP | `windowComp` | `winw/h`, `winoffsetx/y`, `monitor`, `borders` | 用于显示/投影的输出窗口。 |
+| Select COMP | `selectComp` | `rowcol`, `panel` | 从其他位置选择并显示内容。 |
+| Engine COMP | `engineComp` | `tox`, `externaltox` | 加载外部 .tox 组件。子进程隔离。 |
+
+## Cross-Family Converter 总结
+
+| From | To | Operator | Type Name |
+| ------ | ----- | ---------- | ----------- |
+| CHOP | TOP | CHOP to TOP | `choptopTop` |
+| TOP | CHOP | TOP to CHOP | `topchopChop` |
+| DAT | CHOP | DAT to CHOP | `dattochopChop` |
+| CHOP | DAT | CHOP to DAT | `choptodatDat` |
+| SOP | CHOP | SOP to CHOP | `soptochopChop` |
+| CHOP | SOP | CHOP to SOP | `choptosopSop` |
+| SOP | DAT | SOP to DAT | `soptodatDat` |
+| DAT | SOP | DAT to SOP | `dattosopSop` |
+| SOP | TOP | (use Render TOP + Geometry COMP) | — |
+| TOP | SOP | TOP to SOP | `toptosopSop` |

package/extensions/skills/builtin/creative/touchdesigner-mcp/references/panel-ui.md

@@ -0,0 +1,281 @@
+# Panel & UI Reference
+
+TouchDesigner 内部的交互式控制界面 —— 按钮、滑块、字段、自定义参数页面、panel 回调。关于 HUD 叠加层（视觉画面上渲染的文本），请参见 `layout-compositor.md`。
+
+使用场景:
+- VJ 控制机架 (master fader, scene buttons, FX toggles)
+- 装置 operator console
+- 自带参数 UI 的独立 TOX 组件
+- 显示在平板电脑上的手机风格触摸界面
+
+---
+
+## 两层 UI
+
+| Layer | What it is | Use for |
+|---|---|---|
+| **Custom Parameters** | 任何 COMP 上的参数，像内置 TD 参数一样编辑 | 可配置组件、预设、“设置”面板 |
+| **Panel COMPs** | containerCOMP 内部可见的小部件 (button, slider, field) | 交互式控制界面、实时 UI |
+
+将两者结合：构建一个带有 panel 小部件的 containerCOMP，用来读取/写入父组件上的 custom parameters。
+
+---
+
+## Custom Parameters
+
+向任何 COMP 添加用户可编辑的参数。参数会随 COMP 持久化保存，驱动表达式，并在保存/重新加载后依然存在。
+
+```python
+# Add a custom page to a baseCOMP
+comp = op('/project1/my_component')
+page = comp.appendCustomPage('Controls')
+
+# Add typed params
+page.appendFloat('Intensity', label='Intensity')[0]   # returns a Par
+page.appendInt('Count', label='Count')[0]
+page.appendToggle('Enabled', label='Enabled')[0]
+page.appendMenu('Mode', menuNames=['off', 'soft', 'hard'], menuLabels=['Off', 'Soft', 'Hard'])[0]
+page.appendStr('Title', label='Title')[0]
+page.appendRGB('Color', label='Color')                # returns 3 pars
+page.appendXY('Offset', label='Offset')               # returns 2 pars
+page.appendPulse('Reset', label='Reset')[0]
+page.appendFile('TextureFile', label='Texture')[0]
+```
+
+**从任何地方读取/写入：**
+
+```python
+val = op('/project1/my_component').par.Intensity.eval()
+op('/project1/my_component').par.Intensity = 0.7
+```
+
+**通过表达式驱动其他参数：**
+
+```python
+op('bloom1').par.threshold.mode = ParMode.EXPRESSION
+op('bloom1').par.threshold.expr = "op('/project1/my_component').par.Intensity"
+```
+
+**Pulse 处理程序 (Reset 按钮)：**
+
+使用 `parameterExecuteDAT` 监视 COMP 的 pulse 参数。参见 `dat-scripting.md`。
+
+---
+
+## Panel COMPs — 小部件
+
+每一个都是在一个 `containerCOMP` 中渲染为可点击/可拖拽小部件的 COMP。
+
+| Type | Type Name | Use |
+|---|---|---|
+| Button | `buttonCOMP` | 点击动作 — momentary 或 toggle |
+| Slider | `sliderCOMP` | 拖拽以设置 0-1 的值 (1D 或 2D) |
+| Field | `fieldCOMP` | 文本输入 |
+| Container | `containerCOMP` | 布局 + 视觉样式，包含子节点 |
+| Select | `selectCOMP` | 引用并显示来自另一个 COMP 的内容 |
+| List | `listCOMP` | 带行回调的可滚动列表 |
+
+### Button
+
+```python
+btn = root.create(buttonCOMP, 'play_btn')
+btn.par.w = 120; btn.par.h = 40
+btn.par.buttontype = 'momentary'    # 'momentary' | 'toggleup' | 'togglepress' | 'radio'
+btn.par.bgcolorr = 0.1; btn.par.bgcolorg = 0.1; btn.par.bgcolorb = 0.1
+btn.par.text = 'Play'
+
+# Read state
+state = btn.panel.state          # 1 when active
+```
+
+### Slider
+
+```python
+sld = root.create(sliderCOMP, 'master_fader')
+sld.par.w = 60; sld.par.h = 300
+sld.par.style = 'vertical'        # 'vertical' | 'horizontal' | 'xy'
+sld.par.value0min = 0.0
+sld.par.value0max = 1.0
+
+# Drive a parameter via expression (always-on, no callback needed)
+op('/project1/master_level').par.opacity.mode = ParMode.EXPRESSION
+op('/project1/master_level').par.opacity.expr = "op('master_fader').panel.u"
+```
+
+`panel.u` 和 `panel.v` 提供 0-1 的归一化值。对于 2D 滑块，这两个值都会被填充。
+
+### Field (文本输入)
+
+```python
+fld = root.create(fieldCOMP, 'scene_name')
+fld.par.w = 200; fld.par.h = 30
+fld.par.fieldtype = 'string'      # 'string' | 'integer' | 'float'
+
+# Read current text
+text = fld.panel.field            # the text content
+```
+
+### List
+
+对于带有可选择行的可滚动列表，使用停靠的 `list1_callbacks` DAT 来处理行交互。通过 `list_definition` table DAT 设置单元格。
+
+---
+
+## Container COMP — 布局与样式
+
+`containerCOMP` 是用于对小部件进行分组和排列布局的主要父级。
+
+```python
+panel = root.create(containerCOMP, 'control_panel')
+panel.par.w = 400; panel.par.h = 600
+panel.par.bgcolorr = 0.05
+panel.par.bgcolorg = 0.05
+panel.par.bgcolorb = 0.05
+panel.par.bgalpha = 1.0
+
+# Layout child panels in vertical stack
+panel.par.align = 'lefttoright'   # 'lefttoright' | 'toptobottom' | etc.
+```
+
+子节点会根据 `par.align` 自动定位。若要使用绝对定位，请使用 `par.align = 'fillresize'` 并设置每个子节点的 `par.x` / `par.y`。
+
+### 布局策略
+
+| `par.align` | Behavior |
+|---|---|
+| `lefttoright` | 子节点水平堆叠 |
+| `toptobottom` | 子节点垂直堆叠 |
+| `righttoleft` / `bottomtotop` | 反向堆叠 |
+| `fillresize` | 子节点尺寸自适应填充，手动定位 |
+| `top` / `bottom` / `left` / `right` | 固定定位 |
+
+对于复杂的网格：嵌套容器 — 即包含水平容器的垂直容器。
+
+---
+
+## Panel 回调 — 响应事件
+
+`panelExecuteDAT` 监视一个 panel，并在用户交互时触发 Python 回调。
+
+```python
+pe = root.create(panelExecuteDAT, 'btn_handler')
+pe.par.panel = '/project1/play_btn'
+pe.par.click = True              # respond to clicks
+pe.par.value = True              # respond to value changes
+```
+
+在它停靠的 DAT 中：
+
+```python
+def onOffToOn(panelValue):
+    # Click pressed
+    op('/project1/scene_timer').par.start.pulse()
+    return
+
+def onOnToOff(panelValue):
+    # Click released
+    return
+
+def onValueChange(panelValue):
+    # Slider drag, field change, etc.
+    new_val = panelValue.eval()
+    op('/project1/master').par.opacity = new_val
+    return
+```
+
+对于 custom-parameter 页面上的 pulse 参数，请改用 `parameterExecuteDAT`。
+
+---
+
+## 构建完整的 VJ 控制面板
+
+端到端模式：
+
+```python
+# 1. Top-level container
+panel = root.create(containerCOMP, 'vj_control')
+panel.par.w = 800; panel.par.h = 200
+panel.par.align = 'lefttoright'
+
+# 2. Master fader column
+master_col = panel.create(containerCOMP, 'master')
+master_col.par.w = 120; master_col.par.h = 200
+master_col.par.align = 'toptobottom'
+
+master_label = master_col.create(textTOP, 'lbl')
+master_label.par.text = 'MASTER'
+
+master_sld = master_col.create(sliderCOMP, 'fader')
+master_sld.par.w = 60; master_sld.par.h = 150
+master_sld.par.style = 'vertical'
+
+# 3. Scene buttons row
+scene_col = panel.create(containerCOMP, 'scenes')
+scene_col.par.w = 400; scene_col.par.h = 200
+scene_col.par.align = 'lefttoright'
+for i in range(8):
+    b = scene_col.create(buttonCOMP, f'scene_{i+1}')
+    b.par.w = 50; b.par.h = 50
+    b.par.text = str(i+1)
+    b.par.buttontype = 'radio'      # only one active at a time
+
+# 4. FX toggle column
+fx_col = panel.create(containerCOMP, 'fx')
+fx_col.par.w = 280; fx_col.par.h = 200
+fx_col.par.align = 'toptobottom'
+for fx in ['Bloom', 'CRT', 'Glitch', 'Strobe']:
+    t = fx_col.create(buttonCOMP, fx.lower())
+    t.par.w = 220; t.par.h = 35
+    t.par.text = fx
+    t.par.buttontype = 'toggleup'
+
+# 5. Display in a window
+win = root.create(windowCOMP, 'control_win')
+win.par.winop = panel.path
+win.par.winw = 800; win.par.winh = 200
+win.par.borders = True
+win.par.winopen.pulse()
+```
+
+然后通过表达式或 panelExecuteDATs 将面板值连接到 ops。
+
+---
+
+## 显示面板 — 窗口或嵌入
+
+| Approach | When |
+|---|---|
+| 指向面板的 `windowCOMP` | 独立的控制界面，单独的显示屏幕 |
+| 通过 `renderTOP` 渲染 containerCOMP | 将 UI 合成叠加在视觉画面上 (HUD 风格) |
+| 直接在网络编辑器窗格内使用 `panelCOMP` | 仅限设计师/开发者预览 — 面板完全可交互 |
+
+对于触摸屏平板电脑，在路由到平板电脑 HDMI 输入的第二个显示器上使用 `windowCOMP`。
+
+---
+
+## 常见陷阱
+
+1. **面板无法响应点击** — 可能是 `par.disabled = True` 或者父容器设置了 `par.disableinputs = True`。请检查面板层级。
+2. **滑块值未更新** — `panel.u/v` 读取的是视觉位置。如果你直接设置 `par.value0`，视觉效果会滞后。请将 `par.value0` 作为真实来源，让滑块跟随它。
+3. **自定义参数未出现** — 必须先调用 `appendCustomPage`，然后再追加参数。没有参数的页面不会显示。
+4. **自定义参数在重新加载后消失** — 在运行时通过 Python 添加的参数只有在之后保存了 COMP 的情况下才会被保留。请使用 `tox` 保存 (`comp.save('mycomp.tox')`) 或者通过 `td_execute_python` 提交然后保存项目。
+5. **事件回调触发两次** — 单次按钮按下可能同时触发 `onOffToOn` 和 `onValueChange`。选择其中一个来处理动作；不要重复触发。
+6. **Pulse 参数需要 `.pulse()`** — 在 pulse 参数上设置 `par.X = True` 没有任何作用。请始终使用 `.pulse()`。
+7. **字段文本直到按 Tab/Enter 才提交** — 字段在输入时不会触发回调。使用 `par.committemode = 'all'` 可以在每次按键时触发（开销较大）。
+8. **`par.text` 与面板内容** — `buttonCOMP.par.text` 是按钮上的标签。按钮的状态是 `panel.state` (0/1)。不要将它们混淆。
+9. **macOS 上的触摸输入** — 通过直接触摸面板进行的多点触控可以工作，但 TD 的手势处理非常基础。对于复杂的多点触控 (缩放/旋转)，请改用平板电脑上的 TouchOSC。
+10. **布局未更新** — 更改 `par.align` 需要容器重新 cook。触动一个子节点或 pulse 该容器即可触发。
+
+---
+
+## 快速配方
+
+| Goal | Setup |
+|---|---|
+| 主推子 | `sliderCOMP` (vertical) → 绑定在 `level.par.opacity` 上的表达式 |
+| 场景选择器 | 8 个 `buttonCOMP` (radio) → 针对它们状态的 `selectCHOP` → 驱动 `switchTOP.par.index` |
+| 特效开关 | `buttonCOMP` (toggleup) → 绑定在某个 FX op 的 `bypass` 上的表达式 |
+| 数字输入 | `fieldCOMP` (float) → 绑定在目标 par 上的表达式 |
+| 组件设置 | 组件 COMP 上的自定义参数，由内部的 panel 小部件驱动它们 |
+| 触摸平板 UI | 带有小部件的 `containerCOMP` → 位于第二个显示器的 `windowCOMP` |
+| 状态显示 | 通过 `selectCOMP` 渲染到面板中的 `textTOP` |