大佬深度解析：Coding Agent的底層運行邏輯是什么？

編譯 | 澤南

本文作者 Sebastian Raschka 是 AI 領域的知名學者，曾任威斯康星大學麥迪遜分校的統計學教授。

在本文中，我將探討編碼智能體（coding agents）及其智能體編排（agent harnesses）的整體設計：它們究竟是什么、工作原理如何，以及在實際應用中各組件是如何協同運作的。

廣泛地講，智能體之所以成為一個備受關注的重要議題，是因為近期實用型大語言模型（LLM）系統所取得的諸多進展，不僅僅歸功于模型本身的性能提升，更在于我們如何去運用這些模型。在許多實際應用場景中，智能體周邊的支撐系統 —— 例如工具調用、上下文管理及記憶機制 —— 所發揮的作用，其重要性絲毫不亞于模型本身。這也解釋了為何像 Claude Code 或 Codex 這類系統，往往給人的感覺要比單純在普通聊天界面中使用的同款基礎模型顯得更為強大、更具能力。

在本文中，我將詳細闡述構成編碼智能體的六大核心構建模塊。

Claude Code、Codex CLI 及其他編程智能體

如果你是開發者的話，你可能已經很熟悉 Claude Code 或 Codex CLI 了，但為了鋪墊背景，不妨先說明一下：它們本質上屬于「智能體式」編程工具，通過在應用層 —— 即所謂的「智能體編排」（agentic harness）—— 中對大型語言模型（LLM）進行封裝，從而使編程任務變得更加便捷且高效。

圖 1：Claude Code CLI、Codex CLI 和我自建的代碼智能體。

編程智能體（Coding agents）專為軟件開發工作而設計；在這一領域，關鍵要素不僅在于模型的選擇，更在于其周邊的系統架構 —— 包括代碼倉庫的上下文環境、工具的設計、提示緩存的穩定性、記憶機制以及長會話的連續性。

這種區分至關重要，因為當我們探討大型語言模型（LLM）的編程能力時，人們往往會將模型本身、其推理行為以及作為產品的智能體混為一談。不過，在深入探討編程智能體的具體細節之前，請允許我先簡要補充一些背景信息，闡明「大型語言模型」、「推理模型」和「智能體」這三個更宏觀概念之間的區別。

大模型、推理模型與智能體的關系

大型語言模型（LLM）本質上是一種核心的「預測下一個 token」的模型。而「推理模型」雖然仍屬于 LLM 的范疇，但通常經過了專門的訓練和 / 或提示工程優化，使其在推理過程中投入更多的計算資源，用于執行中間步驟的邏輯推理、結果驗證，或在候選答案集合中進行搜索。

智能體（Agent）則是一個構建在模型之上的抽象層，可以將其理解為圍繞核心模型運作的一個「控制回路」。通常情況下，當接收到一個既定目標后，智能體層（或稱「編排框架」）會負責決策下一步需要檢查哪些信息、應當調用哪些工具、如何更新自身的狀態，以及何時終止任務等一系列操作。

粗略地講，我們可以用這樣一個類比來理解它們之間的關系：LLM 相當于引擎，推理模型則相當于經過強化的引擎（性能更強，但運行成本也更高），而智能體編排框架則扮演著輔助我們操控這一引擎的角色。盡管這個類比并不完美 —— 畢竟我們也可以將常規 LLM 和推理型 LLM 作為獨立的模型直接使用（例如在聊天界面或 Python 交互會話中）—— 但我希望它能有效地傳達出其中的核心要義。

圖 2：傳統大語言模型（LLM）、推理型大語言模型（或推理模型），以及封裝在智能體編排框架中的大語言模型之間的關系。

換句話說，智能體就是一個在特定環境中反復調用模型的系統。

因此，簡而言之，我們可以將其歸納如下：

