691b8cdd0c
- 核心配置: IDENTITY, USER, SOUL, AGENTS, TOOLS, HEARTBEAT, MEMORY - memory/: 每日总结和临时记录 - skills/: 所有已安装技能 - notes/: 语音配置笔记
151 lines
4.8 KiB
Markdown
151 lines
4.8 KiB
Markdown
# 幻灯片（Slide / PPT）参考文档
|
||
|
||
本文件包含腾讯文档 MCP 幻灯片相关工具的使用指南和注意事项。
|
||
|
||
---
|
||
|
||
## 概述
|
||
|
||
幻灯片通过 `create_slide` 工具创建，AI 自动根据用户描述和参考资料生成 PPT 内容。该接口为**异步接口**，需配合 `slide_progress` 工具轮询进度。
|
||
|
||
---
|
||
|
||
## 工具列表
|
||
|
||
| 工具名称 | 功能说明 |
|
||
|---------|---------|
|
||
| create_slide | 创建幻灯片（AI 自动生成内容，异步接口） |
|
||
| slide_progress | 查询幻灯片生成进度 |
|
||
|
||
---
|
||
|
||
## 工具详细说明
|
||
|
||
### 1. create_slide
|
||
|
||
#### 功能说明
|
||
根据用户描述和参考资料，由 AI 自动生成幻灯片内容并创建 PPT。
|
||
|
||
#### 调用示例
|
||
|
||
**示例1：根据主题生成 PPT**
|
||
```json
|
||
{
|
||
"description": "生成一份主题为'2024年度销售总结'的PPT，要求包含业绩回顾、亮点项目、问题分析和来年规划四个章节"
|
||
}
|
||
```
|
||
|
||
**示例2：根据参考材料生成 PPT**
|
||
```json
|
||
{
|
||
"reference_context": "第一季度销售额达到1200万，同比增长25%。主要增长来自华南区域，新客户占比40%。存在问题：北方市场渗透率不足，客单价偏低。",
|
||
"description": "根据材料生成PPT，要求风格简洁专业，重点突出数据亮点"
|
||
}
|
||
```
|
||
|
||
#### 参数说明
|
||
- `description` (string, 必填): 用户对 PPT 的要求描述。样例1：【生成一份主题为xxx的PPT，要求xxxx】；样例2：【根据材料生成PPT，要求xxxx】
|
||
- `reference_context` (string, 可选): 生成 PPT 的参考资料，必须是 UTF-8 文本格式。**仅当用户明确指定需要根据某段内容/材料生成PPT时才传此参数，不要自由发挥填充内容**
|
||
|
||
#### 返回值说明
|
||
```json
|
||
{
|
||
"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` 不正确或已过期），停止轮询
|
||
|
||
#### 调用示例
|
||
```json
|
||
{
|
||
"session_id": "session_1234567890"
|
||
}
|
||
```
|
||
|
||
#### 参数说明
|
||
- `session_id` (string, 必填): `create_slide` 返回的异步任务 session_id
|
||
|
||
#### 返回值说明
|
||
```json
|
||
{
|
||
"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 分钟），请稍后重试`
|
||
|
||
#### ❌ 避免的做法
|
||
|
||
```bash
|
||
# ❌ 错误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 时才传
|