alibabacloud-video-editor

视频编辑 Skill

在云端编辑视频（阿里云 ICE）——无需本地 ffmpeg。三种模式：

• 时间线编辑（SubmitMediaProducingJob）——拼接多个片段：你编写 Timeline JSON，脚本提交制作任务、轮询任务状态，并返回输出视频 URL。
• 普通模板（AddTemplate，Type=Timeline）——存储参数化的 Timeline Config，检查其 ClipsParam 契约，并通过替换文本/媒体反复渲染 → references/22-normal-templates.md。
• 智能生产（SubmitIProductionJob）——对单个媒体文件运行一种算法（智能封面、Logo/字幕擦除、字幕提取、抠图、美颜、横转竖、音频降噪/混音/分离/分析）。不涉及 Timeline → §7.1 和 references/13-intelligent-production.md。

此 Skill 是整个链条的最后一环。 内容理解——哪里发生了什么、谁在说话、哪些时刻值得关注——由上游的其他能力生成，并作为数据传递给此 Skill（§2.4）。这里的一切工作，都是将这些数据与素材结合，生成经过验证的成片。

硬性规则

以下六条规则不容置疑。本文档中的其他所有内容——每种字号、颜色、时长、预设和长度比例——都是已交付项目中的示例，而非硬性要求。了解这些示例所展示的可能性，然后根据素材和用户的需求自行判断。

1. 任何内容都不得落到用户的本地存储中。 媒体绝不下载——直接读取原处内容（ffmpeg -i "<https URL>" 通过 HTTP 流式传输；快照任务会返回带签名的帧 URL）。中间文件存放在 OSS 中：算法输出、配音片段、代理文件、转换后的输入——这些都是由 ICE 任务写入的 OSS 对象，绝不是用户磁盘上的文件。交付内容以播放 URL（§8）的形式提供，而非下载文件；只有用户明确要求时，才生成本地文件。少数必须写入本地工具才能读取的内容（波形 PNG、silencedetect 转录文本、要检查的帧、edl.json、project.md）都放在同一个临时目录中，且该目录必须位于用户项目之外——${TMPDIR:-/tmp}/video-editor/<session>；这些内容可随时丢弃，绝不在用户的工作区中创建。用户提供的本地文件必须先上传到 OSS（§4），再在那里进行处理。
2. 所有生成操作都必须通过 ICE；ffmpeg 只用于分析音频。 剪切、拼接、修剪、叠加、转场、字幕烧录、混音、变速、语音合成／配音、格式转换：都由 ICE 任务渲染（Timeline 使用 SubmitMediaProducingJob，单媒体算法使用 SubmitIProductionJob，Normal Timeline 使用模板渲染）。ffmpeg 的全部职责仅限于读取音频信号——波形（showwavespic）、静音／语音尾段（silencedetect）、响度（volumedetect）、时长（ffprobe）——且只输出这些分析数据（§1.4）。它绝不生成或转换媒体：不使用 concat，不对媒体文件使用 -filter_complex，不使用 -c copy，不重新编码，不使用 atempo，不转码。帧必须来自 SubmitSnapshotJob，而非 ffmpeg。唯一例外是图表，不是媒体：timeline_view.py 会从云端快照雪碧图中裁剪图块，并将其叠放在波形上方，因为没有 ICE API 能返回这两者（§1.4）。也不能使用 Python 媒体库，或其他云产品。如果没有 ICE 任务能实现用户的需求，就明确说明并停止——本地渲染交付内容是错误的做法，不是变通方案。
3. 先确认地域，再确认输出存储桶，然后才能开始渲染（§2.1）。生成模板配置和执行 AddTemplate 不需要存储桶；渲染则需要。没有默认地域，连 cn-shanghai 也不是默认值。
4. 提交任何任务之前，先用通俗语言确认计划（§2.2）。生成任务需要花费金钱和时间；一段文字则两者都不需要。
5. 报告任何交付内容之前，都必须先验证（§9）。Success 只表示文件已写入，仅此而已。绝不将未经验证的输出报告为已验证。
6. 每个包含多个片段的 Timeline 都必须编译；绝不直接编写。 即使用户只要求提供 timeline.json 并禁止调用云服务，也必须先编写 edl.json，然后执行 python "$SKILL_DIR/scripts/video_editor.py" compile --edl edl.json --output timeline.json——compile 可离线运行，不会调用云服务（§2.1、18-edl-and-compile.md）。生成的文件就是交付内容。修复所有阻止继续的检查项违规；compile 和 submit 执行相同的检查清单（§5）。 职责划分：references/ = 按需查阅的知识库；scripts/video_editor.py = 纯执行器（提交／轮询／获取 URL，以及 iproduction／iproduction-status）；scripts/frame_qa.py = 对云端素材进行模型审核——审核整段视频（--mode full）或带签名的快照帧（--frames），绝不从本地采样（§9）。所有剪辑逻辑都写在你生成的 Timeline 中。

1. 设置

下文中的 $SKILL_DIR = 此 SKILL.md 所在的目录。始终使用绝对路径调用脚本（python "$SKILL_DIR/scripts/video_editor.py" ...）；工作目录通常是用户的项目目录，而不是技能目录。

pip install -r "$SKILL_DIR/scripts/requirements.txt"

必须提供 AK/SK（§1.1）和 OSS 输出存储桶（§1.2），否则请停止并引导用户完成设置。DASHSCOPE_API_KEY（§1.3）和 ffmpeg（§1.4）是可选项：缺少时，请改用你自己的视觉能力读取云端快照帧进行验证（§9），绝不可跳过验证。

1.1 阿里云凭证（必需）

脚本使用阿里云默认凭证链：环境变量，然后是 aliyun CLI 配置文件（~/.aliyun/config.json，由 current 指定的配置文件，可通过 ALIBABA_CLOUD_PROFILE 覆盖），接着是 ~/.alibabacloud/credentials.ini，最后是 ECS RAM 角色。CLI 配置文件提供程序仅在 alibabacloud-credentials>=1.0.2 中提供，因此 scripts/requirements.txt 将其最低版本设为该版本 — 在较旧版本中，即使 aliyun configure 配置完全正确，也会被跳过，导致看起来像是缺少凭证，而不是版本问题。

引导用户选择一种偏好的方式：

# Option A — aliyun CLI (writes a reusable profile; recommended). Install if `aliyun` is missing:
brew install aliyun-cli   # macOS; or fetch a binary and `tar xzf` it + `sudo mv aliyun /usr/local/bin/`
# Binaries: https://aliyuncli.alicdn.com/aliyun-cli-darwin-arm64-latest.tgz (macOS), https://aliyuncli.alicdn.com/aliyun-cli-linux-amd64-latest.tgz (swap amd64→arm64), https://aliyuncli.alicdn.com/aliyun-cli-windows-amd64-latest.zip (put aliyun.exe on PATH)
aliyun version            # verify the install — aliyun CLI >= 3.3.3 required (upgrade: brew upgrade aliyun-cli, or re-download the binary)
aliyun configure          # prompts for AccessKey ID / Secret / region
# RAM role assumption or STS token: pick the matching authentication mode in the prompts

# Option B — environment variables in ~/.zshenv (all zsh sessions, incl. IDE terminals)
echo 'export ALIBABA_CLOUD_ACCESS_KEY_ID=<id>' >> ~/.zshenv
echo 'export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<secret>' >> ~/.zshenv

在 AccessKey 控制台获取密钥。验证SDK能否解析这些密钥 — aliyun sts get-caller-identity 只能证明 CLI 能读取自己的配置，不能证明 Python 凭证链已获取该配置：

