context-mode：AI辅助开发中的上下文隔离与回收实战

做 AI 辅助开发半年多，我最头疼的问题不是模型不够聪明，而是它总"串味"——早上还在写 A 项目的接口文档，下午打开对话工具问 B 项目的需求，AI 张口就是 A 项目的表结构和代码风格。长期多项目并行的人应该都有同感：大模型本身没有记忆，它记住的内容全来自上下文里塞进去的片段。一旦这些片段张冠李戴，再强的模型也救不回来。

后来我花了两周时间做了一套叫 context-mode 的上下文管理模式，本质上是一套"按项目、按任务组织 AI 工作记忆"的轻量工具集。它把项目背景拆成结构化的小块，用模式切换的方式按需注入和回收，让 AI 在每个任务里只看到当前该看的内容。开发早期，我习惯随手写 prompt，一天改八遍；做完这套体系之后，我几乎不再"临时想背景"，所有东西都是现成的，换项目像换抽屉一样干净。

这篇文章会完整拆解 context-mode 的背景、设计思路、完整搭建过程和实际使用效果。适合两类人看：一类是重度使用 AI 编程助手、经常同时推进多个项目的人；另一类是自己在做 RAG、Agent 相关应用，被上下文窗口和检索质量困扰的开发者。我会把配置文件和脚本都放出来，你可以直接照着抄。

1. 为什么需要 context-mode：先拆解三个真实痛点

1.1 上下文为什么容易"串味"

大模型本质上是一个"无状态函数"。每次你发消息，模型并不会真的记得之前聊过什么，它看到的只是你传进来的那一长串历史文本。聊天界面里所谓的"记忆"，是把所有往来消息一股脑拼在输入里，让模型基于这段文本续写。这个机制决定了：只要上下文里混入了其他项目的信息，模型就会把两件事当成一件事来推理。

我最早踩这个坑是在做某图像处理 Demo 的时候。那个项目用 Python 做边缘检测，依赖库是 OpenCV，接口风格是同步阻塞。同一时期我还参与开发某跨平台系统，那边的技术栈是 Go 微服务、异步消息队列、接口用 gRPC。两边代码我都频繁问 AI，结果某天我让 AI 帮我写图像 Demo 的批量处理脚本，它给我返回了一段 Go 代码，还配了 Kafka 消费者逻辑。问题就出在我贴上下文的时候，把上一个项目的调试日志也一起贴进去了。

如果你也有"AI 刚开新会话就像完全失忆"的体验，其实不是模型变笨了，而是你的上下文没有做隔离和重建。真人做事会分文件夹、分抽屉，AI 没有这个本能，它全靠你塞给它的文本。这就是 context-mode 要解决的第一个问题：让上下文像文件夹一样，每个项目一套，互不干扰。

1.2 上下文浪费与窗口溢出的代价

第二个痛点是成本和效率。大模型 API 是按 token 计费的，输入 token 和输出 token 都要花钱。很多人习惯每次开新对话就重新粘贴一遍项目背景，这段文字少说两三百字，换算成 token 大概 150 到 250 个。你一天问 50 次，多出来的纯消耗就是上万 token。单个看没感觉，月底看账单就肉疼了。

更麻烦的是上下文窗口有上限。模型不是无限记忆的，窗口塞满了旧信息就会被挤掉。早期的对话里可能有关键约束，比如"不要用 MySQL 分区表""错误码统一用 4 位数字"，一旦被挤出窗口，模型就按默认习惯发挥，导致答案完全偏离项目约定。我见过一个团队在某次交付前，AI 给出的迁移脚本用了项目里明令禁止的存储过程，就是因为团队换了新人，新人开的新会话里没有背景约束，模型自由发挥踩了雷。

有人觉得"那就一直保持长对话，别开新会话"——也不行。长对话越滚越长，成本线性上涨，而且模型对长上下文的注意力会衰减，中间部分经常被忽略。这个问题在业内有个通俗说法叫"迷失在中间"。所以真正健康的做法是：控制每个会话的上下文体积，把最重要的信息放在最前面，让旧会话沉淀成结构化记录，而不是无脑堆历史。

1.3 团队协作中的上下文孤岛

