Surehand MCP for Adobe After Effects

Surehand MCP 让你已经在用的 AI 应用在 Adobe® After Effects® 中工作，并向你展示它做了什么。 它面向无法接受“AI 说已经完成”的动态图形设计师、后期制作艺术家和技术总监。 每次编辑都只需一步即可撤销，并会附上精确的更改清单。结构性更改会附带像素级证明，确保画面没有变化。交付内容会根据你自己的规范进行检查，模板会通过最坏情况输入进行测试，而每个基于数据生成的版本都会逐行检查。经过验证，而非盲目信任。

• AI 应用： Claude（Desktop 和 Code）、ChatGPT（桌面应用和网页）、Codex、Cursor、VS Code（GitHub Copilot）、Windsurf / Devin Desktop、LM Studio，或任何 MCP 客户端。在 After Effects 中，Surehand 面板还可以通过你自己的登录账号使用 Codex、Claude Code 或 Antigravity 进行聊天。
• After Effects： 已逐个版本测试 macOS 和 Windows 上的 2025 和 2026 版本，支持任何语言。扩展可加载于 CC 2019（16.0）及更新版本；2025 之前的版本尽力支持。
• 安装： Mac 版已签名并公证的 .pkg，Windows 版已签名的 Setup.exe。无需管理员权限，也无需账户。免费且开源（MIT）。
• 网站和下载： conformlabs.co/get。

它不生成图像，也不附带预设或固定效果。它会按照你的规则处理你的项目，并测量结果。

AI app ──MCP──> surehand-ae server (Node, on your computer) ──localhost──> Surehand panel (CEP, inside After Effects) ──> ExtendScript

查看实际效果

四个简短演示，录制时使用 Surehand 1.4.1 和 After Effects 2026。长时间等待已剪掉并在屏幕上标出；没有加速播放。四个演示的播放列表，也可访问 conformlabs.co/get。

• 预合成修复：Claude 取消合成，保留所有表达式正常工作，并证明画面没有变化（16 帧，差异为零）。
• 交付前检查：根据客户的交付规范检查合成，发现 5 个问题，每个问题都附有时间码；随后修复其中一个问题并再次检查。
• 压力测试：一个包含长德语姓名、阿拉伯语、希伯来语和超大数字的字幕条模板；33 个变体中有 28 个出现问题，并确认原始合成未受影响。
• 渲染农场：将渲染拆分到 4 个 aerender 进程中，并验证了全部 250 帧。

你可以这样向它提问

用自己的话提出真实需求。AI 会选择工具；工具负责测量。

你问	工具
“发送 Endcard 前，检查它是否符合我们的播出规格。”	ae_preflight：根据交付规格检查合成和渲染文件，并提供带时间码的检查结果
“用很长的德语姓名和阿拉伯语对下三分之一进行压力测试。”	ae_stress_test：将最坏情况输入传入每个控件，测量每项结果，不改动你的合成
“取消 Logo_Lockup 的预合成，并证明没有任何变化。”	ae_precomp_surgery：先在临时副本上演练，仅在像素匹配时应用
“为什么渲染这么慢？只在画面保持完全一致的地方加速。”	ae_render_profile：生成时间线成本图，然后仅保留经验证完全一致的加速项
“将渲染拆分到 3 个进程中，并证明每一帧都已生成。”	ae_farm：分块、生成 aerender 脚本、在本地并行运行并检查完整性
“为 scores.csv 中的每一行生成一个 Score Card 版本，并在加入队列前逐一检查。”	ae_versions_from_data：一步撤销，每一行都会回读并测量
“导出文本，交给希伯来语和法语译者。译文回来后调整排版：字距最低到 -40，但字号不得低于 36 px。”	ae_localize：导出 CSV 或 XLIFF，并为每种语言生成一个经过检查的版本
“将 Promo 制作成 9:16 版本。Logo 固定在距顶部 80 px 处，标题放在标题安全区内。”	ae_reformat：按你的规则处理，并逐帧检查
“我继承了这个项目。渲染队列实际会用到哪些内容？哪些部分比较脆弱？”	ae_project_xray：只读说明，并标明精确位置
“v11 和 v12 之间有哪些变化？”	ae_project_history：快照和易读的差异对比

日常编辑也一样：合成、图层、精确到图表编辑器级别的关键帧、表达式、效果、文本、 蒙版、3D、音频、素材、基本图形和渲染设置；如果没有合适的工具，也可以使用任意 After Effects 脚本。请参阅完整工具列表。

安装

下载最新版本

你的设备	下载
Mac	Surehand-MCP-<version>.pkg（已签名并公证）
Windows	Surehand-MCP-Setup-<version>.exe（已签名）
仅使用 Claude Desktop	Surehand-MCP.mcpb
安装程序未涵盖的设备	Surehand-MCP-<version>.zip（Mac 和 Windows 脚本；打开 START HERE.txt）

无需安装其他内容：.pkg 和 Setup.exe 内含 Node.js 24，.mcpb 使用 Claude Desktop 内置的 Node.js，而 zip 安装程序会在缺少 Node.js 时下载并安装。

各 AI 应用的分步设置指南：Claude， ChatGPT 和 Codex，Cursor， VS Code，Windsurf， LM Studio。

Mac 和 Windows 安装程序

1. **Mac：**双击 Surehand-MCP-<version>.pkg 并按步骤操作。无需管理员密码：所有内容 都会安装到你自己的主文件夹中。 **Windows：**运行 Surehand-MCP-Setup-<version>.exe。安装仅对当前用户生效，无需管理员权限。
2. 重启一次 After Effects。
3. 重启安装期间已打开的 AI 应用。

这两个安装程序都会在你的电脑上安装独立的 Node.js 24、服务和 After Effects 扩展，连接检测到的 AI 应用，并为它们写入 Surehand 技能（请参阅安装程序）。

首次运行

桥接程序会随 After Effects 启动；无需打开任何内容。要查看它，请打开 Window > Extensions > Surehand MCP。绿点表示已连接。面板会显示最新调用、权限模式和 Pause AI。

然后向你的 AI 应用提出一个简单的请求：

*"检查 After Effects 是否已连接，然后创建一个 1080p 合成，其中包含一个动画标题，并显示第 1 帧。"

如果出现问题，面板中的 ☰ › Test the connection（或 surehand-ae selftest）会说明问题所在以及如何修复。

仅限 Claude Desktop（.mcpb）

双击 Surehand-MCP.mcpb，然后在 Claude Desktop 中点击 Install，再重启一次 After Effects。首次 启动时，服务会自动安装 After Effects 扩展。Claude Desktop 请使用 .mcpb 或安装程序之一，不要同时使用两者。

压缩包

与双击脚本执行相同的安装程序，适用于安装程序无法涵盖的配置：

Surehand-MCP/
  START HERE.txt
  1. Claude Desktop (easiest)/   Surehand-MCP.mcpb
  2. Mac/                        1. Install, 2. Test Installation, 3. Connect ChatGPT, 4. Uninstall (.command)
  3. Windows/                    1. Install, 2. Test Installation, 3. Connect ChatGPT, 4. Uninstall (.bat)
  Support files/                 run.sh, run.ps1, surehand-ae.mjs, this README

双击 2. Mac 或 3. Windows 中的 1. Install，然后重启一次 After Effects。打开 After Effects 后， 2. Test Installation 会检查所有内容。START HERE.txt（来自 installer/START HERE.txt）用通俗易懂的语言说明了相同步骤， 包括 macOS Gatekeeper 或 Windows SmartScreen 阻止文件时的处理方法。

安装程序

每个安装程序（.pkg、Setup.exe 或压缩包中的 1. Install）都会执行以下操作：

• 使用 .pkg / Setup.exe 安装到 ~/.surehand/node 的专用 Node.js 24；压缩包脚本会使用 PATH 中的 Node.js，或将专用 Node.js 22 LTS 下载到 ~/.surehand/node（并验证校验和）
• 将 MCP 服务复制到 ~/.surehand/ae/server/surehand-ae.mjs（单个自包含文件）
• 将 After Effects 扩展安装到用户 CEP 扩展文件夹。该扩展已签名， 因此无需启用未签名扩展（PlayerDebugMode）即可加载
• 创建包含随机访问令牌的 ~/.surehand/ae/config.json
• 在找到的 AI 应用中以 surehand-ae 为名称注册服务：Claude Desktop、Claude Code、ChatGPT desktop / Codex（~/.codex/config.toml，如果安装了 ChatGPT 或 Codex 应用则会创建）、 Cursor、VS Code（其用户级 mcp.json，供 GitHub Copilot 的 Agent 模式使用）、Windsurf / Devin Desktop （~/.config/devin/mcp_config.json、Windows 上的 %APPDATA%\devin，以及该文件夹存在时的 Windsurf ~/.codeium/windsurf/mcp_config.json）和 LM Studio（~/.lmstudio/mcp.json）。 修改配置文件前，会在同一目录创建带时间戳的备份（*.surehand-<time>.bak，保留最新的 三份）；最初的原始文件也会保留为 *.surehand.bak。如果 Claude Desktop 已打开，安装程序会提示重启它， 因为正在运行的 Claude Desktop 会覆盖其配置文件
• 为会读取技能文件的 AI 应用写入 Surehand 技能（参见 技能），并生成可上传到 Claude Desktop 聊天中的压缩包

服务每次启动时也会检查 After Effects 扩展，并在需要时安装或更新它。

要卸载：双击压缩包中的 4. Uninstall，或运行 surehand-ae uninstall（如果使用了 .mcpb，还需在 Claude Desktop > Settings > Extensions 中将其移除）。除非传入 --all，否则会保留检查点。

技能

四个 Agent 技能教 AI 如何更好地使用 Surehand：

• surehand-ae：基础知识。检查连接，编辑前先读取，每次编辑后确认变更报告，查看结果，绝不绕过拒绝，并了解实时遇到的 ExtendScript 陷阱。
• surehand-ae-delivery：依据你自己的交付规范进行预检、压力测试、逐行核对数据版本、本地化往返检查、渲染农场。
• surehand-ae-safe-restructure：结构调整和渲染提速，并提供像素级验证。
• surehand-ae-timing-layout：精确关键帧、缓动、测量对齐和重新格式化。

源文件位于此仓库的 skills/ 目录中。

• 安装程序会将它们写入 ~/.claude/skills/（Claude Code；Cursor 和 VS Code 也会读取）以及 ~/.agents/skills/（ChatGPT 桌面版 / Codex、Cursor、VS Code、Windsurf / Devin Desktop）；Windows 上则写入 %USERPROFILE%。只有当其中某个应用已安装在计算机上（或相应文件夹已存在）时，才会写入对应文件夹。 只会写入四个 surehand-ae* 文件夹；更新时替换，卸载时移除；绝不会动其他技能。
• **对于 Claude Desktop 聊天：**在 Customize › Skills › Upload a skill 中上传技能（文件位于 ~/.surehand/ae/skills，每个技能一个 zip）。claude.ai 也使用相同的 zip。
• surehand-ae skills [--json] 会显示技能的安装位置；surehand-ae skills install / uninstall 会写入或移除技能。

Claude Code 插件

在 Claude Code 中，你也可以将 Surehand 安装为插件（包含服务和四个技能，来自最新版本；需要将 Node.js 添加到 PATH）：

/plugin install surehand-ae --marketplace ConformLabs/surehand-mcp

服务首次启动时会安装 After Effects 扩展；之后请重启 After Effects。

其他 MCP 客户端

让它们连接到已安装的服务（stdio）：

{
  "mcpServers": {
    "surehand-ae": { "command": "/path/to/node", "args": ["/Users/<you>/.surehand/ae/server/surehand-ae.mjs"] }
  }
}

面板中的 ☰ › Connect an AI app 会显示已连接的应用，并连接其他应用。

对于会自行安装 MCP 服务的 AI Agent（例如 Cline），llms-install.md 中提供了具体步骤：下载、校验和、安装、MCP 设置。

ChatGPT

**ChatGPT 桌面应用（Mac 和 Windows）：无需隧道。**它会自行运行本地 MCP 服务，并读取与 Codex 相同的 ~/.codex/config.toml，该文件由安装程序填充。安装后重启 ChatGPT；surehand-ae 会显示在 Settings > Plugins > Servers 下（将其开启）。手动添加方法：Add > MCP server > STDIO，命令 = 安装程序打印的 Node 路径，参数 = ~/.surehand/ae/server/surehand-ae.mjs。

