chatppt-agent（聊天 PPTAgent）

ChatPPT CLI Skill

环境准备

CLI 安装

运行npm命令进行安装，安装前先检查是否已存在chatppt命令。

npm install -g @yooai/cli

安装后可运行chatppt命令进行调用，比如：

chatppt --help

全局 Flag

标准工作流

1. 检查登录状态（auth status
2. 未登录 → 执行登录（auth login）
3. 生成 PPT（ppt generate 或 ppt import_file）
4. 自动轮询等待结果（直到 `2` 或 `3`）
5. 询问用户要直接下载pptx文件还是跳转到线上编辑器

Agent 执行强约束（必须遵守）

1. 严格流程顺序：始终按“检查登录 -> 登录（如需要） -> 生成 PPT -> 轮询结果”执行，不得跳步。
2. 路径二选一：在生成前必须询问用户选择：

- 普通生成路径 - 绘图生成路径

1. 自动提取参数：先从用户输入中自动提取可识别参数值；仅对缺失且必要的信息追问用户。
2. 用户不想配置参数：若用户明确表示不关心参数或不想填写，全部使用默认值发起请求。
3. 轮询展示图片：轮询期间如果返回 images.urls，可直接把图片链接展示给用户。
4. 成功即停止：当任务状态为 2或3 后，仅返回成功结果与关键信息，不执行任何后续操作（后续接口未就绪）。
5. Web Search 收费确认：--web-search 涉及额外收费，启用前必须先告知用户并获得明确确认；未确认则按关闭处理（传 --web-search=false）。
6. 如果已经进入到了自动轮询流程中，要一直等待轮询成功或失败，不能在轮询过程中又进行生成。如果是Agent手动轮询，也需要轮询到成功或失败，不能中途停止对话等待用户继续输入。
7. 如果轮询接口返回了失败，不要再次生成，要询问用户是否要再次生成。
8. 如果用户权益用完了，提示用户去clawppt官网 <https://chat-ppt.com/openclaw> 进行充值点数。

参数提取与追问规则（Agent）

1. 先提取后追问：先从用户自然语言中提取参数（主题、路径选择、样式参数等），再补问缺失信息。
2. 最小追问原则：仅追问生成任务必需信息（如 主题 或导入时的 文件路径）。
3. 路径参数边界：

- 普通生成路径只处理：font-name、theme-color、ai-picture、image-style、template-id、custom-template-id、custom-page-count - 绘图生成路径只处理：banana-style-id、banana-doc-type、banana-reference-image

1. 默认值策略：若用户明确“不想设置参数/你看着办/默认就行”，则所有未指定参数使用默认值，不再反复追问。
2. 收费项单独确认：web-search 为额外收费项，不能并入“默认就行”；必须单独征得用户同意后才启用。

确认普通生成与绘图生成路径后的参数提取与追问规则（Agent）

1. 模板风格确认：在普通生成和绘图生成中，都需要询问用户是否需要预览模板风格并指定模板生成。

- 普通生成路径参数：template-id - 绘图生成路径参数：banana-style-id

1. 普通生成路径中的图片风格确认：在普通生成中询问用户是否需要指定AI图片风格，如果指定了，则参数--ai-picture必须等于true。参考--image-style参数获取方式。
2. 绘图生成排版风格确认：在绘图模式中还需要确认用户是否需要指定排版样式，如果需要，参考--banana-doc-type参数获取方式。

命令速查

chatppt auth — 认证管理

所有 PPT 生成命令都需要先登录。

# 查看当前登录状态
chatppt auth status

# 登录（默认自动打开浏览器）
chatppt auth login

# 登录但不自动打开浏览器
chatppt auth login --no-browser

# 刷新令牌（令牌即将过期时使用）
chatppt auth refresh

# 登出
chatppt auth logout

典型返回（status）

{
  "success": true,
  "code": 200,
  "data": {
    "is_logged_in": true,
    "user": { "id": "string", "nickname": "string", "mobile": "string" }
  }
}

chatppt ppt generate — 根据主题生成 PPT

普通生成

chatppt ppt generate "主题描述" [options]

绘图生成

chatppt ppt generate_banana "主题描述" [options]

必填

可选参数（公共）

普通生成路径参数（与 Banana 路径平级）

约束说明： - 在生成之前询问用户是否需要浏览并指定模板，需要的话调用chatppt ppt template获取--template-id参数数据，调用之后的数据，一定要将每一项的至少一张图片展示给用户挑选。

--image-style 参数获取方式

chatppt ppt picture_style

--template-id 参数获取方式

获取PPT模板风格列表，支持分页查询

支持查看模板的详细信息，包括： - 模板ID、标题、风格描述 - 预览图片（封面、章节页、内容页、目录页） - 配色方案

示例: chatppt ppt template # 获取第1页，每页10个 chatppt ppt template --page 2 # 获取第2页 chatppt ppt template --limit 20 # 每页显示20个 chatppt ppt template --page 2 --limit 5 # 获取第2页，每页5个