第三个痛点容易被单人开发者忽略，但在团队里非常致命：每个成员的 AI 对话上下文是不互通的。A 同学维护了一套很好的背景说明，B 同学完全不知道，还在用自己那套过时的术语和约束。同一项目的 AI 行为在不同人手里表现完全不一样，有人觉得 AI 是神器，有人觉得 AI 是人工智障，差别往往不在模型，而在喂给模型的上下文。

我见过某团队做内部工具时，测试同学问 AI"这个接口返回什么格式"，AI 给了旧版 JSON 结构，因为新接口改成了嵌套结构但测试同学的 prompt 里还写着老说明。这种"上下文孤岛"本质上是知识没有物化。传统的解决办法是写 wiki、写设计文档，但文档是给人看的，格式松散、更新滞后，很难直接变成 AI 的输入。

context-mode 的第三个目标就是把上下文变成项目资产——它不再是某个人聊天框里的私有内容，而是像代码一样存储在目录里、用 git 管理、可以被所有人复用的公共资源。上下文一旦变成一个一个的小文件，它就能被评审、被更新、被继承，团队成员之间的信息差也就被抹平了。

2. context-mode 的整体设计思路

2.1 核心概念：上下文包、模式配置与注入回收

context-mode 的设计借鉴了一个生活化的场景：工位整理。一个项目就是一个抽屉，抽屉里按标签分成技术栈、项目规则、进度记录、常用术语。你坐在工位上工作时，只需要把当前项目的抽屉拉开，把必要的文件摊在桌面上；换项目时把旧文件收回去，再拉开新抽屉。桌面永远是整洁的，你永远不会把上个项目的草稿压在本项目的合同上。

对应到这套系统里，有三个核心概念：

• 上下文包（context bundle）：描述项目某个侧面的独立文件，比如 stack.md 写技术栈、rules.md 写约定和禁忌、progress.md 写进度和近期决策。它是最小可复用单元。
• 模式（mode）：一个有名有姓的上下文集合，声明"当前我在做什么、需要加载哪些包、哪些包可以写回"。比如 image-demo 模式只加载图像处理项目的包，不加载跨平台系统的任何内容。
• 注册表（registry）：管理和解析模式的配置索引，负责把模式声明的文件按顺序组装成一段完整 prompt，并在退出模式时把新的决策写回对应包。

设计里我坚持三条原则。第一条是"显式优于隐式"——每个模式要加载哪些包，必须白纸黑字写在配置文件里，不能靠脚本里 hardcode 一堆 if else，否则后期维护会疯掉。第二条是"小粒度重用"——一个包只讲一件事，技术栈和进度不要混在一个文件里，这样多个模式可以灵活引用同一个技术栈包，而不是复制粘贴。第三条是"写回沉淀"——对话过程中产生的决策不能只留在聊天记录里，退出模式前要把关键信息压缩成结构化记录写回 progress 文件，否则下次开新会话一切归零。

2.2 目录结构与配置规范

我建议把整个 context-mode 放在用户目录下的 .ctx 文件夹里，用 git 管理。目录结构长这样：

~/.ctx/ ├── modes/ │ ├── image-demo/ │ │ ├── ctx.yaml │ │ ├── stack.md │ │ ├── rules.md │ │ ├── progress.md │ │ └── archive/ │ │ └── 2025-01-18-session.md │ └── cross-platform-system/ │ ├── ctx.yaml │ ├── stack.md │ ├── rules.md │ ├── progress.md │ └── glossary.md ├── global/ │ ├── base.md │ └── code-style.md ├── current/ │ ├── mode.txt │ └── prompt.md └── scripts/ ├── ctx.sh └── summarize.py

modes 目录下每个子目录是一个模式，目录名就是模式名。global 放跨项目通用的背景，比如通用编码规范、常用工具链说明。current 目录保存当前激活模式的标记和组装好的 prompt 文件，方便随时查看。scripts 放切换和管理脚本。

每个模式目录里必须有一个 ctx.yaml 作为配置入口，其他 md 文件从属于它。我的 ctx.yaml 长这样：

