# 产物读取、删除与回填边界

先确认引用属于哪一类产物，再按其文件和来源状态继续操作。

## 对象与身份

| 入口 | 标识与用途 |
| --- | --- |
| 工作区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当旧文件最初产生时间。

<span id="errors"></span>

## 错误与结果确认

参数、日期区间或分页不合法可返回400/code2。详情不可用可返回404/code3；卷授权/依赖还可能先返回403/503。普通错误使用数值code/message，不能套字符串code/msg。

批量结果中的invalid_argument、not_found、already_deleted、unavailable描述具体项。当前部分读取失败也被归入not_found；不能据一个reason推断存储健康、真实不存在或权限结论。与源映射有关的差异候选保留在内部审阅记录，需真实故障/权限场景复测。
