context-mode实战：从CLI工具到LLM会话的上下文管理设计

我记得很清楚，第一次意识到上下文重要性的场景，是在写一个小型终端助手的时候。这个工具需要用户连续完成几步操作：先选择数据源，再指定处理方式，最后输出报告。但每次命令跑完，它就什么都不记得了，用户下一步如果漏掉某个参数，只能重新敲一遍。那一刻我意识到，没有上下文的工具，就像一个每次都重新认识你的柜台服务员，你不得不一遍遍重复自己的需求。

"context-mode"就是为解决这类问题设计的。简单来说，它是一种让软件在多次操作或多次会话之间，自动保存、读取并利用历史上下文信息的运行模式。它解决的问题很具体：减少重复输入、保持操作连续性、让程序能根据"之前发生了什么"做出更合理的判断。如果你是做CLI工具、自动化脚本、编辑器插件，或者自己在折腾AI助手相关的东西，这篇文章值得看完——我会从设计思路讲到代码实现，再分享实测中踩过的三个坑。

1. context-mode是什么：先从一次尴尬的"失忆"说起

1.1 没有上下文的世界：你每天都在重复填表

先想想你平时用的命令行工具，尤其是那些要传一堆参数的工具。比如一个数据迁移脚本，你可能要写成这样：

python migrate.py --source /data/old --target /data/new --format csv --encoding utf-8

如果跑到一半挂了，或者你想换个格式再跑一次，你大概率会把这条命令翻出来改一改，或者按一下上箭头重新编辑。这在单次操作里问题不大，但如果是连续几十条命令呢？比如你要依次做预处理、清洗、校验、导入、导出，每一步都要重复指定路径、编码、分隔符，时间一长，忘参数几乎是必然的。

没有上下文的世界，本质上是把本该由程序记住的信息，全压在了用户身上。这就像你每天去同一个快递点取件，每次都报一遍姓名、电话、地址。快递点的工作人员不是不想记住你，而是他的系统没这个能力。context-mode要做的，就是给程序加上这个"记忆能力"。

1.2 context-mode的定位：让工具记住"刚才发生了什么"

那么context-mode具体指什么？我倾向于给它一个精确的定义：一种运行模式，在这种模式下，程序会将用户当前的操作、输入参数、选中项、临时状态等信息记录下来，并在后续操作中自动读取和套用，从而形成连续的操作体验。

它和普通的日志、缓存有本质区别。日志是写给开发者调试用的，缓存是为了加速重复读取，而context-mode关心的是"语义上的连续性"。举个例子，你在一个文件管理器里选中了一个文件，然后准备执行压缩操作——压缩工具预先把"当前选中了哪个文件"这个信息记下来，这就是上下文。再比如AI聊天助手，它能记得你五分钟前问过什么，这个"记得"就是上下文模式在起作用。

我见过的context-mode实现有很多种形态：

• 基于会话：服务器端为每个连接维护独立上下文，比如SSH会话。
• 基于项目目录：进入某个项目目录后，自动加载该项目相关的偏好设置。
• 基于全局：用户级别的默认配置，任何地方都能访问。
• 基于时间窗口：只记录最近N分钟或N条操作，形成滚动上下文。

这里面的核心难点不是"记录数据"，而是"决定哪些数据值得记录、什么时候该遗忘、上下文冲突时怎么处理"。

1.3 什么场景真正需要它：三个最典型的应用场景

我在实际项目里总结出三类最需要context-mode的场景，你可以对照自己的需求来判断。

第一类是多步骤CLI工具。我之前写过一个批量图片处理工具，包含导入、去重、压缩、重命名、导出五个步骤。如果每一步都要求用户重新输入输入目录、输出目录、质量参数，用起来会非常痛苦。加上context-mode之后，用户只需要在第一次运行时提供完整参数，后续跑任何单步操作都会自动带上，省事很多。

第二类是IDE和编辑器插件。比如你正在编辑一个Python文件，然后按下快捷键跳到一个工具函数定义处，改完之后返回原来的位置——编辑器记住了"你刚才在哪里"。这种上下文记录已经非常普遍了，我们在做插件开发时，也常常需要记录光标位置、当前文件路径、最近打开的文件列表，这就是一种典型的window-level context。

