effectcraft
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseEffectCraft
EffectCraft
Operate EffectCraft through its structured automation interfaces, using the user's intended project and session.
通过EffectCraft的结构化自动化接口操作该应用,使用用户指定的项目与会话。
References
参考文档
Read the relevant sections of references/control-protocol.md before constructing desktop calls. This is an unmodified snapshot downloaded on 2026-10-08 from the upstream control protocol. The upstream MIT license is included in references/LICENSE-MIT.
Search the reference for , , , , or . Relative documentation links resolve against .
EngineUI stateInputLocating thingsScreenshotshttps://github.com/storytold/effectcraft/blob/main/docs/For MCP tool schemas, CLI syntax, scripting, tracking, rotoscoping, and export workflows, consult the upstream agent guide when needed. Discover schemas from the installed application if behavior differs; do not reuse parameters from other ArtCraft applications or assume complete After Effects compatibility.
构建桌面调用前,请阅读references/control-protocol.md的相关章节。这是2026年10月8日从上游控制协议下载的未修改快照。上游MIT许可证包含在references/LICENSE-MIT中。
在参考文档中搜索、、、或相关内容。相对文档链接基于解析。
EngineUI stateInputLocating thingsScreenshotshttps://github.com/storytold/effectcraft/blob/main/docs/如需了解MCP工具schema、CLI语法、脚本编写、tracking、rotoscoping以及导出工作流,请在需要时查阅上游Agent指南。如果行为存在差异,请从已安装的应用中发现schema;不要复用其他ArtCraft应用的参数,也不要假设完全兼容After Effects。
Choose the session
选择会话
Discover available EffectCraft tools, installed executables, and existing sessions. Prefer an available MCP connection targeting the intended session.
- For a running desktop project, use its control channel or . A needed desktop session can be started with
effectcraft-cli mcp --bridge 9877oreffectcraft --control 9877; adapt executable paths and port to the environment.EFFECTCRAFT_CONTROL_PORT=9877 - For independent work, opens a headless session;
effectcraft-cli mcp --project /absolute/path/project.ecprojstarts without content, whileeffectcraft-cli mcploads demonstration content. Headless rendering defaults to CPU;--demorequests a separate GPU compositor and fails if no adapter is usable.--gpu - One-shot CLI invocations use separate headless engines and default to the demo project. Supply the intended project or , and use
--emptyor--saveto persist edits. A CLI call supports--save-aswhen it should act on the live app instead.--bridge 9877
Reuse an appropriate session. Do not open a separate headless project expecting edits to appear in the desktop app. Report a missing executable or connection when unavailable; this skill does not install EffectCraft or configure MCP servers.
发现可用的EffectCraft工具、已安装的可执行文件以及现有会话。优先使用面向目标会话的可用MCP连接。
- 对于正在运行的桌面项目,使用其控制通道或。可通过
effectcraft-cli mcp --bridge 9877或effectcraft --control 9877启动所需的桌面会话;请根据环境调整可执行文件路径和端口。EFFECTCRAFT_CONTROL_PORT=9877 - 对于独立工作,会打开一个无头会话;
effectcraft-cli mcp --project /absolute/path/project.ecproj会在无内容的情况下启动,而effectcraft-cli mcp会加载演示内容。无头渲染默认使用CPU;--demo会请求独立的GPU合成器,若无可用适配器则会失败。--gpu - 一次性CLI调用使用独立的无头引擎,默认使用演示项目。请提供目标项目或参数,并使用
--empty或--save来保存编辑内容。如果CLI调用需要作用于正在运行的应用,可支持--save-as参数。--bridge 9877
请复用合适的会话。不要打开单独的无头项目并期望编辑内容会显示在桌面应用中。如果缺少可执行文件或无法连接,请报告;本技能不会安装EffectCraft或配置MCP服务器。
Discover commands and transport
发现命令与传输方式
The desktop channel is raw TCP on , not HTTP or MCP JSON-RPC. Send UTF-8 JSON objects with a string , optional , and distinct request IDs, one per newline. Read one reply per request, match IDs, and check before dependent actions:
127.0.0.1methodparamsokjson
{"id":1,"method":"ui.inspect","params":{}}
{"id":2,"method":"engine.execute","params":{"command":"project.summary"}}
{"id":3,"method":"engine.execute","params":{"command":"command.describe","params":{"command":"comp.new"}}}Connections are persistent and replies are ordered. Requests run between UI frames with a 60-second timeout. Invalid request lines, invalid UTF-8, or lines over 4 MiB close the connection; at most 16 connections are served. The port has no authentication, so enable it only while needed. After a timeout or lost mutation reply, inspect state before replaying; stop and report uncertainty if the result cannot be established safely.
Use , or engine commands and , for IDs, schemas, enablement, and disabled reasons. Execute edits with . It runs engine commands without opening dialogs; behaves like a menu click and may open a dialog when params are empty.
engine.commandscommand.listcommand.describeengine.execute {command, params}ui.menu.invoke {id, params}MCP uses , , and , plus helper tools such as , , and . Use the actual connected tool schemas; MCP helpers and desktop methods have different names and parameter casing. For CLI discovery, use or .
list_commandsdescribe_commandexecute_command {command, params}get_compget_layerset_propertyeffectcraft-cli commandseffectcraft-cli exec --list --schemas --json桌面通道是运行在上的原始TCP连接,而非HTTP或MCP JSON-RPC。发送包含字符串类型、可选以及唯一请求ID的UTF-8 JSON对象,每行一个请求。每个请求对应一个回复,匹配ID后,在执行依赖操作前检查字段:
127.0.0.1methodparamsokjson
{"id":1,"method":"ui.inspect","params":{}}
{"id":2,"method":"engine.execute","params":{"command":"project.summary"}}
{"id":3,"method":"engine.execute","params":{"command":"command.describe","params":{"command":"comp.new"}}}连接是持久化的,回复按顺序返回。请求在UI帧之间执行,超时时间为60秒。无效的请求行、无效的UTF-8或超过4 MiB的行会导致连接关闭;最多同时服务16个连接。该端口没有身份验证,因此仅在需要时启用。超时或丢失变更回复后,请先检查状态再重放操作;如果无法安全确认结果,请停止并报告不确定性。
使用,或引擎命令和,来获取ID、schema、启用状态和禁用原因。使用执行编辑。它会运行引擎命令而不打开对话框;的行为类似于菜单点击,当参数为空时可能会打开对话框。
engine.commandscommand.listcommand.describeengine.execute {command, params}ui.menu.invoke {id, params}MCP使用、和,以及辅助工具如、和。请使用实际连接的工具schema;MCP辅助工具和桌面方法具有不同的名称和参数大小写。对于CLI发现,请使用或。
list_commandsdescribe_commandexecute_command {command, params}get_compget_layerset_propertyeffectcraft-cli commandseffectcraft-cli exec --list --schemas --jsonInspect and edit compositions
查看与编辑合成
Inspect project items, active comp, selection, time, dirty state, and background jobs before editing. Desktop queries include , , , , and through ; MCP exposes , , and .
project.summarycomp.infoeditor.stateapp.capabilitiesjobs.listengine.executeget_stateget_projectget_compObtain actual comp and layer IDs from queries. Layers can also be addressed by name or (1-based from the top), but indices can change after reordering. Pass an explicit comp where supported, and set selection deliberately for commands acting on selected objects. Do not unlock or edit locked layers incidentally.
#nRead property trees with / MCP and use returned paths or UIDs. Read values with / ; discover effect IDs and parameters before applying them. Returned effect and shape paths identify the newly created instances, avoiding accidental edits to another effect of the same type.
layer.treeget_layerprop.getget_propertyMCP without sets a static value; with it creates a keyframe; with it sets an expression. Times are seconds. Keyframe times use layer time, which differs from comp time for offset or stretched layers. Inspect interpolation and values at relevant times. Expression replies distinguish from and report ; a syntax error can leave the expression stored but disabled.
set_propertytimetimeexpressionvalueevaluatedexpressionErrorFor related multi-step edits, consider MCP or after reading its schema: steps can reference prior results with , and failed batches roll back. For procedural construction, supports the application's After Effects-style object model. Inspect script errors and any result; ScriptUI dialogs require interaction before a script finishes. Preserve the application's scripting file/network restrictions.
batchengine.batch$N.keyrun_scriptwaitingOpening, replacing, reverting, or closing a project through engine/MCP commands does not ask to save. Inspect dirty state and save the user's work before such a transition when needed. Do not use to bypass unsaved work.
app.quit {force: true}在编辑前,请查看项目项、当前活动合成、选中项、时间、脏状态和后台任务。桌面查询包括通过调用的、、、和;MCP提供、和。
engine.executeproject.summarycomp.infoeditor.stateapp.capabilitiesjobs.listget_stateget_projectget_comp从查询中获取实际的合成和图层ID。图层也可以通过名称或(从顶部开始的1-based索引)来寻址,但索引在重新排序后会发生变化。在支持的地方请传入明确的合成,并为作用于选中对象的命令主动设置选区。不要意外解锁或编辑已锁定的图层。
#n使用 / MCP 读取属性树,并使用返回的路径或UID。使用 / 读取值;在应用效果前先发现效果ID和参数。返回的效果和形状路径可标识新创建的实例,避免意外编辑同类型的另一个效果。
layer.treeget_layerprop.getget_property不带参数的MCP 会设置静态值;带参数会创建关键帧;带参数会设置表达式。时间单位为秒。关键帧时间使用图层时间,对于偏移或拉伸的图层,这与合成时间不同。请查看相关时间点的插值和值。表达式回复会区分和,并报告;语法错误可能导致表达式被存储但被禁用。
timeset_propertytimeexpressionvalueevaluatedexpressionError对于相关的多步骤编辑,在阅读完schema后可考虑使用MCP 或:步骤可以通过引用先前的结果,失败的批量操作会回滚。对于程序化构建,支持应用的After Effects风格对象模型。请检查脚本错误和任何结果;ScriptUI对话框需要交互才能让脚本完成。请遵守应用的脚本文件/网络限制。
batchengine.batch$N.keyrun_scriptwaiting通过引擎/MCP命令打开、替换、还原或关闭项目时,不会提示保存。在进行此类切换前,如有需要请检查脏状态并保存用户的工作。不要使用来绕过未保存的工作提示。
app.quit {force: true}Operate the UI when needed
按需操作UI
Use and to discover drawn widgets and stable IDs. Refresh elements after layout changes. Coordinates and widget rectangles are logical window points; converts comp pixels to window points, and locates a layer at a time. Prefer discovered IDs over guessed coordinates. acts on the focused field.
ui.inspectui.elements {prefix?}ui.viewer.locateui.timeline.locateui.typeUse for documented viewer/timeline state or to expose the needed panel. Avoid stealing focus with unless interaction requires it. UI gestures reply after synthetic input is processed; inspect their result before dependent edits.
ui.setui.panel.showui.focus使用和来发现已绘制的控件和稳定ID。布局变化后请刷新控件列表。坐标和控件矩形是窗口逻辑坐标点;可将合成像素转换为窗口坐标点,可定位某一时间点的图层。优先使用发现的ID,而非猜测的坐标。作用于当前聚焦的输入框。
ui.inspectui.elements {prefix?}ui.viewer.locateui.timeline.locateui.type使用设置已记录的查看器/时间轴状态,或使用显示所需的面板。除非交互需要,否则避免使用抢占焦点。UI手势会在模拟输入处理完成后回复;在进行依赖编辑前请检查其结果。
ui.setui.panel.showui.focusSave, render, and verify
保存、渲染与验证
Save the editable separately from exported media. MCP provides ; discover the corresponding engine save command and CLI flags for the chosen interface. Verify the save result and resulting file, and check dirty state where available.
.ecprojsave_project {path?}Use (desktop) or (MCP) to inspect frames at representative times, including animation boundaries and transitions. Desktop frames are independent of viewer zoom/resolution; gives full size. MCP preserves alpha for inspection. Use for panel or UI evidence. A frame preview is not a finished video export.
render.framerender_framemax_side: 0transparent: trueui.screenshotDiscover render queue/export schemas and supported formats with command discovery and capabilities. Set the intended comp, output path, time range, dimensions, and alpha requirements explicitly. Wait for where supported, or poll the relevant job/status until completion; likewise inspect status for tracking or roto jobs before saving or applying results. Check background footage validation after opening a project and report missing media affecting the result.
renderQueue.render {wait: true}Verify exported files exist, are readable, and match the requested format and duration; inspect representative frames and alpha when relevant. Review warnings for Lottie or timeline interchange rather than treating an existing file as proof of fidelity. Report actual saved/exported paths and any unfinished jobs, missing media, or unsupported features.
将可编辑的文件与导出的媒体分开保存。MCP提供;请为所选接口查找对应的引擎保存命令和CLI标志。验证保存结果和生成的文件,并在可用时检查脏状态。
.ecprojsave_project {path?}使用(桌面端)或(MCP)查看代表性时间点的帧,包括动画边界和过渡效果。桌面端帧不受查看器缩放/分辨率影响;可获得完整尺寸。MCP的可保留Alpha通道以供查看。使用获取面板或UI的证据。帧预览不是最终的视频导出。
render.framerender_framemax_side: 0transparent: trueui.screenshot通过命令发现和能力查询,发现渲染队列/导出schema和支持的格式。明确设置目标合成、输出路径、时间范围、尺寸和Alpha要求。在支持的地方等待完成,或轮询相关任务/状态直至完成;同样,在保存或应用结果前,请检查跟踪或rotoscoping任务的状态。打开项目后请检查后台素材验证情况,并报告影响结果的缺失媒体文件。
renderQueue.render {wait: true}验证导出的文件存在、可读,且符合请求的格式和时长;在相关情况下检查代表性帧和Alpha通道。请查看Lottie或时间轴交换的警告,不要认为文件存在就代表保真度合格。报告实际保存/导出的路径,以及任何未完成的任务、缺失的媒体或不支持的功能。