• 大型語言模型：原始模型。
• 推理模型：一種經過優化的 LLM，旨在輸出中間推理過程（痕跡），并具備更強的自我驗證能力。
• 智能體：一個循環執行的實體，它結合使用了模型、工具、記憶模塊以及環境反饋。
• 智能體編排框架（Agent Harness）：圍繞智能體構建的軟件支架，負責管理上下文、工具調用、提示詞、狀態以及控制流。
• 代碼編排框架（Coding Harness）：智能體框架的一種特例；即專用于軟件工程任務的框架，負責管理代碼上下文、工具、代碼執行以及迭代反饋。

如上所述，在智能體和編碼工具的語境下，我們還會遇到兩個流行術語：智能體編排框架和（智能體驅動的）代碼編排框架。后者是圍繞模型構建的軟件支架，旨在輔助模型高效地編寫和編輯代碼。而智能體編排框架的范疇則更為廣泛，并不局限于代碼領域（例如，可以參考 OpenClaw 項目）。Codex 和 Claude Code 均可被視為代碼編排框架的實例。

總之，更優秀的大模型能為推理模型（通常需要經過額外的訓練）奠定更堅實的基礎；而智能體框架則能進一步挖掘并充分發揮該推理模型的潛能。

誠然，LLM 和推理模型本身也具備獨立解決編碼任務的能力（即無需借助編排框架輔助）；但實際上，編碼工作遠不止是單純的「下一個 token 生成」（Next-token generation）。編碼工作很大程度上還涉及代碼倉庫導航、搜索、函數查找、代碼差異應用（Diff）、測試執行、錯誤排查，以及在整個過程中維持所有相關信息的上下文連貫性。

程序員們想必深知這是一項極耗心力的腦力勞動 —— 這也正是我們在專心編碼時最不愿被打擾的原因所在 :））

圖 3。一個編碼編排框架由三個層級構成：模型族、智能體循環以及運行時支持。其中，模型充當「引擎」；智能體循環驅動迭代式的問題求解過程；而運行時支持則提供底層的「管道」基礎設施。在循環內部，「觀察」環節從環境中收集信息；「審視」環節對這些信息進行分析；「決策」環節選定下一步行動；最后由「執行」環節付諸實施。

這里的關鍵要點在于，一套優秀的「編碼輔助框架」能讓具備推理能力和不具備推理能力的模型，在實際表現上顯得比單純置于普通聊天框中強大得多 —— 因為它有助于處理上下文管理等一系列關鍵任務。

編碼輔助編排框架

正如上一節所提到的，當我們提及「輔助編排框架」（Harness）時，通常是指圍繞在模型外部的那一層軟件層。這一層負責組裝提示詞（Prompts）、調用外部工具、追蹤文件狀態、應用代碼修改、執行終端命令、管理權限、緩存穩定前綴、存儲記憶信息，以及處理更多其他任務。

如今，在使用大模型時，相比于直接向模型輸入提示詞，或是使用簡單的網頁聊天界面（后者更接近于「上傳文件后進行對話」的模式），正是這一層輔助框架塑造了用戶體驗的絕大部分。

在我看來，當前各類大模型的「原生版本」在能力上已趨于同質化（例如，GPT-5.4、Opus 4.6 和 GLM-5 等模型的原生版本之間），因此，這套輔助框架往往就成了決定某款大模型表現優于另一款的關鍵差異化因素。

這純屬推測，但我猜想：如果我們把當前最新、能力最強的開源權重大型語言模型之一（例如 GLM-5）置入一套類似的輔助框架之中，它的表現很可能就能與 Codex 環境下的 GPT-5.4，或是 Claude Code 環境下的 Claude Opus 4.6 達到同一水平。話雖如此，針對特定的輔助框架進行一些「后訓練」通常還是有益的。舉例來說，OpenAI 歷史上就曾針對 GPT-5.3 模型維護過兩個不同的變體版本：GPT-5.3 和 GPT-5.3-Codex。

在下一節中，我將深入探討具體細節，并以我開發的「Mini Coding Agent」項目為例（GitHub 鏈接：https://github.com/rasbt/mini-coding-agent），來詳細解析一套編碼輔助框架的核心組成部分。

