stock-assistant/skills/tencent-docs/references/slide_references.md

幻灯片（Slide / PPT）参考文档

本文件包含腾讯文档 MCP 幻灯片相关工具的使用指南和注意事项。

---

概述

幻灯片通过 create_slide 工具创建，AI 自动根据用户描述和参考资料生成 PPT 内容。该接口为异步接口，需配合 slide_progress 工具轮询进度。

---

工具列表

工具名称	功能说明
create_slide	创建幻灯片（AI 自动生成内容，异步接口）
slide_progress	查询幻灯片生成进度

---

工具详细说明

1. create_slide

功能说明

根据用户描述和参考资料，由 AI 自动生成幻灯片内容并创建 PPT。

调用示例

示例1：根据主题生成 PPT

{
  "description": "生成一份主题为'2024年度销售总结'的PPT，要求包含业绩回顾、亮点项目、问题分析和来年规划四个章节"
}

示例2：根据参考材料生成 PPT

{
  "reference_context": "第一季度销售额达到1200万，同比增长25%。主要增长来自华南区域，新客户占比40%。存在问题：北方市场渗透率不足，客单价偏低。",
  "description": "根据材料生成PPT，要求风格简洁专业，重点突出数据亮点"
}

参数说明

• description (string, 必填): 用户对 PPT 的要求描述。样例1：【生成一份主题为xxx的PPT，要求xxxx】；样例2：【根据材料生成PPT，要求xxxx】
• reference_context (string, 可选): 生成 PPT 的参考资料，必须是 UTF-8 文本格式。仅当用户明确指定需要根据某段内容/材料生成PPT时才传此参数，不要自由发挥填充内容

返回值说明

{
  "session_id": "session_1234567890",
  "error": "",
  "trace_id": "trace_1234567890"
}

⚠️ 注意：create_slide 为异步接口，返回 session_id 后需配合 slide_progress 工具轮询进度（每隔20秒轮询一次，最长等待20分钟），待状态为 completed 时从响应中获取 file_url。

2. slide_progress

功能说明

查询幻灯片生成进度，与 create_slide 配合使用。调用 create_slide 获取 session_id 后，每隔 20 秒轮询一次，最长等待 20 分钟，直到状态为 completed 或 failed。

状态说明

• in_progress：进行中，继续轮询
• completed：已完成，幻灯片已生成，从响应中获取 file_url
• failed：失败，停止轮询
• canceled：已取消，停止轮询
• not_found：未找到（session_id 不正确或已过期），停止轮询

调用示例

{
  "session_id": "session_1234567890"
}

参数说明

• session_id (string, 必填): create_slide 返回的异步任务 session_id

返回值说明

{
  "status": "completed",
  "file_url": "https://docs.qq.com/slide/DV2h5cWJ0R1lQb0lH",
  "error": "",
  "trace_id": "trace_1234567890"
}

---

典型工作流

创建幻灯片

1. 调用 create_slide 传入 description（用户要求）和可选的 reference_context（参考资料）
2. 获取返回的 session_id
3. 使用 slide_progress 轮询进度（每隔 20 秒轮询一次，最长等待 20 分钟）
4. 待状态为 completed 时从响应中获取 file_url 并告知用户

⚠️ Agent 执行指引（重要）

异步轮询任务：推荐使用 spawn 子会话

幻灯片生成通常需要 10~15 分钟，推荐使用 spawn 子会话专职轮询，主会话保持响应，避免阻塞用户交互。

✅ 推荐做法：spawn 子会话轮询 + 主会话实时播报

标准工作流：

1. 主会话：提交 create_slide 任务 → 立即告诉用户"已开始"
2. spawn 子会话：专职轮询
   • 每 20 秒检查一次
   • 每次检查生成状态给主会话
   • 超时自动清理，输出超时状态给主会话
3. 主会话：接收子会话状态并格式化输出给用户
   • 进行中：⏳ 正在生成中，第 N 次轮询，请稍候...
   • 完成：✅ 生成完成！PPT 链接：<file_url>
   • 失败：❌ 生成失败：<原因>
   • 超时：⚠️ 生成超时（已等待 20 分钟），请稍后重试

❌ 避免的做法

# ❌ 错误1：主会话直接 sleep 循环阻塞，用户无法交互
for i in 1..15; do
  mcporter call tencent-docs slide_progress ...
  sleep 20  # 阻塞主会话，用户体验差
done

# ❌ 错误2：后台进程静默等待，不向用户播报进度
# 用户看不到任何进度，体验如同宕机

# ❌ 错误3：子会话轮询完成后不通知主会话
# 用户在主会话中无法得知结果

---

注意事项

• create_slide 为异步接口，返回 session_id 后必须轮询
• 轮询间隔：每 20 秒一次
• 最长等待时间：20 分钟
• reference_context 仅在用户明确指定需要根据某段内容/材料生成 PPT 时才传