python3 -c "from alibabacloud_credentials.client import Client; print(Client().get_credential().provider_name)"
# cli_profile/static_ak → Option A live; env → Option B live; CredentialException → nothing configured

1.2 OSS 输出存储桶（必需）

用于上传和存放作业输出：

export OSS_BUCKET=your_bucket_name
export OSS_ENDPOINT=oss-cn-shanghai.aliyuncs.com

存储桶在步骤 0 确认期间（§2.1）选定：运行 aliyun ossutil ls，只向用户展示其确认的区域内的存储桶，并让用户选择。绝不可擅自选择。OSS 使用同一条凭证链。输出存储桶必须与生成该作业的区域相同。

输出存储桶通常是私有的；§8 介绍如何将已完成的对象转换为经过验证的播放链接。

1.3 Model Studio API 密钥（可选，用于验证）

DASHSCOPE_API_KEY 可让 scripts/frame_qa.py 使用多模态模型检查已完成的视频。它是独立于 AK/SK 的凭证 — AK/SK 无法调用模型推理。在 Model Studio 控制台 → API-KEY中创建密钥，然后使用 echo 'export DASHSCOPE_API_KEY=sk-xxxxxxxx' >> ~/.zshenv 将其保存（适用于每个 zsh 会话，包括 IDE 终端），并打开新的 shell。如果只需要在交互式终端中使用，请改用 ~/.zshrc；不要同时在两个文件中设置。

如果用户拒绝设置或尚未设置，仍须进行验证 — 使用你自己的视觉能力读取云端快照帧（§9）。只需提及一次该密钥，然后继续；绝不可将未经验证的视频报告为已验证。

1.4 ffmpeg（可选——仅用于音频分析）

剪辑和合成不需要 ffmpeg——这正是此技能的要点。ffmpeg 在这里只有一项用途：在理解和验证阶段，将音频信号转换为模型可据以推理的文本或图表。它不会生成、转换或提取媒体（硬性规则 2），也不会下载媒体文件（硬性规则 1）——将 https URL 传给它，它就会流式读取所需内容；它写入的文件也仅限于临时目录中的分析产物（硬性规则 1）。

对于 ICE API 不会返回的音频信息，可使用它来生成 RMS 波形图（showwavespic）、检测静音和语音尾段（silencedetect——ASR 间隙可以标出句子边界，但无法覆盖环境音频尾段，见 17-snapshot-and-asr.md §1.5）、检测响度（volumedetect）和获取时长（ffprobe）。要在同一坐标轴上叠加云端胶片带和波形，可使用 timeline_view.py——图块来自快照任务；ffmpeg 绘制波形，并将两行内容拼成一张 PNG，这属于图表，而非媒体（硬性规则 2）。所有视觉内容都来自云端任务，而非 ffmpeg：帧、胶片带和联系表由 SubmitSnapshotJob 生成（17-snapshot-and-asr.md §2）；剪辑点则来自上游场景标签、omni_segment.py 或你查看的胶片带（§2.4）。

在 macOS 上安装：brew install ffmpeg。如果没有 ffmpeg：云端快照仍能覆盖你需要的每一帧（17-snapshot-and-asr.md），但你将无法获取波形、音频尾段和响度数值——请通过 --mode full（§9）进行验证，并明确说明哪些检查无法执行。不要默默降级。

1.5 可观测性——User-Agent

UA 模板： AlibabaCloud-Agent-Skills/{skill-name}/{session-id} skill-version/{skill-version}

Session ID 规则： 如果主机提供了 AGENT_SESSION_ID，请使用它；否则，每个进程生成一个 32 位小写十六进制 ID。同一次运行中的所有 Alibaba Cloud 调用必须使用同一个 session ID。这里的 {skill-name} 为 alibabacloud-video-editor，{skill-version} 来自 references/manifest.json——脚本会在导入时读取该值，早于创建任何云端客户端。scripts/video_editor.py 会构建一次该值，并将其应用于每个客户端；新客户端也必须设置 config.user_agent = USER_AGENT。

---

2. 工作流

步骤	操作	详情
0	先确认区域，再确认输出存储桶——务必先做这两件事	→ §2.1
1	对请求进行分类	→ §3 路由表
2	阅读匹配的参考文档	→ §3
3	收集素材 URL	→ §4
4	阅读素材——每个待解答问题对应一种信号（如下）。先看上游结果（§2.4），然后只运行能回答你仍需决定事项的 asr / snapshot / pack_material.py 流程	→ 17-snapshot-and-asr.md §0、§2.4、19-editor-brief.md
5	编写 EDL（剪辑决策），然后将其 compile 为 Timeline	→ 18-edl-and-compile.md；§5 检查清单会自动执行
6	用通俗语言提出计划——等待确认	→ §2.2
7	提交任务	→ §7
8	轮询并获取签名 URL	→ §8
9	验证、自行修复（≤3 轮），然后汇报	→ §9

单素材算法请求可走捷径：当整个任务是在一个文件上执行一种算法（智能封面、去除 Logo/字幕、字幕提取、抠像、美颜、H→V、语音降噪、音频混音/分离、节拍/副歌/质量检测）时，跳过步骤 4–5，从 §2.1 直接前往 §7.1——此类任务没有 Timeline，§5 检查清单也不适用。步骤 0、3、6、9（区域/存储桶、素材 URL、计划确认、验证）仍须执行。如果之后需要将算法输出与其他素材组合，先运行算法任务，再将其输出送入时间线流程（13-intelligent-production.md §6）。

创建普通模板也可走捷径：确认区域，设计并审核参数化 Config，然后在确认后调用 AddTemplate。只有在渲染模板前才需要输出存储桶。请阅读 references/22-normal-templates.md。

步骤 4 按信号逐项执行，并非全有或全无。 明确你仍需回答的问题，然后只获取能回答该问题的信号——索引见 17-snapshot-and-asr.md §0。整个文件拼接没有待解答问题，因此完全跳过步骤 4：从步骤 3 直接进入步骤 5。用户指定了时间和位置的字幕只有一个问题，而且是视觉问题——采样一帧并查看（11-output-verification.md §3）；ASR 回答的是一个无人提出的问题。asr 和 snapshot 都是计费任务：“几秒内返回”不等于“免费”，用错任务的成本与用对任务相同。

2.1 首先确认环境

切勿假定区域——即使是 cn-shanghai 也不行，即使 aliyun CLI 配置档案或凭据文件中已有区域也不行。对于渲染任务，请按以下顺序确认：

1. 询问用户要在哪个区域提交。 列出有效的 ICE 区域（cn-shanghai、cn-beijing、cn-hangzhou、cn-shenzhen、cn-zhangjiakou、ap-southeast-1），并指出相关限制：AI 功能需要 cn-shanghai / cn-beijing / cn-hangzhou——也就是所有 AI_* 片段和效果，以及每一个 SubmitIProductionJob 函数（§7.1），共 14 个；MediaId 输入必须在资源所在区域提交。如果任务尚不明确，用户可以暂缓选择——但在构建任何 Timeline 之前，必须回来完成这一步。
2. 询问要使用哪个输出 Bucket，并按已确认的区域筛选：aliyun ossutil ls 会列出所有 Bucket 及其区域——只向用户展示所选区域内的 Bucket，让用户选择。输出 Bucket 必须与作业位于同一区域。离线生成 Config 或执行 AddTemplate 时跳过这一步；首次渲染模板之前再回来确认。
3. 只有两项都确认后，才询问用户想制作什么视频（§3 起）。如果任务后来发现需要其他区域（例如在非 AI 区域使用 AI 功能，或 MediaId 位于其他区域），请回到第 1 步，与用户重新确认。

