动画操作手册

视频说明书

将产品截图转化为带字幕的简短导览视频：动画光标在屏幕间点击，高亮和缩放引导注意力，动画文字解释每一步。

工作分为四个步骤。用户决定，您执行。

步骤	用户	您
1. 产品项目	说明目标用户、设置品牌色、背景模板、logo、品牌指南	推导语言规则和调整动效
2. 场景	上传截图或 Figma 链接	导入 Figma 帧
3. 故事板草稿	确定关键屏幕、顺序和文本	起草供用户编辑
4. 视频	观看、编辑文本和顺序、评论帧	添加动作、检查每帧、根据评论修改、渲染

措辞和顺序是用户最关心的，因此在步骤 3 中确定，在所有制作工作之前，并在步骤 4 中保持可编辑性，直至 MP4 渲染完成。

使用用户的语言与其交流。除非另有说明，否则以产品 UI 的语言编写字幕。

两种工作方式

使用 Studio（默认）。 一个本地 Web 应用展示四个步骤。用户在此工作；标有 ✦ 的按钮会将请求排队，您处理、完成并回复。在启动之前，请先阅读 references/studio.md——这是该循环的协议。

仅通过对话。 当用户不想打开浏览器，或者您无法运行本地服务器时，通过提问和展示在对话中完成相同的四个步骤。请参阅下方的“不使用 Studio”。

无论哪种方式，文件都是相同的，因此项目可以在两者之间转移。

项目结构

所有内容均位于用户项目的 video-manual/ 下，这样每个产品的所有说明书共享一个配置文件：

video-manual/
├── product-profile.json     # 每个产品一个：受众、语言、动效、背景
├── brand/                   # guide.md（粘贴的品牌指南）、logo
├── requests.json            # 从 Studio 排队的请求
└── <manual-slug>/           # 每个视频一个文件夹，例如 create-task/
    ├── screens/             # 01-board.png, 02-new-task.png, ...
    ├── storyboard.json      # 先是草稿，然后是完整故事板
    ├── comments.json        # 来自 Studio 的帧评论
    └── out/                 # manual.html, manual.mp4, stills/, frames/

设置

脚本位于此技能的 scripts/ 文件夹中。渲染需要一次性安装依赖：

cd <skill-dir>/scripts && npm install

然后在后台启动 Studio 并给用户地址：

node <skill-dir>/scripts/studio.mjs video-manual --open

用一句话告诉用户接下来会发生什么：他们将填写步骤 1，而您将处理他们通过 ✦ 按钮发送的任何内容。然后按照 references/studio.md 的描述等待请求。

步骤 1 — 产品项目

如果 video-manual/product-profile.json 中已有 voice 块，则表示产品已设置：直接使用。产品内视频的一致性比单独调整每个视频更重要。

否则，用户填写表单（名称、领域、B2C/B2B、目标年龄、设备、强调色、背景模板、可选的 logo 和品牌指南）并发送 profile 请求。然后：

1. 读取 product 块和 brand/guide.md。
2. 编写 voice 块——语域、句子结尾、最长字幕、应避免的词、产品术语。阅读 references/voice-guide.md。用户的品牌指南优先于其一般建议。
3. 为相同受众调整动效。阅读 references/motion-profiles.md。用户选择了预设和背景；您根据受众需求调整节奏、大小和缓动。
4. 添加一到两句话的说明。

这三个事实——目标年龄、领域、B2C 或 B2B——决定了每条字幕。如果表单留空或屏幕与其矛盾，在编写语言规则之前请先询问。

步骤 2 — 场景

每个不同的屏幕状态对应一张图片，放在 screens/ 中，按出现顺序编号。状态发生可见变化（模态框打开、下拉菜单展开、表单填写）时，需要单独的图片：视频通过切换到下一张截图来显示点击的结果。

用户通常在 Studio 中上传这些。如果收到带有 Figma 链接的 scenes 请求，将每帧导出为 PNG 并记录其逻辑宽度作为 coordWidth；同时读取图层元数据——精确的元素边界比从像素估算可靠得多。

如果导览所需的状态缺失，请指出哪个状态并要求提供，而不是跳过该步骤。用户无法跟随的跳跃会破坏说明书的目的。

步骤 3 — 故事板草稿

收到 draft 请求后，读取每张屏幕和配置文件，然后将草稿写入 storyboard.json：按顺序排列的场景，每个场景包含 caption 和描述该场景上发生的事情的 note。尚无动作。阅读 references/manual-script.md 了解如何定位视频和编写文本，并以配置文件中的语言风格编写每一行。

用户在 Studio 中编辑草稿，并在措辞和顺序正确时按下“请求视频”按钮。该 produce 请求即为批准。在收到之前不要添加动作。

步骤 4 — 视频

制作

阅读 references/storyboard-schema.md 并将批准的草稿转化为完整故事板：遵循每个场景的 note，添加动作，设置 coordWidth。字幕与批准时完全相同。

