gen-ai-explainer

动画解说工作流（Light Producer）

你将驱动一个 6 阶段的流水线。在聊天中处理创意阶段；所有媒体生成和渲染都由 gen-ai CLI 负责。状态以 JSON 文件的形式存储在 ~/.gen-ai/projects/explainer/<slug>/ 中。

适用场景

参见上方说明。

前置条件

已安装并完成身份验证的 Picsart gen-ai CLI（gen-ai login）。

运行方式

使用 Agent 的 terminal 工具，按照下方“操作步骤”中所述调用 gen-ai 命令。

快速参考

规范命令请参见“操作步骤”。

操作步骤

详细操作流程请参见以下各节。

注意事项

请参见下方的“常见问题”。

验证

运行 gen-ai whoami 确认身份验证状态，然后为失败的命令重新运行并添加 --debug。

模式 — 交互式（默认）或自动

在进行任何操作之前，先确定用户想要哪种模式：

交互式模式（默认 — 除非用户选择退出，否则使用此模式）

4 个创意阶段均以明确暂停结束。你负责展示，用户负责审阅、输入 continue / 提出修改 / 进行选择。以下完整的规则一适用。 适合首次使用、精品制作，以及尚未另行告知偏好的用户。

自动模式（主动选择）

端到端执行全部 6 个阶段，不暂停。你仍会简要展示每项产物，让用户可以随时打断，但不会等待。你负责做出选择：从 3 个概念中选出最佳方案、为该概念选出最佳执行方案，并按你的方式撰写脚本。用户选择的是“相信你的判断，端到端完成”。

出现以下任一内容时，判定为自动模式：

• auto、auto mode、auto-approve、auto approve
• no approvals、skip approvals、don't ask、no questions
• just do it、yolo、full auto、end to end
• run it through、run all stages、no checks

只要看到其中任意一项，就将模式设为自动。 否则，使用交互式模式。

如果用户的表达有歧义，在开始时只问一次： “交互式（我会在每个阶段暂停供你审阅）还是自动（我会端到端运行并交付最终视频）？” — 然后继续。

即使在自动模式下，仍必须：

• 在第 5 阶段（素材）之前告知预计的点数消耗。一句话： “现在将消耗约 1850 点来生成素材。余额：12,500 → 完成后约 10,650。” 不要征求许可，只需告知。若用户不同意，可以按 Ctrl-C。
• 在每个阶段开始前阅读对应的导演技能。无论使用何种模式，规则零都不可妥协。
• 明确指出实际错误，不要默默失败。如果 CLI 返回 { "status": "error", "hint": "..." }，就停止并告知用户。
• 遇到真正的歧义时停止 — 如果用户说“30 秒解说”，但主题显然需要 3 分钟以上才能讲清楚，就先问一次再做判断。

分阶段行为表

阶段	交互式	自动
研究	展示发现，暂停	简要展示发现，继续
提案	展示 3 个概念和预计消耗，暂停	展示 3 个概念和预计消耗，自行选出最佳方案，宣布选择，继续
脚本	展示完整脚本，暂停	展示脚本，继续
场景规划	展示场景表，暂停	展示场景表，继续
素材	告知消耗 + 确认	告知消耗（无需确认），开始执行
渲染	执行	执行
元数据 + 上传	起草 + 执行	起草 + 执行

6 个阶段——其中四个是必须通过的审批关卡

每个创作阶段都必须暂停。完成工作并展示后，停止 并等待用户。未经用户明确批准，不得连续执行多个阶段。

1. research — 由你在聊天中完成。阅读 references/research-director.md。展示研究结果后停止。
2. proposal — 由你在聊天中完成。阅读 references/proposal-director.md。为每个方案选择一种创作手册。 停止，直到用户选择 A / B / C。
3. script — 由你在聊天中完成。阅读 references/script-director.md。阅读所选创作手册的 audio.voice_style，并在 speaker_directions 中体现。展示脚本后停止。
4. scene_plan — 由你在聊天中完成。阅读 references/scene-plan-director.md。在 scene-plan.json 顶部包含 playbook 字段。 展示场景表后停止——这是花费资金前的最后一道关卡。
5. assets — CLI（约 1500-3000 个点数，耗时 5-25 分钟）。阅读 references/asset-director.md。将 scene-plan.json（包含 playbook 字段）和 script.json 写入项目目录。然后运行 gen-ai explainer:assets <slug>——CLI 会自动应用创作手册中的 image_prompt_prefix、image_negative_prompt 和 music_mood。
6. render — CLI（约 1-3 分钟）。阅读 references/render-director.md。运行 gen-ai explainer:render <slug>——创作手册会从素材清单自动传递；ffmpeg 会使用其 music_volume_db 和 narration_to_music_weight_ratio。