受限区域意味着要提问，绝不是备用选项。 如果用户指定的区域无法满足请求，请说明原因并停止：指出限制，列出能够满足请求的区域，并询问用户选择哪个区域以及同区域的 Bucket。不要为了验证本文档已经说明的内容而提交一次——iproduction 会在本地拒绝调用，根本不会发起 API 请求；服务返回 400 只会让人白跑一趟，却一无所获。也不要自行选择替代方案：失败后擅自切换区域、Bucket 或产品，是用户从未做出的第二个决定，而且会把输出放到用户未指定的位置。“直接提交” / “just submit it”可以免除计划确认（§2.2），但不能免除这项确认。

多片段剪辑必须使用 EDL。 只要任务是“拼接 N 段源素材”（集锦、宣传片、剧集拼接、蒙太奇），就要编写 edl.json——每个保留片段对应一条记录，包含 source/in/out/beat/quote/reason——并运行 compile（18-edl-and-compile.md）。它会生成 Timeline 并自动执行 §5 检查清单，因此迭代时只需修改一个数字，而不必重新生成整个 Timeline。添加装饰不构成例外：静音、背景模糊、滤镜和转场是逐段的 effects，环境叠加层是顶层 EffectTracks，BGM 是一条 audio 记录——这些都是 EDL 字段（18-edl-and-compile.md §1）。即使是前后拼接，同时还要静音、模糊、添加转场和铺设音乐，也仍然属于拼接，因此仍须编译。只有在一开始就没有片段列表时，才手动编写 Timeline：单片段任务、虚拟形象旁白、幻灯片模板。

直接生成 Timeline 时，请依次确定：输出类型 → 轨道 → 每条轨道上的片段 → 片段是否需要 In/Out/TimelineIn/TimelineOut（单纯前后拼接不需要）→ 效果/转场/音量 → 输出 JSON。

如果请求的信息不足，且会影响视觉效果，请先询问再进行组合——尤其要确认背景（没有背景的旁白/虚拟形象视频会以黑色背景渲染）。不要擅自选择用户未提出的视觉风格。

2.2 提交前确认计划

阅读素材并起草 EDL 后，用4–8 句话的通俗语言描述计划，然后停下来。说明剪辑的整体结构、保留和删去的片段、预计时长及其与源素材时长的对比、画面风格（转场／调色／水印——如无则明确说明）、字幕和音频处理方式，以及输出规格。然后等待。

根据素材提出它引出的问题，而不是照搬固定清单——每次合适的问题都不一样。但有两个问题几乎总值得一问，因为猜错会白白浪费一次渲染：目标时长以及是否需要水印（默认关闭——compile 不会凭空添加 EDL 未要求的内容，18-edl-and-compile.md §2）。

什么才算确认。 回复中用户能读到的文字。不是你的内部任务列表或待办事项，也不是编译后的 EDL，更不是带 --yes 的 submit 命令——该标志会跳过脚本关于输出路径和覆盖风险的 stdin 提示，与这一步毫无关系（§7）。一气呵成地从 compile 跳到 submit，意味着用户直到收到账单时才第一次听说剪辑方案。所以，不要写一个同时涵盖这两步的任务项——“说明计划，然后提交”是一个单独的任务项，一批工具调用就能把它勾掉，却可能从未真正写出计划。把计划单独列为一步，完成后发给用户，然后再执行 submit。如果无人能回复——例如脚本化或非交互式运行——仍要先写出计划再执行命令；没有人工回复，只能省去回复，不能省去这一步。

在这里，这一步比在本地编辑器中更有价值。制作任务需要花钱和时间，而被拒收的交付成果会让整个流程重来：一段真实的 79 s 源素材被剪到 66 s，却因“太长，不像高光片段”而遭拒，只得重新剪成 30 s（19-editor-brief.md §4）。如果事先用一段话说明方案，就能避免这个问题。

收到反馈后，修改 EDL 并重新编译——绝不要手动修补 Timeline（18-edl-and-compile.md §5）。

2.3 会话记忆——project.md

对于会跨越多个会话的项目，在临时目录中、与 EDL 放在一起维护 project.md（硬性规则 1）——绝不要放在用户的项目目录树中——并为每个会话追加一个 ## Session N — YYYY-MM-DD 小节，涵盖：环境（区域、输出存储桶、涉及的 MediaId）、策略（一段话）、决策（剪辑、时长、画面风格及原因，以及用户拒绝了什么）、产物（JobId、输出对象路径、值得复用的分析任务 ID）、待办（推迟处理的事项）。用户希望保留记录时，将其粘贴到聊天中，或写入他们指定的位置——那是他们的文件，不是中间文件。

在这项技能中，有两点尤其能体现这样做的价值。§2.1 可避免反复询问用户——阅读上次会话的记录，并以“上次我们用的是 cn-beijing / my-bucket，继续吗？”开场，而不是再次询问。分析结果也不必重复购买：对于未变更源素材上已运行过的 ASR 或快照任务，应查询已有结果，而不是重新提交。也要记录用户拒绝过什么——重新探索用户已经否决的策略，代价最高。

启动时，如果 project.md 已存在，应先用一句话总结上次会话，再提出任何建议。

2.4 上游分析结果——此技能使用的内容

链条中的前置阶段属于其他能力。收到它们提供的数据时，请将其视为权威信息，不要重新推导：

上游结果	用途
剪辑候选项／高光片段（from/to + 原因）	EDL 的 ranges[]——按给定值设置 in/out，将理由填入 reason（18-edl-and-compile.md §1）
带时间戳的转录文本／对话时间线	替代或交叉核对步骤 4 的 asr 阶段
字幕文件（SRT / WebVTT）	EDL 的 subtitles[]，或对展开后的 Timeline 使用 decompile --inline-srt（21-timeline-export.md）
标签／标记／人物出镜信息	决定保留哪些片段；帧精确的切点仍取自 ASR 标点和间隔（17-snapshot-and-asr.md §1.5）
说话人归属	哪个 VoiceId 对应哪句台词，以及术语表中的名称（17-snapshot-and-asr.md §1.7）
已克隆的 VoiceId（已训练——此技能不会训练声音）	AI_TTS 剪辑上的 customizedVoice（07-smart-media-features.md、09-voice-and-avatar-catalog.md）

两条规则：

• 上游时间戳对应的是候选级别，而非帧精确级别。 编译前，请将每个片段对齐到真实切点——标点 + ≥ 0.3 s 的间隔、上游标签／omni_segment.py／快照胶片条中的镜头边界（§1.4），或 silencedetect 检测到的音频尾部。直接照搬粗略片段会截断对话（18-edl-and-compile.md §1.5）。
• 缺少分析时应提出问题，而不是猜测。 如果请求需要你不掌握的内容信息（哪些时刻重要、谁在说话），请用户运行上游能力并提供结果。不要虚构片段，也不要在不告知用户的情况下退而采用整段视频剪辑。

---

3. 需求 → 参考资料路由

找到与请求所需能力相符的条目，阅读后再构建 Timeline。

这些条目描述的是能力，而非场景。没有“高光集锦”文档，也没有“视频翻译”文档：场景是由多项能力组合而成的，你需要从下方条目中组合所需能力——通常是其中两到三项，再加上 18-edl-and-compile.md。如果没有任何单个条目与请求完全匹配，这是正常情况，并不代表失败。

