PPT 生成智能体设计

制作 PPT 是托管智能体的常见使用场景。本页介绍官方 PPT 助手 的设计思路，帮助你使用 API 搭建自己的产出型智能体。官方配置可作为起点，建议根据业务需求调整；可复用的是其中的设计方法。

路径	适用对象	使用方式
直接使用官方智能体	希望直接使用	在控制台选择 PPT 助手 (official)，或通过 API 引用它的智能体 ID
参考本文搭建	需要定制模板、口径或插件组合	参考下文的设计说明，创建自己的智能体

在控制台打开 PPT 助手的详情页可以直接复制它的智能体 ID，也可以调用 GET /v1/agents 在列表中找到 PPT 助手。官方智能体可读不可改，详见智能体。

场景与目标

典型需求是根据原始材料或指定主题，生成结构完整、风格统一且可在 Office / WPS 中继续编辑的 PPTX 文件。官方 PPT 助手的设计重点包括：

内容有来源：优先使用原始材料；没有原始材料时，通过内置检索收集资料；数据类任务调用数据插件获取数据；
可编辑的文件产出：默认生成原生可编辑的 PPTX（文本框、表格、原生图表），而不是图片贴片或网页截图；
支持程序化取回：文件写入约定目录，客户端按约定取回，无需人工进入沙箱查找。

后续配置均围绕这三项目标展开。

设计思路

官方 PPT 助手由模型、系统提示词、技能、插件和默认内置工具集组成，未声明 tools 和 mcp_servers。以下介绍各部分的配置及调整时机。

模型：长上下文和指令遵循优先

官方选择 kimi-k3。PPT 任务需要同时处理原始材料全文、技能说明和排版约束，并严格按技能规范生成文件，因此对模型的长上下文处理、指令遵循和结构化生成能力要求较高。

系统提示词：四条可复用的约定

官方配置的系统提示词包含四条核心约定，也适用于其他产出型智能体：

技能二维体系：技能分为两类——方法类技能（Capability）决定执行方式，如深度调研；产物类技能（Artifact）决定产出形式，如 PPT、文档、表格。任务同时涉及两类技能时，先按方法类技能调研规划，再按产物类技能的规范产出；两者冲突时，以产物类技能的技术约束为准。
渐进加载：不预读全部技能说明，仅读取任务涉及领域的 SKILL.md，避免多个技能说明同时占用上下文，控制上下文成本。
产出物约定：产出文件一律写入工作区的 output/ 目录（沙箱内为 /mnt/agents/output/），最终回复用相对路径逐一列出（如 output/industry_analysis.pptx）。客户端可据此列出目录并取回文件，与文件章的会话文件接口对齐。
沟通策略：回复仅说明产出内容和文件位置，不列出中间使用的命令和库。

技能：产物类技能决定产出形式

官方当前挂载 PPT 产出物技能 ha-slides-pptx。该技能规定页面结构、排版规范和 PPTX 生成方式，用于生成原生可编辑的 PPTX，而非整页图片。可按需调整：

根据产出类型选择技能：制作 Word 报告时使用文档类技能，制作数据表时使用表格类技能；
需要特定研究方法时，可叠加方法类技能，例如深度调研类技能；
仅需收集一般资料时，可不额外挂载技能，平台内置检索工具即可满足需求。

技能按 skill_id 引用。省略 version 会在写入时固定为当时的最新版本；指定精确版本会固定使用该版本；显式传入 "latest" 时保留该值，并在读取或唤醒时重新解析，详见技能。官方智能体挂载的技能会随官方迭代调整，以 GET /v1/agents 返回的当前配置为准。

插件：数据能力按行业替换

数据类 PPT 的取数能力来自插件。金融是 PPT 的高频场景，官方配置了金融数据插件，包括同花顺 iFinD 金融数据库（行情、财报、公告）和天眼查（企业工商、股东高管、司法风险）。自建时可根据行业选择相应的数据插件，并按需组合多个插件。插件把 MCP 服务和捆绑技能打包分发，在控制台勾选或在创建请求中声明即可生效，不需要逐项配置。部分数据插件需要授权或访问凭据，凭据不保存在智能体配置里，而是通过凭据库在运行时注入。插件的引用方式和版本固定规则见插件。

