after-effects

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Overview

概述

This skill automates After Effects by generating ExtendScript (.jsx) and executing it via osascript. It reads project state through query scripts, uses rule files for domain knowledge, and wraps all mutations in undo groups.

本技能通过生成ExtendScript（.jsx）脚本并借助osascript执行，实现After Effects的自动化操作。它通过查询脚本读取项目状态，利用规则文件获取领域知识，并将所有修改操作包裹在撤销组中。

First-Time Setup

首次设置

Run
```
scripts/runner.sh
```
with any query script to detect the AE version
If multiple AE versions are installed, the user must choose one — runner.sh will prompt
Ensure AE Preferences > Scripting & Expressions > "Allow Scripts to Write Files and Access Network" is enabled

运行
```
scripts/runner.sh
```
并传入任意查询脚本，以检测AE版本
若安装了多个AE版本，用户必须选择其中一个——runner.sh会进行提示
确保在AE偏好设置 > 脚本与表达式中启用“允许脚本写入文件和访问网络”选项

Workflow

工作流

For every user request:

针对每个用户请求：

Step 1: Gather context (auto-run, no confirmation needed)

步骤1：收集上下文（自动运行，无需确认）

Run the active state query:

bash

bash scripts/runner.sh scripts/active-state.jsx

Then read

/tmp/ae-assistant-result.json

for active comp, selected layers, CTI.

If this is the first interaction or the project context is unknown, also run:

bash

bash scripts/runner.sh scripts/project-overview.jsx

This returns a summary by default: folder tree with counts, all comps listed, footage grouped by file type. NOT every individual file.

To drill into a specific folder:

bash

bash scripts/runner.sh scripts/project-overview.jsx '{"mode": "folder", "folderName": "Images"}'

Only use full mode when you actually need every item listed:

bash

bash scripts/runner.sh scripts/project-overview.jsx '{"mode": "full"}'

运行活动状态查询：

bash

bash scripts/runner.sh scripts/active-state.jsx

随后读取

/tmp/ae-assistant-result.json

获取当前合成、选中图层、CTI（当前时间指示器）的信息。

如果是首次交互或项目上下文未知，还需运行：

bash

bash scripts/runner.sh scripts/project-overview.jsx

默认情况下，这会返回一份摘要：包含带数量统计的文件夹树、所有合成列表、按文件类型分组的素材。不会返回每个单独文件的信息。

如需深入查看特定文件夹：

bash

bash scripts/runner.sh scripts/project-overview.jsx '{"mode": "folder", "folderName": "Images"}'

仅当确实需要列出所有项目时，才使用完整模式：

bash

bash scripts/runner.sh scripts/project-overview.jsx '{"mode": "full"}'

Step 2: Drill down if needed (auto-run)

步骤2：按需深入查询（自动运行）

If the task targets a specific comp:

bash

bash scripts/runner.sh scripts/comp-detail.jsx '{"compName": "Comp Name"}'

If the task targets specific layers:

bash

bash scripts/runner.sh scripts/layer-detail.jsx '{"layerNames": ["Layer 1", "Layer 2"]}'

Omit

compName

to use the active comp. Omit

layerNames

to use selected layers.

若任务针对特定合成：

bash

bash scripts/runner.sh scripts/comp-detail.jsx '{"compName": "Comp Name"}'

若任务针对特定图层：

bash

bash scripts/runner.sh scripts/layer-detail.jsx '{"layerNames": ["Layer 1", "Layer 2"]}'

省略

compName

则使用当前活动合成。省略

layerNames

则使用选中的图层。

Step 3: Load domain knowledge

步骤3：加载领域知识

Read the relevant rule file from

rules/

. Always read

rules/extendscript-fundamentals.md

— it contains ES3 constraints that apply to every generated script.

Task involves	Load rule file
Layers (create, move, parent, duplicate)	rules/layer-manipulation.md
Keyframes, animation, easing	rules/keyframes-animation.md
Expressions	rules/expressions.md
Compositions (create, precompose, nest)	rules/composition-management.md
Effects and parameters	rules/effects.md
Import, footage, assets	rules/assets-footage.md
Render queue, export	rules/rendering.md
Bulk/batch operations	rules/batch-operations.md
Version-specific features	references/ae-api-versions.md

从

rules/

目录读取相关规则文件。必须始终读取

rules/extendscript-fundamentals.md

——其中包含适用于所有生成脚本的ES3约束。

任务涉及内容	加载规则文件
图层（创建、移动、父级设置、复制）	rules/layer-manipulation.md
关键帧、动画、缓动	rules/keyframes-animation.md
表达式	rules/expressions.md
合成（创建、预合成、嵌套）	rules/composition-management.md
特效与参数	rules/effects.md
导入、素材、资源	rules/assets-footage.md
渲染队列、导出	rules/rendering.md
批量操作	rules/batch-operations.md
版本特定功能	references/ae-api-versions.md

Step 4: Generate the action script

步骤4：生成操作脚本

CRITICAL: Resolve the skill's real path first

Before writing or executing any action script, resolve the skill's real (non-symlinked) path. ExtendScript