用户需求	阅读文档	关键类型 / 字段
任何内容（轨道与片段基础、时长控制、对齐）	01-timeline-basics.md	VideoTracks/AudioTracks/SubtitleTracks/EffectTracks，In/Out/TimelineIn/TimelineOut，MainTrack，MaxDuration，ClipId/ReferenceClipId，FECanvas
旁白、解说、背景音乐、混音、静音、音量、循环音频、降噪、响度归一化、提取音频	02-multi-track-audio.md	多个 AudioTracks，Volume（Gain），AFade，LoopMode，ADenoise，ALoudNorm，AEqualize
标题、字幕、片尾字幕、滚动文字、样式化 / 气泡文字、字幕背景、字幕动画、持续显示的角落标题、叠加在已擦除的内嵌字幕条带上的文字、改写或翻译后对整条轨道重新计时（重新计算行宽与停留时间、术语表、配音遮盖）	03-subtitles-and-titles.md（§1 位置、§11 重新计时）	Type: "Text"/"Subtitle"，Content，Alignment+X/Y，FontSize，SubtitleEffects，AaiMotion*，Scroll*，AdaptMode，subtitle_localize.py
转场、滤镜、调色、视觉特效、蒙版、Ken Burns、缩放、模糊 / 纯色背景、水印 / Logo、画中画、分屏	04-effects-and-transitions.md	Transition/DLTransition，Filter，VFX，Flip，KenBurns，Zoom，Background，GlobalImage，EffectTracks
将照片制作成视频、图片轮播、幻灯片、照片集、开场 / 结尾标题卡（静帧保持 N 秒）	05-slideshow-template.md	Type: "Image" + Duration，Transition，KenBurns，BGM
将 N 个片段范围组装成剪辑（精彩片段、宣传片、剧集拼接、蒙太奇）；记录每次剪辑的原因；提交前验证 Timeline	18-edl-and-compile.md	compile 子命令，edl.json（sources/ranges/audio/subtitles），BLOCK 与 WARN 检查清单
拼接多个片段、多集串接、裁剪素材、混合素材类型（静帧 + 视频）、横屏转竖屏、贴纸 / GIF 叠加、变速、翻转 / 旋转 / 裁剪 / 定格、批量生成混剪版本	06-multi-clip-editing.md	In/Out/MaxOut，Speed，Flip，Rotate，Crop，FreezeFrame，Clip+RandomClip，AdaptMode
文本转语音、语音识别字幕、卡拉 OK 高亮、为现有镜头中的台词配音 / 重新配音、让改写后的台词适配镜头时长、跟读式旁白、数字人 / 新闻播报、绿幕或真实场景背景移除、SSML	07-smart-media-features.md	AI_TTS，AI_ASR（+AlignmentText，NeedHighlighting），AI_Avatar，AI_Matting，AI_RealMatting，Harmonization，SpeechRate，customizedVoice，逐行微型渲染
输出分辨率 / 比特率 / 编解码器 / 格式、VOD 或 S3 输出、封面图片、完成回调	08-output-and-job-config.md	OutputMediaConfig，EditingProduceConfig，MediaMetadata，UserData.NotifyAddress
选择音色或头像图片；使用提供的克隆 VoiceId	09-voice-and-avatar-catalog.md（接线配置参见 07-smart-media-features.md）	Voice 值（多情感 / CosyVoice / 方言 / 多语言），customizedVoice，AvatarId 值
用户没有用于 TTS / 数字人旁白的脚本	10-narration-script-examples.md	Content 脚本风格（故事解说 / 直播带货）
检查成片、帧采样、质量问题（“输出看起来不对”）、查看某个时刻（接缝是否干净、那句台词是否播完、此处画面内容是什么）、多片段剪辑后的接缝验证	11-output-verification.md（§6 接缝、§7 重新配音后的输出）	frame_qa.py 全片检查、快照采样（--time 以 ms 为单位，--count 1 锁定单个时刻）、帧 QA 的盲区、timeline_view.py（胶片条 + 波形，共用时间轴；--seams edl.json）
剪辑前阅读视频：带时间戳的对白时间线、全片胶片条 / 联系表、指定时刻的帧、用于对齐分析的时间↔像素映射、镜头 / 对白分段作为第二意见	17-snapshot-and-asr.md（§1.6 真实依据——一次音频处理、两次云端处理——+ omni_segment.py，§1.7 归属，§1.8 转录稿是草稿）	asr / snapshot 子命令；EditingConfig.SentenceMaxLength，FrameType: normal，Sprite/WebVtt，--cover，--start-time/--duration
以一种易读视图查看所有分析结果；判断剪辑点可以放在哪里	17-snapshot-and-asr.md §1.5	pack_material.py → material_packed.md（在同一时间轴上显示空白间隔 + 标点 + 静音）
委派片段范围选择；选择剪辑结构（精彩片段 / 拼接 / 演示 / 讲解 / 访谈 / 蒙太奇）	19-editor-brief.md	子 Agent 简报模板、结构类型、时长控制
对单个文件运行一种算法：智能封面、视频摘要、移除 Logo / 台标 / 水印、擦除内嵌字幕、提取字幕为 SRT、绿幕抠像、面部美颜、横屏转竖屏构图、合唱 / 节拍检测、音频质量检查、语音降噪、音频混音、人声 / 伴奏分离	13-intelligent-production.md	iproduction / iproduction-status，FunctionName，Input/Output，JobParams，输出占位符
需要本技能无法计算的内容知识：视频标签、动作事件、人物出镜、关键词时间线、精彩片段候选、说话人归属	§2.4——索取上游结果，切勿猜测	EDL ranges[]（in/out/reason），来自 SRT 的 subtitles[]，通过 17-snapshot-and-asr.md §1.5 对齐接缝
引擎实际计算出的时间线（运行 AI_ASR/AI_TTS/AI_Avatar/VideoDetext 后）；微调已完成的 AI 结果；AI 运行后迭代结构而不重新运行 AI；将剪辑交给 Premiere	21-timeline-export.md	export-timeline / export-timeline-status / decompile（+--inline-srt），ExportType，ProjectId 与 Timeline 的区别，SRT 字幕轨道
创建、生成、检查或渲染可复用的普通模板；TemplateId / ClipsParam；可变媒体槽位；片头 / 片尾或默认水印模板	22-normal-templates.md	template_editor.py generate/create/get/expand/submit，AddTemplate，标量 $Param，ArrayItems / Array
真实任务经验：提交前注册 IMS 存储桶、仅使用 MediaId 的 ASR 输入、STS 与长期 AK 签名 URL 交付、避免截断的拼接规则、无动态效果的外观预设、可填充模板 / ClipsParam 工程	23-production-pitfalls.md	aliyun ice get-storage-list，ASR 输入形式，拼接边距，ClipsParam 槽位
权限错误、RAM 配置	ram-policies.md	ice:*，oss:* 操作
AI 功能（AI_*）仅在部分区域运行——请在 cn-shanghai、cn-beijing 或 cn-hangzhou 提交。

---

4. 素材 URL

• 本地文件 → 通过 oss-upload 技能上传，然后使用返回的 OSS URL。
• 已有 URL → 直接使用。裸 URL 不携带元数据：当 EDL 需要数值型 out（18-edl-and-compile.md）时，用 ffprobe "<url>" 测量——该命令通过 HTTP 流式读取，且不会写入任何内容（硬性规则 1–2）。如果未安装 ffprobe，请说明并询问；不要自行编写 MP4/moov 解析器来替代，猜测时长更不可取。
• 逐字复制每个 URL。 MediaURL/FileURL 必须与用户输入或先前工具输出中的内容逐字符完全一致。绝不要“规范化”对象键——将一个 _ 重打成 -、更改字母大小写或删去末尾数字，都会导致 InvalidMaterial.NotFound: The specified clips url not found。
• 使用 MediaId 而不是 URL（32 位十六进制资产 ID）→ 先运行 media-info（§8）确认文件名、类型、区域和时长（GetMediaInfo 会在 FileInfoList[0].FileBasicInfo.Duration 中返回时长，因此无需运行 ffprobe）。在资产所在区域提交作业（如果该区域不支持 AI 功能，则改用支持 AI 的区域），并优先选择同一区域的输出存储桶。

