# Artifact 文件接口

Source: https://langbot.app/docs/zh/develop/artifacts

通过 HTTP 或 MCP 上传、读取、保留和删除当前主体拥有的文件。

Artifact 为文件提供不透明引用和元信息。账户或 API 密钥只能访问当前工作区内属于自己的文件。知道 ID 不代表获得权限，同一工作区的其他成员也不能凭 ID 读取。

沿用工作区 HTTP 认证。读取需要 `resource.view`；创建、保留、释放和删除需要 `resource.manage`。

| 操作      | HTTP                                                                                     |
| ------- | ---------------------------------------------------------------------------------------- |
| 上传      | `POST /api/v1/artifacts`，multipart `file`，可选 `ttl_seconds`                               |
| 元信息     | `GET /api/v1/artifacts/{id}`                                                             |
| 下载      | `GET /api/v1/artifacts/{id}/content`，可选 `max_bytes`                                      |
| 读取结构化内容 | `GET /api/v1/artifacts/{id}/read`，可选 `mode`、`offset`、`max_chars`、`page_start`、`page_end` |
| 持久保留    | `POST /api/v1/artifacts/{id}/retain`                                                     |
| 释放保留    | `POST /api/v1/artifacts/{id}/release`                                                    |
| 删除      | `DELETE /api/v1/artifacts/{id}`                                                          |

上传返回含 `id` 的元信息。下载返回原始字节，使用附件响应及 digest ETag。上传和下载上限为 10 MiB。`max_bytes` 限制整个文件的读取大小，不表示字节范围；超过限制时拒绝读取，不截断文件。

新上传文件默认 24 小时后过期；`ttl_seconds` 可设为 1 秒至 7 天。retain 添加持久保留标记，不改变访问权限。release 移除该标记并恢复 24 小时临时保留期；重复 release 不续期。仍有标记的文件不能删除，需要先释放。过期资产不能读取或重新保留；清理任务回收过期临时内容。

不存在、已删除和无权访问的 ID 均返回 404。已过期的自有文件返回 `artifact_expired`（410），删除仍在使用的文件返回 `artifact_in_use`（409），读取超限返回 `artifact_too_large`（413），完整性校验失败返回 `artifact_integrity_failed`（422）。

删除立即阻止后续访问，底层字节由维护任务回收。有界下载持有临时读取租约，清理会跳过该文件，直至读取结束或租约到期。执行租约有效的活跃 run 也会保护它正在使用的输出。

删除 Artifact 不会撤回已投递的平台文件，也不会删除按独立规则保留的消息历史。

PDF 结构化读取（包括原生模式）会拒绝损坏或受密码保护的文件，返回 `artifact_pdf_unreadable`（422）。有权访问的用户仍可下载原始字节。

## 固定版本 Skill 资源

`POST /api/v1/artifacts/skill-resources` 为数据库持久化 Skill 包中的单个文件创建调用方拥有的引用。JSON 请求包含 `skill_name`、明确的 `revision`、包内相对 `path`，以及可选的 `ttl_seconds`。需要同时具备 `resource.view` 和 `resource.manage`。对应的 ApplicationAPI 操作是 `artifact.skill_resource.create`；MCP 工具 `create_skill_resource_artifact` 使用相同参数。

登记直接复用 ContentStore 中已有的不可变版本包，不上传或复制文件、整包。引用绑定存储版本身份和规范包内路径，并包含文件摘要、大小和 MIME 类型。发布新版本不会改变旧引用。使用现有 Artifact 元信息、下载和结构化读取接口即可读取，无需 Box 会话。

只有创建引用的账户或 API key 能使用它。分享 ID 或保留引用都不授予其他主体权限。来源引用不是普通上传附件，不能假定将其放入调试请求的 `artifact_ids` 就会授权 run 访问。该 Workspace 操作不向插件、默认模型工具或 `lbctl` 开放。

释放和 Artifact 清理只回收引用，不删除共享 Skill 包。存活引用保护其保留版本，临时读租约保护正在进行的读取。删除 Skill 当前目录项不会重写保留版本。此引用接口不支持仅文件系统的 Skill 存储，请使用数据库持久化；原文本资源读取接口仍然可用。

同一所有者、版本和路径的重复登记返回同一引用，不延长过期时间。已过期或删除的引用须先回收，才能重新登记。

在已授权的存活 run 中，`read_skill_resource` 使用已激活 Skill 的冻结版本和同一有界 reader。文本保留文本契约，截断时给出继续读取位置；图片和原生 PDF 使用结构化模型内容，而不是普通文本中的 base64。登记时验证有界来源字节。来源字节读取在每个 run 中对每个不可变 Artifact 只计入预算一次，限额为每文件 256 KiB、每 run 1 MiB。另设独立的每 run 1 MiB 返回预算，累计计算返回 JSON 的 UTF-8 字节和媒体载荷字节。每次继续读取仍会重新检查权限，即使来源已计入预算。旧文本路径不变。原生 PDF 仍要求模型支持。没有该存活 run 授权时只保留旧文本读取路径，不隐式授予二进制来源访问权。

## MCP

