AI编程助手迁移：别只搬运聊天记录，上下文有三层

我相信不少人跟我一样，会在某个时间点决定换一个AI编程助手：可能是订阅价格涨了，可能是觉得当前工具生成的代码总是不对味，也可能是公司统一换了工具链。我当时从用了半年的CodeGeeX换到Cursor，第一反应不是去看文档，而是想把以前的“聊天记录”全部带走。我天真地以为，把过去几十万token的对话导出、塞给新助手，它就能像旧助手一样懂我的代码风格、知道我的历史决策。结果，新助手读完那些聊天记录之后，非但没有变聪明，反而开始经常性地给我过时建议——因为它看到的，全是我上一个项目里已经被推翻的方案。

那次折腾让我反思了一个很基础的问题：对一个AI编程助手来说，上下文到底是什么？后来我总结出一句话——上下文不是一个袋子，而是三层抽屉：聊天记录只是最上面那一层，下面还有一层是代码库，最底下是IDE的实时状态。大多数转工具的人，都只搬了最上面那层，还把它当成全部。这篇文章围绕这个三层拆开讲讲，为什么只复制聊天记录是个陷阱，以及一次体面的助手迁移到底该搬什么。

1. 先想清楚：换助手时你真正想“带过去”的是什么

1.1 一次失败的“聊天记录迁移”实验

我记得很清，那天下午我做了三件事。第一步，用一个第三方导出工具把和旧助手的全部对话导成Markdown，大概有1200多个文件、40多万token。第二步，把导出的对话压缩成一个超大上下文文件，直接作为项目说明喂给新助手。第三步，我喊了一句“你先把这个项目的历史背景了解一下”。新助手倒是很配合，认认真真读完了，然后当我让它改一处接口时，它引用了半年前已经被废弃的数据库字段——那个字段在当时的聊天记录里很正常，但在现在的代码库里已经不存在了。

这个失败不是偶然的。聊天记录有两个非常恶劣的特性：第一，它记录的是“当时的真相”，不是“现在的真相”；第二，它的信息密度极低，大量篇幅是在来回试探、确认需求、解释报错。把这种又旧又长的文本扔进新助手的上下文窗口，相当于让新员工入职第一天先看三年的旧会议纪要，而不是去看最新的代码仓库。

1.2 上下文不是一个袋子，而是三层抽屉

经过那次教训，我给自己画了一张“上下文分层图”。我不建议你跟风，但你可以用它来检查自己手头有哪些可以交接的资产：

• 第一层，对话历史层。也就是你和工具之间累积的全部问答、需求描述、代码片段、报错解决过程。它的特征很明确：显式、文本化、最容易导出。很多人换工具时唯一想到的就是这一层，但它恰恰最容易过期。
• 第二层，项目级上下文层。包括目录结构、文件内容、依赖清单、构建配置、README、Git历史、测试用例、lint规则。它持久、精确、能被任何一个助手重新读取，是真正值得交接的资产。
• 第三层，IDE状态与运行现场层。包括光标位置、当前打开的文件、选中文本、LSP诊断、终端报错、dev server日志、调试断点。这一层基本不落盘，更像是“下一秒就会消失”的现场感。

这三层不是平行的，而是从持久到易失的渐变。你换助手时能原样“复制”的，几乎只有第一层；而真正决定新助手能不能快速上手的，反而是第二层和第三层。这也是为什么很多评测里，同一个模型放进不同的IDE插件里表现天差地别——看起来都是模型在写代码，实际上三层上下文的获取机制完全不一样。你别只盯着模型本身，得看看它在你手头能摸到哪几层。

2. 第一层上下文：聊天记录，最容易被高估的资产

2.1 为什么聊天记录看起来有用，实际帮不上忙

聊天记录是所有上下文里最容易量化的部分，导出按钮一点就有，所以它天然给人一种“保留住就安全”的错觉。但放到真实工程里，它至少有三个致命问题。

第一个问题是时效性。代码项目每天都在变：模块被重命名，接口被合并，方案被推翻。聊天记录里写的是“我上一版是这个思路”，而当前代码库里可能早就换成了另一个实现。新助手拿着旧对话当依据，等于拿去年地图导航今天的路，出错几乎是必然的。