#include

cannot follow symlinks, so you MUST use the real filesystem path.

Run this once at the start of each session:

bash

SKILL_SCRIPTS="$(readlink -f ~/.claude/skills/after-effects-assistant/scripts 2>/dev/null || readlink ~/.claude/skills/after-effects-assistant/scripts)"
echo "$SKILL_SCRIPTS"

Use the resolved path (

$SKILL_SCRIPTS

) for all subsequent Write and Bash commands in this session.

Why this matters:

```
~/.claude/skills/
```
is typically a symlink — ExtendScript
```
#include
```
fails through symlinks
Writing to the real
```
scripts/
```
directory lets
```
#include "lib/json2.jsx"
```
resolve correctly
The resolved path changes per machine, so never hardcode it

Every generated script MUST follow this template:

jsx

#include "lib/json2.jsx"
#include "lib/utils.jsx"

(function() {
    app.beginUndoGroup("AE Assistant: <action description>");
    try {
        var args = readArgs();
        var comp = app.project.activeItem;
        if (!comp || !(comp instanceof CompItem)) {
            writeResult({ error: "No active composition" });
            return;
        }

        // ... action code ...

        writeResult({ success: true, message: "<what was done>" });
    } catch (e) {
        try { writeResult({ error: e.toString(), line: e.line, fileName: e.fileName }); }
        catch(e2) { writeError(e.toString(), "line:" + e.line); }
    } finally {
        app.endUndoGroup();
    }
})();

Write the script using the Write tool, then execute with a short bash command:

Use the Write tool to write the script to
```
$SKILL_SCRIPTS/ae-action.jsx
```
(the resolved real path)
Execute it with bash:

bash

bash "$SKILL_SCRIPTS/runner.sh" "$SKILL_SCRIPTS/ae-action.jsx"

IMPORTANT: Do NOT use

cat > file << 'SCRIPT'

heredocs — they put the entire script in the bash command, cluttering the permission prompt. Always use the Write tool for the script content, then a short bash command to run it.

关键：先解析技能的真实路径

在编写或执行任何操作脚本前，需解析技能的真实（非符号链接）路径。ExtendScript的

#include

无法跟随符号链接，因此必须使用真实文件系统路径。

在每个会话开始时运行一次：

bash

SKILL_SCRIPTS="$(readlink -f ~/.claude/skills/after-effects-assistant/scripts 2>/dev/null || readlink ~/.claude/skills/after-effects-assistant/scripts)"
echo "$SKILL_SCRIPTS"

在本次会话的所有后续写入和Bash命令中，使用解析后的路径（

$SKILL_SCRIPTS

）。

为何这很重要：

```
~/.claude/skills/
```
通常是符号链接——ExtendScript的
```
#include
```
在符号链接下会失效
将脚本写入真实的
```
scripts/
```
目录，可让
```
#include "lib/json2.jsx"
```
正确解析
解析后的路径因机器而异，因此绝不要硬编码

所有生成的脚本必须遵循以下模板：

jsx

#include "lib/json2.jsx"
#include "lib/utils.jsx"

(function() {
    app.beginUndoGroup("AE Assistant: <action description>");
    try {
        var args = readArgs();
        var comp = app.project.activeItem;
        if (!comp || !(comp instanceof CompItem)) {
            writeResult({ error: "No active composition" });
            return;
        }

        // ... action code ...

        writeResult({ success: true, message: "<what was done>" });
    } catch (e) {
        try { writeResult({ error: e.toString(), line: e.line, fileName: e.fileName }); }
        catch(e2) { writeError(e.toString(), "line:" + e.line); }
    } finally {
        app.endUndoGroup();
    }
})();

使用Write工具编写脚本，再通过简短的Bash命令执行：

使用Write工具将脚本写入
```
$SKILL_SCRIPTS/ae-action.jsx
```
（解析后的真实路径）
通过Bash执行：

bash

bash "$SKILL_SCRIPTS/runner.sh" "$SKILL_SCRIPTS/ae-action.jsx"

重要提示： 不要使用

cat > file << 'SCRIPT'

heredoc语法——这会将整个脚本放入Bash命令中，导致权限提示信息混乱。始终使用Write工具编写脚本内容，再通过简短的Bash命令执行。

Step 5: Execute or confirm

步骤5：执行或确认

Auto-run (no confirmation needed):

All read-only queries (active-state, project-overview, comp-detail, layer-detail)
Non-destructive additions: adding a keyframe, adding an effect, creating a layer, creating a comp

Confirm before running (show the script and ask the user):

Deleting layers or comps
Removing keyframes
Replacing footage
Clearing expressions
Render queue operations
Any operation the user might not expect

自动运行（无需确认）：

所有只读查询（活动状态、项目概览、合成详情、图层详情）
非破坏性添加操作：添加关键帧、添加特效、创建图层、创建合成

运行前需确认（展示脚本并询问用户）：

删除图层或合成
移除关键帧
替换素材
清除表达式
渲染队列操作
任何用户可能意外执行的操作

Step 6: Execute and read result

步骤6：执行并读取结果

bash

undefined

