制品与媒体

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.

HTML 项目与网页预览

publish_artifact 可以保留生成的整个 HTML 项目，而不是只发布其入口文件：

publish_artifact(
  path="site/index.html",
  bundle="directory",
  bundle_root="site",
)

bundle="auto"（默认）会跟随 HTML、CSS 和 JavaScript 中可静态识别的本地引用。缺失或被拒绝的引用会作为部分打包（partial bundle）上报。
bundle="directory" 会对整个专用项目目录做快照，如果其中包含被拒绝的路径或敏感文件，则原子性地失败。
bundle="none" 保留旧有的单文件行为。

历史遗留的单文件 HTML 无需迁移即可继续读取。如果它引用了从未被存储的本地 CSS、脚本或其他文件，则预览会被报告为部分（partial），而不是悄悄声称每个资源都已加载。

生成的 Web 项目应使用专用子目录和 directory 模式。Bundle 是静态站点： OpenSquilla 不会为它们启动 Vite、webpack、HMR 或项目后端。当项目需要这些服务时，请在 Desktop 的侧边浏览器中打开一个已在运行的开发服务器。

Desktop 以及以 loopback 方式访问的 Web UI 默认使用全网络预览。这会在一个临时、隔离的浏览器上下文中运行页面：普通的浏览器 JavaScript、模块、workers、 WebAssembly、WebGL、字体、媒体、HTTP(S)、WebSocket 以及页面级的 CORS/CSP 规则仍然适用，但页面不会获得任何 OpenSquilla 凭据、Node/Electron API、宿主文件或系统浏览器登录状态。Desktop 离线模式在保持 JavaScript 启用的同时，将网络访问限制在 artifact 自身，包括阻断 WebRTC/TURN/STUN 和推测性 DNS。浏览器承载的离线预览无法针对任意页面 JavaScript 强制执行那种全协议边界。因此它会在一个不透明沙箱中运行 bundle 脚本，并采用限制性的响应策略；外部网络访问被阻断，而 workers、service workers、持久化存储以及根绝对路径则不作保证。从另一台机器访问的 Web UI 始终被强制使用这种明显受限的离线预览。

在启动 Desktop 应用或 gateway 之前设置 OPENSQUILLA_PREVIEW_FORCE_OFFLINE=1，可作为一项事件响应措施禁用全网络 artifact 预览。

何时使用 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

内置支持的图像 provider 包括 OpenAI Images、OpenRouter Images 以及 Qwen Token Plan（wan2.7-image / wan2.7-image-pro）。Token Plan 使用 QWEN_TOKEN_PLAN_API_KEY；其图像生成 provider 与用于分析图像输入的 Qwen 模型是彼此独立的。

然后在聊天中请求图像：

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 未出现：

检查聊天或 CLI 输出中的 artifact 事件。
打开 Web UI session 并查看 artifact 卡片。
如果需要可靠的留存证据，导出 session：
```
opensquilla sessions export <session-key>
```
如果文档或媒体依赖缺失，运行 opensquilla doctor。

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