# 文件读取和位置对象

时间为Unix秒；size为字节数。元数据表示文件本身，关联位置表示它在某个卷中的引用；标量零值可能省略。来源会话/任务/调用/工具信息按当前身份可见性回读。

(metadata)=
## 工作区文件元数据

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `file_id` | string | 文件ID。 |
| `original_name` | string | 原始文件名。 |
| `md5` | string | 内容摘要。 |
| `size` | integer | 文件字节数。 |
| `ref_count` | integer | 当前引用计数。 |
| `created_at` | integer | 创建时间，Unix秒。 |
| `created_by` | string | 创建者ID。 |
| `updated_at` | integer | 更新时间，Unix秒。 |
| `source` | string | 来源类别。 |
| `source_session_id` | string | 来源会话ID，按可见性返回。 |
| `source_task_id` | string | 来源任务ID，按可见性返回。 |
| `source_call_id` | string | 来源调用ID，按可见性返回。 |
| `content_type` | string | 保存的内容类型。 |
| `source_tool` | string | 来源工具标识，按可见性返回。 |
| `storage_mode` | string | 存储模式。 |
| `external_connector_id` | string | 外部连接器ID，适用时返回。 |
| `external_uri` | string | 外部对象URI，适用时返回。 |

(placement)=
## 卷文件关联位置

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | integer | 卷文件关联记录ID。 |
| `volume_id` | integer | 关联卷ID。 |
| `file_id` | string | 文件ID。 |
| `file_name` | string | 该位置中的文件名。 |
| `file_path` | string | 卷内相对路径。 |
| `created_at` | integer | 创建时间，Unix秒。 |
| `created_by` | string | 创建者ID。 |
| `updated_at` | integer | 更新时间，Unix秒。 |
| `updated_by` | string | 更新者ID。 |
| `original_name` | string | 原始文件名。 |
| `md5` | string | 内容摘要。 |
| `size` | integer | 文件字节数。 |
| `ref_count` | integer | 当前引用计数。 |
| `revision` | integer | 关联位置修订号。 |
| `source` | string | 来源类别。 |
| `source_session_id` | string | 来源会话ID，按可见性返回。 |
| `source_task_id` | string | 来源任务ID，按可见性返回。 |
| `source_call_id` | string | 来源调用ID，按可见性返回。 |
| `content_type` | string | 保存的内容类型。 |
| `source_tool` | string | 来源工具标识，按可见性返回。 |
| `sandbox_path` | string | 沙箱挂载路径。 |

(private-location)=
## 私有卷上传位置

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `workspace_id` | string | 工作区ID。 |
| `volume_id` | integer | 关联卷ID。 |
| `file_id` | string | 文件ID。 |
| `path` | string | 卷内路径。 |
| `name` | string | 关联名称。 |
| `size` | integer | 文件字节数。 |
| `md5` | string | 内容摘要。 |
