长文档处理一直有个很烦的问题搜得到行号搜不到“位置”。为了搞定它我自己写了一个叫 context-mode 的小工具——一个专门给文本行计算“上下文路径”的命令行扫描器。先讲一个真实场景你就知道我说的是什么。去年我接手一份快两千行的产品配置文档里面既有参数说明、又有命令行示例还夹着几段历史变更记录。同事告诉我“timeout 的问题去文档里搜一下就行”。我搜到 timeout30 在第 742 行但问题来了——这一行到底属于哪个章节是全局配置还是某一处示例代码我往上翻了大概五屏才在缩进里找到一个二级标题确认它属于“网络调优”那一节。这种“搜到行号却不知道身在何处”的体验我相信每个处理过长文档的人都遇到过。后来我把这套“上下文定位”的能力独立成了一个工具也就是 context-mode。它扫描 Markdown、YAML、配置说明这类半结构化文本为任意行号计算出一条上下文路径也能按模式批量导出区块。这篇文章就是它的完整复盘从设计动机、核心实现到我自己踩过的三个坑再到怎么把它接进日常编辑和提交流程。1. 从“搜到行号却不知道身在何处”说起context-mode 的诞生动机1.1 一次折腾了我半小时的定位经历先说那次让我决定动手的经历。文档结构大概是这样的开头是全局参数说明中间是不同模块的配置示例每个示例下面还跟了几段“历史变更原因”。我用搜索命令找到了 timeout30它在第 742 行。但这一行是在“网络模块示例”的代码块里还是在“超时参数说明”的普通段落里我看不到。往上有多少层嵌套是标题直接包含还是标题下面是列表、列表里面才是代码块不看上下文完全无法判断。我往上翻找到最近的标题发现是“网络调优”可这个标题下面还有三四个小节742 行到底归哪个小节管我又得继续往上翻。等我把整条链路理清楚时间已经过去了近半小时。更尴尬的是第二天同事 A 问同一个问题我又把刚才的過程重复了一遍。那一刻我真切意识到搜索工具给了我“在哪一行”却没给我“在这一行所处的结构里”。定位行号是线性的而文档结构是树形的两者之间缺一座桥。1.2 搜索、大纲、折叠为什么都差一口气可能有人会说编辑器里有大纲、有折叠你把侧边栏打开不就能看到章节了吗我在实际使用中都觉得差一口气。搜索/正则只能给行号不能回答“这一行属于哪个标题下的哪个代码块”。大纲只展示标题层级覆盖不到代码块、引用块、列表和 frontmatter。就算展示你也得先在正文里定位到第 742 行再回大纲里找对应章节来回切。折叠适合人眼交互但在命令行、脚本、CI 钩子里完全不可用。写正则做局部匹配当然可以但一旦文档有嵌套围栏、标题跳级、引用块跨段正则会变得非常脆弱写一次修半年。我要的并不是“再找一个更好的搜索工具”而是一个能独立工作的、结构感知的小引擎。给它一个文件和一个行号它告诉我完整的上下文路径给它一个文件和一个模式它把属于该模式的所有区块导出。这个定位就是 context-mode 的雏形。1.3 产品定义给每一行算出它的上下文路径第一次动手前我把目标收敛成了三句话能扫描文档构建出“上下文区块树”。能按行号查询返回当前行所在的所有活动区块拼接成一条上下文路径。能按模式导出区块把文档里的代码块、引用、标题、列表当成可编程的数据。它不追求把文档解析成完美的语法树也不打算替代语言服务器。它只做一件事用轻量的边界规则和模式栈给半结构化文本提供“我在哪”的答案。核心概念就是这个“上下文路径”比如网络调优 示例 代码块 bash 第 742 行。这条路径既给人看也适合被脚本消费。我把工具命名为 context-mode也是因为它的工作方式就是“按模式理解上下文”。想清楚这三句话之后后面所有设计都有了主线。2. 想明白核心设计模式栈、边界规则与上下文路径2.1 区块与模式的最小抽象模式mode和区块block是 context-mode 最底层的两个概念。模式是“这段文字属于哪种结构”区块是“文档里一段连续且模式一致的行区间”。一个区块至少包含模式、起始行、结束行、父区块以及某些模式下附带的信息标题文字、围栏语言等。我第一版只支持了六种模式覆盖了绝大多数日常文档场景。模式开始标志结束标志嵌套说明title行首#到######被同级或更高级标题“隐式闭合”支持跳级按层级弹栈fence行首 开围栏对应 收围栏需校验围栏长度和缩进前缀quote行首连续引用行结束可跨多个段落list行首-、*或数字.连续列表项结束对缩进敏感frontmatter文件首行---下一个---只在文件头部生效para其他所有行连续普通文字结束兜底用不允许嵌套这个设计刻意做得很薄。模式不要求“语法正确”只要求“边界可识别”。哪怕文档写得再烂扫描器也能给出一个不报错的、可以接受的结果。这种心态在后面踩坑时救了我很多次。2.2 模式栈的工作原理入栈、出栈与隐式闭合扫描器按行读取文本维护一个“活动区块栈”。栈顶就是当前行所属的最内层区块。处理逻辑可以概括成四条规则遇到模式的开始边界把新区块压入栈顶。遇到模式的结束边界把对应区块从栈里弹出。遇到标题行先把栈里所有级别不小于新标题级别的标题区块全部弹出再把新标题压入。普通行如果落在任何区块外就归入一个 para 区块如果已经在一个区块内就继续扩展当前区块。这里最关键的是标题的“隐式闭合”。Markdown 里没有显式的“标题结束”标记H2 的结束全靠下一个 H2 或更高级别标题的出现。如果你写了一个 H1下面直接跳 H4然后下一个标题是 H2那么 H4 和 H3如果存在都应该被 H2 自动终止。弹栈规则我最终定为新标题入栈前把所有标题级别大于等于新标题级别的标题都弹出。举个例子遇到 H1栈变成[H1]遇到 H4栈变成[H1, H4]遇到 H2先弹出 H4因为 H4 的级别 4 大于等于 H2 的级别 2再检查 H1级别 1 小于 2保留最后压入 H2栈变成[H1, H2]这样即使中间缺了 H3路径也不会出现“H4 挂在 H1 下面”这种误导。这条规则看似简单却是后来一次重要 bug 修复的根源我放到第 4 节细讲。2.3 上下文路径的结构与查询语义有了活动区块栈查询就变得非常直接给定行号把当前这个行号处于其中的所有活动区块按顺序取出来就是上下文路径。我设计了一个 JSON 结构让它既能给人读也能被机器消费{ line: 742, path: [ { mode: title, level: 2, title: 网络调优 }, { mode: fence, language: bash } ], text: timeout30 }路径数组的第一个元素是最外层区块最后一个是最内层区块。最外层通常是标题如果没有标题就以根节点开始。查询接口返回“路径 原文那行文本”这两样拼在一起就完整回答了“我在哪、这段是什么”。我在 CLI 里也做了两种输出默认是带缩进的人类可读格式加--format json则输出上面的结构方便管道和插件消费。选择路径而不是嵌套字符串有一个实际考虑脚本拿到路径后可以直接按path[0].title取标题、按path[1].mode fence判断是否在代码块里不需要 parse 字符串。这比“输出一串A B C”要灵活得多。人看的时候我再把 path 渲染成带箭头的字符串两全其美。2.4 为什么不做完整语法树开发成本与韧性解析的取舍很多人第一反应是现在解析 Markdown/YAML 的库那么多直接引入不好吗我的答案是不好。完整解析要做对的事情太多了各种方言、转义、代码块内嵌特殊语法、表格、脚注、带属性的引用……每支持一种格式就要引入一个解析器最后整个工具变成一大堆解析器外加一堆“残缺文档兼容层”。context-mode 的立场很明确用模式扫描做“韧性解析”。什么是韧性解析就是我不追求 100% 准确理解文档的语义但我保证绝大多数正常文档能给出正确路径遇到看不懂的行兜底进入普通段落不报错、不中断扫描速度快内存可控。这是典型的 80/20 取舍用大约 20% 的规则覆盖 80% 的日常文档结构剩下的边界情况靠配置和后续规则来补。完整解析 vs 模式扫描我在设计文档里列过一张对比表维度完整语法树模式扫描准确性理论上最高足够好用但可能有误判开发成本每格式一套解析器一套边界规则引擎 规则表容错性依赖解析器对残错的容忍度天然兜底未知行归入段落速度通常较慢单次遍历O(n)依赖数量多零依赖这张表基本代表了我在第 3 节里所有工程决策的原则轻量、可组合、无依赖、CLI 优先。3. 第一版 CLI 实现用带类型标注的脚本写出可扫描、可查询的四百行核心3.1 技术选型与工程结构第一版我用的是带类型标注的脚本语言TypeScript 语法风格来实现没有引入任何第三方依赖。选择它的理由很直白类型能帮我定义清楚 Block、Border、ContextPath 这些核心数据结构而零依赖则保证这个工具在任意环境都能快速跑通——下载源码、编译、直接执行不用处理依赖树。工程结构我拆成这样src/ scanner.ts # 逐行扫描主循环维护模式栈 border.ts # 边界规则接口与内置规则 query.ts # 按行号查询上下文路径 export.ts # 按模式导出区块 cli.ts # 命令行入口 tests/ golden/ # golden files 测试样例为什么坚持把 scanner 和 CLI 分开因为核心扫描逻辑是可以被编辑器插件、提交钩子复用的纯函数CLI 只是最外层的一层壳。把纯函数和 IO 分开后面写测试和做集成都会舒服很多。3.2 边界规则表与逐行扫描主循环先定义边界规则的接口。它的核心思想是一条规则不是只看当前行而是看“当前行 当前栈状态”这样才有能力处理缩进、嵌套和上下文相关的边界。type Mode title | fence | quote | list | para | frontmatter; interface Block { mode: Mode; startLine: number; endLine: number; title?: string; // 标题文字 language?: string; // 围栏语言 parent?: Block; } interface BorderResult { action: open | close | continue | none; block?: Block; } // 规则签名输入当前行、当前栈、行号输出如何动作 type BorderRule ( line: string, lineNo: number, stack: Block[] ) BorderResult;扫描主循环也很直白就是逐行问每个规则“该怎么处理”function scan(text: string): Block[] { const stack: Block[] []; const blocks: Block[] []; const lines text.split(\n); for (let i 0; i lines.length; i) { const result matchBorder(lines[i], i 1, stack); if (result.action open) { result.block!.parent stack[stack.length - 1]; stack.push(result.block!); blocks.push(result.block!); } else if (result.action close) { // 关闭当前最内层区块回到父区块 const closed stack.pop(); if (closed) closed.endLine i; } else if (result.action none) { // 兜底如果栈顶不是段落则开启一个普通段落 ensurePara(i 1, stack, blocks); } // continue 表示继续扩展当前区块什么都不做 } // 收尾把所有未关闭区块的 endLine 设为最后一行 for (const block of stack) { block.endLine lines.length; } return blocks; }matchBorder会按优先级依次尝试内置规则标题最高因为标题的隐式闭合直接影响路径结构然后是围栏、引用、列表、frontmatter最后是段落兜底。为什么标题要排第一因为在 Markdown 里标题行是“重新划分上下文”的信号而围栏里的 bash 之类的内容虽然有标题特征但由于围栏规则在扫描时会占据栈顶围栏内部的任何行都不会再走标题规则。顺序保证了这一点。3.3 查询与导出的接口设计CLI 第一版只给了三个命令分别对应三条核心能力context-mode scan ./docs/setup.md context-mode path ./docs/setup.md --line 742 context-mode export ./docs/setup.md --mode fence --language bashscan输出整个上下文树的结构适合用来理解一份陌生文档的骨架。path是我们最常用的定位命令输出我上面给出的 JSON 结构。export则把某个模式下的所有区块都列出来典型用法是“把这份文档里所有 bash 代码块抽出来检查”。导出格式我额外加了一种 JSON Lines每个区块占一行而不是整个结果包成一个巨大的 JSON 数组。为什么大批量导出时JSON Lines 可以边读边处理内存占用稳定也方便用管道接给其他命令。这个选择在扫描上万行的日志类文档时尤其有用。3.4 用 golden files 守住边界回归边界规则最容易出的问题是“修好一个嵌套结果破坏了一个引用”。所以第一版写完扫描器我就把测试重心放在了 golden files 上。做法是准备一组代表性文档和一个期望输出文件nested-fence.md围栏内再放围栏覆盖行首缩进场景jump-title.mdH1 直接跳 H4再跳 H2mixed-list-quote.md列表和引用交替出现frontmatter-body.md带 YAML 头部和正文混排garbage.md故意放一些无法识别的行每个样例都配一份.expected.json里面是这条文档应该生成的上下文树。改规则时跑一次批量对比任何与期望不符的行为会立刻暴露。为什么不用几百个单元测试堆断言因为边界规则的本质是“组合行为”——单行规则好测但多行组合起来的状态爆炸只有用完整文档级别的 golden test 才能兜住。后来我所有“踩坑修复”都先补一个 golden 样例再改扫描器这成了我维护这个项目最重要的习惯。4. 实测踩坑记录嵌套围栏、标题跳级与扫描器性能退化4.1 嵌套围栏行首空格与围栏长度的一致性校验第一个坑出现在处理一份说明文档时文档里有一个“如何写代码块”的示例。为了展示嵌套的作者在外部围栏里约定“内部围栏前加四个空格”。早期扫描器判断围栏结束只看“这一行是不是”结果一到这个示例内部那行 就被当成了外层围栏的结束标记。后续所有内容全部错位报告出来的路径彻底乱了。我修了两处。第一围栏闭合必须校验“围栏长度一致”开着bash闭合就必须是至少三个反引号而不是任意数量并且语言标记可以省略但反引号个数不能小于开启时的个数。第二必须校验缩进前缀如果外层围栏内容整体缩进了四个空格那么内层 也在缩进之后就不能作为外层围栏的闭合标记。这给我一个很重要的教训边界规则不能是“看一行就下结论”的纯函数它必须感知当前所在的区块状态。闭合行只有在“它前面的字符与当前围栏开启时相同位置对齐”的情况下才有效。这个思路后来被抽象成了BorderRule的“当前栈”参数也就是我第 3 节那个接口设计的由来。4.2 标题层级跳变隐式闭合的弹栈规则第二个坑是关于标题的。有一次我用 context-mode 扫描一份技术文档查询一个在第 1500 行的参数。结果路径里出现了“H1: 配置参考 H4: 参数列表 第 1500 行”但我怎么找都没找到 H3。问题在于文档结构是 H1 下面直接写了一个 H4而 H4 之后又跟着一个 H2。我最初的实现是遇到新标题时只在“新标题级别等于当前栈顶标题级别”时才弹出当前标题。结果 H4 遇到 H2 时因为级别不相等H4 就一直挂在栈里H2 变成了 H4 的兄弟而不是 H1 的下一层。路径导出的章节关系完全错乱。修复就是我在 2.2 节写的那条弹栈规则新标题入栈前弹出所有标题级别 ≥ 新标题级别的标题区块。改成这个规则后H4 遇到 H2 会先被弹出H2 变成挂在 H1 下面路径就正了。这个 fix 改动只有三行但影响面非常大。也是从这次开始我给标题规则单独写了三个 golden 样例专门覆盖跳级、缺级和跨级回升这几类情况。对我而言这是整个项目里最值钱的一个修复。4.3 三万行文件的内存与性能问题第三个坑不是功能错误而是性能。有次我把 context-mode 扔给一份三万行的配置文件日志扫描过程足足卡了几秒内存峰值涨到接近一个配置原本大小的几十倍。排查后发现两个问题。一是我扫描时把“区块原文”完整保存在每个区块对象里。三万行的大部分内容都被复制了一遍。比如一个围栏区块有三万行我就存了三万行字符串下一层的段落区块又存了一份。解决办法是只保留区块元信息模式、起止行、标题、语言原文在查询时按行号延迟读取。这把内存占用降到了原来的五分之一左右。二是查询路径的时候我为每一行都构造了一个完整路径数组。三万行等于有三万个数组每个数组里还有共享的父区块引用GC 压力很大。优化方法是把路径压缩成“父区块 ID 当前行号”需要完整路径时再懒加载展开。优化后三万字级别文件扫描稳定在一秒以内内存表现也正常了。我总结出一个通用原则CLI 工具的生死线往往不是功能而是“它能不能处理大文件”。如果一份三万行的文档跑不动用户不会觉得是文档太大只会觉得是工具不行。性能优化必须前置到这个程度。4.4 复盘三条边界设计原则踩完这三个坑我把边界设计总结成三条原则之后所有新规则都按这个标准评审边界判定必须同时看“当前行”和“当前栈”禁止纯行级规则。标题通过“层级弹栈”实现隐式闭合而不是通过“遇到同级才闭合”。边界不确定时宁可兜底成普通段落也不要强行闭合强行闭合更容易造成后续大面积错位。这三条原则听起来简单但如果一开始就按它们设计三个坑能少踩两个。记录下来之后后面接新格式的规则时我基本再没遇到过结构整体错乱的问题。5. 接入日常工作流编辑器提示、提交信息与批量导出5.1 在编辑器状态栏显示当前上下文路径CLI 做出来后我最先做的是把它接进编辑器。我的编辑环境支持“外部命令 状态栏”所以只需要写一个监听脚本文件变化或光标移动时把光标所在行号传给context-mode path然后把返回的路径字符串显示在状态栏。效果就是我在任何一份长文档里移动光标状态栏实时显示配置参考 网络调优 bash 代码块 第 742 行这个功能用了半天就适应了之后再遇到“这里在哪”的问题基本不用手动翻屏。可以这么讲之前靠记忆和视觉追踪的“上下文”现在变成了编辑器给你的一个常量提示。对写长文档、review 配置、维护 CHANGELOG 的人来说这种提示会明显减少漂泊感。5.2 提交钩子里自动生成“影响章节清单”第二个工作流集成是给版本管理工具加提交钩子。这个需求的来源很具体一次 A 同学提了一个很大的变更涉及文档的多个段落提交说明只写了“更新配置说明”。review 的人根本不知道这次改动影响了哪些章节得把整个 diff 打开一屏一屏看。我的方案是在提交钩子里做三步拿到本次变更涉及的文件和行范围对每个行范围调用context-mode path取上下文路径里的标题部分把去重后的标题清单追加到提交说明里。这样提交说明会自动带上“影响章节配置参考 / 网络调优故障排查 / 示例 3”review 者一眼就能判断这个提交是不是改对了地方。这个功能在公司内部推广后被问得最多的不是“怎么实现的”而是“这个能不能用在代码提交上”——但代码提交要的是语言服务器级别的符号信息context-mode 只做文本结构感知两者定位不同不能硬套。5.3 把文档当数据按模式过滤与批量导出第三个用法是把我说的“文档当数据”落地。context-mode 的 export 命令让我可以对文档做很多原本要写一次性脚本文档才能做到的事# 抽出一份文档里所有 bash 代码块逐个做基础语法检查 context-mode export ./docs/setup.md --mode fence --language bash # 抽出所有引用内容做观点汇编 context-mode export ./docs/setup.md --mode quote # 只看某个行范围内的代码块不改整体配置 context-mode export ./docs/setup.md --mode fence --range 100-300因为输出格式是 JSON Lines这些结果可以直接接到while read循环或者jq处理流水线里。我自己最常用的组合是context-mode export diff 版本管理 diff做一个“影响面报告”先算出 diff 影响的行范围再按映射导出这些行涉及的标题区块最后汇总成一条“这个提交会不会碰到配置文件核心区”的提示。这个还只是一个星期前才开始用的组合但已经节省了大量 review 时间。5.4 实际收益与仍存在的边界接入工作流之后我自己的数据感受是定位参数所属章节从原来的三五分钟变成了几秒钟review 别人文档提交时不需要再逐段展开找章节归属。但这不等于没有短板。表格、折叠区、内嵌模板语法比如{{ }}、以及代码块里再嵌套 Markdown 标注的情况context-mode 目前都处理不好。表格行的边界识别比列表复杂得多模板语法又高度依赖具体项目的方言。我的策略是这些场景先不失真兜底等真有需要时再加规则而不是一开始就把解析器做到沉重无比。还是那句话它是“轻量上下文工具”不是“文档完整解析器”。6. 关于取舍、配置方言与后续设想6.1 什么场景真正适合 context-mode什么场景别硬上用了这么久我对它的适用范围有比较清晰的认知。适合的场景长 Markdown 文档、README、CHANGELOG、配置说明的上下文导航半结构化文本的批量区块提取钩子脚本里快速生成“影响章节清单”日志类文本按块做粗粒度分析。不适合的场景需要精确语法理解的代码重构这种需求应该交给语言服务/AST 工具对文档语义要求很高的场景比如生成正式 API 文档表格密集、模板语法密集、格式高度方言化的文档。context-mode 的价值不在“准确解析”而在“快速给出行号和结构之间的桥”。一旦你想让它承担语义分析就会不断加规则最终变成一个大而无当的解析器反而失去轻量优势。6.2 可配置的模式方言渐进增强而不是推倒重来不同团队对文档结构有不同的约定。有的团队喜欢用 HTML 注释当章节标记比如!-- section: 部署说明 --有的团队在 YAML 配置文件里用三层缩进表达层级。这些都默认进不了我内置的六种模式。我的解决方案是给 context-mode 加一个配置入口让用户能自定义模式规则{ rules: [ { name: html-section, mode: title, start: ^!--\\s*section:, end: ^!--\\s*/section: } ] }注意我这里的规则是新增而不是替换内置规则。这样安排的好处是内置模式保证开箱即用自定义规则只在需要时叠加。渐进增强的策略让这个工具适应了很多“方言文档”又不至于变成一个堆满配置的框架。我在实际使用中的体会是只要你把核心规则写死、扩展规则从配置读这个工具的边际成本会非常低。6.3 后续设想并行扫描、标准输出格式与规则生态后续的路线图上还有几件事没做完。一是并行扫描目前整份文档是单线程逐行扫描理论上可以按“能确定闭合关系的边界”做分块再并行构建区块树让超大日志文档也能秒开。二是标准输出格式我计划兼容标签文件协议和语言服务器协议的近似形态这样编辑器和 CI 工具可以按标准协议直接消费上下文路径而不是每家写一个专用对接。三是规则生态希望将来能允许用户发布独立的模式规则包不同团队可以共享自己验证过的“方言规则”。这几项都还没完全落地所以我不打算把它们写得太具体。方向是明确的保持零依赖、CLI 优先、韧性解析。只要这三点不变工具就不会因为膨胀而失去定位。6.4 个人体会把“上下文路径”当成一种通用中间表示最后分享一点个人体会。最初写 context-mode 只是为了解决自己找不到章节的恼火但写完之后我发现“上下文路径”这个抽象的价值远超预期。它本质上是一种通用的中间表示一段文本处在什么结构里、它的父区块是谁、属于什么模式这些信息对搜索、diff、review、 IDE 提示都很有用。当我把 context-mode 从一个“给自己用的脚本”升级成“一套边界规则引擎 查询接口”之后它才真正被团队用起来变成提交钩子和编辑器集成里的公共底座。如果你也在做类似的小工具我的建议是先别急着堆功能把“输入一行输出它在结构里的位置”这个核心闭环做扎实然后用 golden files 把边界行为锁住再加工作流集成。小的 CLI 工具最大的优势就是可以频繁改造而不必太早固化接口。可以说context-mode 目前还在持续演进中而最让我满意的其实不是它处理得有多快而是它让“搜到行号却不知道在哪”这个长期困扰消失了每次在状态栏里看到那串上下文路径我都觉得这工具写得值。 
长河君 · 2026/10/20 21:18:28 · 阅读 1.2k context-mode：为长文档每一行计算上下文路径的 CLI 工具
长文档处理一直有个很烦的问题搜得到行号搜不到“位置”。为了搞定它我自己写了一个叫 context-mode 的小工具——一个专门给文本行计算“上下文路径”的命令行扫描器。先讲一个真实场景你就知道我说的是什么。去年我接手一份快两千行的产品配置文档里面既有参数说明、又有命令行示例还夹着几段历史变更记录。同事告诉我“timeout 的问题去文档里搜一下就行”。我搜到 timeout30 在第 742 行但问题来了——这一行到底属于哪个章节是全局配置还是某一处示例代码我往上翻了大概五屏才在缩进里找到一个二级标题确认它属于“网络调优”那一节。这种“搜到行号却不知道身在何处”的体验我相信每个处理过长文档的人都遇到过。后来我把这套“上下文定位”的能力独立成了一个工具也就是 context-mode。它扫描 Markdown、YAML、配置说明这类半结构化文本为任意行号计算出一条上下文路径也能按模式批量导出区块。这篇文章就是它的完整复盘从设计动机、核心实现到我自己踩过的三个坑再到怎么把它接进日常编辑和提交流程。1. 从“搜到行号却不知道身在何处”说起context-mode 的诞生动机1.1 一次折腾了我半小时的定位经历先说那次让我决定动手的经历。文档结构大概是这样的开头是全局参数说明中间是不同模块的配置示例每个示例下面还跟了几段“历史变更原因”。我用搜索命令找到了 timeout30它在第 742 行。但这一行是在“网络模块示例”的代码块里还是在“超时参数说明”的普通段落里我看不到。往上有多少层嵌套是标题直接包含还是标题下面是列表、列表里面才是代码块不看上下文完全无法判断。我往上翻找到最近的标题发现是“网络调优”可这个标题下面还有三四个小节742 行到底归哪个小节管我又得继续往上翻。等我把整条链路理清楚时间已经过去了近半小时。更尴尬的是第二天同事 A 问同一个问题我又把刚才的過程重复了一遍。那一刻我真切意识到搜索工具给了我“在哪一行”却没给我“在这一行所处的结构里”。定位行号是线性的而文档结构是树形的两者之间缺一座桥。1.2 搜索、大纲、折叠为什么都差一口气可能有人会说编辑器里有大纲、有折叠你把侧边栏打开不就能看到章节了吗我在实际使用中都觉得差一口气。搜索/正则只能给行号不能回答“这一行属于哪个标题下的哪个代码块”。大纲只展示标题层级覆盖不到代码块、引用块、列表和 frontmatter。就算展示你也得先在正文里定位到第 742 行再回大纲里找对应章节来回切。折叠适合人眼交互但在命令行、脚本、CI 钩子里完全不可用。写正则做局部匹配当然可以但一旦文档有嵌套围栏、标题跳级、引用块跨段正则会变得非常脆弱写一次修半年。我要的并不是“再找一个更好的搜索工具”而是一个能独立工作的、结构感知的小引擎。给它一个文件和一个行号它告诉我完整的上下文路径给它一个文件和一个模式它把属于该模式的所有区块导出。这个定位就是 context-mode 的雏形。1.3 产品定义给每一行算出它的上下文路径第一次动手前我把目标收敛成了三句话能扫描文档构建出“上下文区块树”。能按行号查询返回当前行所在的所有活动区块拼接成一条上下文路径。能按模式导出区块把文档里的代码块、引用、标题、列表当成可编程的数据。它不追求把文档解析成完美的语法树也不打算替代语言服务器。它只做一件事用轻量的边界规则和模式栈给半结构化文本提供“我在哪”的答案。核心概念就是这个“上下文路径”比如网络调优 示例 代码块 bash 第 742 行。这条路径既给人看也适合被脚本消费。我把工具命名为 context-mode也是因为它的工作方式就是“按模式理解上下文”。想清楚这三句话之后后面所有设计都有了主线。2. 想明白核心设计模式栈、边界规则与上下文路径2.1 区块与模式的最小抽象模式mode和区块block是 context-mode 最底层的两个概念。模式是“这段文字属于哪种结构”区块是“文档里一段连续且模式一致的行区间”。一个区块至少包含模式、起始行、结束行、父区块以及某些模式下附带的信息标题文字、围栏语言等。我第一版只支持了六种模式覆盖了绝大多数日常文档场景。模式开始标志结束标志嵌套说明title行首#到######被同级或更高级标题“隐式闭合”支持跳级按层级弹栈fence行首 开围栏对应 收围栏需校验围栏长度和缩进前缀quote行首连续引用行结束可跨多个段落list行首-、*或数字.连续列表项结束对缩进敏感frontmatter文件首行---下一个---只在文件头部生效para其他所有行连续普通文字结束兜底用不允许嵌套这个设计刻意做得很薄。模式不要求“语法正确”只要求“边界可识别”。哪怕文档写得再烂扫描器也能给出一个不报错的、可以接受的结果。这种心态在后面踩坑时救了我很多次。2.2 模式栈的工作原理入栈、出栈与隐式闭合扫描器按行读取文本维护一个“活动区块栈”。栈顶就是当前行所属的最内层区块。处理逻辑可以概括成四条规则遇到模式的开始边界把新区块压入栈顶。遇到模式的结束边界把对应区块从栈里弹出。遇到标题行先把栈里所有级别不小于新标题级别的标题区块全部弹出再把新标题压入。普通行如果落在任何区块外就归入一个 para 区块如果已经在一个区块内就继续扩展当前区块。这里最关键的是标题的“隐式闭合”。Markdown 里没有显式的“标题结束”标记H2 的结束全靠下一个 H2 或更高级别标题的出现。如果你写了一个 H1下面直接跳 H4然后下一个标题是 H2那么 H4 和 H3如果存在都应该被 H2 自动终止。弹栈规则我最终定为新标题入栈前把所有标题级别大于等于新标题级别的标题都弹出。举个例子遇到 H1栈变成[H1]遇到 H4栈变成[H1, H4]遇到 H2先弹出 H4因为 H4 的级别 4 大于等于 H2 的级别 2再检查 H1级别 1 小于 2保留最后压入 H2栈变成[H1, H2]这样即使中间缺了 H3路径也不会出现“H4 挂在 H1 下面”这种误导。这条规则看似简单却是后来一次重要 bug 修复的根源我放到第 4 节细讲。2.3 上下文路径的结构与查询语义有了活动区块栈查询就变得非常直接给定行号把当前这个行号处于其中的所有活动区块按顺序取出来就是上下文路径。我设计了一个 JSON 结构让它既能给人读也能被机器消费{ line: 742, path: [ { mode: title, level: 2, title: 网络调优 }, { mode: fence, language: bash } ], text: timeout30 }路径数组的第一个元素是最外层区块最后一个是最内层区块。最外层通常是标题如果没有标题就以根节点开始。查询接口返回“路径 原文那行文本”这两样拼在一起就完整回答了“我在哪、这段是什么”。我在 CLI 里也做了两种输出默认是带缩进的人类可读格式加--format json则输出上面的结构方便管道和插件消费。选择路径而不是嵌套字符串有一个实际考虑脚本拿到路径后可以直接按path[0].title取标题、按path[1].mode fence判断是否在代码块里不需要 parse 字符串。这比“输出一串A B C”要灵活得多。人看的时候我再把 path 渲染成带箭头的字符串两全其美。2.4 为什么不做完整语法树开发成本与韧性解析的取舍很多人第一反应是现在解析 Markdown/YAML 的库那么多直接引入不好吗我的答案是不好。完整解析要做对的事情太多了各种方言、转义、代码块内嵌特殊语法、表格、脚注、带属性的引用……每支持一种格式就要引入一个解析器最后整个工具变成一大堆解析器外加一堆“残缺文档兼容层”。context-mode 的立场很明确用模式扫描做“韧性解析”。什么是韧性解析就是我不追求 100% 准确理解文档的语义但我保证绝大多数正常文档能给出正确路径遇到看不懂的行兜底进入普通段落不报错、不中断扫描速度快内存可控。这是典型的 80/20 取舍用大约 20% 的规则覆盖 80% 的日常文档结构剩下的边界情况靠配置和后续规则来补。完整解析 vs 模式扫描我在设计文档里列过一张对比表维度完整语法树模式扫描准确性理论上最高足够好用但可能有误判开发成本每格式一套解析器一套边界规则引擎 规则表容错性依赖解析器对残错的容忍度天然兜底未知行归入段落速度通常较慢单次遍历O(n)依赖数量多零依赖这张表基本代表了我在第 3 节里所有工程决策的原则轻量、可组合、无依赖、CLI 优先。3. 第一版 CLI 实现用带类型标注的脚本写出可扫描、可查询的四百行核心3.1 技术选型与工程结构第一版我用的是带类型标注的脚本语言TypeScript 语法风格来实现没有引入任何第三方依赖。选择它的理由很直白类型能帮我定义清楚 Block、Border、ContextPath 这些核心数据结构而零依赖则保证这个工具在任意环境都能快速跑通——下载源码、编译、直接执行不用处理依赖树。工程结构我拆成这样src/ scanner.ts # 逐行扫描主循环维护模式栈 border.ts # 边界规则接口与内置规则 query.ts # 按行号查询上下文路径 export.ts # 按模式导出区块 cli.ts # 命令行入口 tests/ golden/ # golden files 测试样例为什么坚持把 scanner 和 CLI 分开因为核心扫描逻辑是可以被编辑器插件、提交钩子复用的纯函数CLI 只是最外层的一层壳。把纯函数和 IO 分开后面写测试和做集成都会舒服很多。3.2 边界规则表与逐行扫描主循环先定义边界规则的接口。它的核心思想是一条规则不是只看当前行而是看“当前行 当前栈状态”这样才有能力处理缩进、嵌套和上下文相关的边界。type Mode title | fence | quote | list | para | frontmatter; interface Block { mode: Mode; startLine: number; endLine: number; title?: string; // 标题文字 language?: string; // 围栏语言 parent?: Block; } interface BorderResult { action: open | close | continue | none; block?: Block; } // 规则签名输入当前行、当前栈、行号输出如何动作 type BorderRule ( line: string, lineNo: number, stack: Block[] ) BorderResult;扫描主循环也很直白就是逐行问每个规则“该怎么处理”function scan(text: string): Block[] { const stack: Block[] []; const blocks: Block[] []; const lines text.split(\n); for (let i 0; i lines.length; i) { const result matchBorder(lines[i], i 1, stack); if (result.action open) { result.block!.parent stack[stack.length - 1]; stack.push(result.block!); blocks.push(result.block!); } else if (result.action close) { // 关闭当前最内层区块回到父区块 const closed stack.pop(); if (closed) closed.endLine i; } else if (result.action none) { // 兜底如果栈顶不是段落则开启一个普通段落 ensurePara(i 1, stack, blocks); } // continue 表示继续扩展当前区块什么都不做 } // 收尾把所有未关闭区块的 endLine 设为最后一行 for (const block of stack) { block.endLine lines.length; } return blocks; }matchBorder会按优先级依次尝试内置规则标题最高因为标题的隐式闭合直接影响路径结构然后是围栏、引用、列表、frontmatter最后是段落兜底。为什么标题要排第一因为在 Markdown 里标题行是“重新划分上下文”的信号而围栏里的 bash 之类的内容虽然有标题特征但由于围栏规则在扫描时会占据栈顶围栏内部的任何行都不会再走标题规则。顺序保证了这一点。3.3 查询与导出的接口设计CLI 第一版只给了三个命令分别对应三条核心能力context-mode scan ./docs/setup.md context-mode path ./docs/setup.md --line 742 context-mode export ./docs/setup.md --mode fence --language bashscan输出整个上下文树的结构适合用来理解一份陌生文档的骨架。path是我们最常用的定位命令输出我上面给出的 JSON 结构。export则把某个模式下的所有区块都列出来典型用法是“把这份文档里所有 bash 代码块抽出来检查”。导出格式我额外加了一种 JSON Lines每个区块占一行而不是整个结果包成一个巨大的 JSON 数组。为什么大批量导出时JSON Lines 可以边读边处理内存占用稳定也方便用管道接给其他命令。这个选择在扫描上万行的日志类文档时尤其有用。3.4 用 golden files 守住边界回归边界规则最容易出的问题是“修好一个嵌套结果破坏了一个引用”。所以第一版写完扫描器我就把测试重心放在了 golden files 上。做法是准备一组代表性文档和一个期望输出文件nested-fence.md围栏内再放围栏覆盖行首缩进场景jump-title.mdH1 直接跳 H4再跳 H2mixed-list-quote.md列表和引用交替出现frontmatter-body.md带 YAML 头部和正文混排garbage.md故意放一些无法识别的行每个样例都配一份.expected.json里面是这条文档应该生成的上下文树。改规则时跑一次批量对比任何与期望不符的行为会立刻暴露。为什么不用几百个单元测试堆断言因为边界规则的本质是“组合行为”——单行规则好测但多行组合起来的状态爆炸只有用完整文档级别的 golden test 才能兜住。后来我所有“踩坑修复”都先补一个 golden 样例再改扫描器这成了我维护这个项目最重要的习惯。4. 实测踩坑记录嵌套围栏、标题跳级与扫描器性能退化4.1 嵌套围栏行首空格与围栏长度的一致性校验第一个坑出现在处理一份说明文档时文档里有一个“如何写代码块”的示例。为了展示嵌套的作者在外部围栏里约定“内部围栏前加四个空格”。早期扫描器判断围栏结束只看“这一行是不是”结果一到这个示例内部那行 就被当成了外层围栏的结束标记。后续所有内容全部错位报告出来的路径彻底乱了。我修了两处。第一围栏闭合必须校验“围栏长度一致”开着bash闭合就必须是至少三个反引号而不是任意数量并且语言标记可以省略但反引号个数不能小于开启时的个数。第二必须校验缩进前缀如果外层围栏内容整体缩进了四个空格那么内层 也在缩进之后就不能作为外层围栏的闭合标记。这给我一个很重要的教训边界规则不能是“看一行就下结论”的纯函数它必须感知当前所在的区块状态。闭合行只有在“它前面的字符与当前围栏开启时相同位置对齐”的情况下才有效。这个思路后来被抽象成了BorderRule的“当前栈”参数也就是我第 3 节那个接口设计的由来。4.2 标题层级跳变隐式闭合的弹栈规则第二个坑是关于标题的。有一次我用 context-mode 扫描一份技术文档查询一个在第 1500 行的参数。结果路径里出现了“H1: 配置参考 H4: 参数列表 第 1500 行”但我怎么找都没找到 H3。问题在于文档结构是 H1 下面直接写了一个 H4而 H4 之后又跟着一个 H2。我最初的实现是遇到新标题时只在“新标题级别等于当前栈顶标题级别”时才弹出当前标题。结果 H4 遇到 H2 时因为级别不相等H4 就一直挂在栈里H2 变成了 H4 的兄弟而不是 H1 的下一层。路径导出的章节关系完全错乱。修复就是我在 2.2 节写的那条弹栈规则新标题入栈前弹出所有标题级别 ≥ 新标题级别的标题区块。改成这个规则后H4 遇到 H2 会先被弹出H2 变成挂在 H1 下面路径就正了。这个 fix 改动只有三行但影响面非常大。也是从这次开始我给标题规则单独写了三个 golden 样例专门覆盖跳级、缺级和跨级回升这几类情况。对我而言这是整个项目里最值钱的一个修复。4.3 三万行文件的内存与性能问题第三个坑不是功能错误而是性能。有次我把 context-mode 扔给一份三万行的配置文件日志扫描过程足足卡了几秒内存峰值涨到接近一个配置原本大小的几十倍。排查后发现两个问题。一是我扫描时把“区块原文”完整保存在每个区块对象里。三万行的大部分内容都被复制了一遍。比如一个围栏区块有三万行我就存了三万行字符串下一层的段落区块又存了一份。解决办法是只保留区块元信息模式、起止行、标题、语言原文在查询时按行号延迟读取。这把内存占用降到了原来的五分之一左右。二是查询路径的时候我为每一行都构造了一个完整路径数组。三万行等于有三万个数组每个数组里还有共享的父区块引用GC 压力很大。优化方法是把路径压缩成“父区块 ID 当前行号”需要完整路径时再懒加载展开。优化后三万字级别文件扫描稳定在一秒以内内存表现也正常了。我总结出一个通用原则CLI 工具的生死线往往不是功能而是“它能不能处理大文件”。如果一份三万行的文档跑不动用户不会觉得是文档太大只会觉得是工具不行。性能优化必须前置到这个程度。4.4 复盘三条边界设计原则踩完这三个坑我把边界设计总结成三条原则之后所有新规则都按这个标准评审边界判定必须同时看“当前行”和“当前栈”禁止纯行级规则。标题通过“层级弹栈”实现隐式闭合而不是通过“遇到同级才闭合”。边界不确定时宁可兜底成普通段落也不要强行闭合强行闭合更容易造成后续大面积错位。这三条原则听起来简单但如果一开始就按它们设计三个坑能少踩两个。记录下来之后后面接新格式的规则时我基本再没遇到过结构整体错乱的问题。5. 接入日常工作流编辑器提示、提交信息与批量导出5.1 在编辑器状态栏显示当前上下文路径CLI 做出来后我最先做的是把它接进编辑器。我的编辑环境支持“外部命令 状态栏”所以只需要写一个监听脚本文件变化或光标移动时把光标所在行号传给context-mode path然后把返回的路径字符串显示在状态栏。效果就是我在任何一份长文档里移动光标状态栏实时显示配置参考 网络调优 bash 代码块 第 742 行这个功能用了半天就适应了之后再遇到“这里在哪”的问题基本不用手动翻屏。可以这么讲之前靠记忆和视觉追踪的“上下文”现在变成了编辑器给你的一个常量提示。对写长文档、review 配置、维护 CHANGELOG 的人来说这种提示会明显减少漂泊感。5.2 提交钩子里自动生成“影响章节清单”第二个工作流集成是给版本管理工具加提交钩子。这个需求的来源很具体一次 A 同学提了一个很大的变更涉及文档的多个段落提交说明只写了“更新配置说明”。review 的人根本不知道这次改动影响了哪些章节得把整个 diff 打开一屏一屏看。我的方案是在提交钩子里做三步拿到本次变更涉及的文件和行范围对每个行范围调用context-mode path取上下文路径里的标题部分把去重后的标题清单追加到提交说明里。这样提交说明会自动带上“影响章节配置参考 / 网络调优故障排查 / 示例 3”review 者一眼就能判断这个提交是不是改对了地方。这个功能在公司内部推广后被问得最多的不是“怎么实现的”而是“这个能不能用在代码提交上”——但代码提交要的是语言服务器级别的符号信息context-mode 只做文本结构感知两者定位不同不能硬套。5.3 把文档当数据按模式过滤与批量导出第三个用法是把我说的“文档当数据”落地。context-mode 的 export 命令让我可以对文档做很多原本要写一次性脚本文档才能做到的事# 抽出一份文档里所有 bash 代码块逐个做基础语法检查 context-mode export ./docs/setup.md --mode fence --language bash # 抽出所有引用内容做观点汇编 context-mode export ./docs/setup.md --mode quote # 只看某个行范围内的代码块不改整体配置 context-mode export ./docs/setup.md --mode fence --range 100-300因为输出格式是 JSON Lines这些结果可以直接接到while read循环或者jq处理流水线里。我自己最常用的组合是context-mode export diff 版本管理 diff做一个“影响面报告”先算出 diff 影响的行范围再按映射导出这些行涉及的标题区块最后汇总成一条“这个提交会不会碰到配置文件核心区”的提示。这个还只是一个星期前才开始用的组合但已经节省了大量 review 时间。5.4 实际收益与仍存在的边界接入工作流之后我自己的数据感受是定位参数所属章节从原来的三五分钟变成了几秒钟review 别人文档提交时不需要再逐段展开找章节归属。但这不等于没有短板。表格、折叠区、内嵌模板语法比如{{ }}、以及代码块里再嵌套 Markdown 标注的情况context-mode 目前都处理不好。表格行的边界识别比列表复杂得多模板语法又高度依赖具体项目的方言。我的策略是这些场景先不失真兜底等真有需要时再加规则而不是一开始就把解析器做到沉重无比。还是那句话它是“轻量上下文工具”不是“文档完整解析器”。6. 关于取舍、配置方言与后续设想6.1 什么场景真正适合 context-mode什么场景别硬上用了这么久我对它的适用范围有比较清晰的认知。适合的场景长 Markdown 文档、README、CHANGELOG、配置说明的上下文导航半结构化文本的批量区块提取钩子脚本里快速生成“影响章节清单”日志类文本按块做粗粒度分析。不适合的场景需要精确语法理解的代码重构这种需求应该交给语言服务/AST 工具对文档语义要求很高的场景比如生成正式 API 文档表格密集、模板语法密集、格式高度方言化的文档。context-mode 的价值不在“准确解析”而在“快速给出行号和结构之间的桥”。一旦你想让它承担语义分析就会不断加规则最终变成一个大而无当的解析器反而失去轻量优势。6.2 可配置的模式方言渐进增强而不是推倒重来不同团队对文档结构有不同的约定。有的团队喜欢用 HTML 注释当章节标记比如!-- section: 部署说明 --有的团队在 YAML 配置文件里用三层缩进表达层级。这些都默认进不了我内置的六种模式。我的解决方案是给 context-mode 加一个配置入口让用户能自定义模式规则{ rules: [ { name: html-section, mode: title, start: ^!--\\s*section:, end: ^!--\\s*/section: } ] }注意我这里的规则是新增而不是替换内置规则。这样安排的好处是内置模式保证开箱即用自定义规则只在需要时叠加。渐进增强的策略让这个工具适应了很多“方言文档”又不至于变成一个堆满配置的框架。我在实际使用中的体会是只要你把核心规则写死、扩展规则从配置读这个工具的边际成本会非常低。6.3 后续设想并行扫描、标准输出格式与规则生态后续的路线图上还有几件事没做完。一是并行扫描目前整份文档是单线程逐行扫描理论上可以按“能确定闭合关系的边界”做分块再并行构建区块树让超大日志文档也能秒开。二是标准输出格式我计划兼容标签文件协议和语言服务器协议的近似形态这样编辑器和 CI 工具可以按标准协议直接消费上下文路径而不是每家写一个专用对接。三是规则生态希望将来能允许用户发布独立的模式规则包不同团队可以共享自己验证过的“方言规则”。这几项都还没完全落地所以我不打算把它们写得太具体。方向是明确的保持零依赖、CLI 优先、韧性解析。只要这三点不变工具就不会因为膨胀而失去定位。6.4 个人体会把“上下文路径”当成一种通用中间表示最后分享一点个人体会。最初写 context-mode 只是为了解决自己找不到章节的恼火但写完之后我发现“上下文路径”这个抽象的价值远超预期。它本质上是一种通用的中间表示一段文本处在什么结构里、它的父区块是谁、属于什么模式这些信息对搜索、diff、review、 IDE 提示都很有用。当我把 context-mode 从一个“给自己用的脚本”升级成“一套边界规则引擎 查询接口”之后它才真正被团队用起来变成提交钩子和编辑器集成里的公共底座。如果你也在做类似的小工具我的建议是先别急着堆功能把“输入一行输出它在结构里的位置”这个核心闭环做扎实然后用 golden files 把边界行为锁住再加工作流集成。小的 CLI 工具最大的优势就是可以频繁改造而不必太早固化接口。可以说context-mode 目前还在持续演进中而最让我满意的其实不是它处理得有多快而是它让“搜到行号却不知道在哪”这个长期困扰消失了每次在状态栏里看到那串上下文路径我都觉得这工具写得值。