原生 PDF 需要可信的模型能力信息；对于已由供应商确认支持、但能力目录尚未识别的模型别名，可由管理员在模型的现有 `abilities` 字段中声明 `pdf_input`。未声明且能力未知时会明确拒绝原生 PDF，仍可使用文本模式。

内置 `/mcp` 服务提供 `create_artifact`、`get_artifact`、`read_artifact`、`read_artifact_content`、`retain_artifact`、`release_artifact` 和 `delete_artifact`，使用相同的归属及权限检查。创建参数为 `filename`、`content_base64`，以及可选的 `mime_type` 和 `ttl_seconds`。原始读取参数为 `artifact_id` 及可选的 `max_bytes`，返回 base64 和元信息。`read_artifact_content` 沿用 HTTP `/read` 的读取参数，返回原生 MCP 文本、图片或嵌入 PDF 内容，不把 base64 放入普通文本。对应 Workspace 操作为 `artifact.read_content`。

`read_artifact` 传输原始字节。插件授权和类型化方法不授予账户私有文件访问权；安装私有的 Artifact 操作见下文。账户管理不会加入默认模型工具或 `lbctl`。原有上传接口和运行内 `file_id` 接口继续使用原契约。

## Agent 按需读取

Runner 初始输入只包含附件引用、名称、MIME 和大小。图片、文件字节和来源 URL 保留在 Host 的运行内注册表中，不直接进入首轮模型消息。当前消息和引用消息中的附件各有独立引用。Agent 需要内容时才调用读取工具，Host 继续检查当前 run 的冻结附件权限；另一个 run 的引用不能授权访问。

`read_input_attachment_content` 返回结构化内容，支持以下模式：

| 模式       | 行为                               |
| -------- | -------------------------------- |
| `auto`   | 读取 UTF-8 文本、返回结构化图片，或提取 PDF 文本。  |
| `text`   | 有界读取字符范围；PDF 结果标明所选页码，明确不包含视觉内容。 |
| `native` | 将图片或 PDF 作为原生输入交给支持的模型；不支持时明确报错。 |
| `pages`  | 本阶段尚不支持页面渲染，返回明确错误。              |

文本使用从零开始的 `offset` 和 `max_chars`（默认 8192，最大 16384）。结果带 `truncated` 和 `next_offset`，应从该位置继续读取，不能将截断内容当作全文。PDF 文本使用从一开始的 `page_start` 和可选 `page_end`，每次最多十页，并返回下一页位置；不做 OCR，也不保留图片和页面布局。其他二进制格式明确拒绝；自有上传文件仍可通过账户下载接口取得原件。

Agent 调试 API 的请求可带 `artifact_ids`，最多 20 个不同的自有上传资产 ID。Host 在启动 run 前按真实认证主体检查归属，再给该 run 引用。请求中的事件 `actor` 不会改变资产归属。独立的 Workspace 管理助手本阶段仍不接受附件输入。已有原始字节接口 `read_input_attachment` 继续供有权限的 Runner 代码使用。

## Runner 输出文件

`ctx.export_box_files(paths)` 把选定的沙箱文件登记为临时 Artifact。返回的 `BoxFile.id` 仍是原有 UUID 文件句柄，归导出它的 run 所有；元信息新增 `artifact_id`、`mime_type`、`digest`、`lifecycle` 和 `expires_at`。`artifact_id` 不会授予账户 Artifact API 的读取权限。

`ctx.read_run_file(file_id, mode="auto", offset=0, max_chars=8192, page_start=1, page_end=None)` 使用上述模式有界读取结构化内容。要发布选定的输出，认证账户或具名 API 密钥需要先为 Agent 或流水线启用发布策略：

```http
PUT /api/v1/artifacts/producers/agent/{agent_id}/publication
Content-Type: application/json

{"enabled": true}
```

流水线使用 `pipeline`，事件处理器使用 `event_processor`。服务器将真实认证主体设为接收人，请求不能指定其他人；需要同时具有 `resource.view` 和 `resource.manage`。策略属于该主体，同工作区其他成员不能接管。新建或复制的执行器默认没有策略。全局和旧版兼容 API key 不能接收发布产物，需要使用具名工作区 API key。

Host 在运行开始时冻结策略。`ctx.commit_run_files(file_ids)` 重新检查策略和接收人的当前权限，通过后添加接收人的持久保留标记，并返回更新后的元信息。策略缺失、被修改、停用或权限被撤销时会拒绝提交。导出、读取和投递都不会自动提交，默认模型工具也不提供 commit。重复提交不会撤销接收人随后执行的 release。

提交后，接收人可用 `artifact_id` 调用已有 Artifact 元信息、下载、retain、release 和 delete 接口，运行结束或 Core 重启后仍可管理。其他账户、密钥和 run 不因此获得权限；原 `file_id` 仍只在原 run 存活时有效。release 恢复 24 小时临时保留期。仍有持久保留标记或有效使用租约时，delete 返回 `artifact_in_use`（409），解除后重试。

管理接口按 ID 操作，没有 Artifact 列表接口。Runner 实现需要在业务结果中把 commit 返回的 `artifact_id` 交给接收人，供后续管理使用。

