ArtifactsRuntimeCapability 通过 platform.artifacts 暴露 ArtifactsApi。它管理插件与智能体生成的持久化交付物,包括 HTML、Markdown、PDF、PowerPoint、图片、普通文件、站点和演示文稿。
产物内容字节存放在工作区文件中。产物服务在此基础上增加稳定业务身份、不可变版本历史、受治理访问链接、生命周期状态和访问计数。
数据模型
产物流程分为三层:- 产物容器:由
pluginName、resourceType和resourceId定义的稳定插件业务身份。 - 产物版本:由
WorkspacePortableFileReference、MIME 类型、校验和与元数据描述的不可变内容。 - 产物链接:包含版本策略、访问模式、过期时间和展示策略的打开、共享或下载入口。
kind 类型支持 html、markdown、pdf、pptx、image、file、site 和 presentation。
容器与版本方法
容器状态为
active、archived 或 deleted;版本状态为 active 或 deleted。
链接与共享方法
链接状态为
active、revoked 或 expired。versionMode: 'latest' 始终跟随当前产物版本;versionMode: 'version' 固定到某个不可变版本。
访问模式包括:
owner_onlyworkspace_allorganization_allcustom_principalspublic_linksigned_preview
inline 或 attachment,可控制是否允许下载,还可应用 strict 或 interactive 安全 HTML 配置。
发布生成文件
先将字节写入工作区文件,再创建或复用产物版本和共享:idempotencyKey。ensureArtifactVersion() 返回 created 或 reused;ensureArtifactShare() 返回 created、reused 或 replaced。
安全与生命周期规则
- 不要在产物元数据中保存内容字节;应写入工作区文件并传递可移植引用。
- 请求
public_link前必须取得用户明确确认,并在访问输入中设置userConfirmedPublicLink。 createSignedPreviewLink()只用于短期预览;持久共享策略应保存shareKey并调用ensureArtifactShare()。- 评审、审批、审计和可复现交付应固定到具体版本;只有读者应始终看到最新内容时才使用
latest。 - 除非交付物确实需要平台允许的交互 HTML 能力,否则应选择
strict。 - 访问应结束时撤销链接或共享槽位。业务对象归档时,插件也应同步执行相应的产物生命周期策略。