@baimingtao/lbs-agent 1.0.0

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

@@ -0,0 +1,382 @@
+# twozero MCP 工具 参考
+
+来自 twozero MCP v2.774+（2026 年 4 月）的 36 个工具。
+所有工具均接受可选的 `target_instance` 参数，用于多 TD 实例场景。
+
+## Execution & Scripting
+
+### td_execute_python
+
+在 TouchDesigner 内部执行 Python 代码并返回结果。拥有完整的 TD Python API 访问权限（op, project, app 等）。Print 语句和最后一个表达式的值会被捕获。最适合：建立连接（inputConnectors）、设置表达式（par.X.expr/mode）、查询参数名称，以及批量创建脚本（5 个以上 operator）。若要创建 1-4 个 operator，建议改用 td_create_operator。
+
+| Param | 类型 | 必需 | 说明 |
+|-------|------|----------|-------------|
+| `code` | string | yes | 在 TouchDesigner 中执行的 Python 代码 |
+
+## Network & Structure
+
+### td_get_network
+
+获取 TouchDesigner (TD) 中指定路径下的 operator 网络结构。返回精简列表：name OPType flags。第一行是所查询 op 的完整路径。Flags：ch:N=子节点数量，!cook=allowCooking 关闭，bypass，private=isPrivate，blocked:reason，"comment text"。depth=0（默认）= 仅当前层级。depth=1 = 包含一层子节点（带缩进）。若需深入探索，请针对特定 COMP 路径再次调用。系统 operator（/ui, /sys）默认隐藏。
+
+| Param | 类型 | 必需 | 说明 |
+|-------|------|----------|-------------|
+| `path` | string | no | 要检查的网络路径，例如 '/' 或 '/project1' |
+| `depth` | integer | no | 递归深入的层级数。0=仅当前层级（推荐），1=包含 COMP 的直接子节点 |
+| `includeSystem` | boolean | no | 包含系统 operator（/ui, /sys）。默认为 false。 |
+| `nodeXY` | boolean | no | 包含 nodeX, nodeY 坐标。默认为 false。 |
+
+### td_create_operator
+
+在 TouchDesigner (TD) 中创建一个新的 operator（节点）。这是首选的 operator 创建方式——可自动处理视口定位、viewer 标志和停靠的 op。若要批量创建（5 个以上 op），你可以改用 td_execute_python 运行脚本，但需先调用 td_get_hints('construction') 以获取正确的参数名称和布局规则。支持所有 TD operator 类型：TOP, CHOP, SOP, DAT, COMP, MAT。若省略 parent，则会在用户当前视口打开的网络中创建。构建容器时：首先创建 baseCOMP（无 parent），然后创建子节点并指定 parent=compPath。
+
+| Param | 类型 | 必需 | 说明 |
+|-------|------|----------|-------------|
+| `type` | string | yes | Operator 类型，例如 'textDAT', 'constantCHOP', 'noiseTOP', 'transformTOP', 'baseCOMP' |
+| `parent` | string | no | 父 operator 的路径。若省略，则使用 TD 中当前打开的网络。 |
+| `name` | string | no | 新 operator 的名称（可选，若省略 TD 会自动命名） |
+| `parameters` | object | no | 要为创建的 operator 设置的参数键值对 |
+
+### td_find_op
+
+在整个项目中按名称和/或类型查找 operator。返回 TSV：path, OPType, flags。Flags：bypass, !cook, private, blocked:reason。使用 td_search 搜索代码/表达式内部；使用 td_find_op 查找 operator 本身。
+
+| Param | 类型 | 必需 | 说明 |
+|-------|------|----------|-------------|
+| `name` | string | no | 要与 operator 名称匹配的子字符串（不区分大小写）。例如 'noise' 会找到 noise1, noise2, myNoise。 |
+| `type` | string | no | 要与 OPType 匹配的子字符串（不区分大小写）。例如 'noiseTOP', 'baseCOMP', 'CHOP'。使用准确类型可精确匹配，或使用部分类型扩大匹配范围。 |
+| `root` | string | no | 搜索的根 operator 路径。默认为 '/project1'。 |
+| `max_results` | number | no | 返回的最大结果数。默认为 50。 |
+| `max_depth` | number | no | 从根节点开始的最大递归深度。默认无限制。 |
+| `detail` | `basic` / `summary` | no | 结果详细程度。'basic' = 名称/路径/类型（快速）。'summary' = + 连接、非默认参数、表达式。默认 'basic'。 |
+
+### td_search
+
+在整个 TD 项目中搜索所有代码（DAT 脚本）、参数表达式和字符串参数值中的文本。返回 TSV：path, kind (code/expression/parameter/ref), line, text。当 context>0 时返回 JSON。单词按 OR 逻辑匹配。使用引号进行精确短语匹配：'GetLogin "op('login')"'。使用 count_only=true 可在不获取完整结果的情况下快速检查是否引用了某内容。
+
+| Param | 类型 | 必需 | 说明 |
+|-------|------|----------|-------------|
+| `query` | string | yes | 搜索查询。多个单词 = OR（任意匹配）。用引号括起来表示精确短语。例如：'GetLogin getLogin' 会匹配两者。 |
+| `root` | string | no | 搜索的根 operator 路径。默认为 '/project1'。 |
+| `scope` | `all` / `code` / `editable` / `expressions` / `parameters` | no | 搜索范围。'code' = 仅 DAT 脚本（快，约 0.05 秒）。'editable' = 仅可编辑代码（跳过继承/参考的 DAT）。'expressions' = 仅参数表达式。'parameters' = 仅字符串参数值。'all' = 全部（慢，由于需扫描参数约 1.5 秒）。默认 'all'。 |
+| `case_sensitive` | boolean | no | 区分大小写匹配。默认 false。 |
+| `max_results` | number | no | 返回的最大结果数。默认 50。 |
+| `context` | number | no | 每个代码匹配项前后显示的行数。可减少 td_read_dat 调用。默认 0。 |
+| `count_only` | boolean | no | 仅返回匹配数量，不返回结果。用于快速检查存在性。 |
+| `max_depth` | number | no | 从根节点开始的最大递归深度。默认无限制。 |
+
+### td_navigate_to
+
+导航 TouchDesigner 网络编辑器视口以显示特定的 operator。打开该 operator 的父网络并将视图居中于其上。当你想向用户展示问题所在，或在修改 operator 之前导航定位到该节点时，请使用此工具。
+
+| Param | 类型 | 必需 | 说明 |
+|-------|------|----------|-------------|
+| `path` | string | yes | 要导航到的 operator 路径，例如 '/project1/noise1' |
+
+## Operator Inspection
+
+### td_get_operator_info
+
+获取有关 TouchDesigner (TD) 中特定 operator（节点）的信息。detail='summary'：连接、非默认参数、表达式、CHOP 通道（精简）。detail='full'：包含上述所有内容，加上每个参数的 value/default/label。
+
+| Param | 类型 | 必需 | 说明 |
+|-------|------|----------|-------------|
+| `path` | string | yes | operator 的完整路径，例如 '/project1/noise1' |
+| `detail` | `summary` / `full` | no | 详细级别。'summary' = 连接、表达式、非默认参数、自定义参数（标记了 pulse）、CHOP 通道。'full' = summary + 所有参数。默认 'full'。 |
+
+### td_get_operators_info
+
+在一次调用中获取多个 operator 的信息。返回 operator 信息对象数组。请使用此工具代替多次调用 td_get_operator_info。
+
+| Param | 类型 | 必需 | 说明 |
+|-------|------|----------|-------------|
+| `paths` | array | yes | 完整 operator 路径数组，例如 ['/project1/null1', '/project1/null2'] |
+| `detail` | `summary` / `full` | no | 详细级别。默认 'summary'。 |
+
+### td_get_par_info
+
+获取 TouchDesigner operator 类型的参数名称和详细信息。不指定 pars 时：返回包含所有参数名称、类型和菜单选项的精简列表。指定 pars 时：返回特定参数的完整详细信息（帮助文本、菜单值、样式）。当你需要在设置之前了解确切的参数名称时使用。
+
+| Param | 类型 | 必需 | 说明 |
+|-------|------|----------|-------------|
+| `op_type` | string | yes | TD operator 类型名称，例如 'noiseTOP', 'blurTOP', 'lfoCHOP', 'compositeTOP' |
+| `pars` | array | no | 用于获取完整详细信息的特定参数名称的可选列表 |
+
+## Parameter Setting
+
+### td_set_operator_pars
+
+在 TouchDesigner (TD) 中为 operator 设置参数和标志。对于简单的参数更改，比 td_execute_python 更安全。无需编写 Python 代码即可设置值、切换 bypass/viewer。
+
+| Param | 类型 | 必需 | 说明 |
+|-------|------|----------|-------------|
+| `path` | string | yes | operator 路径 |
+| `parameters` | object | no | 要设置的参数键值对 |
+| `bypass` | boolean | no | 设置 operator 的 bypass 状态（在 COMP 上不可用） |
+| `viewer` | boolean | no | 设置 operator 的 viewer 状态 |
+| `allowCooking` | boolean | no | 设置 COMP 上的 cooking 标志。当为 False 时，内部网络停止计算（0 CPU）。仅适用于 COMP。 |
+
+## Data Read/Write
+
+### td_read_dat
+
+读取 TouchDesigner (TD) 中 DAT operator 的文本内容。返回带有行号的内容。用于读取脚本、extension、GLSL shader 和表格数据。
+
+| Param | 类型 | 必需 | 说明 |
+|-------|------|----------|-------------|
+| `path` | string | yes | DAT operator 的路径 |
+| `start_line` | integer | no | 起始行（基于 1）。省略则从开头读取。 |
+| `end_line` | integer | no | 结束行（包含）。省略则读取到结尾。 |
+
+### td_write_dat
+
+写入或修改 TouchDesigner (TD) 中 DAT operator 的文本内容。可进行完全替换或类似 StrReplace 的修补（old_text -> new_text）。用于编辑脚本、extension 和 shader。不会自动重新初始化 extension。
+
+| Param | 类型 | 必需 | 说明 |
+|-------|------|----------|-------------|
+| `path` | string | yes | DAT operator 的路径 |
+| `text` | string | no | 完整的替换文本。使用此项或 old_text+new_text，不能同时使用。 |
+| `old_text` | string | no | 要查找并替换的文本（在 DAT 中必须唯一） |
+| `new_text` | string | no | 替换后的文本 |
+| `replace_all` | boolean | no | 如果为 true，替换所有出现的 old_text（默认为 false，要求匹配项唯一） |
+
+### td_read_chop
+
+读取 CHOP 通道的采样数据。以数组形式返回通道值。适用于你需要实际采样值（动画曲线、查找表、波形），而不仅仅是 td_get_operator_info 中摘要信息的情况。
+
+| Param | 类型 | 必需 | 说明 |
+|-------|------|----------|-------------|
+| `path` | string | yes | CHOP operator 的路径 |
+| `channels` | array | no | 要读取的通道名称。省略则读取所有通道。 |
+| `start` | integer | no | 起始采样索引（基于 0）。省略则从开头读取。 |
+| `end` | integer | no | 结束采样索引（包含）。省略则读取到结尾。 |
+
+### td_read_textport
+
+从 TouchDesigner (TD) 的日志/textport（控制台输出）读取最后 N 行。用于查看 TD 的错误、警告和 print 输出。
+
+| Param | 类型 | 必需 | 说明 |
+|-------|------|----------|-------------|
+| `lines` | integer | no | 要返回的最近行数 |
+
+### td_clear_textport
+
+清除 MCP textport 日志缓冲区。在开始调试会话或“编辑-运行-检查”循环之前使用此工具，以保持 td_read_textport 输出集中且最小化。
+
+无参数（除可选的 `target_instance` 外）。
+
+## Visual Capture
+
+### td_get_screenshot
+
+获取 TouchDesigner (TD) 中 operator viewer 的截图。将图像保存到文件并返回文件路径。使用你的文件读取工具查看图像。展示 operator 在其 viewer 中的外观（TOP 输出、CHOP 波形图、SOP 几何体、DAT 表格、参数 UI 等）。用于直观检查任何 operator，或通过 TD 生成图像供项目使用。两步异步使用：步骤 1 — 使用 'path' 调用以启动：返回 {'status': 'pending', 'requestId': '...'}。步骤 2 — 使用 'request_id' 调用以获取结果：返回 {'file': '/tmp/.../opname_id.jpg'}。然后读取该文件即可查看图像。如果步骤 2 仍返回 pending，请进行其他工具调用然后重试。
+
+| Param | 类型 | 必需 | 说明 |
+|-------|------|----------|-------------|
+| `path` | string | no | 要截图的 operator 完整路径，例如 '/project1/noise1'。步骤 1 必需。 |
+| `request_id` | string | no | 从步骤 1 获取的 request ID，用于提取完成的截图。 |
+| `max_size` | integer | no | 长边的最大像素尺寸（默认 512）。使用 0 保持 operator 原始分辨率（适用于像素级精确的 UI 工作）。数值越高（例如 1024）细节越丰富。 |
+| `output_path` | string | no | 可选的图像保存绝对路径（例如 '/Users/me/project/render.png'）。如果省略，将保存到 /tmp/pisang_mcp/screenshots/。请使用绝对路径——TD 的工作目录可能与 agent 的不同。 |
+| `as_top` | boolean | no | 如果为 true，直接以 TOP 形式捕获 operator（绕过 viewer 渲染器），从而保留 alpha/透明度。仅适用于 TOP operator——如果目标不是 TOP，会自动回退到 viewer。当你需要带 alpha 的干净 PNG 时使用此选项，例如保存生成的图像供另一个项目使用。 |
+| `format` | `auto` / `jpg` / `png` | no | 图像格式。'auto'（默认）：viewer 模式使用 JPEG，as_top=true 时使用 PNG。'jpg'：始终为 JPEG（体积更小）。'png'：始终为 PNG（无损）。 |
+
+### td_get_screenshots
+
+批量获取多个 operator 的截图。将图像保存到文件并返回文件路径。使用你的文件读取工具查看图像。两步异步使用：步骤 1 — 使用 'paths' 数组调用以启动：返回 {'status': 'pending', 'batchId': '...', 'total': N}。步骤 2 — 使用 'batch_id' 调用以获取结果：返回 {'files': [{op, file}, ...]}。然后读取这些文件即可查看图像。如果仍在处理中，会返回 {'status': 'pending', 'ready': K, 'total': N}。
+
+| Param | 类型 | 必需 | 说明 |
+|-------|------|----------|-------------|
+| `paths` | array | no | 要截图的 operator 完整路径列表。步骤 1 必需。 |
+| `batch_id` | string | no | 从步骤 1 获取的 batch ID，用于提取完成的截图。 |
+| `max_size` | integer | no | 长边的最大像素尺寸（默认 512）。使用 0 保持原始分辨率。 |
+| `as_top` | boolean | no | 如果为 true，直接捕获 TOP operator（保留 alpha）。非 TOP operator 自动回退到 viewer。 |
+| `output_dir` | string | no | 可选的目录绝对路径。每张截图将作为 <opname>.jpg 或 .png 保存在其中并保留在磁盘上。 |
+| `format` | `auto` / `jpg` / `png` | no | 图像格式。'auto'（默认）：viewer 模式使用 JPEG，as_top=true 时使用 PNG。'jpg'：始终为 JPEG（体积更小）。'png'：始终为 PNG（无损）。 |
+
+### td_get_screen_screenshot
+
+通过 TD 的 screenGrabTOP 捕获真实屏幕的截图。将图像保存到文件并返回文件路径。使用你的文件读取工具查看图像。与 td_get_screenshot（operator viewer）不同，这会显示用户在显示器上真实看到的内容——TD 窗口、UI 面板等一切。适用于模拟鼠标/键盘输入以验证屏幕上发生的操作。工作流：td_get_screen_screenshot → 读取文件 → td_input_execute → 等待空闲 → 再次调用 td_get_screen_screenshot。两步异步：步骤 1 — 不带 request_id 调用：返回 {'status':'pending','requestId':'...'}。步骤 2 — 使用 request_id 调用：返回 {'file': '/tmp/.../screen_id.jpg', 'info': '...metadata...'}。然后读取该文件以查看图像。该 requestId 也可保留供之后通过 td_screen_point_to_global 进行坐标查询。crop_x/y/w/h 基于真实屏幕像素（而非图像像素）。超出屏幕边界的裁剪会被自动钳制。智能默认值：省略时 max_size 为自动——全屏使用 1920（便于概览），裁剪使用 max(crop_w,crop_h)（保证 1:1 比例）。在 1:1 比例下：screen_coord = crop_origin + image_pixel。否则使用元数据中提供的公式。
+
+| Param | 类型 | 必需 | 说明 |
+|-------|------|----------|-------------|
+| `request_id` | string | no | 从步骤 1 获取的 request ID，用于提取完成的截图。 |
+| `max_size` | integer | no | 长边的最大像素尺寸。省略时自动：全屏 1920，裁剪为 max(crop_w,crop_h)（1:1 比例）。显式设置以覆盖默认值。 |
+| `crop_x` | integer | no | 屏幕像素中的左边缘位置。 |
+| `crop_y` | integer | no | 屏幕像素中的顶边缘位置（y=0 在屏幕顶部）。 |
+| `crop_w` | integer | no | 宽度（像素）。 |
+| `crop_h` | integer | no | 高度（像素）。 |
+| `display` | integer | no | 屏幕索引（默认 0 = 主显示器）。 |
+
+## Context & Focus
+
+### td_get_focus
+
+获取 TouchDesigner (TD) 中当前用户的焦点：打开的网络、选中的 operator、当前 operator 以及 rollover（鼠标光标下的内容）。重要提示：当用户说“这个 operator”或“вот этот”时，他们指的是选中/当前的 operator，而不是 rollover。Rollover 只是偶然的鼠标位置，在意图判断中应忽略。传入 screenshots=true 可立即为所有选中的 operator 启动批量截图——响应包含带有 batchId 的 'screenshots' 字段；使用 td_get_screenshots(batch_id=...) 获取结果。
+
+| Param | 类型 | 必需 | 说明 |
+|-------|------|----------|-------------|
+| `screenshots` | boolean | no | 如果为 true，为所有选中的 operator 启动批量截图。使用 td_get_screenshots(batch_id=...) 提取。 |
+| `max_size` | integer | no | screenshots=true 时的最大截图尺寸（默认 512）。 |
+| `as_top` | boolean | no | screenshots=true 时传递给批量截图的参数。 |
+
+### td_get_errors
+
+在 TouchDesigner (TD) 的 operator 中查找错误和警告。检查 operator 错误、警告以及损坏的参数表达式（缺失通道、错误引用等）。还会包含日志中最近的脚本错误（traceback），并经过分组和去重——例如 1000 个相同的鼠标移动错误将显示为一条带 ×1000 标记的记录。如果提供了路径，则检查该 operator 及其子节点。如果没有提供路径，则检查当前打开的网络。使用 '/' 检查整个项目。适用于用户反馈某些东西损坏、有错误、红色节点、горит ошибка 等情况。提示：在复现错误之前调用 td_clear_textport 以保持日志集中。提示：当用户说“тупит/лагает”时，与 td_get_perf 结合使用以同时检查错误和性能。
+
+| Param | 类型 | 必需 | 说明 |
+|-------|------|----------|-------------|
+| `path` | string | no | 要检查的路径。如果省略，检查当前网络。使用 '/' 扫描整个项目。 |
+| `recursive` | boolean | no | 递归检查子节点（默认 true） |
+| `include_log` | boolean | no | 包含日志中最近的脚本错误，按唯一签名分组（默认 true）。在复现错误之前使用 td_clear_textport 以保持结果集中。 |
+
+### td_get_perf
+
+从 TouchDesigner (TD) 获取性能数据。返回 TSV：包含 fps/budget/memory 摘要的头部，随后是按 cook 时间排序的最慢 operator。列：path, OPType, cpu/cook(ms), gpu/cook(ms), cpu/s, gpu/s, rate, flags。适用于用户报告卡顿、低 FPS、性能慢、тупит、тормозит 的情况。
+
+| Param | 类型 | 必需 | 说明 |
+|-------|------|----------|-------------|
+| `path` | string | no | 要分析的路径。如果省略，分析当前网络。使用 '/' 检查整个项目。 |
+| `top` | integer | no | 返回的最慢 operator 数量 |
+
+## Documentation
+
+### td_get_docs
+
+获取有关 TouchDesigner 主题的综合文档。与 td_get_hints（精简提示）不同，它会返回深入的参考资料。不带参数调用可查看可用主题及描述。使用主题名称调用可获取完整文档。
+
+| Param | 类型 | 必需 | 说明 |
+|-------|------|----------|-------------|
+| `topic` | string | no | 要获取文档的主题。省略以列出可用主题。 |
+
+### td_get_hints
+
+获取有关 TouchDesigner 主题的提示和常见模式。在创建 operator 或编写 TD Python 代码之前调用此工具，以学习正确的参数名称、表达式和惯用方法。可用主题：animation, noise, connections, parameters, scripting, construction, ui_analysis, panel_layout, screenshots, input_simulation, undo。重要提示：在构建多 operator 设置之前，始终使用 topic='construction' 调用以获取正确的 TOP/CHOP 参数名称、compositeTOP 输入顺序和布局指南。重要提示：在使用 td_input_execute 之前，始终使用 topic='input_simulation' 调用以了解焦点恢复、坐标系统和测试工作流。
+
+| Param | 类型 | 必需 | 说明 |
+|-------|------|----------|-------------|
+| `topic` | string | yes | 要获取提示的主题。可选：'animation', 'noise', 'connections', 'parameters', 'scripting', 'construction', 'ui_analysis', 'panel_layout', 'screenshots', 'input_simulation', 'undo', 'networking', 'all' |
+
+### td_agents_md
+
+读取、写入或更新 COMP 容器内部的 agents_md 文档。agents_md 是一个 Markdown 格式的 textDAT，用于描述容器的用途、结构和约定。action='read'：返回内容 + 过期检查（对比记录的子节点与实时状态）。action='update'：从实时状态刷新自动生成的部分（子节点列表、连接），保留手写部分。action='write'：设置完整内容，如果缺失则创建 DAT。
+
+| Param | 类型 | 必需 | 说明 |
+|-------|------|----------|-------------|
+| `path` | string | yes | COMP 容器的路径 |
+| `action` | `read` / `update` / `write` | yes | read=获取内容+过期检查，update=刷新自动部分，write=设置内容 |
+| `content` | string | no | Markdown 内容（仅用于 action='write'） |
+
+## Input Automation
+
+### td_input_execute
+
+向 TouchDesigner 发送一系列鼠标/键盘命令。命令按顺序执行，并带有平滑的贝塞尔曲线移动。立即返回——轮询 td_input_status() 直到 status='idle' 再继续。命令类型：'focus' — 将 TD 置于前台。'move' — 平滑鼠标移动：{type,x,y,duration,easing}。'click' — 点击：{type,x,y,button,hold,duration,easing}。hold=按下的秒数。duration=点击前的平滑移动时间。'dblclick' — 双击：{type,x,y,duration}。'mousedown'/'mouseup' — {type,x,y,button}。'key' — 击键：{type,keys}，例如 'ctrl+z','tab','escape','shift+f5'。在 Mac 上需要辅助功能（Accessibility）权限。'type' — 模拟人类打字：{type,text,wpm,variance} — 与布局无关的 Unicode，带有可变时间。'wait' — 暂停：{type,duration}。'scroll' — {type,x,y,dx,dy,steps} — 模拟人类滚动：首先将鼠标移动到 (x,y)，然后以自然的节奏作为多个刻度发送 dy（垂直，+上）和 dx（水平，+右）。默认 steps=4。鼠标命令可包含 coord_space='logical'（默认）或 coord_space='physical'。在 macOS 上，'physical' 表示来自 td_get_screen_screenshot 的实际屏幕像素，并会自动转换为 CGEvent 逻辑坐标。顶层的 coord_space 适用于未自行覆盖该参数的命令。on_error：'stop'（默认）在出错时清除队列；'continue' 跳过失败的命令。重要提示：首次使用前调用 td_get_hints('input_simulation') 了解焦点恢复、坐标系统和测试工作流。
+
+| Param | 类型 | 必需 | 说明 |
+|-------|------|----------|-------------|
+| `commands` | array | yes | 要按顺序执行的命令字典列表。 |
+| `coord_space` | `logical` / `physical` | no | 未指定自身 coord_space 的鼠标命令的默认坐标空间。'logical' 直接使用 CGEvent 坐标。'physical' 使用来自 td_get_screen_screenshot 的实际屏幕像素，并在 macOS 上自动转换。 |
+| `on_error` | `stop` / `continue` | no | 出错时的操作。默认 'stop'。 |
+
+### td_input_status
+
+获取 td_input 命令队列的当前状态。在 td_input_execute 之后轮询此状态，直到 status='idle'。返回：status（'idle'/'running'）、当前命令、queue_remaining、最后错误。
+
+无参数（除可选的 `target_instance` 外）。
+
+### td_input_clear
+
+清除 td_input 命令队列并立即停止当前执行。
+
+无参数（除可选的 `target_instance` 外）。
+
+### td_op_screen_rect
+
+获取网络编辑器中 operator 节点的屏幕坐标。返回 {x,y,w,h,cx,cy}，其中 cx,cy 是用于点击的中心。当你需要寻找特定 operator 的点击位置时使用。仅当该 operator 的父网络当前在某个网络编辑器面板中打开时才有效。
+
+| Param | 类型 | 必需 | 说明 |
+|-------|------|----------|-------------|
+| `path` | string | yes | operator 的完整路径，例如 '/project1/myComp/noise1' |
+
+### td_click_screen_point
+
+解析之前 td_get_screen_screenshot 结果中的某个点并点击它。传入截图 request_id 以及 normalized u/v 或 image_x/image_y。使用物理屏幕坐标将 td_input 点击加入队列，因此可直接配合截图得出的点使用。使用 duration/easing 控制点击前的光标移动。
+
+| Param | 类型 | 必需 | 说明 |
+|-------|------|----------|-------------|
+| `request_id` | string | yes | 最初由 td_get_screen_screenshot 返回的 request ID。 |
+| `u` | number | no | 截图区域内的归一化水平位置（0=左，1=右）。与 v 配合使用。 |
+| `v` | number | no | 截图区域内的归一化垂直位置（0=上，1=下）。与 u 配合使用。 |
+| `image_x` | number | no | 返回的截图图像内的水平像素坐标。与 image_y 配合使用。 |
+| `image_y` | number | no | 返回的截图图像内的垂直像素坐标。与 image_x 配合使用。 |
+| `button` | `left` / `right` / `middle` | no | 要点击的鼠标按钮。默认 left。 |
+| `hold` | number | no | 释放前按住鼠标按钮的秒数。 |
+| `duration` | number | no | 点击前光标移动到目标位置的秒数。 |
+| `easing` | `linear` / `ease-in` / `ease-out` / `ease-in-out` | no | 点击前移动的鼠标光标缓动效果。 |
+| `focus` | boolean | no | 如果为 true，在点击前将 TD 置于最前，并稍作等待以稳定焦点。 |
+
+### td_screen_point_to_global
+
+将之前 td_get_screen_screenshot 结果中的点转换为绝对屏幕坐标。传入截图 request_id 以及归一化 u/v（在该截图区域内为 0..1）或返回图像像素中的 image_x/image_y。返回绝对物理屏幕坐标、逻辑坐标以及可直接使用的 td_input_execute 负载。最近的屏幕截图元数据会被保留，以便多个 agent 以后可以通过 request_id 解析点。
+
+| Param | 类型 | 必需 | 说明 |
+|-------|------|----------|-------------|
+| `request_id` | string | yes | 最初由 td_get_screen_screenshot 返回的 request ID。 |
+| `u` | number | no | 截图区域内的归一化水平位置（0=左，1=右）。与 v 配合使用。 |
+| `v` | number | no | 截图区域内的归一化垂直位置（0=上，1=下）。与 u 配合使用。 |
+| `image_x` | number | no | 返回的截图图像内的水平像素坐标。与 image_y 配合使用。 |
+| `image_y` | number | no | 返回的截图图像内的垂直像素坐标。与 image_x 配合使用。 |
+
+## System
+
+### td_list_instances
+
+列出所有正在运行且带有活动 MCP 服务器的 TouchDesigner (TD) 实例。返回每个实例的端口、项目名称、PID 和 instanceId。在每次对话开始时调用此工具，以发现可用实例并选择要操作的实例。instanceId 在 TD 进程的生命周期内是稳定的，并在所有其他工具调用中用作 target_instance。
+
+无参数（除可选的 `target_instance` 外）。
+
+### td_project_quit
+
+保存和/或关闭当前的 TouchDesigner (TD) 项目。可在关闭前保存。报告项目是否有未保存的更改。要关闭其他实例，请传入 target_instance=instanceId。警告：这将关闭该实例上的 MCP 服务器。
+
+| Param | 类型 | 必需 | 说明 |
+|-------|------|----------|-------------|
+| `save` | boolean | no | 关闭前保存项目。默认 true。 |
+| `force` | boolean | no | 强制关闭且不弹出保存对话框。默认 false。 |
+
+### td_reinit_extension
+
+在 TouchDesigner (TD) 中重新初始化 COMP 上的 extension。在通过 td_write_dat 完成所有代码编辑后调用此工具以应用更改。不要在每次微小修改后调用——请先批量处理你的修改。
+
+| Param | 类型 | 必需 | 说明 |
+|-------|------|----------|-------------|
+| `path` | string | yes | 带有 extension 的 COMP 路径 |
+
+### td_dev_log
+
+从 MCP 开发日志中读取最后 N 条记录。仅在启用 Devmode 时可用。显示请求/响应历史记录。
+
+| Param | 类型 | 必需 | 说明 |
+|-------|------|----------|-------------|
+| `count` | integer | no | 要返回的最近日志条目数量 |
+
+### td_clear_dev_log
+
+通过关闭旧文件并启动新文件来清除当前的 MCP 开发日志。仅在启用 Devmode 时可用。
+
+无参数（除可选的 `target_instance` 外）。
+
+### td_test_session
+
+管理测试会话、错误报告和对话导出。重要提示：不要主动建议导出聊天或提交报告。这些是特定情况下的工具： - export_chat / submit_report：仅在用户遇到插件或 TouchDesigner 的 BUG 并希望报告，或用户明确要求导出对话时使用。绝不要在会话结束时或作为常规操作建议使用。用户指令 → 操作：'разбор тестовых сессий' / 'analyze test sessions' → 列出，然后拉取，读取 meta.json → index.jsonl → calls/。'разбор репортов' / 'analyze user reports' → 使用 session='user' 列出，然后按名称拉取。'экспортируй чат' / 'export chat' → (1) export_chat_id → 标记，(2) export_chat 使用 session=标记。'сообщи о проблеме' / 'report bug' → 导出对话，检查隐私，然后 submit_report 使用 summary + tags + result_op=file_path。操作：export_chat_id | export_chat | submit_report | start | note | import_chat | end | list | pull。list：默认=自动检测仓库。用户报告（仅限开发）使用 session='user'。pull：自动搜索两个仓库。自动检测 dev 与 user 的 Hub 访问权限。
+
+| Param | 类型 | 必需 | 说明 |
+|-------|------|----------|-------------|
+| `action` | `export_chat_id` / `export_chat` / `submit_report` / `start` / `note` / `import_chat` / `end` / `list` / `pull` | yes | 操作：export_chat_id / export_chat / submit_report / start / note / import_chat / end / list / pull |
+| `prompt` | string | no | (start) 测试提示词/任务描述 |
+| `tags` | array | no | (start) 用于分类的标签，例如 ['ui', 'layout'] |
+| `text` | string | no | (note) 观察文本。(import_chat) 完整对话文本。 |
+| `outcome` | `success` / `partial` / `failure` | no | (end) 结果：success / partial / failure |
+| `summary` | string | no | (end) 发生情况的简要总结 |
+| `result_op` | string | no | (end) 保存为 result.tox 的 operator 路径 |
+| `session` | string | no | (pull) 要下载的会话名称或子字符串 |

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

