@baimingtao/lbs-agent 1.0.0

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

@@ -0,0 +1,463 @@
+# TouchDesigner Python API 参考文档
+
+## The td Module
+
+TouchDesigner 的 Python 环境会自动导入 `td` 模块。所有 TD 特有的类、函数和常量都位于此处。TD 内部的脚本（Script DAT、CHOP/DAT Execute 回调、Extensions）拥有完全访问权限。
+
+使用 MCP `execute_python_script` 工具时，会自动预加载以下全局变量：
+- `op` — `td.op()` 的快捷方式，通过路径查找 operators
+- `ops` — `td.ops()` 的快捷方式，通过模式查找多个 operators
+- `me` — 运行脚本的 operator（通过 MCP 时为 twozero 内部执行器）
+- `parent` — `me.parent()` 的快捷方式
+- `project` — 根 project 组件
+- `td` — 完整的 td 模块
+
+## 查找 Operators: op() 和 ops()
+
+### op(path) — 查找单个 operator
+
+```python
+# 绝对路径（从 MCP 始终有效）
+node = op('/project1/noise1')
+
+# 相对路径（相对于当前 operator — 仅在 Script DATs 中有效）
+node = op('noise1')      # 同级
+node = op('../noise1')   # 父级的同级
+
+# 未找到时返回 None（不会引发异常）
+node = op('/project1/nonexistent')  # None
+```
+
+### ops(pattern) — 查找多个 operators
+
+```python
+# Glob 模式
+nodes = ops('/project1/noise*')       # 所有以 "noise" 开头的节点
+nodes = ops('/project1/*')            # 所有直接子节点
+nodes = ops('/project1/container1/*') # container1 的所有子节点
+
+# 返回 operator 元组（可能为空）
+for n in ops('/project1/*'):
+    print(n.name, n.OPType)
+```
+
+### 从节点导航
+
+```python
+node = op('/project1/noise1')
+
+node.name        # 'noise1'
+node.path        # '/project1/noise1'
+node.OPType      # 'noiseTop'
+node.type         # <class 'noiseTop'>
+node.family       # 'TOP'
+
+# 父级 / 子级
+node.parent()              # 父级 COMP
+node.parent().children     # 所有同级及自身
+node.parent().findChildren(name='noise*')  # 过滤
+
+# 类型检查
+node.isTOP   # True
+node.isCHOP  # False
+node.isSOP   # False
+node.isDAT   # False
+node.isMAT   # False
+node.isCOMP  # False
+```
+
+## Parameters
+
+每个 operator 都具有可通过 `.par` 属性访问的参数。
+
+### 读取参数
+
+```python
+node = op('/project1/noise1')
+
+# 直接访问
+node.par.seed.val        # 当前求值结果（可能是表达式结果）
+node.par.seed.eval()     # 等同于 .val
+node.par.seed.default    # 默认值
+node.par.monochrome.val  # 布尔参数: True/False
+
+# 列出所有参数
+for p in node.pars():
+    print(f"{p.name}: {p.val} (default: {p.default})")
+
+# 按页面过滤（参数组）
+for p in node.pars('Noise'):  # 页面名称
+    print(f"{p.name}: {p.val}")
+```
+
+### 设置参数
+
+```python
+# 直接设置值
+node.par.seed.val = 42
+node.par.monochrome.val = True
+node.par.resolutionw.val = 1920
+node.par.resolutionh.val = 1080
+
+# 字符串参数
+op('/project1/text1').par.text.val = 'Hello World'
+
+# 文件路径
+op('/project1/moviefilein1').par.file.val = '/path/to/video.mp4'
+
+# 引用另一个 operator（适用于 "dat", "chop", "top" 类型的参数）
+op('/project1/glsl1').par.dat.val = '/project1/shader_code'
+```
+
+### 参数表达式
+
+```python
+# 动态求值的 Python 表达式
+node.par.seed.expr = "me.time.frame"
+node.par.tx.expr = "math.sin(me.time.seconds * 2)"
+
+# 引用另一个参数
+node.par.brightness1.expr = "op('/project1/constant1').par.value0.val"
+
+# 导出（从 CHOP 到参数的单向绑定）
+# 这会使参数跟随 CHOP 通道值
+op('/project1/noise1').par.seed.val  # 也可以由 exports 驱动
+```
+
+### 参数类型
+
+| 类型 | Python 类型 | 示例 |
+|------|------------|---------|
+| Float | `float` | `node.par.brightness1.val = 0.5` |
+| Int | `int` | `node.par.seed.val = 42` |
+| Toggle | `bool` | `node.par.monochrome.val = True` |
+| String | `str` | `node.par.text.val = 'hello'` |
+| Menu | `int` (索引) 或 `str` (标签) | `node.par.type.val = 'sine'` |
+| File | `str` (路径) | `node.par.file.val = '/path/to/file'` |
+| OP reference | `str` (路径) | `node.par.dat.val = '/project1/text1'` |
+| Color | 独立的 r/g/b/a 浮点数 | `node.par.colorr.val = 1.0` |
+| XY/XYZ | 独立的 x/y/z 浮点数 | `node.par.tx.val = 0.5` |
+
+## 创建和删除 Operators
+
+```python
+# 通过父级组件创建
+parent = op('/project1')
+new_node = parent.create(noiseTop)         # 使用类引用
+new_node = parent.create(noiseTop, 'my_noise')  # 带有自定义名称
+
+# MCP create_td_node 工具会自动处理此操作：
+# create_td_node(parentPath="/project1", nodeType="noiseTop", nodeName="my_noise")
+
+# 删除
+node = op('/project1/my_noise')
+node.destroy()
+
+# 复制
+original = op('/project1/noise1')
+copy = parent.copy(original, name='noise1_copy')
+```
+
+## 连接（Wiring Operators）
+
+### 从输出到输入的连接
+
+```python
+# 将 noise1 的输出连接到 level1 的输入
+op('/project1/noise1').outputConnectors[0].connect(op('/project1/level1'))
+
+# 连接到特定输入索引（适用于 Composite 等多输入 operators）
+op('/project1/noise1').outputConnectors[0].connect(op('/project1/composite1').inputConnectors[0])
+op('/project1/text1').outputConnectors[0].connect(op('/project1/composite1').inputConnectors[1])
+
+# 断开所有输出
+op('/project1/noise1').outputConnectors[0].disconnect()
+
+# 查询连接
+node = op('/project1/level1')
+inputs = node.inputs          # 已连接的输入 operators 列表
+outputs = node.outputs        # 已连接的输出 operators 列表
+```
+
+### 常见设置的连接模式
+
+```python
+# 线性链: A -> B -> C -> D
+ops_list = [op(f'/project1/{name}') for name in ['noise1', 'level1', 'blur1', 'null1']]
+for i in range(len(ops_list) - 1):
+    ops_list[i].outputConnectors[0].connect(ops_list[i+1])
+
+# 扇出: A -> B, A -> C, A -> D
+source = op('/project1/noise1')
+for target_name in ['level1', 'composite1', 'transform1']:
+    source.outputConnectors[0].connect(op(f'/project1/{target_name}'))
+
+# 合并: A + B + C -> Composite
+comp = op('/project1/composite1')
+for i, source_name in enumerate(['noise1', 'text1', 'ramp1']):
+    op(f'/project1/{source_name}').outputConnectors[0].connect(comp.inputConnectors[i])
+```
+
+## DAT 内容操作
+
+### Text DATs
+
+```python
+dat = op('/project1/text1')
+
+# 读取
+content = dat.text          # 以字符串形式获取完整文本
+
+# 写入
+dat.text = "new content"
+dat.text = '''multi
+line
+content'''
+
+# 追加
+dat.text += "\nnew line"
+```
+
+### Table DATs
+
+```python
+dat = op('/project1/table1')
+
+# 读取单元格
+val = dat[0, 0]         # 行 0, 列 0
+val = dat[0, 'name']    # 行 0, 名为 'name' 的列
+val = dat['key', 1]     # 名为 'key' 的行, 列 1
+
+# 写入单元格
+dat[0, 0] = 'value'
+
+# 读取行/列
+row = dat.row(0)         # Cell 对象列表
+col = dat.col('name')    # Cell 对象列表
+
+# 维度
+rows = dat.numRows
+cols = dat.numCols
+
+# 追加行
+dat.appendRow(['col1_val', 'col2_val', 'col3_val'])
+
+# 清空
+dat.clear()
+
+# 设置整个表格
+dat.clear()
+dat.appendRow(['name', 'value', 'type'])
+dat.appendRow(['frequency', '440', 'float'])
+dat.appendRow(['amplitude', '0.8', 'float'])
+```
+
+## 时间与动画
+
+```python
+# 全局时间
+td.absTime.frame       # 绝对帧数（从不重置）
+td.absTime.seconds     # 绝对秒数
+
+# 时间轴时间（受播放/暂停/循环影响）
+me.time.frame          # 时间轴上的当前帧
+me.time.seconds        # 时间轴上的当前秒数
+me.time.rate           # FPS 设置
+
+# 时间轴控制（通过 execute_python_script）
+project.play = True
+project.play = False
+project.frameRange = (1, 300)   # 设置时间轴范围
+
+# Cook 帧（operator 上次计算的时间）
+node.cookFrame
+node.cookTime
+```
+
+## Extensions（组件上的自定义 Python 类）
+
+Extensions 用于向 COMPs 添加自定义 Python 方法和属性。
+
+```python
+# 在 Base COMP 上创建 extension
+base = op('/project1/myBase')
+
+# Extension 类定义在 COMP 内部的一个 Text DAT 中
+# 通常命名为 'ExtClass'，包含以下 extension 代码：
+
+extension_code = '''
+class MyExtension:
+    def __init__(self, ownerComp):
+        self.ownerComp = ownerComp
+        self.counter = 0
+
+    def Reset(self):
+        self.counter = 0
+
+    def Increment(self):
+        self.counter += 1
+        return self.counter
+
+    @property
+    def Count(self):
+        return self.counter
+'''
+
+# 将 extension 代码写入 COMP 内部的 DAT 中
+op('/project1/myBase/extClass').text = extension_code
+
+# 在 COMP 上配置 extension
+base.par.extension1 = 'extClass'  # DAT 的名称
+base.par.promoteextension1 = True  # 将方法提升到父级
+
+# 调用 extension 方法
+base.Increment()       # 调用 MyExtension.Increment()
+count = base.Count     # 访问 MyExtension.Count 属性
+base.Reset()
+```
+
+## 常用内置模块
+
+### tdu — TouchDesigner 实用工具
+
+```python
+import tdu
+
+# 依赖追踪（响应式值）
+dep = tdu.Dependency(initial_value)
+dep.val = new_value   # 触发依赖项重新 cook
+
+# 文件路径工具
+tdu.expandPath('$HOME/Desktop/output.mov')
+
+# 数学运算
+tdu.clamp(value, min, max)
+tdu.remap(value, from_min, from_max, to_min, to_max)
+```
+
+### TDFunctions
+
+```python
+from TDFunctions import *
+
+# 常用实用工具
+clamp(value, low, high)
+remap(value, inLow, inHigh, outLow, outHigh)
+interp(value1, value2, t)  # 线性插值
+```
+
+### TDStoreTools — 持久化存储
+
+```python
+from TDStoreTools import StorageManager
+
+# 存储能在项目重新加载后保留的数据
+me.store('myKey', 'myValue')
+val = me.fetch('myKey', default='fallback')
+
+# 存储 dict
+me.storage['key'] = value
+```
+
+## 通过 execute_python_script 实现的常见模式
+
+### 构建完整的链路
+
+```python
+# 创建一个完整的音频反应性噪声链路
+parent = op('/project1')
+
+# 创建 operators
+audio_in = parent.create(audiofileinChop, 'audio_in')
+spectrum = parent.create(audiospectrumChop, 'spectrum')
+chop_to_top = parent.create(choptopTop, 'chop_to_top')
+noise = parent.create(noiseTop, 'noise1')
+level = parent.create(levelTop, 'level1')
+null_out = parent.create(nullTop, 'out')
+
+# 连接链路
+audio_in.outputConnectors[0].connect(spectrum)
+spectrum.outputConnectors[0].connect(chop_to_top)
+noise.outputConnectors[0].connect(level)
+level.outputConnectors[0].connect(null_out)
+
+# 设置参数
+audio_in.par.file = '/path/to/music.wav'
+audio_in.par.play = True
+spectrum.par.size = 512
+noise.par.type = 1  # Sparse
+noise.par.monochrome = False
+noise.par.resolutionw = 1920
+noise.par.resolutionh = 1080
+level.par.opacity = 0.8
+level.par.gamma1 = 0.7
+```
+
+### 查询网络状态
+
+```python
+# 获取项目中的所有 TOPs
+tops = [c for c in op('/project1').findChildren(type=TOP)]
+for t in tops:
+    print(f"{t.path}: {t.OPType} {'ERROR' if t.errors() else 'OK'}")
+
+# 查找所有有错误的 operators
+def find_errors(parent_path='/project1'):
+    parent = op(parent_path)
+    errors = []
+    for child in parent.findChildren(depth=-1):
+        if child.errors():
+            errors.append((child.path, child.errors()))
+    return errors
+
+result = find_errors()
+```
+
+### 批量更改参数
+
+```python
+# 在多个节点上一次性设置参数
+settings = {
+    '/project1/noise1': {'seed': 42, 'monochrome': False, 'resolutionw': 1920},
+    '/project1/level1': {'brightness1': 1.2, 'gamma1': 0.8},
+    '/project1/blur1': {'sizex': 5, 'sizey': 5},
+}
+
+for path, params in settings.items():
+    node = op(path)
+    if node:
+        for key, val in params.items():
+            setattr(node.par, key, val)
+```
+
+## Python 版本与包
+
+TouchDesigner 捆绑了 Python 3.11+，并预装了以下内容：
+- **numpy** — 数组操作，快速数学运算
+- **scipy** — 信号处理，FFT
+- **OpenCV** (cv2) — 计算机视觉
+- **PIL/Pillow** — 图像处理
+- **requests** — HTTP 客户端
+- **json**, **re**, **os**, **sys** — 标准库
+
+**重要提示：** 以下示例中的参数名称仅为说明之用。请务必运行发现步骤（SKILL.md Step 0）以获取适用于您 TD 版本的实际名称。请勿直接照抄这些示例中的参数名称。
+
+自定义包可以安装到 TD 的 Python site-packages 目录中。有关各平台的具体路径，请参阅 TD 文档。
+
+## SOP 顶点/点访问（TD 2025.32）
+
+在 TD 2025.32 中，`td.Vertex` 没有 `.x`、`.y`、`.z` 属性。请使用索引访问：
+
+```python
+# 错误 — 在 TD 2025.32 中会导致崩溃：
+vertex.x, vertex.y, vertex.z
+
+# 正确 — 索引/属性访问：
+pt = sop.points()[i]
+pos = pt.P          # Position 对象
+x, y, z = pos[0], pos[1], pos[2]
+
+# 请始终先进行内省检查：
+dir(sop.points()[0])   # 查看实际存在哪些属性
+dir(sop.points()[0].P) # 查看 Position 对象接口
+```

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

