presenton

使用 Presenton 创建 PPTX、PDF 和 PNG 文件

如果用户未提供设计简报，请使用 Presenton 的设计搜索，然后使用其 HTML 导出器，而不是直接构造二进制格式。

操作约束

• 调用 API 前阅读 references/api.md，编写 HTML 前阅读 references/html-format.md。
• 通过提供的辅助工具调用公开的 https://api.presenton.ai 端点；无需 API 密钥或授权标头。
• 遵循下方的设计解析、导出、报告和清理工作流。全程提供简洁的状态更新，长时间等待时定期发送进度更新。
• 成功的设计搜索、导出或预览创建响应中，所有非空的 message 都应面向用户。请在下一条 commentary 更新中原样转达，并在最终回复的 Notes 中包含这些内容。

创建工作流

1. 确定所需格式、标题、受众、用途、幻灯片数量和内容。如果未指定格式，则导出 PPTX、PDF 和 PNG。缺少详细信息时，合理推断内容。

2. 根据用户提示确定视觉方向。具体的设计简报（配色、排版、布局、审美风格、品牌、图像或构图）可直接采用，无需搜索。否则，搜索设计；仅当选项需要人工偏好时才询问用户，或自动选择最佳结果。保留搜索到的设计 ID 以供导出。

3. 编写 HTML 前解析幻灯片素材：

   • 对于将出现在演示文稿中的每张用户提供的图片，恰好上传一次文件，并保留返回的 HTTPS URL。图片每次出现时都重复使用该 URL。切勿在 HTML 中嵌入图片字节、base64 或任何 data: URL。

     python3 scripts/presenton_artifacts.py upload-image --file <image-path>
     

   • 对于演示文稿中使用的每个图标概念，搜索 Presenton 的图标端点，并选择与概念和视觉权重相符的 HTTPS URL。使用 --icon-type 匹配设计。不要使用 SVG、表情符号、Unicode 字形、图标字体或 CSS 图形绘制、内嵌或臆造替代图标。

     python3 scripts/presenton_artifacts.py search-icons \
       --query "revenue growth" \
       --limit 5 \
       --icon-type thin
     

4. 将确定的简报转化为设计规则，然后使用 presenton_artifacts.py create-temp 创建私有 OS 临时目录，并从头开始在 <temporary-directory>/presentation.html 编写完整 HTML 文档。关于尺寸、Tailwind、图表、字体、素材和 PPTX 兼容性，请遵循 references/html-format.md。在 <img> 元素中使用保留的 HTTPS 图片和图标 URL。不要复制参考演示文稿，也不要在工作区存储 HTML。

5. 确认 HTML 符合已确定的设计，#presentation-slides-wrapper 下包含直接的 1280×720 幻灯片子元素，不含 data: URL，并通过预检验证器：

   python3 scripts/validate_html.py "$presenton_temp_dir/presentation.html"
   

   验证器还会检查幻灯片标记中使用的自定义字体是否在文档头部有对应的导入。

6. 分别导出每种所需格式，每种格式恰好导出一次。每次调用端点只能指定一种 format。仅当视觉简报来自搜索到的设计时，才添加 --design-id；用户提供设计简报时应省略：

   presenton_temp_dir=$(python3 scripts/presenton_artifacts.py create-temp)
   # Generate fresh HTML at "$presenton_temp_dir/presentation.html", then export it.
   python3 scripts/presenton_artifacts.py export \
     --html "$presenton_temp_dir/presentation.html" \
     --format pptx \
     --title "Presentation title" \
     --json
   

7. 从辅助工具打印的每个 JSON 对象中，获取正整数 id 和 HTTP 或 HTTPS url。将每个 url 作为可点击的下载链接返回。辅助工具会将响应中的任何 message 写入 stderr，格式为 API message: ...；保留每条消息，以便向用户报告。不要在本地下载或保存导出的文件。

