td-cli 安裝與使用：讓 AI 幫忙操作 TouchDesigner

td-cli 是我開發的 TouchDesigner 命令列工具，可以搭配 Claude Code 直接操作 TD 專案。安裝好 CLI、Skill 與 Agent TOX 後，只要描述需求就能請 AI 幫忙接節點、處理訊號或調整效果。

之前一直找不到用得順手的工具來和 Agent 協作，我就決定開發 td-cli，開發工作也完全交給 AI 處理。目前主要配合我自己的互動設計需求，只支援 Windows x86-64 與 TouchDesigner 2025.32050。本文以 1.0.0 為準，用過舊版的話請直接看從舊版升級到 1.0.0。

td-cli 由三個部分組成：

安裝 td-cli

可以把安裝交給 Claude Code 處理，也可以依照後面的步驟手動安裝。兩種方式裝完後，都要再把 Agent TOX 拖進專案。

交給 Claude Code 安裝

在 TD 所在的 Windows 電腦開啟 Claude Code，確認它能執行本機指令後貼上以下 Prompt：

1請參考 https://github.com/tedliou/td-cli 的 README 與最新穩定版 Release，
2幫我安裝或升級 td-cli，並把 td-cli Skill 裝到你的個人 Skill 資料夾。
3
4先確認這台電腦的 Windows 架構與 TouchDesigner 版本符合需求。
5已有安裝時先檢查版本，覆蓋 Skill 前先告訴我差異。
6完成後確認 td 指令能執行、你讀得到新的 Skill，
7再告訴我 td-agent.tox 的位置。

Claude Code 回報 TOX 位置後，接著做「把 Agent 加進 TD 專案」。

手動安裝

以下指令依 v1.0.0 的安裝說明整理。先開啟 PowerShell 安裝最新穩定版，安裝程式會核對 Checksum 並把指令加入使用者的 PATH：

1irm https://github.com/tedliou/td-cli/releases/latest/download/install.ps1 | iex

安裝後開啟新的 PowerShell 視窗，確認版本，再把 Skill 裝到 Claude Code 的個人 Skill 資料夾：

1td --version
2td-agent install-skill --destination "$env:USERPROFILE\.claude\skills\td-cli"

目標資料夾已經有 Skill 時，要再加上 --replace 才會覆蓋。使用 Codex 的話省略 --destination，Skill 會裝到 ~/.codex/skills/td-cli。

把 Agent 加進 TD 專案

用 TouchDesigner 2025.32050 開啟要操作的專案，在檔案總管的網址列貼上以下路徑：

1%LOCALAPPDATA%\Programs\touchdesigner-cli\current

把裡面的 td-agent.tox 拖進 TD 節點編輯區。td_agent 的 Connection 頁會從 waiting_for_daemon、connecting 變成 online，連線失敗時會顯示驗證或登記錯誤。看到 online 後回到 PowerShell 確認連線，這個指令也會在需要時自動啟動 Daemon：

1td --json instances list

清單中的 status 為 online，project 會列出專案的檔名與資料夾：

1{"selector":"d146","status":"online","agent_version":"1.0.0","protocol_version":4,
2 "project":{"name":"design.toe","folder":"E:/td-cli-test"}}

確認成功就儲存 .toe，下次開啟專案時會一起載入 Agent。

用藍色影像確認 Agent 能操作專案

開啟新的 Claude Code 對話，請它使用 td-cli Skill 操作專案。td-cli Skill 會要求 AI 先讀取節點與參數，以已安裝版本的 --help 確認支援的指令，完成後再檢查結果。

我們先建立一個藍色影像，確認 Claude Code 能操作正確的專案。請把下面的路徑換成已放入 Agent 的 .toe：

1請使用 td-cli Skill 開啟 E:\td-cli-test\design.toe。
2若專案已經開啟就連線到現有實例，先確認專案路徑再修改。
3
4在 /project1 建立 Constant TOP 並接到 Null TOP，將顏色設成藍色。
5保留現有節點，替新增節點選擇沒有重複的名稱。
6完成後檢查參數與連線，告訴我輸出節點在哪裡。

這次測試送進 TD 的是下面這幾行指令，每一行都會回傳 succeeded 或錯誤碼，AI 依結果判斷下一步：

1td --json ops create /project1 constantTOP constant1 --node-x 300
2td --json ops create /project1 nullTOP null1 --node-x 500
3td --json ops connect /project1/constant1 /project1/null1
4td --json parameters set /project1/constant1 colorr --number 0
5td --json parameters set /project1/constant1 colorg --number 0.3
6td --json parameters set /project1/constant1 colorb --number 1

完成後回到 TD，可以看到新增的 Constant TOP 接到 Null TOP，兩個節點的預覽都是藍色。

確認這個結果後，就能把 Prompt 換成自己的設計需求。

設計完成可以直接在 TD 儲存，或請 AI「檢查結果後儲存目前專案」。AI 存檔時會用 project save 帶上磁碟上 .toe 的 SHA-256，檔案若在這段期間被另存過，雜湊值對不上就會拒絕覆蓋。CLI 只能儲存已存在的 .toe，新專案要先在 TD 手動存檔一次。

用 AI 處理互動訊號與效果

我自己會一些 TD，但沒有到專精。之前做腦波儀互動時，需要接收 OSC 訊號並處理訊息解析、數值換算和 Remapping，這些數學與邏輯運算人工做很花時間。用 td-cli 交給 AI 處理大概半小時就能完成，之後我再微調各訊號的體感。