圖 4：編碼智能體 / 編碼編排框架的主要特性，將在后續章節中討論。

順便一提，為了行文簡潔，本文中「編碼智能體」和「編碼編排框架」這兩個術語有時會互換使用。（嚴格來說，智能體是模型驅動的決策循環，而框架是提供上下文、工具和執行支持的外部軟件框架。）

圖 5：一個極簡但功能完備、從零構建的「迷你編程智能體」（純 Python 實現）。

言歸正傳，下方列出了編程智能體的六大核心組件。你可以查閱我所構建的那個極簡但功能完備、從零構建的「迷你編程智能體」（純 Python 實現）的源代碼，以獲取更具體的代碼示例。在該代碼中，我已通過注釋對下文將要探討的這六大組件進行了標注

################################## Six Agent Components ################################### 1) Live Repo Context -> WorkspaceContext# 2) Prompt Shape And Cache Reuse -> build_prefix, memory_text, prompt# 3) Structured Tools, Validation, And Permissions -> build_tools, run_tool, validate_tool, approve, parse, path, tool_*# 4) Context Reduction And Output Management -> clip, history_text# 5) Transcripts, Memory, And Resumption -> SessionStore, record, note_tool, ask, reset# 6) Delegation And Bounded Subagents -> tool_delegate

1、實時代碼庫上下文

這或許是最顯而易見的組件，但同時也是至關重要的組件之一。

當用戶發出「修復測試」或「實現 xyz 功能」之類的指令時，模型應當能夠識別當前是否處于 Git 代碼庫環境中，正處于哪條分支上，哪些項目文檔可能包含相關指引，諸如此類。

之所以如此，是因為這些細節往往會改變或影響模型應采取的正確行動。例如，「修復測試」這一指令本身并非一條自足的指令。如果智能體能夠查閱諸如 AGENTS.md 或項目 README 之類的文檔，它便能獲知應當執行哪條測試命令等具體信息。若能知曉代碼庫的根目錄位置及整體布局，它便能直奔目標位置進行查找，而非盲目猜測。

此外，Git 分支信息、當前狀態及提交記錄等數據，也能提供更為豐富的上下文信息，幫助智能體了解當前正在進行哪些變更，以及應當將工作重心聚焦于何處。

圖 6：智能體運行框架首先構建一份簡要的「工作區摘要」，隨后將其與用戶請求合并，以此為項目提供額外的上下文信息。

核心要點在于：該編程代理在著手執行任何任務之前，會預先收集相關信息（即作為工作區摘要的「穩定事實」）；這樣一來，它就不必在處理每一個提示詞（Prompt）時都從零開始，陷入缺乏上下文的窘境。

2、提示詞結構與緩存復用

一旦智能體獲得了代碼倉庫的概覽視圖，接下來的問題便是：如何將這些信息有效地輸入給語言模型？上一幅圖中展示了這一過程的簡化視圖（即「組合提示詞：前綴 + 請求」）；但在實際操作中，若針對用戶的每一次查詢都重新合并并處理一遍工作區摘要，將是相對低效且浪費資源的做法。

換言之，編程會話往往具有重復性，且智能體所遵循的規則通常保持不變。各類工具的功能描述通常也維持原樣。甚至連工作區摘要的內容，通常也（在很大程度上）保持穩定。真正發生變化的主要因素，通常僅限于最新的用戶請求、近期的交互對話記錄，以及可能涉及的短期記憶信息。

如圖下方所示，「智能」運行時環境并不會在每一個交互回合中，都將所有信息重新打包成一個龐大且未作區分的整體提示詞。

圖 7：智能體編排框架構建一個「穩定提示前綴」，隨后加入不斷變化的會話狀態，并將合并后的完整提示輸入給模型。

與第 1 節的主要區別在于：第 1 節側重于收集代碼倉庫的相關事實信息；而在本節中，我們的重點是如何高效地封裝并緩存這些事實，以便在后續對模型進行反復調用時加以復用。