工具：使用默认内置工具集

官方智能体没有声明 tools，平台会默认加载内置工具集，云沙箱中的文件读写、命令执行和联网检索等能力可直接使用，因此无需额外声明 tools 和 mcp_servers。仅在需要平台之外的能力时接入 MCP 服务，见接入 MCP。

起点模板

以下提供一个可运行的最小配置示例，根据上文的系统提示词、技能和插件组合编写。该示例并非官方配置的逐字拷贝，官方当前配置以 GET /v1/agents 返回为准。创建智能体：

curl -X POST https://api.moonshot.cn/v1/agents \
  -H "Authorization: Bearer $KIMI_API_KEY" \
  -H "kimi-api-version: 2026-09-01-beta" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "我的 PPT 助手",
    "model": {"id": "kimi-k3"},
    "system": "你是一个 PPT 制作助手。\n- 没有原始材料时，先用内置检索收集资料，再制作 PPT。\n- 技能文件按需读取，不要一次性加载全部技能说明。\n- 所有产出文件写到工作区的 output/ 目录，最终回复里用相对路径逐一列出（如 output/report.pptx）。\n- 产出所有元素可编辑的 .pptx 文件，不要用图片贴片。\n- 回复只讲产出了什么、放在哪里，不汇报实现细节。",
    "skills": [
      {"skill_id": "ha-slides-pptx", "version": "latest"}
    ],
    "description": "自建 PPT 助手：官方同款配方，可自定义模板与插件"
  }'

kha agents create --file - <<'JSON'
{
    "name": "我的 PPT 助手",
    "model": {"id": "kimi-k3"},
    "system": "你是一个 PPT 制作助手。\n- 没有原始材料时，先用内置检索收集资料，再制作 PPT。\n- 技能文件按需读取，不要一次性加载全部技能说明。\n- 所有产出文件写到工作区的 output/ 目录，最终回复里用相对路径逐一列出（如 output/report.pptx）。\n- 产出所有元素可编辑的 .pptx 文件，不要用图片贴片。\n- 回复只讲产出了什么、放在哪里，不汇报实现细节。",
    "skills": [
      {"skill_id": "ha-slides-pptx", "version": "latest"}
    ],
    "description": "自建 PPT 助手：官方同款配方，可自定义模板与插件"
}
JSON

创建成功后，从响应中保存 id 作为 AGENT_ID。可根据需求调整以下字段：

字段	调整频率	配置建议
`system`	经常调整	替换公司模板、品牌视觉规范和内容口径；建议保留上述四条约定
`skills`	按产出物调整	替换产物类技能，或叠加方法类技能
`plugins`	按行业调整	加入 `{"plugin_id": "<插件 ID>"}`，插件 ID 用 `GET /v1/plugins` 查询，或在控制台智能体表单中直接勾选
`model`	通常保持默认	`kimi-k3` 已适配长上下文产出任务
工具集	通常保持默认	默认内置工具集即可满足需求，无需额外声明

资源准备

执行环境：创建一个通用的云沙箱环境即可，config 传 {"type": "cloud"} 表示全部使用默认值，详见快速开始。PPT 生成不需要特殊的依赖或网络配置。
原始材料（可选，建议提供）：先通过 POST /v1/files 上传数据或文字等原始材料并获取 file_id，创建会话时挂载到 resources。文件会以只读副本形式挂载到沙箱的 /mnt/agents/upload/ 目录。原始材料有助于提高 PPT 内容的准确性和针对性，详见文件。
凭据（可选）：使用的数据插件需要授权时，提前在凭据库中配置好凭据，运行时自动注入，见凭据库。

挂载原始材料调用

快速开始已介绍完整调用流程，包括选择智能体、创建环境和会话、订阅事件流、发送消息及取回文件。此处仅补充使用原始材料的步骤。先上传原始材料，从响应中保存 id 作为 FILE_ID。/v1/files* 接口通过请求头 kimi-api-version: 2026-09-01-beta 选择本文档对应的 API 版本，省略该头时走旧版兼容行为（如上传返回 200 而非 201），请始终携带：

