进阶 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 | 文档媒体 | report.pdf |
|---|
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 编码图像的最大字节数;必须为正整数。 |
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 和提供商的限制。