mode: image-demo description: 图像处理 Demo 项目，使用 Python + OpenCV 做边缘检测 contexts: - file: stack.md scope: project priority: high - file: rules.md scope: project priority: high - file: progress.md scope: writable priority: medium - file: ../global/base.md scope: global priority: low - file: ../global/code-style.md scope: global priority: low budget: max_tokens: 8000 headroom: 2000

contexts 列表声明这个模式要加载哪些包。file 是相对于 ctx.yaml 所在目录的路径，scope 标记是项目级还是全局级，priority 控制组装顺序：high 排在最前面，low 放在最后。writable 表示这个包在退出模式时可以被写回更新。

用 YAML 而不是 JSON，是因为可读性好、支持注释、diff 起来干净。团队多人修改配置时，YAML 的冲突合并比 JSON 直观得多。如果你觉得 YAML 的缩进麻烦，也可以用 TOML，看团队习惯，但不要混用。

budget 里 max_tokens 是这个模式允许的上下文总预算，headroom 是给模型回复预留的空间。这个值要结合你用的模型窗口大小来定，后面我会讲具体算法。

3. 从零搭建 context-mode 的实操过程

3.1 初始化脚手架

第一步，创建目录结构。直接在终端里执行：

mkdir -p ~/.ctx/{modes,global,current,scripts} cd ~/.ctx git init

我建议从一开始就用 git 管理整个 .ctx 目录，原因很简单：上下文包是知识资产，需要版本历史。某天有人改坏了一个规则文件，你可以快速回滚；团队协作时也能通过 diff 看谁改了什么、为什么改。这一步五分钟能做，别偷懒。

接下来给第一个模式建目录。我用 image-demo 举例：

mkdir -p ~/.ctx/modes/image-demo touch ~/.ctx/modes/image-demo/ctx.yaml touch ~/.ctx/modes/image-demo/stack.md touch ~/.ctx/modes/image-demo/rules.md touch ~/.ctx/modes/image-demo/progress.md

同时把全局包准备好：

touch ~/.ctx/global/base.md touch ~/.ctx/global/code-style.md

全局包一开始可以不写太多内容，只要放通用原则就行。后面的工作重点是填充各个上下文包的内容——这是整个系统最耗时间但最值得的部分。

3.2 编写上下文包：内容质量决定一切

上下文包的内容直接决定 AI 的回答质量。很多人以为写包就是把自己脑子里的东西倒出来，结果写成流水账，AI 看了半天找不到重点。我给你几个实际写作模板。

stack.md 是技术栈说明，重点是"具体版本 + 关键约束"，不要写废话。我的 image-demo 项目这样写：

# 技术栈与架构 - 语言: Python 3.11 - 视觉库: OpenCV 4.8 - 进程模型: 同步阻塞，不使用 asyncio - 输入: 单张图片路径，命令行参数传入 - 输出: 处理后图片保存到指定路径，终端打印耗时统计 - 禁止: 不要引入 torch / onnx 等重型依赖 - 测试: pytest，测试文件放在 tests/ 目录下

规矩就一条：每条信息都要"可执行"。说我用 Python 没用，说 Python 3.11 才能让 AI 知道 f-string 语法和类型注解写法；说不许用 asyncio 才能拦住它自作聪明给你上异步。

rules.md 是项目约定与禁忌，我的写法是"正向解释 + 反例 + 原因"三段式：

# 项目规则 1. 所有图像处理函数必须返回 (status, result) 元组，status 为 bool。 反例: 直接返回 result 或 None。 原因: 统一结果结构方便调用方处理异常路径。 2. 命令行参数用 argparse，不用 click。 反例: 某历史代码用 sys.argv 手工解析导致 bug。 3. 新代码不要写 logging.info 输出图片矩阵内容。 原因: 矩阵打印会刷爆终端且没有实际价值。 4. 修改公共接口时必须同步更新 README 示例。

这些规则来自实际踩过的坑。AI 非常擅长遵循明确规则，但前提是你得把规则写成"可判定"的形式——"不要写 X"比"尽量优雅"有用十倍。

progress.md 记录进度和决策，这个文件会被频繁写回，所以要保持精简。我用的模板是每条记录只有四行：