chatppt ppt template

绘图生成路径参数（与普通路径平级）

约束说明： - 绘图生成路径参数允许全部为空。 - 普通路径与绘图生成路径是两条平级路线，不存在“更高级”关系。 - Agent 必须先确认用户走哪条路径，再组装对应参数。 - 生成任务默认开启轮询（--poll=true），接口内自动调用轮询接口持续查询直到 SUCCESS 或 FAILED。 - 在生成之前询问用户是否需要浏览并指定风格，需要的话调用chatppt ppt banana-template获取--banana-style-id参数数据。

--banana-style-id 页面绘图风格参数获取方式

获取绘图生成PPT模板风格列表，支持分页查询

支持查看模板的详细信息，包括： - 模板ID、标题、风格描述 - 预览图片（封面、章节页、内容页、目录页） - 配色方案

示例: chatppt ppt banana-template # 获取第1页，每页10个 chatppt ppt banana-template --page 2 # 获取第2页 chatppt ppt banana-template --limit 20 # 每页显示20个 chatppt ppt banana-template --page 2 --limit 5 # 获取第2页，每页5个

chatppt ppt banana-template

--banana-doc-type 页面排版样式参数获取方式

chatppt ppt template_banana_style

示例

# 基础生成
chatppt ppt generate "人工智能发展趋势" --language zh

# 普通生成路径（带样式）
chatppt ppt generate "2024年度工作总结" \
  --language zh \
  --font-name "微软雅黑" \
  --theme-color blue \
  --custom-page-count 15 \
  --image-style "商务风"

# 绘图生成风格路径（参数可部分或全部为空）
chatppt ppt generate_banana "产品介绍" \
  --banana-style-id style_001 \
  --banana-doc-type business

# 异步模式（不等待结果，手动查询）
chatppt ppt generate "主题" --poll=false

成功返回

{
  "success": true,
  "code": 200,
  "data": {
    "ppt_id": "ppt_1234567890",
    "request_id": "string",
    "title": "string",
    "task_status": "2",
    "images": {
      "urls": [{ "url": "https://example.com/ppt/slide1.jpg" }]
    }
  }
}

task_status 说明

chatppt import file — 文件导入生成 PPT

上传本地文件后基于其内容生成 PPT，适合将现有 Word / PDF / Markdown 转为演示文稿。

导入生成普通PPT

chatppt ppt import_file --file-path "/绝对路径/文档.docx"

导入生成绘图PPT

chatppt ppt import_file_banana --file-path "/绝对路径/文档.docx"

必填

支持格式

文本文件须为 UTF-8 编码。

其余可选参数与 ppt generate 完全相同，包括普通路径参数与 Banana 路径参数。

示例

# Word 文档导入
chatppt ppt import_file \
  --file-path "/Users/me/docs/product.docx" \
  --theme-color 蓝色

# PDF 导入，绘图生成风格
chatppt ppt import_file_banana \
  --file "/Users/me/docs/annual.pdf" \
  --banana-style-id style_002 \
  --banana-doc-type business 

返回格式与 ppt generate 相同。

chatppt ppt result — 查询 PPT 生成结果

在异步模式（--poll=false）下使用，主动查询任务状态。

chatppt ppt result <ppt_id> [-f pretty]

config — 配置管理

# 查看当前配置
chatppt config show

# 重新加载配置文件
chatppt config reload

典型返回（show）

{
  "success": true,
  "code": 200,
  "data": {
    "app": { "name": "ChatPPT CLI", "version": "1.0.0" },
    "api": { "url": "http://localhost:9157", "timeout": 30000 },
    "auth": { "type": "Bearer", "access_key_id": "csVyGKphwM..." },
    "ppt": { "default_ai_picture": true }
  }
}

生成下载链接 chatppt downloadppt

chatppt ppt downloadppt [ppt-id]

生成线上编辑器链接 chatppt editor

chatppt ppt editor [ppt-id]

错误处理

常见错误码

通用错误格式

{
  "success": false,
  "code": 400,
  "message": "错误描述",
  "error_type": "VALIDATION_ERROR",
  "error_details": { "field": "topic", "reason": "主题长度必须在 1-200 字符之间" },
  "suggestion": "请检查输入参数并重试"
}

注意事项

• 并发限制：同一用户同时只能有一个 PPT 生成任务，需串行执行。
• 文件上传：依赖百度 BOS 服务，需正确配置 BCE 参数（AK/SK、Bucket 权限）。
• 令牌自动刷新：运行时令牌过期会自动刷新；刷新失败则需重新 auth login。
• 敏感信息：勿在日志中记录 AK/SK 或密码；定期清理云端不再使用的 PPT 文件。
• Agent 提问策略：优先自动提取用户输入中的参数；仅在缺失关键信息时追问；若用户不想配置参数，按默认值执行。