chatppt-agent

使用 ChatPPT CLI 命令行工具通过 AI 自动生成 PPT 演示文稿。适用场景：用户需要根据主题文字或现有文件（Word/PDF/Markdown）生成 PPT 时触发本 skill。支持登录认证、PPT 生成、文件导入生成、结果查询等完整流程。

ChatPPT CLI Skill

环境准备

CLI 安装

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

npm install -g @yooai/cli

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

chatppt --help

全局 Flag

Flag	说明
--config string	配置文件路径（默认 $HOME/.chatppt/config.yaml）
-d, --debug	启用调试模式
-f, --format string	输出格式：json（默认）/ table / pretty
-h, --help	帮助
-v, --version	版本

---

标准工作流

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

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

1. 严格流程顺序：始终按“检查登录 -> 登录（如需要） -> 生成 PPT -> 轮询结果”执行，不得跳步。
2. 路径二选一：在生成前必须询问用户选择：
   • 普通生成路径
   • 绘图生成路径
3. 自动提取参数：先从用户输入中自动提取可识别参数值；仅对缺失且必要的信息追问用户。
4. 用户不想配置参数：若用户明确表示不关心参数或不想填写，全部使用默认值发起请求。
5. 轮询展示图片：轮询期间如果返回 images.urls，可直接把图片链接展示给用户。
6. 成功即停止：当任务状态为 2或3 后，仅返回成功结果与关键信息，不执行任何后续操作（后续接口未就绪）。
7. Web Search 收费确认：--web-search 涉及额外收费，启用前必须先告知用户并获得明确确认；未确认则按关闭处理（传 --web-search=false）。
8. 如果已经进入到了自动轮询流程中，要一直等待轮询成功或失败，不能在轮询过程中又进行生成。如果是Agent手动轮询，也需要轮询到成功或失败，不能中途停止对话等待用户继续输入。
9. 如果轮询接口返回了失败，不要再次生成，要询问用户是否要再次生成。
10. 如果用户权益用完了，提示用户去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
4. 默认值策略：若用户明确“不想设置参数/你看着办/默认就行”，则所有未指定参数使用默认值，不再反复追问。
5. 收费项单独确认：web-search 为额外收费项，不能并入“默认就行”；必须单独征得用户同意后才启用。

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

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

---

命令速查

目标	命令
查看登录状态	auth status
登录	auth login
登出	auth logout
刷新令牌	auth refresh
生成 PPT（主题文字）	ppt generate "主题"
生成绘图PPT（主题文字）	ppt generate_banana "主题"
生成 PPT（文件导入）	ppt import_file "/path/to/file"
生成绘图PPT（文件导入）	ppt import_file_banana "/path/to/file"
查询 PPT 结果	ppt result <ppt_id>
查看配置	config show
重载配置	config reload
查看版本	version

---

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]

必填

参数	说明
主题描述	PPT 主题，1–200 字符

可选参数（公共）

参数	类型	默认值	说明
--complex	int	0	内容复杂度 1=简单，2=中等，3=复杂
--language	string	—	语言：zh-CN / en-US / zh-TW
--web-search	bool	false	联网补充内容（额外收费，启用前需用户明确确认）
--poll	bool	true	是否自动轮询等待结果
--interval	int	5	轮询间隔（秒）
--max-retries	int	60	最大轮询次数（约 5 分钟）

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

参数	类型	默认值	说明
--font-name	string	—	字体名，如 微软雅黑
--theme-color	string	—	主题色：蓝色 红色 绿色 橙色 紫色 黄色 粉色
--ai-picture	bool	true	是否启用 AI 配图
--image-style	string	—	配图风格描述，如 商务风
--template-id	string	—	预制矢量模板 ID
--custom-template-id	string	—	自定义模板 ID
--custom-page-count	int	0	页数，0 = 自动

约束说明：

• 在生成之前询问用户是否需要浏览并指定模板，需要的话调用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

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

参数	类型	说明
--banana-style-id	string	绘图风格ID
--banana-doc-type	string	绘图排版样式
--banana-reference-image	string	参考图片 URL 或路径

约束说明：

• 绘图生成路径参数允许全部为空。
• 普通路径与绘图生成路径是两条平级路线，不存在“更高级”关系。
• 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 说明

值	含义
1	生成中
2	已完成
3	失败

---

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"

必填

参数	说明
--file-path	本地文件绝对路径

支持格式

格式	扩展名	大小上限
Word	.doc .docx	100 MB
PDF	.pdf	100 MB
Markdown	.md	100 MB
纯文本	.txt	100 MB

文本文件须为 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]

参数	说明
ppt_id	ppt generate / ppt import_file 返回的 ppt_id
-f	输出格式（继承全局 flag）

---

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]

---

错误处理

常见错误码

错误码	原因	处理
400	参数错误（topic 超长、路径无效等）	修正参数后重试
401	未登录或令牌失效	执行 auth login
403	文件上传权限不足	检查 BCE AK/SK 配置
413	文件超过 100 MB	压缩或拆分文件
429	请求频率过高	等待 5 秒后重试，最多 3 次
500	服务端错误	等待 10 秒后重试，最多 3 次

通用错误格式

{
  "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 提问策略：优先自动提取用户输入中的参数；仅在缺失关键信息时追问；若用户不想配置参数，按默认值执行。