假設已經有 OSC 接收節點，可以直接把要處理的訊號和用途告訴 AI：

1請使用 td-cli Skill 查看目前的 OSC 接收節點，列出實際收到的 Channel 與數值。
2我要挑一個訊號控制影像亮度。先和我確認 Channel 及輸入範圍，
3再將數值映射成 0 到 1，保留原始訊號與可手動調整的範圍參數。
4完成後確認亮度會隨訊號變化。

已經知道 Channel 名稱、單位與輸入範圍的話，直接寫進 Prompt 即可。

除了 OSC，我也用它做過影像變化、粒子效果、複雜調整與 Base COMP 介面設計。需求可以直接描述成「用這個訊號控制粒子速度，讓我能手動調整速度上下限」，或「將這段效果整理進 Base COMP，把強度和開關放到自訂參數頁」。要讓 AI 直接生成 TD 的即時影像，可以參考在 TouchDesigner 做即時 AI 影像的 StreamTurbo。

先讓 AI 完成功能，再回到 TD 看實際效果。反應太快、變化太小或需要增加平滑處理，都可以繼續請它調整。

從舊版升級到 1.0.0

1.0.0 把通訊協定換成 v4，td 也改成原生執行檔，指令延遲大幅縮短。我在同一台電腦用 TouchDesigner 2025.32050 的空專案比較 0.11.0 與 1.0.0，單一指令各執行 10 次取中位數：

用 commands execute 建立 256 個 Constant TOP 再設定 256 個參數，0.11.0 花了約 274 秒，1.0.0 只要 8.9 秒。1.0.0 另外新增 --frame-batch，讓連續指令在同一個 Frame 內執行，同樣的工作縮短到 1.7 秒。1.0.0 的 td 也不再展開 ~、$VAR 與萬用字元，腳本裡用到的路徑要先展開成完整路徑。

代價是 Daemon 只接受 1.0.0 的 Agent，而更新 CLI 不會替換 .toe 裡內嵌的 Agent。直接打開舊專案時，td_agent 的 Connection 會一直停在 connecting，td --json instances list 回傳空清單，每個舊專案都要各自升級一次。升級工具只接受白名單內的官方 Agent，1.0.0 的白名單包含 0.7.0 到 0.11.0。

開始前先把 TD 專案存檔，並關閉所有 TouchDesigner 視窗，升級工具偵測到 TD 還在執行時會拒絕動作。下面的指令有兩處要依自己的環境修改：專案檔名 design.toe，以及 TD 不在預設位置時的 --tools-dir。

1. 用安裝指令更新 CLI，再停掉舊版 Daemon，下一個 td 指令會啟動新版：

   1irm https://github.com/tedliou/td-cli/releases/latest/download/install.ps1 | iex
   2td-daemon stop
   

2. 在專案資料夾開啟 PowerShell，執行升級。--artifact 與 --manifest 指向剛安裝的新版檔案，--expected-sha256 是專案目前的雜湊值，檔案在執行前被改過就會停止：

   1$bundle = "$env:LOCALAPPDATA/Programs/touchdesigner-cli/current"
   2$project = (Resolve-Path ./design.toe).Path
   3$sha = (Get-FileHash $project -Algorithm SHA256).Hash.ToLower()
   4& "$bundle/td-agent.exe" upgrade-project $project --artifact "$bundle/td-agent.tox" --manifest "$bundle/manifest.json" --tools-dir "C:/Program Files/Derivative/TouchDesigner/bin" --expected-sha256 $sha --timeout 90
   

3. 確認輸出的 status 為 upgraded。我拿一個內嵌 0.7.1 Agent 的專案測試，約 2 秒完成，原檔另存成同資料夾的 .agent-backup-*，確認新專案正常後可以自行刪除：

   1{"agent_path":"/project1/td_agent","agent_version":"1.0.0",
   2 "backup":"E:\\td-cli-test\\design.toe.agent-backup-87a4406d80c34014b59a7fdd6cdbba40",
   3 "path":"E:\\td-cli-test\\design.toe","status":"upgraded"}
   

4. 重新開啟專案，可以直接雙擊 .toe，也可以讓 td 啟動 TD：

   1td --json project open E:/td-cli-test/design.toe --executable 'C:/Program Files/Derivative/TouchDesigner/bin/TouchDesigner.exe'
   

   專案載入後執行 td --json instances list，確認 agent_version 是 1.0.0 且 status 為 online。

5. 用「手動安裝」的 install-skill 指令加上 --replace 更新 Skill，讓 AI 讀到新版的指令說明。

問題排除

不再使用 td-cli 時，可以用以下指令移除執行檔，Daemon 的資料與 TD 專案都會保留：

1irm https://github.com/tedliou/td-cli/releases/latest/download/uninstall.ps1 | iex

總結

安裝 CLI 與 Skill，再把 td_agent 加進專案並確認 online，就能請 Claude Code 協助 TouchDesigner 設計。1.0.0 讀一個參數的完整往返從 1,954 ms 降到 33 ms，512 個連續指令從約 274 秒降到 1.7 秒，舊專案執行一次 upgrade-project 就能接上。對我來說最有幫助的，就是把花時間的計算與節點操作交給 AI，自己接著調整互動的體感。之後也會依這些需求持續升級工具。

Ted Liou

Unity 現役工程師，Unity、AI 技術開發經驗分享與諮詢。