# 进度与决策记录 ## 2025-01-18 - 完成: 高斯滤波参数校验逻辑 - 决定: 统一使用 cv2.BORDER_REFLECT 处理边界 - 放弃: 手动实现卷积核，性能不达预期 - 下一步: 实现 Canny 边缘检测的滞后阈值联动

每个决策记录都包含"决定什么、为什么、后续影响"，这样才能在未来的会话中复现当时的选择逻辑。如果只写"决定了用 REFLECT 边界"而不写原因，下次模型可能会问"为什么不用默认边界"。

写包的时候还有一个 token 估算技巧。中英文 token 密度不同：中文大约每个字 1.5 到 2 个 token，英文大约是每 4 个字符 1 个 token。你用wc -m看字符数再折算一下，很快能算出每个包大概的 token 体量。我要求单个包不超过模式预算的四分之一，否则整个 prompt 会失控。

3.3 实现模式切换脚本

脚本是这套系统的心脏。我的目标非常明确：输入一个 mode 名，组装好 prompt，写入 current 目录，并支持写回。为了零依赖可移植，我最初用纯 bash 写了一个版本，核心逻辑是这样的：

#!/usr/bin/env bash # ctx - context-mode 模式切换工具 CTX_ROOT="${CTX_ROOT:-$HOME/.ctx}" ctx_build_prompt() { local mode="$1" local mode_dir="$CTX_ROOT/modes/$mode" local yaml="$mode_dir/ctx.yaml" if [ ! -f "$yaml" ]; then echo "mode not found: $mode" >&2 return 1 fi # 从 yaml 里提取 file 字段，按 priority 排序后拼接内容 # 实际项目里建议用 python + pyyaml 做解析，这里演示从简 local files files=$(awk -F': *' '/file:/{print $2}' "$yaml") local prompt="" prompt+="[系统角色]\n你正在协助进行以下项目的开发工作：\n\n" for rel in $files; do local path="$mode_dir/$rel" if [ -f "$path" ]; then prompt+="\n--- ${rel} ---\n" prompt+="$(cat "$path")\n" fi done if [ -f "$CTX_ROOT/current/mode.txt" ]; then rm "$CTX_ROOT/current/mode.txt" fi echo "$mode" > "$CTX_ROOT/current/mode.txt" echo -e "$prompt" > "$CTX_ROOT/current/prompt.md" echo "entered mode: $mode" } ctx_status() { echo "current mode: $(cat "$CTX_ROOT/current/mode.txt" 2>/dev/null || echo none)" echo "prompt file: $CTX_ROOT/current/prompt.md" wc -c "$CTX_ROOT/current/prompt.md" } case "$1" in enter) ctx_build_prompt "$2" ;; status) ctx_status ;; *) echo "usage: ctx {enter|status} [mode]" ;; esac

这段 bash 脚本够用，但不完美。最大的问题是 awk 解析 YAML 很脆弱，一旦配置里出现注释或者多行数组就会挂掉。所以我在实际项目里换成了 Python 版，用 PyYAML 做解析，不到 80 行，可靠得多。给你的建议是：如果你本身就在 Python 环境里工作，直接上 Python 脚本，别折腾 bash 解析 YAML。

脚本虽然简单，但组装 prompt 的顺序有讲究。我把 priority: high 的项目级包放在最前面，全局通用包放在最后。因为模型对开头和结尾的内容记忆最强，项目特异性信息放前面容易被"记住"，通用规范放后面作为兜底。如果你有非常关键的硬性约束，甚至可以把它放在 prompt 的最开头，压过一切。

3.4 上下文回收与压缩策略：用完记得收抽屉

进入模式只是第一步，退出模式时的"回收"同样重要。很多人以为切个模式就完事了，结果 progress.md 永远是旧的，下一轮对话 AI 还是什么都不知道。我在 ctx 脚本里加了一个 exit 流程，分三步走：

第一步，从当前对话里提取关键决策。我写了一个 summarize.py 脚本，把最后一段对话中出现的"决定、选择、放弃、下一步"这类动词后面的内容抽出来，格式化追加到 progress.md。当然，AI 提取会有误伤，所以我保留了手动确认的环节：它生成草稿，我看一眼再决定是否写入。

