你有没有过这种时刻代码改到一半想看一眼另一个文件里的函数定义于是切窗口、翻文件、看完再切回来刚才的思路已经断了或者排查线上日志grep 出几十条结果却记不清每一条前后到底发生了什么。终端是个放大器但它默认不给你“记忆”。我给自己的工作流加了一个叫context-mode的模式简单说就是一套运行在终端里的“上下文预览与提炼工具”它扫描文件树、自动提取每个文件里的关键区块在你不打开编辑器的情况下就能看到“这个文件里有什么、关键逻辑在哪”还能把这份结构摘要导出成 Markdown 或 JSON直接粘给 AI 工具、写周报、或者留作项目笔记。这个模式听起来很小但解决的是终端里最普遍的隐性问题上下文断层。前阵子我连续踩了几个坑最后干脆写了一个自包含的 Python 脚本把它固化成了日常工作流的一部分。这篇博文就把完整思路、实现细节、踩坑实录一起写出来。适合后端、运维、以及所有整天泡在终端里、又想让 AI 工具替自己省点力气的开发者参考。1. 为什么终端工作流需要 context-mode1.1 终端里的上下文断层比你想的更严重大部分人在终端里读代码和查日志靠的是三条命令cat、grep、less。这三条命令本身没问题问题出在它们都是“一次性视图”——你看到的是某个文件里匹配到的某个片段而不是这个文件的结构、这个目录的全貌。我打个比方看纸质地图的时候你手里有一张总览图还知道自己在哪一页、周边有什么。但在终端里普通查看文件相当于有人只把地图放大镜塞给你告诉你“这是第 42 页的一小块”至于这一页周围是什么、整本书目录长什么样一概不知。后果就是来回切。改 A 文件的时候要看 B 函数的签名切过去看完回来发现自己写到哪行都忘了查日志的时候 grep 出 50 条 ERROR但每条是哪个模块、发生在哪个请求里得再开好几个窗口对照时间戳。我做 context-mode 的出发点就是让终端具备一种“肌肉记忆”不管你正在看哪个文件都能一瞬间看到它的关键结构而不是把结构从你的工作记忆里“现翻”。1.2 “预览文件”和“理解文件”是两回事市面上很多终端工具都有 preview 模式比如fzf --preview能在文件列表旁边显示选中文件的内容片段。我用过一段时间发现它只能解决“预览”的问题解决不了“理解”的问题。什么叫“理解”举个例子一个 800 行的 Python 文件你把它整屏打在右侧你能知道第 1 到第 800 行都是干什么的吗很多时候读代码的“认知单元”不是每一行而是一个个语义块——哪个是入口函数、哪个是辅助函数、哪里标记了 TODO、哪里是数据库连接、哪里是路由注册。所以我对 context-mode 的要求从一开始就非常具体扫描的粒度不是行而是区块。它要自动识别def、class、function、TODO这些“结构锚点”并把文件压缩成一串可以快速扫描的上下文卡片。你说它是“带目录的书”比说它是“预览器”准确得多。2. 功能拆解context-mode 做的是哪三件事2.1 文件树联动预览不切窗口也能看到关键信息第一个能力是文件树联动预览。脚本启动后会递归扫描当前目录构建一棵可交互的文件树左侧是过滤过后的文件列表右侧是对应文件的关键区块。这里的关键不是“扫出来”而是“扫得聪明”。我踩过的最深的一个坑是如果照单全收地遍历整个目录遇到 node_modules 或者 .git 这种目录扫描时间直接失控。所以我在第一版就加了排除目录黑名单from pathlib import Path IGNORE {.git, node_modules, __pycache__, .venv, venv, dist, build} def scan_files(root: str, max_depth: int 4): root Path(root) results [] for path in root.rglob(*): if path.is_dir(): continue rel path.relative_to(root) # 关键任何一级路径里出现黑名单目录整支子树都直接跳过 if any(part in IGNORE for part in rel.parts): continue if len(rel.parts) max_depth: continue results.append(path) return sorted(results, keylambda p: str(p).lower())我特意提一句any(part in IGNORE for part in rel.parts)这个判断特别重要。如果你只检查path.parent.name in IGNORE那么src/node_modules/xxx/yarn.log这种深层路径还是会被扫到。要判断的是相对路径里所有层级而不是最外层目录名。2.2 上下文卡片把文件压成可读的“结构摘要”第二个能力是生成上下文卡片。所谓卡片就是一组带行号、带类型、带摘要的锚点信息。脚本会逐行扫描文件用正则匹配结构关键行然后截取每个锚点附近几行作为摘要。卡片长这样| app.py | 共 74 处关键区块 第 12 行 [import] from fastapi import FastAPI 第 20 行 [def] def create_app(): 第 35 行 [route] app.get(/healthz) 第 41 行 [def] async def health_check(): 第 63 行 [todo] TODO: 这里需要补上连接池的超时策略为什么要“区块锚点”而不是“全文预览”两个原因。第一是成本。上下文是有读取成本的人脑的工作记忆也就装下 4 到 7 个块。一个 800 行文件全文铺开没人能一下子消化但一张只有十来个锚点的卡片一秒就能扫完。第二是可携带性。锚点信息可以被写进 Markdown、JSON直接交给 AI 工具或者同事。全文是不适合作为“提货单”的结构摘要才适合。这个设计在后面的 AI 场景里收益特别明显。2.3 结构化导出让上下文可以被带走第三个能力是导出。context-mode 支持两种输出格式Markdown 和 JSON。Markdown 用于人读比如写项目说明、贴到文档里、当作 commit 备注的素材。JSON 用于机器读比如喂给 API、生成代码索引、或者做 diff 分析。为什么必须是“结构化导出”因为终端的上下文如果只留在终端里价值就少了一半。很多时候你需要的不是“当时看一眼”而是“把这个结构带走”——贴进 AI 对话框、存进项目 wiki、或者在下一次重构的时候对比前后差异。这也是我坚持不用一个普通 alias 脚本敷衍了事的原因只有把输出做成标准格式它才能真正嵌入其他工作流。3. 从 0 实现一个自包含的 context-mode 脚本3.1 环境准备与整体设计先说结论这个脚本不需要任何第三方库Python 3.8 以上的标准库就够。为什么不用rg、fzf或者 Node 生态的现成工具因为我想要的是一个跨平台、零依赖、能塞进任何 CI 或者容器里跑的小工具而不是一个需要反复升级配置的“全家桶”。脚本整体分四步扫描文件树应用排除目录和深度限制提取每个文件的关键区块生成带行号的锚点渲染成终端预览面板或者导出成 Markdown/JSON支持配置文件让不同项目的“关键结构”可以自定制。我把完整脚本拆成几段讲方便你照着搭。先看核心的提取函数import re PATTERNS [ re.compile(r^\s*(def|class|async def)\s\w.*:, 0), re.compile(r^\s*(function|const\s\w\s*\s*\(|export\s(default\s)?(function|class))\b, 0), re.compile(r^(TODO|FIXME|HACK|XXX)\b, re.IGNORECASE), ] def extract_blocks(file_path, max_blocks20): blocks [] with open(file_path, encodingutf-8, errorsreplace) as fh: lines fh.readlines() for idx, line in enumerate(lines, 1): for pattern in PATTERNS: if pattern.match(line): summary .join(line.strip().split()) blocks.append({line: idx, type: block, summary: summary[:120]}) break if len(blocks) max_blocks: break return blocks3.2 第一步文件扫描与过滤规则第一步里有个容易被忽略的细节能不能扫描取决于文件是不是文本文件。我第一版没有做二进制过滤扫到一个app.ico或者.pngreadlines()读出来一团乱码摘要里全是不可见字符。解决办法很简单按扩展名白名单过滤。我默认只扫描.py、.js、.ts、.go、.java、.c、.cpp、.h、.md、.yaml、.yml、.json、.sh、.sql、.txt这些常见文本类型。白名单之外的直接跳过既安全又省时间。扫描策略上我建议限制最大深度而不是限制文件数量。原因很实际大多数项目根目录下散落的配置文件加上三层以内的业务代码已经覆盖了 90% 的上下文需求。max_depth4是我试下来比较舒服的默认值目录特别深的老项目可以临时调大。3.3 第二步关键区块提取关键区块提取是整个工具的核心。正则匹配的结构锚点分三类第一类是代码结构锚点比如 Python 的def、class、async defJavaScript 的function、export function、const xxx ()。第二类是标记锚点比如TODO、FIXME、HACK、XXX。第三类是项目自定义锚点比如app.route、router.get这类装饰器或路由标记。为什么正则要匹配“行首”而不是“任意位置”因为我们要的是定义点而不是调用点。如果一个函数既被定义又被调用把两个位置都标出来只会增加噪声。^\s*(def|class...)开头的^和\s*非常关键它能忽略缩进但不会匹配到函数体内的func()调用。提取后还要做去重和排序。同一行多个标记命中时只保留第一个不同行的锚点按行号自然升序。这些细节直接决定了卡片好不好读。3.4 第三步预览渲染与卡片导出预览面板我用纯文本加 ANSI 颜色实现。右键显示文件列表左侧高亮当前选中文件右侧渲染上下文卡片。渲染逻辑里最容易翻车的是行号对齐不同文件行数位宽不同要统一按右对齐补空格否则面板会来回抖动。导出函数相对简单核心是把区块信息拼成 Markdowndef render_card(file_path, blocks, all_lines, snippet_lines3): lines [f## {file_path}, f关键区块: {len(blocks)} 处, ] for b in blocks: start max(0, b[line] - 1 - snippet_lines) end min(len(all_lines), b[line] - 1 snippet_lines 1) lines.append(f### 第 {b[line]} 行) lines.append(text) lines.extend(all_lines[start:end]) lines.append() lines.append() return \n.join(lines)snippet_lines3的含义是锚点前后各带 3 行上下文。这个参数别小看太小的话看不到逻辑上下文太大又会让卡片臃肿。我试过 1、3、53 是最平衡的默认值。3.5 第四步让配置可调整最后一张牌是配置文件。我用 JSON 做配置支持自定义忽略目录、最大深度、每文件最大区块数以及自定义正则规则。{ ignore_dirs: [.git, node_modules, __pycache__, .venv], max_depth: 4, max_blocks_per_file: 20, patterns: [ {regex: ^\\s*(def|class|async def)\\s\\w.*:, type: code-block}, {regex: ^\\s*(function|const\\s\\w\\s*\\s*\\(), type: code-block}, {regex: ^(TODO|FIXME|HACK|XXX)\\b, type: todo, flag: i} ] }设计配置化而不是把规则写死在代码里是因为不同语言、不同项目的“上下文热点”差异很大。Go 项目可能更关注type和funcJava 项目要把Controller、Service加进来这些都应该通过配置扩展而不是改源码。4. 实测效果、常见问题与避坑清单4.1 实测场景一找回一个月前的脚本我有个目录里放了二十几个自己写的运维脚本一个月前写过一个小工具判断一堆服务器磁盘水位并输出报警。要真去翻每个文件都可能长得像不看里面的代码根本认不出来。用 context-mode 扫一遍之后卡片直接告诉我disk_alert.py第 12 行是def check_disk_usage():第 33 行是TODO: 支持远程执行。我一眼就认出这个文件是要找的。整个过程不到十秒省掉了挨个cat文件的时间。4.2 实测场景二排查线上日志线上日志文件动辄几万行。以前查问题我得先grep ERROR拿到行号再sed -n x,yp把每段上下文拽出来。有了上下文卡片情况完全不同直接扫一输出所有 ERROR 的行号和前后摘要排成一列扫一眼就能判断哪个 ERROR 是同一波异常。这里有个特别有用的技巧把卡片里的“区块摘要”和错误消息做关键字过滤。我后来给工具加了一个--filter参数只保留包含指定关键字比如交易号、模块名的区块日志排查速度快得不是一点半点。4.3 实测场景三给 AI 工具搭提示词最近写代码越来越依赖 AI 工具但发现个问题AI 回答的质量高度取决于你给它的上下文够不够“结构化”。你直接把一个 800 行文件全部粘进去它反而抓不住重点。但如果你先跑一次 context-mode把 Markdown 卡片喂给 AI效果会好得多。比如我对 AI 说“请重构这个文件里的数据库连接逻辑并给出迁移建议”同时附上 context 卡片。AI 不用逐行读代码就能定位到和数据库连接相关的函数区块回答里引用行号也特别准。这个用法是我最近觉得 context-mode 回报率最高的场景。4.4 常见问题速查表运行过程中我整理了这些高频问题症状常见原因解决方案中文注释变成乱码文件编码不是 UTF-8读取时加errorsreplace显示时统一按 UTF-8 解码扫描大目录卡死没设深度或排除目录默认max_depth4把node_modules、.git加进黑名单正则匹配到函数调用而不是定义缺少^\s*行首限定所有结构锚点都从行首开始匹配缩进用\s*兼容卡片里出现二进制乱码扫描到了图片、jar 包等加扩展名白名单非文本文件直接跳过终端颜色输出异常Windows 旧终端不支持 ANSI判断终端能力不支持就退化为纯文本符号链接导致重复扫描项目里有循环链接rglob前用resolve()去重或直接跳过符号链接4.5 避坑清单每个坑背后都有一次真实的“翻车”单独整理出来第一不要用全文作为上下文单元。我第一次实现时把每个锚点附近 10 行作为区间看起来信息量更大但卡片又长又乱。后来强制自己把摘要截断到 120 字符信息密度反而上去了。做上下文工具最重要的能力是“克制”。第二终端输出要判断 isatty。脚本如果接管道输出比如context-mode context.md再往 stdout 里写 ANSI 颜色导出的 Markdown 全是乱码。判断逻辑很简单sys.stdout.isatty()为真才加颜色否则输出纯文本。第三正则规则宁少勿多。配置里正则越多误报越多。比如const在 JS 里常见但你如果加了const开头就标锚点大量赋值语句会被当成结构块。我只保留“函数定义、类定义、路由装饰器、TODO”这四类通用锚点自定义规则按项目再慢慢加。第四文件读取异常要静默处理。遇到权限不足、文件被占用、或者单行特别长的文件直接跳过比抛异常好。工具定位是“辅助浏览”不是“严格编译器”稳定快速永远优先。我在实际使用中最深的体会是context-mode 不是又一个文件预览工具而是一种把文件结构从“隐式”变成“显式”的工作习惯。你不需要记住代码在哪一行也不需要反复翻窗口结构摘要会自动躺在那里等你扫一眼。这种体验一旦用惯就回不去了。后续我还想给它加上两个扩展一是和 fzf 联动在交互式选择文件的同时显示上下文卡片二是针对 git diff 生成“变更结构摘要”这样每次提交之前我都能用 AI 自动从结构层面 review 一遍自己的改动。如果你也整天在终端里被上下文断层折磨建议从最小实现开始自己动手做一个 context-mode它带来的收益会超出你的预期。