Mintii-Labs/ozor-skills

Ozor 文档转视频

在 Ozor.ai 上将真实文件（PDF、PPTX、DOCX 等）端到端转换为视频。它会在 Ozor 侧分析文件，生成结构化的分镜计划，让用户批准/编辑该计划，然后生成并导出成品视频——在此过程中保留幻灯片的视觉内容。

何时使用

当输入是文档/文件时使用此技能。典型场景：

• 用户附加或引用了 PDF、PPTX、DOCX、Keynote 导出、幻灯片、提案、白皮书、报告、一页纸
• “把这个演示文稿做成视频”
• “从这个 PDF 生成视频”
• “从我的 pitch / 提案 / 报告生成视频”

请勿在以下情况使用此技能：

• 输入是简短创意的文本简报 → 使用 ozor-generate
• 输入是 URL 或落地页 → 使用 ozor-url-to-video
• 用户只需要一个书面的 Ozor 提示词 → 使用 ozor-doc-to-video（纯提示词技能）
• 用户想管理已有视频 → 使用 ozor-video-library

所需的 MCP 工具

• mcp__ozor__analyze_document — 分析文档，返回 planId 以及结构化的计划
• mcp__ozor__prepare_document_upload — 获取一个可通过 curl 上传的 URL，用于没有公开 URL 的本地文件（常见路径）
• mcp__ozor__get_plan — 获取最新的计划状态
• mcp__ozor__update_plan — 在生成之前应用用户对计划的编辑
• mcp__ozor__generate_from_plan — 从已批准的计划开始构建视频，返回 projectId
• mcp__ozor__export_video — 开始渲染（使用 projectId 作为 videoId）
• mcp__ozor__wait_for_export — 阻塞直到渲染就绪
• mcp__ozor__get_embed_code — 返回 <iframe> HTML

如果未连接 Ozor MCP，请告知用户并停止。请勿自行提取内容并退回到使用 generate_video 并附上手写脚本——这样会丢失幻灯片视觉效果并超出 2000 字符的提示词限制。基于计划的流程对文档来说是强制性的。

工作流程

步骤 1 — 将文档提供给 Ozor

按优先级选择最佳来源：

1. 公开 URL → 直接将 url 传给 analyze_document。无大小限制，无令牌消耗。只要有就首选。
2. 本地文件（常见情况） → 调用 mcp__ozor__prepare_document_upload，然后运行返回的 curl 命令将字节直接推送到 Ozor 的存储。字节永远不会经过工具调用，因此最大约 50 MB 的文件也能正常工作。用于用户上传到对话中的任何数 MB 的 PDF/PPTX/DOCX。
3. 在 analyze_document 上使用 fileBase64 + fileName → 仅适用于小文件（约几百 KB 以内）。对于大型演示文稿请避免使用——它会消耗令牌。

如果工具列表中不存在 prepare_document_upload，则此服务器上禁用了上传功能——请回退到 URL 或小的 base64。

步骤 2 — 分析文档

一旦 Ozor 获取到文件，调用：

mcp__ozor__analyze_document({
  url | uploadId | fileBase64+fileName,
  ...可选提示：targetDuration，format（16:9 / 9:16），audience，tone
})

此调用返回 { planId, plan }。该计划包含提议的场景、旁白、视觉注释以及哪些幻灯片/页面映射到哪些场景。

步骤 3 — 向用户展示计划并停止

这是关键步骤。 不要跳过到生成阶段。向用户展示一份简洁的计划呈现：

📋 Ozor 计划 for "<文档名称>"

**格式：** 16:9（或 9:16）
**预计时长：** ~X 秒
**场景数：** N

(1) <场景标题> — <一行旁白/视觉描述>
(2) <场景标题> — <一行旁白/视觉描述>
...

需要我直接按此生成，还是做任何修改？您可以：
- 编辑某个场景（“将场景 2 改为...”）
- 重新排序 / 删除 / 添加场景
- 改变语气、时长或格式
- 批准并生成

然后等待用户批准或请求编辑。不要自行调用 generate_from_plan——计划是用户掌控成本和创意方向的检查点。

步骤 4 — 应用编辑（如有）

