effectcraft

EffectCraft

通过 EffectCraft 的结构化自动化接口，根据用户指定的项目和会话进行操作。

参考资料

构造桌面调用前，请阅读 references/control-protocol.md 的相关部分。这是一份于 2026-11-02 从上游控制协议下载的未修改快照。上游 MIT 许可证包含在 references/LICENSE-MIT 中。

搜索参考文档中的 Engine、UI state、Input、Locating things 或 Screenshots。相对文档链接以 https://github.com/storytold/effectcraft/blob/main/docs/ 为基准解析。

如需了解 MCP 工具架构、CLI 语法、脚本编写、跟踪、转描和导出工作流，请按需查阅上游 Agent 指南。如果行为有所不同，请从已安装的应用程序中发现架构；不要复用其他 ArtCraft 应用程序的参数，也不要假设与 After Effects 完全兼容。

选择会话

发现可用的 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 会在不加载内容的情况下启动，而 --demo 会加载演示内容。无头渲染默认使用 CPU；--gpu 会请求单独的 GPU 合成器，如果没有可用的适配器则会失败。
• 单次 CLI 调用会使用独立的无头引擎，且默认加载演示项目。请指定目标项目或使用 --empty，并使用 --save 或 --save-as 保存编辑。若 CLI 调用需要操作正在运行的应用，可使用 --bridge 9877。

请复用合适的会话。不要打开单独的无头项目并期待编辑内容出现在桌面应用中。如果可执行文件或连接不可用，请报告此情况；本技能不会安装 EffectCraft 或配置 MCP 服务。

发现命令和传输方式

桌面通道使用 127.0.0.1 上的原始 TCP，而非 HTTP 或 MCP JSON-RPC。发送 UTF-8 JSON 对象，其中包含字符串 method、可选的 params 和各不相同的请求 ID；每行发送一个对象。每个请求会收到一条回复，请根据 ID 匹配，并在执行依赖操作前检查 ok：

{"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 个连接。该端口没有身份验证，因此仅在需要时启用。发生超时或丢失变更操作的回复后，请先检查状态再重试；如果无法安全确认结果，请停止操作并报告不确定性。

使用 engine.commands，或引擎命令 command.list 和 command.describe，查看 ID、架构、启用状态和禁用原因。使用 engine.execute {command, params} 执行编辑。它会执行引擎命令而不打开对话框；ui.menu.invoke {id, params} 的行为类似菜单点击，若 params 为空，可能会打开对话框。

MCP 使用 list_commands、describe_command 和 execute_command {command, params}，以及 get_comp、get_layer 和 set_property 等辅助工具。请使用实际连接的工具架构；MCP 辅助工具与桌面方法的名称和参数大小写不同。要发现 CLI 命令，请使用 effectcraft-cli commands 或 effectcraft-cli exec --list --schemas --json。

检查和编辑合成

编辑前，先检查项目项、当前合成、所选内容、时间、脏状态和后台作业。桌面端查询可通过 engine.execute 调用 project.summary、comp.info、editor.state、app.capabilities 和 jobs.list；MCP 提供 get_state、get_project 和 get_comp。

通过查询获取实际的合成 ID 和图层 ID。也可按名称或 #n（从顶部开始，1 起始）定位图层，但重新排序后索引可能会改变。在支持的情况下，显式传入合成，并为作用于所选对象的命令有意设置选择内容。不要顺带解锁或编辑锁定的图层。

使用 layer.tree / MCP get_layer 读取属性树，并使用返回的路径或 UID。使用 prop.get / get_property 读取值；应用效果前，先查明效果 ID 和参数。返回的效果路径和形状路径会标识新建的实例，避免误改其他同类型效果。

MCP set_property 不带 time 时会设置静态值；带 time 时会创建关键帧；带 expression 时会设置表达式。时间单位为秒。关键帧时间使用图层时间；对于偏移或拉伸的图层，图层时间与合成时间不同。检查相关时间点的插值方式和值。表达式响应会区分 value 与 evaluated，并报告 expressionError；语法错误可能导致表达式已存储但处于禁用状态。

对于相关的多步编辑，在读取架构后，可考虑使用 MCP batch 或 engine.batch：步骤可以通过 $N.key 引用先前结果，批处理失败时会回滚。进行程序化构建时，run_script 支持应用程序的 After Effects 风格对象模型。检查脚本错误和任何 waiting 结果；ScriptUI 对话框需要交互后脚本才能完成。遵守应用程序的脚本文件和网络限制。

通过 engine/MCP 命令打开、替换、还原或关闭项目时，不会询问是否保存。执行这类操作前，如有需要，先检查脏状态并保存用户的工作。不要使用 app.quit {force: true} 跳过未保存内容的处理。

必要时操作 UI

使用 ui.inspect 和 ui.elements {prefix?} 查找绘制的控件和稳定 ID。布局更改后刷新元素。坐标和控件矩形使用窗口逻辑点；ui.viewer.locate 会将合成像素坐标转换为窗口点，ui.timeline.locate 会定位指定时间的图层。优先使用已查找的 ID，而非猜测坐标。ui.type 会作用于当前聚焦的字段。

对于有文档说明的查看器/时间轴状态，使用 ui.set；若要显示所需面板，使用 ui.panel.show。除非交互确有需要，否则避免使用 ui.focus 抢占焦点。UI 手势会在合成输入处理完毕后返回响应；执行依赖操作前，先检查其结果。

保存、渲染和验证

请将可编辑的 .ecproj 与导出的媒体文件分别保存。MCP 提供 save_project {path?}；请发现所选接口对应的引擎保存命令和 CLI 标志。验证保存结果和生成的文件，并在可用时检查脏状态。

使用 render.frame（桌面端）或 render_frame（MCP）检查代表性时间点的帧，包括动画边界和转场。桌面端帧不受查看器缩放比例或分辨率影响；max_side: 0 会提供完整尺寸。MCP 的 transparent: true 可在检查时保留 Alpha。使用 ui.screenshot 获取面板或 UI 证据。帧预览并非已完成的视频导出。

通过命令发现和功能查询，发现渲染队列／导出架构及支持的格式。明确设置目标合成、输出路径、时间范围、尺寸和 Alpha 要求。在支持的情况下，等待 renderQueue.render {wait: true} 完成；否则轮询相关任务／状态直至完成。同样，在保存或应用结果前检查跟踪或描摹任务的状态。打开项目后检查背景素材验证，并报告影响结果的缺失媒体。

验证导出的文件确实存在、可读取，且格式和时长符合要求；必要时检查代表性帧和 Alpha。检查 Lottie 或时间线互操作的警告，不要仅凭文件存在就认定保真度合格。报告实际的保存／导出路径，以及任何未完成的任务、缺失媒体或不支持的功能。