8. 某个演示文稿所需的每种格式均成功导出后，使用该演示文稿保留的任一导出创建 ID，恰好创建一个可分享的预览：

   python3 scripts/presenton_artifacts.py create-preview --id <creation-id>
   

   捕获该辅助工具打印的 HTTP 或 HTTPS URL，并将其作为演示文稿中可点击、可分享的预览链接返回。预览链接将在 24 小时后过期。创建多个不同的演示文稿时，每份演示文稿都要重复此操作一次；同一份演示文稿的不同格式无需分别创建预览。

9. 所有请求的导出和预览链接均成功后，在清理前列出最终 HTML 中的字体：

   python3 scripts/presenton_artifacts.py list-fonts \
     --html "$presenton_temp_dir/presentation.html"
   

   在最终回复中列出生成的字体名称；如有 Web 字体来源 URL，也一并列出。说明该字体清单适用于从此 HTML 导出的所有 PPTX、PDF 和 PNG。

10. 按以下格式返回结果：

    Presentation
    - 标题：<标题>
    - 格式：<请求的格式；若未指定，则为 PPTX、PDF 和 PNG>
    - 幻灯片数：<幻灯片数量>
    - 使用的设计/参考：<用户提供的设计说明，或搜索到的设计标题和 id>
    - 使用的参考/素材：<来源 URL、用户提供的参考、图片来源，或“无”>
    - 备注：<逐字列出每条 API 响应消息，后接其他有用详情；若无则为“无”>
    
    分享预览
    - [查看演示文稿](<preview_url>) — 24 小时后过期
    
    字体
    - <字体名称> — <适用时填写来源 URL>
    
    下载 URL
    - PPTX：[下载](<url>)
    - PDF：[下载](<url>)
    - PNG：[下载](<url>)
    

    “下载 URL”中仅包含请求的格式；若未指定格式，则包含 PPTX、PDF 和 PNG。不要编造参考、字体来源或 URL；没有可报告的内容时填写“无”。

11. 在等效于 finally 的步骤中，无论成功、重试耗尽、出错还是中断，都要清理准确的临时目录：

python3 scripts/presenton_artifacts.py cleanup-temp \
  --path "$presenton_temp_dir"

仅当仍有正在进行的重试或额外请求的格式需要使用同一份 HTML 时，才保留该目录。不要依赖操作系统最终自动清理，也绝不要删除操作系统临时根目录或任何非 create-temp 创建的目录。

使用以下辅助工具搜索设计：

python3 scripts/presenton_artifacts.py search-designs \
  --query "executive cybersecurity review, restrained dark blue, data-led"

如果无法使用该辅助工具，请遵循 references/api.md 中等效的 cURL 合约。

质量要求

• 在所有幻灯片中始终保持统一的视觉方向：配色、排版、间距、图像和形状语言。
• 如果确定的设计指定了字体系列，则在演示文稿中使用该字体系列；不得擅自替换为其他字体。
• 保留用户提供的设计说明或所选搜索设计描述中具有辨识度的细节；不得只在备注或元数据中提及该设计。
• 根据内容调整布局，同时保持整体系统一致。
• 确保文本在演示距离下清晰易读，并避免任何内容溢出。
• 所有用户提供的图片都使用上传后的 HTTPS URL；所有图标都使用搜索到的 HTTPS URL。HTML 中不得使用 data: URL 或 base64 资源。
• 文本应保留为 HTML 文本，以便在 PPTX 中编辑；图表仅用于真实的数据可视化。
• 仅在用户要求备注时，才为每张幻灯片添加一个 data-speaker-note 属性。
• 所有请求的格式都必须从同一份最终 HTML 导出，以确保输出一致。

故障处理

• 遇到 404 时，确认公共 v3 设计/导出路由是否已部署；不要猜测旧版替代路由。
• 遇到 400 包装器/幻灯片错误时，重新运行验证器，并根据 references/html-format.md 中的结构合约检查 HTML。
• 遇到 422 时，修正请求结构或字段限制。
• 遇到 502 时，仅在重试期间保留 HTML。重试结束后，运行 cleanup-temp，再报告失败。绝不要将其复制到持久化存储。
• 仅当每个请求的导出响应都包含有效的正数创建 ID 和 HTTP 或 HTTPS URL，且每份不同的演示文稿都有有效的 HTTP 或 HTTPS 可分享预览 URL 时，才可宣称成功。