第三类是AI助手的连续对话。当前所有主流AI对话产品都在做上下文管理，因为把整段历史全部塞给模型既浪费tokens，又会超出模型的上下文窗口。实际工程中，我们往往需要保留最近几轮对话，而对更久之前的内容做摘要或裁剪。这个"保留多少、裁剪多少"的策略，本质上是context-mode的策略选择。

除此之外，运维自动化、构建系统、数据管道调度等领域也大量依赖上下文。判断一个系统适不适合引入context-mode，我有个简单的经验：如果你发现使用者在反复输入或反复选择相同的信息，并且这些信息跟"上一次操作"强相关，那这个系统就值得改造。

2. 设计一个合理的上下文模型：数据结构和生命周期

2.1 上下文粒度：全局、会话、项目三层的取舍

在动手写代码之前，必须先想清楚上下文数据要分成几层。如果不分层，所有数据混在一起，很快就会出现"张三的项目配置被李四带走了"这种问题。

我在context-mode项目里设计了三个层级，非常够用：

这套设计解决了两个关键问题。一个是隔离性：不同项目的上下文不会互相污染，即使是同一个工具，在项目A和项目B下会自动加载各自的设置。另一个是时效性：session里的状态本来就该用完即焚，比如某次登录产生的临时凭证，如果放到了global里，那就是给自己埋雷。

有人可能会问，为什么不做成数据库表用外键关联？我的答案是：对于大部分工具型项目，三层结构用嵌套字典就够了。数据库适合海量数据检索，而context数据通常单用户、低并发、量也不大，用树状结构反而更直观，调试时候一眼就能看到当前上下文里有什么。

2.2 持久化选型：为什么用JSON加内存两级缓存

确定层级结构后，接下来要考虑数据存哪。我先说结论：我采用了"内存字典做热存储 + JSON文件做冷持久化"的组合，而不是直接上SQLite。

内存字典的好处是快，读写都在纳秒级，适合高频访问。JSON文件的好处是方便调试——你可以直接用vim或cat打开来看，如果用了SQLite，还得装个客户端才能查。对于context-mode这种偏工具性质的组件，易调试比查询性能重要得多。

具体做法是：

• 启动时，把JSON文件加载进内存，形成一个三层嵌套字典。
• 每次set操作，先更新内存，再决定是否写盘。
• 写盘不能每次set都做，否则高频操作时IO会成为瓶颈。我的做法是做一个"脏标记"，在程序退出、或者每隔一段时间批量落盘。

下面是我最初的存储结构设计示意：

{ "global": { "default_editor": "vim" }, "session": { "login_time": 1700000000 }, "project": { "/home/user/myapp": { "build_command": "make", "last_output": "Build OK" } } }

这里把project的键设计成了项目绝对路径，天然实现了项目级隔离。后来又发现一个细节值得注意：路径里可能含有特殊字符，所以我在加载时对路径做了规范化处理（去掉末尾斜杠、解析符号链接），避免同一个项目因为路径写法不同出现两个上下文副本。

2.3 上下文有效期：过期策略与自动清理机制

上下文不是无限堆积的，否则用户会发现：三个月前的一次操作记录，还影响了今天的执行结果，这反而变成了一种困扰。

我设计的过期策略是给每条上下文数据附加元信息：

{ "value": "data", "created_at": 1700000000, "updated_at": 1700000000, "ttl": 3600 }

• created_at和updated_at分别记录创建时间和最后更新时间。
• ttl是存活时间（秒），例如3600表示1小时后过期。
• 读取时，如果now - updated_at > ttl，就认为这条数据已过期，不返回给调用方。

这里我要强调一个容易犯的错：很多人把TTL只写在层级上，比如"整个session层1小时过期"，这会引发连锁问题——一个长任务可能只需要某些字段长期有效，但整个层级过期会把它一并杀掉。正确的做法是字段级TTL，不同字段可以单独指定有效期。比如"当前登录用户"可以永久，"上次选中的文件"只需要5分钟。

清理机制我用的是"惰性删除 + 定期扫描"双保险。惰性删除是在get时发现过期就顺便删掉；定期扫描是每隔10分钟把过期数据批量清掉，避免脏数据堆积占内存。这样既保证实时性，又不至于每次操作都触发大量删除。

3. 动手实现一个可用的context-mode模块（Python版）

3.1 核心类设计：ContextManager的接口定义

设计完成后，实现阶段需要用代码把想法固定下来。这一节我用Python来写一个可直接运行的context-mode模块，语言无关性很好，你换成Go、Node.js也是一样的思路。