---

5. 提交前检查清单

以下每条规则都源自真实的失败作业。提交前请检查此列表——违反规则会导致生成作业失败（或悄然产生错误结果）。

现在，此列表中的大部分规则都会通过机械方式检查。 compile 和 submit 都会运行检查：有失败记录的规则会阻止提交，其余规则会警告（18-edl-and-compile.md §3）。ICE 没有服务端 dry-run 端点；Timeline 检查器和普通模板 expand 命令都是本地重新实现，因此可能遗漏新的引擎规则。对于它们无法检查的事项（意图、素材选择、§5-E 参数规范），仍请阅读此列表。

A. 正确的片段类型和放置位置

规则	正确	错误（会失败）
AI 功能以 AI_ 为前缀	AI_ASR、AI_TTS、AI_Matting、AI_RealMatting、AI_Avatar	裸写 ASR / TTS / Matting
AI_Avatar 是 VideoTrackClips 中的片段类型	{"Type":"AI_Avatar","AvatarId":...,"Voice":...,"Content":...}	将它放入另一个片段的 Effects → InvalidTimelineFormat: ... MediaId is empty
抠像是片段 Effects 中的效果	{"Type":"AI_RealMatting"}	使用抠像片段类型，或 SubType: "Matting"
绿幕抠像参数	{"Type":"AI_Matting","Color":"green"}	ColorType / "GreenScreen"
实景（无绿幕）抠像	AI_RealMatting	AI_Matting（边缘效果较差）
镜像/翻转是专用效果	{"Type":"Flip","Direction":"horizontal"}	使用带 hflip/vflip 的 VFX → InvalidTimelineFormat: Invalid vfx subType
字幕文本字段	Content	Text

AI_ASR 有两种有效的放置方式——根据意图选择：

• 放在 VideoTracks/AudioTracks 中某个片段的 Effects 里：{"Type":"AI_ASR","AlignmentText":"...", <style fields>}——字幕由该片段自身的音频驱动，并在同一个作业中渲染。适合旁白/数字人视频的首选一步式模式，也是唯一支持 NeedHighlighting/HighlightingStyle 的放置方式。
• 作为片段放在 SubtitleTracks 中，并将 MediaURL 指向源视频——仅识别现有视频中的语音。

语音转字幕始终使用内置 AI_ASR；不要自行转录音频，也不要手动为合成语音确定 Type: "Text" 片段的时间。

每个脚本只使用一个 AI_Avatar 片段。 将整段旁白放在单个片段的 Content 中——按句拆分会导致数字人每句话都重复开场动作。

B. 音频

• 静音/音量使用 Gain：{"Type":"Volume","Gain":0}（0 = 静音，1 = 原始音量，>1 = 放大，最大 10，建议 ≤3）。在 Volume 效果中使用 {"Volume": 0} 会导致任务失败。
• LoopMode 仅用于音频片段：在 AudioTrackClips 中使用一个片段，设置 LoopMode: true + In/Out + TimelineIn/TimelineOut。要重复播放视频，请使用相邻的副本（或使用模板 ArrayItems 展开），并将最后一个副本修剪至目标时长。
• 同一音轨上的音频片段在时间上不得重叠；要叠加声音，请使用不同音轨。

C. 视觉与效果

• 每个 EffectTrack 只能包含一种效果类型：每个 EffectTracks 条目中的 EffectTrackItems 只能包含一种效果类型。滤镜和 VFX 必须放在不同的 EffectTrack 条目中；混用会导致任务失败。（可以包含多个相同类型的项目。）
• 当时间线上没有实际视频时，GlobalImage 需要显式设置 Duration，否则它只会显示在第一帧。有实际视频时，它会自动覆盖整个输出。
• 按要求让背景铺满屏幕：在背景片段上设置 "Width": 1, "Height": 1（相对于画布）。仅设置 AdaptMode 可能会留下黑边。
• 常规 Transition 会按其 Duration 缩短输出时长（片段会重叠）；使用 DLTransition 可保持总时长不变。

D. 时间线结构

• 至少需要一个视频或音频片段：VideoTracks 和 AudioTracks 不能同时为空——只有字幕的时间线会因 TimelineFormatError: Both video tracks and audio tracks are empty. 而失败。字幕会渲染在其他内容之上，因此无法构建纯文本交付内容；要添加什么由用户决定，而不是由你决定（§2.1）。如果用户没有提到背景，请询问他们想要哪种背景。如果用户明确排除了图像、视频和音频，请说明按当前要求无法实现，并询问他们愿意放宽哪项限制。绝不要为了通过此检查而生成或上传素材——黑色 PNG 或无声 WAV 都会违背用户的明确指示，并在用户的存储桶中留下他们没有要求的对象。
• 索引较高的视频轨道会渲染在索引较低的轨道之上。
• 省略 TimelineIn/TimelineOut 会按数组顺序将片段首尾相接。

E. 参数规范

• **只设置用户要求的参数。**不要为可选的样式/效果参数臆造取值——错误的默认值会悄无声息地破坏预期效果：

  • 蒙版上的 outer_alpha=1.0 会让蒙版看起来毫无作用；blur_intensity=1.0 会模糊整个内部区域。
  • 人物抠像叠加层中的 Width/Height 会缩放人物，破坏“同一个人，不同背景”的效果。
  • 猜测的 Gain 值会悄悄改变混音。

  省略这些字段以使用引擎默认值，或从参考文档中复制经过验证的组合。

• URL 必须原样保留（§4）。

---

6. 最简时间线示例

完整示例、简化示例和时长受控示例见 references/01-timeline-basics.md。**只有单片段时间线或导出的时间线才允许手动编写 Timeline（§7.2）。**如果包含两个或更多片段，请先编写 EDL，然后运行 compile -e edl.json -O timeline.json（§2 第 5 步，18-edl-and-compile.md）。EDL 通常只有几行，编译只需一条离线命令；它也是唯一能以机械方式运行 §5 检查清单的方式——在自己的脚本中导入 validate_timeline / lint_timeline 并不能运行该检查。

---

7. 提交作业

请停下——§2.2 中的计划已经写在你的回复里了吗？ 如果你最后发给用户的是一条命令，而不是描述剪辑内容的段落，就不要运行此命令。compile 和 submit 放在同一批工具调用中，正是本节要防止的失误。

# Submit and wait for completion (--yes skips the script's stdin prompt, not §2.2)
python "$SKILL_DIR/scripts/video_editor.py" submit \
  --timeline timeline.json \
  --output-config output.json \
  --region <region confirmed in §2.1> \
  --wait --yes

--region 为必填项，没有默认值。省略 --wait 可在不轮询的情况下提交；--client-token 可让重试具备幂等性。所有标志：video_editor.py submit --help。

有两种不同的确认，而 --yes 只涵盖其中一种。 不使用 --yes 时，脚本会通过 stdin 提示 Do you want to proceed? [y/N]，并且会在非交互式 Shell 中中止，因此 Agent 基本上总会传入该标志。此标志只会跳过脚本自身关于输出路径、分辨率、区域和覆盖风险的提示。它不能代替 §2.2 的计划确认——任何标志都无法做到这一点，因为 §2.2 发生在对话中，早于此命令的存在。只有当计划已写在你可见的回复中时，才能执行 submit。

OutputMediaConfig：

{
  "MediaURL": "https://{your-bucket}.oss-cn-shanghai.aliyuncs.com/{your-target-video-path}",
  "Width": 1080,
  "Height": 1920
}

如果用户没有指定分辨率，竖屏使用 1080×1920，横屏使用 1920×1080。更多字段（比特率、编解码器、VOD/S3 输出、回调）：08-output-and-job-config.md。

