产物读取、删除与回填边界¶
先确认引用属于哪一类产物,再按其文件和来源状态继续操作。
对象与身份¶
入口 |
标识与用途 |
|---|---|
工作区agent-artifacts |
智能体生成文件的版本投影,artifact_id/version。 |
catalog/file-artifacts/{file_id} |
按文件查询处理关联及数据资产。 |
lineage/artifacts/{artifact_id} |
工作流血缘产物节点、输出块与修订。 |
workspaces/{id}/runtime-artifacts |
活动任务的受限文件发布;额外运行凭据入口。 |
四者不能仅因名称都含artifact而互换。当前五个产物管理动作不是任意文件发布、知识库解析或工作流重跑入口。
来源与文件可见性¶
可读文件的产物行不一定能展示原任务来源。当前handler会检查来源任务是否属于当前用户且context匹配;不能展示时清空conversation_id、conversation_title、task_id、call_id、tool_id、source_event_id及source_event_seq。
按conversation_id筛选还要求来源会话与任务属于当前用户。来源会话归档或智能体归档、当前挂载不可读等条件可使条目消失。不能仅凭列表空、详情404或空来源字段判断物理文件已删除。
删除结果¶
最多100项,逐项检查succeeded和failed。已读版本、当前挂载、卷范围及状态共同影响结果。实现会标记指定版本deleted,解除当前选定的volume_files挂载并递减引用计数;不会在此同步清除所有挂载或直接保证底层对象已擦除。
重复删除可能因产物已不是completed或挂载已移除而得到not_found,不承诺每次都返回already_deleted。
回填行为¶
仅扫描有智能体工具/沙箱来源、任务/活动会话关联和当前可读挂载、但缺少产物记录的文件。先dry_run=true;确认范围后才用false写入。省略dry_run、空JSON对象、JSON null、无请求体或Content-Length为0时默认false,limit默认200、最大1000。
回填补的是索引式记录,不重新生成文件、不恢复已丢失内容、不触发智能体任务。没有游标或next_token;重复dry-run可反复看到同批候选,不能把统计次数累计当不同文件数。实际新增版本从1开始,时间使用回填时刻;不能将generated_at当旧文件最初产生时间。
错误与结果确认¶
参数、日期区间或分页不合法可返回400/code2。详情不可用可返回404/code3;卷授权/依赖还可能先返回403/503。普通错误使用数值code/message,不能套字符串code/msg。
批量结果中的invalid_argument、not_found、already_deleted、unavailable描述具体项。当前部分读取失败也被归入not_found;不能据一个reason推断存储健康、真实不存在或权限结论。与源映射有关的差异候选保留在内部审阅记录,需真实故障/权限场景复测。