先定义核心类的接口。我习惯先写注释再写实现，因为这样能逼自己把接口想清楚：

import json import os import threading import time from pathlib import Path class ContextManager: """Manage context data at global/session/project levels with TTL support.""" def __init__(self, storage_path): self.storage_path = Path(storage_path) self._lock = threading.Lock() self._context = {"global": {}, "session": {}, "project": {}} self._load() def _load(self): if self.storage_path.exists(): with open(self.storage_path, "r", encoding="utf-8") as f: loaded = json.load(f) self._context.update(loaded) def set(self, level, key, value, ttl=None): """Set a value in the given level. level: 'global' | 'session' | 'project' key: string key value: any JSON-serializable value ttl: optional time-to-live in seconds """ with self._lock: meta = { "value": value, "created_at": time.time(), "updated_at": time.time(), "ttl": ttl, } self._context.setdefault(level, {})[key] = meta def get(self, level, key): """Get a value. Return None if key doesn't exist or is expired.""" with self._lock: meta = self._context.get(level, {}).get(key) if meta is None: return None if meta["ttl"] is not None: if time.time() - meta["updated_at"] > meta["ttl"]: del self._context[level][key] return None return meta["value"] def save(self): """Persist current context to disk.""" with self._lock: tmp_file = self.storage_path.with_suffix(".tmp") with open(tmp_file, "w", encoding="utf-8") as f: json.dump(self._context, f, ensure_ascii=False, indent=2) tmp_file.replace(self.storage_path)

这个类虽然只有几十行，但已经包含了最核心的能力：设置、读取、过期判断、落盘。其中save用了一个临时文件加原子替换的技巧，避免直接写原文件时如果程序崩溃导致文件损坏。这是一个我踩过坑后的经验，后面第4节还会详细说。

3.2 一个简单的CLI集成示例：从保存到读取

光有类还不够，我把它集成进一个真实的CLI场景来演示。假设我们要做一个图片压缩工具，压缩之前需要用户指定输入目录和质量参数。我用argparse来解析命令，命令行没有提供时就从上下文读取：

import argparse from pathlib import Path ctx = ContextManager("~/.myapp/context.json") def require_dir(arg_value=None): """Return provided arg value, or read from context if available.""" if arg_value: ctx.set("project", "input_dir", arg_value) return arg_value cached = ctx.get("project", "input_dir") if cached: return cached raise SystemExit("请输入输入目录，或者先设置过context-mode") if __name__ == "__main__": parser = argparse.ArgumentParser() parser.add_argument("--input-dir", default=None) parser.add_argument("--quality", type=int, default=None) args = parser.parse_args() input_dir = require_dir(args.input_dir) quality = args.quality if quality is None: quality = ctx.get("project", "quality") or 85 ctx.set("project", "quality", quality) ctx.save() print(f"开始压缩，输入目录：{input_dir}，质量：{quality}")

注意require_dir的设计：如果用户传了新参数，就会更新上下文；如果没传，就尝试从上下文取值。这就是context-mode的核心体验——今天少敲几个参数，明天少敲更多，越用越顺手。

3.3 代码走读：关键的边界条件处理

这几十行代码里有几个边界条件，是实际跑起来之后才会发现的。

第一个是存储路径的扩展符处理。Path("~/.myapp/context.json")在Python中不会自动展开波浪号，必须调用Path.expanduser()。我在最初版本里漏了这一步，导致一直找不到文件，后来排查了很久。正确写法是：

self.storage_path = Path(storage_path).expanduser()

第二个是过期数据在get之后才删除。我的实现里，如果get时发现TTL过期，会先把数据删掉再返回None。但如果在删除之前，另一个线程正好也在读同一个key，就会出现竞态。我在get外层加了线程锁，这就是_lock的作用。不过，对单文件来说，这个锁只在进程内有效；如果多个进程同时读写同一个JSON文件，还需要加文件锁，这个坑我第4节会专门讲。

第三个是set的值必须可JSON序列化。如果你存了个自定义对象，json.dump时会直接抛TypeError。更隐蔽的是，如果存的是tuple，json会把它变成list，下次读出来类型就变了。如果想保留类型信息，必须在set时做转换检查。我在实际项目中加了这样一个断言：

def _ensure_json_serializable(self, value): try: json.dumps(value) except TypeError: raise TypeError(f"值 {value} 无法序列化为JSON")

