进阶 opencode.ai 2026-11-11 16:13:22 · 17 阅读

第20章 OpenCode V2附件功能详解

附件功能允许挂载本地文件,并在提示词中让 OpenCode 使用该文件。在桌面端或 Web 客户端中,你可以通过选择“附加文件”、粘贴文件或拖入文件来操作。

总结所附加的 README.md,并列出所需的配置步骤。
桌面端文件选择器的单次选择总量上限为 20 MiB。其他接口可能应用更低的客户端侧限制。

V2 版本的提示词和命令输入使用带有 uri 的附件描述,并可选包含 name 和 description:

{
  "uri": "file:///home/me/project/src/server.ts",
  "name": "server.ts",
  "description": "HTTP 服务器入口点"
}
使用绝对路径 file: URL 来指定服务器可访问的文件或目录。对于文本文件,正数的 start 和 end 参数用于选择基于 1 的行号。 file:///home/me/project/src/server.ts?start=20&end=60 使用 data: URL 可以内联发送内容:
{
  "uri": "data:text/plain;base64,SGVsbG8sIE9wZW5Db2RlIQ==",
  "name": "greeting.txt"
}
不支持 HTTP 和 HTTPS 附件 URL。有关通过编程方式提交提示词的信息,请参阅生成的 API 参考文档。

当前的 V2 会话使模型能够看到以下类型的附件:

输入模型接收 示例 UTF-8 文本文件 文件名和解码后的文本 README.md 目录 直接文件和目录的非递归列表 file:///home/me/ PNG, JPEG, GIF 或 WebP 图像媒体 diagram.png PDF 文档媒体 report.pdf
PDF 需要支持 PDF 输入的模型。如果模型不支持附件的类型,OpenCode 将替代发送一条简短的说明。SVG 被视为文本。AVIF、BMP、音频、视频以及其他二进制提示词附件不会包含在模型请求中。请先将不支持的二进制文件转换为文本或受支持的图像格式;例如,将 BMP 图像转换为 PNG 后再附加。

OpenCode 在接受提示词之前会读取每个附件。它会拒绝无效的 URL、不可读的路径、非文件或目录的路径,以及解码后超过 20 MiB 的附件。媒体类型从字节中检测,因此更改文件名或 data: URL 的媒体类型并不会使不受支持的二进制文件变得可见。

在 opencode.json 或 opencode.jsonc 中配置图像归一化:

opencode.jsonc{
  "$schema": "https://opencode.ai/config.json",
  "media": {
    "image": {
      "auto_resize": true,
      "max_width": 2000,
      "max_height": 2000,
      "max_base64_bytes": 5242880,
    },
  },
}
所有字段均为可选:
字段 默认值 行为
auto_resize true 调整超过配置限制的图像大小;若为 false,则拒绝图像。
max_width 2000 最大宽度(像素);必须为正整数。
max_height 2000 最大高度(像素);必须为正整数。
max_base64_bytes 5242880 Base64 编码图像的最大字节数;必须为正整数。
例如,以下内容将拒绝而不是调整宽度超过 1200 像素的图像:
opencode.jsonc{
  "media": {
    "image": {
      "auto_resize": false,
      "max_width": 1200,
    },
  },
}

这些设置适用于附加到提示词的支持图像以及由内置 read 工具返回的图像。

read 工具通过内容识别 PNG、JPEG、GIF 和 WebP,并读取最多 20 MiB 的源图像数据。它会对照配置的图像限制检查宽度、高度和 Base64 长度。

当 auto_resize: true 时,OpenCode 保持宽高比并将图像缩小至尺寸限制内。随后,它尝试逐步较小的 PNG 和 JPEG 编码,直到满足 Base64 限制为止,因此输出的媒体类型可能会改变。

输入:  4000 × 2000 WebP
限制: 2000 × 2000
输出: 2000 × 1000 PNG 或 JPEG

如果没有编码符合限制,处理将失败。当 auto_resize: false 时,超过任何限制的图像将在不做修改的情况下失败;无法解码的图像也会失败。

输入:  2400 × 1600 JPEG
限制: max_width = 2000, auto_resize = false
结果: 图像处理失败

如果图像调整器不可用,OpenCode 将原样传递原始图像。因此,图像设置是处理限制,而非上传或安全边界。

限制 值或行为 示例
直接附件 每项解码后 20 MiB;客户端可能施加更低的限制 两个 12 MiB 文件通过每项限制
桌面选择器选择 总量 20 MiB 两个 12 MiB 文件超过选择限制
max_base64_bytes 仅编码后的 Base64,不包括完整的 data: URL SGVsbG8= 计为 8 字节
提供商图像限制 在 OpenCode 处理后应用 提供商可能会拒绝已接受的图像
文本附件模型支持 不要求多模态模型 notes.txt 作为提示词文本插入
read 文本限制 使用独立的分页和截断限制 分页读取大型日志

客户端接受文件并不保证内容到达模型。附件必须使用模型可见的格式,并满足 OpenCode 和提供商的限制。

评论 (0)