第二个问题是信息密度。你可以回看自己和助手的任何一段对话，里面大量内容是“你试试这样”“不行，报错了”“再贴一段日志”这种低信息量来回。真正有价值的结论可能只占十分之一。把几十万token的原始对话塞进上下文窗口，大量token都在传递无效信号，真正能辅助判断的内容反而被稀释了。

第三个问题则和模型机制有关：上下文窗口再大也不是无限缓存。现在很多工具打着32K、128K甚至1M上下文的招牌，很多人误以为“1M上下文”意味着可以把所有历史都囤进去。但你要明白，上下文窗口是给“当前任务需要的全部信息”预留的计算空间。你把旧对话塞进去，当前代码库、最新的报错、Agent临时探索到的文件就会被挤出去。窗口越长，模型对中间内容的注意力也越容易摊薄，这是个需要严肃对待的工程问题，不是“越大越好”。

2.2 聊天记录的正确用法：压缩成“决策存档”而不是原文搬运

那么聊天记录就彻底没用了吗？当然不是。它有一个不可替代的价值：记录了你和旧助手之间达成的“隐性约定”——比如哪些库是禁用的、错误码为什么统一用四位数字、核心模块为什么选了这个架构。这些结论如果还没落入文档，通常只存在于聊天记录里。

所以正确姿势是“提炼”，不是“搬运”。我后来固定用三步法处理旧对话。

第一步，翻录。从头到尾快速过一遍对话，划出三类片段：技术约束（“这个项目只能用这一套库”）、方案取舍（“为什么选Postgres而不是MySQL”）、风格偏好（“命名要动词开头，函数式优先”）。遇到已经过期的实现细节不标，直接跳过。

第二步，重写。把划出的片段改写成陈述句，每个条目控制在100字内，按主题归类。所有涉及具体旧代码行号、旧报错堆栈的细节全部删掉，因为它们要么已经失效，要么能在当前代码里直接查到。

第三步，验证。把提炼出的条目对照当前代码库逐条确认，把已经不成立的条目删掉，最后生成一份不超过20条的“AI协作约定”文档。下面是我给一个后端项目整理过的示例结构：

# AI协作约定 （来源：2024.05-2025.01 旧助手对话提炼，已对照当前代码验证） 1. 后端路由统一挂 /api/v1，禁止自行追加前缀。 2. 数据库操作必须使用 SQLAlchemy 2.x 的 select() 风格，禁止裸 SQL。 3. 核心服务对外调用必须带超时与重试，禁止裸调第三方接口。 4. 前端错误提示统一用中文，后端错误码统一为 4 位数字。 5. 命名：函数用动词开头，状态量前缀 is/has。 6. 提交信息统一用 conventional commits 格式。

这份文件只有几百token，不会撑爆任何窗口，而且新助手只要读一遍，价值就超过40万token的原始对话。我一直觉得，聊天记录不等于记忆，记忆是经过压缩和更新的结论。这句话建议你贴到显示器旁边。

3. 第二层上下文：代码库，真正能让新助手“秒懂”你的东西

3.1 项目级上下文究竟包含什么

第二层是很多人最容易忽视、但对新助手来说最重要的一层。项目级上下文可以由下面这张表来概括：

这些内容的共同特点是：它们不是你在聊天里“告诉”助手的，而是助手自己通过索引、读取、检索拿到的。所以只要你换助手时代码库本身还在，第二层上下文其实没有任何丢失。问题只在于——它能不能快速有效地读取到。

3.2 现代编程助手是如何读取代码库的

理解这一层的关键，是要知道现代编程助手读取项目上下文大致有三种机制。

第一种是仓库索引加向量检索，也就是常说的RAG。Cursor、Cline、Copilot的@workspace、CodeGeeX的代码库问答，底层都是类似思路：先对代码切片、做向量化，用户提问时把最相关的若干片段抓回上下文。索引质量取决于代码结构是否清晰——命名规范、模块边界清楚的项目，检索命中率会明显高。

第二种是显式引用，也就是你自己手动把文件路径交给助手。很多工具支持在对话里输入@src/api/client.ts，让助手读取指定文件再回答。这种方式精度高、可预期，适合“只改某个模块”的任务。

