framejam

FrameJam：风格、作战手册 + 一键视频和分镜审阅

技能版本：5

FrameJam 会在 http://localhost:2400 与你的聊天并排运行。它能提供三样聊天不擅长的东西： 选择风格（描述视觉效果的结构化 style.json，以及示例视频）、遵循作战手册 （针对某类视频的完整方法：用户需要提供什么、操作步骤、使用哪些工具、质量标准）以及精准反馈 （带时间戳和固定位置的评论，并附上渲染视频的帧图）。

FrameJam 可配合任何视频制作工具使用。用户审阅的是渲染后的视频（videoPath），因此他们看到的内容与你渲染的完全一致。选择合适的工具即可：项目自带的工具，或你通常会使用的工具 （Hyperframes、Remotion、Motion Canvas、ffmpeg……）。

FrameJam 是一套工具包，不是一套流程。按照用户的要求行事，采用合理的默认设置，并在有帮助时使用这些工具。不要擅自增加用户未要求的步骤、问题或审批。

与用户交流时使用的说法： FrameJam 将每次审阅称为一个项目（起始页名为“Projects”）。请说“我已在 FrameJam 中打开该项目”，不要说“我已打开一个审阅”。工具和字段名称（open_review、reviewId）保持原样。

0. 在内置浏览器中打开 FrameJam（始终先执行此操作）

使用此技能后，立即打开 FrameJam，让用户能够看到，无需征求同意：

• **Cursor：**使用内置浏览器工具（cursor-ide-browser → browser_navigate），并设置 position: "side"，让它在聊天旁边打开。
• **其他运行环境：**如果有浏览器或预览工具，请使用；否则将链接提供给用户。
• **打开哪个页面：**如果项目有 url，则打开该页面；如果你打开了选择页，则打开选择页；否则打开 http://localhost:2400（Projects）。
• 如果页面无法加载，说明 UI 尚未启动。运行 npx -y framejam start（它会在后台启动 UI，或复用正在运行的实例，并打印 URL），然后打开该 URL。绝不要让用户启动它。
• 如果 FrameJam 工具本身不可用，请运行 npx -y framejam install <app>，其中 <app> 是你正在使用的应用 （cursor、claude 或 codex）。此命令会添加 MCP 服务和技能（或确认它们已存在），并启动 UI。打开它打印的链接，然后告知用户它打印的最后一步（重启应用一次以加载工具）。

1. 按照用户的要求行事

立即处理用户的请求，采用合理的默认设置（时长、格式、工具、风格）；只有在无法推断时才提问，例如剪辑所需的素材。请求较简短时，可以使用以下快捷方式：

• **/framejam playbook 或 /framejam style：**仅打开对应的选择器（open_picker({ kinds: ["playbook"] }) 或 ["style"]），参见循环步骤 0。
• **继续制作：**如果你在此聊天中一直在制作视频，请将下一版渲染到同一项目中 （使用其 reviewId 调用 add_version，或使用相同的 title 调用 open_review）。
• 有待处理的反馈：list_reviews() 会显示所有项目。如果某个项目状态为 sent_not_delivered 或 user_commenting，请调用 get_feedback({ reviewId }) 并应用反馈。如果状态为 awaiting_user，请打开其 url 并调用 wait_for_feedback。
• 此文件夹中已有视频（渲染文件，或 Hyperframes、Remotion 或 Motion Canvas 项目），且用户想要审阅：将最新渲染作为项目打开。
• **仅输入 /framejam，没有其他说明：**用一句话询问视频要讲什么。

工作循环

0. 选择（仅在用户要求时）。 如果用户指定了操作手册或风格，请使用它（get_playbook(id) / get_preset(id)）。 仅在用户要求选择时（/framejam playbook、/framejam style、“让我选一种风格”），或请求开放得无法直接着手时，才打开选择页面。否则直接构建。
   • 调用 open_picker({ title, kinds })（kinds 默认包含两者），在内置浏览器中打开返回的 url， 在聊天中将其作为可点击链接发出，然后调用 wait_for_pick({ pickId })。如果返回 pending，就再次调用； 如果连续 6 次返回 pending，则改为在聊天中询问。
   • 选项确定后，用一行说明你将使用什么（“将使用 Clean Cut 操作手册，不使用风格”），并附上它们页面的链接。
   • null 操作手册或风格表示用户选择了不使用。将 playbookId 和 styleId 传给 open_review，以便后续版本保留它们；现有项目会通过 get_feedback 和 wait_for_feedback 返回这两个值。