同一 URL 的 `GET` 查看策略，`DELETE` 停用策略；MCP 对应 `get_artifact_publication`、`set_artifact_publication` 和 `disable_artifact_publication`。停用会阻止后续发布，已发布文件继续由原接收人管理。

运行完成、失败或取消时，Host 在有时间限制的清理中尝试使未发布输出过期，再由维护任务回收。Core 崩溃、清理失败或超时时，仍以原有 24 小时期限兜底。

`ctx.reply_files` 和流水线附件回复通过原有平台投递路径读取 Artifact 字节。本阶段没有新增通用 run 文件 HTTP 下载入口。完整流程见 [Runner API](https://langbot.app/docs/zh/plugin/dev/apis/agent-run.md#box-与附件)。

## 知识库导入 Artifact

要索引已有且有权访问的 Artifact 而不重新上传，可调用 `knowledge.file.store_artifact`，传入 `kb_uuid`、`artifact_id` 和可选的 `parser_plugin_id`；也可向 `POST /api/v1/knowledge/bases/{kb_uuid}/files/artifact` 发送包含后两项的 JSON。需要同时具备 `resource.view` 和 `resource.manage`。MCP 工具 `add_knowledge_file_artifact` 使用相同参数。返回值保持现有索引任务的 `task_id` 契约。原上传和 `file_id` 入库路径继续可用。

此账户/API key 入口建立持久的知识文件业务引用，知道 Artifact ID 本身并不授予访问权。此导入路径不接受 Skill 包来源或 run 拥有的来源。删除知识文件或知识库仅解除自身业务引用，不删除其他消费者的引用或共享字节。有效业务引用会阻止 Artifact 删除。

KnowledgeEngine 插件继续通过 `get_knowledge_file_stream` 读取 `context.file_object.storage_path`。对 Artifact 导入，该字段是不透明的 `artifact:<knowledge_file_uuid>` 标识，不是文件系统路径、URL 或公开下载密钥。Core 先验证已安装调用方是知识库指定的引擎，再通过公共 Artifact 服务读取。不要在本地打开此标识，也不要把它当作对另一插件安装的授权。

## 插件拥有的 Artifact

插件可显式申请 `artifact.create`、`artifact.get`、`artifact.read`、`artifact.read_content`、`artifact.retain`、`artifact.release` 和 `artifact.delete`。请逐项列出所需操作 ID：`artifact.*` 还包含仅供账户使用的发布和 Skill 来源操作，因此会被拒绝。类型化调用使用 `self.plugin.workspace.artifact.<method>(...)`，或 run 绑定的 `ctx.api.workspace` 代理。

这些 Artifact 属于安装 UUID，不属于插件作者/名称、账户或 run。每次操作均重新检查当前安装是否启用及有效授权；撤销权限或以新 UUID 重装后不能访问旧资产。知道 ID 或保留引用并不分享权限。插件操作不能导入账户上传、Skill 来源或 run 句柄。`artifact.skill_resource.create` 和 `artifact.publication.get/set/disable` 仍仅供账户/API key 使用。参见 [Artifact 接口](https://langbot.app/docs/zh/develop/artifacts.md)。

JSON RPC 创建使用 `filename`、`content_base64`、可选的 `mime_type` 和 `ttl_seconds`。解码后的输入最多 256 KiB；插件原始读取同样限制为 256 KiB，返回 `metadata` 和 `content_base64`。有界文本/结构化媒体优先使用 `read_content`。较小的传输限制不改变原已认证 HTTP 上传/下载契约。保留/释放只操作此安装的保留引用；存在有效业务引用时拒绝删除。

## 旧上传入口与共享保留

`/api/v1/files/images` 和 `/api/v1/files/documents` 保持现有 `file_key`、`file_id` 返回字段。使用持久存储的新上传额外返回 `artifact_id`。旧别名和 Artifact 引用共享同一内容对象，不重复保存字节。别名持有独立的持久引用；删除别名只释放该引用，其他持有者不受影响。非持久旧存储仅返回原字段。已有不透明 key 不会迁移或重新解释为 Artifact ID。

持久化旧上传若超过 `storage.max_object_read_bytes` 与 Artifact 大小限制中的较小值，会在写入前返回 HTTP 413。超过 255 个字符的普通文件名仍可上传，仅 Artifact 显示名称会缩短，保留扩展名和 MIME 类型；返回的旧句柄及文件字节保持不变。

知识文件导入仅接受账户/API key 拥有的普通上传。已发布的 run 产物和 Skill 包来源仍被排除，避免扩大原权限。知识库删除通过持久删除屏障阻止新的文件加入；删除失败或结果不确定时保留业务引用及可重试的屏障，不回收可能仍在使用的字节。

知识文件列表新增 `artifact_id`（旧文件为 `null`），本次不新增摘要、大小或 MIME 字段。上游知识库删除失败、取消或结果未知时，应重试显式删除操作，Core 重启后也可重试。删除完成前，屏障持续禁止新入库。活跃或中断未完成的入库会在建立屏障前阻止删除。
