最近同时推进三个开发任务的时候我遇到了一个特别磨人的问题切到后端写接口再切回前端调样式最后又回去改数据库脚本每次切换完脑子和AI工具里的“上下文”全断了。要么得重新贴一遍项目背景要么翻聊天记录找半天之前说到了哪一步。一来二去我实在受不了决定做一个属于自己的context-mode工具——用命令行把不同任务的上下文独立保存、随时切换、按需恢复。这名字听起来抽象其实本质很简单把隐式的工作记忆变成显式的、可存取、可切换的状态。这篇文章就完整复盘一下我是怎么设计、实现并在真实工作流里用起来的包括踩过的坑和最终的取舍。如果你也是那种需要同时维护多个任务、又经常被“上下文丢失”折磨的人这篇文章应该能给你一套可直接复用的思路和代码骨架。我不会只贴结论会把每个选择背后的原因、实现时的关键细节、跑了一周后暴露的问题统统讲清楚。1. 先想清楚context-mode到底要管什么状态写代码之前最容易犯的错误是把“上下文”当成一个黑盒觉得存个字符串就完事了。实际用下来上下文是分粒度、分生命周期的不先想清楚这一点工具做出来一定难用。1.1 上下文的三种粒度会话、任务与全局刚开始我脑子里只有“上下文文件”这个概念但真的用起来之后我把它拆成了三层会话级上下文一次连续交互内的临时信息。比如你正在调试一个报错刚定位到某个函数这些信息过了今天可能就没用了。它的特点是短命、变化快、不需要长期保存。任务级上下文一个功能模块从设计到落地的所有背景。比如“订单列表接口改写分页”这个任务涉及字段说明、关联表结构、历史决策原因这类内容生命周期是几小时到几天。全局级上下文跨任务通用的信息。比如团队代码规范、项目目录结构、常用命令。它不经常变但每个任务都可能用到。context-mode工具最该管好的就是中间的“任务级上下文”。它是切换成本最高的部分——会话级可以通过滚动记录找回全局级本来就是一直放着的唯独任务级你不主动记录切走就再也拼不回来。1.2 隔离与共享什么该进上下文什么不该进想清楚“什么不该放”比“什么该放”更重要。我把不该进上下文的清单列出来了临时性报错堆栈、一次性的调试打印、与任务无关的聊天废话。这些内容放进上下文只会污染后续的读取还会浪费模型注意力。真正值得进任务上下文的是这几类任务的目标和非目标避免做偏与任务相关的技术约束框架版本、接口协议、运行环境已经做出的关键决策和理由避免重蹈覆辙当前进度状态做到哪一步、下一步是什么采用的术语/命名约定保证前后一致打个比方任务上下文就像工地上的施工铭牌上面写清楚承包商、工期、技术要点。它不需要记录每一块砖怎么搬但要保证换一个包工头新来的人也能知道这栋楼按什么标准盖。1.3 为什么不用现成会话管理器而自己写市面上其实有不少会话管理和备忘录工具我最开始也试过几种。但它们大多有两个问题一是绑定在某个特定编辑器或AI产品里换个终端就抓瞎二是太重我不需要一个会议纪要系统我只需要一个“保存现场”的开关。context-mode的价值不在于功能多而在于打通一个统一的切换入口。它最终要做成终端里的一等公民配合shell alias、git分支、AI工具提示词一起工作。自己写一个小工具30分钟能搞定的骨架却能刚好贴合自己的使用习惯比被通用工具掰着走舒服得多。2. 从零搭一个可用的context-mode命令行工具设计定下来了实现就顺理成章。我选Python标准库做这个工具零第三方依赖任何机器上都能跑。整体思路是用文件系统模拟上下文空间每个上下文是一个独立目录目录里放结构化的元数据。2.1 存储方案选型目录即上下文存储这件事我没用数据库也没用单一的JSON大文件而是采用了最朴素的方案——一个上下文一个目录。用户主目录下建一个~/.context-mode/contexts/每个任务上下文对应一个子目录~/.context-mode/ ├── contexts/ │ ├── 订单接口分页/ │ │ ├── meta.json │ │ ├── progress.md │ │ └── notes.md │ ├── 前端弹窗重构/ │ │ ├── meta.json │ │ └── progress.md │ └── database-backup/ │ ├── meta.json │ └── notes.md └── current.json为什么用目录而不是数据库因为人类对文件系统有一种天然的直觉目录就是命名空间文件名就是索引。而且每个上下文的内容组成可能不一样有的需要存进度有的需要存接口样例有的需要存SQL脚本。目录结构天然支持这种异构内容数据库还要做schema设计。current.json是全局指针记录当前激活的是哪个上下文。这就像终端里的“当前工作目录”——状态只有一行却决定了所有相对行为。2.2 核心数据结构与命令行协议每个上下文目录里必须有至少一个meta.json我用它保存描述性信息和切换时需要注入的“上下文块”{ name: 订单接口分页, created_at: 2025-05-14T10:30:00, updated_at: 2025-05-15T14:22:00, context_block: 项目商城后端。订单列表接口需要改造为游标分页。\n技术栈Python 3.11 FastAPI数据库用PostgreSQL 15。\n约束不得破坏现有旧版分页兼容需保留page/page_size参数。\n进度游标分页核心逻辑已完成正在调整返回格式。\n下一步补充limit/offset兼容测试。 }context_block这个字段是整个工具的精华。它是一段精炼的、可直接复制给AI工具或同事的文字。为什么单独抽出来因为在实际使用中我经常需要“把当前上下文注入到某个对话里”。如果每次都得临时从文件里挑重点效率就很低。提前维护好一段干净的上下文块切换成本就变成了复制粘贴的零成本。命令行协议我设计了四个核心指令cm new name # 创建新上下文并切换过去 cm use name # 切换到已有上下文 cm add text # 向当前上下文追加一条记录 cm show # 显示当前上下文块和摘要信息实现这些指令的核心是状态机所有操作都基于“当前上下文”进行而当前上下文只有从current.json读出来才知道。切换等于更新这个指针同时刷新上下文的updated_at时间。2.3 关键实现切换、注入与清除切换指令的Python实现非常简单但需要注意几个点import json from pathlib import Path BASE Path.home() / .context-mode CONTEXTS BASE / contexts CURRENT BASE / current.json def load_current(): if CURRENT.exists(): data json.loads(CURRENT.read_text()) return data.get(name) return None def switch_to(name): ctx_dir CONTEXTS / name if not ctx_dir.exists(): raise FileNotFoundError(fcontext {name} not found) CURRENT.write_text(json.dumps({name: name, switched_at: now_iso()})) def add_note(text): current load_current() ctx_dir CONTEXTS / current notes_file ctx_dir / notes.md with notes_file.open(a, encodingutf-8) as f: f.write(f- {now_iso()} {text}\n)注意switch_to里有个容易踩的坑切换时不能简单覆盖current.json因为如果用户当前上下文里还有没保存的临时想法切换后就丢了。我的处理是切换前自动把current.json里记录的“上一个上下文”的updated_at刷一下并且向用户输出提示“你正在离开XX上下文”强迫自己确认没有遗漏。这一步在自动化脚本里很容易被忽视却是信息完整性的最后一道保险。清除逻辑更简单cm rm删除整个目录就行。但我在删除前会生成一个tar备份扔到~/.context-mode/trash/等到第二次执行同样的删除时才真正清掉。这样误删后还能救回来成本只是几行代码收益却可能是几小时的工作量。3. 接入实际工作流让上下文真正发挥作用工具写完只完成了30%剩下70%是把它嵌入到日常工作流里。如果只是偶尔想起来用一下很快就会被遗忘。我花了两个星期调整触发节奏才让它变成肌肉记忆。3.1 手动切换的时机选择什么时机执行cm use和cm add我总结出了一套规则切换时机从A任务的工作状态退出、准备开始B任务之前。哪怕只是去回一条消息只要确定接下来至少有15分钟要投入B任务就值得切一下。因为大脑的上下文切换成本远高于命令行的上下文切换成本。记录时机任何一个值得被记住的结论出现的瞬间。比如定位到一个bug的根因、确定了一个接口参数命名、和一个同事达成了一致。这类内容往往在对话结束后会被吞掉当场记下来才靠谱。实际用下来最有效的方式不是强迫自己“每次都要记录”而是遇到转折点才记录。转折点包括任务范围变了、有了新决策、完成了一个里程碑。把记录的触发条件钉在“转折点”上频率大概是一小时一两条完全无负担。3.2 与编辑器/终端多开配合的实践一个很有意思的发现是多开终端窗口时context-mode不只是“记录工具”还可以当成“同步工具”。我在两个终端里分别跑着不同任务的服务和日志以前换个任务要回忆“我到底在哪个终端部署过什么”。现在我把每个终端的标题和当前上下文绑定# .bashrc / .zshrc 里的提示符改造 PROMPT_COMMANDexport PS1[$(cm current 2/dev/null)] $PS1这样每个终端窗口的提示符都会显示当前所属上下文从哪个窗口该做什么一眼就知道。后来我甚至给不同上下文绑定了不同的目录映射习惯——写前端代码时自动切到前端上下文这个工具反过来成了“任务定锚”。3.3 把context-mode嵌进AI对话提示词这是整个工具使用率飙升的关键一步。我给主流的AI对话工具做了一个固定的提示词模板放在全局上下文里你在帮忙处理{context.name}任务。项目背景、技术栈、约束和进度说明如下 {context.block} 请基于以上上下文回答问题。如果问题超出该上下文范围请先提醒我是否需要切换上下文。使用时只需要执行cm show把输出的内容粘贴到对话窗口即可。整个过程不到10秒。别小看这10秒它解决了一个隐藏痛点AI对话服务重启、换设备、忘记录制上下文的时候过去的所有铺垫全部白费。现在只要cm show一场新对话就能站在旧对话的肩上开场。有条件的同学可以把这一步做成自动化写一个小的vim/编辑器插件按一个键自动读取当前上下文块并插入到输入框。我是直接用终端复制粘贴解决的大多数人不需要走到那一步。4. 运行一段时间后的调整与坑任何工具不经历真实场景的冲刷都不知道自己缺什么。context-mode跑了两周暴露了四个典型的坑每一个我都花了不小代价才踩明白。4.1 上下文过期问题与ttl机制第一个坑来得猝不及防有个任务停了整整一周再切回去的时候context_block里的“进度”已经严重过时领域内的代码早被别人改了好几轮。我照着旧上下文给AI发提示AI给出的建议全建立在一个已经不存在的代码基础上。解决方案是给每个上下文加一个“保鲜期”。在meta.json里加last_active_at字段切换时检查是否超过72小时。如果过期cm show会输出醒目的提示[注意] 该上下文已超过72小时未更新。 建议执行以下操作 1. 执行 cm add 并补充最新的进度/决策 2. 运行 cm refresh 基于当前代码库状态修正上下文这个机制的本质是强制让上下文与真实世界对齐。上下文脱离了实际代码比没有上下文更危险——它会给你一种“我知道发生了什么”的错觉但实际上是什么都不知道。4.2 token预算上下文太长怎么办第二个坑是贪多嚼不烂。刚开始写context_block的时候我恨不得把所有技术细节全部塞进去结果一段写给AI的上下文超过2000字模型的注意力被摊薄关键约束反而被忽略。后来我把context_block分成两层核心层约500字包含不可妥协的目标和约束和扩展层额外细节按需追加。cm show默认只输出核心层需要扩展时执行cm show --full。核心层的写作原则是如果只允许保留五句话这五句话分别要说什么实际调优后我的典型核心层只有四句话任务要交付什么当前依赖哪套技术栈最不能破坏的旧行为是什么现在卡在哪一步这四句话喂给AI效果远好于一大段事无巨细的背景描述。做工具的时候不要只考虑“怎么存”更要想“怎么读”。4.3 并发写同一个上下文时的锁与冲突有一次我开了两个终端同时往同一个上下文里追加笔记。本来以为文件写入是小事结果notes.md被写坏了——两个进程同时open同一个文件后面的写入覆盖了前面的一部分。这种事概率不高但一旦发生丢失的就是当时认为不重要但事后很关键的调试线索。补丁很简单在add_note里加个文件锁import fcntl with notes_file.open(a, encodingutf-8) as f: fcntl.flock(f, fcntl.LOCK_EX) f.write(f- {now_iso()} {text}\n) fcntl.flock(f, fcntl.LOCK_UN)顺便说一句meta.json的更新也要用“先写临时文件再原子重命名”的方式避免写一半崩溃。这些基础但必要的卫护代码是工具在真实环境里跑得住的前提。4.4 版本化上下文带来的意外收获第四个坑不是负面问题而是意外惊喜。我在手动覆盖context_block时为了对比前后差异顺手给每个上下文目录加了个版本化存储每次修改都保留一份带时间戳的历史快照。原本只是想方便回退结果发现这变成了一个“决策流水账”功能。有一次团队问“为什么当时决定用游标分页而不用默认偏移分页”我直接翻旧快照找到了当时记录的原因和参考链接。如果没有版本化这类决策依据就永远消失了。5. 复盘context-mode真正解决与没有解决的问题跑了几周之后我对context-mode的边界认识越来越清楚。它不是一个万能的生产力工具但有它和没有它的差距已经体现在每天的切换效率上。context-mode真正解决的是外部化工作记忆的问题。人类大脑的短期记忆容量本身就极为有限跨任务切换时又需要主动丢弃旧信息来给新信息腾地方。把任务相关信息放在工具里等于给大脑加了一块外接硬盘——你不需要记住全部细节只需要记住“我的上下文存在哪里”。它没有解决的问题同样明确它不替你整理信息。原始的、混乱的、过时的信息放进去吐出来的依然是原始的、混乱的、过时的信息。工具的价值上限取决于维护者对“值得记录的转折点”的判断力。这也是我为什么建议在context_block里保持核心层的精炼度——让外界存储参与思考而不是单纯执行备份。如果你也打算做一个类似的工具我的经验是别一上来就上重型框架。先用文件系统加一个一两百行的Python脚本跑起来真实用两周再根据痛点迭代。真正贴身的工具不是设计出来的是用出来的。