这些边界条件看起来不复杂，但往往就是"能用"和"好用"之间的差距。

4. 实测中的坑与排查过程：数据覆盖、过期混乱和隐私泄漏

4.1 坑一：并发写入导致上下文互相覆盖

代码看起来没问题的部分，一上实测就暴露了第一个大坑。我的工具支持并行处理多个任务，于是会同时跑多个进程，每个进程都会调用ctx.save()，结果经常出现：进程A把上下文写到一半，进程B也写过来了，最终文件里数据错乱，甚至JSON解析直接失败。

排查过程是这样的：我先检查了代码里的线程锁_lock，发现它只能锁住当前进程内的线程，进程之间完全不管用。两个进程同时执行tmp_file.replace(self.storage_path)时，虽然临时文件是各自独立的，但替换操作本身不是原子的关联操作集合——A替换成功，B替换成功，后面的覆盖了前面的，无法合并。

解决办法是让进程间也能串行化。我引入了一个简单的文件锁，基于操作系统层面的fcntl：

import fcntl def save(self): with open(self.storage_path, "a+") as lock_file: fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX) # 原子写入内容 with open(tmp_file, "w", ...): json.dump(...) tmp_file.replace(self.storage_path) fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN)

但这里还有个微妙的问题：锁的竞争粒度是"整个文件的写入"，如果多个进程同时修改的是不同层级的数据，理论上是可以合并的。我图省事直接全文件互斥了，实测下来因为context本身写得不频繁，性能损失可以忽略。如果你的项目写得很频繁，就需要把锁粒度细化到字段级。

4.2 坑二：单字段过期机制导致的连锁混乱

第二个坑是在我加字段级TTL之后才浮现的。最初版本我把TTL放到了level层级，也就是session层整体2小时过期。后来改成字段级TTL后，我发现一个新的问题：决定"是否过期"的时间基准有问题。

一开始我给的逻辑是now - created_at > ttl就过期，但这有个反例：用户在一个长任务的刚开始设置了"待处理文件列表"，这个列表的created_at是一个小时前，但任务还没跑完。按created_at算，它已经过期了；可实际上它一直被正常使用着。

后来我改成now - updated_at > ttl，每次get命中就刷新updated_at，这样只要这个字段还在被持续使用，它就会一直存活。这个逻辑目前验证下来比较合理，但它也有代价：一个长期不用的上下文永远不会被彻底清掉，因为每次get都会给它续命。所以我加了一个上限：当now - created_at超过某个最大值（比如7天）时，强制认为过期，防止数据无限膨胀。

实际排查过程中，我用了一段脚本模拟了"反复读取同一个旧字段"的情况，确认了updated_at确实被刷新，也发现了created_at一直没变。这类问题只有在把"预期行为"和"实际行为"对照着看才容易暴露，单纯看代码很难发现。

4.3 坑三：上下文日志里存了不该存的密钥

第三个坑比较吓人。我在调试context-mode时经常打印整个上下文看看数据对不对，有一次发现打印内容里包含了用户临时输入的数据库密码。最开始没在意，觉得反正本地开发，后来才意识到，一旦这个模块被集成到线上的自动化脚本里，并且开启debug日志，就等于把密钥明文写到了日志文件里，如果日志被上传到日志中心，那就是事故。

修复方案是加一个脱敏层。具体在打印和序列化时，需要识别常见的敏感字段名：

SENSITIVE_KEYS = {"password", "secret", "token", "api_key"} def safe_dump(data): if isinstance(data, dict): return {k: ("***" if k.lower() in SENSITIVE_KEYS else safe_dump(v)) for k, v in data.items()} if isinstance(data, list): return [safe_dump(i) for i in data] return data

然后把所有对外输出改成走safe_dump，底层的存量数据保持原样。这里关键在于"展示层脱敏，存储层不脱敏"——如果你把存储层的值都改了，那后续需要用真实密码时就会出错。这个坑给我一个更深的教训：context-mode这类工具天然就是"什么数据都往里塞"的类型，所以必须在设计阶段就明确哪些数据碰都不能碰，对于高敏感数据，宁可完全不放进去。

4.4 修复后的验证方案：我是怎么确认问题真解决的

修完三个坑之后，我整理了一组回归测试用例，专门用来验证context-mode模块的稳定性。这组用例现在被我放在项目的tests目录下，每次改动后都会跑一遍：

