Skill: kahn520/chatppt-agent (version 1.0.4)

--- name: chatppt-cli description: 使用 ChatPPT CLI 命令行工具通过 AI 自动生成 PPT 演示文稿。适用场景：用户需要根据主题文字或现有文件（Word/PDF/Markdown）生成 PPT 时触发本 skill。支持登录认证、PPT 生成、文件导入生成、结果查询等完整流程。 --- # ChatPPT CLI Skill ## 环境准备 ### CLI 安装 运行npm命令进行安装，安装前先检查是否已存在chatppt命令。 ```bash npm install -g @yooai/cli ``` 安装后可运行chatppt命令进行调用，比如： ```bash 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 生成命令都需要先登录。 ```bash # 查看当前登录状态 chatppt auth status # 登录（默认自动打开浏览器） chatppt auth login # 登录但不自动打开浏览器 chatppt auth login --no-browser # 刷新令牌（令牌即将过期时使用） chatppt auth refresh # 登出 chatppt auth logout ``` **典型返回（status）** ```json { "success": true, "code": 200, "data": { "is_logged_in": true, "user": { "id": "string", "nickname": "string", "mobile": "string" } } } ``` --- ## chatppt ppt generate — 根据主题生成 PPT **普通生成** ```bash chatppt ppt generate "主题描述" [options] ``` **绘图生成** ```bash 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 参数获取方式 ```bash 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个 ```bash 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个 ```bash chatppt ppt banana-template ``` #### --banana-doc-type 页面排版样式参数获取方式 ```bash chatppt ppt template_banana_style ``` ### 示例 ```bash # 基础生成 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 ``` ### 成功返回 ```json { "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** ```bash chatppt ppt import_file --file-path "/绝对路径/文档.docx" ``` **导入生成绘图PPT** ```bash 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 路径参数。 ### 示例 ```bash # 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`）下使用，主动查询任务状态。 ```bash chatppt ppt result <ppt_id> [-f pretty] ``` | 参数 | 说明 | |------|------| | `ppt_id` | `ppt generate` / `ppt import_file` 返回的 `ppt_id` | | `-f` | 输出格式（继承全局 flag） | --- ## config — 配置管理 ```bash # 查看当前配置 chatppt config show # 重新加载配置文件 chatppt config reload ``` **典型返回（show）** ```json { "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 ```bash chatppt ppt downloadppt [ppt-id] ``` --- ## 生成线上编辑器链接 chatppt editor ```bash chatppt ppt editor [ppt-id] ``` --- ## 错误处理 ### 常见错误码 | 错误码 | 原因 | 处理 | |--------|------|------| | 400 | 参数错误（topic 超长、路径无效等） | 修正参数后重试 | | 401 | 未登录或令牌失效 | 执行 `auth login` | | 403 | 文件上传权限不足 | 检查 BCE AK/SK 配置 | | 413 | 文件超过 100 MB | 压缩或拆分文件 | | 429 | 请求频率过高 | 等待 5 秒后重试，最多 3 次 | | 500 | 服务端错误 | 等待 10 秒后重试，最多 3 次 | ### 通用错误格式 ```json { "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 提问策略**：优先自动提取用户输入中的参数；仅在缺失关键信息时追问；若用户不想配置参数，按默认值执行。


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)