如果用户要求修改，使用编辑内容调用 mcp__ozor__update_plan({ planId, ... })。使用 get_plan 重新获取并重新展示更新后的计划。循环直到用户批准。

步骤 5 — 从计划生成

当用户批准时：

mcp__ozor__generate_from_plan({ planId })

此调用返回 { projectId }。在后续所有调用中将 projectId 作为 videoId 使用。

如果响应中包含 jobId，则使用 wait_for_job({ videoId: projectId, jobId }) 等待它。否则继续导出。

步骤 6 — 导出

mcp__ozor__export_video({ videoId: projectId })
mcp__ozor__wait_for_export({ videoId: projectId })

返回 shareUrl、editorUrl、downloadUrl。

步骤 7 — 嵌入

mcp__ozor__get_embed_code({ videoId: projectId })

步骤 8 — 呈现结果

🎬 视频已准备完成 from "<文档名称>"

**分享：** <shareUrl>
**编辑器：** <editorUrl>
**下载：** <downloadUrl>

**嵌入：**
```html
<iframe ...></iframe>

需要基于同一计划制作 9:16 的社交媒体版本吗？我可以重新生成。

## 可传给 `analyze_document` 的提示参数

如果用户提到过或从文档中显而易见，可以传递以下任意参数：

- `targetDuration` — 例如 `"60s"`、`"90s"`。提案/演示文稿默认约 60 秒，一页纸默认约 30 秒。
- `format` — `"16:9"`（默认）或 `"9:16"`（用于社交媒体）。
- `audience` — 投资者、客户、开发者、内部团队……
- `tone` — 自信、温暖、技术、充满活力……
- `focus` — 可选，一行注释，如“突出第 4 张幻灯片的指标”或“跳过团队介绍幻灯片”。

## 按文档类型的适配建议

| 文档类型 | 默认时长 | 格式 | 语气 | 重点 |
|----------|----------|------|------|------|
| Pitch deck | 60–90s | 16:9 | 自信 | 问题 → 解决方案 → 进展 → CTA |
| 提案（DOCX） | 60s | 16:9 | 专业 | 成果 + 报价 + 下一步 |
| 白皮书 / 报告 | 60–90s | 16:9 | 权威 | 3 个关键发现，在 CTA 中链接完整文档 |
| 销售一页纸 | 30–45s | 16:9 | 精炼 | 吸引点 → 3 个好处 → CTA |
| 发布说明 | 30–45s | 16:9 | 充满活力 | 每个功能一个场景 |
| 培训 / SOP | 90s+ | 16:9 | 冷静、清晰 | 编号步骤，超过 7 个场景则拆分为系列 |

如有疑问，在初始调用中提出默认值，让用户在查看计划后覆盖。

## 生成后的迭代

如果渲染的视频需要修改：
- 小范围的旁白/文案调整 → 使用 `update_plan` + 重新生成（这会从计划重新运行，无需重新分析文档）
- 新的场景顺序或语气 → 相同路径
- 新的重点或受众 → 可能更便宜的做法是使用更强的提示再次调用 `analyze_document`

## 错误与恢复

- **`analyze_document` 因文件太大而失败** → 使用 `prepare_document_upload` 代替 base64。
- **计划内容缺失或错误** → 使用 `update_plan` 进行修正，而不是重新开始。
- **`generate_from_plan` 失败** → 错误通常指向某个特定场景。通过 `update_plan` 修复，然后重试。
- **导出挂起** → 可以安全地再次调用 `wait_for_export`；它会恢复。

## 规则

1. **始终先计划后生成。** 切勿使用从文档中提取的手写散文调用 `generate_video`。此技能的全部意义在于 Ozor 直接看到幻灯片。
2. **始终向用户展示计划并等待批准**，然后再调用 `generate_from_plan`。生成是昂贵的步骤；计划是检查点。
3. **对于本地文件，使用 `prepare_document_upload` + curl。** Base64 仅适用于 tiny 文件。
4. **在 `generate_from_plan` 之后的所有地方使用 `projectId` 作为 `videoId`。** 它是同一个标识符。
5. **提供每一个 URL** — 分享、编辑器、下载、嵌入。
6. **不要自行总结文档** — Ozor 的 `analyze_document` 会完成此操作并保留视觉效果。您的工作是编排 MCP 并策划计划，而不是重写内容。