1. 上下文模式（context-mode）到底在解决什么问题
先说一个我自己的经历：几年前我维护过一个老项目，单文件一千多行，核心逻辑又偏偏集中在一个五百行的类里。每天打开文件第一件事就是滚动到那个大方法开头，盯一眼方法名，再跳回当前编辑位置。改到一半忘了自己在哪个函数里，又滚上去看一眼。一天下来，这种“抬头看路标”的动作要重复几十次，强度不高，但很耗神。后来我想办法把“当前光标所在的外层上下文”始终固定在屏幕顶部显示，这个功能后来就被叫做 context-mode，中文就是“上下文模式”。
技术社区里给 context-mode 的定义很直白：在编辑代码时，自动识别光标所在的函数、类、模块、回调等外层结构，并把这一层结构持续、醒目地展示给开发者。它解决的不是“跳转得快不快”的问题，而是“你知不知道自己在哪”的问题。适合谁用？高频改代码的前端、后端开发，做代码评审的人，还有经常要从一个几千行的大文件里定位逻辑的人。你不需要像 IDE 那样把整个调用链画出来，只需要在编辑区域上方清楚看到“我现在在哪个函数里，它挂在哪个类下面”，效率就能往上走一截。
为什么这个需求很真实？因为人脑的工作记忆是有限的。当你在一个函数的第 40 行里调参数、看报错、改逻辑时，你实际上同时要维护多条信息：当前函数的签名、这个函数所在的类、类又挂在哪个模块下、改完这里会不会影响上层调用。编辑器默认只给你窗口内这几行代码，窗口外的信息要靠脑子记。context-mode 的作用，就是把这些“脑内缓存”搬到界面上，让你不用记，扫一眼就知道。没有它你也能工作，但有它以后，你会明显觉得在长文件里改代码的负担轻了。
2. 方案选型：为什么我不直接用 IDE 的现状，而要自建 context-mode
2.1 这个功能不是新概念，为什么很多编辑器没做好
理论上 IDE 早就该原生提供这个能力。像 JetBrains 系列有面包屑（Breadcrumb），Visual Studio 有顶部方法列表，Vim/Neovim 社区也有不少相关方案。但真用过的人都知道，这些方案各有各的别扭。
- 面包屑：默认不展开，需要点击才显示，而且只看得到位置，看不到代码结构，信息密度低。
- 方法列表弹窗（如 Ctrl+F12）：信息倒是全，但它是模态的，看完了要关掉，不能持续挂在屏幕上。
- 代码折叠：能折叠外层结构，但fold之后看不到光标处上下文的实时变化，而且频繁折叠展开很打断思路。
- 有的编辑器顶部能显示当前函数名，但通常只显示一层，函数套函数的时候根本不够用。
所以与其说是“没有这个功能”，不如说是“没有一个做到位、可随时定制”的。这正好是自建一个 context-mode 的出发点：我可以决定它显示几层、用什么颜色、什么时候隐藏、按什么键展开，每个细节都符合我自己工作时的习惯。
2.2 三条实现路径的对比
我当时的想法很简单，选一个最可控的方案。主要有三条路，我每条都试过或者调研过：
| 实现路径 | 优点 | 缺点 |
|---|---|---|
| 用 Vim/Neovim 原生的 foldtext + scrollcontext | 零依赖，不用装任何东西 | 只能显示一行，不能分层；scrollcontext 在 Neovim 0.9 之后才完善，且只算文本行，不能识别函数层级 |
| 用现成插件（如 mini.context、相关上下文显示插件） | 装完即用，功能完整 | 定制受限；版本升级可能改 API；出问题要看别人源码 |
| 自己写 Lua 扩展 | 完全可控，想加什么加什么 | 要维护自己的代码，入门门槛略高 |
我最终选了第三条路，但不是从零写一个完整框架，而是自己用 Neovim 的 Lua API 写一个小模块。核心只有三个部分：从语法树拿光标所在的词法上下文、把上下文渲染到界面指定区域、按需拓展交互。整套代码二百多行就能跑通，维护成本完全可以接受。
如果你只是想在 Neovim 里快速体验 context-mode 的效果，装现成插件是划算的。但如果你想搞清楚它到底怎么工作、想调整行为表现，自己写一遍会让你对整个编辑器生态的语法树、渲染、自动命令机制有更深的理解。我这篇博文会把关键原理和逐行配置讲透，你看完可以直接照抄，也可以改成自己想要的形态。
2.3 环境准备
我平时主力用的是 Neovim，所以要先把基础环境准备好。这里有三个硬性依赖：
- Neovim 0.9 及以上版本。0.9 之后原生支持 winbar（窗口顶栏），这是渲染 context-mode 最合适的容器。
- tree-sitter 解析器。用于实时获取光标所在的函数、类等语法节点。
- 一个插件管理器，我用的是 lazy.nvim。虽然自建模块不依赖某个插件，但我需要从 GitHub 拉 tree-sitter parser，用懒加载逻辑统一管理是最省事的。
环境就绪之后，我的目标是实现一个这样的效果：编辑文件时，屏幕上方始终有一行文字，显示类似src/modules/order.lua > OrderService > processPending这种层级结构；光标挪到不同函数里，这一行跟着变；按一个快捷键可以临时固定住当前上下文，方便对比；在某些不需要的场景（比如输入弹窗、快速滚动）自动隐藏，避免干扰。下面的内容就是围绕这四个行为逐步展开。
3. 核心实现：逐行拆解一个可用的 context-mode
3.1 第一步：拿到光标所在的语法节点
context-mode 的地基是“定位”。光标在一段文本里，这段文本属于哪个函数，哪个 class，哪个 if 块？最稳的答案是借助语法树来算，而不是靠正则或缩进猜。
tree-sitter 会把代码解析成一颗具体的树，每个节点都有类型和范围。比如 Go 代码里，一个函数是function_declaration节点，它包含func关键字、函数名、参数列表和函数体。我拿到光标位置之后，在语法树里从叶子节点往上走，凡是遇到「能代表一个词法作用域」的节点就把它记下来，存到一个栈里，最后形成的链路就是完整的上下文。
下面这段 Lua 函数就是核心查找逻辑，我在一个通用工具文件里维护它：
local function get_context_nodes(bufnr, row, col) local ok, parser = pcall(vim.treesitter.get_parser, bufnr) if not ok or not parser then return {} end local root = parser:parse()[1]:root() local target = vim.treesitter.get_node_at_pos(bufnr, row, col, { include_subtree = true }) if not target then return {} end -- 收集从当前节点到根节点路径上所有“作用域类”节点 local scopes = {} local node = target while node do local type = node:type() if vim.tbl_contains(CONTEXT_SCOPE_TYPES, type) then table.insert(scopes, 1, node) end node = node:parent() end return scopes end这里的CONTEXT_SCOPE_TYPES是一组按语言维护的节点类型集合。比如 JavaScript 里我关心的是function_declaration、method_definition、class_declaration、arrow_function，Python 里关心的是function_definition、class_definition、module。你日常写什么语言，就为那种语言准备一张类型表。之后在光标移动事件里调用这个函数，每次拿到一串节点，就得到了码农最关心的“我在哪”的信息。
3.2 第二步：把上下文渲染到屏幕固定位置
拿到节点列表之后，关键设计问题来了：放到哪，怎么显示？
我调研过几种可选容器：全局状态栏（statusline）最稳，但它是全局的，同时开多个窗口时上下文会互相覆盖；独立 buffer 最灵活，但每次刷新要重算高度和布局，反而增加复杂度；窗口顶部横条（winbar）是 Neovim 0.9 原生提供的，每个窗口都有自己的 winbar，互不干扰，是最合适的容器。
贴一段完整的渲染代码，这是整个模块的核心：
local function render_context() local bufnr = vim.api.nvim_get_current_buf() local winid = vim.api.nvim_get_current_win() local row, col = unpack(vim.api.nvim_win_get_cursor(winid)) row = row - 1 col = math.max(col - 1, 0) -- 跳过特殊模式：插入模式弹窗、命令行、模糊查找界面 if vim.bo[bufnr].buftype ~= '' then return end local scopes = get_context_nodes(bufnr, row, col) if #scopes == 0 then vim.api.nvim_win_set_option(winid, 'winbar', '') return end local segments = {} for _, node in ipairs(scopes) do local text = get_node_signature(node) if text then table.insert(segments, text) end end local bar = ' 📍 ' .. table.concat(segments, ' > ') vim.api.nvim_win_set_option(winid, 'winbar', bar) endget_node_signature负责把节点转成人类可读的名字。它的逻辑也很直接：根据节点类型提取名字字段。对于function_declaration，我从子节点里找名字节点；对class_definition类似；递归的时候要小心嵌套的匿名函数，它们没有名字，那我就用(anonymous function)标记，防止渲染成空字符串。
这里有个细节我用得比较多：加入类型前缀。显示成function: processPending而不是只显示processPending，在多语言混合项目（比如前端一门语言里既有 ts 类型又有 tsx）中特别管用，能一眼分清当前是类还是函数。
3.3 第三步：触发更新的时机与性能优化
每次光标移动都全量重算语法树肯定不行，树很大，几百毫秒的卡顿谁都受不了。我的做法是分两档：
CursorMoved事件：走节流，150ms 内的连续移动只更新一次。CursorMovedI插入模式事件：同样节流，但更新频率降到 300ms。插入模式下用户手速快，如果每敲一个字符都刷新，视觉上会闪得很难受。
更重要的是只做增量计算。tree-sitter 的get_node_at_pos本身是有缓存机制的，它只从根节点向光标位置做一次线性定位，复杂度基本是树的深度，和整个文件大小无关。所以大部分场景下性能压力小到可以忽略。唯一要注意的是避免在TextChanged之类的高频事件里直接调用渲染函数，必须包一层定时器。
local function debounce(fn, wait) local timer = vim.uv.new_timer() return function(...) local args = { ... } timer:stop() timer:start(wait, 0, function() vim.schedule(function() fn(unpack(args)) end) end) end end这段代码是标准的 debounce 实现，我实际用在生产环境里已经一年多，体验上没有任何迟滞感。如果你的机器比较老，可以把 wait 从 150 改成 200，视觉上没有本质差别，但 CPU 占用会明显下降。
3.4 第四步：交互设计，让 context-mode 不只是显示
只有显示能力的 context-mode 还只是个“花架子”，真正好用必须配合交互。我给自己设计了三层交互逻辑，这也是我在实际使用中摸索出来的：
第一层，临时锁定。按一个键，当前窗口的上下文就固定住，光标怎么动都不变，再按一次解锁。这个功能在代码评审时特别有用：光标在一堆 diff 间来回跳，但我想知道这些改动都属于哪个上层功能，锁住上下文之后信息不丢。
第二层，点击跳转。winbar 上的每个上下文片段用%@区域扩展语法做成可点击的，用鼠标点“类”的片段，光标跳到类的定义处；点“函数”，跳到函数定义处。熟悉 Vim 鼠标支持的人都知道，默认点击不会产生跳转动作，所以这里要用mousemodel和MouseClicked事件配合处理。
第三层，上下文折叠整理。如果嵌套层级太深，比如一个函数里套了三个回调函数，winbar 一行放不下，我就只显示最外层两个和最内层一个，中间用省略号代替。这既保住了整体信息，又不会无限增长。
这三层交互加起来，context-mode 才真正从“显示器”变成了“工具”。这也是自建方案最大的价值——市面上的现成插件往往停在第一层，你得自己动手才能做到后面两层。
4. 与日常开发工作流的结合：LSP、tmux 和代码评审场景
4.1 让 context-mode 反向增强 LSP 的能力
一个很常见的场景：你在一个大文件里看到一个报错，LSP 会告诉你“这里有个类型错误”，但不会告诉你“这个错误发生在哪个方法里”。有了上下文模式之后，我可以把语法树提供的上下文和诊断信息拼在一起，渲染出更有价值的一行说明。
我给渲染函数加了一个分支逻辑：如果当前节点范围内有 LSP 诊断信息，就在 winbar 里追加一个⚠标记和错误摘要，用不同颜色区分。这样我在看报错时，不需要先定位到具体行，再从行数推算它在哪个函数里——诊断信息直接附着在上文语境中。
4.2 在 tmux 多窗口下的使用体验
我的日常环境是 tmux + Neovim 的组合，经常左右分屏，一边跑测试，一边改代码。这种情况下 context-mode 反而更有用：窗口收窄之后，每屏能显示的代码行数更少，更容易丢失上下文。我在左侧开了一个竖向窄窗口专门浏览代码树，右侧主编辑区保持 120 列宽，两边都用 context-mode，互不干扰，因为每一个窗口的 winbar 都是独立的。
一个小技巧：在窄窗口里，我手动把渲染层级减少到只显示类名和函数名，省去模块名。代码里有三层以上的嵌套，在 60 列宽的 winbar 里确实放不下。这个能力来源于自建方案的分层体满足条件，加了一个配置项depth_limit，不同窗口宽度应用不同深度。
4.3 用 context-mode 做代码评审，是个被低估的场景
代码评审时，我们看的往往是一个大 diff，但评审的核心不是看每一行改了什么，而是看这批改动在一个更大的逻辑里是否自洽。我习惯在评审前，让 context-mode 只渲染改动行所在的上下文，并根据 diff 结果，在 winbar 里显示一个[modified: 3 lines]的标记。这样扫到任何一个 chunk 时，都不用去列表里翻它属于哪个函数，就能对全貌有数。
和一个评审同事聊过，他第一次看到我的终端时很困惑地问：“这一行OrderService > processPending [modified: 5 lines]是你手动写的注释吗？”我解释说这是自动化渲染的，他立刻意识到如果能把这个数据导出成一个文件，就是天然的评审摘要。这算是 context-mode 的一个衍生价值——它不仅服务于写代码的过程，还能服务于代码流转的整个过程。
5. 常见问题与排查技巧实录
5.1 上下文信息不出来，尤其是新装语言 parser 之后
这个问题十次里有八次是 tree-sitter parser 没装上，Neovim 本身没有语法树可用，get_node_at_pos直接返回空。排查方式是执行:checkhealth treesitter或直接看:TSInstallInfo里对应语言的 parser 是否已安装。装完之后记得重启 Neovim 或者执行:TSUpdate强制刷新。
还有一个坑是光标落在空白行、注释里或者字符串里，语法树在这个位置根本没有合法的叶子节点，所以自然没上下文。这其实是正常现象，我的处理是让它留空，而不是强行回退到文本缩进猜测。用户看着上下文突然消失会有点奇怪，但这个行为是准确的：光标确实不在任何代码结构里。
5.2 大文件（两千行以上）出现渲染卡顿
性能瓶颈一般不在语法树取值，而在渲染本身。winbar 的每一次 set 操作都会触发一次完整的 UI 重绘，如果你用 debounce 控制了触发频率，理论上不会卡。我实际遇到过一次卡顿，排查后发现是渲染函数里调用了node:start()、node:end()拿范围，这个操作在深层嵌套代码里会触发子节点遍历，复杂度不是 O(1) 的。优化方案是只取一次根节点范围，在遍历节点的过程中缓存关键字段，避免反复调用。
另一个实测经验：两千行以内的文件，150ms debounce 毫无压力；五千行的大文件，重启后第一次进入会有一次约 80ms 的解析延迟，后续移动都是毫秒级响应。如果对延迟敏感，开一个大文件的瞬间可以先按zz让视口稳定下来，再开始移动，体验上几乎无感。
5.3 和代码折叠功能冲突
代码折叠（fold）和 winbar 的好处都是“在有限的屏幕里展示更多结构信息”，但两者会互相干扰。折叠后光标所在折叠行的节点范围可能被截断，语法树返回的上下文有时是折叠区域外的根部节点，有时是整个折叠块。
我的处理方案是：渲染前先检查当前视图里有没有打开的折叠，如果光标所在行没有被折叠，就正常渲染；如果光标所在行折叠了，就只显示最外层一个节点，不深入展开。这个逻辑很顺手，因为折叠本身就是一种“自定义上下文”——用户主动选择隐藏的层级，不需要再渲染一遍。
5.4 问题速查表
| 表现 | 最可能原因 | 处理方式 |
|---|---|---|
| winbar 完全空白 | tree-sitter parser 未安装 | :TSInstall <language> |
| winbar 在部分行显示、部分行空白 | 光标在注释/空白/字符串内 | 正常行为，无需修复 |
| 渲染延迟大于 300ms | debounce 时间过长或机器性能差 | 调低 debounce 到 100ms，或减小depth_limit |
| 折叠后上下文层级错误 | 折叠阻挡了语法树遍历 | 检测折叠状态，只渲染最外层节点 |
| 插入模式下频繁闪烁 | TextChangedI 事件触发太勤 | 专门为插入模式延长 debounce |
| 多窗口同时打开时上下文相互串 | 误用全局 statusline 而非 winbar | 改用nvim_win_set_option设置 winbar |
这六条基本上覆盖了我在真实使用中碰过的所有问题类型。如果看完某一类仍然解决不了，我建议你单独写一段最小复现代码，分别打印语法树节点类型和 winbar 最终渲染值，对照一下是节点获取环节出错还是渲染环节出错，基本一分钟内就能定位。
6. 一些可以继续扩展的方向
如果你已经实现了上面这套基础 context-mode，你可能会发现它已经能覆盖大部分日常场景。但我个人觉得它最有想象力的地方还在后面。
一个方向是调用链上下文。语法树只知道词法上下文，它告诉你“这个函数在一个类里”，但不知道“这个类是谁在用它”。配合 LSP 的workspace/symbol和textDocument/references，你可以把调用者信息也渲染进来，这样 context-mode 就从“我在哪”扩展成了“谁在用我”。做大规模重构的时候，这个价值会体现得特别明显。
另一个方向是跨文件上下文。打开一个接口文件改签名时，如果 context-mode 能顺带在 winbar 里提示“这个签名在三个实现类里被用到”，你就不用先跑一遍全局搜索再改。这个目前需要额外调用语言服务 API，但架构上完全可以和现有模块平级对接。
还有一个小而美的方向：把 context-mode 的信息导出成 JSON，配合自动化脚本生成项目接口摘要。代码评审、新人 onboarding、接口文档生成，都可以直接受益于这份数据。
我在实际中使用 context-mode 已经有很长一段时间了，最直观的改变不是某个操作变快了，而是改代码时的心流更连贯了。以前从函数头跳回函数体内容时总需要一两次“确认自己没看错位置”，现在这个确认动作被系统实时完成了。如果你也经常在长文件里迷失方向，我认为花一下午照着上面的思路做一套适合自己的 context-mode，是很值得的投入。