1. 遵循操作手册和风格。
   • 操作手册： 其中的 skill 是制作此类视频的配方，用户请求中的设置优先于默认设置。每次渲染都使用下面的循环。如果方法要求读取 playbookDir 中的文件，就读取这些文件，并在使用操作手册中的脚本、引擎或模板前将其复制到项目中；绝不要编辑 playbookDir。stylesSentence 说明风格如何与操作手册结合。有些操作手册会列出为其定制的风格（featuredStyles）；如果选中的风格属于其中之一，就调用 get_playbook({ id, styleId })，并按照操作手册的 skill 所述使用 styleForThisPlaybook.settings，因为这些设置与其示例视频相匹配。
   • 风格是一种视觉呈现，而不是起始视频。 首先根据用户的要求规划视频内容（火箭发射的重点是火箭），然后使用风格的视觉语言来构建该主题：按照 guide 所述运用其 palette、纹理和背景、fonts、easing、transitions、textAnimations 及节奏。将其视为有力的起点，而非死板规则：根据主题或用户请求灵活调整。
   • example 说明风格预览视频展示的内容。不要重复使用其中的场景（主题、道具、布局或故事，例如 Cyanotype Mac 中的电脑），除非用户要求。
   • templateDir 中的示例构图只是参考，不是骨架。不要复制它再替换文字。仅在查看某种技法的实现方式时（例如纹理滤镜或标题显现效果），才打开 templateFiles 中的文件（或调用 get_preset({ id, includeTemplate: true })），并在自己的构图中重新制作该技法。
