1. 从一次上下文崩溃说起为什么长会话里的编码代理会“失忆”如果你用 AI 编码代理跑过稍微大一点的项目大概率遇到过这种场景前 30 轮对话里它还记得你的目录结构、命名规范、某个工具函数的签名到了第 50 轮你让它改一个之前已经讨论过的模块它开始一本正经地胡说八道把utils/date.ts里的函数搬到services/下面或者干脆重新发明一个你已经写好的工具。这不是模型变笨了而是上下文窗口被压缩机制“动过刀”了。我把它叫做“脑叶切除术”——当会话 token 数逼近上限平台侧会触发上下文压缩把早期对话摘要化、截断化甚至直接丢弃。对于闲聊这没什么但对于一个需要持续记住项目状态、文件结构、接口约定的编码代理来说这等于把它的长期记忆切掉了一大块。你还在按原来的约定跟它协作它却已经换了一个“人格”。这个项目要解决的问题很具体让 AI 编码代理在长会话中对抗上下文压缩保持对项目关键状态的记忆连续性。核心思路借鉴了两个东西——Unix 的init.d服务管理模型以及电影《记忆碎片》里那种“用外部载体对抗短期记忆缺失”的叙事结构。前者提供了一套“开机自举、按需拉起、状态可查”的机制后者提供了一种“把关键事实写下来、每次操作前先读一遍”的工作范式。适合谁来参考如果你满足下面任意一条这篇内容对你就直接有用一是用 AI 代理做中大型项目重构会话经常超过几十轮二是自己搭过基于 API 的编码助手被上下文管理折磨过三是单纯好奇“怎么让一个会失忆的助手依然可靠地干活”。下面我会把整套设计思路、关键实现、踩过的坑和排查方法完整拆开讲。2. 整体设计思路用 init.d 的自举模型对抗记忆丢失2.1 为什么选“服务自举”而不是“加大上下文”最直觉的方案是换更大的上下文窗口或者把压缩阈值调高。我试过治标不治本。原因有两个第一窗口再大也有上限项目一大照样溢出第二即使不溢出超长上下文里的信息密度会被稀释模型对早期关键信息的注意力本来就会衰减。这就像你往一个房间里不断堆东西堆到一定程度找任何一件东西都变难了。所以我换了个思路不指望模型自己记住而是让它在每次需要的时候能主动“查”到。这正好对应 Unix 的init.d模型——系统启动时不需要把所有服务都塞进内存而是通过一套约定好的脚本目录按需启动、查询状态、重启服务。代理也一样它不需要把整个项目历史背在脑子里只需要知道“去哪里查、怎么查、查完怎么用”。具体来说我把项目里那些“代理必须始终知道”的信息抽出来固化到一组外部文件里形成一套类似init.d的目录约定。代理在每次关键操作前先执行一个“自举脚本”把这些文件读进来重建工作记忆。这样即使平台侧把早期对话压缩掉了代理也能通过这套机制把关键状态“拉回来”。2.2 《记忆碎片》范式把“记忆”外化成可重复读取的载体《记忆碎片》里主角的做法很极端但很有效他记不住新发生的事于是把关键信息纹在身上、拍成照片、写成纸条每次行动前先看一遍。这个范式迁移到编码代理上核心就一句话——不要依赖对话历史作为唯一记忆载体把关键事实写成代理每次都会读的文件。我落地时把它拆成三层第一层是“纹身”项目级的不可变约定比如目录结构、命名规范、技术栈版本。这些写在PROJECT_CONTRACT.md里代理每次自举必读。第二层是“照片”当前任务的动态状态比如“正在重构哪个模块”“已经改了哪些文件”“下一步要做什么”。写在TASK_STATE.md里随任务推进更新。第三层是“纸条”临时的、一次性的上下文比如某个函数的当前实现、某次报错的完整堆栈。这些放在SCRATCH.md里用完即弃。关键在于这三层文件不是给人看的文档而是给代理读的“记忆载体”。它们的格式、位置、读取时机都是被自举脚本严格约定的代理不需要“想起来”去读而是流程强制它读。2.3 方案选型的取舍为什么不直接用向量库或 RAG有人会问为什么不搞一套向量检索把历史对话存进去需要时检索出来我实际对比过对于编码代理这个场景向量库有几个硬伤一是检索结果不可控你没法保证它一定召回“那个函数签名”而编码场景对精确性要求极高二是引入额外依赖调试链路变长出问题很难定位是检索错了还是模型理解错了三是延迟每次操作前检索一遍交互体验会变差。而基于文件的自举方案本质上是“确定性检索”——文件路径和内容是固定的代理读到的就是写进去的没有召回率问题。代价是需要人工维护这些文件的结构但换来的是可预测、可调试、零额外依赖。对于个人开发者和小团队这个取舍是划算的。3. 核心细节解析自举脚本、状态文件与读取时机3.1 自举脚本的设计代理的“开机第一件事”自举脚本是整个机制的入口。它的职责很简单按固定顺序读取那三层记忆文件拼装成一段结构化的“工作记忆摘要”注入到当前对话的最前面。我用的是 shell 脚本加一个轻量的模板拼接核心逻辑大概是这样#!/usr/bin/env bash # bootstrap.sh - 代理自举脚本 # 按约定顺序读取记忆文件输出结构化工作记忆 CONTRACT.agent/PROJECT_CONTRACT.md STATE.agent/TASK_STATE.md SCRATCH.agent/SCRATCH.md echo WORKING MEMORY BOOTSTRAP echo echo --- [LAYER 1: CONTRACT] --- cat $CONTRACT 2/dev/null || echo (empty) echo echo --- [LAYER 2: TASK STATE] --- cat $STATE 2/dev/null || echo (empty) echo echo --- [LAYER 3: SCRATCH] --- cat $SCRATCH 2/dev/null || echo (empty) echo echo END BOOTSTRAP 这个脚本本身不复杂复杂的是它背后的约定代理在每次开始一个新任务、或者感觉上下文可能被压缩之后必须先跑一遍这个脚本。我在系统提示里明确写了这条规则并且用“如果你不确定当前项目状态先执行 bootstrap”这样的措辞反复强化。注意自举脚本的输出要控制长度。我一开始把整个PROJECT_CONTRACT.md都塞进去结果每次自举就吃掉几千 token反而加速了压缩。后来改成只读“契约摘要”部分完整契约放在文件里按需查阅。3.2 三层记忆文件的格式约定文件格式直接决定了代理能不能高效读取。我踩过的坑是一开始用自由格式的 Markdown结果代理每次读进来的理解都不太一样有时候把注释当成了指令。后来我改成半结构化的格式用固定的标题和键值对稳定性好了很多。PROJECT_CONTRACT.md的结构大概是这样# PROJECT CONTRACT (IMMUTABLE) ## STACK - language: TypeScript 5.x - runtime: Node 20 - test: vitest - package-manager: pnpm ## STRUCTURE - src/components: UI 组件每个组件一个目录 - src/services: 业务逻辑禁止直接操作 DOM - src/utils: 纯函数必须有单元测试 ## NAMING - 组件文件: PascalCase.tsx - 工具函数: camelCase.ts - 常量: UPPER_SNAKE_CASE ## FORBIDDEN - 禁止在 services 层引入 React - 禁止使用 any - 禁止跳过测试直接提交TASK_STATE.md是动态的我要求代理在每次完成一个子任务后更新它# TASK STATE ## CURRENT - task: 重构用户认证模块 - phase: 提取 token 校验逻辑 - last-file: src/services/auth/verify.ts ## DONE - [x] 梳理现有认证流程 - [x] 提取 token 解析函数 ## NEXT - [ ] 提取 token 校验函数 - [ ] 补充单元测试 - [ ] 更新调用方 ## BLOCKERS - 无SCRATCH.md则是用完即清的临时区代理可以往里写任何它觉得“这次需要记住但下次不一定需要”的东西。3.3 读取时机的判断什么时候该自举这是整个机制里最需要经验的部分。自举太频繁浪费 token 和交互轮次自举太少代理已经失忆了才补救为时已晚。我总结了几条触发规则新任务开始时必读不管上下文看起来多完整新任务一律先自举。连续对话超过 20 轮后每 5 轮自举一次这是我实测下来压缩开始变得明显的临界区间。代理出现“记忆模糊”信号时立即自举比如它开始问“你之前说的那个文件叫什么来着”或者引用了不存在的路径。执行破坏性操作前必读删除文件、批量重命名、改公共接口之前先自举确认当前状态。实操心得我在系统提示里加了一条“如果你对当前项目状态有任何不确定先执行 bootstrap 再继续”这条规则救了我很多次。代理主动自举的成本远低于它基于错误记忆干活的成本。4. 实操过程从零搭一套抗压缩的代理工作流4.1 初始化项目记忆目录第一步是在项目根目录建一个.agent/目录把三层记忆文件的模板放进去。我建议用脚本初始化避免每次手动建mkdir -p .agent touch .agent/PROJECT_CONTRACT.md touch .agent/TASK_STATE.md touch .agent/SCRATCH.md然后把bootstrap.sh放到.agent/下并赋予执行权限。接着在.gitignore里决定哪些文件要版本控制——我的做法是PROJECT_CONTRACT.md和TASK_STATE.md纳入版本控制SCRATCH.md忽略因为它是临时的。4.2 把自举规则写进系统提示这一步是成败关键。代理不会自动知道要去读这些文件你必须在系统提示里用明确的、可执行的指令告诉它。我的系统提示里相关部分大概是这样你是一个编码代理工作在一个可能发生上下文压缩的长会话环境中。 在以下情况你必须先执行 .agent/bootstrap.sh 并阅读其输出 1. 开始任何新任务之前 2. 连续对话超过 20 轮后每 5 轮执行一次 3. 当你对项目结构、命名规范、当前任务状态有任何不确定时 4. 执行删除、重命名、修改公共接口等破坏性操作之前 执行 bootstrap 后以输出内容为准重建你的工作记忆。 如果 bootstrap 输出与你的对话记忆冲突以 bootstrap 输出为准。最后那句“以 bootstrap 输出为准”很重要。压缩后的对话记忆可能是错的但文件是可信的必须明确优先级。4.3 一次完整的任务执行记录我拿一个真实的重构任务走一遍流程你能看到自举是怎么嵌入的。任务是“把认证模块里的 token 校验逻辑抽成独立函数”。第 1 步任务开始代理自举。它执行bootstrap.sh读到契约里的“services 层禁止引入 React”“工具函数必须有测试”读到任务状态里的“当前在提取 token 校验逻辑”读到 scratch 为空。基于这些它确认了工作目录和约束。第 2 步代理读取目标文件。它打开src/services/auth/verify.ts看到当前的校验逻辑内联在login函数里。它没有直接改而是先更新TASK_STATE.md把 phase 改成“提取 token 校验函数”。第 3 步代理执行提取。它新建src/services/auth/validateToken.ts把逻辑搬过去然后在原文件里 import 新函数。这一步它遵守了契约里的命名规范camelCase 文件名。第 4 步代理补充测试。因为契约里写了“工具函数必须有单元测试”它自动去src/services/auth/__tests__/下建了测试文件。这一步如果没有契约约束它很可能会跳过。第 5 步代理更新状态。它把TASK_STATE.md里的 DONE 加一条NEXT 里划掉“提取 token 校验函数”phase 改成“补充单元测试”。第 6 步会话继续了 30 多轮中间平台触发了一次压缩。代理在第 35 轮时感觉要改调用方它主动执行了 bootstrap重新读到契约和最新状态确认了“调用方在src/pages/Login.tsx”然后准确地去改了那个文件。如果没有自举它很可能已经忘了调用方在哪。这个流程跑下来最直观的感受是代理的行为变得可预测了。它不再依赖“运气好没被压缩”而是有一套确定的机制把关键状态拉回来。4.4 参数与阈值的选择依据上面提到的“20 轮”“5 轮”这些数字不是拍脑袋来的。我做过一组粗略的测试在典型的中等复杂度项目里对话轮次和 token 消耗大致是线性关系每轮平均消耗 800 到 1500 token取决于代码块大小。当总 token 逼近窗口的 70% 到 80% 时压缩开始明显影响早期信息的保真度。按每轮 1000 token 估算20 轮大约消耗 2 万 token对于 32k 窗口来说已经过半所以我把 20 轮设为第一个警戒线。至于“每 5 轮自举一次”是因为自举本身消耗大约 500 到 1000 token太频繁会加速消耗。5 轮一次是在“记忆新鲜度”和“token 成本”之间取的平衡。你可以根据自己的窗口大小和每轮 token 消耗调整公式大概是自举间隔 窗口大小 × 0.3 / 每轮平均 token。5. 常见问题与排查技巧实录5.1 代理不执行自举怎么办这是最常见的问题。原因通常有三个一是系统提示里的指令不够明确代理把它当成了“建议”而不是“规则”二是自举脚本路径不对代理执行失败后就放弃了三是代理在压缩后连“要自举”这件事都忘了。针对第一个原因我把指令从“你可以执行 bootstrap”改成了“你必须执行 bootstrap”并且加了“如果输出与记忆冲突以输出为准”的优先级声明。针对第二个我在脚本里加了容错路径不存在时输出明确的错误信息而不是静默失败。针对第三个这是最棘手的——如果代理连自举规则都忘了那就没辙了。我的应对是在每个任务的第一个用户消息里手动带上“先执行 bootstrap”的提醒相当于人工兜底。5.2 自举输出太长反而加速压缩前面提过这个坑。解决办法是分层读取自举时只读契约的“摘要区”和任务状态的“当前区”完整内容放在文件里代理需要时再单独读。我在PROJECT_CONTRACT.md顶部加了一个## SUMMARY区只放最关键的 5 到 10 条约束自举脚本只读这个区。5.3 状态文件被代理改乱代理有时候会“过度更新”状态文件把一些不该记的东西写进去或者格式改得乱七八糟。我的应对是给状态文件定一个严格的模板并且在系统提示里写明“只允许在指定区块内追加或修改不允许改变文件结构”。另外TASK_STATE.md纳入版本控制后改乱了我可以直接git diff看它改了什么必要时回滚。5.4 常见问题速查表问题现象可能原因排查方法解决手段代理引用不存在的文件路径上下文压缩导致记忆错乱让它执行 bootstrap 后重新确认强化自举触发规则代理跳过测试直接改代码契约约束被压缩丢失检查 bootstrap 是否读到契约把测试要求写进契约摘要区自举后行为仍不对状态文件本身是错的人工检查 TASK_STATE.md修正状态文件并回滚错误操作自举脚本执行失败路径或权限问题手动跑一遍脚本看报错修正路径加容错输出token 消耗过快自举太频繁或输出太长统计每轮 token 消耗调整自举间隔精简输出5.5 几个我踩过的坑第一个坑是把契约写得太细。一开始我把所有编码规范都塞进契约结果自举一次就吃掉大量 token。后来我只保留“代理容易违反且后果严重”的约束比如“禁止 any”“services 层禁止引入 React”其他细节让它按常规习惯来。第二个坑是状态文件更新滞后。代理有时候干完活忘了更新TASK_STATE.md导致下次自举读到的是旧状态。我的应对是在系统提示里把“完成任务后更新状态”设为强制步骤并且在自举脚本里加了一个检查如果状态文件的修改时间早于最近一次代码提交就输出警告。第三个坑是过度依赖自举。有一段时间我让代理每轮都自举结果交互变得很慢而且 token 消耗翻倍。后来我改成按需触发体验好了很多。这个机制的定位是“保险”不是“日常操作”别把它用成每轮必跑的仪式。6. 把这套机制迁移到你的工作流这套东西的核心其实不是那几个脚本而是一个观念转变不要把 AI 代理的记忆当成理所当然要像对待一个会失忆的协作者一样给它准备好外部记忆载体。Unix 的 init.d 给了我们“按需自举”的模型《记忆碎片》给了我们“关键事实外化”的范式两者结合就能让代理在长会话里保持可靠。迁移到你的项目时我建议从最小可用版本开始先建一个PROJECT_CONTRACT.md只写 5 条最重要的约束再建一个TASK_STATE.md只记当前任务和下一步然后写一个最简单的 bootstrap 脚本把这两个文件拼起来输出。跑几个任务感受一下代理在压缩后的表现有没有改善再决定要不要加第三层 scratch 和更复杂的触发规则。最后分享一个我最近在用的技巧在TASK_STATE.md里加一个## HANDOFF区专门写给“下一个自举的代理”看。当我知道这次会话可能要结束了我会让代理把当前进度、未解决的问题、下一步建议写进 HANDOFF 区。下次新会话开始时代理自举读到 HANDOFF就能无缝接上。这个技巧把“抗压缩”延伸到了“跨会话”实测下来很稳。 AI编码代理长会话失忆？用init.d自举模型对抗上下文压缩
1. 从一次上下文崩溃说起为什么长会话里的编码代理会“失忆”如果你用 AI 编码代理跑过稍微大一点的项目大概率遇到过这种场景前 30 轮对话里它还记得你的目录结构、命名规范、某个工具函数的签名到了第 50 轮你让它改一个之前已经讨论过的模块它开始一本正经地胡说八道把utils/date.ts里的函数搬到services/下面或者干脆重新发明一个你已经写好的工具。这不是模型变笨了而是上下文窗口被压缩机制“动过刀”了。我把它叫做“脑叶切除术”——当会话 token 数逼近上限平台侧会触发上下文压缩把早期对话摘要化、截断化甚至直接丢弃。对于闲聊这没什么但对于一个需要持续记住项目状态、文件结构、接口约定的编码代理来说这等于把它的长期记忆切掉了一大块。你还在按原来的约定跟它协作它却已经换了一个“人格”。这个项目要解决的问题很具体让 AI 编码代理在长会话中对抗上下文压缩保持对项目关键状态的记忆连续性。核心思路借鉴了两个东西——Unix 的init.d服务管理模型以及电影《记忆碎片》里那种“用外部载体对抗短期记忆缺失”的叙事结构。前者提供了一套“开机自举、按需拉起、状态可查”的机制后者提供了一种“把关键事实写下来、每次操作前先读一遍”的工作范式。适合谁来参考如果你满足下面任意一条这篇内容对你就直接有用一是用 AI 代理做中大型项目重构会话经常超过几十轮二是自己搭过基于 API 的编码助手被上下文管理折磨过三是单纯好奇“怎么让一个会失忆的助手依然可靠地干活”。下面我会把整套设计思路、关键实现、踩过的坑和排查方法完整拆开讲。2. 整体设计思路用 init.d 的自举模型对抗记忆丢失2.1 为什么选“服务自举”而不是“加大上下文”最直觉的方案是换更大的上下文窗口或者把压缩阈值调高。我试过治标不治本。原因有两个第一窗口再大也有上限项目一大照样溢出第二即使不溢出超长上下文里的信息密度会被稀释模型对早期关键信息的注意力本来就会衰减。这就像你往一个房间里不断堆东西堆到一定程度找任何一件东西都变难了。所以我换了个思路不指望模型自己记住而是让它在每次需要的时候能主动“查”到。这正好对应 Unix 的init.d模型——系统启动时不需要把所有服务都塞进内存而是通过一套约定好的脚本目录按需启动、查询状态、重启服务。代理也一样它不需要把整个项目历史背在脑子里只需要知道“去哪里查、怎么查、查完怎么用”。具体来说我把项目里那些“代理必须始终知道”的信息抽出来固化到一组外部文件里形成一套类似init.d的目录约定。代理在每次关键操作前先执行一个“自举脚本”把这些文件读进来重建工作记忆。这样即使平台侧把早期对话压缩掉了代理也能通过这套机制把关键状态“拉回来”。2.2 《记忆碎片》范式把“记忆”外化成可重复读取的载体《记忆碎片》里主角的做法很极端但很有效他记不住新发生的事于是把关键信息纹在身上、拍成照片、写成纸条每次行动前先看一遍。这个范式迁移到编码代理上核心就一句话——不要依赖对话历史作为唯一记忆载体把关键事实写成代理每次都会读的文件。我落地时把它拆成三层第一层是“纹身”项目级的不可变约定比如目录结构、命名规范、技术栈版本。这些写在PROJECT_CONTRACT.md里代理每次自举必读。第二层是“照片”当前任务的动态状态比如“正在重构哪个模块”“已经改了哪些文件”“下一步要做什么”。写在TASK_STATE.md里随任务推进更新。第三层是“纸条”临时的、一次性的上下文比如某个函数的当前实现、某次报错的完整堆栈。这些放在SCRATCH.md里用完即弃。关键在于这三层文件不是给人看的文档而是给代理读的“记忆载体”。它们的格式、位置、读取时机都是被自举脚本严格约定的代理不需要“想起来”去读而是流程强制它读。2.3 方案选型的取舍为什么不直接用向量库或 RAG有人会问为什么不搞一套向量检索把历史对话存进去需要时检索出来我实际对比过对于编码代理这个场景向量库有几个硬伤一是检索结果不可控你没法保证它一定召回“那个函数签名”而编码场景对精确性要求极高二是引入额外依赖调试链路变长出问题很难定位是检索错了还是模型理解错了三是延迟每次操作前检索一遍交互体验会变差。而基于文件的自举方案本质上是“确定性检索”——文件路径和内容是固定的代理读到的就是写进去的没有召回率问题。代价是需要人工维护这些文件的结构但换来的是可预测、可调试、零额外依赖。对于个人开发者和小团队这个取舍是划算的。3. 核心细节解析自举脚本、状态文件与读取时机3.1 自举脚本的设计代理的“开机第一件事”自举脚本是整个机制的入口。它的职责很简单按固定顺序读取那三层记忆文件拼装成一段结构化的“工作记忆摘要”注入到当前对话的最前面。我用的是 shell 脚本加一个轻量的模板拼接核心逻辑大概是这样#!/usr/bin/env bash # bootstrap.sh - 代理自举脚本 # 按约定顺序读取记忆文件输出结构化工作记忆 CONTRACT.agent/PROJECT_CONTRACT.md STATE.agent/TASK_STATE.md SCRATCH.agent/SCRATCH.md echo WORKING MEMORY BOOTSTRAP echo echo --- [LAYER 1: CONTRACT] --- cat $CONTRACT 2/dev/null || echo (empty) echo echo --- [LAYER 2: TASK STATE] --- cat $STATE 2/dev/null || echo (empty) echo echo --- [LAYER 3: SCRATCH] --- cat $SCRATCH 2/dev/null || echo (empty) echo echo END BOOTSTRAP 这个脚本本身不复杂复杂的是它背后的约定代理在每次开始一个新任务、或者感觉上下文可能被压缩之后必须先跑一遍这个脚本。我在系统提示里明确写了这条规则并且用“如果你不确定当前项目状态先执行 bootstrap”这样的措辞反复强化。注意自举脚本的输出要控制长度。我一开始把整个PROJECT_CONTRACT.md都塞进去结果每次自举就吃掉几千 token反而加速了压缩。后来改成只读“契约摘要”部分完整契约放在文件里按需查阅。3.2 三层记忆文件的格式约定文件格式直接决定了代理能不能高效读取。我踩过的坑是一开始用自由格式的 Markdown结果代理每次读进来的理解都不太一样有时候把注释当成了指令。后来我改成半结构化的格式用固定的标题和键值对稳定性好了很多。PROJECT_CONTRACT.md的结构大概是这样# PROJECT CONTRACT (IMMUTABLE) ## STACK - language: TypeScript 5.x - runtime: Node 20 - test: vitest - package-manager: pnpm ## STRUCTURE - src/components: UI 组件每个组件一个目录 - src/services: 业务逻辑禁止直接操作 DOM - src/utils: 纯函数必须有单元测试 ## NAMING - 组件文件: PascalCase.tsx - 工具函数: camelCase.ts - 常量: UPPER_SNAKE_CASE ## FORBIDDEN - 禁止在 services 层引入 React - 禁止使用 any - 禁止跳过测试直接提交TASK_STATE.md是动态的我要求代理在每次完成一个子任务后更新它# TASK STATE ## CURRENT - task: 重构用户认证模块 - phase: 提取 token 校验逻辑 - last-file: src/services/auth/verify.ts ## DONE - [x] 梳理现有认证流程 - [x] 提取 token 解析函数 ## NEXT - [ ] 提取 token 校验函数 - [ ] 补充单元测试 - [ ] 更新调用方 ## BLOCKERS - 无SCRATCH.md则是用完即清的临时区代理可以往里写任何它觉得“这次需要记住但下次不一定需要”的东西。3.3 读取时机的判断什么时候该自举这是整个机制里最需要经验的部分。自举太频繁浪费 token 和交互轮次自举太少代理已经失忆了才补救为时已晚。我总结了几条触发规则新任务开始时必读不管上下文看起来多完整新任务一律先自举。连续对话超过 20 轮后每 5 轮自举一次这是我实测下来压缩开始变得明显的临界区间。代理出现“记忆模糊”信号时立即自举比如它开始问“你之前说的那个文件叫什么来着”或者引用了不存在的路径。执行破坏性操作前必读删除文件、批量重命名、改公共接口之前先自举确认当前状态。实操心得我在系统提示里加了一条“如果你对当前项目状态有任何不确定先执行 bootstrap 再继续”这条规则救了我很多次。代理主动自举的成本远低于它基于错误记忆干活的成本。4. 实操过程从零搭一套抗压缩的代理工作流4.1 初始化项目记忆目录第一步是在项目根目录建一个.agent/目录把三层记忆文件的模板放进去。我建议用脚本初始化避免每次手动建mkdir -p .agent touch .agent/PROJECT_CONTRACT.md touch .agent/TASK_STATE.md touch .agent/SCRATCH.md然后把bootstrap.sh放到.agent/下并赋予执行权限。接着在.gitignore里决定哪些文件要版本控制——我的做法是PROJECT_CONTRACT.md和TASK_STATE.md纳入版本控制SCRATCH.md忽略因为它是临时的。4.2 把自举规则写进系统提示这一步是成败关键。代理不会自动知道要去读这些文件你必须在系统提示里用明确的、可执行的指令告诉它。我的系统提示里相关部分大概是这样你是一个编码代理工作在一个可能发生上下文压缩的长会话环境中。 在以下情况你必须先执行 .agent/bootstrap.sh 并阅读其输出 1. 开始任何新任务之前 2. 连续对话超过 20 轮后每 5 轮执行一次 3. 当你对项目结构、命名规范、当前任务状态有任何不确定时 4. 执行删除、重命名、修改公共接口等破坏性操作之前 执行 bootstrap 后以输出内容为准重建你的工作记忆。 如果 bootstrap 输出与你的对话记忆冲突以 bootstrap 输出为准。最后那句“以 bootstrap 输出为准”很重要。压缩后的对话记忆可能是错的但文件是可信的必须明确优先级。4.3 一次完整的任务执行记录我拿一个真实的重构任务走一遍流程你能看到自举是怎么嵌入的。任务是“把认证模块里的 token 校验逻辑抽成独立函数”。第 1 步任务开始代理自举。它执行bootstrap.sh读到契约里的“services 层禁止引入 React”“工具函数必须有测试”读到任务状态里的“当前在提取 token 校验逻辑”读到 scratch 为空。基于这些它确认了工作目录和约束。第 2 步代理读取目标文件。它打开src/services/auth/verify.ts看到当前的校验逻辑内联在login函数里。它没有直接改而是先更新TASK_STATE.md把 phase 改成“提取 token 校验函数”。第 3 步代理执行提取。它新建src/services/auth/validateToken.ts把逻辑搬过去然后在原文件里 import 新函数。这一步它遵守了契约里的命名规范camelCase 文件名。第 4 步代理补充测试。因为契约里写了“工具函数必须有单元测试”它自动去src/services/auth/__tests__/下建了测试文件。这一步如果没有契约约束它很可能会跳过。第 5 步代理更新状态。它把TASK_STATE.md里的 DONE 加一条NEXT 里划掉“提取 token 校验函数”phase 改成“补充单元测试”。第 6 步会话继续了 30 多轮中间平台触发了一次压缩。代理在第 35 轮时感觉要改调用方它主动执行了 bootstrap重新读到契约和最新状态确认了“调用方在src/pages/Login.tsx”然后准确地去改了那个文件。如果没有自举它很可能已经忘了调用方在哪。这个流程跑下来最直观的感受是代理的行为变得可预测了。它不再依赖“运气好没被压缩”而是有一套确定的机制把关键状态拉回来。4.4 参数与阈值的选择依据上面提到的“20 轮”“5 轮”这些数字不是拍脑袋来的。我做过一组粗略的测试在典型的中等复杂度项目里对话轮次和 token 消耗大致是线性关系每轮平均消耗 800 到 1500 token取决于代码块大小。当总 token 逼近窗口的 70% 到 80% 时压缩开始明显影响早期信息的保真度。按每轮 1000 token 估算20 轮大约消耗 2 万 token对于 32k 窗口来说已经过半所以我把 20 轮设为第一个警戒线。至于“每 5 轮自举一次”是因为自举本身消耗大约 500 到 1000 token太频繁会加速消耗。5 轮一次是在“记忆新鲜度”和“token 成本”之间取的平衡。你可以根据自己的窗口大小和每轮 token 消耗调整公式大概是自举间隔 窗口大小 × 0.3 / 每轮平均 token。5. 常见问题与排查技巧实录5.1 代理不执行自举怎么办这是最常见的问题。原因通常有三个一是系统提示里的指令不够明确代理把它当成了“建议”而不是“规则”二是自举脚本路径不对代理执行失败后就放弃了三是代理在压缩后连“要自举”这件事都忘了。针对第一个原因我把指令从“你可以执行 bootstrap”改成了“你必须执行 bootstrap”并且加了“如果输出与记忆冲突以输出为准”的优先级声明。针对第二个我在脚本里加了容错路径不存在时输出明确的错误信息而不是静默失败。针对第三个这是最棘手的——如果代理连自举规则都忘了那就没辙了。我的应对是在每个任务的第一个用户消息里手动带上“先执行 bootstrap”的提醒相当于人工兜底。5.2 自举输出太长反而加速压缩前面提过这个坑。解决办法是分层读取自举时只读契约的“摘要区”和任务状态的“当前区”完整内容放在文件里代理需要时再单独读。我在PROJECT_CONTRACT.md顶部加了一个## SUMMARY区只放最关键的 5 到 10 条约束自举脚本只读这个区。5.3 状态文件被代理改乱代理有时候会“过度更新”状态文件把一些不该记的东西写进去或者格式改得乱七八糟。我的应对是给状态文件定一个严格的模板并且在系统提示里写明“只允许在指定区块内追加或修改不允许改变文件结构”。另外TASK_STATE.md纳入版本控制后改乱了我可以直接git diff看它改了什么必要时回滚。5.4 常见问题速查表问题现象可能原因排查方法解决手段代理引用不存在的文件路径上下文压缩导致记忆错乱让它执行 bootstrap 后重新确认强化自举触发规则代理跳过测试直接改代码契约约束被压缩丢失检查 bootstrap 是否读到契约把测试要求写进契约摘要区自举后行为仍不对状态文件本身是错的人工检查 TASK_STATE.md修正状态文件并回滚错误操作自举脚本执行失败路径或权限问题手动跑一遍脚本看报错修正路径加容错输出token 消耗过快自举太频繁或输出太长统计每轮 token 消耗调整自举间隔精简输出5.5 几个我踩过的坑第一个坑是把契约写得太细。一开始我把所有编码规范都塞进契约结果自举一次就吃掉大量 token。后来我只保留“代理容易违反且后果严重”的约束比如“禁止 any”“services 层禁止引入 React”其他细节让它按常规习惯来。第二个坑是状态文件更新滞后。代理有时候干完活忘了更新TASK_STATE.md导致下次自举读到的是旧状态。我的应对是在系统提示里把“完成任务后更新状态”设为强制步骤并且在自举脚本里加了一个检查如果状态文件的修改时间早于最近一次代码提交就输出警告。第三个坑是过度依赖自举。有一段时间我让代理每轮都自举结果交互变得很慢而且 token 消耗翻倍。后来我改成按需触发体验好了很多。这个机制的定位是“保险”不是“日常操作”别把它用成每轮必跑的仪式。6. 把这套机制迁移到你的工作流这套东西的核心其实不是那几个脚本而是一个观念转变不要把 AI 代理的记忆当成理所当然要像对待一个会失忆的协作者一样给它准备好外部记忆载体。Unix 的 init.d 给了我们“按需自举”的模型《记忆碎片》给了我们“关键事实外化”的范式两者结合就能让代理在长会话里保持可靠。迁移到你的项目时我建议从最小可用版本开始先建一个PROJECT_CONTRACT.md只写 5 条最重要的约束再建一个TASK_STATE.md只记当前任务和下一步然后写一个最简单的 bootstrap 脚本把这两个文件拼起来输出。跑几个任务感受一下代理在压缩后的表现有没有改善再决定要不要加第三层 scratch 和更复杂的触发规则。最后分享一个我最近在用的技巧在TASK_STATE.md里加一个## HANDOFF区专门写给“下一个自举的代理”看。当我知道这次会话可能要结束了我会让代理把当前进度、未解决的问题、下一步建议写进 HANDOFF 区。下次新会话开始时代理自举读到 HANDOFF就能无缝接上。这个技巧把“抗压缩”延伸到了“跨会话”实测下来很稳。