所謂「穩定提示前綴」中的「穩定」，意指其中包含的信息變動極小。它通常涵蓋了通用指令、工具描述以及工作空間的概覽信息。如果其中未發生任何實質性變化，我們便不希望在每一次交互過程中都耗費計算資源將其從頭重建。

而其他組件的更新頻率則要高得多（通常是每一輪交互更新一次）。這些組件包括短期記憶、近期的對話記錄以及最新的用戶請求。

簡而言之，針對「穩定提示前綴」所實施的緩存機制，其核心理念就在于：通過智能的運行時環境，盡可能地對這部分內容進行復用。

3、工具訪問與使用

工具訪問與使用環節讓交互體驗從聊天逐漸轉變為智能體。

普通模型可以生成文字形式的命令建議，但編碼框架中的大模型應該執行更精準、更有用的任務，并能夠實際執行命令并獲取結果（而不是讓我們手動調用命令并將結果粘貼回聊天窗口）。

但編排框架通常不會讓模型隨意生成語法，而是提供一個預定義的、包含明確輸入和邊界的可用工具列表。（當然，像 Python 的 subprocess.call 這樣的工具也可以包含在內，這樣智能體就可以執行任意范圍的 shell 命令。）

工具使用流程如下圖所示。

圖 8：模型發出一個結構化操作，框架對其進行驗證，并可選擇性地請求批準，然后執行該操作，并將有界結果反饋回循環。

為了說明這一點，以下示例展示了用戶使用迷你編碼智能體時通常看到的界面。（由于它非常簡潔，并且使用純 Python 編寫，沒有任何外部依賴，因此不如 Claude Code 或 Codex 那樣美觀。）

圖 9：Mini Coding Agent 中工具調用審批請求的示意圖。

在此環節中，模型必須選擇一個編排框架（harness）能夠識別的動作，例如列出文件、讀取文件、執行搜索、運行 Shell 命令、寫入文件等。同時，它還必須以一種編排框架能夠進行校驗的格式提供相應的參數。

因此，當模型請求執行某項操作時，運行時環境會暫停執行，并運行一系列程序化檢查，例如：

• 「這是一個已知的工具嗎？」
• 「提供的參數是否有效？」
• 「此操作是否需要用戶的審批？」
• 「請求訪問的路徑是否位于工作區（workspace）范圍之內？」

只有在通過了上述所有檢查之后，實際的操作指令才會被真正執行。

誠然，運行編碼智能體確實伴隨著一定的風險；但得益于編排框架的這些檢查機制，系統的可靠性也得到了提升，因為模型無法執行完全隨意、不受控的指令。

此外，除了能夠拒絕格式錯誤的動作請求并實施審批門控機制外，通過對文件路徑進行校驗，還可以確保文件訪問操作始終被限制在代碼倉庫（repo）的范圍之內。

從某種意義上說，編排框架雖然限制了模型的自由度，卻顯著提升了其實用性。

4、最小化上下文膨脹

上下文膨脹并非編碼智能體所獨有的問題，而是大模型普遍面臨的一個難題。誠然，如今的 LLM 已能支持越來越長的上下文窗口，但長上下文依然成本高昂，且若其中夾雜大量無關信息，還可能引入額外的「噪聲」。

在多輪對話過程中，編碼智能體比普通 LLM 更易受上下文膨脹之苦 —— 這主要是由于頻繁的文件讀取、冗長的工具輸出、系統日志等因素所致。

如果運行時環境對上述所有信息都采取「全保真」的存儲策略，那么可用的上下文 Token 額度很快就會被耗盡。因此，一套優秀的代碼智能體編排框架（Coding Harness）通常會采取相當精妙的策略來應對上下文膨脹問題，其處理手段遠比普通聊天界面那種單純的「截斷」或「摘要」操作要復雜得多。

