如何精准控制 AI 看到什么?opencode.nvim 上下文引擎深度解析:@提及、诊断、Git Diff 与剪贴板图片

原创2026-10-21 19:30:322,825 阅读

如何精准控制 AI 看到什么?opencode.nvim 上下文引擎深度解析:@提及、诊断、Git Diff 与剪贴板图片

opencode.nvim 是 OpenCode(终端 AI 编程智能体)的 Neovim 前端插件。它最被低估的能力,不是聊天面板,而是背后的上下文引擎(Context Engine)——它决定了 AI 每次收到什么:当前文件、你选中的代码、LSP 诊断、Git 暂存改动,甚至剪贴板里的截图。今天我们就来拆解:如何用 @ 提及、诊断信息、Git Diff 和图片附件,精准控制 AI 的"视野",让提示更准、Token 更省。

opencode.nvim 上下文引擎:代码编辑区与 AI 智能体面板协同工作的演示

核心概念:上下文栏 = 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,不如只给它你关心的那几行:

  1. 在 visual 模式下选中代码;
  2. 按 <leader>oy:选区连同文件名、行号一起加入上下文,输入框自动打开;
  3. 或者按 <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 中查看输入输出示例。

opencode.nvim 中的 Git Diff 审阅流程:左侧代码 diff 与右侧 AI 分析面板联动

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 类型一起发送。⚠️ 注意:所使用的模型必须支持图像输入。

上下文引擎配置速查

opencode.nvim 面板布局切换演示,展示不同工作模式下 AI 面板与代码窗口的组合

一个典型的"精简派"配置:关掉自动附带当前文件,只保留手动选区与诊断:

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。

⚠️ 安全提醒:别让敏感代码悄悄出圈

两个容易忽略的点:

  1. 发送前看一眼上下文栏。如果当前缓冲区包含密钥、Token 等敏感内容,确认它不会被附带;
  2. 上下文设置只控制"插件附带什么"。AI 智能体仍可通过自己的工具读取项目文件——需要在 OpenCode 侧用权限(permissions)限制;若想在某些项目中彻底禁止提示,可以配合 prompt guard 使用。

总结:把"给 AI 看什么"变成可控的开关

opencode.nvim 的上下文引擎把常见的"喂上下文"动作变成了精确的开关:

  • @ / ~:点名文件,附带提及;
  • <leader>oy:只给关键选区,不给全文;
  • 诊断:默认自动附带光标处的警告与错误;
  • Git Diff:一键开启暂存改动审阅模式;
  • <leader>ov:剪贴板图片直接变附件。

再配合上下文栏的可视化预览与去重发送机制,你就能在保证信息充分的同时,把每次提示的 Token 开销控制在最低。想要更深入的配置项与命令参考,建议阅读 docs/README.md 文档目录与 README.md。

登录后查看全文
opencode.nvim