@@ -0,0 +1,197 @@
+# Replicator COMP 参考文档
+
+`replicatorCOMP` 会根据数据表将模板 operator 克隆 N 次。这是数据驱动网络的基础 TD 模式：按钮网格、场景列表、动态 UI 以及每个通道的 parameter 面板。
+
+关于视觉实例化（基于像素或渲染的副本），请参阅 `geometry-comp.md`。Replicator 用于构建 NETWORK NODES（网络节点）；实例化用于构建 RENDER COPIES（渲染副本）。它们属于不同的层级。
+
+---
+
+## 概念
+
+```
+[Template OP]                  [Data tableDAT]
+       │                              │
+       └─────→ replicatorCOMP ←───────┘
+                     │
+                     ▼
+        [N clones], one per data row
+        Each clone gets per-row params
+```
+
+编辑一次模板 → 所有克隆体都会继承。编辑表格 → 克隆体会动态添加或删除。可以按行推送 parameter 覆盖设置。
+
+---
+
+## 最小设置
+
+```python
+# 1. Make a template (the thing to clone)
+template = root.create(buttonCOMP, 'btn_template')
+template.par.w = 80; template.par.h = 80
+template.par.text = 'X'
+template.par.bgcolorr = 0.2
+
+# 2. Make a data table (one row per clone)
+data = root.create(tableDAT, 'scene_data')
+data.appendRow(['name', 'color_r', 'color_g', 'color_b'])
+data.appendRow(['Sunset', 1.0, 0.4, 0.0])
+data.appendRow(['Midnight', 0.0, 0.1, 0.4])
+data.appendRow(['Storm', 0.3, 0.3, 0.5])
+data.appendRow(['Forest', 0.0, 0.5, 0.2])
+
+# 3. Replicator — points at template + data
+rep = root.create(replicatorCOMP, 'scene_buttons')
+rep.par.template = template.path
+rep.par.opfromdat = data.path
+rep.par.namefromdatname = 'name'        # use 'name' column for clone names
+rep.par.incrementalnumbering = False
+```
+
+完成 cook 后，replicator 会创建 4 个名为 `Sunset`、`Midnight`、`Storm`、`Forest` 的子 COMP（每个非表头行对应一个），它们都是基于 `btn_template` 克隆而来的。
+
+---
+
+## 按行覆盖 Parameter
+
+Replicator 挂载的 `replicator1_callbacks` DAT 允许你自定义每个克隆体：
+
+```python
+def onReplicate(comp, allOps, newOps, template, master):
+    """Called once per replicate cycle. newOps is the list of just-created clones."""
+    data = op('scene_data')
+    for i, clone in enumerate(newOps):
+        row = i + 1                 # +1 to skip header
+        clone.par.text = data[row, 'name'].val
+        clone.par.bgcolorr = float(data[row, 'color_r'].val)
+        clone.par.bgcolorg = float(data[row, 'color_g'].val)
+        clone.par.bgcolorb = float(data[row, 'color_b'].val)
+    return
+```
+
+或者使用引用 `digits`（每个克隆体的索引，作为克隆子树中内置的 expression token）的 parameter expression：
+
+```python
+# Inside the template, set a param expression like:
+# par.value0.expr = "op('../scene_data')[me.digits + 1, 'value']"
+```
+
+`me.digits` 会解析为当前克隆体的行索引。这是处理静态引用模式最简洁的方法——不需要 callback。
+
+---
+
+## 布局：网格中的按钮
+
+将 replicator 放入一个启用了自动布局的 `containerCOMP` 中：
+
+```python
+panel = root.create(containerCOMP, 'scene_panel')
+panel.par.w = 400; panel.par.h = 100
+panel.par.align = 'lefttoright'
+
+# Move the replicator inside
+rep.parent = panel.path           # or create rep as a child of panel directly
+```
+
+每个克隆体都是 replicator 的子级（replicator 本身又是 panel 的子级）。panel 会自动排列所有元素。
+
+要实现 2D 网格，请在 container 上设置 `par.align = 'fillresize'`，并在 callback 中根据行/列索引覆盖每个克隆体的 `par.x` / `par.y`。
+
+---
+
+## 更新而不重建
+
+当数据表发生改变时，replicator 会重新生成克隆体。默认情况下，它会销毁并重新创建所有内容。为了保留状态，请设置：
+
+```python
+rep.par.recreatemissing = True       # only add/remove changed rows
+rep.par.recreateallonchange = False
+```
+这种模式对于实时编辑场景（设计师调整表格，网络保持运行）至关重要。
+
+对于增量数据摄取（例如，通过 `webDAT` 轮询 API），可以使用 `datExecuteDAT` 监听响应，解析数据并写入数据表，replicator 就会自动更新。
+
+---
+
+## 常见模式
+
+### 场景列表（数据 → 按钮 + 逻辑）
+
+```python
+# Data per scene: name, file path, audio track, BPM
+scene_data.appendRow(['name', 'file', 'audio', 'bpm'])
+scene_data.appendRow(['Intro', '/scenes/intro.tox', '/audio/intro.wav', 110])
+scene_data.appendRow(['Main', '/scenes/main.tox', '/audio/main.wav', 128])
+
+# Replicator clones a buttonCOMP per scene
+# Each button's onClick callback loads the corresponding tox + cues audio
+```
+
+### 动态 Parameter 面板
+
+对于一个频段列表，为每个频段生成一个推子条：
+
+```python
+# Data: band names (sub, low, mid, hi-mid, high, air)
+# Template: containerCOMP with label + sliderCOMP
+# Replicator clones N strips
+# Each slider's value is read at /audio_eq/{band_name}/fader
+```
+
+### 程序化视觉网络
+
+根据配置文件构建一个多通道视觉网络：
+
+```python
+# Data: which TOPs to chain, per "scene"
+# Template: a baseCOMP with placeholder children
+# Replicator builds one baseCOMP per scene; each scene contains a custom chain
+# Switch between scenes via switchTOP.par.index driven by panel
+```
+
+### 逐通道 CHOP 显示
+
+将多通道 CHOP 的每个通道单独可视化：
+
+```python
+# Data table: one row per channel (auto-extracted via choptodatDAT)
+# Template: a small chopVis COMP showing one channel
+# Replicator generates N visualizers stacked vertically
+```
+
+---
+
+## Replicator 与纯 Python 循环
+
+| 方法 | 适用场景 |
+| --- | --- |
+| **replicatorCOMP** | 克隆集会发生变化（实时添加/删除行）。符合可视化编辑器的预期。模式可跨项目复用。 |
+| **Python loop** (在 `td_execute_python` 中) | 一次性生成。静态集合。逻辑更简单，没有模板开销。编写速度更快。 |
+
+如果你只需要构建一次网络，请优先选择在 `td_execute_python` 中使用 Python 循环。当数据需要实时更新时，replicator 才能真正体现其价值。
+
+---
+
+## 陷阱
+
+1. **表头行** — `tableDAT` 的行索引从 0 开始。如果有表头，第一个数据行的索引就是 1。在 callback 中经常出现差一错误（off-by-one 错误）。
+2. **缺少 `namefromdatname` 列** — replicator 会默默使用 `digits`（数字后缀）来命名。按钮最终会被命名为 `1`、`2`、`3`，而不是有意义的名字。请务必显式设置 `par.namefromdatname`。
+3. **模板存在于网络中** — 模板 OP 本身也是一个真实的网络节点。不要直接将事物连接到它的下游；请连接到克隆体（或者在中间使用一个 `nullCOMP`）。
+4. **改变时重新创建会清除状态** — 每次重新生成时，克隆体内部的开关、推子位置以及未缓存的数据都会丢失。请使用 `recreatemissing` 进行保留。
+5. **`onReplicate` 在编辑时不会触发** — 只有当克隆集发生改变时才会触发。编辑现有行*内*的值不会重新触发它。请使用 `parameterExecuteDAT` 或 expression 实现逐单元格的实时更新。
+6. **克隆体上的自定义 parameter** — 在模板中添加的页面会被保留。在 `onReplicate` 中添加的页面在下一次重新生成时将不复存在。请始终在模板上添加自定义页面，而不是在克隆体上。
+7. **Cooking 风暴** — 快速添加许多行会触发大量克隆事件。请通过 Python 批量添加，并在最后调用一次 `data.cook(force=True)`。
+8. **在 replicator 子级之外使用 `me.digits`** — `me.digits` 只能在 replicator 后代的 op 中解析。不要在无关的网络中引用它。
+9. **跨克隆体引用** — 在克隆体内部通过相对路径引用兄弟克隆体是可以的（`op('../OtherClone/x')`），但如果名称改变，引用就会失效。推荐通过数据表使用绝对路径。
+
+---
+
+## 快速实例
+
+| 目标 | 设置 |
+| --- | --- |
+| 8 按钮场景选择器 | `tableDAT`（8 行）+ `buttonCOMP` 模板 + `replicatorCOMP` |
+| 逐频段 EQ 推子面板 | `tableDAT`（频段名称）+ container 模板（label + slider）+ replicator |
+| 数据驱动视觉场景 | `tableDAT`（场景配置）+ `baseCOMP` 模板（视觉链）+ replicator |
+| 实时更新的克隆集 | 同上 + `par.recreatemissing = True` |
+| 按行着色的 UI | 带有颜色列的数据表，`onReplicate` callback 设置每个克隆体的颜色 |
+| 来自 API 响应的列表 | `webDAT` → `datExecuteDAT` 解析 JSON → 写入数据表 → replicator 更新 |