從概念層面來看，編碼智能體中的「上下文壓縮」機制大致可按下方圖示所概括的流程運作。具體而言，我們在此將視角進一步聚焦于上一節圖 8 中所展示的「截取」（Clip，即第 6 步）環節。

圖 10：在重新送入提示詞之前，系統會對大篇幅的輸出進行截斷，對較早的讀取內容進行去重，并對交互記錄（Transcript）進行壓縮。

一個極簡的編排框架至少會采用兩種「緊湊化」策略來應對這一問題。

第一種策略是「截斷」（Clipping），即縮短冗長的文檔片段、大型工具輸出、內存筆記以及交互記錄條目。換言之，它能防止任何單段文本僅僅因為內容冗長，就獨占了大部分的提示詞預算。

第二種策略是「記錄縮減」或「摘要化」，即將完整的會話歷史（關于這一點，下一節會有更詳細的闡述）轉化為一段篇幅更小、更適合作為提示詞輸入的摘要。

這里的關鍵技巧在于：保留近期事件的更多細節，因為它們往往與當前步驟的關聯度更高；而對于較早期的事件，我們會采取更激進的壓縮手段，因為它們的相關性通常較低。

此外，我們還會對較早期的文件讀取操作進行去重處理，從而避免模型因同一文件在會話早期被反復讀取，而不得不一遍又一遍地重復接收相同的文件內容。

總而言之，我認為這正是優秀「編碼智能體」設計中那些往往被低估、看似枯燥乏味的關鍵環節之一。許多表面上歸功于「模型質量」的優異表現，實際上恰恰源自于「上下文質量」的提升。

5、結構化會話記憶

在實踐中，此處涵蓋的所有這 6 個核心概念都是高度交織在一起的；不同的章節和圖示會以不同的側重點或粒度來闡述這些概念。在上一節中，我們探討了在提示階段（prompt-time）如何利用歷史信息，以及如何構建一份緊湊的會話記錄（transcript）。當時的核心問題是：在下一輪交互中，究竟應該將多少過往的歷史信息回傳給模型？因此，那一節的重點在于信息的壓縮、截斷、去重以及時效性。

而本節 —— 即「結構化會話記憶」—— 所探討的則是歷史信息在存儲階段（storage-time）的內部結構。本節的核心問題在于：作為智能體，它應當隨著時間的推移保留哪些信息，并將其作為永久性的記錄？因此，本節的重點在于：運行時環境應維護一份更為完整的會話記錄作為「持久化狀態」；與此同時，它還應維護一個更為輕量級的「記憶層」—— 該記憶層體積較小，且其內容會經歷修改與壓縮處理，而非僅僅進行簡單的追加。

綜上所述，一個編程智能體會將其狀態拆分為（至少）兩個層級：

• 工作記憶（Working Memory）：即智能體顯式維護的一份經過高度提煉、體積較小的狀態信息。
• 完整會話記錄（Full Transcript）：這份記錄涵蓋了所有的用戶請求、工具輸出結果以及大模型的響應內容。

圖 11：新事件會被追加到「完整對話記錄」中，并被歸納總結至「工作記憶」里。磁盤上的會話文件通常以 JSON 格式存儲。

上圖展示了兩個主要的會話文件 ——「完整對話記錄」和「工作記憶」—— 它們通常以 JSON 文件的形式存儲在硬盤上。正如前文所述，「完整對話記錄」保存了完整的歷史信息，即使智能體程序被關閉，該記錄也能支持后續的會話恢復。「工作記憶」則更像是一個經過提煉的精簡版本，其中包含了當前最重要的信息；這一點在功能上與「精簡對話記錄」有著一定的關聯。

不過，「精簡對話記錄」與「工作記憶」各自承擔的職責略有不同。「精簡對話記錄」主要用于提示詞的重構。其作用是向模型提供近期歷史信息的壓縮視圖，從而使模型無需在每一輪對話中都查閱完整的對話記錄，便能順暢地延續對話。「工作記憶」則更側重于保障任務的連續性。其作用是維護一份小巧且經過顯式管理的摘要，專門用于記錄跨輪次對話中那些至關重要的信息，例如當前正在執行的任務、重要的相關文件以及近期的備忘記錄等。

