Ppt Course

# PPT 做课

用户明确要求用 PPT 做课时，按「两阶段」流程操作：先提交 PPT 拿每页图片，再逐页写口播文案提交制作。

## 第一阶段：提交 PPT

调用 `start_ppt_course`，为一次做课生成稳定的 `request_key`，重试时复用。`title` 在转换阶段使用附件文件名（去掉扩展名）作为临时标题，不要在上传前要求用户填写最终课程信息。

- 可以使用用户给出的 HTTPS 文件链接。
- 用户在当前对话中发送了 PPT/PPTX/PDF 附件时，优先使用 WorkBuddy 提供的真实附件路径，不要求用户再次选择文件。先调用 `start_ppt_course`（不传 `source_url`），再把该附件以 `multipart/form-data` 上传到返回的 `upload_url`，表单字段使用返回的 `upload_field`（当前为 `file`），并请求 JSON 响应。上传动作必须由本机文件上传能力完成，不把文件二进制或 Base64 放进 MCP JSON。
- 只有 WorkBuddy 确实没有暴露可读取的附件路径、或者本机上传能力不可用时，才把 `upload_url` 作为兜底页面交给用户手工上传。不得在附件可用时先打开上传页面。
- 直接上传成功后继续使用原 `job_id` 查询进度；不要再次调用 `start_ppt_course` 创建新任务。签名地址过期时，复用同一个 `request_key` 获取当前任务状态，不猜测或改写签名参数。

用 `get_ppt_course_status` 轮询，直到 `stage` 变为 `awaiting_scripts`。此时返回体中的 `pages` 为逐页 `{index, image_url}`，即可开始写文案。

- 优先直接使用 `image_url` 查看每页图片，不把图片保存到用户的下载目录。
- 视觉工具必须读取本地文件时，只下载到临时缓存目录，识别完成后立即删除，不把临时文件作为产物展示给用户。
- 工具返回的 `index` 从 0 开始；向用户展示时统一转换为从 1 开始的“第 N 页”。

## 第二阶段：提交文案生成草稿或视频

逐页看图后，根据整份 PPT 自动生成建议课程标题、课程描述和逐页口播文案。`scripts` 数组长度必须与 `pages` 一致并严格按页序。

调用提交工具前必须完成以下审核循环：

1. 一次性展示完整建议内容：课程标题、课程描述，以及每页 PPT 图片和对应口播文案。
2. 明确提示用户可以直接确认，也可以修改标题、描述、指定页文案或整体语气、长度和风格。
3. 用户提出修改后更新对应内容，并重新展示包含全部页面的完整最新版；不得只展示修改页后直接提交。
4. 只有用户明确回复“确认”“可以”“按此生成”等同意含义后，才允许调用 `submit_ppt_course_scripts`。仅生成或展示建议内容不代表用户确认。
5. 确认后询问用户是“保存草稿后自行修改”还是“直接生成视频”；用户未明确选择时使用草稿模式。

调用 `submit_ppt_course_scripts`：

- `job_id`（必填）：第一阶段返回的任务编号。
- `scripts`（必填）：每页口播文案字符串数组。
- `title`（必填）：用户确认后的最终课程标题，最多 255 字。
- `description`（必填）：用户确认后的最终课程描述，最多 255 字。
- `mode`（可选）：`draft` 保存草稿，`render` 直接生成视频，默认 `draft`。

- `mode=draft` 时，将返回的 `edit_url` 给用户，说明可在系统内调整文案、音色、字幕和数字人后再生成视频，不要继续轮询视频。
- `mode=render` 时，用 `get_ppt_course_status` 轮询，`stage` 变为 `completed` 后调用 `get_ppt_course_video` 把视频链接给用户预览。

仅在用户明确说「发布」时，调用 `publish_ppt_course`，参数 `target_status` 固定为 `published`。失败时展示具体错误，不自动再次创建新课程。