第二步，更新 current/mode.txt 为空，避免下次误读模式。同时把当前完整 prompt 和对话摘要归档到对应模式的 archive 目录，文件名带日期。

第三步，对超长会话执行压缩。如果当前会话已经接近 budget 上限，我需要把早期对话总结成一段 200 字的摘要，放在新会话的开头，替代原来那几千字的原文。压缩模板是这样的：

# 早期会话摘要 - 已完成: 高斯滤波参数校验、边界模式确认 - 关键决策: 使用 cv2.BORDER_REFLECT；放弃手写卷积核 - 阻塞问题: Canny 滞后阈值联动未定 - 当前阶段: 准备实现 Canny 边缘检测

摘要里只留"已完成、关键决策、阻塞问题、当前阶段"四类信息。那些讨论过程、调试日志、错误堆栈全部丢弃，因为它们不是知识，只是噪音。这个压缩习惯让我的每个会话都能轻装上阵，新开会话时把摘要贴进去就可以无缝续上。

4. 实际使用效果与关键配置参考

4.1 一个完整的使用场景演示

理论讲完，看下实际效果。某天上午我先在 image-demo 模式下让 AI 帮我实现了一个高斯滤波的边界处理，然后切换到 cross-platform-system 模式处理接口文档。两次切换的命令行输出如下：

$ ctx enter image-demo entered mode: image-demo prompt written to ~/.ctx/current/prompt.md (6,320 chars, approx 3,160 tokens)

$ ctx enter cross-platform-system entered mode: cross-platform-system prompt written to ~/.ctx/current/prompt.md (8,140 chars, approx 4,070 tokens)

关键验证点是用 grep 检查 image-demo 模式生成的 prompt 里不包含 cross-platform-system 的任何专有名词，反过来也一样。我用脚本跑了一个断言，确认两个模式之间零泄漏。以前手动粘贴上下文时经常把 A 项目的依赖名带到 B 项目里，现在切换模式后我可以直接检查 current/prompt.md 的内容，保证喂给 AI 的文本是干净的。

组装后的 prompt 开头部分长这样：

[系统角色] 你正在协助进行以下项目的开发工作： --- stack.md --- # 技术栈与架构 - 语言: Python 3.11 ... --- rules.md --- # 项目规则 1. 所有图像处理函数必须返回 (status, result) 元组 ...

实际使用下来，AI 给出的代码不再出现其他项目的框架和术语。以前一次误用需要花二十分钟改代码，现在从源头就避免了。而且由于上下文体积可控，每次请求的 token 消耗比之前的"大杂烩"方式少了大约三成，月底对账时效果很明显。

4.2 关键参数选择建议

参数调节是这套系统里最容易被忽视的部分。我的经验值如下：

预算分配方面，我把 max_tokens 设为模型窗口的一半以下。比如模型窗口是 8k，我就把 max_tokens 压到 4k 到 5k，留 3k 以上给模型输出和中间推理。上下文塞得太满，模型输出质量会明显下降，因为它需要"挤"在剩余空间里回答问题，推理深度受限。

上下文包的大小上，单个包控制在总预算的四分之一以内。一个 image-demo 的 stack.md 加上 rules.md 加起来 3k token，完全够用。如果某个包超过预算，我会拆成两个模块——比如把"接口规范"和"实现细节"分开，后者只在需要深挖实现时才临时引用，不进入默认模式。

priority 的设置也值得细想。我把真正不可违反的硬规则放在 high，把背景信息和惯例放在 low。全局包通常都是 low，因为通用规范对具体任务的影响较弱；项目包的 rules.md 是 high，因为它是项目特异性最强的约束。如果全局包和项目包出现冲突，规则是项目包覆盖全局包，因为具体项目的约定理应优先于通用惯例。

写回频率我固定在两个时机：完成一个可验证的小任务后立刻写一条进度；或者退出模式前做一次批量写回。不要每次对话都写，那样 progress.md 会变成聊天流水账，没有价值。要写就写决策级别的内容，条数少但信息密度高。

5. 常见问题与排查技巧实录

5.1 常见问题速查表

真实部署这套系统之后，我整理了一份问题速查表，几乎每个问题我都自己踩过：