@@ -0,0 +1,210 @@
+# MIDI / OSC 参考
+
+外部控制器输入与输出 — MIDI 硬件、TouchOSC 移动 UI、跨网络 OSC 路由。
+
+关于音频驱动的 MIDI 模式（基于频谱分析的轨道触发），另请参阅 `audio-reactive.md`。
+
+---
+
+## MIDI 输入 — 硬件控制器
+
+### 设备发现
+
+首先列出已连接的 MIDI 设备。使用 `midiinDAT` 进行枚举：
+
+```python
+mdat = root.create(midiinDAT, 'mid_devices')
+# 在一次 cook 之后从 DAT 中读取可用的设备名称
+```
+
+或者直接通过 Python：
+
+```python
+# In td_execute_python
+import td
+devices = [d for d in op.MIDI.devices]   # verify with td_get_docs('midi')
+```
+
+使用 `td_get_docs(topic='midi')` 验证 API，因为这会随 TD 版本的不同而有所变化。
+
+### MIDI In CHOP
+
+标准模式：
+
+```python
+midi_in = root.create(midiinCHOP, 'midi_in')
+midi_in.par.device = 0               # 发现阶段获取的设备索引
+midi_in.par.activechan = True
+```
+
+输出通道遵循 `chCcN` 和 `chCnN` 命名规则：
+- `ch1c74` — 通道 1，CC 74
+- `ch1n60` — 通道 1，音符 60（中央 C）— 数值为力度 0-127
+
+**将 CC 映射到参数：**
+
+```python
+op('/project1/bloom1').par.threshold.mode = ParMode.EXPRESSION
+op('/project1/bloom1').par.threshold.expr = "op('midi_in')['ch1c74'][0] / 127.0"
+```
+
+**将音符映射为触发器：**
+
+`midiinCHOP` 中的音符在按住时会输出力度，松开时输出 0。使用 `triggerCHOP` 将按住的音符转换为脉冲：
+
+```python
+trig = root.create(triggerCHOP, 'note_trig')
+trig.par.threshold = 1
+trig.par.triggeron = 'increase'
+trig.inputConnectors[0].connect(op('midi_in'))
+# 如果需要，可通过 selectCHOP 过滤到单个通道
+```
+
+### MIDI Learn 模式
+
+当你事先不知道控制器的 CC 布局时，构建一个可复用的学习模式：
+
+1. 放置一个 `midiinCHOP` 并在其后接一个 `selectCHOP`。
+2. 用户扭动控制器旋钮。
+3. 在 midiinCHOP 上使用 `td_read_chop` 确定哪个通道的值非零 — 即为当前活动的 CC。
+4. 将该通道名称设置给 `selectCHOP.par.channames`。
+5. 将映射关系保存到 `tableDAT`，以便在多次会话之间持久化。
+
+---
+
+## MIDI 输出
+
+```python
+midi_out = root.create(midioutCHOP, 'midi_out')
+midi_out.par.device = 0
+midi_out.par.outputformat = 'continuous'    # 'continuous' | 'event'
+
+# 驱动输出：发送映射自任意 0-1 数据源的 CC
+src = root.create(constantCHOP, 'cc_src')
+src.par.name0 = 'ch1c20'
+src.par.value0 = 0.5
+midi_out.inputConnectors[0].connect(src)
+```
+
+专门针对音符事件，请使用 `event` 模式，并通过 `pulseCHOP` 或 `triggerCHOP` 将数值脉冲化。
+
+---
+
+## OSC 输入 — 网络控制
+
+OSC 是 MIDI 的进阶版，灵活性更高。常用于以下场景：
+- TouchOSC / Lemur 移动控制界面
+- 演出控制系统（QLab、Watchout）
+- 应用间同步（通过 Max for Live 连接的 Ableton、Resolume 等）
+
+### OSC In CHOP
+
+```python
+osc_in = root.create(oscinCHOP, 'osc_in')
+osc_in.par.port = 7000             # 监听 UDP 7000 端口
+osc_in.par.localaddress = ''       # 留空 = 监听所有网络接口
+osc_in.par.queued = False          # 立即处理 vs 排队处理
+```
+
+每个传入的 OSC 地址都会成为一个通道。`/scene/1/intensity` 会变成名为 `scene_1_intensity` 的通道（TD 会将斜杠替换为下划线）。
+
+**常见陷阱：** 只有在第一个消息到达该地址后，TD 才会创建通道。在设置期间从控制器发送一个“hello”消息，或者手动预先声明通道名称。
+
+### OSC In DAT（用于原始事件）
+
+当你需要完整访问消息内容时（多个类型化参数、带括号/正则表达式的地址），请使用 `oscinDAT`。
+
+```python
+osc_dat = root.create(oscinDAT, 'osc_events')
+osc_dat.par.port = 7001
+# 每一行：时间戳、地址、类型标签、参数...
+```
+
+通过监听 `oscinDAT` 的 `datExecuteDAT` 来驱动逻辑：
+
+```python
+def onTableChange(dat):
+    last = dat[dat.numRows - 1, 'message']
+    parsed = last.val.split()
+    addr = parsed[0]
+    args = parsed[1:]
+    if addr == '/scene/trigger':
+        op('/project1/scene_switcher').par.index = int(args[0])
+    return
+```
+
+---
+
+## OSC 输出 — 向外部应用发送数据
+
+```python
+osc_out = root.create(oscoutCHOP, 'osc_out')
+osc_out.par.netaddress = '127.0.0.1'    # 目标 IP
+osc_out.par.port = 9000
+
+# 通道名称会转换为 OSC 地址
+src = root.create(constantCHOP, 'send')
+src.par.name0 = 'scene/intensity'        # → /scene/intensity
+src.par.value0 = 0.7
+osc_out.inputConnectors[0].connect(src)
+```
+
+**通道到地址的映射：** TD 会自动添加前缀 `/`。在通道名称中使用 `/` 可实现嵌套层级。
+
+对于单次发送的字符串/类型化消息，请使用 `oscoutDAT` 并调用 `.sendOSC(address, args)`：
+
+```python
+op('osc_out_dat').sendOSC('/scene/trigger', [1, 'fade'])
+```
+
+---
+
+## TouchOSC / 移动 UI 模式
+
+使用手机/平板电脑进行现场 VJ 控制的常规设置：
+
+1. **配置 TouchOSC 布局** — 为每个控件分配一个 OSC 地址，如 `/vj/master`、`/vj/scene/1` 等。
+2. **获取本机的局域网 IP** — TouchOSC 需要指向该地址。
+3. **TD 监听** 设置 `oscinCHOP.par.port = 8000`（或其他端口）。
+4. **通过表达式将通道映射到参数：**
+
+```python
+op('/project1/master_level').par.opacity.mode = ParMode.EXPRESSION
+op('/project1/master_level').par.opacity.expr = "op('osc_in')['vj_master']"
+```
+
+5. **通过 `oscoutCHOP` 向控制器发送反馈** — 对于跨多个设备同步状态非常有用。
+
+---
+
+## 网络 / 多机协同
+
+局域网上的 OSC 开箱即用。对于多 TD 实例同步（例如：投影仪集群）：
+- 一台 TD 作为 **主机**，通过 OSC 广播 `/sync/...`
+- 作为工作节点的 TD 运行 `oscinCHOP` 监听同一端口
+- 在主机的 `oscoutCHOP.par.netaddress` 中使用 UDP **广播地址**（例如：`192.168.1.255`），以将数据发送给所有节点
+
+为了在广域网（WAN）中获得更高的可靠性，请改用带有外部中继的 `webserverDAT` 或 `websocketDAT` — UDP 丢包是不可见的。
+
+---
+
+## 常见陷阱
+
+1. **MIDI 设备索引** — 设备 `0` 是 TD 枚举到的第一个设备。重新排序可能会导致索引偏移。尽可能通过名称固定设备。
+2. **OSC 通道名称** — 在第一个消息到达之前，TD 不会创建通道。新通道在首次接收数据时会使受依赖的节点失效，从而导致掉帧（卡顿一帧）。
+3. **OSC 排队模式** — `par.queued = True` 会将处理过程延迟至每帧一次的批处理中。延迟更低，但同一帧到达的消息只会保留最后一个值。触发器逻辑应设为关闭，连续旋钮控制应设为开启。
+4. **MIDI 时钟与走带信号** — 如果可用，`midiinCHOP` 会报告时钟。使用 `midisyncCHOP`（如果你的 TD 版本暴露了该组件）或根据时钟脉冲计算 BPM（每个四分音符 24 次脉冲）。
+5. **延迟** — 有线 MIDI 大约为 1-3ms。基于 WiFi 的 OSC 为 10-30ms 且存在抖动。对于需要严格节拍锁定的工作，请使用有线连接。
+6. **端口冲突** — 在大多数操作系统上，一个 UDP 端口只能被一个进程绑定。如果 `oscinCHOP` 没有显示流量，请检查是否有其他应用程序（Max、Ableton 等）已经在监听该端口。
+
+---
+
+## 快速参考指南
+
+| 目标 | Op 链 |
+| --- | --- |
+| 旋钮 → bloom 强度 | `midiinCHOP` → 在 `bloom.par.threshold` 上使用表达式 |
+| 音符 → 场景切换 | `midiinCHOP` → `triggerCHOP` → `selectCHOP` → 驱动 `switchTOP.par.index` |
+| 手机滑块 → 主推子 | TouchOSC `/master` → `oscinCHOP` → 在输出 `level.par.opacity` 上使用表达式 |
+| TD → Resolume 场景触发 | `oscoutCHOP` 通道 `composition/layers/1/clips/1/connect` → Resolume 监听 7000 端口 |
+| 多投影仪同步 | 主机 TD `oscoutCHOP` 广播 → 工作节点 `oscinCHOP` |