文章目錄
td-cli 是我開發的 TouchDesigner 命令列工具，可以搭配 Codex 或 Claude Code 直接操作 TD 專案。安裝好 CLI、Skill 與 TOX 後，只要描述需求就能請 AI 幫忙接節點、處理訊號或調整效果。
目前先支援 Windows x86-64 與 TouchDesigner 2025.32050。這個工具主要是我自己做互動時使用，也完全交由 AI 全自動開發。
安裝 td-cli
有兩種安裝方式。平常就在使用 Agent 的話，可以直接把安裝交給它處理。想自己操作則參考後面的手動步驟。
交給 Agent 自動安裝
在 TD 所在的 Windows 電腦開啟 Codex 或 Claude Code，貼上以下 Prompt：
1請參考 https://github.com/tedliou/td-cli 的 README 與最新穩定版 Release，
2幫我安裝 td-cli 和你使用的 td-cli Skill。
3
4先確認這台電腦的 Windows 架構與 TouchDesigner 版本符合需求。
5依官方安裝方式完成安裝，確認 td 指令能執行，也能讀取已安裝的 Skill。
6已有安裝時先檢查版本，保留我自行修改的 Skill 與現有 TD 專案。
7
8請找出安裝包裡的 td-agent.tox，協助將它加入我要操作的專案。
9若你無法操作 TD 介面，請開啟 TOX 所在資料夾，告訴我要把哪個檔案拖到哪裡。
10等我放好後繼續檢查連線，直到 CLI 能列出正確的線上專案。
11確認成功後協助儲存包含 TOX 的 .toe，最後回報版本、Skill 位置與連線結果。
Agent 需要能執行這台 Windows 電腦上的指令。安裝完成後直接進入「開始使用」。
手動安裝
以下指令依 v0.7.1 的安裝說明 整理。先開啟 PowerShell 安裝最新穩定版：
1irm https://github.com/tedliou/td-cli/releases/latest/download/install.ps1 | iex
安裝後開啟新的 PowerShell 視窗，確認版本並安裝 Skill。使用 Codex 請輸入：
1td --version
2td-agent install-skill
使用 Claude Code 則將 Skill 安裝到它的個人技能目錄：
1td-agent install-skill --destination "$env:USERPROFILE\.claude\skills\td-cli"
接著用指定版本的 TD 開啟專案。在檔案總管的網址列貼上以下路徑：
1%LOCALAPPDATA%\Programs\touchdesigner-cli\current
把裡面的 td-agent.tox 拖進 TD 節點編輯區，回到 PowerShell 查詢連線：
1td --json instances list
指令會自動啟動需要的背景服務。等 TOX 的 Connection 頁面顯示 online 後再查詢一次，清單應列出這份專案。確認成功就儲存 .toe，下次開啟時便會一起載入 TOX。
若清單仍是空的，先確認專案已放入 TOX，再查看 Connection 頁面的錯誤訊息。CLI 與 TOX 必須使用相容版本，更新 CLI 不會替換專案裡原有的 TOX。
開始使用
安裝好後開啟新的 Agent 對話，直接請它使用 td-cli Skill 操作專案。下面用簡單的藍色影像確認整套流程，請把路徑換成自己的 .toe：
1請使用 td-cli Skill 開啟 C:\work\design.toe。
2若專案已經開啟就連線到現有實例，先確認專案路徑再修改。
3
4在 /project1 建立 Constant TOP 並接到 Null TOP，將顏色設成藍色。
5保留現有節點，替新增節點選擇沒有重複的名稱。
6完成後檢查參數與連線，告訴我輸出節點在哪裡。
這份專案要先存有 td-agent.tox。Agent 找不到 TD 執行檔時，再補上實際安裝路徑即可。
回到 TD 應該能看到新增的兩個節點，Null TOP 的輸出會是藍色。確認可以正常操作後，就能把 Prompt 換成自己的設計需求。
完成設計可以直接在 TD 儲存，或請 AI「檢查結果後儲存目前專案」。CLI 目前只能儲存已存在的 .toe，新專案先在 TD 手動存檔一次。
可以怎麼用
我自己會一些 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 工具來和 Agent 協作，就決定自己開發 td-cli。現在先配合自己的 Windows 環境與固定 TD 版本使用，之後會依互動設計的需求持續升級。
搭配的 td-cli Skill 會要求 AI 先讀取專案中的節點與訊號，確認目前版本支援哪些指令再開始操作。做完要檢查結果、整理節點，讓我能接著調整。
總結
td-cli 裝好後就能直接請 AI 協助 TouchDesigner 設計。可以先從現有專案的一小段訊號處理開始，確認結果後再繼續加效果。對我來說最有幫助的，就是把花時間的計算與節點操作交給 AI，自己接著調整互動的體感。