提交后会返回一个 JobId。

7.0 Normal Timeline 模板

如需可复用的剪辑结构，请阅读 references/22-normal-templates.md。在本地生成 Config，向用户展示其固定素材和替换槽位，然后仅在确认后创建持久化模板。渲染不熟悉的模板之前，先通过 get 获取其 ClipsParam 并在本地执行 expand——切勿猜测由控制台生成的数字槽位 ID，并牢记名为 VideoDuration 的槽位只描述它所替换的字段（参见 references/22 §Parameter Rules）。

python "$SKILL_DIR/scripts/template_editor.py" generate --preset video-concat -o template_config.json

现在请停下，并把 Config 展示给用户：其中的固定素材、替换槽位，以及这些槽位所隐含的 ClipsParam 约定。AddTemplate 会创建持久化的云资源，因此这就是 §7 说明中 --yes 无法代替的确认。

python "$SKILL_DIR/scripts/template_editor.py" create --name "Video Concatenation Template" \
  --config template_config.json --region <confirmed region> --yes

模板渲染属于常规生成作业，因此 §2.2 确认、同区域输出存储桶、轮询、§9 验证和最多 3 轮自我修复均适用（references/22-normal-templates.md §Workflow）。

7.1 智能生产作业（单媒体算法）

一个算法、一个输入文件，没有 Timeline。提交前请阅读 references/13-intelligent-production.md——14 个函数名称、对应的 JobParams、必需的输出占位符以及结果结构都无法靠猜测得知。

# Smart cover images from a media asset into OSS
python "$SKILL_DIR/scripts/video_editor.py" iproduction \
  --function Cover --input <mediaId-or-oss://bucket/object> \
  --output 'oss://<bucket>/covers/{source}-{sequenceId}.png' \
  --job-params '{"Model":""}' \
  --region <region confirmed in §2.1> --wait --yes

# Poll / re-read a job
python "$SKILL_DIR/scripts/video_editor.py" iproduction-status --job-id <job_id> --region <region>

• SubmitIProductionJob 没有 ClientToken——盲目重试会产生第二笔作业费用。重新提交前先查询。
• 输入存储桶、输出存储桶、媒体资源和作业必须全部位于同一区域。
• 全部 14 个函数都是 AI 功能：仅支持 cn-shanghai / cn-beijing / cn-hangzhou。在其他任何区域——cn-shenzhen、cn-zhangjiakou、ap-southeast-1——都会导致 iproduction 在本地返回 ValidationError 并失败，不会调用 API；服务本身只会返回 InvalidParameter.FunctionNotSupported。此请求到此为止：返回 §2.1，询问用户要使用哪个区域以及同区域的存储桶，绝不要擅自替换。
• 按照时间线作业的方式准确验证结果（§9）——无论是否实际进行了更改，擦除或美颜作业都会报告 Success。

7.2 项目导出 — AI 扩展后的 Timeline

你提交的 Timeline 中包含 AI 声明（AI_ASR、AI_TTS、AI_Avatar、VideoDetext）；真实地址和时间信息只有在引擎运行后才会生成。用户想要计算后的 Timeline 时，请将其导出 — references/21-timeline-export.md 中列出了命令和标志。

python "$SKILL_DIR/scripts/video_editor.py" export-timeline \
  --project-id <ProjectId from GetMediaProducingJob> \
  --bucket <scratch bucket, same region> --prefix export/ep01 \
  --region <region confirmed in §2.1> --output timeline_expanded.json --wait --yes

传入 ProjectId，不要传入 Timeline — ProjectId 会展开已经完成的渲染，而未渲染的 Timeline 会让导出操作运行并计费其 AI 任务。这个 Timeline 可以手动编辑（§11 的例外），因为它背后没有 EDL；不过，将其反编译（decompile）回 EDL 会更好：与其他所有内容使用相同的流程，离线完成，而且绝不会重新运行 AI。

---

8. 轮询并报告

# Query once (region = the region the job was submitted in)
python "$SKILL_DIR/scripts/video_editor.py" status --job-id <job_id> --region <region>

# Wait for completion
python "$SKILL_DIR/scripts/video_editor.py" status --job-id <job_id> --region <region> --wait
# Add --details to print the submitted ClipsParam and Timeline when diagnosing a template render.

# Resolve a MediaId to a signed (authenticated) URL and media details (region = the asset's region)
python "$SKILL_DIR/scripts/video_editor.py" media-info --media-id <media_id> --region <region>

# Verified V4 signed URL for private-bucket hand-off (supports AK and STS)
zsh "$SKILL_DIR/scripts/oss_sign_clean.sh" oss://<bucket>/<object> [ttl-seconds] [region-or-endpoint]

状态值：Init、Queuing、Processing = 仍在运行；Success = 已完成；Failed = 查看消息以了解原因。

状态为 Success 时，status 会打印任务的 MediaId、MediaURL 和时长。使用该 MediaId 运行 media-info，即可获得签名 URL — 输出存储桶通常是私有的，因此无法查看普通的 OSS URL。

两个 URL，两种用途。 media-info 的 URL 是给你现在使用的：它大约一小时后过期，而且有些 STS 签名 URL 根本无法获取 — 用于即将进行的 §9 检查没问题，但不适合用户之后打开。你交付的链接来自 oss_sign_clean.sh：它使用 V4 签名，携带 STS 令牌，限定区域范围，并在打印前经 curl 验证。验证失败的链接不能交付（23-production-pitfalls.md §3）。如果签名工具本身失败，请如实说明，提供标注为短时有效且未经验证的 media-info URL，并给出重新签名的命令 — 绝不要让原始 URL 冒充已验证的链接。

这个 URL 就是交付物 — 但还不是答案。 只有完成 §9 后，才能将它交给用户。media-info 返回时长和分辨率，这些只是元数据，不是验证：它无法判断 BGM 是静音还是已混音。请将其报告为播放链接，并注明有效期及重新签名的一行命令；绝不要把成品视频下载到用户的机器上（硬性规则 1）。只有用户明确要求时，才获取本地副本。

---

9. 验证输出

Success 只表示文件已写入。素材错误、黑帧、字幕被裁切和音频无声，都可能显示 Success。报告任何交付物前都必须先验证。 完整指南：references/11-output-verification.md。

按顺序选择第一个可用路径：

顺序	路径	命令	所需条件
1	云端快照帧，由你读取（首选）	video_editor.py snapshot --mode normal -i <output MediaId or oss:// object> -r <region> --time <ms> --count 12 --interval 5 -O "oss://<bucket>/qa/f-{Count}.jpg" --wait，然后运行 snapshot-urls 获取签名链接	AK/SK + 输出存储桶
2	完整视频 + 模型	frame_qa.py --video "<signed URL>" --mode full	DASHSCOPE_API_KEY
3	覆盖完整输出的云端胶片条	video_editor.py snapshot --mode webvtt --cover <duration> → 读取精灵图块（见下文 §9 接缝检查）	AK/SK + 输出存储桶