1. 并发测试：同时启动8个进程，每个进程往context里写入不同的key，重复100轮，最后检查JSON文件里是否所有key都完整存在。
2. 过期测试：创建一条TTL为1秒的数据，sleep 1.2秒后读取，确认返回None，并且该key从存储中删除。
3. 隐私测试：用一个包含了password的假上下文跑一次打印，确认输出中对应字段是***。
4. 边界测试：key名称为空字符串、value为None、value为中文和带Unicode的字符，都要能正常写入和读取。

这些测试全部通过的时候，心里才踏实下来。尤其是并发测试，第一次跑就失败，后来加上进程锁才通过，那种"测试救了一命"的感觉，写代码的人都懂。

5. 从context-mode到智能化：在LLM会话场景中的扩展

5.1 把context-mode用在大模型交互上：滑动窗口和摘要

搞定了基础模块之后，我把它用在了另一个更贴近当前热点的场景：大语言模型（LLM）会话的上下文管理。很多人问，为什么AI聊天工具不能无限记住所有对话？核心原因就是上下文窗口有上限。context-mode在这里的价值，是可以设计一种"滑动窗口 + 摘要"的组合策略。

具体做法是：维护一个会话历史列表，新消息不断加入。当列表长度超过N条，或者总token数超过阈值时，我们取前面若干条消息做一次摘要，然后把摘要作为一个新的系统消息，再丢掉最老的消息。这样实际上形成了一种"滚动上下文"。

我把这个逻辑复用了之前的ContextManager，只是在session层里存了一个chat_history：

MAX_HISTORY = 10 def append_message(role, content): history = ctx.get("session", "chat_history") or [] history.append({"role": role, "content": content}) if len(history) > MAX_HISTORY: old_part = history[:-MAX_HISTORY // 2] recent_part = history[-MAX_HISTORY // 2:] old_text = "\n".join(f"{m['role']}: {m['content']}" for m in old_part) summary = llm_summarize(old_text) # 调用模型生成摘要 ctx.set("session", "chat_summary", summary) ctx.set("session", "chat_history", recent_part) else: ctx.set("session", "chat_history", history)

这套方案的关键是摘要的更新时机。如果每来一条新消息就跑一次摘要，成本太高；我的经验是等旧部分累计超过阈值时再整体生成一次摘要。另外要注意摘要本身也应该有TTL，因为它保存的是会话的临时状态，会话结束或被新摘要替代后就不再需要了。

5.2 后续还能怎么扩展：共享上下文、权限控制、可视化调试

现在这个context-mode模块已经能稳定运行了，但还谈不上完善。我自己整理了三个明确的扩展方向，如果你也在做类似项目，可以参考。

第一个方向是共享上下文。目前每个用户各自维护一份context文件，如果想在团队里共享项目级上下文，就需要引入同步机制。我的初步思路是：给每条context记录加一个owner字段，拉取时先检查权限，只返回自己有权限的部分。这样可以做到"项目组共享构建参数，个人私有配置不泄露"。

第二个方向是权限控制。这跟上面的共享是配套的。context里往往包含敏感信息，比如数据库连接串、临时密钥。改造方向是在set/get的接口中加入一个权限校验层，按照用户角色判断当前操作是否被允许。最简单的实现是建一个权限表，每个key对应一个可访问的角色列表；复杂一点的方向是做成与现有SSO/身份系统对接。

第三个方向是可视化调试。前端工程师调试时最想看的是上下文树的实时变化。我已经用Python做了个简单的Web页面，把ContextManager暴露成一个HTTP接口，用WebSocket推送变更事件，界面上能看到global/session/project三层的数据新增、过期、删除。这个扩展对排查"为什么某次操作行为异常"特别有用，因为你能看到程序到底记住了什么。

把context-mode从一个小模块扩展成完整的上下文管理框架，这条路其实很长。但至少起步阶段的方向是清晰的：先保证数据结构合理，再确保并发安全，最后再往智能化和协作方向走。

我在实际项目中体会最深的一点是，context-mode看起来像是个不起眼的辅助功能，但对用户体验的提升是实实在在的。它让工具从一个"每次都要重新认识你的陌生人"变成了"记得你习惯的同事"。开发过程中踩过的这三个坑——并发覆盖、过期混乱、隐私泄漏——几乎每一个都值得单独写篇文章，但总结下来核心原则也就三条：上下文要分层、过期要按字段、敏感要脱敏。记住这三点，你也能做出一个稳定好用的context-mode。