网页版 ChatGPT（chatgpt.com） 只能通过公共 HTTPS 访问 MCP 服务，因此服务会以 HTTP 模式运行在临时隧道后方。面板中的 ☰ › ChatGPT on the web 页面会在后台运行服务（也可以为你下载 Cloudflare 的 cloudflared）；详见 wiki 页面。 手动操作：

1. 安装一次隧道工具：cloudflared（无需账户：macOS 上运行 brew install cloudflared，Windows 上运行 winget install --id Cloudflare.cloudflared）或 ngrok。
2. 双击 zip 的 2. Mac 或 3. Windows 文件夹中的 3. Connect ChatGPT（或运行 surehand-ae chatgpt）。 它会打印一个类似 https://xxxx.trycloudflare.com/mcp/<token> 的 URL。
3. 在 ChatGPT 中：开启 Settings > Apps & Connectors > Advanced settings > Developer mode，然后创建连接器，粘贴 URL，选择 No authentication（令牌位于 URL 中），并保存。
4. 在聊天中，从工具菜单启用连接器。使用期间请保持隧道运行。

URL 中包含你的秘密令牌：只要隧道处于运行状态，任何拥有该令牌的人都可以在你的计算机上运行脚本。快速隧道的 URL 每次启动都会变化，因此每次都要更新连接器 URL（或设置一个命名的 Cloudflare 隧道）。要轮换令牌，请从 ~/.surehand/ae/config.json 中删除 token，然后重新运行安装程序，并重启 After Effects。

安全模型

Surehand 的设计旨在让你始终掌控项目，并能核实 AI 声称已完成的操作。

权限、暂停 AI 和撤销

权限。 Surehand 面板顶部的模式选择器 Full / Ask / Read-only（或 ~/.surehand/ae/config.json 中的 "permissions"）会立即应用于下一个请求，无需重启：

模式	执行方式
Full（默认）	执行所有操作。你的 AI 应用仍可能在每次调用工具前征求你的同意。
Ask	每项编辑和脚本都会在 Surehand 面板中等待，显示确切的代码或参数，直到你点击 Allow 或 Deny。关闭面板时，会改为显示审批弹窗。读取操作不受限制。
Read-only	拒绝会编辑内容的工具。脚本仍会运行（以读取信息），但如果脚本更改了项目，会立即撤销更改，并告知 AI 它尝试进行了哪些更改。对于会触及撤销历史记录（executeCommand、beginUndoGroup、endUndoGroup、purge）或执行不可撤销操作（打开、关闭或保存项目、newProject、quit、渲染、scheduleTask、保存首选项）的脚本，会在运行前拒绝。这是文本检查（会忽略注释并解码转义字符；字符串内或其他对象上的同名内容也会被计入）：运行时组装的调用可以绕过检查，但之后最多只会撤销一次，并通过临时撤销标记进行检查；如果项目没有恢复原状，就会报告。

暂停 AI。 在面板中点击一次，即可拒绝所有 AI 调用，直到你恢复使用。

撤销。 每次工具调用都是一个撤销步骤，ae_undo 会撤销该操作并报告撤销了什么。默认情况下，ae_batch 会将多个步骤作为一个撤销步骤执行，并确保要么全部完成，要么全部不做。面板的活动动态中，最近一次更改旁会提供 Undo，但只有在此之后项目未发生任何更改时才会显示。After Effects 本身可能会将少数操作拆分为多个撤销步骤（已知包括合成副本、图层副本和源替换）；可能出现这种情况时，结果会改为提供准确的恢复方式（检查点，或恰好移除所创建副本的命令）。请参阅限制。

检查点。 ae_checkpoint 会保存带时间戳的项目副本，并将其恢复为原文件旁的新文件；原文件永远不会被覆盖。进行重大更改的工具（预合成手术式编辑、渲染优化、版本处理、重新格式化）可以先保存检查点。面板会在 ☰ › Checkpoints 下列出这些检查点。

绝不会静默替换现有文件。 对于“另存为”、帧和联系表输出路径、帧导出、交接包、渲染农场计划和渲染农场渲染，如果文件已存在，操作都会被拒绝；只有确实需要替换文件时，AI 才会传入 overwrite: true。

可以单独关闭脚本中的 Shell 命令（system.callSystem）（☰ › Shell commands in scripts）。

AI 能做和不能做的事

• 它能做 After Effects 脚本能做的任何事：ae_run_script 会在 After Effects 中运行 JavaScript（现代语法会转换为 ExtendScript），现成工具则涵盖常见操作，并内置检查。
• 它不能批准自己的请求、绕过 Pause AI，也不能按下面板上的按钮。批准、Pause AI 和面板自身的操作都需要一个密钥；桥接程序会将其保存在内存中，并仅通过 After Effects 的扩展事件交给 Surehand 面板和批准弹窗，绝不会通过网络或文件传递。新请求在屏幕上出现的第一秒内无法得到响应，按 Enter 也绝不会批准。
• 它能看到自己请求查看的内容：工具结果以及它渲染的帧。你的项目文件会留在你的电脑上；AI 应用发送给其服务提供商的内容（你的消息、工具结果、渲染帧）受该服务提供商的条款约束。
• 权限是防止出错的护栏，不是沙箱。脚本仍然可以读取和写入文件。以你的用户帐户身份拥有完整 shell 访问权限的 AI 应用，可以读取和更改 Surehand 能访问的一切，包括 config.json。

活动日志。 每次工具调用都会记录到 ~/.surehand/ae/activity.jsonl，包含时间、AI 应用、工具、参数（包括完整脚本代码）、耗时和结果。面板会显示最近的调用，☰ › 活动历史会列出所有调用（点击某一项可查看更改内容），其中的打开日志文件可打开该文件，surehand-ae activity 则会打印日志。

安全性

• 桥接程序仅监听 127.0.0.1，并要求提供 ~/.surehand/ae/config.json 中的令牌（文件权限为 600）；来自网页（带有 Origin 标头）的请求会被拒绝。
• ae_run_script 能做 After Effects 脚本能做的任何事，包括读取和写入文件，以及通过 system.callSystem 运行 shell 命令。只连接你信任的 AI 应用，并且只在使用 ChatGPT 隧道时保持其运行。
• 令牌可以防范：这台电脑上的其他用户，以及无法读取你文件的程序。令牌无法防范：以你的用户帐户身份运行、且可以访问你文件的程序。
• After Effects 中的聊天不会存储或处理 API 密钥或登录信息：AI Agent 使用自己的登录信息运行。
• 只有在能够读取 AI 应用的设置文件时，才会修改这些文件（如果文件中有错误，则会保持原样并报告）；修改前会先创建带时间戳的备份（保留最新的三个），并以原子方式写入。
• surehand-ae diagnostics 和面板中的复制诊断信息不包含任何秘密信息。

自测

surehand-ae selftest（或2. 测试安装，或面板中的测试连接）会检查整个链路的每个环节：配置和令牌、扩展及其签名、AI 应用的设置、After Effects 中的桥接程序、ExtendScript、脚本偏好设置、一项小型无破坏性测试任务（包含文本、关键帧和效果的临时合成）以及帧预览。检查失败时会说明如何修复。

surehand-ae selftest --full 会针对临时合成运行每个主要工具（超过 60 个步骤；之后会移除临时合成。如果打开的项目没有未保存的更改，Save As 和检查点还原检查会短暂切换到临时项目，然后重新打开原项目），列出你的 After Effects 版本具备哪些脚本功能，并将报告保存到 ~/.surehand/ae/compat/。在 macOS 上的 After Effects 2025 (25.6) 和 2026 (26.5)，以及 Windows 11 上的 2026 中，所有步骤均通过；2025 和 2026 同时运行时也通过。面板、权限、批准和后台渲染已在 macOS 和 Windows 上通过验证。欢迎分享其他版本的报告。

按任务分类的功能

检查并交付

交付前检查（ae_preflight）会根据交付规范检查合成，以及可选的渲染文件：这是一份小型 JSON 文件，其中包含客户或广播机构文档中的数值。没有内置的规范。检查内容包括合成 设置、缺失项、每一帧安全区域内的文本、字高和阅读速度，以及文件中的： 编解码器、电平、响度、黑帧和冻结帧，以及闪光预检。无法运行的检查会使判定结果变为 INCOMPLETE，而不是 PASS。压力测试（ae_stress_test）会将极端输入（较长的德语和芬兰语 字符串、希伯来语和阿拉伯语、CJK、表情符号、超大和负数）输入模板公开的每个控件，并在 临时副本上测量每项结果；它还会列出在其他 After Effects 语言版本中会出错的表达式。 ae_project_health 会列出缺失的素材、字体和效果、表达式错误及未使用项。 详情：交付前检查、交付前检查：渲染文件、压力测试。

安全地重构

每次编辑都会返回由 After Effects 自身计算的更改报告。ae_prove_identical 会渲染参考 帧，执行编辑后再次渲染：结果为完全相同、在容差范围内相同或存在差异 （附带差异图像）。ae_precomp_surgery 会取消预合成或深度复制，并重写每个表达式引用， 在临时副本上预演更改，仅在像素匹配时才应用；无法精确复现的操作会被拒绝，并说明原因。 ae_replace_in_expressions 会在整个项目中查找并替换，并支持试运行。 详情：更改报告、已验证的编辑、预合成操作。

时间与布局

关键帧表（ae_get_keyframes、ae_set_keyframe_table）会按帧或秒读取和写入关键帧，并保留 After Effects 存储的精确速度和影响度。ae_copy_ease 会将缓动复制到其他关键帧，ae_audit_easing 会根据项目中最常用的曲线检查运动，而 ae_retime_keyframes 会按整帧缩放、偏移、错开或匹配时间。ae_align_layers 会根据测量出的屏幕显示边界（而非锚点）对齐和分布图层，并报告任何残余偏差。ae_get_layer_bounds、ae_sample_pixels、ae_render_frame 和 ae_render_contact_sheet 可让 AI 测量并查看结果。

版本、本地化与重新排版

ae_versions_from_data 会在一个撤销步骤中，将 CSV 或 JSON 文件转换为模板合成的多个版本，然后逐行读取其渲染结果：文本、数字格式、颜色规则、溢出、安全区域，以及根据你的映射规则确定的条形尺寸。ae_localize 会连同上下文一起将文本导出为 CSV 或 XLIFF，并将译文导入为每种语言一个版本；它只会采用你允许的调整来适配，并能处理从右向左的文字。ae_reformat 会根据你的规则（覆盖方式、安全区域、固定点、缩放限制）制作 9:16、1:1、4:5 或任意尺寸的版本，并逐帧检查结果。无法满足规则时，报告会说明 FAIL 及原因；它不会替你做决定。 详情：根据数据生成版本、本地化、重新排版。

渲染与渲染农场

ae_render_profile 会显示整个时间线中渲染时间的分布，然后逐项应用选定的加速方式，只保留经验证完全相同的方式，并报告节省的时间。ae_handoff_package 会为其他人收集项目，并附上所需内容清单（字体、插件、颜色设置），还可验证打包后的渲染结果是否相同。ae_farm 会列出节点渲染所需内容并据此检查节点，将渲染拆分为多个区块，交给本地进程或其他机器处理，在这里并行运行，并验证这些区块能否合并为完整结果。ae_render_background 会在独立进程中运行 aerender，同时让 After Effects 保持可用。 详情：渲染配置、交接包、渲染农场。

了解项目

ae_project_xray 可在不更改项目的情况下，解释继承的项目：渲染队列会渲染什么、每个表达式依赖什么以及哪些链接容易出问题、缺少什么、素材规格，以及项目为何如此庞大。 ae_project_history 会为项目创建快照，并将任意两个版本或检查点的差异整理成易读的更改列表。 ae_get_comp_map 会绘制嵌套预合成、父子关系、遮罩和表达式链接的关系图。 详情：项目 X 射线、项目历史记录。

在 After Effects 中聊天

Surehand 面板中的 ☰ › 与 AI 应用聊天 可运行 Codex、Claude Code 或 Antigravity，使用你自己的登录账号和订阅，且只能使用 Surehand 的工具。相同的模式、审批、Pause AI 和活动日志同样适用。 在支持交互式视图的 AI 应用（例如 Claude Desktop、ChatGPT、VS Code 和 Cursor）中，预检、X 射线、压力测试、证明和历史差异会以聊天内视图呈现：时间线上的发现、帧，以及前后对比。其他应用则会以文本形式提供相同结果。 详情：与 AI 应用聊天、聊天内视图。

参考

所有工具

Surehand 提供多达 114 种现成工具，此外还有可用于其他任务的 ae_run_script。

运行任意操作：