curl https://api.moonshot.cn/v1/files \
  -H "Authorization: Bearer $KIMI_API_KEY" \
  -H "kimi-api-version: 2026-09-01-beta" \
  -F "file=@industry_data.xlsx"

kha files upload --file industry_data.xlsx

创建会话时将文件挂载到 resources；没有原始材料时，省略 resources 字段：

curl -X POST https://api.moonshot.cn/v1/sessions \
  -H "Authorization: Bearer $KIMI_API_KEY" \
  -H "kimi-api-version: 2026-09-01-beta" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "'"$AGENT_ID"'",
    "environment_id": "'"$ENVIRONMENT_ID"'",
    "title": "行业分析 PPT",
    "resources": [
      {"type": "file", "file_id": "'"$FILE_ID"'"}
    ]
  }'

kha sessions create --file - <<JSON
{
    "agent_id": "$AGENT_ID",
    "environment_id": "$ENVIRONMENT_ID",
    "title": "行业分析 PPT",
    "resources": [
      {"type": "file", "file_id": "$FILE_ID"}
    ]
}
JSON

AGENT_ID 是官方 PPT 助手或自建智能体的 ID，ENVIRONMENT_ID 是执行环境 ID。从响应中保存会话 id 作为 SESSION_ID，然后订阅事件流并提交任务（订阅方式和消息结构见快速开始）：

curl -X POST https://api.moonshot.cn/v1/sessions/$SESSION_ID/events \
  -H "Authorization: Bearer $KIMI_API_KEY" \
  -H "kimi-api-version: 2026-09-01-beta" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.message",
        "data": {
          "content": [
            {"type": "text", "text": "基于绑定的行业数据，做一份 12 页的行业分析 PPT：市场格局、产业链、头部公司对比、投资要点，商务简洁风格、深蓝主色，所有元素可编辑的 .pptx。"}
          ]
        }
      }
    ]
  }'

kha sessions send "$SESSION_ID" "基于绑定的行业数据，做一份 12 页的行业分析 PPT：市场格局、产业链、头部公司对比、投资要点，商务简洁风格、深蓝主色，所有元素可编辑的 .pptx。"

会话回到 idle 后，智能体交付的成品会登记为 产物（Artifact）。先列出该会话的产物，找到生成的 PPTX 并保存它的 id：

curl "https://api.moonshot.cn/v1/artifacts?session_id=$SESSION_ID" \
  -H "Authorization: Bearer $KIMI_API_KEY" \
  -H "kimi-api-version: 2026-09-01-beta"

kha artifacts list --session "$SESSION_ID"

再用产物 id 下载成品：

curl "https://api.moonshot.cn/v1/artifacts/$ARTIFACT_ID/content" \
  -H "Authorization: Bearer $KIMI_API_KEY" \
  -H "kimi-api-version: 2026-09-01-beta" \
  -o industry_analysis.pptx

kha artifacts download "$ARTIFACT_ID" --out industry_analysis.pptx

如果产物列表为空，或需要查看中间文件，可使用 GET /v1/sessions/$SESSION_ID/filesystem 按 prefix 逐层浏览子目录，再通过文件条目的 path 调用 filesystem/raw 下载，详见文件。

PPT 生成是耗时任务，包含调研时可能需要几分钟到十几分钟。如果事件流连接中断，请将断开前最后一帧 SSE 消息的 id: 字段作为 cursor 重新订阅，以继续读取，详见事件流。

运行监控

可通过事件流查看任务进展。典型 PPT 任务中，建议关注以下信号：

session.status：idle → running 表示任务启动；状态回到 idle 表示本轮完成，可以取回文件。
agent.thinking：可查看任务规划，包括原始材料读取顺序、调研安排、大纲结构和页面内容。如果大纲方向不符合预期，可在此阶段取消会话并提交更清晰的需求。
agent.tool_use / agent.tool_result：可查看数据任务调用的数据插件或检索工具，以及查询的数据口径。数据异常时，可优先检查数据源选择。
agent.message：最终回复会按产出物约定列出 output/ 下的相对路径。客户端可以解析这份清单；为提高稳定性，取回成品时建议直接查询产物接口（GET /v1/artifacts?session_id=...）。
session.error：任务失败时出现，包含错误类型和信息。

