如何精准控制 AI 看到什么?opencode.nvim 上下文引擎深度解析:@提及、诊断、Git Diff 与剪贴板图片
如何精准控制 AI 看到什么?opencode.nvim 上下文引擎深度解析:@提及、诊断、Git Diff 与剪贴板图片
opencode.nvim 是 OpenCode(终端 AI 编程智能体)的 Neovim 前端插件。它最被低估的能力,不是聊天面板,而是背后的上下文引擎(Context Engine)——它决定了 AI 每次收到什么:当前文件、你选中的代码、LSP 诊断、Git 暂存改动,甚至剪贴板里的截图。今天我们就来拆解:如何用 @ 提及、诊断信息、Git Diff 和图片附件,精准控制 AI 的"视野",让提示更准、Token 更省。
核心概念:上下文栏 = AI 的"视野预览"
opencode.nvim 在输入框上方提供一条 context bar(上下文栏),实时展示这条提示词将附带哪些内容:当前文件、选区、诊断、Git Diff……发送前你一眼就能看清 AI 会看到什么。在插入模式下按 # 还可以逐项开关或移除。
这一机制的源码在 lua/opencode/ui/context_bar.lua,上下文项的采集逻辑集中在 lua/opencode/context/base_context.lua 和 lua/opencode/context/chat_context.lua,官方说明见 docs/context.md。
默认发送哪些上下文?
| 上下文类型 | 默认 | 说明 |
|---|---|---|
| 当前文件 | ✅ 开启 | 你切到面板前所在的代码缓冲区 |
| 可视化选区 | ✅ 开启 | 用 <leader>oy 添加,附带文件和行号 |
| 提及的文件 | ✅ 开启 | 通过 @ 或 ~ 添加 |
| LSP 诊断 | ⚠️ 仅警告和错误 | 只取光标或选区所在行 |
| Review 评论 | ✅ 开启 | session diff 中保存的评论 |
| 光标上下文 | ❌ 关闭 | 光标行及上下各 5 行 |
| 整个缓冲区 | ❌ 关闭 | 当前缓冲区全部内容 |
| Git Diff | ❌ 关闭 | 暂存区改动(git diff --cached) |
每项都可以在 context 配置下独立开关,context.enabled = false 则一键关闭所有自动上下文。
@提及:用一行符号精准指向文件
在输入框的插入模式下:
- 输入
@:弹出文件与 Agent 补全菜单,直接指向具体文件; - 输入
~:打开文件选择器(file picker),在多个文件中快速挑选; - 输入
#:列出当前上下文中的全部内容,可移除文件/选区、整组开关诊断、或删除单条 Review 评论。
提及匹配的正则与高亮逻辑在 lua/opencode/ui/mention.lua 中实现。
防重复机制:同一内容不会被反复发送
上下文引擎内置了去重策略,这是省 Token 的关键:
- 当前文件:只发送一次,之后仅在磁盘上的文件发生变化后才重新发送。上下文栏中,文件已"最新"时呈暗色,将随下一条提示发送时则高亮;
- 诊断、光标数据、缓冲区、Git Diff:仅在内容变化时重新发送;
- 提及的文件和选区:每次随所在提示词发送。
这个设计意味着:你可以在同一个会话里连续追问,而不用担心 AI 每次都要"重读"同一份代码。
可视化选区:只把关键几行交给 AI
与其把整个文件塞给 AI,不如只给它你关心的那几行:
- 在 visual 模式下选中代码;
- 按
<leader>oy:选区连同文件名、行号一起加入上下文,输入框自动打开; - 或者按
<leader>oY:选区直接以内联代码块的形式粘进提示词中间,适合在句子中引用代码片段。
💡 小技巧:配置 open_input = false 参数后,可以连续添加多个选区而无需每次都跳回输入框。如果选区就在当前文件中,插件只发送选区本身而不是整个文件——AI 需要时仍可自行读取完整文件。
对应实现位于 lua/opencode/commands/handlers/workflow.lua,默认键位定义在 lua/opencode/config.lua。
LSP 诊断:让 AI 顺着报错一起读代码
这是上下文引擎里"静默而强大"的功能:当你让 AI 修复某行代码时,插件会自动附带该行上的 LSP 诊断信息(默认只取警告和错误级别),AI 因此能看到真实的报错文本,而不是凭猜测修 bug。
诊断采集逻辑在 lua/opencode/context/base_context.lua 的 get_diagnostics 中:默认 only_closest 模式只提取光标行或选区行的诊断,避免把整个项目的警告列表一股脑丢给模型。你可以在配置中调整级别与范围:
require('opencode').setup({
context = {
diagnostics = { only_closest = false, info = false, warning = true, error = true },
},
})
完整的配置参考在 docs/configuration.md,诊断相关的测试数据可以在 tests/data/diagnostics.json 中查看输入输出示例。
Git Diff:让 AI 看见你暂存的改动
默认情况下 Git Diff 是关闭的。开启后,插件会异步执行 git diff --cached --minimal,把暂存区的改动附加到每次提示中——非常适合让 AI 帮你 review 即将提交的代码:
require('opencode').setup({
context = { git_diff = { enabled = true } },
})
它在 lua/opencode/context/base_context.lua 中通过 Promise.async 异步执行,且做了健壮性保护:非 Git 仓库或 Git 命令失败时,不会阻塞你发送提示词。改动内容发生变化时才会重新发送,配合上文提到的去重机制非常经济。
剪贴板图片:截图比千言万语更直观
看到 UI 还原效果不对、想给 AI 看一张报错弹窗截图?opencode.nvim 支持剪贴板图片附件:
- 普通模式下按
<leader>ov,或输入框插入模式下按<M-v>,即可把剪贴板中的图片附加到提示词; - 支持 PNG / JPEG / GIF / WebP,跨平台适配(macOS 用 osascript、Linux 用 wl-paste/xclip、Windows 用 PowerShell),还支持 base64 编码的剪贴板数据。
实现位于 lua/opencode/image_handler.lua,保存的图片以 pasted_image_*.png 命名并由 lua/opencode/context/chat_context.lua 附带 MIME 类型一起发送。⚠️ 注意:所使用的模型必须支持图像输入。
上下文引擎配置速查
一个典型的"精简派"配置:关掉自动附带当前文件,只保留手动选区与诊断:
require('opencode').setup({
context = {
current_file = { enabled = false },
selection = { enabled = true },
diagnostics = { only_closest = false, info = false, warning = true, error = true },
},
})
其他常用选项:
context.cursor_data = { enabled = true, context_lines = 5 }:开启光标上下文,context_lines控制前后各几行;context.current_file.show_full_path/context.files.show_full_path:控制上下文栏中文件显示完整路径还是仅文件名;context.enabled = false:一键关闭全部自动上下文。
全部选项说明见 docs/context.md 与 docs/configuration.md。
⚠️ 安全提醒:别让敏感代码悄悄出圈
两个容易忽略的点:
- 发送前看一眼上下文栏。如果当前缓冲区包含密钥、Token 等敏感内容,确认它不会被附带;
- 上下文设置只控制"插件附带什么"。AI 智能体仍可通过自己的工具读取项目文件——需要在 OpenCode 侧用权限(permissions)限制;若想在某些项目中彻底禁止提示,可以配合 prompt guard 使用。
总结:把"给 AI 看什么"变成可控的开关
opencode.nvim 的上下文引擎把常见的"喂上下文"动作变成了精确的开关:
@/~:点名文件,附带提及;<leader>oy:只给关键选区,不给全文;- 诊断:默认自动附带光标处的警告与错误;
- Git Diff:一键开启暂存改动审阅模式;
<leader>ov:剪贴板图片直接变附件。
再配合上下文栏的可视化预览与去重发送机制,你就能在保证信息充分的同时,把每次提示的 Token 开销控制在最低。想要更深入的配置项与命令参考,建议阅读 docs/README.md 文档目录与 README.md。