工具
ae_run_script	在 After Effects 中运行 JavaScript；使用 return 返回一个值，即可将其作为 JSON 获取。支持现代语法（let/const、箭头函数、模板字符串、解构、类、?.、??、for...of）和常用内置功能（map、filter、Object.keys、JSON 等）：代码会通过 Babel 转换，以适配 AE 的 ES3 引擎，并保留行号。发生错误时，会返回出错行、附近的代码和提示。log() 的输出也会返回。每次调用对应一个撤销步骤。
ae_run_script_file	使用参数运行磁盘中的 .jsx / .jsxbin 文件。
ae_get_scripting_guide	为模型提供的 ExtendScript 速查表（也是 MCP 资源 aemcp://docs/extendscript）。

按领域分类：

• 工作流： ae_batch（一次调用中执行多个工具步骤或脚本，只需一个撤销步骤，并生成一份变更报告；默认原子执行：如果某个步骤失败，则撤销所有操作）、ae_checkpoint（保存项目的带时间戳副本、列出副本、在原文件旁恢复为新文件；绝不覆盖原文件；每个检查点还会保存一份历史快照）、ae_list_scripts（列出你的脚本：AE 的 Scripts 文件夹、ScriptUI Panels，以及 ~/.surehand/ae/config.json 中 "scriptFolders" 列出的文件夹，并附带说明）+ ae_run_script_file、ae_tools 和 ae_call（按需调用任意工具，参见工具配置）
• 验证： ae_prove_identical（已验证的编辑）、ae_precomp_surgery（预合成手术）、ae_project_history（项目历史）
• 检查与交付： ae_preflight（预检）、ae_stress_test（压力测试）、ae_project_health（缺失的素材／字体／效果、表达式错误、未使用的素材、空合成／文件夹、重复的合成名称）
• 版本： ae_versions_from_data（根据数据生成版本）、ae_localize（本地化）、ae_reformat（重新排版）
• 理解项目： ae_project_xray（项目透视）、ae_get_comp_map（嵌套预合成、父子关系、轨道遮罩、表达式引用）
• 查看结果： ae_render_frame（将单帧渲染为图像；选项：放大查看某个区域、仅渲染部分图层、在棋盘格或纯色背景上显示透明度、与另一时间点或合成生成差异图像）、ae_render_contact_sheet（将不同时间点的帧排列成网格，并标注时间和帧编号，以便评估运动和缓动）。临时合成会一直保留到 After Effects 写入图像，然后将其移除，并手动恢复为渲染而切换的所有设置；随后将项目与渲染前的状态进行比较。它们绝不会使用“编辑 > 撤销”（否则可能撤销你自己的上一步操作）；After Effects 可能会显示一个“Surehand MCP preview”步骤，该步骤仅用于还原预览自身所做的更改。在 32 bpc 项目或启用了“Blend Colors Using 1.0 Gamma”的项目中，帧会以 16 bpc 渲染且不启用该选项，以便颜色与查看器中的显示一致（After Effects 渲染这类帧时会使画面过暗）；之后会恢复项目设置。ae_export_frames 的处理方式相同。ae_prove_identical 始终使用项目自身的设置进行渲染，因此捕获图像与比较图像一致。
• 测量： ae_get_layer_bounds（经过变换、父子关系、3D 和摄像机处理后的精确屏幕边界框；检查是否位于画面内以及是否处于动作／标题安全区）、ae_sample_pixels（渲染结果中指定点的 RGBA／十六进制值）
• 状态与应用： ae_status、ae_system_info、ae_execute_menu_command、ae_undo、ae_redo、ae_purge、ae_get_fonts、ae_reload_helpers
• 项目： ae_get_project_info、ae_list_items、ae_get_item_info、ae_import_files、ae_create_folder、ae_move_items、ae_rename_item、ae_remove_items、ae_replace_footage、ae_save_project、ae_open_project、ae_new_project
• 合成： ae_list_comps、ae_get_comp_info、ae_create_comp、ae_set_comp_settings、ae_duplicate_comp、ae_open_comp、ae_precompose、ae_add_comp_marker
• 图层： ae_get_layer_info、ae_add_layer（纯色、文本、形状、空对象、调整图层、摄像机、灯光、素材／合成）、ae_set_layer_attributes（开关、时间、父级、混合模式、轨道遮罩、顺序等）、ae_delete_layers、ae_duplicate_layer、ae_split_layer、ae_get_selection、ae_select_layers、ae_set_text
• 属性与动画： ae_get_properties、ae_find_properties（按名称／匹配名称搜索所有图层，或列出已设动画／包含表达式的属性）、ae_set_property、ae_set_keyframes（插值 + 缓动）、ae_remove_keyframes、ae_set_expression、ae_get_expressions
• 表达式： ae_check_expression（试用表达式并查看错误和值，不保留表达式）、ae_replace_in_expressions（在整个项目中查找并替换，支持试运行，并检查更改后的错误）
• 关键帧（图表编辑器级别）： ae_edit_keyframes（数值、时间移动、入／出插值、每个维度的速度 + 影响、连续／自动贝塞尔、空间切线、游离关键帧、关键帧颜色标签、删除）、ae_copy_keyframes（在属性／图层／合成之间复制，可指定时间范围和偏移量）、ae_set_time_remap（设置关键帧或冻结帧）。关键帧工具既接受整帧参数（frame、moveToFrame、frames、offsetFrames），也接受秒数。
• 精确计时与缓动： ae_get_keyframes（跨多个图层和属性的关键帧表：每个关键帧的整帧位置和精确时间、精确值、插值方式、After Effects 中存储的每个维度的精确速度 + 影响、切线、游离状态；标记帧间关键帧；可选提供每段曲线的归一化数值）、ae_set_keyframe_table（写回此类表格，在一个撤销步骤中修改多个属性，并精确保留每项属性）、ae_copy_ease（将参考关键帧的精确缓动应用于其他属性和图层的关键帧，并明确维度数不同时所用的规则）、ae_audit_easing（根据项目中使用最多的曲线检查运动一致性：列出与任何曲线都不匹配的片段）、ae_retime_keyframes（围绕锚点缩放、偏移或按整帧错开，并适配新的帧速率；保持曲线形状，遇到关键帧落在同一帧时会拒绝操作）
• 经测量的布局： ae_align_layers（根据真实屏幕边界框对齐、分布和居中；会处理父子关系、缩放、旋转和文本字形框，而非锚点；报告移动后的任何剩余偏差）
• 效果、形状与遮罩： ae_list_available_effects、ae_get_effect_params（获取效果的精确参数名称、类型、默认值和范围，不会触碰你的图层）、ae_apply_effect、ae_set_effect_params、ae_remove_effect、ae_apply_preset（通过路径指定动画预设 .ffx 文件）、ae_add_shape、ae_add_mask
• 文本： ae_style_text_range（按范围或匹配的词语逐字符设置样式）、ae_set_paragraph（对齐方式、缩进、间距、文本框大小）、ae_add_text_animator（动画器属性 + 范围／摆动／表达式选择器）
• 3D： ae_set_camera（单节点／双节点、以 mm 为单位的焦距、景深；报告视角）、ae_set_light（类型、颜色、强度、锥角、衰减、阴影）、ae_set_material（材质选项，并列出 3D 渲染器）
• 音频： ae_audio_to_keyframes（将音频转换为关键帧）、ae_audio_markers（在节拍／峰值处添加标记）
• 颜色： ae_color_settings（Adobe 或 OCIO 颜色引擎、工作空间、位深、线性化、OCIO 空间）
• 素材： ae_set_footage_interpretation（匹配帧速率、Alpha、场、下拉帧、循环、像素长宽比）、ae_set_proxy、ae_relink_footage（在文件夹树中按名称查找缺失文件，并保留序列）
• 文件与导出： ae_find_files（支持 glob、~、任一 Unicode 规范化形式的名称、深度和结果数量限制；不会陷入符号链接循环；无需 After Effects）、ae_export_frames（导出合成、单个图层或素材的 PNG 静帧；支持帧列表和范围，可在一次调用中进行多次导出；除非指定 overwrite: true，否则绝不覆盖文件）；当文件无法按 importAs 要求的方式导入时，ae_import_files 会给出提示
• 基本图形： ae_essential_graphics（将属性添加为控制器，并设置模板名称）、ae_export_mogrt
• 渲染： ae_list_render_queue、ae_add_to_render_queue、ae_get_render_settings / ae_set_render_settings（将每项渲染设置和输出模块设置作为可编辑的键值对）、ae_queue_in_media_encoder、ae_render_background + ae_render_jobs（在独立进程中运行 aerender，并显示进度且支持取消；After Effects 可继续使用）、ae_render_queue_start、ae_clear_render_queue、ae_render_profile（渲染配置）、ae_handoff_package（交付包）、ae_farm（渲染农场） 可以通过 ID、名称或省略合成来引用当前活动合成；图层可通过从 1 开始的索引或名称引用；属性可通过类似 "Transform/Position" 或 "Effects/Gaussian Blur/Blurriness" 的路径引用（显示名称或匹配名称）。

适用于任何语言版本的 After Effects。 在非英语版 After Effects 中，属性、效果和菜单名称会被翻译。常见的英文名称在所有语言版本中仍然有效：Transform/Opacity 这样的属性路径、"Gaussian Blur" 这样的效果，以及 "Pre-compose..." 这样的菜单命令，都会映射到内部匹配名称和命令 ID，这些名称和 ID 在所有语言版本中都相同。匹配名称（ae_get_properties / ae_get_effect_params 返回的 ADBE ...）始终有效，遇到未知效果名称时会给出建议。

工具配置

每次聊天时，所有工具描述都会发送给 AI，因此默认只加载核心的 29 个工具（约 12k 个 token，而非全部 114 个工具的 50k 个 token），其他所有工具仍可按需使用：ae_tools 会按类别列出所有工具（或提供所选工具的完整参数详情），ae_call 则可按名称运行任何工具，并采用相同的验证、权限、变更报告和活动日志。在支持聊天内视图的 AI 应用中，四个带视图的工具（ae_preflight、ae_project_xray、ae_project_history、ae_stress_test）会加入核心工具集，因为只有 AI 应用直接调用工具时才会显示视图。

也可以选择预先加载所有工具：在 Surehand 面板中切换到 All tools（☰ › Tools the AI sees › All tools），在 Claude Desktop 的扩展设置（"Enable all tools"）中为 .mcpb 启用，或在 ~/.surehand/ae/config.json 中设置 "toolProfile": "full"，然后重启 AI 应用。进阶用法： "toolProfile": "core,ae_import_files,ae_render_queue_start" 可添加单个工具。

核心工具集：ae_status、ae_run_script、ae_get_scripting_guide、ae_render_frame、ae_render_contact_sheet、 ae_get_project_info、ae_get_comp_info、ae_get_layer_info、ae_get_selection、ae_get_properties、 ae_find_properties、ae_get_layer_bounds、ae_get_comp_map、ae_create_comp、ae_add_layer、ae_add_shape、 ae_set_property、ae_set_keyframes、ae_set_expression、ae_apply_effect、ae_get_effect_params、ae_undo、 ae_batch、ae_checkpoint、ae_prove_identical、ae_list_scripts、ae_run_script_file、ae_tools、ae_call。

功能参考

了解各项验证功能的工作方式、检查内容以及不检查的内容。

交付前检查

交付前，请让 AI 对合成执行交付前检查（ae_preflight）。它会根据交付规格检查项目，并可选择检查渲染文件：交付规格是一个小型 JSON 文件，其中包含客户或广播机构交付文档中的数值（也可以直接在聊天中提供相同内容）。没有内置任何内容：没有预设，每个规格部分都是可选的，只有提供了相应部分才会运行检查。AI 可以帮你编写规格（action: "schema" 会提供可用字段）。

在项目中，对于交付的合成（规格中的 comp，否则为当前活动合成），检查以下内容：