參照上圖中的第 4 步，在隨后的下一輪對話中（為避免上圖顯得過于繁雜，該輪次并未在圖中展示），最新的用戶請求 —— 連同大模型的響應及工具的輸出 —— 將被作為一條「新事件」，同時記錄并追加到「完整對話記錄」與「工作記憶」之中。

6、使用（有界）子智能體進行任務委托

一旦智能體擁有了工具和狀態，下一個有用的功能之一就是任務委托。

原因在于，它允許我們通過子智能體將某些工作并行化為子任務，從而加速主任務的執行。例如，主智能體可能正在執行某個任務，但仍然需要一些輔助信息，例如哪個文件定義了某個符號、某個配置的含義是什么，或者某個測試失敗的原因。將這些信息拆分成一個有界子任務會很有用，而不是強制一個循環同時處理所有線程的工作。

（在我的迷你編碼代理中，實現更簡單，子智能體仍然同步運行，但基本思想是相同的。）

子智能體只有在繼承足夠的上下文來執行實際工作時才有用。但如果我們不加以限制，就會出現多個智能體重復工作、訪問相同文件或生成更多子智能體等問題。

所以，棘手的設計問題不僅在于如何生成子智能體，還在于如何綁定子智能體。

圖 12：子智能體繼承了足以使其發揮作用的上下文，但其運行邊界比主智能體更為嚴格。

這里的關鍵在于：子智能體既繼承了足夠的上下文以確保其有效性，同時也受到了一定的限制（例如，被設定為只讀模式，且遞歸深度受到限制）。

Claude Code 早在很久以前便已支持子智能體功能，而 Codex 則是近期才引入這一特性的。通常情況下，Codex 并不會強制將子智能體設定為只讀模式；相反，它們往往會繼承主智能體的大部分沙箱環境與審批配置。因此，這里的「邊界」更多是指任務的范圍界定、上下文環境以及執行深度等方面的限制。

總結

上一節旨在概述編碼智能體系統的主要組成部分。正如前文所述，從實現層面來看，這些組件之間或多或少都存在著深度交織與耦合。不過，我仍希望通過逐一剖析這些組件的方式，能有助于讀者構建起一套關于編碼智能體編排框架運作機制的整體心智模型，并理解為何相比于簡單的多輪對話模式，代碼智能體能夠顯著提升大語言模型的實用價值。

圖 13：前文討論過的編碼編排框架（Coding Harness）的六大主要特征。

如果你有興趣看到這些特征是如何通過簡潔、極簡風格的 Python 代碼實現的，不妨看看「Mini Coding Agent」。

它與 OpenClaw 相比有何不同？

OpenClaw 確實是一個值得拿來對比的有趣案例，但它與本文所探討的系統并非完全屬于同一類型。

OpenClaw 更像是一個運行于本地的通用型智能體平臺 —— 盡管它也具備編碼能力 —— 而非一款專精于（終端環境下的）編碼輔助工具。

不過，它與編碼輔助框架之間仍存在諸多重疊之處：

• 它會在工作區內利用提示詞和指令文件，例如 AGENTS.md、SOUL.md 和 TOOLS.md；
• 它會保存 JSONL 格式的會話記錄文件，并具備會話記錄壓縮與會話管理功能；
• 它能夠衍生出輔助會話及子智能體；
• 等等。

然而，正如上文所述，兩者的側重點截然不同。編碼智能體的設計初衷，是為了優化個人開發者在代碼倉庫中工作時的體驗 —— 即高效地指揮輔助工具去檢查文件、修改代碼并執行本地工具。相比之下，OpenClaw 的設計重心則在于跨聊天窗口、頻道及工作區運行大量「長生命周期」的本地智能體，而編碼工作僅僅是其眾多重要任務負載之一。

參考原文：

https://magazine.sebastianraschka.com/p/components-of-a-coding-agent