2. 构建视频，使用项目指定的工具（Hyperframes 的详情见下文，其他工具见更后面的说明）。
3. 渲染到每个版本各自的新文件，例如 renders/v1.mp4、renders/v2.mp4，以便比较先前的版本。 先自行检查： 打开评审前，使用你能自行进行的任何方式检查渲染结果是否符合请求（以及操作手册规定的质量标准，如有），并修复发现的问题。
4. 打开评审： open_review({ title, videoPath: "<abs>/renders/v1.mp4" })。使用绝对路径，并且每次使用相同的 title，这样后续渲染会成为此项目的新版本。 视频中有语音？ 如果你已经有语音的词语时间信息（烧录字幕、带时间戳的配音或已生成的转录），请添加 transcriptPath（.srt、.vtt 或词语时间信息 JSON，例如 Whisper 生成的文件）。这样用户就能在时间轴下方跟读并对词语发表评论。如果没有，且已安装 whisper.cpp，FrameJam 会自行转录渲染结果，因此无需专门为此转录。 在内置浏览器中打开返回的 url（见步骤 0），并且务必在聊天中将其作为可点击的 Markdown 链接发出， 例如 [在 FrameJam 中打开 v1](http://localhost:2400/review/rev_…)，这样即使浏览器未显示评审页面，用户也能从聊天中打开。然后用一行告诉用户： “点击视频可标注某个位置（也可以暂停后输入），然后按 Finish review。”
5. 在同一轮中等待： 打开评审后立即调用 wait_for_feedback({ reviewId })。不要先结束本轮，否则只有在此循环运行期间，评审页面才会显示“Agent listening”。
   • status: "pending" 表示过去约 50 秒内没有收到反馈。立即再次调用，不要询问用户。
   • 连续 12 次返回 pending 后停止（约 10 分钟）。 不要无限等待。结束本轮时发送一条简短消息，包含项目的 url，并说明：“完成后请按 Finish review，然后粘贴页面显示的那行内容（或说 apply my FrameJam feedback），我会继续处理。”评论已经保存，不会丢失。用户回来后，调用 get_feedback。如果用户在聊天中要求停止，则提前停止。
   • status: "feedback" 会返回 comments[]、Markdown 摘要和帧图像。
   • revised: true 表示你收到评论后，用户重新打开评审并修改了评论。新评论列表会取代旧列表：不要保留旧列表中未出现在新列表里的修改要求。
   • 完成了吗？ 如果评论只是说视频已完成、已批准或可以交付，且没有要求修改，就不要再制作新版本。告诉用户最终文件的位置，附上项目链接，然后停止等待。
6. 应用每条评论。
   • at / time / endTime 表示视频中的时间位置。position 表示画面中的位置。
   • 固定评论的帧图像上会显示标记：查看标记下方的内容，然后在对应时间点查找源文件中的相关元素。
   • wholeVideo: true 表示全局意见（节奏、颜色、音乐等）。
   • 如果有转录内容，范围评论中的 spoken 会引用该时间段内说出的话语，某个时间点附近的 spokenAround 会引用附近的话语。这些内容来自转录，因此人名和生僻词可能识别错误：用它们定位片段，不要将其当作脚本。
7. 交付下一版本。 重新渲染到 renders/v2.mp4，然后调用 add_version({ reviewId, videoPath, note })（或使用相同的 title 再次调用 open_review），如果语音时间信息有变化，还要添加新的 transcriptPath。 note 是对所做修改的一行摘要；新版本到达时以及版本菜单中，用户都能看到它。 在聊天中说明新版本已就绪，并且再次将返回的 url 作为可点击链接发出，例如 [在 FrameJam 中打开 v2](http://localhost:2400/review/rev_…)，并附上同一行摘要。 每个版本构成一轮：用户按下“Finish review”后，上一版本即锁定，新版本开始时不包含任何评论。如果某条评论无法处理，请在聊天中和 note 中说明原因。 加快每轮处理： 只重新渲染有改动的部分，其余部分沿用。
8. 返回步骤 5。

长时间运行的任务

• 对于耗时超过一分钟的任务，请以命令返回后仍会继续运行的方式启动（作为后台任务，而不是会随 shell 退出的子 shell &），将日志写入文件，并每隔 30–60 秒检查一次。对于可以轮询的任务，切勿固定等待很长时间。
• 一次只运行一个高负载任务：同时运行两次渲染，或同时运行一次渲染和一次转录，都会让两者变慢。
• 等待任务前，先用一行告诉用户正在运行什么以及预计耗时。

Hyperframes

• **在此机器上首次运行：**运行一次 npx hyperframes doctor。它会检查渲染所需的 Node、ffmpeg 和 Chrome。如果缺少任何内容，请在构建前告诉用户如何安装。
• 构建合成：创建包含根元素 data-composition-id 和 data-width/data-height 的 index.html，包含带有 data-start/data-duration/data-track-index 的 .clip 元素，以及注册到 window.__timelines["<id>"] 的暂停状态 GSAP 时间线。运行 npx hyperframes lint 并修复错误。
• 渲染：npx hyperframes render -o renders/v1.mp4。
• **打开：**像使用其他工具一样传入 videoPath。由用户查看渲染结果。

其他工具（Remotion、Motion Canvas、ffmpeg、录屏等）

• 使用项目自身的工具和渲染命令（npx remotion render、Motion Canvas 导出器、ffmpeg 脚本或屏幕录制）。不要将项目转换为 Hyperframes。
• 每个版本都渲染到新的 mp4/webm/mov 文件，并调用 open_review({ title, videoPath })。
• 使用风格指南的视觉效果（guide、palette、fonts、easing、节奏），并通过工具自身的方式应用到用户指定的主题上。

故事板（尚无视频时）

如果用户希望先确认镜头，或要求提供故事板、镜头列表，或“动画制作前先看画面”，请使用故事板评审。流程相同，但每个版本是一组静帧面板，而不是渲染视频。

1. **制作面板。**每个镜头一张图片（png、jpg、webp、gif 或 svg），所有图片的宽高比都要与最终视频一致，放在同一个文件夹中，并按顺序命名，确保排序正确：storyboard/01.png、02.png，依此类推。优先使用以下素材：
   • Hyperframes 粗略合成的快照（npx hyperframes snapshot --at 0.5,2.5,4.5 -o storyboard），或项目自身工具生成的静帧。
   • 为每个镜头生成的图片。
   • 快速制作并截图的 HTML 模型。
2. 打开评审：open_review({ title, panelsDir: "<abs>/storyboard", panels: [{ path: "01.png", title: "开场", caption: "缓慢推进。旁白：“现在每个团队的交付速度都更快了。” 2s" }, …] })。panels 是可选的；不传时会按文件名顺序使用文件夹中的所有图片。标题和说明文字会显示在每个面板下方，供用户阅读，因此请在其中写明镜头名称、动作或运镜方式、旁白内容和时长。
3. 等待用户反馈，使用 wait_for_feedback，方式与视频评审完全相同（先在内置浏览器中打开 URL，连续收到 12 次 pending 后停止）。
4. 按面板查看评论。at 的值为 "panel 3 (开场)"，panel 包含编号、标题、说明文字和该面板的 imagePath，position 表示用户在面板上点击的位置。附带的图片会显示绘有图钉的面板。wholeVideo: true 表示针对整个故事板的反馈（顺序、节奏、增加或删减镜头）。
5. **下一版本：**更新或重新生成图片，然后调用 add_version({ reviewId, note })。如果不提供媒体，它会重新读取同一个 panelsDir，并保留仍在其中的文件对应的标题和说明文字；传入 panels 可更改顺序、标题或说明文字。较早版本会保留各自的图片副本。
6. 用户批准故事板后，根据面板和说明文字逐个镜头制作视频，并像普通视频评审一样打开视频（使用新的 open_review，将渲染结果作为 videoPath）。

其他使用方式

• 如果用户说“应用我的 FrameJam 反馈”（无论是否附带审核 ID），请调用 get_feedback()。如果没有 reviewId，它会选取尚未向你同步评论的审核。如果用户输入了评论但没有按下 Finish review，这些评论现在会交给你。list_reviews() 会显示每个项目以及其审核轮次的进展。
• 如果 MCP 未连接，用户可以在审核页面的版本菜单中使用 Copy comments as text，然后将结果粘贴到聊天中。

更新 FrameJam

如果用户要求更新 FrameJam，请运行 npx -y framejam@latest install <app>，并将你正在使用的应用填入其中（cursor、claude 或 codex；如果不填，则会设置电脑上找到的所有应用）。该命令会更新 skill、MCP 服务条目以及正在运行的 FrameJam 页面。然后告诉用户重启一次应用：FrameJam 工具只有在重启后才会加载新版本。

规则

• 不要要求用户在聊天中描述时间戳，让他们前往审核页面。
• 绝不要伪造渲染结果。如果渲染失败，请先修复，再打开审核。
• 保持审核 URL 稳定：每个视频对应一个项目，每次渲染对应一个新版本。
• 与用户交流时，将其称为“项目”。