TouchDesigner Atlas

English | Русский | 简体中文

td-atlas 为 Agent 提供三样东西：来自这台机器的准确算子和参数名称；可以在运行中的实例中操作，并支持一步撤销；以及无需打开项目就能读取已保存项目的方式。

功能

• **原子索引**是名称列表。分两轮从你自己的应用副本中读取所有算子和参数，写入一个 SQLite 文件。其中的值就是该副本报告的值。
• **桥接**让 Agent 能在 TouchDesigner 运行时修改你的项目。脚本会在其中用四个普通节点构建桥接：Web Server DAT、callbacks DAT、状态面板，以及一个在你保存时触发的 Execute DAT。你可以读取它、在 git 中查看其变更，并原位升级。
• TouchDesigner 不会报告的内容。errors涵盖 TouchDesigner 自身称为错误的情况，而td_health则涵盖它没有明确报告的问题。
• **调用日志**会把每次桥接调用写成一行，记录到磁盘上的文件中，并且日志会在会话结束后保留。
• **离线读取项目**可在关闭 TouchDesigner 的情况下检查、搜索和比较项目，并且不会改动原始文件。
• **保存时写入的网络文本**是桥接在每次保存时可放在.toe旁边的文本，让项目在 git 中拥有可比较差异的历史记录。

安装

开始前需要准备好三样东西。

• TouchDesigner，且已安装。索引根据你自己的应用副本构建，并保存该副本报告的值。无需下载任何内容。
• Python 3.11 或更高版本，与 TouchDesigner 安装在同一台计算机上。
• 支持 MCP 的 AI Agent。Agent 会调用这些工具。td-atlas 是针对 Claude Code 构建并进行测试的，其命令就是下文的 claude mcp add 行。任何 MCP 客户端都能访问相同的工具。

兼容性列出了支持的平台，以及连接器可以对项目做出的更改。

在 macOS 上，只需在终端中运行一行命令。安装程序是 POSIX shell 脚本，因此 Windows 用户请按下方步骤逐步操作。

curl -fsSL https://grigabyte.github.io/td-atlas/i | sh

如果该地址无法响应，也可以从代码库获取同一脚本：

curl -fsSL https://raw.githubusercontent.com/grigabyte/td-atlas/main/install.sh | sh

install.sh 会查找 Python、克隆代码库、在旁边创建虚拟环境、安装软件包、构建索引并暂存桥接。每条命令都会在运行前打印出来。

安装程序会询问两个问题：克隆到哪里，以及是否立即构建索引。第一个问题的默认答案是 ~/td-atlas。如果没有终端可供询问，两个问题都会采用默认值。

磁盘上最终会有两个目录：代码库检出目录（除非指定其他目录，否则为 ~/td-atlas），以及 ~/.td-atlas。除此之外，uv 或 pip 还会像安装任何软件包一样填充自己的软件包缓存。无需 sudo。不会触碰系统目录和 shell 启动文件。在已有检出目录上再次运行安装程序会更新该目录。

git clone https://github.com/grigabyte/td-atlas
cd td-atlas
uv venv                     # or: python3 -m venv .venv
uv pip install -e .         # or: .venv/bin/pip install -e .

.venv/bin/td-atlas build      # offline index, 13–16 s, no TouchDesigner process
.venv/bin/td-atlas install    # stage the bridge, print the bootstrap and MCP lines

从这里开始，命令都简写为 td-atlas。除非已激活虚拟环境，否则请通过路径调用。在代码库检出目录中，该路径是 .venv/bin/td-atlas。在其他位置则需要使用完整路径；默认目录对应的路径为 ~/td-atlas/.venv/bin/td-atlas。在 Windows 上则为 .venv\Scripts\td-atlas。系统 Python 无法看到这个软件包。

td-atlas install 会打印两项内容供你粘贴。通过 curl 运行的命令已经替你执行了安装，因此这两项内容已位于命令输出末尾；再次运行时会重新打印。首先，将以下内容粘贴到 TouchDesigner 的 textport（Dialogs → Textport and DATs）中，每个项目执行一次：

exec(open('/Users/you/.td-atlas/bootstrap.py').read())

textport 会以 [td-atlas] 行作出响应。最后一行会列出你的 TouchDesigner 版本和桥接所连接的项目。

[td-atlas] registered as /Users/you/.td-atlas/instances/9977.json
[td-atlas] bridge ready at /tdatlas on port 9977 (auth: token)
[td-atlas] TouchDesigner 2025.32460, project 'NewProject.1.toe'

其次，是一条供 MCP 客户端使用的 claude mcp add 命令。请参阅作为 MCP 服务。如需将同一条目写入 DIR/.mcp.json，或合并到已有文件中，请传入 --write-mcp-json DIR。

textport 响应后，完成索引构建。

td-atlas probe

这一步会添加只有运行中的实例才知道的信息。

最后，检查安装情况。如果你是从中途开始操作，请从这里开始。

td-atlas doctor

安装完成后，每条链接都会显示 ok，并输出一行收尾信息。

environment   : ok — running from /Users/you/td-atlas/.venv …
touchdesigner : ok — build 2025.32460 at /Applications/TouchDesigner.app …
index         : ok — 667 ops, 24251 params, 2060 articles …
index build   : ok — index and installation agree: 2025.32460
probe         : ok — runtime pass complete: 647 ops probed …
bridge        : ok — connected on port 9977 to 'NewProject.1.toe' …
mcp server    : ok — 'claude mcp add …' launches …

every link checked out.

统计数据取自你自己的 TouchDesigner 副本，因此你的结果会有所不同。每条未显示 ok 的链接都会附带修复方法；如果有链接故障，命令会以非零状态码退出。索引构建前会显示 index : FAIL … fix: td-atlas build，桥接暂存前会显示 bridge : warn … fix: td-atlas install。

作为 MCP 服务

运行 td-atlas install，并粘贴它打印出的 claude mcp add … 命令行。该命令行使用绝对路径指定解释器，因此无论当前工作目录是什么，以及是否激活了虚拟环境，都能正常工作。手动接入的配置如下：

claude mcp add td-atlas -- /path/to/python -m td_atlas.cli mcp

接下来，只需用日常语言说明你想做什么。以下是 Agent 会调用的工具：

共有 47 个工具，分为三组。9 个索引工具可离线使用，29 个实时工具可操作正在运行的实例，9 个项目文件工具可从磁盘读取和写入 .toe/.tox。每个工具的参数及用途都列在 plugin/skills/touchdesigner/references/tools.md 中，并且有测试确保该列表与代码一致。

td_build 和 td_set_params 会在发送前根据索引检查参数名称，因此常见错误会得到相应的更正：

- t: is a parameter group, not a settable parameter (try: tx, ty, tz)
- typ: no such parameter (try: type, ty)
- type: 'simplex5d' is not a valid menu entry
        (try: simplex4d, simplex3d, simplex2d, sparse, perlin4d)
- period: -3 is below the clamped minimum 0.0

文档

许可证

MIT，完整文本见 LICENSE。TouchDesigner 是 Derivative Inc. 的产品。 本项目与该公司无关，也不会再分发安装程序中的任何内容。 它只会读取你机器上已有的内容。