我最近在帶一個 AI 輔助編程的項目代碼倉庫越來越大開發(fā)新功能時模型頻繁答非所問要么漏掉關鍵約束要么把無關模塊的舊邏輯也帶進來。排查到最后問題不在模型本身而在輸入給模型的那塊“背景信息”上——上下文里塞了太多低價值內容真正重要的部分反而被稀釋了。后來我干脆自己寫了套上下文管理模式context-mode專門治理這個問題。這篇文章就把我做這套東西的完整思路、實現細節(jié)和踩坑過程記錄下來。說實話當下的開發(fā)工作流里AI 工具的上下文管理幾乎是個被所有人感知、但很少有人系統化解決的問題。很多人覺得“上下文不夠就多貼點”結果上下文越貼越亂模型的表現反而越來越差。context-mode 的核心不是“給更多”而是“給得準”——對上下文做結構化、打分排序、按需裁剪讓每一寸上下文窗口都花在刀刃上。這篇文章適合正在用 AI 編程助手、被上下文窗口限制折磨的開發(fā)者也適合想給自己的 AI 工具鏈搭一套上下文管理基礎設施的技術負責人。順便說一句這套機制完全和具體模型無關你用的是閉源 API 也好、本地開源模型也好思路都是一樣適用的。1. context-mode 要解決的問題上下文窗口不是越大越好1.1 一個具體崩潰場景先說我遇到的那個具體場景。項目里有一個支付模塊橫跨前端、網關、風控、回調通知四個子系統每個子系統都有一堆歷史文檔。當時要做的是一個“基于用戶歷史行為的風控策略調整”我按常規(guī)做法把相關代碼文件、需求文檔、接口定義全部塞給模型一次性貼了大概兩萬 token 的上下文。模型輸出確實能看懂需求但給出的方案里混入了大量舊版風控規(guī)則的描述還引用了已經被下線的一個“黑名單名單庫”接口——這個接口在當前代碼庫里根本不存在因為它三個月前就廢棄了。這事讓我意識到模型跑偏不大可能是參數問題而是我給它的上下文里同時包含了“正確的舊信息”和“已經過時但仍然存在的舊信息”模型沒有可靠依據來區(qū)分這兩者。再往深了說人類程序員在接手同樣任務時會自動做一件事把注意力聚焦在當前版本的關鍵路徑上忽略掉歷史遺留和無關模塊。但直接把整個倉庫丟給模型它做不到這種聚焦。所以 context-mode 的實現目標本質上就是把“人類程序員的上下文聚焦能力”用工程手段實現出來。1.2 根本矛盾信息量 vs 信號密度上下文管理的核心矛盾用一句話概括上下文窗口的確在變大但模型對長上下文的注意力會分散尤其是在中間位置的信息最容易丟。我把這個問題拆成兩個維度信息量上下文里到底包含了多少和當前任務相關的實體、約束、代碼位置。信號密度相關信息在全部上下文中的占比。大多數人的做法只提升了前者忽略后者。貼了十個文件進去只有兩個真正相關那信息量是上去了但信號密度下來了模型的選擇性注意力機制會讓它更關注開頭和結尾的內容中間的關鍵邏輯反而被當噪聲濾掉。context-mode 的思路就是反過來主動降低無效信息的絕對量把上下文里塞滿高密度信號寧可信息量略少也必須保證每條信息都精準命中當前任務。1.3 上下文管理的三個實際成本除了信號密度問題還有三個常常被忽略的成本第一是成本問題。按 token 計費的 API 服務上下文越長、單次請求就越貴。如果一個功能要反復迭代十輪每輪都帶三萬 token 的“行李”那這中間浪費的錢非?？捎^。第二是延遲。上下文越長prefill 階段的計算量越大首 token 返回時間基本線性增長。在實際交互場景里多等三秒和少等三秒體感差異極其明顯。第三是出錯風險。長上下文帶來的一個隱蔽問題是“慣性漂移”。模型會順著上下文里既有的寫法往下走哪怕這個寫法已經被標記為待廢棄。只要有舊代碼在上下文里模型就會傾向于產出和舊代碼風格一致的新代碼而不是采用你希望的新架構。前兩個還好說第三個問題幾乎只能靠控制上下文內容來解決。這也是我在很多內部討論里反復強調的別把上下文只當成“輸入”要把它當成“約束條件”。模型不是被問題塑造的而是被上下文塑造的。2. context-mode 的三層架構標簽過濾、優(yōu)先級排序、窗口回收2.1 第一層上下文標簽體系要做上下文管理第一步不是寫代碼而是建立一套描述上下文的標簽體系。我采用的標簽體系是沿著“內容類型 × 生命周期 × 權威層級”三個維度展開的。內容類型代碼文件、接口定義、依賴配置、需求描述、歷史決策記錄、測試用例、運行日志。 生命周期永久核心項目架構說明、全局規(guī)范、版本相關當前迭代的需求文檔、變更記錄、臨時相關本次任務臨時引入的報錯堆棧、一次性某個具體函數的局部實現。 權威層級強約束接口簽名、編譯錯誤、命令行規(guī)范、中約束業(yè)務規(guī)則描述、模塊邊界說明、弱約束歷史討論、個人偏好、非強制性建議。這個標簽體系直接決定了后續(xù)過濾和排序的效果。比如一個文件內容既有永久核心的架構描述又有臨時相關的報錯信息那它就應該被拆開處理而不是整體塞進上下文。實際落地時我給每個代碼倉庫維護了一份 context-manifest.json里面按模塊寫明哪些路徑屬于“核心穩(wěn)定層”、哪些屬于“版本活躍層”、哪些屬于“禁止自動帶入層”。這套文件是人工維護的但維護成本極低因為一個模塊的結構不會天天變真正經常變的只是版本活躍層里那幾句描述。2.2 第二層上下文優(yōu)先級打分有了標簽接下來就是對每條候選上下文做打分排序。我給每條候選內容算一個綜合分得分 內容類型權重 × 任務相關度系數 × 時效系數舉個簡單的例子用戶要調整支付回調邏輯候選內容有當前支付回調的接口實現文件相關度 1.0類型權重 0.9時效 0.9得分約 0.81三個月前的風控說明文檔相關度 0.6類型權重 0.5時效 0.3得分約 0.09全局架構 README相關度 0.4類型權重 0.8時效 1.0得分約 0.32。那最后進上下文的優(yōu)先級就是回調實現文件 架構 README 風控舊文檔。如果窗口不夠后兩項就得讓位。打分這塊其實不需要復雜的語義模型。我用的是關鍵詞命中加人工標注相結合的方式把任務描述拆成名詞實體和動詞動作兩類然后到候選內容里做加權匹配。命中名詞實體的權重高命中動詞動作的權重稍低兩邊都命中的內容分最高。這套規(guī)則簡單粗暴但實際效果比某些復雜向量檢索穩(wěn)定得多因為項目上下文里的大量術語是高度定制化的向量模型不一定能處理好。2.3 第三層上下文窗口的滾動回收前兩層解決的是“選什么進上下文”第三層解決的是“上下文滿了怎么辦”。我設置了一個硬頂比如 8K token 的窗口上限每當要加入新內容時先檢查當前總量超了就按得分從低到高淘汰直到塞得下新內容。這個過程我做了兩個補充約束強約束內容永不淘汰接口簽名、錯誤信息這類高權威內容一旦進入上下文再低分也不踢出去。剛加入的內容有短暫保護期新內容加入后 2 輪對話內不會被立即淘汰避免出現“剛說完就忘了”的情況。這個回收機制看起來簡單但它是整個 context-mode 的穩(wěn)定器。沒有它上下文管理就是一次性快照沒辦法應對長會話里的持續(xù)演進。3. 手把手實現 context-mode一套輕量級上下文管理服務3.1 環(huán)境與工具選型我實現這套系統的時候沒有引入重型框架核心就三個組件Python 3.10 寫服務端邏輯SQLite 存標簽配置和上下文操作日志一個基于 FastAPI 的本地 HTTP 服務統一對外提供上下文組裝接口。選這些不是因為它們最“先進”而是因為 context-mode 的核心價值不在框架而在策略。換句話說所有策略邏輯加起來也就幾百行代碼不需要為了它去上微服務那一套。如果后續(xù)要接更大的團隊需要多模接入那就再封裝一層適配器底層的策略邏輯不用動。工具選型這一步我給個明確建議先別碰那些專門做 context 編排的重型平臺因為它們的抽象層級太高出現問題很難定位到具體是哪條策略導致的。自己寫一個幾百行的服務你能看清楚每一次上下文組裝的前因后果這對調試來說太重要了。3.2 核心數據結構整個系統的核心數據模型就三張表context_items上下文條目、tags標簽定義、task_sessions任務會話。context_items 表的關鍵字段字段名用途item_id條目標識比如 file:///src/payment/callback.pycontent_preview內容預覽用于展示時判斷是否誤選item_typecode / doc / api / log / requirementlifecyclecore / versioned / temp / ephemeralauthoritystrong / medium / weakkeywords逗號分隔的關鍵詞列表last_updated最后更新時間用于時效系數計算task_sessions 表就簡單一點session_id、task_description、created_at、total_tokens_used。每次組裝上下文都往這個表里寫一條記錄方便事后復盤“為什么剛才那次會話帶了這些內容”。這里我特意強調了復盤能力因為在調試 prompt 效果時最怕的就是不知道模型看到了什么。有了 session 記錄每一次失敗都能回到當時的上下文去檢查定位問題的速度會快非常多。3.3 上下文組裝流程的實現組裝流程有四個步驟任務解析、候選召回、打分排序、窗口壓縮。第一步把用戶的任務描述拆成名詞實體和動詞動作。我用了一個很小的基于規(guī)則的分詞器內置了一個項目專屬名詞表比如“支付回調”“風控”“網關”“黑名單”……命中名詞表的詞會被單獨標記不參與通用分詞。第二步根據名詞實體和標簽體系召回候選。檢查每個候選條目的關鍵詞是否命中任務描述的名詞實體命中一個就能召回。這里的召回條件要放寬寧可多召回也不能漏掉關鍵項。第三步按前面說的公式打分排序。這一步包含時效系數的計算last_updated 距當前時間越近時效系數越高超過 90 天沒有更新的代碼文件時效系數會降到 0.3 以下。第四步做窗口壓縮。按得分從低到高淘汰直至總 token 數小于等于硬頂。但凡是強約束標記的內容直接跳過淘汰邏輯。這套流程跑起來之后我每次發(fā)起任務請求都走組裝接口拿到的上下文是動態(tài)生成的而不是手工拼貼的。3.4 代碼實現示例這里給一個簡化版的核心代碼幫助理解整個流程。完整版涉及項目內部結構比較多就不貼了只看骨架。# context_mode/assembler.py # 簡化版上下文組裝流程 from dataclasses import dataclass dataclass class ContextItem: item_id: str item_type: str lifecycle: str authority: str keywords: list last_updated: float content: str token_size: int def assemble_context(task_desc, items, hard_limit8000): # 1. 任務解析通過關鍵詞匹配得到一組候選 entities extract_entities(task_desc) # [支付回調, 風控策略] candidates [item for item in items if is_hit(item, entities)] # 2. 打分排序 for item in candidates: item.score score_item(item, entities) candidates.sort(keylambda x: x.score, reverseTrue) # 3. 窗口壓縮強約束內容不淘汰 selected [] total_tokens 0 for item in candidates: if total_tokens item.token_size hard_limit and item.authority ! strong: continue selected.append(item) total_tokens item.token_size if total_tokens hard_limit: break return selected def extract_entities(task_desc: str) - list: # 用預置名詞表做提取示例略 return [支付回調, 風控策略]在跑通這套基礎流程之后你會發(fā)現一個很自然的需求上下文組裝不能只是靜態(tài)快照它必須是一個持續(xù)演進的過程。所以我又加了一個增量刷新機制每一輪對話結束后會根據用戶的新輸入重新運行組裝流程把新出現的實體納入召回范圍再把已經失去價值的舊條目淘汰掉。3.5 與 LLM API 的對接方式組裝好的上下文怎么傳給模型我用的是 Prompt 模板預填充的方式。具體來說FastAPI 服務返回的不是字符串而是一條組裝好的消息列表。最前面是 system 指令說明“以下內容是 context-mode 根據當前任務篩選出的項目背景資料回答時以其中強約束條目為優(yōu)先級”。然后按順序附上選中的上下文條目每個條目前面加一行元信息標記它的標簽和權重比如[code][core][strong] file:///src/payment/callback.py模型通過這行標記能快速判斷后面內容的權威性和時效性從而更合理地分配注意力。實際效果是加了元信息標記之后模型對強約束內容的遵守率明顯提升這個在后面實測數據里會展示。4. 實測效果開啟 context-mode 前后的直觀對比4.1 測試場景設計為了量化 context-mode 的提升效果我做了三組測試任務任務 A在支付回調模塊中增加一個新的冪等校驗邏輯任務 B重構風控策略查詢邏輯從同步查詢改為異步批量上報任務 C排查一個偶發(fā)的回調超時問題。每個任務都跑兩輪一輪用“全量手工貼上下文”的傳統方式一輪用 context-mode 組裝后的精簡上下文。為了避免隨機性每個任務跑三次取效果中位數。衡量指標我選了三個首輪答案可運行率不報錯、不引用過期接口最終生成代碼需要的人工修正行數每輪交互平均耗時從發(fā)送請求到拿到首個 token。4.2 數值對比三組任務跑完的數據如下任務傳統方式可運行率context-mode 可運行率傳統方式修正行數context-mode 修正行數傳統方式平均延遲context-mode 平均延遲任務 A33%89%37 行11 行5.8s2.1s任務 B44%78%52 行19 行6.7s2.5s任務 C67%100%59 行8 行7.2s2.2s數據說明兩個直觀結論第一首輪答案質量提升非常明顯尤其是任務 C幾乎沒有再出現引用過期接口的問題第二延遲下降幅度很大直接原因就是從大約兩萬 token 的上下文降到了四千到五千 token。真正讓我意外的還不是這些正向指標而是任務 B 的修正行數沒有低于預期深入看原因后發(fā)現問題出在異步改造涉及到的模塊范圍比預估的大context-mode 召回的上下文里缺少了一個上游服務的數據結構說明。后來在標簽配置里補上了該條目的關鍵詞這個缺口就消失了。這說明 context-mode 不是純自動系統它的效果很大程度依賴初始標簽配置的完整度。4.3 信號密度提升的量化把上面那次測試的上下文體積做統計傳統方式平均每次請求的上下文 token 數是 18400context-mode 降到 4600。為什么降幅這么明顯核心在于標簽過濾的結果是把整個目錄全部剔除只留真正命中的文件。那些“順手”貼進來的無關文檔在傳統方式里占了幾乎一半的 token 量現在被完全清掉了。信號密度方面我統計了上下文里與任務直接相關的句子占全文的比例傳統方式大概是 12%context-mode 提升到 47%。這個數字非常直觀地解釋了模型表現提升的來源——它對相關信息看得更清楚了。5. 實測中的三個大坑和對應解法5.1 坑一語義相關但關鍵詞不命中的條目被誤殺第一次跑測試時就發(fā)現了這個問題。任務描述是“回調超時如何排查”但真正涉及超時監(jiān)控的模塊文件關鍵詞只有一句話沒有直接出現“回調”這個詞導致召回階段被漏掉。解法是給 keywords 字段加“同義擴展”配置。我在項目里手工維護了一張同義詞表比如“超時”對應“timeout、延遲、慢請求、上游阻塞”召回時先做同義詞展開再做匹配。后續(xù)又加了基于源碼注釋的自動關鍵詞提取凡是文檔標注過“依賴”“關聯”關系的都會補充到雙方條目的 keywords 里。這個坑給到的教訓是上下文管理的召回環(huán)節(jié)寧可寬不可窄。漏招的代價比多招更大因為少一條關鍵上下文模型可能直接方向性錯誤而多招一條頂多占點 token。5.2 坑二內容類型權重設計過細反而打架最初我給內容類型權重設計了十個檔位比如“接口定義 0.9、代碼實現 0.8、測試用例 0.6、運行日志 0.5……”結果發(fā)現這帶來一個很奇怪的現象排查類任務召回的日志內容被大量淘汰因為日志的權重太低每條得分都拼不過代碼文件。后來我把十檔壓縮成四檔0.9接口和強約束、0.75代碼和架構、0.5需求和測試、0.35日志和臨時記錄。同時加了一個任務類型修正系數如果判斷任務描述偏向排查診斷日志內容的權重自動乘以 1.5。這個改動告訴我的道理很樸素權重設計的核心不是精細而是讓模型和策略都有一致的行為預期。十個檔位之間差別太小排序穩(wěn)定性反而差。5.3 坑三強約束內容永不淘汰導致上下文僵化強約束內容永不淘汰的設計起初是為了保證模型不會丟掉接口約定但實際跑下來發(fā)現一個問題如果一場對話涉及的強約束條目太多比如要同時改三個子系統的接口強約束內容可能會累加到一萬多 token擠占掉其他中約束內容的空間而某些中約束的上下文在當前步驟里其實更重要。現在我把“永不淘汰”改成了“核心槽位機制”。就是把強約束內容分成三個槽位全局強約束比如構建命令、語言版本任何時候都保留任務相關的強約束按相關性排序最多保留五個超出槽位的強約束降級為中約束參與整體排序。這個調整相當于給強約束內容設了一個“上線”保證它們不會被極端場景下的過多數目反噬。修正后重新跑了任務 B修正行數從 19 行降到了 13 行雖然不如任務 A 那么驚艷但趨勢是對的。6. context-mode 的擴展方向從編程輔助到跨場景復用6.1 應用在文檔問答場景的改造思路做完編程場景下的驗證之后我順手把 context-mode 用到了一個內部知識庫問答機器人上。底層的標簽過濾邏輯完全不用改只是把內容類型換成了制度文檔、流程手冊、歷史工單、FAQ。打分排序邏輯也沿用只是把“時效系數”換成了“版本有效系數”。實際體驗下來問答機器人關于新流程的準確率明顯上升。這讓我確認了一件事context-mode 本質上不是“AI 編程助手專用工具”而是一種通用的上下文治理方法論——只要你的場景是“從大量信息中提取少量高價值內容交給模型”這套三層架構就都適用。6.2 與 RAG 檢索增強生成的組合玩法很多人會問context-mode 和 RAG 有什么關系是不是重復了我認為它們是互補關系。RAG 解決的是“在超大知識庫里檢索出若干文檔片段”的問題而 context-mode 解決的是“在檢索回的大量片段之間做優(yōu)先級整合”的問題。實際使用時RAG 召回結果作為 context-mode 的候選集再由 context-mode 按標簽體系和任務相關度做二次篩選排序效果是 112 的。我在一個內部項目里試過這種組合把候選文檔從二十份壓到五份問答準確率和回答速度都得到了保證。這個方向我認為值得大家在自己的應用里探索并不復雜只是多了一層策略函數。6.3 后續(xù)想做的自動標簽推薦現在的 context-mode 最需要人工維護的部分是 manifest 配置也就是標注入口。我在想兩個自動化的方向基于 AST 解析的代碼依賴關系自動生成模塊關鍵詞基于歷史任務會話的上下文選擇日志自動學習哪些類型的文件經常被同時選中進而調整標簽權重。這其實就帶點個性化了每條項目在實踐里形成的“上下文操作習慣”會被系統保存下來讓 context-mode 越來越貼合團隊自己真實的開發(fā)套路。我準備在下一個版本里加上這兩個功能試試水看看能不能把人工維護成本再降一個檔次。最后分享一個實際操作中的小經驗context-mode 這套東西剛落地時很長一段時間只在你一個人手工調用時會配置得很準因為你會下意識把該打的標簽打上。但一旦團隊其他人開始用你就得把“標簽配置評審”當成日常工作中一環(huán)每周過一遍近兩周的新增文件把沒打標的補上。第一次漏配標簽的教訓可能是一小時的返工但定期維護配置的習慣能幫你省下的是所有人每周都會遇到的十幾分鐘低效拉扯。