写清任务描述

任务描述是影响 PPT 产出质量的主要因素。建议遵循以下四条原则。

1. 优先提供原始材料

先上传数据或文字等原始材料，创建会话时挂载到 resources，再提交任务。原始材料有助于提高 PPT 内容的准确性和针对性。

推荐：上传财报 Excel 后说「基于绑定的数据做季度经营分析 PPT」；
未提供原始材料时，也可仅指定主题，智能体会通过内置检索收集资料。这种方式覆盖面较广，但耗时更长，内容口径可能不如原始材料贴合。

2. 明确页数、风格和受众

其他排版细节可使用 PPT 技能的默认规范，避免过多约束相互冲突。

示例：「做一份 12 页的新能源行业分析 PPT，商务简洁风格、深蓝主色，给投委会看。」

3. 数据类 PPT：指定数据源

如果智能体已挂载数据插件，可在任务中直接指定数据来源，无需另行准备数据。

示例：「用金融数据插件拉取某公司最近四个季度的财报数据，做一份基本面分析 PPT。」

4. 明确可编辑格式

示例：「所有元素可编辑的 .pptx，不要图片贴片。」

PPT 技能默认生成原生可编辑的 PPTX 元素（文本框、表格、原生图表）。在任务中明确要求可编辑格式，可降低产出退化为整页图片的风险。后续在同一会话中要求修改 PPT 时，新版本文件仍会写入 output/ 目录，重新列出目录并取回文件即可。

进阶方向

批量生产：为每份 PPT 任务分别创建会话并并发执行，按会话取回产出，避免相互影响。各会话相互隔离。
嵌入自有系统：将审批和预览界面集成到自有业务看板，智能体仅负责生成 PPTX 文件。业务系统订阅事件流并按 output/ 约定取回文件，最终用户无需直接与智能体交互。
自建变体：基于上述起点模板和字段表调整配置：修改系统提示词以固定公司模板和内容口径，通过 skills 调整产出形式，通过 plugins 匹配行业数据源。
发布前人工确认：金融、品牌宣传等对外发布场景，应在自有系统中设置人工审核。业务系统订阅事件流并取回文件后，先提交人工审核，确认无误再发布。

下一步

运行官方 PPT 助手

从零走通一次官方 PPT 助手的完整调用。

查看 PPT 生成事件

订阅、断线续读与增量事件对账。

上传原始材料

上传原始材料、挂载会话与取回产出文件。

开始使用

定义智能体

配置执行环境

运行会话

上下文与记忆

高级编排

最佳实践

常见问题

场景与目标

设计思路

模型：长上下文和指令遵循优先

系统提示词：四条可复用的约定

技能：产物类技能决定产出形式

插件：数据能力按行业替换

工具：使用默认内置工具集

起点模板

资源准备

挂载原始材料调用

运行监控

写清任务描述

1. 优先提供原始材料

2. 明确页数、风格和受众

3. 数据类 PPT：指定数据源

4. 明确可编辑格式

进阶方向

下一步

运行官方 PPT 助手

查看 PPT 生成事件

上传原始材料

​场景与目标

​设计思路

​模型：长上下文和指令遵循优先

​系统提示词：四条可复用的约定

​技能：产物类技能决定产出形式

​插件：数据能力按行业替换

​工具：使用默认内置工具集

​起点模板

​资源准备

​挂载原始材料调用

​运行监控

​写清任务描述

​1. 优先提供原始材料

​2. 明确页数、风格和受众

​3. 数据类 PPT：指定数据源

​4. 明确可编辑格式

​进阶方向

​下一步

运行官方 PPT 助手

查看 PPT 生成事件

上传原始材料

场景与目标

设计思路

模型：长上下文和指令遵循优先

系统提示词：四条可复用的约定

技能：产物类技能决定产出形式

插件：数据能力按行业替换

工具：使用默认内置工具集

起点模板

资源准备

挂载原始材料调用

运行监控

写清任务描述

1. 优先提供原始材料

2. 明确页数、风格和受众

3. 数据类 PPT：指定数据源

4. 明确可编辑格式

进阶方向

下一步