制品与媒体

OpenSquilla 可在 agent 工作过程中创建并交付文件：报告、HTML 文件、PDF、幻灯片、电子表格、生成的图片以及其他 artifact。当输出过大、可视化、结构化或重要到不应仅以聊天文本形式留存时，使用 artifact。

Artifact

Artifact 是在 session 期间创建、对用户可见的文件。在 Web UI 聊天中，当 runtime 发布它们时会以 artifact 卡片形式出现。在 CLI 运行中，artifact 事件可包含文件名、id 和下载 URL。

常见用例：

• 生成报告；
• 创建独立的 HTML 原型；
• 构建 CSV/XLSX 工作簿；
• 创建 PDF 简报；
• 制作幻灯片；
• 为 channel 投递打包生成的输出。

直接提出请求：

Create a one-page HTML dashboard from this data and publish it as an artifact.

Generate a PDF briefing with sources and publish the final file.

何时使用 Artifact 而非聊天

在以下情况使用 artifact：

• 用户需要下载或分享的文件；
• 需要排版的表格或报告；
• 生成的应用、仪表盘或原型；
• 在聊天中显得笨拙的长输出；
• 平台支持文件上传的 channel 投递。

将聊天文本用于简短回答、决策和后续步骤。

文档 Skill

OpenSquilla 内置了用于常见文档格式的 skill：

• docx 用于 Word 文档；
• pptx 用于 PowerPoint 幻灯片；
• xlsx 用于 Excel 工作簿；
• pdf-toolkit 用于结构化 PDF 处理；
• html-to-pdf 用于带样式的 PDF 渲染。

发现它们：

opensquilla skills search pdf
opensquilla skills view pptx
opensquilla skills view xlsx

某些文档功能需要可选的原生/系统依赖。使用 opensquilla skills list 和 opensquilla doctor 检查就绪状态。

图像输入与生成

在终端聊天中，发送图像进行分析：

/image /path/to/screenshot.png Describe what is wrong with this UI.

配置图像生成：

opensquilla configure image-generation

然后在聊天中请求图像：

Generate a clean product mockup image for this landing page.

图像 provider 的支持情况取决于已配置的 provider 凭据、可选依赖以及 runtime 策略。

文本转语音与媒体辅助工具

媒体工具族包含图像、PDF 和 TTS 辅助工具。其可用性可能取决于 provider 配置、可选依赖和 runtime 策略。

当请求的输出本质上是文件或资产而非纯文本回答时，使用媒体辅助工具。

Channel 投递

各 channel 在文件大小限制、线程行为和上传 API 上各有不同。如果某个 channel 无法直接投递 artifact，请使用 Web UI 的 artifact 卡片或 session 导出作为兜底入口。

关于 channel 配置，参见 channels.md。

排障

如果 artifact 未出现：

1. 检查聊天或 CLI 输出中的 artifact 事件。

2. 打开 Web UI session 并查看 artifact 卡片。

3. 如果需要可靠的留存证据，导出 session：

   opensquilla sessions export <session-key>

4. 如果文档或媒体依赖缺失，运行 opensquilla doctor。

文档索引 · 产品指南 · 改进此页面 · 报告文档问题