跳转到主要内容

Artifacts

Artifacts(产物)把 Xpert 智能体和插件生成的工作结果,转化为可以长期打开、回看、下载和分享的持久对象。 一个 Artifact 拥有稳定的产品身份。它的内容以不可变版本保存在 Workspace Files 中,访问入口则由独立的 Artifact Link 管理。因此,一份报告可以持续发布新版本而不改变自身身份;分享链接既可以始终指向最新版本,也可以固定在某个确定版本。
Artifact 不只是一条文件链接。Artifact 管理结果的身份和生命周期;Artifact Version 表示一次不可变内容快照;Artifact Link 决定谁可以访问哪个版本。

什么时候使用 Artifact

当聊天文本不适合承载结果,或者结果需要跨越一次智能体运行长期存在时,应使用 Artifact。典型场景包括:
  • 交互式 HTML 报告和数据看板;
  • Presentation Studio 生成的演示文稿;
  • Sites 生成的静态站点快照;
  • PDF 报告、PPTX、图片、CSV 和其他可下载文件;
  • 方案对比、带批注的评审、时间线和任务清单;
  • 插件后续会通过追加版本持续更新的业务结果。
例如,Presentation Studio 中的演示文稿可以继续在 Workbench 中协同编辑,每次 HTML 导出则成为一个 Artifact Version。用户既可以发布一条“始终分享最新版本”的链接,也可以把链接固定在评审时使用的确切版本。

Artifact 不是什么

Artifact 是发布后的工作结果,不是完整的托管应用运行时。
  • 它不会向访问者暴露插件后端或平台凭证。
  • 它不能替代带数据库、多路由和服务端逻辑的应用。
  • 分享 Artifact 不会让访问者获得协同编辑权限。
  • 交互式 HTML 可以运行安全策略允许的客户端交互,但不应在访问时依赖外部服务或平台 API。
  • 版本更新会被持久保存,但已经打开的页面目前需要刷新,才能让 latest 链接解析到新版本。
如果产品需要鉴权后的后端操作、持久化表单、多路由或实时协作,应使用 Agentic App 或 Sites 部署。

核心模型

内容字节仍保存在 Workspace Files 中。Artifacts 服务只保存可移植文件引用和产品元数据,不保存本地绝对路径,也不复制平台凭证。

创建 Artifact

Artifact 通常由 Xpert Agentic App 或插件在生成有价值的结果后创建。标准产品流程是:
  1. 生成或导出内容。
  2. 把内容写入 Workspace Files。
  3. 使用插件的业务资源身份创建或查找稳定的 Artifact 容器。
  4. 添加一个引用 Workspace Files 对象的不可变 Artifact Version。
  5. 按需创建预览链接或分享链接。
创建 Artifact 不等于对外公开。在创建链接之前,它只是当前租户和组织作用域中的私有平台对象。

更新 Artifact

发布更新内容时会创建新的 Artifact Version,已有版本不会被覆盖。 每个 Artifact 都有 currentVersionId。新版本默认成为当前版本;插件也可以只创建版本而不更新当前指针,从而支持评审和分阶段发布。 Artifact Link 有两种版本模式: 内容变化不会静默改写旧版本。如果要让固定版本链接展示新内容,必须显式调整链接目标或创建新链接。

预览 Artifact

正式发布前,可以使用 signed preview 进行临时预览。signed preview:
  • 使用 signed_preview 访问模式;
  • xpert_artifact_preview 查询参数中携带不透明 token;
  • 默认 15 分钟后过期;
  • 可在平台允许范围内设置更短或更长 TTL;
  • 不能作为长期公开 URL 保存。
预览 token 只在创建链接时返回。平台持久化的是 token 哈希,而不是 token 明文。

分享 Artifact

分享是施加在 Artifact Link 上的一次显式访问决策。公开 URL 中不会包含底层对话、智能体运行状态、插件工作区、租户 ID 或 Workspace Files 路径。 规范的公开访问路由是:
下载路由是:
slug 是随机生成的 12 位紧凑短码,是 Artifact Link 的公开标识,不是 Artifact ID 或数据库 UUID。插件必须复制平台返回的 publicUrl,不能根据浏览器当前地址自行拼接链接。

访问模式

创建 public_link 必须获得用户显式确认。智能体和插件不能静默把结果发布到公开网络。公开分享只暴露 Artifact 内容,对话和插件工作区仍保持私有。
链接还可以控制内容是浏览器内打开还是作为附件下载,以及是否允许使用专门的下载路由。

撤销、归档和删除

  • 当 Artifact 仍需内部保留,但某条访问入口必须失效时,使用撤销链接。撤销立即生效。
  • 当 Artifact 不应继续处于活动状态,但需要保留平台历史和审计记录时,使用归档 Artifact
  • 删除 Artifact会把 Artifact 标记为已删除,并撤销其所有链接。插件如果拥有底层 Workspace Files 文件,还应单独执行自己的文件保留或删除策略。
遇到已撤销、已过期、已归档或已删除内容时,平台会返回明确的访问错误,不会回退到其他版本或其他文件。

支持的内容

Artifact 的产品类型与 MIME 类型相互独立。支持的类型包括 htmlmarkdownpdfpptximagefilesitepresentation 推荐的展示行为: 平台会校验声明的 MIME 类型和被引用的 Workspace Files 对象。如果调用方提供了大小或 SHA-256,它们必须与实际存储内容一致。

HTML 安全策略

HTML Artifact 会带有 nosniffno-referrerno-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 负责身份、版本、访问、安全策略和审计。
该 capability 提供创建、追加版本、查询、列表、归档和删除 Artifact 的操作,也支持创建 signed preview、创建或更新链接,以及撤销链接。

插件职责

  • 使用稳定的 pluginName + resourceType + resourceId 标识 Artifact 容器。
  • 通过 Workspace Files 保存内容,只持久化可移植文件引用。
  • 创建新版本,不替换已经发布的内容字节。
  • 创建公开链接前取得用户显式确认。
  • 返回并复制平台提供的 publicUrl
  • 删除插件拥有的导出文件前先撤销相关链接。
  • 不在工具结果和日志中放入大文件正文、HTML、token 或私有标识。

当前版本边界

当前平台能力已经提供 Artifact 数据模型、不可变版本、基于 Workspace Files 的内容、作用域链接与公开链接、signed preview、访问计数和审计记录。平台级 Artifact Gallery、页面内自动实时更新、组织保留策略和合规管理界面可以在同一模型上继续建设;如果当前 Xpert 部署没有显式提供这些产品界面,不应假设它们已经可用。

相关资源