Artifacts
Artifacts(产物)把 Xpert 智能体和插件生成的工作结果,转化为可以长期打开、回看、下载和分享的持久对象。 一个 Artifact 拥有稳定的产品身份。它的内容以不可变版本保存在 Workspace Files 中,访问入口则由独立的 Artifact Link 管理。因此,一份报告可以持续发布新版本而不改变自身身份;分享链接既可以始终指向最新版本,也可以固定在某个确定版本。什么时候使用 Artifact
当聊天文本不适合承载结果,或者结果需要跨越一次智能体运行长期存在时,应使用 Artifact。典型场景包括:- 交互式 HTML 报告和数据看板;
- Presentation Studio 生成的演示文稿;
- Sites 生成的静态站点快照;
- PDF 报告、PPTX、图片、CSV 和其他可下载文件;
- 方案对比、带批注的评审、时间线和任务清单;
- 插件后续会通过追加版本持续更新的业务结果。
Artifact 不是什么
Artifact 是发布后的工作结果,不是完整的托管应用运行时。- 它不会向访问者暴露插件后端或平台凭证。
- 它不能替代带数据库、多路由和服务端逻辑的应用。
- 分享 Artifact 不会让访问者获得协同编辑权限。
- 交互式 HTML 可以运行安全策略允许的客户端交互,但不应在访问时依赖外部服务或平台 API。
- 版本更新会被持久保存,但已经打开的页面目前需要刷新,才能让
latest链接解析到新版本。
核心模型
内容字节仍保存在 Workspace Files 中。Artifacts 服务只保存可移植文件引用和产品元数据,不保存本地绝对路径,也不复制平台凭证。
创建 Artifact
Artifact 通常由 Xpert Agentic App 或插件在生成有价值的结果后创建。标准产品流程是:- 生成或导出内容。
- 把内容写入 Workspace Files。
- 使用插件的业务资源身份创建或查找稳定的 Artifact 容器。
- 添加一个引用 Workspace Files 对象的不可变 Artifact Version。
- 按需创建预览链接或分享链接。
更新 Artifact
发布更新内容时会创建新的 Artifact Version,已有版本不会被覆盖。 每个 Artifact 都有currentVersionId。新版本默认成为当前版本;插件也可以只创建版本而不更新当前指针,从而支持评审和分阶段发布。
Artifact Link 有两种版本模式:
内容变化不会静默改写旧版本。如果要让固定版本链接展示新内容,必须显式调整链接目标或创建新链接。
预览 Artifact
正式发布前,可以使用 signed preview 进行临时预览。signed preview:- 使用
signed_preview访问模式; - 在
xpert_artifact_preview查询参数中携带不透明 token; - 默认 15 分钟后过期;
- 可在平台允许范围内设置更短或更长 TTL;
- 不能作为长期公开 URL 保存。
分享 Artifact
分享是施加在 Artifact Link 上的一次显式访问决策。公开 URL 中不会包含底层对话、智能体运行状态、插件工作区、租户 ID 或 Workspace Files 路径。 规范的公开访问路由是:publicUrl,不能根据浏览器当前地址自行拼接链接。
访问模式
链接还可以控制内容是浏览器内打开还是作为附件下载,以及是否允许使用专门的下载路由。
撤销、归档和删除
- 当 Artifact 仍需内部保留,但某条访问入口必须失效时,使用撤销链接。撤销立即生效。
- 当 Artifact 不应继续处于活动状态,但需要保留平台历史和审计记录时,使用归档 Artifact。
- 删除 Artifact会把 Artifact 标记为已删除,并撤销其所有链接。插件如果拥有底层 Workspace Files 文件,还应单独执行自己的文件保留或删除策略。
支持的内容
Artifact 的产品类型与 MIME 类型相互独立。支持的类型包括html、markdown、pdf、pptx、image、file、site 和 presentation。
推荐的展示行为:
平台会校验声明的 MIME 类型和被引用的 Workspace Files 对象。如果调用方提供了大小或 SHA-256,它们必须与实际存储内容一致。
HTML 安全策略
HTML Artifact 会带有nosniff、no-referrer、no-store、安全的 Content-Disposition 和内容安全策略(CSP)。表单不能提交,文档不能设置 base URL,Artifact 也不能被其他页面嵌入。
Artifact 内容不能包含平台 token、租户或组织标识、Workspace Files 路径、签名 URL 或其他凭证。插件在发布前应校验用户输入的 HTML、SVG、URL 和媒体内容。
插件接入 Artifacts
插件通过@xpert-ai/plugin-sdk 提供的 platform.artifacts runtime capability 使用平台能力。Workspace Files 仍负责内容存储;Artifacts 负责身份、版本、访问、安全策略和审计。
插件职责
- 使用稳定的
pluginName + resourceType + resourceId标识 Artifact 容器。 - 通过 Workspace Files 保存内容,只持久化可移植文件引用。
- 创建新版本,不替换已经发布的内容字节。
- 创建公开链接前取得用户显式确认。
- 返回并复制平台提供的
publicUrl。 - 删除插件拥有的导出文件前先撤销相关链接。
- 不在工具结果和日志中放入大文件正文、HTML、token 或私有标识。
当前版本边界
当前平台能力已经提供 Artifact 数据模型、不可变版本、基于 Workspace Files 的内容、作用域链接与公开链接、signed preview、访问计数和审计记录。平台级 Artifact Gallery、页面内自动实时更新、组织保留策略和合规管理界面可以在同一模型上继续建设;如果当前 Xpert 部署没有显式提供这些产品界面,不应假设它们已经可用。相关资源
- 插件开发
- Remote Component 与 Agentic App
- Claude Code Artifacts,Xpert Artifacts 产品概念的参考来源