文章目錄
td-cli 是我開發的 TouchDesigner 命令列工具，可以搭配 Codex 或 Claude Code 直接操作 TD 專案。安裝好 CLI、Skill 與 TOX 後，只要描述需求就能請 AI 幫忙接節點、處理訊號或調整效果。
之前一直找不到用得順手的工具來和 Agent 協作，我就決定開發 td-cli，開發工作也完全交給 AI 處理。目前主要配合我自己的互動設計需求，先支援 Windows x86-64 與 TouchDesigner 2025.32050。
安裝 td-cli
平常就在使用 Codex 或 Claude Code 的話，可以把安裝交給 Agent 處理，也可以依照後面的步驟手動安裝。兩種方式都需要把 td-agent.tox 加入要操作的 TD 專案並確認連線。
交給 Agent 自動安裝
在 TD 所在的 Windows 電腦開啟 Codex 或 Claude Code，確認 Agent 能執行本機指令後貼上以下 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 位置與連線結果。
確認安裝與連線成功後，就可以跳到「開始使用」操作專案。
手動安裝
以下指令依 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 操作專案。搭配的 td-cli Skill 會要求 AI 先讀取節點與訊號，確認目前版本支援的指令，完成後再檢查結果並整理節點。
我們先建立一個藍色影像，確認 Agent 能操作正確的專案。請把下面的路徑換成已存有 td-agent.tox 的 .toe：
1請使用 td-cli Skill 開啟 C:\work\design.toe。
2若專案已經開啟就連線到現有實例，先確認專案路徑再修改。
3
4在 /project1 建立 Constant TOP 並接到 Null TOP，將顏色設成藍色。
5保留現有節點，替新增節點選擇沒有重複的名稱。
6完成後檢查參數與連線，告訴我輸出節點在哪裡。
Agent 找不到 TD 執行檔時，再補上實際安裝路徑。完成後回到 TD 應該能看到新增的 Constant TOP 與 Null TOP，後者的輸出會是藍色。確認這個結果後，就能把 Prompt 換成自己的設計需求。
完成設計可以直接在 TD 儲存，或請 AI「檢查結果後儲存目前專案」。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 看實際效果。反應太快、變化太小或需要增加平滑處理，都可以繼續請它調整。
總結
安裝 td-cli 並把 TOX 加入專案後，就能請 AI 協助 TouchDesigner 設計。對我來說最有幫助的，就是把花時間的計算與節點操作交給 AI，自己接著調整互動的體感。之後也會依這些需求持續升級工具。
