EffectCraft 是一款图形合成与动效制作应用，支持创建和编辑合成、图层、动画、蒙版及视觉效果。该技能说明如何通过其结构化自动化接口操作 EffectCraft，并强调应使用用户预期的项目与会话。
用途 该技能面向需要在 EffectCraft 中自动化完成合成与图层编辑、动画与关键帧设置、效果应用、UI 操作以及渲染导出等任务的场景。构造桌面调用前，应先阅读 references/control-protocol.md 的相关章节；该文档为 2026-10-08 从上游控制协议下载的未修改快照，上游 MIT 许可证见 references/LICENSE-MIT。文档中可搜索 Engine、UI state、Input、Locating things 或 Screenshots，相对文档链接基于 https://github.com/storytold/effectcraft/blob/main/docs/ 解析。
会话选择 应先发现可用的 EffectCraft 工具、已安装的可执行文件和现有会话，优先使用指向目标会话的 MCP 连接。对于正在运行的桌面项目，可使用其控制通道或 effectcraft-cli mcp --bridge 9877；需要启动桌面会话时可用 effectcraft --control 9877 或 EFFECTCRAFT_CONTROL_PORT=9877，并按环境调整可执行路径与端口。独立工作可使用 effectcraft-cli mcp --project /absolute/path/project.ecproj 打开 headless 会话；effectcraft-cli mcp 不带内容启动，--demo 加载演示内容。Headless 渲染默认使用 CPU，--gpu 会请求独立的 GPU 合成器，若无可用适配器则失败。一次性 CLI 调用使用独立的 headless 引擎并默认使用演示项目，应指定目标项目或 --empty，并用 --save 或 --save-as 持久化编辑；需要作用于实时应用时可加 --bridge 9877。应复用合适的会话，不要另开 headless 项目并期望编辑出现在桌面应用中；可执行文件或连接不可用时应报告缺失，该技能不负责安装 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。
检查与编辑合成 编辑前应检查项目项、活动合成、选择、时间、脏状态和后台任务。桌面查询包括 project.summary、comp.info、editor.state、app.capabilities 和 jobs.list（通过 engine.execute）；MCP 提供 get_state、get_project 和 get_comp。应从查询获取实际的合成和图层 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 的对象模型；应检查脚本错误与等待结果，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}，或轮询相关任务/状态直至完成；跟踪或 roto 任务在保存或应用结果前也应检查状态。打开项目后检查背景素材验证，并报告影响结果的缺失媒体。 应验证导出文件存在、可读，并符合请求的格式和时长；相关时检查代表性帧和 alpha。应审阅 Lottie 或时间线交换的警告，而不是把已存在的文件视为保真度的证明。应报告实际保存/导出路径，以及未完成任务、缺失媒体或不支持的功能。
限制 该技能不安装 EffectCraft，也不配置 MCP 服务器；桌面控制端口无认证，应仅在需要时开启；不要假设与其他 ArtCraft 应用参数通用或与 After Effects 完全兼容；帧预览不等同于最终视频导出；具体 MCP 工具模式、CLI 语法及导出格式应以已安装应用的实际发现为准。