• **视频：**合成尺寸、帧速率、像素宽高比和时长（精确值、带帧数容差的值，或范围）。
• **项目：**位深、工作色彩空间、缺失素材、字体和效果、表达式错误，以及仍带有效果的已禁用图层（使用与 Project X-ray 相同的收集器，但仅检查交付合成及其预合成）。
• **安全区域随时间变化：**每个可见文本图层，以及你指定的任何图层（支持 Logo* 这样的通配符），在其可见的每一帧（或每隔 N 帧）上的边界框；计算时会考虑位置、缩放、旋转、锚点、父级，以及所在的预合成，并据此检查标题安全区、动作安全区或画面边界。问题会以时间范围的形式显示，例如“标题：超出标题安全区 00:00:02:03–00:00:03:10（2.12s–3.40s），最远处超出右侧 46 px”。已关闭、透明（不透明度为 0）或不在入点和出点范围内的图层不可见，因此不会检查。3D 图层会标记为未检查（请使用 ae_get_layer_bounds 检查，该工具会通过摄像机进行投影）；自动定向，以及会在变换之外移动或缩放像素的效果（Transform、Offset、图层样式、文本动画器），会标记为警告，因为边界可能不准确。找不到任何图层匹配 layersMustBeIn 中名称时，会给出警告，而非通过。
• **文本：**最小大写字母高度（估算值为字体大小 × 图层缩放 × 0.7，因为实际字体约为 0.65 至 0.75）、阅读速度（文本可见期间每秒显示的字符数，计入空格，不计换行）、最短屏显时长、溢出文本框的段落文本（After Effects 24.6 或更高版本），以及字体缺少字形的字符（After Effects 25.1 或更高版本）；在较旧版本中，报告会说明无法执行此项检查。

对于渲染文件（target: "file" 或 "both"）：检查编解码器、容器、位深、色度抽样、Alpha、场序、色彩标签、合法范围、黑帧和冻结帧、响度和真峰值，以及闪烁检查。文件检查需要 ffmpeg：可以使用系统上已有的版本，也可以一次性下载。闪烁检查是用于尽早发现明显问题的预检查，并非经过认证的 PSE / Harding 测试。

报告开头会显示判定结果：有任何失败时显示失败（n）；否则，如果规格要求的检查无法运行或只能基于不完整数据运行（没有 ffmpeg、用于检查合法范围的文件是 RGB 文件、检查需要更新版本的 After Effects、文件无法读取至末尾），则显示不完整（n 项检查未运行），因此未运行的检查绝不会视为通过；否则显示警告（n）或通过。之后报告会列出已请求但未运行的检查及原因，再按检查项目归类列出结果（先列失败项，再列警告项，并按时间排序），其中包含以合成帧速率和秒数表示的时间码、问题所在位置（合成 > 图层）以及简短的修复建议；最后列出本次检查未涵盖的内容（规格中未包含的部分，或目标为项目时未执行的文件检查）。对于文件，报告还会显示 ffprobe 检测到的内容，以及最严重问题处最多四帧的画面。交付前检查不会更改项目，也不会留下撤销步骤，因此也可在只读模式下运行。较长的合成会在时间预算内检查（timeBudgetSeconds，默认值为 120 s）；若检查不完整，报告会明确说明。

交付前检查：渲染文件

预检还会使用 ffprobe 和一次 ffmpeg 扫描画面与声音，按照相同的交付规范检查渲染后的文件。仅当规范中包含相应部分时，才会运行该项检查；如果无法运行某项请求的检查，会列出原因（例如没有 ffmpeg、用于合法范围检查的 RGB 文件，或 ffmpeg 未报告某个值），并将判定结果标为 INCOMPLETE。当规范要求音频时，没有音频流的文件会检查失败（通常是输出模块中的 Audio Output 处于关闭状态）。每个解码帧都会按照画面自身的时长进行计数：文件截断或损坏时会检查失败（“只能解码 8 s 中的 2.8 s”），而不会因为已读取的部分就通过；解码错误则会作为警告。时长（以及末尾的黑场／静帧）以画面为准，而非容器；声音比画面长或短超过一帧时，会发出警告。

规范部分	文件中的测量内容
video	容器（文件扩展名）、编解码器、帧尺寸、像素宽高比、帧率（30000/1001 是 29.97，不是 30）、时长（± durationToleranceFrames）、位深、色度抽样、Alpha、场序，以及标记的色彩原色／传递函数／矩阵／范围（缺少标记时会发出警告）
audio	采样率、声道、required；按照 ITU-R BS.1770 / EBU R128 测量响度（ffmpeg ebur128）：综合响度、响度范围、真峰值、最高短时（3 s）响度
legalRange	按文件自身位深缩放到 8-bit 后，检查每一帧的每个像素（10-bit 的 941 对应 235.25：超出 16-235 范围）；当某帧中超出亮度／色度范围的像素比例超过 maxOutOfRangePercent 时，该帧检查失败。按时间范围报告，并列出最严重帧及其代码值。仅适用于 YUV 文件
black、frozen	ffmpeg blackdetect / freezedetect：检测时长超过 maxSeconds 的片段（根据 allowAtStart / allowAtEnd 允许开头／结尾出现黑场；同一段黑场不会再次作为静帧报告）
flash	预检查，并非经认证的 PSE / Harding 测试：将画面划分为 32x18 网格，测量每个单元的相对亮度；当较暗状态低于 0.8，且亮度变化至少达到 minLuminanceChange 时，即视为一次转变；当一对方向相反的转变覆盖屏幕至少 minAreaFraction 时，即视为一次闪烁；任意一秒内闪烁次数超过 maxFlashesPerSecond 时检查失败。除非 redFlash 为 false，也会检查饱和红色闪烁（R/(R+G+B) >= 0.8，(R-G-B)x320 的变化 > 20；定义参照 ITU-R BT.1702 / WCAG 2.x）

检查结果中的时间以文件中的秒数表示。最多会将四张最重要失败时间点的 JPEG 帧（宽度不超过 960 px）写入 ~/.surehand/ae/tmp，并在报告中显示，随后立即删除（取消检查时也会删除；超过一天的残留文件会被清理）。在 Apple Silicon Mac 上，对一段一分钟的 1080p ProRes 422 HQ 文件运行所有检查约需 4 s（合法范围检查会标记超出范围的像素，并将该掩码缩小至小网格后求平均；这种方法结果精确，且比对每帧进行完整统计快得多）。

ffmpeg。 Surehand MCP 会按以下顺序查找：~/.surehand/ae/config.json 中的 "ffmpegPath" / "ffprobePath"、~/.surehand/ffmpeg 中的私有副本，然后是 PATH（在 Mac 上还会检查 /opt/homebrew/bin 和 /usr/local/bin）。如果都不存在，只有在你允许后，它才会将 FFmpeg 9.0.2 下载到 ~/.surehand/ffmpeg 一次（在“询问”权限模式下，还需在 Surehand MCP 面板中批准；只读模式下绝不会下载）。下载的是经过固定版本号的构建，且会与源代码中记录的 SHA-256 值进行校验；在使用前，程序必须能够启动并报告预期版本，否则会拒绝该文件，且不会安装任何内容：

• macOS（Apple Silicon 和 Intel）：Martin Riedl 的静态发布构建（ffmpeg.martin-riedl.de）， ffmpeg.zip + ffprobe.zip，约 60 MB。这些是 GPL v3 构建（包含 x264 / x265）。
• Windows x64（以及 Windows on Arm，可运行 x64 程序）：BtbN/FFmpeg-Builds 月末发布版本中的 ffmpeg-n9.0.2-...-win64-lgpl-shared-9.0.zip（这些版本会保留），约 77 MB。采用 LGPL v2.1+。

Surehand MCP 不会随附或重新分发 FFmpeg：它会在你的计算机上下载发布方自己的文件，并将其作为单独的程序运行，因此，FFmpeg 的许可（上述 GPL / LGPL 条款，其源代码可从 ffmpeg.org 获取）适用于该副本，而不适用于 Surehand MCP。~/.surehand/ffmpeg/SOURCE.json 会记录已安装的内容及其来源。若要使用自己的 FFmpeg，请安装它（brew install ffmpeg、winget install ffmpeg），或设置 "ffmpegPath"。

压力测试

ae_stress_test 会在编辑器或客户端发现问题之前，找出哪些地方会出错：它会对合成中公开的每个变量输入最坏情况数据，并测量每项结果。

• **测试变量：**合成的 Essential Graphics 控制器（文本、数字、复选框、菜单、颜色、媒体替换），以及读取数据的文本，或你指定的图层。输入是测试数据，而非外观样式：根据当前文本长度缩放的德语和芬兰语长字符串、带数字的希伯来语和阿拉伯语、日语、中文、韩语、泰语、印地语、组合标记、表情符号、全大写、空文本、单个字符、无空格；零、负数、极大值、超出滑块上限的值、多位小数、两种分隔符样式、百分比；每种复选框和菜单状态。也支持你自己的值或 CSV / JSON 行。组合会均匀抽样，并设有上限；报告会说明保留了哪些组合。
• **测量内容：**在动画的关键帧，以及每段文本开始和停止显示的位置，测量文本框溢出情况及超出多少像素和多少行（After Effects 24.6+）、帧安全区 / 标题安全区 / 动作安全区（你的边距）、文本实际渲染大小（你的最小值，或比合成自身文本更小）、缺失字形（25.1+）和替代字体、缺少所需方向或排版引擎的从右向左文本及复杂文字、行数和单词中间的换行（24.3+）、与你指定图层的重叠情况，以及文本中显示的数字是否正确。合成本身已有的问题会作为基线只列出一次。
• **其他语言中的表达式：**使用英文显示名称引用对象（effect("Slider Control")("Slider")、thisLayer("Transform")("Opacity")、默认形状和蒙版名称），在其他语言版本的 After Effects 中会出错；每项都会列出语言安全的写法（索引、匹配名称或属性）。
• **绝不修改你的合成：**每个变量都会设置在一个临时副本上，同一步骤就会删除该副本；之后会重新读取你的合成（每个属性值），且必须与原来完全一致，否则报告会说明情况（proveUnchanged: true 会添加像素证明）。只读模式会返回测试计划和表达式扫描结果。
• **报告内容：**PASS / FAIL 及出错内容、位置、帧数和幅度（“标题超出文本框 184 px；共 3 行，而 f48 处的文本框只能显示 2 行”）、变量和检查项网格，以及每个失败变量对应的 PNG 联系表。AI 应用提供视图的情况下，网格中还会标出每个失败帧。

变更报告

每次编辑项目的调用都会附带一个 Changes 列表，由 After Effects 自行生成（比较调用前后的快照），例如：

Changes (layers/properties compared in: Main):
+ layer "Headline" in "Main"
~ layer "Plate" in "Main": name "Plate" -> "Background"; locked off -> on
+ Headline > Effects/Glow
~ Headline > Transform/Opacity: 100 -> 0, expression added
~ Headline > Transform/Position: [640,360] -> [640,800], keyframes 0 -> 2

始终比较项目项；并比较活动合成以及调用中提及的任何合成里的图层、属性、关键帧、表达式、效果和蒙版。如果脚本中途失败，报告会列出它已完成的更改。ae_undo 会报告撤销的内容。对于非常大的合成（数万个属性），每次编辑大约会多花 1 秒；可在 ~/.surehand/ae/config.json 中设置 "changeReport": false 关闭此功能，也可对单个脚本设置 report: false。

已验证的编辑

有些更改不应改变画面：取消预合成、深度复制合成、烘焙或折叠表达式、重新排序效果、简化绑定。ae_prove_identical 可以验证这一点。它会渲染合成的参考帧（默认使用活动合成，在工作区间内取 5 帧，完整尺寸，最大 1920 px）；由你或 AI 进行更改后，它会再次渲染相同帧，并逐像素进行比较。结果为 identical、identical within tolerance（默认差异小于半个 8 位步长，因此只有 16/32 位项目的舍入误差会通过；tolerance: 0 表示要求逐位相同）或 differs。每帧都会列出最大通道差异、变化的像素数、最大颜色差异（ΔE）、变化区域，以及差异最大的帧的差异图像（黑色 = 相同）。如果捕获后合成已被删除或调整了尺寸，也会说明。比较的是采样的视频帧，包含 Alpha；不比较音频、合成的背景颜色和采样帧之间的时段。保存帧时，32 位值中大于 1.0 的部分会被钳制，因此过亮区域的差异可能被忽略。合成 ID 仅在一个项目内有效：在已保存项目中捕获的证明，只会与同一文件中的内容比较（否则结论未经验证）；在未保存项目中捕获的证明，只要每个合成仍保留原名称就会进行比较，并注明无法确认项目本身。 action: "run" 可通过一次调用完成整个流程：捕获、以 ae_batch 步骤执行编辑（一个撤销步骤，全部成功或全部回滚），然后进行比较。 对于取消预合成和深度复制，ae_precomp_surgery（见「预合成手术」）会自行执行编辑（包括重写表达式），并在应用前以相同方式验证结果。 参考帧会在 ~/.surehand/ae/proofs/ 中保存 7 天（最多保存 30 个证明）。渲染方式与 ae_render_frame 相同：通过一个临时合成完成，渲染后会将其删除，且不会留下撤销步骤（After Effects 仍会将项目标记为已更改）；如果无法删除临时合成，结果会说明这一点。只读模式下允许捕获和比较；run 会执行编辑，因此权限与 ae_batch 相同。