第五个问题在团队场景里最容易出现。个人用的时候自己改了包自己知道，但团队里如果有人改了 stack.md 没有推送，另一个人用旧包生成 prompt，AI 给出的方案就会过时。把上下文包纳入 git 只是第一步，真正要养成"改动必须有记录"的习惯。

5.2 排查过程实录：一次典型的"串味"事故

有一次我遇到了一个诡异的情况：明明切到了 image-demo 模式，AI 回答的还是跨平台系统里的内容。当时我按三层排查走了一遍。

先跑 ctx status，显示当前 mode 是 image-demo，模式切换看起来正常。然后我看 current/prompt.md，发现里面确实没有 cross-platform-system 的包。到这里我已经很奇怪了，prompt 是干净的，为什么输出有问题。最后仔细搜索才发现：global/base.md 里有一段历史遗留的文字，写了跨平台系统的部署环境变量，这是很早以前我为了省事塞进全局包的。全局包虽然 priority 是 low，但它依然会被加载进每个模式，于是旧项目的信息就顺着这个口子溜进来了。

这个教训很深刻：全局包必须保持真正的"全局"，绝不能图省事把项目专属信息塞进去。我后来给 global 目录加了审查习惯——每次往里面加内容时问自己一句："这个内容对另一个完全无关的项目也有用吗？"如果答案是否，它就应该放进具体模式目录而不是全局目录。

第二个案例是 token 超限问题。某天我进入某个大项目的模式，一测 prompt 字符数到了 15k，明显超预算。排查发现引入的包过多，包括一个写得很啰嗦的 glossary.md，里面有几十条术语解释，每条还带例句。我把 glossary 从默认模式里移除，改成只有在需要时才通过额外参数临时加载，prompt 立刻瘦身到 6k。这个项目给我的启发是：词典、背景故事这类"低密度信息"包，尽量不要占用默认上下文，要用时再单独引入。

5.3 几个容易踩的坑

第一个坑是一开始容易把上下文包写得又长又全。我曾经给一个项目的 rules.md 写了四十多条规则，结果模型面对这么多约束反而"选择困难"，经常违反低级约束只遵守高级约束。后来我把规则按重要性分层：top 5 条硬性规则放最前面，其他常规约定放后面当补充。模型对开头的注意力最强，把最重要的约束放在 prompt 开头，遵守率明显提高。

第二个坑是全局包与项目包内容对撞。比如全局规则说"优先复用已有组件"，项目 A 的 rules 说"本次重构允许引入新库"，两条同时在 prompt 里，AI 会犹豫甚至自我矛盾。解决方法是建立覆盖约定：在组装 prompt 时，项目包排在全局包前面，并在 prompt 末尾追加一句"当规则冲突时，以项目包内容为准"。这样模型就有一个明确的冲突裁决依据。

第三个坑是过度设计。我一开始想给每个小任务都建一个 mode，比如"写周报模式""查日志模式""写 README 模式"，结果模式数量爆炸，维护成本比收益还高。后来我砍到只剩三类模式：长期项目模式、重复性日常任务模式、通用问答模式。其他的场景直接走通用问答模式，临时在对话里补两句背景就够了。建 mode 的成本不低——上下文包要长期维护、定期更新，所以只给"至少要用两个星期以上、知识密度高"的场景建 mode，其他都是浪费。

最后一点真实体会

用了 context-mode 快两个月，最大的收获不是省了 token，也不是回答准确率提升，而是它逼着我把每个项目的背景知识整理成了结构化文档。以前我总觉得"AI 应该能猜出我在做什么"，现在明白，真正可靠的用法是把预期管理做在前面——让模型在动手之前就看到清晰、无冲突的上下文。这些上下文文件后来也成了新人上手的快速培训材料，这个副产品是我当初没想到的。

一个小技巧分享给你：如果你暂时不想引入完整脚本，可以先从"手动模式"开始——把 stack.md、rules.md、progress.md 三个文件按固定顺序粘贴到每个新会话的开头，用一个月感受到效果后再上脚本自动组装。别一上来就折腾 YAML 解析和 git flow，先用最简单的方案跑通流程、养成习惯，后面的一切都会顺理成章。