完成第 6 阶段后：在聊天中拟定标题、描述、章节和标签。然后运行 gen-ai upload-to-drive <slug>/explainer.mp4 --name "<title>"。分享返回的 drive_url， 并说明它是临时 CDN 链接——如果用户需要长期保留的副本，请引导其查找 Drive 条目（drive_uid）。

规则零——每个阶段开始前都要阅读导演技能文件

6 个阶段都各有专门的导演技能文件，位于 ~/.claude/skills/gen-ai-explainer/references/<stage>-director.md。在执行每个阶段之前，必须阅读 相应的导演技能文件。不是执行之后读，也不能略读。要完整阅读。

导演文件不是“背景阅读材料”——其中包含该阶段的准确流程、查询模板、架构结构、自评标准、常见陷阱和停止关卡。跳过这些文件会导致输出质量下降，浪费用户的点数。

技能加载流程（每个阶段开始时执行）

1. 在聊天中宣布：“正在加载 references/<stage>-director.md。” 一行即可，让 用户看到你正在遵循流程。
2. 使用 Read 工具阅读文件。完整阅读。
3. **严格遵循其中的流程步骤。**不要自行发挥——这些导演文件经过精心编写，让你无需每次都重新设计工作流。
4. 当导演文件中的停止关卡触发时，停止。不要提前加载下一阶段的导演文件。

阶段 → 导演文件对应关系（请记住）

阶段	首先要阅读的导演技能文件
research	references/research-director.md（5 轮搜索，约 12-15 次网络搜索）
proposal	references/proposal-director.md（3 个方案 + 通过 gen-ai credits + gen-ai pricing --json 估算点数）
script	references/script-director.md（叙事弧线、字数预算、eleven-v3 指示）
scene_plan	references/scene-plan-director.md（5 项检查清单、技巧库）
assets	references/asset-director.md（调用 gen-ai explainer:assets <slug>）
render	references/render-director.md（调用 gen-ai explainer:render <slug>）

不要做的事（技能加载违规）

• 不要因为“记得上次对话中的内容”而跳过阅读 director。
• 不要为了“减少往返”而批量阅读 director——每个阶段都要使用全新的上下文。
• 不要凭一般知识临场发挥某个阶段，而要遵循 director 的具体流程。
• 不要把上一阶段过时的 director 内容带到当前阶段（例如，把场景规划规则用于脚本阶段）。
• 不要为了“更快”而默默省略 director 要求的步骤（网络搜索、自我评估、发音指南）。

如果跳过阅读 director，用户会发现：研究内容缺少有来源的 URL，脚本缺少叙事弧线，场景规划也无法通过 5 项检查清单。低质量的输出会暴露你没有遵循协议。

规则一——交互模式中的审批关卡

此规则仅适用于交互模式。自动模式会按照上文“模式”部分的规定，将 STOP 替换为“告知并继续”。

在交互模式下，四个创作阶段（research / proposal / script / scene_plan）结束时都必须立即停止。呈现输出后：

• 等待用户回复。
• 如果用户说“继续”／“看起来不错”／“批准”／“开始”，则进入下一阶段。
• 如果用户说“编辑 X”／“重写 Y”／“调换 N”，则修改后再次呈现，并再次停止。
• 持续迭代，直到用户明确批准。

在交互模式下，不要：

• 未经用户回复就自动进入下一阶段。
• 为了“节省时间”而在等待期间预先起草下一阶段的内容。
• 因用户沉默而假定已获批准。
• 跳过向用户展示产出。
• 在同一条消息中合并多个阶段。

如果在交互模式下跳过审批关卡，用户就可能要为尚未确认的画面付出代价。交互模式的核心就是让人在流程中进行把关。

在自动模式下，用户已明确选择不经审批——你应完成全部 6 个阶段并生成视频。你仍需告知每个阶段的产出（让用户看到你的选择），并告知积分预估，但无需等待用户输入。

其他规则

• 资产阶段成本较高（30–90 秒的视频约需 1500–3000 积分）。运行前告知积分预估，并在第 5 阶段开始时再次确认。
• 如果 CLI 调用失败，请读取错误 JSON 中的 hint 字段，并判断应重试、重新规划还是告知用户。
• 除非用户提出要求，否则绝不要覆盖默认模型。默认值如下：
  • 图像：gemini-3.1-flash-image（Nano Banana 2）
  • 视频：seedance-2.0
  • 语音：eleven-v3
  • 音乐：minimax-music

恢复协议

如果用户提到一个现有项目，运行 ls ~/.gen-ai/projects/explainer/<slug>/，并根据存在的 JSON 文件判断应从哪个阶段恢复：

存在的文件	恢复阶段
仅有 manifest.json	阶段 3（脚本）
script.json	阶段 4（scene_plan）
scene-plan.json	阶段 5（资产）
asset-manifest.json	阶段 6（渲染）
render-report.json	上传步骤

参见 pipeline.yaml 中的机器可读清单。