预合成手术

继承来的项目通常需要重构：某个本不该存在的预合成，或需要连同所有嵌套预合成一起复制且解除链接的合成（即“深度复制”）。After Effects 自带命令和免费脚本可能会丢弃预合成图层原有的内容，并悄无声息地破坏 comp("Logo").layer("Title") 或 thisComp.layer(3) 这样的表达式。ae_precomp_surgery 会精确完成操作，否则就完全不做。

• unprecompose 会将预合成图层中的图层移入其合成，并放在该图层所在的位置。空对象会承载预合成图层的锚点、位置、缩放和旋转（包括关键帧和表达式），移入的顶层图层会设为其子级（预合成内部的父子关系会保留；当变换为单位变换时，bakeNull 不会保留空对象）。图层会按预合成图层的开始时间移动，并裁切至其持续时间范围；完全位于该范围之外的图层移动后会被关闭。合成中重名的图层会添加数字后缀。表达式会使用真正的 JavaScript 解析器读取，并按位置改写：在移入的图层中，thisComp.layer("x") 会指向移入后的副本，thisComp.layer(3) 会指向其新索引，thisComp.width（以及其他所有合成属性）会变为 comp("<precomp>").width；从项目中的任何位置按索引引用该合成自身图层的表达式，会继续指向下移后的图层。轨道遮罩和图层控制参数会指向移入的图层。一个可见图层会接管预合成图层的不透明度和混合模式。源合成会保留（只有在没有其他内容使用它时，removeSource 才会将其移除）。
• deep_duplicate 会复制一个合成及其所有嵌套预合成，每个合成仅复制一次（同一个预合成即使在多个位置使用，也只对应一个副本），将副本中的预合成图层指向相应副本，并改写副本中的 comp("X")（当 X 位于该树中时；对树外合成的引用保持不变）。suffix（默认值为 " copy"，名称冲突时会添加数字）。副本会创建在原件旁边：After Effects 会将每次移入文件夹的操作分别记录为一个撤销步骤，因此移动副本（ae_move_items）会留作单独步骤处理。素材和纯色图层会共享，不会复制。

若无法精确复现，则拒绝操作并给出确切原因：预合成图层上存在效果、遮罩、图层样式、时间重映射、时间伸缩、轨道遮罩、3D、折叠变换、运动模糊或帧混合；预合成包含多个可见图层时，其混合模式或不透明度；预合成中的图层会与合成中的其他图层交互（混合模式、调整图层、保留底层透明度、摄像机、灯光、3D 图层）；帧速率或运动模糊设置不同；基本图形覆盖项；图层延伸至预合成画面之外，且该部分会显示；以及无法安全改写引用的表达式：在运行时计算出的名称或索引、图层索引变化时图层自身的 index 或 wiggle / random（以图层索引作为随机种子）、图层随时间移动时的 time、toComp 等方法、对预合成图层本身的引用、存在歧义的合成名称，以及手术前就有错误的表达式（改写后可能开始正常工作）。override: ["expressions"] 或 ["bounds"] 会强制继续操作：这些问题仍会列出，并保持原样，最终由验证结果决定。dryRun 只返回计划：哪些内容会移动、哪些内容会重命名、所有表达式改写（改写前 → 改写后）以及所有问题。 先验证，再修改。 会保存检查点（项目必须已保存）、渲染参考帧（默认在预合成图层的时间跨度内渲染 6 帧，包括首帧和末帧；深度复制时在工作区间内渲染 5 帧），并在临时副本上预演修改（复制父合成；深度复制时复制各个副本）。会将临时副本与原始合成逐像素比较，比较方式与 ae_prove_identical 相同（使用默认容差），随后再次删除临时副本。只有结果为完全一致时，才会在一个撤销组中对项目执行相同的修改，并逐图层将结果与预演结果核对（否则会立即撤销）。After Effects 可能会拆分此类撤销组（图层复制和源替换时都遇到过），因此 ae_undo 可能需要执行多次；结果会改为说明确切的恢复方法：对于取消预合成，恢复先前保存的检查点（使用 ae_checkpoint 恢复，并提供其 id）；对于深度复制，因为它不会更改原始内容，只会添加副本，{action: "remove_copies", id} 会移除其列出的确切副本（如果副本被外部内容使用，则拒绝执行）。存在差异表示未应用任何修改：结果会列出差异最大的帧、差异图像以及可能的原因（例如，预合成图层经过缩放时，预合成会整体重新采样，而移动的图层只会变换一次）。其他合成中的表达式重写属于精确文本编辑；像素验证覆盖父合成（或复制的合成树）。

来自数据的版本

ae_versions_from_data 可将 CSV 或 JSON 文件（或聊天中的行）转换为模板合成的多个版本，然后 检查每一行。填入数据很简单；关键是确认每个版本都正确。没有任何内容是内置的：每种格式、颜色、尺寸和边距都来自你的数据和自定义规则。

