EffectCraft — 代理操作
EffectCraft 是一個原生的 Rust 動態圖形 / VFX 合成器（After Effects 等級），其代理介面是內建的：每個動作都是一個帶有 ID 的命令。GUI、選單、CLI、控制通道和 MCP 伺服器都驅動同一個引擎。已針對 0.17.0 版本在 Windows 上進行驗證。
機器與環境路徑
| 平台 | 二進位檔 | CLI | 預設資料目錄 |
|---|---|---|---|
| Windows | C:\Program Files\EffectCraft\effectcraft.exe | C:\Program Files\EffectCraft\effectcraft-cli.exe | %LOCALAPPDATA%\EffectCraft（磁碟快取） |
| Linux | /usr/bin/effectcraft | /usr/bin/effectcraft-cli | ~/.local/share/effectcraft |
- 控制埠：
--control <port>或EFFECTCRAFT_CONTROL_PORT（無令牌——橋接器接受純環回連線，與 FilmCraft 不同） - 命令： 55 個命名空間中的 734 個（在全新的無頭環境中啟用了 439 個；其餘需要選取 / 啟用合成 / 工具模式）
- 特效： 註冊表中有 307 個（
list_effects）；149 種字型系列（list_fonts）
心理模型
- 專案（
.ecproj）包含項目：Composition、Folder、Solid、Footage。get_project會回傳項目樹、髒標記和啟用中的合成。一次只有一個合成是啟用中的；大多數命令作用於它。 - 合成為
{width, height, frameRate, duration, startTime, background, renderer: classic3D|advanced3D}。時間單位為秒（浮點數，非 tick——這裡沒有像 FilmCraft 那樣的 tick 數學）。 - 圖層為 Text、Shape、Solid、Null、Composition（預合成）、Adjustment、Light 或 Camera。圖層以 1 為頂層。透過
id、#n（堆疊索引）或name來定址圖層。 - 每個圖層都有一個屬性樹：
Transform（anchor, position, scale, rotation, opacity），加上effects、masks、文字或形狀contents。屬性路徑接受transform.position和Transform/Position——但裸position（無群組）會被拒絕。 - 動畫 = 屬性上的關鍵影格（
prop.addKey）或表達式（prop.setExpression，AE JavaScript）。prop.get {time}回傳插值、關鍵影格清單和animated標記。 - 參數經過嚴格驗證：未知的參數名稱會導致命令失敗，並附上可接受的鍵值清單；未知的命令 ID 也一樣。這與 FilmCraft 默默丟棄參數的行為相反——閱讀錯誤、修正呼叫、不要盲目重試。
- 透過讀回驗證（
get_state、get_project、get_comp、get_layer、get_property）或透過渲染驗證（render_frame——PNG 可以捕捉到任何讀回都無法顯示的錯誤位置、隱形的圖層和遺漏的特效）。
兩種連線模式
| 模式 | 啟動方式 | 用途 |
|---|---|---|
| 無頭模式 | effectcraft-cli mcp --demo（--project p.ecproj、--empty、--autosave） | 無視窗、批次建置、渲染、腳本 |
| 應用程式橋接模式 | effectcraft --control 50052 + effectcraft-cli mcp --bridge 50052 | 真實視窗：UI 狀態、螢幕截圖、點擊、按鍵、僅 GUI 命令 |
每個 CLI 呼叫都是獨立的工作階段。 在一個 run 中建立的狀態在進程退出時消失——使用 file.saveAs + --save-as 完成，或在單一的 render/run 呼叫中完成所有工作（建置 → 渲染）。
應使用者要求啟動 EffectCraft（「起動して」/「啟動 EffectCraft」）
- 檢查是否已在執行：
Get-Process effectcraft/pgrep effectcraft。 如果正在執行，測試埠：effectcraft-cli --bridge 50052 info。 如果正在執行但沒有控制埠，請要求使用者以--control重新啟動（否則未儲存的工作將會遺失）。 - 以
--control <port>（預設50052）啟動：- Windows——使用
scripts/launch.ps1讓視窗出現在可見的桌面上，而不是背景工作階段中：powershell -File scripts/launch.ps1 -Port 50052 - Linux：
./scripts/launch.sh 50052
- Windows——使用
- 驗證： 等待 1–3 秒，然後
effectcraft-cli --bridge 50052 info——它會印出版本、命令/特效計數和開啟的專案。
MCP 工具
無頭模式暴露 27 個工具；橋接模式增加了 9 個 UI 工具（ui_inspect、ui_elements、ui_click、ui_drag、ui_key、ui_set、ui_type、screenshot、control）加上用於 ScriptUI 對話方塊的 script_ui = 總共 36 個。
| 工具 | 用途 |
|---|---|
command_list / list_commands | 每個命令（--filter、--enabled） |
command_run / execute_command | 執行一個 {id, params}（可復原） |
command_batch / batch | 多個命令，一個復原步驟（batch） |
describe_command | 一個命令的結構描述 |
doc_inspect / get_project | 一次呼叫取得專案樹 + 啟用中合成 |
get_comp | 一個合成：設定、圖層、工作區域 |
get_layer | 一個圖層的完整屬性樹 |
get_property / set_property | 讀取 / 寫入一個屬性（設定鍵值時為動畫狀態） |
add_keyframe | 屬性的關鍵影格（開啟碼錶） |
add_effect / list_effects | 套用一個特效（一次呼叫 + 參數）/ 307 個特效的註冊表 |
list_fonts | 149 種文字圖層可用的字型系列 |
run_script | After Effects 風格的 ExtendScript（app.project、合成、圖層） |
render_frame / render_preview | 在 time 處渲染（啟用中合成的）PNG |
open_project / save_project | 開啟（path、demo:true、empty:true）/ 儲存（+另存新檔） |
undo / redo / history | 分支復原歷史記錄 |
get_state | 啟用中合成、目前時間、選取狀態、播放 |
script_ui | 驅動已開啟的 ScriptUI 對話方塊/面板腳本 |
資源：effectcraft://document 和 effectcraft://commands。
標準工作流程
- 探查。
get_state+get_project；無頭模式啟動時為空白，除非指定--demo/--project。橋接模式下先使用ui_inspect。 - 建置。
comp.new {name,width,height,frameRate,duration}→layer.newText/newShape/newSolid/newNull（內嵌樣式參數）→file.import {paths}用於素材 →layer.addItem風格的放置。 - 動畫。 每個關鍵影格使用
prop.addKey {layer,path,time,value}；keys.setEase、keys.interpolation、prop.setExpression。 - 樣式。
effect.apply {effect:"Gaussian Blur", layers:[id]}+effects/#1/...下的參數路徑；遮罩（mask.new）、文字動畫器、形狀漸層筆畫。 - 驗證。 在關鍵時間點使用
get_property；在那些時間點使用render_frame並檢視 PNG（位置、緩動和模糊都可見）。 - 渲染。
render --out file.mp4 --format h264（CLI），或renderQueue.add+renderQueue.render；用於 RGBA 的render-frame --transparent；用於範本工作的render --template t.ectemplate --values v.json。 - 儲存。
file.saveAs {path}（或 CLI--save-as）；重新讀取get_project——髒標記在儲存後清除。
尋找命令
command_list {filter:"mask"} 會比對 id、標籤和選單。從 shell：effectcraft-cli commands --filter mask，以及使用 describe_command/describe 來取得一個命令的結構描述。所有 734 個 id 及其參數文件都在 references/catalog/commands.md 中；經過驗證的逐步 JSON 在 references/recipes.md 中。
從這些開始：comp.new、comp.settings、comp.open、layer.newText、layer.newShape、layer.newSolid、layer.newNull、layer.select、layer.moveLater、layer.setTransform、layer.setText、prop.get、prop.set、prop.addKey、keys.setEase、keys.interpolation、prop.setExpression、effect.apply、mask.new、time.set、file.import、file.saveAs、renderQueue.add、renderQueue.render、app.quit。
耗時的陷阱
- 到處都是嚴格的驗證。 未知參數 →
invalid parameters … accepted: name, width, …帶有完整的鍵值清單；未知命令 ID →unknown command。錯誤本身就是文件——但一個有效參數帶有錯誤的值類型仍可能行為異常，所以請讀回狀態。 - 圖層時間 vs 合成時間。 寫入命令（
prop.addKey、keys.set、prop.set）預設使用圖層秒數作為time（timeBase:"layer"|"comp"可切換）；prop.get讀取time為合成秒數。當圖層從 0 開始時兩者一致；在layer.move之後則不然。錯誤的基準 = 關鍵影格會根據圖層起始時間而偏移。 - 許多命令需要選取。
prop.set、effect.apply、keys.easyEase在未選取任何東西時顯示enabled:false（無頭模式啟動時為空白）。請傳遞明確的layer/layers參數，或先使用layer.select。 comp.new會回傳{comp: id}並使其成為啟用中合成（已驗證：兩次comp.new呼叫後，文字圖層會落在第二個合成中）。使用comp.open {comp: id|name}切換，並透過get_state確認——在第一次comp.new之前，針對「啟用中合成」的命令和渲染會在全新的--empty專案上失敗，並顯示無啟用中合成。- 屬性路徑需要群組：
transform.position/Transform/Position有效，裸position會報錯 no property。使用props <comp> <layer> --flat或get_layer尋找確切路徑。 - 特效參數是特效下的路徑，例如
effects/#1/Blurriness（索引 = 套用順序）。effect.apply會回傳paths:["effects/#1"]——請使用它們。 - 每個 CLI 呼叫都是獨立的工作階段（見上文）。MCP 工作階段會保持狀態，直到伺服器退出。
render將相對的--out寫入程序工作目錄；請始終傳遞絕對路徑以獲得可預測的輸出。- 文字圖層在建立時接受完整的樣式設定（
layer.newText {size,fill,tracking,…}——數十個參數）。後續的重新樣式設定需透過文字來源/文件屬性進行；請檢查get_layer以取得確切路徑。 - 僅 GUI 的表面：
ui_*、screenshot、control、script_ui僅存在於橋接模式；window.*、view.*和help.*大多需要 GUI。 mcp --autosave在退出時保留未儲存的無頭編輯；沒有它則會遺失（對於一次性執行是可預期的，但對於實際工作則令人驚訝）。
參考地圖
| 檔案 | 內容 |
|---|---|
references/recipes.md | 經過驗證的 JSON：建置、文字、形狀、關鍵影格、緩動、表達式、特效、遮罩、渲染、匯出、GUI |
references/catalog/commands.md | 所有 734 個命令，按命名空間分組，附帶參數文件 |
references/mcp-and-control.md | 27+9 個工具、錯誤形式、資源、橋接模式詳細資訊 |
references/cli.md | effectcraft-cli 子命令、渲染格式、範本、基準測試 |
references/bugs-and-workarounds.md | 已重現的缺陷及最小重現方式 |
references/maintenance.md | 重新驗證版本、匯出命令、更新此技能 |
scripts/probe.sh / .ps1 | MCP 握手 + 工具計數 + 版本 |
scripts/dump-commands.sh / .ps1 | 重新產生命令目錄 |
scripts/launch.sh / .ps1 | 以控制埠啟動 GUI（可見桌面） |
scripts/smoke-test.sh / .ps1 | 建置 → 關鍵影格 → 渲染 → 驗證 |
社群：https://discord.gg/artcraft · https://getartcraft.com/apps/effectcraft。