chatppt-agent

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

Security Scan

The skill's instructions generally match a CLI-based PPT generator, but there are several mismatches and privacy/installation risks (undeclared binary requirement, npm global install of an unverified package, and implicit access to local config/tokens) that you should review before installing or running it.

Purpose & Capability

The skill claims no required binaries or credentials in registry metadata, but the SKILL.md explicitly requires the 'chatppt' CLI (installed via `npm install -g @yooai/cli`). Requiring a global CLI is coherent with the described purpose, but the registry metadata omits that requirement — an inconsistency users should be aware of.

Instruction Scope

Instructions tell the agent to run commands that affect authentication, show config, import local files (e.g., `ppt import_file "/path/to/file"`), and display configuration/preview images. Those actions can expose local files and config (tokens) and will upload user-specified files to the remote service — which is coherent with the feature but not declared in metadata and has privacy implications.

Install Mechanism

There is no install spec in the registry, but SKILL.md instructs installing an npm package globally (`npm install -g @yooai/cli`). That is an ad-hoc, user-run install of remote code (unverified publisher). Because the package source/repo/homepage is not provided, this raises supply-chain and trust concerns.

Credentials

The registry lists no required env vars or credentials, yet the CLI uses a config file at $HOME/.chatppt/config.yaml and authentication flows (auth login/refresh). Running `config show` or auth commands may surface tokens/credentials. The skill does not declare these access expectations, which is disproportionate to the metadata and increases the chance of secrets exposure.

Persistence & Privilege

The skill is not always-enabled and does not request elevated/persistent privileges in the registry metadata. It is user-invocable and allows autonomous invocation (platform default) but does not request unusual persistent presence or modification of other skills.

What to consider before installing

Before installing or running this skill: (1) treat the SKILL.md instruction to run `npm install -g @yooai/cli` as pulling and executing remote code — only proceed if you trust the package and its publisher; (2) inspect the package (npm page or GitHub repo) and prefer to run it in a sandbox or container rather than installing globally; (3) be aware the CLI will prompt for login and stores tokens in $HOME/.chatppt/config.yaml — running commands like `config show` or `ppt import_file` can expose local config and upload local files to the service; (4) if you need stronger guarantees, ask the skill author for the package repository/homepage, cryptographic release artifacts, or a vetted install mechanism; (5) if you must use it, avoid running it on machines with sensitive credentials or files, do not grant it access to system-wide secrets, and prefer manual invocation over letting an autonomous agent run install/auth commands on your behalf.

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