第三种是Agent式主动探索。助手自己执行命令、读文件、查依赖关系，再把结果逐步塞回上下文。比如它遇到一个不认识的函数，会自动去搜它的定义和调用链。这个模式最接近一个真正的开发者在读代码，也正是1M级上下文窗口发挥作用的地方——它能一次性容纳几十个关键文件的全量内容，让Agent在这一轮探索里看到更多信息。

所以你会发现，这三条路径的共同点是“以当前代码为准”。聊天记忆是弱信号，代码库才是强信号。换助手这件事，本质上换的是一套索引方式和交互范式，而不是“继承一段对话”。

3.3 把项目整理成“可交接资产”的三件套

为了让第二层上下文在新工具里发挥最大价值，我给自己的每个长期项目都准备了三样东西，统称“可交接三件套”。

第一件是架构说明文档。它不需要很长的篇幅，但至少要有目录结构说明、模块依赖与数据流、核心业务流程、已知的技术债与坑、本地运行方式。有条件的再加一节“当前进展”，标明最近一次交付完成了什么、下一步计划是什么。

第二件是AI协作约定，也就是上一章提炼出来的那份文档。它比代码更像“项目的脾气”，任何新助手读一遍就能避开很多雷区。

第三件是整洁的Git历史。提交信息要规范，合并记录要清晰。因为新助手在接手项目时，经常通过git log来补足上下文，看最近几十个commit是了解项目当前状态最快捷的方式。

这三样东西的共同点是跨平台通用：ChatGPT能读、Cursor能读、Copilot能读，任何一套新工具都能直接使用。它们才是真正的通用上下文格式。而且它们和聊天记录最大的不同是，文档会跟着代码更新，聊天记录不会。

我自己补上architecture.md之后，新助手再也没有问过“这个模块在哪”“这个错误码什么意思”这类问题。开始我还想用聊天记录回答它，后来发现根因根本不在对话，在我的仓库少了这份文档。

4. 第三层上下文：IDE里的现场感，换不掉也搬不走

4.1 现场感包括哪些“碰不到”的信息

第三层上下文，我把它叫做“现场感”。它出现在代码库与编辑器结合的缝隙里，平时你不会意识到它存在，一旦换工具，立刻感觉像断了手臂。

具体来说，这层包括：光标当前停留的位置与活动的文件、你正选中的那一段代码、编辑器的Problems面板里堆积的实时编译诊断、终端里正在滚动的构建日志、测试失败时那一堆堆栈、调试会话里的断点与变量值、dev server持续输出的warning。这些信息的共同特点是：它们不在文件里，不落盘，也不在聊天记录里，它们只存在于“当前这一刻的工具和环境里”。

打个比方，你正在修一个bug：代码第102行报错，光标停在那一行，终端里滚着一屏异常日志，你脑子里刚理出“问题大概出在这个缓存策略上”。这时候你让助手看一眼，它瞬间就能接上话。但如果换了工具，这种互相衔接的状态归零，新助手面对的是干净的文件，而不是你所处的那个“现场”。

4.2 用“执行上下文”来理解为什么现场感不可复制

如果你接触过操作系统或图形编程，会发现“上下文”这个词在底层概念里同样无处不在：进程切换时保存和恢复的寄存器、栈指针、程序计数器叫执行上下文；中断处理时保存的CPU状态叫中断上下文；OpenGL里的状态绑定则叫图形上下文。

这些领域对“上下文”的通用定义是：决定一个执行体下一步行为的状态集合。操作系统切换进程时，保存的是易失状态，文件系统才是持久状态；AI编程助手也一样，它的上下文必然由两部分组成：持久状态（代码库、约定、对话历史）和易失状态（当前位置、诊断、运行输出）。

想清楚这一点，你就明白为什么现场感不能靠导出解决——你不可能把一个进程的寄存器值存成文件，换一台机器继续跑。同样，你也没法把IDE里正在发生的诊断和报错“下载”下来，再“上传”给另一个工具。现场感只能重建，不能搬移。

4.3 换助手后如何重建现场感

既然搬不走，那就重建。我在实际操作中总结出几个有效动作。

换工具当天，不要挑在“改到一半”的时候。先把当前改动提交或者至少stash，让仓库处于干净、可复现的状态。为什么要这样？因为现场感丢失后，新助手唯一能依赖的就是代码状态和报错输出，如果仓库本身处于半成品状态，它连基线都找不到。