坐标是最可能出错的部分。有确切边界时（Figma 元数据、DOM 矩形）使用它们。只有图像时，仔细观察并估算；下面的检查用于发现您的错误。

在用户看到之前检查

构建，然后渲染静态图——每次点击、文本和字幕变化时以及每个场景结束时各一帧：

node <skill-dir>/scripts/build.mjs video-manual/<slug>/storyboard.json
node <skill-dir>/scripts/render.mjs video-manual/<slug>/out/manual.html --stills video-manual/<slug>/out/stills

build.mjs 验证故事板，检查每条字幕是否符合配置文件的语言规则，并打印每个场景的时间。修复错误。对于用户编写的文本的语言警告，保留其措辞，并在回复中提及警告。

阅读静态图并检查每一帧：

• 光标尖端是否指向字幕所命名的元素？
• 高亮环是否完全包围整个元素且不包含其他内容？
• 缩放后，目标是否完全可见且可读？
• 输入文本是否位于其字段内并覆盖占位符？
• 每条字幕是否完全可见，且最多两行？
• 每个标注是否指向正确的元素，且不覆盖该元素或光标？

纠正故事板，重新构建并重新渲染，直到每帧都通过，然后回答请求。点击按钮旁的光标会让整个说明书看起来错误，因此用户绝不应该发现这一点。

审查循环

在 Studio 的步骤 4 中，用户可以：

• 编辑任何字幕、标题或屏幕内文本并重新排列场景——直接保存到 storyboard.json，无需请求；
• 暂停在一帧上，固定位置并编写评论，然后将评论作为 revise 请求发送。

按照 references/studio.md 的描述处理 revise：渲染被评论的帧以查看用户所见内容，仅更改评论所指的部分，在新帧上确认已修复，然后回复每条评论。在用户重新排列场景后，检查每次点击是否仍指向后续屏幕；断链是需要告知用户的事情，而不是默默修复。

此循环重复，直到用户满意为止。

渲染

用户通过 Studio 中的一个按钮导出 MP4。要自行渲染：

node <skill-dir>/scripts/render.mjs video-manual/<slug>/out/manual.html --out video-manual/<slug>/out/manual.mp4

渲染时间大约与视频本身一样长，在较慢的机器上可能需要两到三倍时间；对于超过一分钟的说明书，在后台运行。报告输出路径、时长和文件大小。

不使用 Studio

在对话中完成相同的四个步骤：

1. 项目——根据屏幕和 UI 文本推断目标年龄、领域和 B2C/B2B，陈述您的理解并请用户用一个问题确认。然后自行编写完整的配置文件，包括预设、强调色和背景。
2. 场景——将用户提供的图像复制到 screens/ 中，或者如果您有浏览器或 Figma 工具，则自行捕获。
3. 草稿——编写草稿故事板，以表格形式展示（步骤、屏幕、发生的事情、字幕、屏幕内文本），并附上估计时长，等待批准。如果他们一开始就说直接进行，则继续并说明草稿位置。
4. 视频——按上述方法制作和检查，然后告诉他们 out/manual.html 的位置。该独立页面播放视频，并有自己的面板用于编辑文本和顺序；“下载编辑内容”会生成一个 storyboard.edited.json，他们可以交回。当他们交回时，列出更改内容，以便他们确认您理解其意图，将其保存为 storyboard.json，重新构建并重新检查静态图。然后渲染。

后续更改

• 措辞或顺序：用户在 Studio 中编辑，或告知您。
• 语言风格（“太生硬”、“我们的用户更年长”）：更改配置文件中的 voice 块，然后重写字幕。
• 感觉（“太慢”、“太弹”）：更改配置文件中的动效标记，而不是单个场景——参见 references/motion-profiles.md 中的调整表。
• 某个步骤看起来不对：修复该场景的动作并重新检查其静态图。

任何更改后，在再次渲染之前，重新构建并重新检查静态图。

限制

当请求遇到以下情况时，明确说明：

• 屏幕是静态图像。不重现滚动、悬停状态和应用内动画；将其作为单独的截图展示。
• 没有旁白或音乐。字幕和屏幕内文本承载解释。
• Studio 编辑文本和场景顺序。步骤点击或高亮的内容通过向您的评论进行更改。
• 默认输出为 16:9。在故事板中设置 meta.width 和 meta.height 以使用其他形状。

故障排除

• playwright-core is not installed：在脚本文件夹中运行 npm install。
• no browser found：安装 Google Chrome，或在脚本文件夹中运行 npx playwright install chromium。
• ffmpeg not found：安装 ffmpeg 或设置 FFMPEG_PATH。npm install 通常通过 ffmpeg-static 提供一个。
• Studio 中请求保持“等待”状态：没有人运行 studio.mjs wait。运行它，或运行 studio.mjs pending。
• 步骤 4 显示错误而不是视频：场景指向缺失的图像或坐标超出屏幕。build.mjs 会指出场景。
• 字体看起来不对：视频使用机器上安装的字体。在配置文件中将 font.family 设置为已安装的字体。