优先使用帧 — 无论时长如何，成本都保持稳定（89 MB / 78 s 的视频 → 约 500 KB 的 JPEG，约 3-5k 个令牌），而完整视频审查会将每一秒都转换为令牌。短转场需要比 5 s 间隔更密集的采样：--interval 的单位是秒，只会调整单个任务内部的帧间距；--time 的单位是毫秒，因此每个时刻都需要单独的任务（--time <ms> --count 1）— 检查可疑接缝前后 ±0.1 s 和 ±0.2 s，需要运行四个单帧任务（11-output-verification.md §6）。frame_qa.py 只审查云端素材（--video <signed URL>，或通过 --frames 传入签名帧 URL），绝不会下载任何内容（硬性规则 1–2）。 没有 DASHSCOPE_API_KEY？ 不要跳过验证，也不要因缺少密钥而停下。路径 1 和路径 3 完全不需要密钥——使用支持 URL 的视觉／浏览器工具检查带签名的帧 URL。不要把 HTTP URL 传给要求本地绝对路径的文件读取器；如有必要，用 curl 将帧下载到临时目录，再检查该文件。你很可能是多模态模型，所以请用自己的视觉能力进行审核。只需提醒用户查看 §1.3 一次，然后继续。视觉能力是仅适用于图片问题的免密钥路径——以音频为主的交付内容应走下方的 ffmpeg 音频检查路径，而不是检查帧。无法自行读取图片？ 那么密钥就不可或缺：将同一批带签名的帧 URL 交给模型（frame_qa.py --frames "<url>" …），并将其发现报告为模型审核结果，而不是你自己的审核结果。只有在既没有视觉能力也没有密钥时，才将输出报告为未经验证，并说明原因。

用户放弃验证（“别检查了”／“just send the URL”）？ 尊重用户的决定——这是他们的选择，而且路径 1 会占用一个任务和一分钟，他们可能不想花这份时间。但放弃验证只代表不运行检查，不代表可以不报告：提供 URL 时标注为未经验证，明确说明 Success 只能证明已写入字节，指出应用户要求跳过了哪些检查（帧、音频尾部、渲染时长是否符合预期），并给出运行这些检查的那条命令（上面的路径 1 snapshot），这样用户改变主意时只需十秒。回复绝不能让人误以为交付内容已通过验证（硬规则 5）。

当交付内容的价值在于音频或动作时，升级到 --mode full——例如 TTS 旁白、AI_Avatar 对嘴、BGM 混音、KenBurns/Scroll* 动画。抽帧无法听到音频，也无法看出音画同步或卡顿。对于以旁白为主的输出，请比较渲染时长与预期旁白时长；渲染时长更短会截断旁白，而无法解释的时长过长可能会留下黑屏／静音尾段。即使任务显示 Success，这两种时长不匹配也都意味着交付失败。时长短于扫描间隔的转场并非无法检查——可对该转场执行单帧任务——但每个时刻都要占用一个任务，因此应先扫描，再仅对看起来有问题的部分进行精确检查。

--mode full 需要密钥。以音频为主的交付内容仍有一条免密钥路径：将 ffmpeg 指向带签名的输出 URL，读取信号，而不是画面。 这是分析，不属于硬规则 2 禁止的本地混音／渲染操作——它会流式读取，唯一写入的文件是临时目录中的分析产物（§1.4）。对输出运行 volumedetect 或 astats，即可确认混音底床是否达到要求的音量、源音频是否保留，以及尾部是否过早变为静音。既没有密钥也没有 ffmpeg 时，请将音频标记为未经验证，并指出缺少哪一项——抽帧无法替代音频检查，因为无论 BGM 音量是 20% 还是静音，画面看起来都一样。

多区间剪辑还需要专门检查剪辑接缝（确认每处剪切后对白都完整；如果要求添加水印，确认水印已放置且未被剪断）——见 11-output-verification.md §6。模型质检很少能发现被截断的台词。用于此项检查的工具是 timeline_view.py --seams edl.json：每个接缝生成一张图，展示接缝两侧的胶片带和共享时间轴上的音频波形。这样的组合能发现最常见的问题——音频台词延续到了画面剪切之后——单帧无法显示这一点，因为剪切处的画面只是一张脸。 普通的整文件拼接无需源帧。素材身份已通过两次验证：URL 原样复制（§4），而且 ICE 无法解析素材时会明确报错 InvalidMaterial.NotFound。在片头、接缝和片尾截取输出，并将渲染时长与源素材时长总和进行比较——这能发现文件丢失、顺序交换和黑场接缝。将输出帧与源快照逐像素匹配，只是为了回答 Timeline 已经确定的问题，却要为每个锚点支付一次任务费用。只有在编辑对素材进行了变换——裁剪、遮罩、擦除、变速——且需要查看素材原始状态时，才购买源帧。

非视频 IProduction 交付物（§7.1）不适用于 frame_qa.py：读取提取出的 SRT，对照源素材检查时间和文本；读取检测 JSON / Result，根据媒体时长检查范围是否合理；对于音频输出，使用 --mode full，该模式会监听。视频输出（擦除、美颜、H→V、抠像）走上述常规路径——在本应发生变化的区域采样帧。

9.1 自我修复循环——最多 3 轮

验证不是一份交给用户的报告，而是要先完成的闭环：

1. 验证。如果全部通过，就交付成果。
2. 如果有任何项目未通过，就修复真实依据——EDL，或者普通模板渲染的模板 Config/ClipsParam——然后重新编译/展开、重新提交并再次验证。改变假设，而不只是参数类型。
3. 3 轮后停止。如果问题仍然存在，将结果标记为未交付，指出尚未解决的缺陷并附上证据；绝不能把无法解释的不匹配说成“模板行为”或已完成的结果。

对未通过的项目重新验证，并使用比发现问题时更高的分辨率：以 1 fps 标记的接缝，应使用 4–8 fps 的字幕带条带进行检查（11-output-verification.md §6），而不是再进行一次 1 fps 扫描。只有之前未通过的检查通过后，才能声称缺陷已修复。

不要向用户展示未经验证的预览。如果你不会交付，就不要展示。

然后报告：实际提交的 Timeline（总结多阶段流水线；当结果取决于轨道的挂载方式时——例如从提取的 SRT 得到的字幕轨道、配音轨道、水印/效果图层——说明具体挂载方式，例如 SubtitleTracks[].FileURL → SRT 对象，而不只是 JobId）；输出信息（bucket / 对象路径 / 区域 / MediaId / 时长 / 分辨率 / JobId）；签名观看 URL（注明其有效期）；使用了哪种验证路径、验证结果以及无法检查的内容；以及进行了多少轮自我修复。

---

10. 错误 → 修复

在 references/25-error-index.md 中查找错误消息：每一行都列出原因、最简修复方法以及说明该问题的章节。报告 Success 却仍然破坏交付物的失败情况见 §11。

---

11. 反模式

references/25-error-index.md 列出了会明确报错的情况。以下情况会返回 Success，却仍然生成有问题的交付物——或浪费一次往返。这些情况都已经付过一次代价。

流程

• 在计划确认前就开始编辑。 渲染需要花钱；写一段文字不需要（§2.2）。常见做法是在同一轮中直接从 compile 执行到 submit --yes，还把内部任务列表误当成用户已经看过的计划（§2.2「什么才算确认」）。
• 把没看过的输出说成已经检查过。 Success 只表示字节已写入（§9）。常见做法是执行 status → media-info →「输出已验证」：时长和分辨率只是元数据；对于音频交付物，它们并不能说明混音情况（§8、§9）。如果用户免除了检查，就如实说明并将交付物标记为未经验证——免除检查只让他们跳过检查，不代表交付物已通过检查（§9）。
• 同一缺陷反复处理超过 3 轮。 明确指出缺陷并交接处理（§9.1）。
• 验证失败后手动修补 Timeline。 这会偏离生成它的决策，导致下一轮无从推理——应修复 EDL（18-edl-and-compile.md §5）。唯一例外是已导出的 Timeline（§7.2）：AI 扩展没有对应的 EDL，因此直接编辑它是微调结果的唯一方法。
• 微调已提交的时间线，而不是实际计算出的时间线。 其中的 AI_* 条目只是占位符——里面没有对齐器生成的句子边界和实际时长。请先导出（§7.2）。
• 对未更改的源素材重新运行分析。 ASR 和快照输出是不可变输入的不可变函数；应缓存这些结果（§2.3）。
• 下载媒体进行查看，或将工作文件写入用户的项目。 使用流式传输、生成快照，并将临时文件保存在临时目录中（硬性规则 1）。成片也一样：交付物是播放 URL（§8），不是用户磁盘上的文件。
• project.md 已记录区域和存储桶时，还再次询问用户（§2.3）。
• 探测区域以发现本文档已说明的限制，然后自行迁移作业。 在 cn-shenzhen 中调用 3 次 InvalidParameter.FunctionNotSupported 并未发现 §7.1 未说明的内容；之后切换到 cn-shanghai 和另一个存储桶，则替用户做出了两个他们未要求的决定。遇到首次拒绝时就停下并询问用户（§2.1）。