• **映射：**每列对应模板合成的一个图层（或 Essential Graphics 控制器）：文本；按你的格式设置的数字（小数、十进制和千位分隔符、前缀、后缀、负数写法）；来自单元格或自定义规则的颜色（例如“低于 0：#C62828，否则为 #2E7D32”）；替换图层源素材的素材文件；任意属性值；或通过数值到像素的映射设置条形图在屏幕上的宽度或高度（例如 0 → 0 px，100 → 800 px）。名称来自类似 {comp} - {City} 的模式。
• 两种模式。duplicate（图层目标）会按每行复制合成。复制合成不会复制其中的预合成（所有版本共用它们），因此目标必须是模板合成自身的图层。essentialGraphics（控制器目标）会按每行创建一个合成，将模板作为预合成，并设置该行的 Essential Graphics 值，方式与 After Effects 保留实例级数值相同；此模式无法测量行的布局，因此不会运行这些检查。
• 一步撤销，并显示 Changes 列表，且可先创建检查点。dryRun: true 会根据模板和数据检查映射，并显示每行将获得的内容，但不会进行任何更改。在构建任何内容之前，如果项目中已存在同名项、目标带有关键帧或输出文件已存在，操作都会被拒绝。
• **检查每一行：**会在实际渲染的位置读回每个值（应用表达式后），因此文本会准确显示格式化后的字符串，颜色也会符合规则；段落文本不得溢出文本框，映射后的文本在每一帧都必须位于画面内（或在按自定义边距设置的标题安全区或动作安全区内），并使用 Preflight 自身的代码进行测量；字体缺少字形的字符以及缺失的字体都会导致该行失败；会在屏幕上测量条形图（包括父级影响），并根据你的映射检查是否在设定的容差范围内；素材文件必须存在。
• **报告：**给出判定结果（FAIL (n of m rows)、INCOMPLETE、WARNINGS 或 PASS）、汇总，然后每行显示一条结果：PASS，或说明失败内容和位置的 FAIL。未运行的检查（例如旧版 After Effects、检查时间点图层不可见、Essential Graphics 模式）会使该行变为 INCOMPLETE，绝不会变为 PASS。
• 渲染（可选）：queue 会使用你指定的输出模块模板和输出路径模式（/renders/{City}_{#3}.mov），将每个版本加入渲染队列；render: true 只会渲染通过检查的版本。除非设置 overwrite: true，否则绝不会替换已有文件。

本地化

ae_localize 会将合成中的文本发送给译者并取回译文，同时检查每种语言。

• 导出（action: "export"）：将合成及其预合成中的每个文本图层（无论是否可见；逐个关键帧处理带关键帧的 Source Text）导出为供 Excel 使用的 CSV（带 BOM 的 UTF-8，因此希伯来语和阿拉伯语可以正确打开；每种语言占一列），或供 CAT 工具使用的 XLIFF 1.2（Trados、memoQ、Phrase……；每种语言一个文件）。XLIFF 1.2 是 CAT 工具支持最广泛的版本；也可以读取 2.0 文件。每个字符串都带有上下文：合成和图层、屏幕上的显示时间、段落框或点文本到画面边缘（或安全区域）的宽度、字符数限制（由你指定，或使用 maxChars: "fromBox" 根据文本框估算）以及备注。
• 导入（action: "import"）：每种语言生成一个版本。合成树会像从数据复制合成生成版本那样进行复制：根合成以及所有含有译文的预合成都会被复制，副本之间会相互引用（"{comp} [{lang}]"）。更改列表中会显示为一个撤销步骤；dryRun: true 会显示每种语言将获得的内容；如果项目中已存在同名项，则会拒绝导入，除非设置 overwrite: true。
• **按你的规则适配，绝不擅自调整：**按你指定的顺序执行允许的调整：将字距调整值减至最低值、将字号减至最低值（或减至以合成像素计的最低大写字高，该高度根据字体测量）、将水平缩放比例减至最低值、将段落框最多扩展指定像素（远离文本对齐的边缘）；点文本则限制在你指定的宽度内。每一步都只调整到刚好适配为止。如果文本仍无法适配，则保留最佳尝试结果，并以尝试过的调整内容报告 FAIL；绝不会低于你指定的最低值。未设置规则时，不会进行任何调整。
• **从右向左：**希伯来语、阿拉伯语、波斯语、乌尔都语和意第绪语（根据语言代码或 direction 判断）会设置从右向左的段落方向，并使用 Universal composer（以前称为 South Asian and Middle Eastern，After Effects 24.0+）；其对齐方式也会镜像（左对齐变为右对齐）；对齐方式翻转的点文本会保持原位。可为每种语言指定字体（fonts: {"he": {"*": "YourHebrewFont"}}）。脚本无法实现，因此不会执行：镜像布局本身、kashida 两端对齐、逐字符设置方向。
• 每种语言的检查，措辞类似 Preflight（FAIL (1 of 3 languages)、INCOMPLETE、PASS）：回读每段文本的渲染结果、适配情况、方向、文本框溢出、每帧中文本是否位于画面或安全区域内、是否缺少字形（希伯来语和阿拉伯语常见问题：拉丁字体不包含这些字母）以及是否缺少字体。未翻译的字符串会导致 FAIL（或通过 allowUntranslated: true 发出警告）。
• 差异（action: "drift"）：按语言列出自导出后发生变化的源文本，并与文件中的源文本进行比较；导入时也会对此发出警告。

重新调整格式

ae_reformat 会按你设定的规则将合成调整为其他尺寸（从 16:9 调整为 9:16、1:1、4:5 或任意尺寸），然后逐帧检查结果。不会替你做任何猜测：没有预设，也没有“智能裁剪”。

• **规则：**必须覆盖或适应新画面的背景图层；必须保持在标题安全区、动作安全区或画面内（含你设定的边距）的图层；固定在边缘或角落并带有 px 边距的图层；允许缩放的图层及其缩放范围（相对于自身尺寸的百分比）；文本的最小大写字母高度；要关闭的图层。图层名称可精确指定，也可使用通配符（Logo*）。未被任何规则指定的图层，会保留其相对于画面中心的偏移，就像 After Effects 自带的“合成设置”调整尺寸时使用中心锚点一样。
• **编辑：**创建合成副本（源合成绝不会被更改），在一个撤销步骤中完成，并可先创建检查点，随后列出更改。位置和缩放关键帧会按相同的移动和缩放方式映射，空间切线和缓动速度也会相应缩放，因此运动会保持原有形态。父子关系中的图层会在其父级空间内移动，轨道遮罩会随其图层移动，3D 图层会随画面中心移动。除非规则指定了全画幅预合成内部的图层，否则会重复使用预合成；如果指定了，则会复制并重新调整该预合成的格式，报告也会说明原因（可通过 precomps: "reuse" 或 "duplicate" 选择）。
• **检查：**在新合成上运行 Preflight 项目检查（包括你的安全区规则和最小大写字母高度，可逐帧检查或每隔 N 帧检查一次），还会检查覆盖／适应、固定位置，以及计划与 After Effects 实际生成结果是否一致。判定结果由 Preflight 给出：PASS、FAIL (n)、INCOMPLETE 或 WARNINGS (n)。
• 无法满足规则时（例如标题太宽，无法在不低于最小大写字母高度的情况下适应 9:16，或固定位置与标题安全区冲突），图层会保留效果最佳的尝试，报告会标记为 FAIL，并说明原因及你可以考虑的选项：缩短文本、换行、降低最小值或调整缩放限制。AI 不会替你做选择。
• dryRun: true 会显示计划和预测结果，不会进行任何更改。

渲染分析

After Effects 自带的分析器只显示单帧。ae_render_profile 会分析合成在整个时间线上的渲染耗时，并且只有在确认画面未发生变化时才会保留提速结果。

• measure 会为抽样帧计时（默认在工作区域内抽取 24 帧，每次渲染前清空图像缓存，取 3 次渲染的中位数），并以文本热力图显示结果和最慢的时间范围。随后，它会在最慢的帧上依次关闭各图层和效果，并测量差值（耗时，单位为 ms 和百分比）。分析结果会附带证据：仍然耗时的不可见图层、已证明使用 16 bpc 与使用 32 bpc 画面相同、在运动模糊下重新计算的表达式、尺寸过大的预合成，以及其他隐藏开销。每项结果都会标记为 可应用（optimize 可以应用并验证）、建议（由你决定）或 未知（例如脚本无法读取的多帧渲染支持情况）。timeBudgetSeconds（默认 300）会阻止启动新的测量，报告会说明已测量的内容。
• 项目会保持原样。 每项开关都会恢复原值并重新读取确认，结果也会说明这一点（“Project unchanged”）。这些开关仍会显示为 Edit > Undo 历史记录中的步骤，彼此抵消；After Effects 也可能将项目标记为有未保存的更改。在只读模式下，仅测量帧耗时。
• optimize 会在创建检查点后，逐项应用你选择的分析结果。每项都会使用默认容差通过 ae_prove_identical 进行验证；如果画面不相同，会自动还原。结果会报告测量帧上的节省时间。
• **限制：**抽样帧之间的耗时为估算值；图层和效果的开销可能重叠（遮罩、调整图层、表达式），因此无法直接相加；验证只覆盖抽样帧，不覆盖音频或抽样帧之间的时间。分析结果会在 ~/.surehand/ae/profiles 中保留 7 天（最多 30 个）。

交接包

要将项目交给客户、其他工作室或渲染农场？ae_handoff_package 会将项目整理到你指定的文件夹中，采用 File > Dependencies > Collect Files 的目录结构：项目文件，以及项目使用的素材，位于 (Footage)/<Project panel folders>/ 中；每个图像序列单独放在一个文件夹中，并包含代理文件。交接包中的项目是重新链接到已收集文件的副本（素材项保留名称，表达式可能会用到这些名称）；collect: "all" 也会复制未使用的素材，而 reduce: true 会将未使用的项排除在副本之外。除非设置 overwrite: true，否则绝不会替换文件夹中已有的文件；也绝不会将交接包写入你的项目或其素材所在位置。

项目文件旁会生成 handoff.json（供工具使用）和 HANDOFF.txt（供人阅读），其中列出项目使用的字体及使用这些字体的图层（包括版本，以及 After Effects 提供信息时列出的 Adobe Fonts）、每个效果的匹配名称及其显示名称、类别和版本（如果 After Effects 报告了插件版本，则列出该版本；这不是插件“关于”窗口中的版本）、After Effects 版本、位深和颜色设置（工作空间、OCIO 配置和色彩空间、线性化、混合）、表达式引擎、每个素材项的规格及其保存位置、缺失项（素材、占位符、字体、插件）以及总大小。第一行会显示 Opens clean，并列出接收方所需的内容（字体、带版本号的第三方插件、OCIO 配置），或者指出无法正常打开的原因：缺失项、仍指向交接包外部的素材、会显示为缺失项的未使用素材，以及表达式错误（会对副本中的每个表达式进行求值）。

verify: true 可验证交接包的渲染结果是否与项目一致。aerender（After Effects 的命令行渲染器）会从项目副本和交接包副本分别渲染示例帧（默认每个合成在工作区间内渲染 5 帧；选择渲染队列中任意状态的合成，否则选择活动合成，或使用 verifyComps），每次渲染都在独立进程中进行；然后使用与 ae_prove_identical 相同的比较方法逐像素比对帧。结果为 IDENTICAL、DIFFERS（附带帧、差异区域和差异图像）或 NOT VERIFIED，并说明原因（未找到 aerender、没有 PNG 输出模块、渲染失败）。此过程需要几分钟：aerender 会启动 After Effects 两次。每次都会列出无法验证的内容：接收方机器上的字体和插件（只检查当前机器）、移至其他位置的交接包（After Effects 会像使用 Collect Files 时那样，相对于项目查找已收集的素材）、示例帧之间的画面、音频，以及各合成工作区间起始时刻之外的表达式。用于验证的副本中，渲染队列只包含示例帧，因此你自己的排队渲染不会运行。

不会编辑当前打开的项目，但 After Effects 中的脚本无法在不打开项目的情况下保存其副本：交接包是通过“另存为”创建的，最后会从磁盘重新打开你的项目。因此，项目必须先保存（有未保存更改的项目会被拒绝），其撤销历史会从头开始；结果也会确认磁盘上的文件未改变（大小、日期和 SHA-256），且重新打开后没有未保存的更改。操作遵循权限模式，与任何编辑一样（只读模式下会被拒绝；询问模式下会在写入任何内容之前请求一次批准）。

渲染农场

在这里可以正常渲染的内容，在渲染农场节点或同事的机器上可能会失败：那里未安装的插件或字体、只有这台机器能访问的路径中的素材、不同版本的 After Effects，或缺失的 OCIO 配置。 ae_farm 会测量渲染所需的内容，而不是凭空猜测；并将长时间渲染拆分为多个区块，确保每个区块都已完整完成。你自己的渲染队列项目和输出模块才是事实依据：渲染不会使用自带的设置。它不会在其他机器上运行任何内容；其他机器会获得一份清单，用于核对，并获得在那边运行的脚本。

• manifest：针对排队中的渲染队列项目（或 rqIndex），提供节点所需的全部信息：After Effects 版本和构建版本、位深、颜色设置（工作空间、线性混合、OCIO 配置及其是否位于项目文件夹内）、表达式引擎、可读取偏好设置时的多帧渲染、按匹配名称列出的所有效果（标记第三方效果、列出 After Effects 报告的版本，以及使用这些效果的合成）、渲染涉及的文本图层所用字体，以及渲染通过预合成读取的所有文件：路径、大小、图像序列的帧范围和缺帧情况、渲染使用的代理，以及路径位于本机（主文件夹、桌面、本地磁盘）还是共享位置（网络挂载、UNC 路径，或通过 sharedPaths 指定的文件夹）。输出模块：格式、脚本可读取时的编解码器、路径，以及文件夹是否存在且可写。save: true 会在项目旁写入 <project>.farm-manifest.json 和 .txt（除非设置 overwrite: true，否则绝不覆盖现有文件）。
• check：根据清单检查一台机器：是否安装 After Effects 和 aerender 及其版本、项目、素材（序列中的每一帧）、代理、OCIO 配置和输出文件夹是否可访问，字体文件夹中是否有相应字体（从字体文件读取 PostScript 名称），Plug-ins 文件夹中是否有第三方插件（按匹配名称），以及表达式引擎。在节点上（没有 After Effects）： surehand-ae farm check <manifest.json> [--map /Volumes/Jobs=J:\Jobs] [--ae <install folder>] [--json] （退出代码：0 表示就绪，1 表示缺失或不匹配，3 表示无法完成所有检查）。在聊天中，运行中的 After Effects 自带的效果和字体列表也会纳入检查。
• plan：将一个渲染队列项目拆分成多个帧范围，供此机器上的 processes 个进程使用，或供具名的 machines 使用（每台机器都指定平台、aerender、路径映射和相对速度）。每个分块都会获得相应的 aerender 命令（-project、-rqindex、-s / -e 使用 After Effects 显示的帧编号（从合成的起始帧算起：一段从 01:00:00:00 开始、时长 4 秒、帧率为 25 fps 的合成，其帧范围为 90000-90099），必要时设置 -output；若多进程共用一台机器，则在共享 CPU 时使用 -mfr），每台机器还会获得一个脚本（macOS 上为 .command，Windows 上为 .bat）。脚本会与项目一起写入 farm-plan.json。图像序列：每个分块都写入同一序列；如果输出模块通过“起始编号”给文件编号，计划将被拒绝（每个分块都会覆盖相同文件），并会标记 [####] 补零位数不足的情况。影片：每个分块都会写入自己的文件，另附用于拼接这些文件的 ffmpeg concat 步骤；若拼接无法无损完成（例如长 GOP 编解码器，如 H.264、AAC 音频，或 PCM 拼接点落在采样点之间），计划会说明这一点，并建议改为渲染图像序列。以下情况会拒绝计划：项目包含多个输出模块、渲染设置指定了自己的帧速率、输出仅包含音频。时间估算取自 ae_render_profile 对该合成的测量数据；如果没有测量数据，则会基于当前抽样渲染的几帧进行估算，并说明未计入哪些时间（aerender 启动、编码）。
• run_local：在此机器上将各分块作为并行 aerender 进程运行，作为后台渲染作业（日志、进度、取消、面板的作业文件）：同时运行的进程数不会超过核心和内存所允许的数量，其余进程会在前面的进程完成后启动。在 Windows 上，每个进程都会等到前一个进程渲染出第一帧后再启动（两个 aerender 进程同时启动会在 Windows 上发生冲突）；如果某个分块的 aerender 在渲染第一帧前就结束，则会重新启动一次，status 会通过其日志说明这一情况。若未指定 plan，则使用打开的项目旁的计划文件（并说明使用的是哪个文件）；如果该项目有多个渲染队列项目，则会拒绝运行。除非设置 overwrite: true，否则绝不覆盖现有输出；项目再次保存后，计划会被拒绝。即使 AI 应用重新加载服务，渲染也会继续：status 会根据文件重新找到运行任务，并显示每个分块的进度和每帧用时（aerender 的总耗时除以帧数）。status 只报告状态（打开项目的最新运行任务；设置 all: true 可查看所有运行任务），绝不会启动或重试渲染。如果服务停止时仍有分块在等待，该运行任务会报告为中断，并列出剩余分块的 aerender 命令；使用其 run 调用 run_local 可恢复该任务，但只能在任务开始后 6 小时内，且项目自计划创建以来未发生更改时恢复。
• verify：验证分块运行结果，无论它们在哪台机器上运行。图像序列：检查每帧是否恰好存在一次、是否没有多余帧、文件是否非空且未被截断（PNG 文件完整、JPEG 具有结束标记、DPX 大小字段正确；其他格式依据文件头检查），并精确列出缺失帧以及需要重新渲染的 -s / -e 范围（缺失、空白和截断的帧）。会检查若干帧：如果这些帧全是同一张纯色画面（这是合成范围之外的帧的渲染结果），则验证失败。在项目于 After Effects 中打开时，还会将抽样的 2 帧与其自身渲染结果进行比较（颜色转换容差为 4/255；若画面不同则验证失败：差异超过画面的 1%，或分布范围超过画面的四分之一；文本边缘等局部细微差异——这是因为 aerender 和应用程序的抗锯齿略有不同——会作为提示列出像素数量和位置）。影片：使用 ffprobe 检查每个分段的帧数和时长，然后核对拼接文件的帧数、大小、帧速率和编解码器是否与合成及输出模块一致；若拼接能够无损完成，join: true 会拼接各个分段（绝不覆盖现有文件）。proveFrames 会对指定数量的帧进行严格的像素验证（采用 ae_prove_identical 比较和容差）。结果为 PASS、FAIL (n) 或 INCOMPLETE，并说明无法检查的内容。

项目透视

打开别人的项目？让 AI 透视一下（ae_project_xray）。它会读取整个项目，不做任何改动，并解释项目的工作原理，而不是整理项目：渲染队列实际渲染了哪些合成，以及每个合成调用了哪些预合成（还有哪些合成完全没有被渲染）；每个表达式读取了什么，以及绑定架构依赖哪些图层；哪些链接已经损坏，或者会在图层重命名、重新排序或项目在另一种 After Effects 语言环境中打开时失效；缺少哪些插件、素材和字体；素材是如何指定的（与合成帧率不匹配的帧率、超大素材），以及哪些因素会拖慢渲染（高负载效果、隐藏在隐藏或已禁用图层上的效果、较高的运动模糊采样数、3D 渲染器、帧混合、缩放比例很小的素材）。你会得到通俗易懂的回答；AI 会获取精确位置（合成 > 图层 > 属性）。大型项目会在时间限制内读取，并在回答不完整时说明；comps 和 sections 可缩小分析范围。

项目历史

“v11 和 v12 之间改了什么？”ae_project_history 可以回答。快照是对当前打开项目的记录：每个项目项（合成、带文件路径的素材、纯色图层、文件夹）、合成设置、每个图层及其开关、时间设置、父级和轨道遮罩、所有非默认值或带动画的属性（值、带插值和缓动设置的关键帧）、表达式、效果、遮罩、文本、标记和渲染队列。创建快照不会更改项目，也不会增加撤销步骤；快照保存在 ~/.surehand/ae/history 中（每个项目保留最近 100 个），每次 ae_checkpoint save 也会保存一个快照，因此可以比较检查点（时间预算为 15 s，以确保保存速度；如果时间不够，检查点会注明快照不完整，也可以通过 snapshot 创建完整快照）。差异会比较两个快照，或比较某个快照与当前项目，并按合成分组列出改动，首先显示摘要：

Summary: 1 layer added, 1 layer renamed, 2 values changed, 1 keyframe change, 1 expression changed, 1 effect added
Comp "Main" (id 12):
  + layer #1 "Logo" (shape)
  ~ layer #2 "Title": renamed from "Headline"
  + Title > Effects/Glow (ADBE Glo2)
  ~ Title > Transform/Opacity: keyframes: @1s 100 -> 80
  ~ Title > Transform/Position: expression changed:
        - wiggle(2, 10)
        + wiggle(3, 10)

可以通过标签（“v11”）、快照或检查点 ID、latest、previous 或 current 指定版本。较长的差异会截断，并注明剩余内容的数量；detail 可完整显示一个合成。读取大型项目需要一些时间（数千个图层时需要几秒）；comps 可将快照限制在指定合成范围内，timeBudgetSeconds 可限制耗时（未能读取的合成会明确报告，不会悄悄跳过）。此功能推出前保存的检查点没有快照；若要比较，就必须用旧 .aep 替换当前项目打开，因此不会自动执行此操作。

与你的 AI 应用聊天

Surehand 面板中的 ☰ › 与你的 AI 应用聊天 会运行你已安装并登录的 AI Agent： Codex、Claude Code 或 Antigravity。模型由你自己的订阅提供支持；Surehand 从不存储或处理 密钥或登录信息。每次聊天中，Agent 只能使用 Surehand 的工具，并会在当前打开的 项目中工作。

• 所有操作都受你的控制。 Agent 发出的调用都是普通的 AI 调用：完全 / 询问 / 只读、暂停 AI、审批卡片和活动日志的适用方式与其他 AI 应用完全相同。在询问模式下，只要聊天窗口处于打开状态，审批卡片就会显示在聊天中（按 Esc 拒绝）。
• 内置工具处于关闭状态。 Agent 的 Shell、文件编辑和 Web 访问会被关闭或禁止；Agent 自己针对 Surehand 工具的审批提示也会关闭，因此由 Surehand 的模式决定是否允许操作。
• 不会更改你的 Agent 设置（Codex 和 Claude Code 的选项仅对本次运行生效）。Antigravity 不支持按会话配置 MCP 选项，因此聊天屏幕会要求你确认一次以进行连接：备份后，将 Surehand 添加到 Antigravity 的 MCP 服务列表，并添加一条允许使用 Surehand 工具的规则；断开连接和卸载程序都会移除这两项。
• 登录： 用于聊天的 AI 应用屏幕会将每个应用标记为“已就绪”“未登录”或“未安装”，并说明登录方式（claude auth login、codex login，或启动一次 agy）。

设计说明、命令行以及各个 Agent 的流式输出示例：docs/chat-in-ae.md。

聊天内视图

在支持交互式视图的 AI 应用（MCP Apps；例如 Claude Desktop、ChatGPT、VS Code 和 Cursor）中，部分结果会在聊天中附带视图：

• **预检报告：**判定结果、发现项的时间线，以及每个发现项对应的帧。
• **项目 X 光视图：**从渲染队列到素材，展示哪些内容会被渲染，以及缺失、脆弱、隐藏时占用资源过多或未使用的内容。
• **压力测试：**变体和检查项网格，标记每个失败帧，并显示在其他 After Effects 语言版本中会出错的表达式。
• **变更内容及证明：**已验证编辑的判定结果，以及编辑前、编辑后和差异帧，并显示项目中发生的变更（历史差异也适用）。

视图只能用于浏览和查看；绝不会更改项目。所有编辑都通过聊天进行。不支持视图的 AI 应用（Claude Code、Windsurf、LM Studio）会获得相同的文本结果。

命令行

已安装的服务也可作为命令使用：surehand-ae <command>（或 node ~/.surehand/ae/server/surehand-ae.mjs <command>）。surehand-ae --help 会列出所有内容。

命令	功能
selftest [--full]	检查安装和连接；--full 会运行所有主要工具并保存兼容性报告
diagnostics	生成可粘贴到错误报告中的报告（不含机密信息）
activity [n]	最近 n 次工具调用
clients, connect <app>, disconnect <app>	此计算机上的 AI 应用及其连接状态（claude-desktop、claude-code、codex、cursor、vscode、windsurf、lm-studio）
chatgpt	为网页端 ChatGPT 提供 HTTP 服务和公共隧道
update [--check] [--channel beta|stable]	安装最新版本，或仅查看更新信息
checkpoints, checkpoint-diff <id>, checkpoint-save	查看项目的检查点、检查点之后的更改，或保存检查点
skills [install|uninstall]	查看 Surehand 技能的安装位置；写入或移除技能
farm check <manifest.json>	在渲染节点上检查渲染所需内容是否齐备，无需 After Effects
install, uninstall, setup	安装、移除，或仅安装/更新扩展、配置和技能

面板命令（使用 --json 时会打印一个 JSON 对象，且不会提出任何问题；未知命令会报错退出）：clients → {clients: [{id, name, installed, configured, inUse?, note?, action?}], snippet?}； connect <app> / disconnect <app> → {ok, message}；checkpoints [--project <path>] → {checkpoints: [{id, at, label, file, history?}]}；checkpoint-diff <id> [--project <path>] → 文本（{text}；需要 After Effects：用于与打开的项目进行比较）；test --json → {checks: [{ok, name, message?, fix?: {connect, label?}}]}；update --check → {latest, current, updateAvailable, url, checkedAt, channel, notes?, keptBeta?} （不会安装任何内容）。错误以 {error} 的形式返回。面板会使用 ~/.surehand/ae/runtime.json 中指定的 Node 和服务运行这些命令。活动日志条目还包含 changeList、revision、undoGroup，以及 ae_preflight / ae_prove_identical 的 result: {verdict, summary}；后台渲染会持续更新 ~/.surehand/ae/renders/<id>.json。

环境变量： SUREHAND_AE_CONFIG（配置文件； 实例会在其旁边查找）、SUREHAND_AE_BRIDGE_PORT、SUREHAND_AE_TOKEN、SUREHAND_AE_HTTP_PORT、 SUREHAND_AE_HTTP_TOKEN、SUREHAND_AE_TOOLS（core / full）、SUREHAND_AE_INSTANCE、 SUREHAND_AE_BLOCKED_AFTER_SECONDS、SUREHAND_AE_STARTUP_WAIT_SECONDS、SUREHAND_AE_NO_UPDATE_CHECK、 SUREHAND_AE_NO_AUTOSETUP、SUREHAND_AE_NO_ACTIVITY_LOG。

更新

更新： 点击面板底部的版本号（或选择 ☰ › Check for updates…），然后在 Updates 页面安装；也可以运行 surehand-ae update（update --check 仅查看更新信息）。该命令会从最新的 GitHub 版本下载服务，验证其 SHA-256 校验和及启动情况，然后替换已安装的版本（旧版本会保留为 surehand-ae.mjs.previous），并更新 After Effects 扩展。之后请重启 After Effects 和 AI 应用。如果使用 Claude Desktop 扩展（.mcpb），请从版本发布页面安装新的 Surehand-MCP.mcpb。有新版本发布时，面板会在版本号旁显示 · update ready（每天最多检查一次 GitHub；可在 ~/.surehand/ae/config.json 中设置 "updateCheck": false 关闭）。

Beta 更新： 在面板中开启 ☰ › Settings › Beta updates（或运行 surehand-ae update --channel beta；在 config.json 中设置 "updateChannel": "beta"），即可获取预发布版本：系统会以相同方式检查并安装 beta 版本和稳定版本中较新的那个。关闭此选项（--channel stable）不会回退到旧版本：较新的 beta 版本会保留，直到发布更新的稳定版本。

从 1.3 更新

自动完成。首次运行 1.4 时（无论是安装、更新还是直接启动），你的设置、检查点、项目历史记录、访问令牌和 AI 应用连接都会迁移过来，因此 ChatGPT 连接器 URL 仍可正常使用。不会删除任何内容：如果某项内容无法迁移（例如文件正在使用），一切仍会在原位置正常运行，之后会再次尝试迁移；原因记录在 ~/.surehand/migration.log 中。重启一次 After Effects 以加载新面板；在此之前 Surehand 会提示你。对于 Claude Desktop 扩展：1.4 的 .mcpb 会作为新扩展（surehand-ae）安装，因此安装后请在 设置 > 扩展 中移除旧版本的条目。开发者可在 名称 中查看迁移内容及其去向。

故障排查

问题	解决方法
“无法连接到 After Effects”	确保 AE 正在运行。打开 Window > Extensions > Surehand MCP 查看桥接状态。如果菜单中没有 Surehand MCP，请重新运行安装程序并彻底重启 AE。
菜单中缺少扩展	运行 selftest：它会根据扩展的签名检查扩展文件（After Effects 会静默跳过文件已更改的已签名扩展）。重新运行安装程序会重写这些文件。作为最后的手段，也可以允许未签名扩展：在 macOS 上使用 defaults write com.adobe.CSXS.12 PlayerDebugMode 1 将 PlayerDebugMode 设为 1，或在 Windows 注册表的 HKCU\Software\Adobe\CSXS.12 下进行设置。
“8765–8774 端口全部被占用”	每个 After Effects 实例都会使用 8765 到 8774 中第一个空闲端口，因此这意味着有十个桥接正在运行，或其他程序占用了这些端口。关闭其他 After Effects 实例（或占用端口的程序），或者更改 ~/.surehand/ae/config.json 中的 bridgePort（端口范围的起始端口），然后重启 AE 和 AI 应用。
“令牌不匹配”	重新运行安装程序（它会保留现有令牌），然后重启 AE。
脚本无法运行 shell 命令或使用网络（“权限被拒绝”）	在 After Effects 中启用 Settings > Scripting & Expressions > Allow Scripts to Write Files and Access Network（Windows：Edit > Preferences > Scripting & Expressions）。Surehand 自带的工具不需要此设置；脚本也可以在未启用此设置时读取和写入文件。ae_status 和面板中的 Test 屏幕会显示此设置是否已开启。
调用超时	ExtendScript 无法中断：长时间运行的脚本或渲染会让 AE 忙碌，模态对话框则会阻止其运行。检查 AE，然后重试。对于长时间运行的任务，请传入 timeoutSeconds。
“After Effects 正忙或正在显示对话框”	AE 中打开了对话框或设置窗口（Project Settings、Preferences、警告），或者 AE 仍在启动。关闭窗口并重试：该调用尚未运行，也不会在之后运行。此状态会在 3 秒后报告；可通过 ~/.surehand/ae/config.json 中的 "blockedAfterSeconds" 更改（0 表示等待完整超时时间）。已开始运行的脚本绝不会被强行中断。
Claude Desktop 中未显示工具	完全退出 Claude Desktop（菜单栏／系统托盘），然后重新打开。检查 claude_desktop_config.json 中是否包含 surehand-ae。

**报告问题：**运行 2. Test Installation 或 surehand-ae selftest。如果有任何检查失败，程序会在末尾输出诊断报告（不含机密信息）。你也可以点击 Surehand 面板中的 Copy diagnostics，或运行 surehand-ae diagnostics，然后提交问题。更多帮助请参阅 wiki（故障排查、Surehand 面板）。

**同时运行多个 After Effects 版本。**每个正在运行的 After Effects 都会注册自己的桥接（端口 8765–8774）。AI 会控制你最近使用的实例；ae_status 会列出所有实例，并可通过 instance: "2025"（或版本号或端口）进行切换。在配置中设置 "instance": "2026" 可设为永久首选项。

**取消请求与卡住检测。**当 AI 应用取消请求时，如果 After Effects 尚未开始执行，该请求就会被丢弃。如果 After Effects 没有响应，错误消息会说明它正忙于什么以及持续了多久，并建议检查是否有对话框处于打开状态。ae_status 会显示相同信息。

限制

Surehand 目前不会做或暂时无法做到的事情。每项功能自身的限制，请参阅对应的参考章节。

• 目前使用 CEP。 面板和桥接程序是 CEP 扩展，也就是 After Effects 目前支持的扩展系统。Adobe 正在将其较新的扩展系统 UXP 引入 After Effects；计划推出 UXP 面板，脚本层保持不变。
• After Effects 必须正在运行。 Surehand 通过已打开的 After Effects 工作（少数功能除外，例如 ae_find_files 和 surehand-ae farm check）。我们针对 macOS 和 Windows 11 上的 After Effects 2025 和 2026，逐个版本进行了测试；从 CC 2019 起的旧版本也能加载扩展，但不保证完全可用。有些检查需要较新的 After Effects（段落溢出检查需要 24.6，缺失字形检查需要 25.1）；若版本过旧，工具会明确提示，而不会假装通过。
• 一次撤销一步，但有例外。 每次工具调用都是一个撤销组，但 After Effects 可能会拆分某些组（已发现于合成复制、图层复制和素材替换）。预合成修改和深度复制会明确说明恢复方法。交接包会从磁盘重新打开项目，因此撤销历史会重置。面板中的“撤销”只会撤销最近一次更改，且仅当此后没有发生其他更改时才可用。
• “允许脚本写入文件并访问网络”。 Surehand 自带的工具不需要启用此 After Effects 设置，脚本无需启用该设置也能读写文件。但运行 Shell 命令或使用网络的脚本需要启用；ae_status 和面板的测试界面会显示该设置是否已开启。
• ffmpeg 是 Preflight 检查渲染文件以及渲染农场处理影片分块（统计帧数、合并片段）所必需的。Surehand 会使用你已有的版本，或者在获得许可后下载一次经过固定版本和校验和验证的构建。项目中的其他所有功能都不依赖它。
• aerender（随 After Effects 一起安装）是后台渲染、交接包渲染验证以及渲染农场本地运行所必需的。
• 验证只抽样检查帧。 ae_prove_identical、预合成修改和渲染优化会比较抽样的视频帧，包括 Alpha 通道。不会比较音频、合成背景颜色或抽样时间点之间的内容。
• Preflight 的闪光检查是预检，不是经过认证的 PSE / Harding 测试。
• 只读模式和权限是防护措施，并非沙箱。 请参阅AI 能做和不能做的事。
• 在 After Effects 中聊天支持 Codex、Claude Code 和 Antigravity。Antigravity 的输出格式尚无文档说明：Surehand 会读取 Antigravity 的 CLI 1.4 写入的格式，因此后续 Antigravity 版本可能需要更新 Surehand。
• **从右向左书写：**已设置段落方向、文本编辑器和对齐方式；脚本无法镜像布局本身、进行克什米尔连写对齐或设置逐字符方向。

常见问题

**它能根据提示词制作动态图形吗？**不能。它是在你的项目中操作 After Effects：你的图层、关键帧、表达式和规则。它不会生成图像，也不附带预设或视觉效果。

**我的项目会离开我的电脑吗？**项目文件会保留在本地。你的 AI 应用会根据其提供方的条款，将你的消息和工具结果（包括 AI 渲染以供查看的帧）发送给该提供方。

**需要付费或注册账号吗？**不需要。它免费且采用 MIT 许可证。你需要使用已有的 AI 应用；适用该应用自己的方案。

**哪款 AI 应用效果最好？**任何支持 MCP 工具的应用都可以。支持在聊天中显示视图的应用（Claude Desktop、ChatGPT、VS Code、Cursor）还会显示 Preflight、X-ray、压力测试和证明视图。

**AI 会弄坏我的项目吗？**它和任何人一样都可能出错。因此，每次编辑都可通过一步撤销恢复，并附有更改报告；结构性编辑会经过验证；询问模式会先向你展示每项编辑；检查点则会保留安全副本。

**是否支持非英语版 After Effects？**支持。属性、效果和菜单名称会映射为匹配名称，这些名称在各种语言中都相同；压力测试和 X-ray 也会标记在其他语言环境下会出错的表达式。

开发

server/              MCP server (TypeScript) -> bundled into server/dist/surehand-ae.mjs
  src/aemcp.jsxinc     ExtendScript helper library, loaded into AE on demand (reloaded when it changes)
  src/tools/           tool definitions (each tool is a small ExtendScript function body)
  src/cli/             install / uninstall / selftest / chatgpt / setup commands (surehand-ae <command>)
  src/chat/            the panel's Chat with your AI app (agents, runner)
  scripts/smoke.mjs    end-to-end test against a running After Effects
  scripts/package.mjs  builds the shareable release folder, zip and .mcpb
  scripts/release.mjs  cuts a release: version, sign, check, Mac + Windows tests, package, installers, release PR, CI, merge, GitHub release
  scripts/test-mac.mjs      installs the build on this Mac and runs the full self-test on each open After Effects
  scripts/test-windows.mjs  the same on a Windows PC over SSH
  scripts/test-guard.mjs    lock and build checks so parallel test:mac runs don't test each other's build
  scripts/sign-extension.mjs  signs the After Effects extension
  scripts/package-mac-pkg.mjs        the signed, notarized Mac installer (.pkg)
  scripts/package-win-installer.mjs  the Windows installer (.exe, NSIS, built on the Mac)
  scripts/sign-win.mjs               signs Windows files with the Certum certificate (SimplySign)
  scripts/ci-check.mjs assertions for the CI install / uninstall dry runs
extension/           After Effects extension (signed): invisible bridge (auto-starts) + status panel
skills/              the Agent Skills (embedded in the server bundle; `install` writes them)
docs/                design notes (chat-in-ae.md)
installer/           run.sh / run.ps1: find or download Node.js, then run a surehand-ae command
  START HERE.txt       plain-language install guide (copied into the release)
  mac/, windows/       double-click launchers for a source checkout (the release generates its own)
brand/               the logo: master SVGs, PNG sizes, Surehand.icns / Surehand.ico (see brand/README.md)
.github/workflows/   CI: unit tests + real launcher install/test/uninstall on macOS and Windows

cd server
npm install
npm run check            # what CI runs: type-check, all tests, build (run before pushing)
npm test                 # unit tests only
npm run build            # -> dist/surehand-ae.mjs
node scripts/smoke.mjs   # live test: needs After Effects running with the bridge
npm run package          # -> ../dist-zip/Surehand-MCP/ (launchers, server, Surehand-MCP.mcpb) + zip
npm run sign             # re-sign the After Effects extension after changing extension/ or the version
                         # (needs the certificate in ~/.aemcp-signing; see scripts/sign-extension.mjs)
npm run test:mac         # install this build here and run the full self-test on each open After Effects
                         # (one run per Mac at a time: waits for ~/.surehand/test-mac.lock; reports the commit tested)
npm run test:windows     # the same on the Windows PC over SSH
npm run package:mac-pkg       # -> ../dist-zip/Surehand-MCP-<version>.pkg, signed and notarized (--no-notarize: faster)
npm run package:win-installer # -> ../dist-zip/Surehand-MCP-Setup-<version>.exe (--sign: needs SimplySign logged in)
npm run release -- 1.4.0 --notes notes.md   # everything above, then a release PR, its CI, merge and the GitHub release
                                            # (1.4.0-beta.1 makes a GitHub pre-release; --skip-installers skips both installers)

extension/ 中的 After Effects 扩展会在构建时嵌入服务包中，服务启动时会安装或更新该扩展。更改服务或面板后：重新构建、重新运行安装程序并重启 After Effects。

要添加工具，请在 server/src/tools/*.ts 中的某个数组里添加一项：包括一个 zod 输入架构，以及一个接收 args 并可使用 aemcp 辅助函数的 ExtendScript 函数体。本 README 中的工具数量由 server/test/readme-tool-count.test.ts 检查。

**名称。**该系列名为 Surehand（未来可能推出 Photoshop 和 Premiere 版本），因此此应用的名称为 surehand-ae：包括命令（ae-mcp 保留为别名）、服务文件 surehand-ae.mjs、MCP 服务名称以及各 AI 应用设置中的键（SERVER_NAME；1.3 使用的是 after-effects）、.mcpb 的 name（其 display_name 为 "Surehand MCP"），以及文件夹 ~/.surehand/ae（此应用）和 ~/.surehand（共享：node/、ffmpeg/）；这些都在 server/src/paths.ts 中。为确保脚本和扩展继续正常工作，以下内容保持不变：工具名称（ae_*）、After Effects 扩展 ID com.aemcp（及其 bundle ID）、aemcp 辅助对象和 aemcp:// 资源 URI。环境变量为 SUREHAND_AE_*；AEMCP_* 名称仍可使用。发布包中包含服务文件 surehand-ae.mjs，也包含 ae-mcp.mjs（1.3 的更新程序会下载此文件）。npm 包名称为 surehand-mcp。

从 1.3 迁移（server/src/migrate.ts）：1.3 将所有内容保存在 ~/.aemcp 中。1.4 将设置、检查点、项目历史记录及其他文件迁移到 ~/.surehand/ae，将私有 Node.js 和 ffmpeg 迁移到 ~/.surehand，并将运行旧服务的 AI 应用指向新服务（after-effects 会变为 surehand-ae；如果 after-effects 条目并非由我们创建，则会保留不动）。在重启 After Effects 一次之前，旧扩展仍会运行并使用 ~/.aemcp，因此该目录中会保留一份 config.json 副本、一个 instances 文件夹、一个用于启动新服务的小型 server/ae-mcp.mjs 文件以及 MOVED.txt；卸载时也会将它们移除。

在 Windows 上测试构建

已确认在 Windows 11 上可正常使用：安装（包括自动下载 Node.js）、自检和 ChatGPT 桌面应用。请使用此清单测试其他机器。

你需要一台安装了 After Effects 的 Windows 10/11 PC（或虚拟机）。你的 Creative Cloud 许可证允许激活两台设备，因此使用第二台机器也没问题。在 Mac 上使用 Parallels/VMware 中的 Windows 虚拟机也可行，但 Apple Silicon 上的 x64 模拟性能可能较慢，因此最好使用实体 PC。

1. 将 Surehand-MCP-<version>.zip 复制到 PC 上，右键单击 > 全部解压。
2. 确保 After Effects 已关闭，然后打开 3. Windows 并双击 1. Install。
   • 如果出现 SmartScreen：选择 更多信息 > 仍要运行。
   • 预期结果：如果未安装 Node.js，将自动下载；随后服务器、扩展程序（“扩展程序已签名”）以及找到的应用旁会出现勾号。
3. 启动 After Effects，并等待其完成加载。
4. 双击 2. Test Installation（同一文件夹中）。所有行都应显示勾号，最后显示 “所有检查均已通过”。
5. 在 After Effects 中，打开 窗口 > 扩展 > Surehand MCP：指示点应为绿色。
6. 打开 Claude Desktop（如果安装期间它已打开，请重启），然后询问： “检查 After Effects 是否已连接，然后创建一个带动画标题的 1080p 合成，并展示第 1 帧。”
7. 可选，更全面的测试：安装 Node 后，从完整的源代码检出目录运行 node server\scripts\smoke.mjs （先在 server\ 中运行 npm install）。此命令会调用所有主要工具，并要求 After Effects 处于打开状态。
8. 也可以试试 .mcpb：运行 4. Uninstall，双击 1. Claude Desktop (easiest)\\Surehand-MCP.mcpb，在 Claude Desktop 中安装， 让 Claude 检查连接（它应提示重启 After Effects），重启 AE，然后再次询问。

建议在 Windows 上特别检查以下情况：用户名中包含空格或非英文字符的路径、未安装 Node.js 的机器（用于测试自动下载），以及 ARM 版 Windows。 如果遇到失败，请发送 2. Test Installation 的完整输出，以及 %USERPROFILE%\.surehand\ae\bridge-status.json。

许可证和致谢

MIT，详见 LICENSE。本产品由 Conform Labs 开发，由 Ron Yitzhaki 创建并维护 (@ronyitzhaki)。

Surehand 不会附带 FFmpeg：在你允许的情况下，它会根据对应构建版本的许可证，下载发布者自己的构建版本（macOS 上为 Martin Riedl 的构建，Windows 上为 BtbN/FFmpeg-Builds）；详见 ffmpeg。脚本中的 JavaScript 会通过 Babel 转换为 ExtendScript。

Adobe 和 After Effects 是 Adobe 在美国和／或其他国家／地区的注册商标或商标。Surehand MCP 与 Adobe 无关联，也未获 Adobe 背书。