重开项目后，第一件事是跑一遍构建和测试，故意让错误重新暴露。注意，这里有个重要区别：新助手分析的应该是“刚刚发生的报错”，而不是“上礼拜的旧报错”。前者能从编译器拿到完整现场信息，分析起来高效得多；后者只是聊天记录里的一段二手描述，价值大打折扣。

然后在新IDE里手动打开核心文件，把与当前任务相关的几个文件拉开，再开始第一轮对话。很多助手支持从当前文件或当前选区开始会话，这样第三层会以最快速度重建。如果要做跨模块的大重构，先给新助手一个“侦察任务”，让它读一遍代码库，输出它对模块关系的理解，你确认无误后再让它动手。这就像操作系统切换进程后先做寄存器恢复，而不是盲目接管。

5. 一份可照抄的助手迁移清单

5.1 换之前的准备：迁移前1~2天

我把整个迁移过程整理成了一份清单，每次换工具前照着走一遍，基本不会出大问题。

• 提炼聊天记录。用前文的三步法生成“AI协作约定”文档，条目控制在20条以内，并逐条对照当前代码验证，删除过期内容。
• 补全架构文档。确保README里有一份能说明模块划分和核心流程的文档，哪怕只是简单的段落，也比没有强。
• 让仓库干净起来。提交或暂存所有未提交改动，把本地测试跑绿。有条件的话，把CI状态也恢复为绿色。
• 记录依赖与构建命令。把“如何安装依赖、如何启动、如何跑测试”写进README，换工具当天照着执行即可。
• 如果你在旧助手那里配置过系统级提示词或规则，把那段提示词也导出。它通常反映了你对AI协作的要求，比如“不要主动修改未提到的文件”，这类规则同样适用于新助手。

5.2 换之后的磨合：一周内不要急着喂旧对话

换好后，接下来一周是关键磨合期。我的原则是：别急着把旧对话批量喂给新助手，先让它用代码库本身建立理解，再逐步校准风格。

第一天只做“侦察”和“热身”。让新助手读取architecture.md和AI协作约定，跑一遍测试，然后回答几个关于模块关系的问题。此时不要让它改代码，先看它能不能准确描述项目现状。

第二天到第三天开始修真实bug。优先挑那些“你完全知道答案”的小问题，比如一个明确的热点bug。目标不是让助手解决问题，而是观察它的方案和你预期是否一致，以此来校准差异——同一个问题，旧助手可能给出“加到原函数里”的方案，新助手可能建议“抽成独立工具函数”，两边都有道理，但你要从中感受它的思维习惯。

一周内，把磨合中发现的规则回流到项目文档。如果新助手多次把某个逻辑抽到公共函数，而你认可这种风格，就把它写进约定文档。这样一周下来，新助手对项目的理解会慢慢超越你当初转录的任何聊天记录。

这里还有一句重要的提醒：不要强把一个工具的使用习惯套在另一个工具身上。每个助手的上下文机制有差异，有的模型原生支持工具调用，你教它像旧工具那样用对话式长凭证，反而低效。比如CodeGeeX的交互方式和Cursor就不同，前者的长记忆链路可能更适合对话式，后者更适合靠索引和Agent探索。工具的新习惯，要在使用中感受，而不是背靠背硬搬。

5.3 迁移中常见的四个翻车现场

如果已经不小心把聊天记录整段倒了进去，最直接的补救办法是新建一个会话，清空项目索引，重新生成约定文档，然后强制自己“遗忘”那份旧对话。脏上下文比没上下文更可怕，它会持续把新助手带向错误的方向。

我个人换了几次助手之后的真实体会是：聊天记录是你和旧助手的共同记忆，但它从来不是项目的地基。真正的地基是代码库、文档和能复现问题的环境。换助手，本质上等于换一个执行环境，不要指望把现场感搬过去，要做的是把持久状态整理清楚，让新进程重新顺畅跑起来。后来我又有一次从Claude Pro换回本地工具链，这次没有导出任何聊天记录，只是完成了当天的约定提炼、补齐架构文档、重建一次现场，第三天新助手就已经能独立接活。这套思路，之后不管换什么工具，我相信都还用得上。