阅读素材

• 在快照作业中使用 FrameType: intra。 这会在不提示的情况下只交付 ⅓ 的帧，但仍报告 Success（17-snapshot-and-asr.md §2.2）。
• 因为响应示例中出现过某个未文档化的 API 字段，就信任该字段。 SubmitASRJob 会接受并忽略这些字段，且不报错（17-snapshot-and-asr.md §1.3）。
• 根据请求参数计算胶片条的图块坐标。 服务端会改写坐标；应读取 VTT（17-snapshot-and-asr.md §2.3）。
• 臆造本应由上游提供的内容知识。 高光候选项、标签和说话人归属都作为数据提供（§2.4）；猜测时间段等于用抛硬币的方式决定是否付费渲染。应请求上游结果，并使用 SubmitASRJob 获取对话时间线。
• 使用 qwen-omni-turbo 获取时间戳。 即使是 40 秒的片段，也会出现量化和幻觉问题（17-snapshot-and-asr.md §1.6）。

剪辑

• 仅凭静音间隔判断句子边界。 实测发现，符合间隔要求的候选项中有 2 个（共 16 个）位于句子中间。必须同时满足句末标点和间隔 ≥ 0.3 秒（17-snapshot-and-asr.md §1.5）。
• 在视觉场景切换处设置 Out。 对话音频经常会延续到切点之后；应以音频尾部为准（18-edl-and-compile.md §1.5）。
• 为达到目标时长而在对话块内部裁剪。 应改为删除整个对话块（18-edl-and-compile.md §1.5）。
• “高光”保留了大部分源素材。 将 79 秒剪至 66 秒的方案被拒绝；30 秒的方案通过。默认控制在原片的 30–40 %（19-editor-brief.md §4）。
• 将“尽可能长”作为时长选项。 最长选项不得超过原片的一半。

合成

• 本地使用 ffmpeg 渲染以省去一次往返——将片段 concat，用 -filter_complex 叠加画面，烧录字幕，用 atempo 调整配音速度。这会生成一份 ICE 从未产出的交付文件，因此下游无法复现或重新编辑，而且明确禁止（硬性规则 2）。请修复 EDL 或 Timeline 并重新提交；如果 ICE 作业无法表达该剪辑，请改为报告这一情况。
• 擅自添加用户未要求的可选参数。 错误的默认值会悄无声息地破坏预期结果——outer_alpha=1.0 会让蒙版看起来形同虚设；对已抠像的人物设置 Width/Height 会将其缩放（§5-E）。
• 在 Text 片段上设置 X/Y。 其语义不可靠；请只使用 Alignment，并检查一个画面帧（03-subtitles-and-titles.md）。
• 添加用户未要求的水印。 默认关闭（§2.2）。
• 在多范围剪辑中添加转场。 转场会模糊画面并吞掉句尾；除非用户要求，否则使用硬切（18-edl-and-compile.md §1.5）。
• 将 AI_Avatar 脚本拆分到多个片段中。 虚拟形象会在每个句子开头重复做开场动作（§5-A）。
• 手动调整 Text 片段的时间，使其匹配合成语音。 使用带有 AlignmentText 的 AI_ASR，让引擎进行对齐（§5-A）。
• 将 HighlightingStyle.FontColor 设置为 RGB 十六进制值。 它使用的是 BGR 字节顺序，且不带 # 前缀——这与同一片段中常规的 FontColor/OutlineColour 字段（#RRGGBB）正好相反。"00FFFF" 会渲染成 黄色；"FFFF00" 会渲染成青色；"#FFFF00" 会渲染成黑色（解析失败）。务必检查采样帧中的颜色（07-smart-media-features.md）。
• 将源字幕的时间用于翻译轨道。 西班牙语/德语的时长比英语长 10–30 %；源字幕的提示时长会导致译文溢出画面，或一闪而过、来不及读完。请按语言重新计算换行和停留时长，并延长每条字幕，使其覆盖对应的配音（03-subtitles-and-titles.md §11）。
• 将加快配音作为解决台词过长的第一步。 处理顺序应为：改写译文 → 提高 SpeechRate → 在 ICE 重新渲染中调整音频片段的 Speed（上限约为 1.5）——绝不可使用本地 atempo（硬性规则 2）。将一条 34 个字符的台词改写为 21 个字符后，便能以自然语速适配 2 s 的镜头；加速版本因语速过急而被否决（07-smart-media-features.md）。也绝不要为了适配音频而改变画面速度。
• 未检查配音时长，就相信对其进行的 ASR 识别结果。 识别可能会把被截断的录音幻觉成完整句子，也可能在较短的时间窗口内臆造词语——这会掩盖你正在检查的问题。先测量音频，再读取识别结果（11-output-verification.md §7）。
• 将提供的 VoiceId 用于错误说话人的台词，或尝试自行训练语音。 归属判定依据是画面中正在动嘴的人，而不是对音色的猜测（17-snapshot-and-asr.md §1.7）；克隆语音是用户提供的输入（§2.4），绝不是此技能会提交的作业（07-smart-media-features.md）。

12. 文件映射

路径	用途
scripts/requirements.txt	Python 依赖项
related_apis.yaml	依赖的阿里云 API
references/manifest.json	Skill 名称 + 版本——UA skill-version/ 来源，在首次云端调用前读取（§1.5）
scripts/video_editor.py	执行器：compile（离线 EDL → Timeline + 检查清单）/ submit / status / media-info / asr / asr-status / snapshot / snapshot-urls / iproduction / iproduction-status / export-timeline / export-timeline-status / decompile（离线展开后的 Timeline → EDL）
scripts/template_editor.py	普通模板执行器：离线通用 Config 预设，以及本地 expand / AddTemplate / GetTemplate / TemplateId + ClipsParam 生成任务
scripts/frame_qa.py	仅审查云端素材的模型：完整视频（--video，§9）或签名快照帧 URL（--frames）——不会在本地采样（硬性规则 1–2）
scripts/pack_material.py	将 ASR + WebVTT + silencedetect 合并到 material_packed.md——统一时间轴、剪辑标记、缓存
scripts/timeline_view.py	在共享时间轴上显示胶片条 + 音频波形；使用 --seams edl.json 进行逐剪辑点验证
scripts/omni_segment.py	qwen3.5-omni-plus 镜头/对白分段——对 ASR 转录文本进行第二次核验（17-snapshot-and-asr.md §1.6）
scripts/oss_sign_clean.sh	用于私有存储桶交接的已验证 OSS V4 签名 URL；支持 AK 和 STS（§8）
scripts/subtitle_localize.py	本地化提示生成器：换行 + 重新计算停留时间 + 词汇表断言 + SRT，并强制要求 sub_end ⊇ 实测配音时长（03-subtitles-and-titles.md §11）
references/	能力知识库（§3 路由）、25-error-index.md、ram-policies.md
evals/scenarios/	评估场景