ArtifactsRuntimeCapability 通过 platform.artifacts 暴露 ArtifactsApi。它管理插件与智能体生成的持久化交付物,包括 HTML、Markdown、PDF、PowerPoint、图片、普通文件、站点和演示文稿。
普通生成文件可保存在工作区文件中;受保护定义使用下文介绍的产物专属内容存储。产物服务在此基础上增加稳定业务身份、不可变版本历史、受治理访问链接、生命周期状态和访问计数。
数据模型
产物流程分为三层:- 产物容器:由
pluginName、resourceType和resourceId定义的稳定插件业务身份。 - 产物版本:由
WorkspacePortableFileReference、MIME 类型、校验和与元数据描述的不可变内容。 - 产物链接:包含版本策略、访问模式、过期时间和展示策略的打开、共享或下载入口。
kind 类型支持 html、markdown、pdf、pptx、image、file、site 和 presentation。
容器与版本方法
listArtifacts 支持按字面值匹配 resourceIdPrefix,以及不加载内容的 includeCurrentVersion 元数据。ensureArtifactVersion.expectedCurrentVersionId 提供比较后写入保护,null 表示预期尚无当前版本。幂等重试不能把旧保存恢复到新版本之上。
容器状态为 active、archived 或 deleted;版本状态为 active 或 deleted。
链接与共享方法
链接状态为
active、revoked 或 expired。versionMode: 'latest' 始终跟随当前产物版本;versionMode: 'version' 固定到某个不可变版本。
访问模式包括:
owner_onlyworkspace_allorganization_allcustom_principalspublic_linksigned_preview
inline 或 attachment,可控制是否允许下载,还可应用 strict 或 interactive 安全 HTML 配置。
发布生成文件
普通生成文件应从已授权 Agent 运行时解析capabilities,先写入工作区文件,再创建或复用产物版本和共享。以下为服务端集成片段,ID 和字节来自已授权操作:
idempotencyKey。ensureArtifactVersion() 返回 created 或 reused;ensureArtifactShare() 返回 created、reused 或 replaced。
草稿与显式发布
ArtifactDraftsRuntimeCapability(platform.artifact-drafts)提供与正式版本分离的可变工作副本:
新草稿使用修订号
0,预期尚无正式版本时使用 null。冲突必须重新加载并协调,不能静默把过期编辑覆盖到新版本。重试同一次发布返回相同正式版本;保存草稿不会更新已发布链接。
publish 只能由用户显式确认后的可信应用操作调用,不能暴露为智能体工具。类型可声明 versioning: { mode: 'draft-only' },使用 authorizeDraft 和 assertDraftPublication 增加策略;后者在发布锁内再次执行。普通版本上传不能绕过此流程。
回收会撤销链接,恢复不会重新启用旧链接。普通编辑器不要设置 get 的 includeArchived,该选项用于目录或回收站读取。
类型提供器与受保护内容
通过@ArtifactTypeProvider(resourceType) 注册实现 IArtifactTypeProvider 的提供器,并加入插件模块。definition 声明允许的 kind、MIME、字节限制、分享规则和展示模式;authorize 执行业务限制,validateContent 校验字节。可选的发布与链接钩子可进一步收紧策略。
type 是业务类型,kind 是格式族,mimeType 描述字节格式。显式 { pluginName, resourceType } 类型必须匹配来源;加载器绑定安装来源,必要提供器缺失时拒绝访问。省略 type 选择普通内置文件行为,但不能绕过已注册的自定义来源类型。过去未绑定类型的试验记录需要经过授权重新发布。
展示模式包括:
file:提供经过授权的不可变文件。snapshot:通过打包的隔离入口展示明确发布的快照数据,不提供查询操作。authenticated:由同一安装来源的ArtifactPresentationProvider按当前访问者身份展示。
ArtifactContentRuntimeCapability(platform.artifact-content)。write({ artifactId, buffer }) 返回可移植引用;read(reference) 对拥有这些具体字节的草稿或正式版本执行授权。宿主检查规范引用、完整性及 50 MB 限制;拒绝时不能回退到原始文件读取。
所有权与来源授权
规范来源为pluginName + resourceType + resourceId。可选 authorizationProviderKey 指定为同一个资源执行授权的内容资源提供器,不替代所有者或分享受众。
省略 scope.userId 保留当前用户所有权;显式 scope: { projectId, userId: null } 选择项目共享所有权,并保留真实认证创建者。项目读、编辑和管理策略仍然生效;列表和来源查找只返回当前有权访问的产物。
默认情况下,项目成员资格与分享受众需要同时满足。类型仅能在认证展示及组织/工作区受众下显式声明 sharing.projectAccess: 'link-audience',允许管理者把正式定义分享给项目外受众,同时保留提供器和资源 ACL。此例外不覆盖草稿、编辑、库引用、普通文件 API、数据查询或匿名分享。
认证展示
为认证类型注册@ArtifactPresentationProvider({ pluginName, resourceType }),实现 IArtifactPresentationProvider。getEntry() 返回打包 HTML,read(context) 提供初始数据,operations 声明只读操作名,query(context, request) 按 context.actor 执行。
context 包含已授权的正式版本与内容字节。不能用创建者替换当前访问者;需要校验输入,保存、编辑草稿和发布不属于该接口。宿主在返回查询结果前再次检查链接状态、权限和目标版本。跟随最新版本的链接在目标变化后需重新打开。
使用平台返回的 ArtifactLinkRecord.presentationUrl(/artifacts/view/:slug)。创作端远程视图声明并调用 artifact.presentation.open,传入 { url: presentationUrl };应处理命令不可用或弹窗被拦截的结果,不要放宽 iframe sandbox。独立展示页需要正常认证登录,仅提供已声明只读操作,不开放创作、导航或文件通道。
外层产物展示仍是隔离、无网络的宿主。如果渲染器嵌入 HTML 产物文档,内层文档的显式策略属于独立集成契约,不代表可以放宽外层宿主。
项目库引用与复制
ArtifactLibraryRuntimeCapability(platform.artifact-library)提供 add、open、selectVersion、share 和 revoke。添加固定版本引用不创建公开链接,也不授予来源访问。打开时同时检查项目成员资格与当前来源权限。重命名、移动或删除引用不修改原产物,切换引用版本也不更新已发布链接。
readArtifactVersion({ artifactId, artifactVersionId, purpose }) 对正式字节执行来源授权、内容与摘要校验。purpose: 'copy' 还要求 definition.collection.allowCopy: true。自定义类型默认不允许复制,普通内置文件允许。复制品具有独立生命周期并采用目标项目 ACL,收集界面须说明并确认这一边界。会话快照只允许引用。
安全与生命周期规则
- 不要在产物元数据中保存内容字节。普通输出使用工作区文件,受保护定义使用 Artifact Content,并传递可移植引用。
- 请求
public_link前必须取得用户明确确认,并在访问输入中设置userConfirmedPublicLink。 createSignedPreviewLink()只用于短期预览;持久共享策略应保存shareKey并调用ensureArtifactShare()。- 评审、审批、审计和可复现交付应固定到具体版本;只有读者应始终看到最新内容时才使用
latest。 - 除非交付物确实需要平台允许的交互 HTML 能力,否则应选择
strict。 - 访问应结束时撤销链接或共享槽位。业务对象归档时,插件也应同步执行相应的产物生命周期策略。