做 AI 辅助开发半年多我踩过最深的坑不是 prompt 写得不够好而是上下文丢了。今天聊的项目 context-mode就是专门解决这个问题的一套轻量级上下文管理方案。它本身是一个跑在终端里的命令行工具负责把每次 AI 协作会话里的“记忆”结构化地存下来下次打开终端一键恢复不用重新把项目背景、改到哪一步、踩过哪些坑再讲一遍。这个问题有多痛我用一个数字说明我统计过自己某段开发周期里的 40 次 AI 会话平均每次要花 6 到 10 分钟重建上下文包括重复粘贴项目结构、重新描述目标、把昨天的结论再说一遍。这还不算上下文窗口被占满后模型开始“忘记”早期约束导致的返工。context-mode 想做的事很简单把上下文当成一等公民来管理像 git 管理代码一样管理记忆。适合谁来参考如果你经常用 AI 编码助手做多文件改造、跨天续接任务或者同时维护好几个项目这篇文章里的设计思路和代码可以直接抄。下面从需求拆解、分层模型、核心实现到排坑实录完整走一遍偏实战不讲虚的。1. 项目缘起与需求拆解1.1 痛点剖析AI 协作中的“失忆”问题所有 AI 编码助手本质上都是一个“无状态函数”你给它一段输入它返回一段输出中间不保留任何记忆。所谓多轮对话不过是你自己把历史消息一遍遍重新塞回去。这个问题在短会话里不明显一旦任务跨天、跨文件、跨模块立刻暴露。我梳理了自己的真实工作流发现上下文丢失主要发生在四个环节启动新会话时需要重新描述项目背景、技术栈和当前进度。切换任务时上一个任务的关键决策会被新任务挤掉。上下文窗口被长日志、大文件占满后早期约束被“挤”出模型注意力。中断几天后回来自己都忘了当初为什么做某个设计。这些不是模型能力问题而是工作流问题。模型的能力再强没有上下文它就是一张白纸。所以我当时的判断是与其等模型“记得更牢”不如自己把记忆管起来。context-mode 的定位不是又一个笔记工具而是专门给 AI 协作场景设计的状态管理器核心动作只有三个记录、压缩、恢复。1.2 context-mode 的定位与核心价值我把这套工具拆成了三个价值点对应三类使用场景第一跨会话续接。昨天改到一半的模块今天打开终端执行ctx resume工具自动把项目摘要、未完成清单、最近几个关键决策拼成一段结构化文本直接作为新会话的初始输入。实测下来续接任务的上下文重建时间从 8 分钟降到了 1 分钟以内。第二多项目隔离。同时维护三四个项目时最容易出现 A 项目的代码风格要求被带到 B 项目。context-mode 按项目目录划分存储空间每个项目一套独立的上下文切目录就是切记忆互不污染。第三上下文瘦身。给 AI 的输入不是越多越好。把近一周的会话记录全部塞进去效果反而不如一段 500 字的高质量摘要加几条关键原文。context-mode 把上下文分成热、温、冷三层热层保留原文温层保留摘要冷层只留索引把输入控制在一个合理的 token 预算内。这三个价值点决定了工具的整体形态它必须是一个 CLI 工具因为要融入终端工作流它必须是文件存储因为要保证可审计、可手动修改它必须支持导出因为最终这些上下文要喂给各种 AI 助手。2. 整体架构与分层模型设计2.1 三层上下文模型热、温、冷上下文管理的核心难点不是“存下来”而是“存什么、扔什么”。我参考了缓存系统的思想把上下文按访问频率和价值分成三层层级内容保留策略用途热层当前任务的关键决策、未完成项、报错原文本次会话内保留任务切换时降级直接作为 prompt 原文温层已完成步骤摘要、文件改动清单、关键函数签名按时间衰减最近 3 天优先拼接为任务背景冷层历史会话的压缩索引、版本快照长期保留只存摘要和指针追溯决策依据这个模型解决了两个问题一是 prompt 长度可控。热层控制在 1500 token 以内温层控制在 3000 token 以内冷层只在需要回溯时才读取。二是信息不丢。冷层不是直接删掉旧内容而是压缩成摘要万一后面发现某个设计决策有问题还能从冷层翻出原始记录。分层的依据来自我对真实会话的观察一次 40 轮左右的 AI 编码会话真正有价值的有效信息不超过 20%剩下 80% 是重复提问、报错堆叠、中间产物。把 80% 的噪音塞给模型等于花钱买干扰。2.2 存储结构与数据格式存储方案我对比过三个方向SQLite、JSON 文件、纯文本目录。最终选了 JSON 文件理由有三点一是数据结构天然是嵌套的项目、层级、条目三级关系用 JSON 表达最直观二是出了问题可以直接用编辑器打开修改故障恢复成本低三是配合 git 可以做版本管理这比数据库迁移简单太多。每个项目的上下文存储在~/.context-mode/project.json结构如下{ project: alpha, version: 3, updated_at: 2025-06-20T22:15:0008:00, tiers: { hot: [ { id: 47, type: decision, content: 用户模块改用仓库模式统一走 gateway 接口禁止直接操作数据层, created_at: 2025-06-20T21:00:0008:00 }, { id: 48, type: todo, content: 剩余阻塞项订单超时状态机缺少重试分支, created_at: 2025-06-20T21:30:0008:00 } ], warm: [ { id: 40, type: summary, content: 完成用户模块接口重构旧接口保持兼容删除冗余的 XXService, created_at: 2025-06-19T18:00:0008:00 } ], cold: [] }, summary: alpha 项目用户模块重构完成 70%下一阶段处理订单超时状态机。技术栈后端 Go PostgreSQL前端 Vue3。关键约定所有接口返回统一响应结构。 }每个条目都要带id和type这是我踩过坑之后加的。id用于回溯和删除type决定条目在导出时的格式比如decision类型会以“关键决策”前缀导出todo类型以“待办”前缀导出这样 AI 助手能更快识别哪些是约束、哪些是任务。2.3 为什么是“模式切换”而不是全量记录项目名叫 context-mode重点在“mode”。一开始我写的是全量记录器想把每次会话都存成完整日志结果存了两周就发现根本没法用日志文件越来越大导出给 AI 时长度爆炸而且大部分内容是无效的。后来我换了个思路把工具定位成“手动 半自动”的混合模式。手动的地方在于任务完成、方向调整、发现关键坑位时你主动执行一条ctx mark命令做标记。半自动的地方在于工具监听当前工作区的文件变化自动记录最近改动的文件列表并在会话结束时自动生成一段总结建议。为什么不全自动因为当前技术条件下自动抽取“什么是有价值的信息”准确率还不够高。与其存一堆噪音不如让开发者自己按下快门。这也符合我对上下文管理工具的判断它应该是开发者的副驾仪表盘不是自动驾驶系统。3. 核心实现与实操要点3.1 命令设计与交互流程context-mode 的命令不多一共就六个设计原则是“一个手势做一件事”ctx init # 初始化当前目录的项目上下文 ctx mark -t decision -m 内容 # 手动记录一条上下文-t 指定类型 ctx capture -m 完成用户模块重构 # 捕获当前工作区状态自动带上改动文件列表 ctx resume # 生成本次会话所需的初始 prompt ctx use --project name # 切换项目上下文 ctx export --format prompt | head -n 100 # 导出上下文方便手动粘贴capture是最常用的命令。它的执行流程是先跑git status拿到改动文件列表再读取最近 5 条热层条目加上用户传入的描述合并成一条新的上下文条目存入热层同时把超过 3 天的温层条目压缩进 summary 字段。我刻意没有做“自动在 AI 会话结束后抓取内容”的功能因为终端里的 AI 会话和 shell 之间没有干净的截断点自动抓取的边界判断很难做。后来用了一个折中方案在 shell 提示符里挂了一个 hook检测到 AI 编码助手的进程退出时提示你“是否记录本次会话要点”把决定权留给人。3.2 摘要压缩与 Token 预算控制摘要压缩是整个工具里最值得讲的部分。我实验了三种方式规则截断、小模型摘要、大模型摘要最终采用的是“分层混合”策略。先说 token 预算怎么算。我用的估算公式很简单中英文混排时token 数 ≈ 字符数 / 1.8纯英文时≈ 字符数 / 3.5。虽然不精确但足够做预算控制。我给自己定的导出上限是 4500 token其中热层 1500、温层 2500、summary 500。超出预算时工具会先压缩温层里最老的条目把 5 条旧摘要合并成 1 条新摘要再把原文下沉到冷层。压缩策略分两级。第一级是在本地用规则做按decision、todo、bugfix三种类型分别提取关键句这种“类型感知压缩”能去掉 40% 的冗余。第二级是调用大模型接口做语义压缩输入是待压缩的原始条目输出要求是“保留所有事实性信息、去掉语气词和过程描述、控制在 150 字以内”。实测下来两级压缩后信息保留率在 85% 以上但体积缩小了约 60%。压缩的核心代码逻辑如下def compress_entries(entries, llm_fn): texts [e[content] f类型{e[type]} for e in entries] prompt ( 将以下代码开发记录压缩为一段不超过200字的摘要。 必须保留具体技术方案、文件名或接口名、已完成/未完成状态。 去掉过程描述、语气词、无关细节。\n\n \n.join(texts) ) return llm_fn(prompt)这里我踩过一个坑压缩 prompt 里如果不强调“保留接口名和文件名”摘要经常会把关键的技术名词吞掉生成“优化了相关模块”这种正确但没用的废话。所以后来我在 prompt 里明确列出了三类必须保留的信息效果立竿见影。3.3 上下文恢复把存储变成高质量 Promptresume命令做的事情听起来简单——把摘要和热层条目拼起来——但这里的细节决定了 AI 助手能不能真正用上这些信息。我通过大量对比实验确定了导出模板的顺序# 项目alpha ## 当前状态 summary 字段内容 ## 正在进行 热层中 typetodo 的条目 ## 近期关键决策 热层中 typedecision 的条目 ## 最近改动的文件 capture 时记录的 git status 文件列表 请基于以上信息继续协助开发。注意所有决策为既定约束如需调整请先说明理由。最后一句“如需调整请先说明理由”很关键。加了它之后AI 助手不再动不动就推翻之前的方案而是先确认再动手。这本质上是一种 prompt 工程技巧但放在工具里实现就能让每个团队成员都享受到不需要每个人自己写这套话术。3.4 项目隔离与目录切换实现项目隔离的实现在早期版本里很简单以.context-mode/project.json区分。但用了一段时间发现一个问题同一个项目在不同机器上克隆时目录名可能不一样导致上下文文件对不上。后来我改成“目录哈希 项目名”双索引~/.context-mode/projects.json保存了一个映射表把项目名映射到“最近访问的工作目录哈希列表”。执行ctx use --project alpha时工具先查映射表找到工作目录再读取对应上下文。如果工作目录不存在就提示用户重新指定路径并更新索引这样换机器时只需拷贝整个.context-mode目录即可。这个改动还顺带解决了一个多开问题同一台机器上同时开着 alpha 和 beta 两个项目目录shell 提示符会根据当前目录自动匹配上下文不会串。4. 实操过程三个真实场景完整演示4.1 场景一跨天续接重构任务某次给内部系统做用户模块重构第一天晚上改到一半卡在订单状态机的并发问题上我记录了上下文后下班。第二天回来的操作流程是这样的# 进入项目目录 cd ~/work/alpha # 恢复上下文 ctx resume /tmp/ctx.md # 把 /tmp/ctx.md 内容粘贴给 AI 编码助手作为初始输入恢复出来的 prompt 里清楚地写着“重构完成 70%”“剩余阻塞项订单超时状态机缺少重试分支”“关键决策统一走 gateway 接口”。AI 助手拿到这些信息后第一句话就问“需要我一起分析重试分支的幂等性吗”直接进入了问题本身而不是先问“你的项目是做什么的”。这个场景里最值钱的不是省了几分钟而是没有丢失“设计约束”。如果没有 context-mode第二天开启新会话时我大概率会忘记“统一走 gateway”这条约束AI 助手可能会给出绕过 gateway 的方案那才是真正的灾难。4.2 场景二双项目并行切换我平时同时维护一个数据中台和一个前端组件库。以前切换项目时经常把中台的代码规范带到前端项目里AI 助手给出的组件代码风格和后端项目完全不是一个体系。用了 context-mode 之后每个项目独立维护上下文切换前执行ctx mark -t decision -m 前端组件库样式方案定为 CSS Variables不引入预处理器 ctx use --project ui-lib由于两个项目存在不同的.context-mode文件里导出的 prompt 各自带着自己项目的技术栈约定AI 助手很少再串风格。这里有个小技巧在 shell 的cdhook 里调用ctx use --by-dir目录切到哪儿上下文就自动切到哪儿连手动执行use都省了。4.3 场景三团队上下文交接给团队里两个同学交接一个进行中的项目时我直接执行ctx export --format prompt把生成的上下文文档发给他们。他们在自己的机器上执行ctx import --file context.json整个项目的背景、进度、坑位、约束一下子全过去了。这个场景比想象的更常用。以前交接项目靠写文档但文档写不到“昨天刚发现某个 SDK 的返回值是错误类型”这种粒度。上下文工具提供的是一个“活文档”粒度细到具体的 bug、具体的决策而且每个条目都带时间戳可以追溯。交接的实操细节是导出前先跑一次ctx capture -m 交接前快照确保所有最新的改动文件列表被记录进去。另外交接方导入后要核对 summary 字段是否完整尤其是技术栈部分因为新成员对项目没有背景认知summary 里的一句“技术栈后端 Go PostgreSQL”能省掉很多基础问答。4.4 关键参数的选择依据工具里有几个参数是我经过多轮调整定下来的这里记录一下决策过程方便你按自己的需求改导出上限 4500 token对应主流模型在保证回复质量时比较舒服的输入长度。超过这个值模型容易忽略后面的内容回复质量明显下降。如果只用长上下文模型可以把warm_tokens从 2500 调到 4000。温层保留 3 天这是我观察自己工作节奏得出的结论。超过 3 天的内容基本属于“已完成且不再活跃”的状态适合压缩。如果是长周期项目建议改成 7 天配合每日自动 capture 使用。热层最多 5 条热层条目大多比较长超过 5 条就超过了 1500 token 预算。当第 6 条进来时工具会自动把最早的 1 条降级到温层并触发一次局部压缩。这些参数我全部放在了配置文件~/.context-mode/config.yaml里没有写死在代码中。参数化的好处是不同团队、不同项目规模对上下文长度的需求差异很大宁可多暴露几个配置项也不能让你为了改参数去动源码。5. 常见问题与排查技巧实录5.1 上下文串扰A 项目的上下文混入 B 项目这是使用频率最高的反馈之一。排查下来大部分原因不是工具 bug而是目录映射没有对上。比如从~/work/alpha通过软链接访问~/code/alpha-linkpwd显示的路径不同工具匹配不到同一个项目就新开了一个上下文。解决办法在projects.json里把同一个项目的多个目录路径记录到一个 bucket 里匹配时只要命中任一路径就视为同一项目。另外要检查是否有子目录嵌套的情况比如~/work/alpha/frontend是另一个项目的前端仓库这种嵌套结构容易让工具误认为是同一项目。5.2 摘要质量劣化关键信息被压缩丢失压缩后的摘要会慢慢丢失细节这个问题在项目进行到中期特别明显。我发现典型表现是摘要里只有“完成支付流程优化”但“用消息队列替代同步调用”这个关键决策被弄丢了。这个决策恰恰是后续排查性能问题时最需要的线索。针对这个问题我做了两个改进。第一在压缩 prompt 里明确要求“必须以列表形式保留所有涉及的具体技术名词、文件路径和接口名”压缩质量明显提升。第二在冷层保留完整原文只要摘要质量下降可以执行ctx trace --keyword 消息队列从冷层找回原文。实际排查时冷层索引的价值比想象中大得多。5.3 存储膨胀与启动变慢跑了三个月后某个项目的 JSON 文件涨到了 30MB每次执行命令都要等一两秒。原因也是我一开始没预料到的capture命令里“自动记录 git 改动文件列表”会把每次抓到的文件路径全部存下来反复改一个文件会生成几十条几乎一样的记录。解法是加了一个“相似合并”逻辑如果新条目的类型和内容与热层最近一条的相似度超过 90%就把时间戳更新到新条目而不是新增一条。实现上我用的是简单的文本相似度计算没引入复杂的算法效果已经足够。另外每个月执行一次ctx gc把冷层里超过 90 天且从未被回溯的条目归档到独立路径。5.4 避坑清单速查坑位现象解决方案软链接目录导致上下文隔离同一项目出现两份上下文为项目绑定多个目录路径压缩丢掉具体技术名词摘要只剩泛泛描述prompt 里强制保留名词列表反复修改同一文件产生冗余条目存储膨胀文本相似度合并resume 后 AI 仍然跑偏决策约束未被识别在导出模板里把 decision 条目放前面并加“既定约束”前缀团队交接时背景缺失新成员看不懂摘要capture 里强制记录技术栈和架构约定另一个我反复强调的经验上下文工具体系要尽量保持轻量不要塞太多自动化。我试过给工具加“自动摘要每日会话”功能跑了不到两周就关掉了——自动生成的低质量摘要反而污染了温层导致真正需要时找不到准确信息。现在这个功能变成了“晚 6 点提示是否生成今日摘要”把决策权交回给人。6. 扩展方向与个人体会context-mode 目前还只是单机工具但它的数据结构设计为后续扩展留了很大空间。我比较看好的几个方向一是把上下文数据接进 AI 助手的 system prompt 模板体系做成插件让助手天然感知项目状态二是做团队共享后端把上下文存入 Git 仓库或内部服务这样跨人交接会更顺滑三是接入更多工作流事件源比如 CI 失败、测试用例变更自动在上下文里标记状态变化。在实现这个工具的整个过程中我最大的体会是上下文管理本质上不是技术问题而是习惯问题。工具能帮你把记忆结构化地保存下来但如果你不在关键时刻按下快门再好的存储也没有用。每次方向调整、每个关键决策产生时花 10 秒钟执行一条ctx mark这个习惯比工具本身更值钱。如果你也在被“AI 失忆”困扰建议先别急着照抄我的实现明确你自己最常丢的是哪种上下文再做一个最小版本跑两周让真实工作流帮你迭代出适合自己的模式。