做 AI 輔助開發(fā)半年多我踩過最深的坑不是 prompt 寫得不夠好而是上下文丟了。今天聊的項目 context-mode就是專門解決這個問題的一套輕量級上下文管理方案。它本身是一個跑在終端里的命令行工具負責(zé)把每次 AI 協(xié)作會話里的“記憶”結(jié)構(gòu)化地存下來下次打開終端一鍵恢復(fù)不用重新把項目背景、改到哪一步、踩過哪些坑再講一遍。這個問題有多痛我用一個數(shù)字說明我統(tǒng)計過自己某段開發(fā)周期里的 40 次 AI 會話平均每次要花 6 到 10 分鐘重建上下文包括重復(fù)粘貼項目結(jié)構(gòu)、重新描述目標、把昨天的結(jié)論再說一遍。這還不算上下文窗口被占滿后模型開始“忘記”早期約束導(dǎo)致的返工。context-mode 想做的事很簡單把上下文當成一等公民來管理像 git 管理代碼一樣管理記憶。適合誰來參考如果你經(jīng)常用 AI 編碼助手做多文件改造、跨天續(xù)接任務(wù)或者同時維護好幾個項目這篇文章里的設(shè)計思路和代碼可以直接抄。下面從需求拆解、分層模型、核心實現(xiàn)到排坑實錄完整走一遍偏實戰(zhàn)不講虛的。1. 項目緣起與需求拆解1.1 痛點剖析AI 協(xié)作中的“失憶”問題所有 AI 編碼助手本質(zhì)上都是一個“無狀態(tài)函數(shù)”你給它一段輸入它返回一段輸出中間不保留任何記憶。所謂多輪對話不過是你自己把歷史消息一遍遍重新塞回去。這個問題在短會話里不明顯一旦任務(wù)跨天、跨文件、跨模塊立刻暴露。我梳理了自己的真實工作流發(fā)現(xiàn)上下文丟失主要發(fā)生在四個環(huán)節(jié)啟動新會話時需要重新描述項目背景、技術(shù)棧和當前進度。切換任務(wù)時上一個任務(wù)的關(guān)鍵決策會被新任務(wù)擠掉。上下文窗口被長日志、大文件占滿后早期約束被“擠”出模型注意力。中斷幾天后回來自己都忘了當初為什么做某個設(shè)計。這些不是模型能力問題而是工作流問題。模型的能力再強沒有上下文它就是一張白紙。所以我當時的判斷是與其等模型“記得更牢”不如自己把記憶管起來。context-mode 的定位不是又一個筆記工具而是專門給 AI 協(xié)作場景設(shè)計的狀態(tài)管理器核心動作只有三個記錄、壓縮、恢復(fù)。1.2 context-mode 的定位與核心價值我把這套工具拆成了三個價值點對應(yīng)三類使用場景第一跨會話續(xù)接。昨天改到一半的模塊今天打開終端執(zhí)行ctx resume工具自動把項目摘要、未完成清單、最近幾個關(guān)鍵決策拼成一段結(jié)構(gòu)化文本直接作為新會話的初始輸入。實測下來續(xù)接任務(wù)的上下文重建時間從 8 分鐘降到了 1 分鐘以內(nèi)。第二多項目隔離。同時維護三四個項目時最容易出現(xiàn) A 項目的代碼風(fēng)格要求被帶到 B 項目。context-mode 按項目目錄劃分存儲空間每個項目一套獨立的上下文切目錄就是切記憶互不污染。第三上下文瘦身。給 AI 的輸入不是越多越好。把近一周的會話記錄全部塞進去效果反而不如一段 500 字的高質(zhì)量摘要加幾條關(guān)鍵原文。context-mode 把上下文分成熱、溫、冷三層熱層保留原文溫層保留摘要冷層只留索引把輸入控制在一個合理的 token 預(yù)算內(nèi)。這三個價值點決定了工具的整體形態(tài)它必須是一個 CLI 工具因為要融入終端工作流它必須是文件存儲因為要保證可審計、可手動修改它必須支持導(dǎo)出因為最終這些上下文要喂給各種 AI 助手。2. 整體架構(gòu)與分層模型設(shè)計2.1 三層上下文模型熱、溫、冷上下文管理的核心難點不是“存下來”而是“存什么、扔什么”。我參考了緩存系統(tǒng)的思想把上下文按訪問頻率和價值分成三層層級內(nèi)容保留策略用途熱層當前任務(wù)的關(guān)鍵決策、未完成項、報錯原文本次會話內(nèi)保留任務(wù)切換時降級直接作為 prompt 原文溫層已完成步驟摘要、文件改動清單、關(guān)鍵函數(shù)簽名按時間衰減最近 3 天優(yōu)先拼接為任務(wù)背景冷層歷史會話的壓縮索引、版本快照長期保留只存摘要和指針追溯決策依據(jù)這個模型解決了兩個問題一是 prompt 長度可控。熱層控制在 1500 token 以內(nèi)溫層控制在 3000 token 以內(nèi)冷層只在需要回溯時才讀取。二是信息不丟。冷層不是直接刪掉舊內(nèi)容而是壓縮成摘要萬一后面發(fā)現(xiàn)某個設(shè)計決策有問題還能從冷層翻出原始記錄。分層的依據(jù)來自我對真實會話的觀察一次 40 輪左右的 AI 編碼會話真正有價值的有效信息不超過 20%剩下 80% 是重復(fù)提問、報錯堆疊、中間產(chǎn)物。把 80% 的噪音塞給模型等于花錢買干擾。2.2 存儲結(jié)構(gòu)與數(shù)據(jù)格式存儲方案我對比過三個方向SQLite、JSON 文件、純文本目錄。最終選了 JSON 文件理由有三點一是數(shù)據(jù)結(jié)構(gòu)天然是嵌套的項目、層級、條目三級關(guān)系用 JSON 表達最直觀二是出了問題可以直接用編輯器打開修改故障恢復(fù)成本低三是配合 git 可以做版本管理這比數(shù)據(jù)庫遷移簡單太多。每個項目的上下文存儲在~/.context-mode/project.json結(jié)構(gòu)如下{ project: alpha, version: 3, updated_at: 2025-06-20T22:15:0008:00, tiers: { hot: [ { id: 47, type: decision, content: 用戶模塊改用倉庫模式統(tǒng)一走 gateway 接口禁止直接操作數(shù)據(jù)層, created_at: 2025-06-20T21:00:0008:00 }, { id: 48, type: todo, content: 剩余阻塞項訂單超時狀態(tài)機缺少重試分支, created_at: 2025-06-20T21:30:0008:00 } ], warm: [ { id: 40, type: summary, content: 完成用戶模塊接口重構(gòu)舊接口保持兼容刪除冗余的 XXService, created_at: 2025-06-19T18:00:0008:00 } ], cold: [] }, summary: alpha 項目用戶模塊重構(gòu)完成 70%下一階段處理訂單超時狀態(tài)機。技術(shù)棧后端 Go PostgreSQL前端 Vue3。關(guān)鍵約定所有接口返回統(tǒng)一響應(yīng)結(jié)構(gòu)。 }每個條目都要帶id和type這是我踩過坑之后加的。id用于回溯和刪除type決定條目在導(dǎo)出時的格式比如decision類型會以“關(guān)鍵決策”前綴導(dǎo)出todo類型以“待辦”前綴導(dǎo)出這樣 AI 助手能更快識別哪些是約束、哪些是任務(wù)。2.3 為什么是“模式切換”而不是全量記錄項目名叫 context-mode重點在“mode”。一開始我寫的是全量記錄器想把每次會話都存成完整日志結(jié)果存了兩周就發(fā)現(xiàn)根本沒法用日志文件越來越大導(dǎo)出給 AI 時長度爆炸而且大部分內(nèi)容是無效的。后來我換了個思路把工具定位成“手動 半自動”的混合模式。手動的地方在于任務(wù)完成、方向調(diào)整、發(fā)現(xiàn)關(guān)鍵坑位時你主動執(zhí)行一條ctx mark命令做標記。半自動的地方在于工具監(jiān)聽當前工作區(qū)的文件變化自動記錄最近改動的文件列表并在會話結(jié)束時自動生成一段總結(jié)建議。為什么不全自動因為當前技術(shù)條件下自動抽取“什么是有價值的信息”準確率還不夠高。與其存一堆噪音不如讓開發(fā)者自己按下快門。這也符合我對上下文管理工具的判斷它應(yīng)該是開發(fā)者的副駕儀表盤不是自動駕駛系統(tǒng)。3. 核心實現(xiàn)與實操要點3.1 命令設(shè)計與交互流程context-mode 的命令不多一共就六個設(shè)計原則是“一個手勢做一件事”ctx init # 初始化當前目錄的項目上下文 ctx mark -t decision -m 內(nèi)容 # 手動記錄一條上下文-t 指定類型 ctx capture -m 完成用戶模塊重構(gòu) # 捕獲當前工作區(qū)狀態(tài)自動帶上改動文件列表 ctx resume # 生成本次會話所需的初始 prompt ctx use --project name # 切換項目上下文 ctx export --format prompt | head -n 100 # 導(dǎo)出上下文方便手動粘貼capture是最常用的命令。它的執(zhí)行流程是先跑git status拿到改動文件列表再讀取最近 5 條熱層條目加上用戶傳入的描述合并成一條新的上下文條目存入熱層同時把超過 3 天的溫層條目壓縮進 summary 字段。我刻意沒有做“自動在 AI 會話結(jié)束后抓取內(nèi)容”的功能因為終端里的 AI 會話和 shell 之間沒有干凈的截斷點自動抓取的邊界判斷很難做。后來用了一個折中方案在 shell 提示符里掛了一個 hook檢測到 AI 編碼助手的進程退出時提示你“是否記錄本次會話要點”把決定權(quán)留給人。3.2 摘要壓縮與 Token 預(yù)算控制摘要壓縮是整個工具里最值得講的部分。我實驗了三種方式規(guī)則截斷、小模型摘要、大模型摘要最終采用的是“分層混合”策略。先說 token 預(yù)算怎么算。我用的估算公式很簡單中英文混排時token 數(shù) ≈ 字符數(shù) / 1.8純英文時≈ 字符數(shù) / 3.5。雖然不精確但足夠做預(yù)算控制。我給自己定的導(dǎo)出上限是 4500 token其中熱層 1500、溫層 2500、summary 500。超出預(yù)算時工具會先壓縮溫層里最老的條目把 5 條舊摘要合并成 1 條新摘要再把原文下沉到冷層。壓縮策略分兩級。第一級是在本地用規(guī)則做按decision、todo、bugfix三種類型分別提取關(guān)鍵句這種“類型感知壓縮”能去掉 40% 的冗余。第二級是調(diào)用大模型接口做語義壓縮輸入是待壓縮的原始條目輸出要求是“保留所有事實性信息、去掉語氣詞和過程描述、控制在 150 字以內(nèi)”。實測下來兩級壓縮后信息保留率在 85% 以上但體積縮小了約 60%。壓縮的核心代碼邏輯如下def compress_entries(entries, llm_fn): texts [e[content] f類型{e[type]} for e in entries] prompt ( 將以下代碼開發(fā)記錄壓縮為一段不超過200字的摘要。 必須保留具體技術(shù)方案、文件名或接口名、已完成/未完成狀態(tài)。 去掉過程描述、語氣詞、無關(guān)細節(jié)。\n\n \n.join(texts) ) return llm_fn(prompt)這里我踩過一個坑壓縮 prompt 里如果不強調(diào)“保留接口名和文件名”摘要經(jīng)常會把關(guān)鍵的技術(shù)名詞吞掉生成“優(yōu)化了相關(guān)模塊”這種正確但沒用的廢話。所以后來我在 prompt 里明確列出了三類必須保留的信息效果立竿見影。3.3 上下文恢復(fù)把存儲變成高質(zhì)量 Promptresume命令做的事情聽起來簡單——把摘要和熱層條目拼起來——但這里的細節(jié)決定了 AI 助手能不能真正用上這些信息。我通過大量對比實驗確定了導(dǎo)出模板的順序# 項目alpha ## 當前狀態(tài) summary 字段內(nèi)容 ## 正在進行 熱層中 typetodo 的條目 ## 近期關(guān)鍵決策 熱層中 typedecision 的條目 ## 最近改動的文件 capture 時記錄的 git status 文件列表 請基于以上信息繼續(xù)協(xié)助開發(fā)。注意所有決策為既定約束如需調(diào)整請先說明理由。最后一句“如需調(diào)整請先說明理由”很關(guān)鍵。加了它之后AI 助手不再動不動就推翻之前的方案而是先確認再動手。這本質(zhì)上是一種 prompt 工程技巧但放在工具里實現(xiàn)就能讓每個團隊成員都享受到不需要每個人自己寫這套話術(shù)。3.4 項目隔離與目錄切換實現(xiàn)項目隔離的實現(xiàn)在早期版本里很簡單以.context-mode/project.json區(qū)分。但用了一段時間發(fā)現(xiàn)一個問題同一個項目在不同機器上克隆時目錄名可能不一樣導(dǎo)致上下文文件對不上。后來我改成“目錄哈希 項目名”雙索引~/.context-mode/projects.json保存了一個映射表把項目名映射到“最近訪問的工作目錄哈希列表”。執(zhí)行ctx use --project alpha時工具先查映射表找到工作目錄再讀取對應(yīng)上下文。如果工作目錄不存在就提示用戶重新指定路徑并更新索引這樣換機器時只需拷貝整個.context-mode目錄即可。這個改動還順帶解決了一個多開問題同一臺機器上同時開著 alpha 和 beta 兩個項目目錄shell 提示符會根據(jù)當前目錄自動匹配上下文不會串。4. 實操過程三個真實場景完整演示4.1 場景一跨天續(xù)接重構(gòu)任務(wù)某次給內(nèi)部系統(tǒng)做用戶模塊重構(gòu)第一天晚上改到一半卡在訂單狀態(tài)機的并發(fā)問題上我記錄了上下文后下班。第二天回來的操作流程是這樣的# 進入項目目錄 cd ~/work/alpha # 恢復(fù)上下文 ctx resume /tmp/ctx.md # 把 /tmp/ctx.md 內(nèi)容粘貼給 AI 編碼助手作為初始輸入恢復(fù)出來的 prompt 里清楚地寫著“重構(gòu)完成 70%”“剩余阻塞項訂單超時狀態(tài)機缺少重試分支”“關(guān)鍵決策統(tǒng)一走 gateway 接口”。AI 助手拿到這些信息后第一句話就問“需要我一起分析重試分支的冪等性嗎”直接進入了問題本身而不是先問“你的項目是做什么的”。這個場景里最值錢的不是省了幾分鐘而是沒有丟失“設(shè)計約束”。如果沒有 context-mode第二天開啟新會話時我大概率會忘記“統(tǒng)一走 gateway”這條約束AI 助手可能會給出繞過 gateway 的方案那才是真正的災(zāi)難。4.2 場景二雙項目并行切換我平時同時維護一個數(shù)據(jù)中臺和一個前端組件庫。以前切換項目時經(jīng)常把中臺的代碼規(guī)范帶到前端項目里AI 助手給出的組件代碼風(fēng)格和后端項目完全不是一個體系。用了 context-mode 之后每個項目獨立維護上下文切換前執(zhí)行ctx mark -t decision -m 前端組件庫樣式方案定為 CSS Variables不引入預(yù)處理器 ctx use --project ui-lib由于兩個項目存在不同的.context-mode文件里導(dǎo)出的 prompt 各自帶著自己項目的技術(shù)棧約定AI 助手很少再串風(fēng)格。這里有個小技巧在 shell 的cdhook 里調(diào)用ctx use --by-dir目錄切到哪兒上下文就自動切到哪兒連手動執(zhí)行use都省了。4.3 場景三團隊上下文交接給團隊里兩個同學(xué)交接一個進行中的項目時我直接執(zhí)行ctx export --format prompt把生成的上下文文檔發(fā)給他們。他們在自己的機器上執(zhí)行ctx import --file context.json整個項目的背景、進度、坑位、約束一下子全過去了。這個場景比想象的更常用。以前交接項目靠寫文檔但文檔寫不到“昨天剛發(fā)現(xiàn)某個 SDK 的返回值是錯誤類型”這種粒度。上下文工具提供的是一個“活文檔”粒度細到具體的 bug、具體的決策而且每個條目都帶時間戳可以追溯。交接的實操細節(jié)是導(dǎo)出前先跑一次ctx capture -m 交接前快照確保所有最新的改動文件列表被記錄進去。另外交接方導(dǎo)入后要核對 summary 字段是否完整尤其是技術(shù)棧部分因為新成員對項目沒有背景認知summary 里的一句“技術(shù)棧后端 Go PostgreSQL”能省掉很多基礎(chǔ)問答。4.4 關(guān)鍵參數(shù)的選擇依據(jù)工具里有幾個參數(shù)是我經(jīng)過多輪調(diào)整定下來的這里記錄一下決策過程方便你按自己的需求改導(dǎo)出上限 4500 token對應(yīng)主流模型在保證回復(fù)質(zhì)量時比較舒服的輸入長度。超過這個值模型容易忽略后面的內(nèi)容回復(fù)質(zhì)量明顯下降。如果只用長上下文模型可以把warm_tokens從 2500 調(diào)到 4000。溫層保留 3 天這是我觀察自己工作節(jié)奏得出的結(jié)論。超過 3 天的內(nèi)容基本屬于“已完成且不再活躍”的狀態(tài)適合壓縮。如果是長周期項目建議改成 7 天配合每日自動 capture 使用。熱層最多 5 條熱層條目大多比較長超過 5 條就超過了 1500 token 預(yù)算。當?shù)?6 條進來時工具會自動把最早的 1 條降級到溫層并觸發(fā)一次局部壓縮。這些參數(shù)我全部放在了配置文件~/.context-mode/config.yaml里沒有寫死在代碼中。參數(shù)化的好處是不同團隊、不同項目規(guī)模對上下文長度的需求差異很大寧可多暴露幾個配置項也不能讓你為了改參數(shù)去動源碼。5. 常見問題與排查技巧實錄5.1 上下文串擾A 項目的上下文混入 B 項目這是使用頻率最高的反饋之一。排查下來大部分原因不是工具 bug而是目錄映射沒有對上。比如從~/work/alpha通過軟鏈接訪問~/code/alpha-linkpwd顯示的路徑不同工具匹配不到同一個項目就新開了一個上下文。解決辦法在projects.json里把同一個項目的多個目錄路徑記錄到一個 bucket 里匹配時只要命中任一路徑就視為同一項目。另外要檢查是否有子目錄嵌套的情況比如~/work/alpha/frontend是另一個項目的前端倉庫這種嵌套結(jié)構(gòu)容易讓工具誤認為是同一項目。5.2 摘要質(zhì)量劣化關(guān)鍵信息被壓縮丟失壓縮后的摘要會慢慢丟失細節(jié)這個問題在項目進行到中期特別明顯。我發(fā)現(xiàn)典型表現(xiàn)是摘要里只有“完成支付流程優(yōu)化”但“用消息隊列替代同步調(diào)用”這個關(guān)鍵決策被弄丟了。這個決策恰恰是后續(xù)排查性能問題時最需要的線索。針對這個問題我做了兩個改進。第一在壓縮 prompt 里明確要求“必須以列表形式保留所有涉及的具體技術(shù)名詞、文件路徑和接口名”壓縮質(zhì)量明顯提升。第二在冷層保留完整原文只要摘要質(zhì)量下降可以執(zhí)行ctx trace --keyword 消息隊列從冷層找回原文。實際排查時冷層索引的價值比想象中大得多。5.3 存儲膨脹與啟動變慢跑了三個月后某個項目的 JSON 文件漲到了 30MB每次執(zhí)行命令都要等一兩秒。原因也是我一開始沒預(yù)料到的capture命令里“自動記錄 git 改動文件列表”會把每次抓到的文件路徑全部存下來反復(fù)改一個文件會生成幾十條幾乎一樣的記錄。解法是加了一個“相似合并”邏輯如果新條目的類型和內(nèi)容與熱層最近一條的相似度超過 90%就把時間戳更新到新條目而不是新增一條。實現(xiàn)上我用的是簡單的文本相似度計算沒引入復(fù)雜的算法效果已經(jīng)足夠。另外每個月執(zhí)行一次ctx gc把冷層里超過 90 天且從未被回溯的條目歸檔到獨立路徑。5.4 避坑清單速查坑位現(xiàn)象解決方案軟鏈接目錄導(dǎo)致上下文隔離同一項目出現(xiàn)兩份上下文為項目綁定多個目錄路徑壓縮丟掉具體技術(shù)名詞摘要只剩泛泛描述prompt 里強制保留名詞列表反復(fù)修改同一文件產(chǎn)生冗余條目存儲膨脹文本相似度合并resume 后 AI 仍然跑偏決策約束未被識別在導(dǎo)出模板里把 decision 條目放前面并加“既定約束”前綴團隊交接時背景缺失新成員看不懂摘要capture 里強制記錄技術(shù)棧和架構(gòu)約定另一個我反復(fù)強調(diào)的經(jīng)驗上下文工具體系要盡量保持輕量不要塞太多自動化。我試過給工具加“自動摘要每日會話”功能跑了不到兩周就關(guān)掉了——自動生成的低質(zhì)量摘要反而污染了溫層導(dǎo)致真正需要時找不到準確信息?，F(xiàn)在這個功能變成了“晚 6 點提示是否生成今日摘要”把決策權(quán)交回給人。6. 擴展方向與個人體會context-mode 目前還只是單機工具但它的數(shù)據(jù)結(jié)構(gòu)設(shè)計為后續(xù)擴展留了很大空間。我比較看好的幾個方向一是把上下文數(shù)據(jù)接進 AI 助手的 system prompt 模板體系做成插件讓助手天然感知項目狀態(tài)二是做團隊共享后端把上下文存入 Git 倉庫或內(nèi)部服務(wù)這樣跨人交接會更順滑三是接入更多工作流事件源比如 CI 失敗、測試用例變更自動在上下文里標記狀態(tài)變化。在實現(xiàn)這個工具的整個過程中我最大的體會是上下文管理本質(zhì)上不是技術(shù)問題而是習(xí)慣問題。工具能幫你把記憶結(jié)構(gòu)化地保存下來但如果你不在關(guān)鍵時刻按下快門再好的存儲也沒有用。每次方向調(diào)整、每個關(guān)鍵決策產(chǎn)生時花 10 秒鐘執(zhí)行一條ctx mark這個習(xí)慣比工具本身更值錢。如果你也在被“AI 失憶”困擾建議先別急著照抄我的實現(xiàn)明確你自己最常丟的是哪種上下文再做一個最小版本跑兩周讓真實工作流幫你迭代出適合自己的模式。