bash

undefined

Execute the action script (already written to $SKILL_SCRIPTS/ae-action.jsx in Step 4)

执行操作脚本（已在步骤4中写入$SKILL_SCRIPTS/ae-action.jsx）

bash "$SKILL_SCRIPTS/runner.sh" "$SKILL_SCRIPTS/ae-action.jsx" '{"arg1": "value1"}'


Read `/tmp/ae-assistant-result.json` for the result.

bash "$SKILL_SCRIPTS/runner.sh" "$SKILL_SCRIPTS/ae-action.jsx" '{"arg1": "value1"}'


读取`/tmp/ae-assistant-result.json`获取执行结果。

Debugging failures

调试失败问题

If a script fails, check these in order:

~/.ae-assistant-log
— runner.sh logs every execution, args, results, and errors here
/tmp/ae-assistant-error.txt
— JXA-level errors (AE not responding, DoScriptFile failure)
~/.ae-assistant-extendscript.log
— ExtendScript-level logs from
```
appendLog()
```
in utils.jsx
AE Preferences — Ensure "Allow Scripts to Write Files and Access Network" is enabled

When an error occurs, read

~/.ae-assistant-log

to understand what happened, fix the script, and retry.

若脚本执行失败，按以下顺序排查：

~/.ae-assistant-log
—— runner.sh会记录每次执行的信息、参数、结果及错误
/tmp/ae-assistant-error.txt
—— JXA层面的错误（AE无响应、DoScriptFile执行失败）
~/.ae-assistant-extendscript.log
—— 来自utils.jsx中
```
appendLog()
```
的ExtendScript层面日志
AE偏好设置 —— 确保“允许脚本写入文件和访问网络”已启用

发生错误时，读取

~/.ae-assistant-log

了解问题所在，修复脚本后重试。

MUST

必须遵守的规则

ALWAYS wrap mutations in
```
app.beginUndoGroup()
```
/
```
app.endUndoGroup()
```
ALWAYS use matchNames for property access, not display names (display names are localized)
ALWAYS use 1-based indexing for layers and project items
ALWAYS write action scripts to
```
$SKILL_SCRIPTS/ae-action.jsx
```
(the resolved real path, NOT
```
/tmp/
```
)

ALWAYS use relative

#include "lib/json2.jsx"

and

#include "lib/utils.jsx"

(NOT absolute paths)

ALWAYS wrap in an IIFE to avoid global scope pollution
ALWAYS use
```
var
```
, never
```
let
```
or
```
const
```
(ES3)
ALWAYS write results to /tmp/ae-assistant-result.json via writeResult()
ALWAYS check
```
comp instanceof CompItem
```
before accessing comp properties

始终将修改操作包裹在
```
app.beginUndoGroup()
```
/
```
app.endUndoGroup()
```
中
始终使用matchNames访问属性，而非显示名称（显示名称会本地化）
始终对图层和项目项使用1-based索引
始终将操作脚本写入
```
$SKILL_SCRIPTS/ae-action.jsx
```
（解析后的真实路径，而非
```
/tmp/
```
）
始终使用相对路径的
```
#include "lib/json2.jsx"
```
和
```
#include "lib/utils.jsx"
```
（不要使用绝对路径）
始终将脚本包裹在IIFE中，避免污染全局作用域
始终使用
```
var
```
，绝不要使用
```
let
```
或
```
const
```
（遵循ES3标准）
始终通过writeResult()将结果写入/tmp/ae-assistant-result.json
始终在访问合成属性前检查
```
comp instanceof CompItem
```

FORBIDDEN

禁止操作

NEVER use ES5+ syntax: let, const, arrow functions, template literals, destructuring
NEVER use Array.map, Array.filter, Array.reduce, Array.forEach (not in ES3)
NEVER use JSON.parse or JSON.stringify without including json2.jsx
NEVER write action scripts to
```
/tmp/
```
— ExtendScript
```
#include
```
can't resolve paths from there
NEVER use absolute paths in
```
#include
```
— they break through symlinks
NEVER hardcode layer indices — use names, selection, or iteration
NEVER run destructive operations without user confirmation
NEVER assume a comp is active without checking
NEVER use
```
cat > file << 'SCRIPT'
```
heredocs to write scripts — use the Write tool instead, then execute with a short bash command

绝不要使用ES5+语法：let、const、箭头函数、模板字符串、解构赋值
绝不要使用Array.map、Array.filter、Array.reduce、Array.forEach（ES3不支持）
绝不要在未引入json2.jsx的情况下使用JSON.parse或JSON.stringify
绝不要将操作脚本写入
```
/tmp/
```
——ExtendScript的
```
#include
```
无法从该目录解析路径
绝不要在
```
#include
```
中使用绝对路径——会在符号链接下失效
绝不要硬编码图层索引——使用名称、选中项或迭代方式
绝不要在未获得用户确认的情况下执行破坏性操作
绝不要在未检查的情况下假设存在活动合成
绝不要使用
```
cat > file << 'SCRIPT'
```
heredoc语法编写脚本——应使用Write工具编写，再通过简短的Bash命令执行