塞巴斯蒂安深度好文：Claude Code、Codex等Coding Agent的架构解析

知名机器学习专家Sebastian Raschka《Build a Large Language Model From Scratch》作者在最近的文章《Components of A Coding Agent》中详细拆解了Coding Agent的核心设计原理。他强调Coding Agent的实际性能并不仅仅取决于底层LLM而是更多依赖于围绕LLM的Agent Harness一个软件层用于管理上下文、工具、记忆和控制流程。文章通过一个极简的纯Python实现称为 Mini Coding Agent作为示例系统性地介绍了六个核心构建模块。这些模块共同形成一个迭代循环observe → inspect → choose → act让Agent能够高效处理真实软件工程任务如仓库导航、代码编辑、命令执行等。在这篇文章中我想讨论Coding Agent和Agent Harness的整体设计它们是什么如何工作以及不同部分如何在实践中结合在一起。在许多现实世界的应用中Agent周围的系统比如工具的使用、上下文管理和记忆扮演的角色与模型本身一样重要。这也有助于解释为什么像Claude Code或Codex这样的系统比在普通聊天界面中使用相同模型的体验要显得更有能力。在这篇文章中我将介绍Coding Agent的六个主要组成部分。Claude Code、Codex CLI和其他Coding Agent你可能熟悉Claude Code或Codex CLI但为了便于理解它们本质上是Agentic Coding工具通过在应用层中包装LLM形成一个所谓的“Agent Harness”使其在编码任务中更加便捷并且表现更好。Coding Agent是为软件工作设计的其中重要的不仅仅是模型选择还有周围的系统包括代码库上下文、工具设计、提示缓存稳定性、记忆和长时间会话的连续性。这个区别很重要因为当我们讨论LLM的编码能力时人们往往将模型、推理行为和Agent产品混为一谈。但在深入探讨Coding Agent的具体细节之前让我先简要地提供一些关于更广泛概念——LLM、推理模型和Agent——之间区别的背景信息。关于LLM、推理模型和Agent之间的关系LLM大语言模型是核心的下一个词预测模型。推理模型仍然是LLM但通常是经过训练和/或提示以便在推理、验证或候选答案搜索时花费更多的推理时间计算。Agent是位于顶层的一层可以理解为围绕模型的控制循环。通常Agent层或Agent Harness会根据目标决定下一步要检查什么调用哪些工具如何更新其状态以及何时停止等。大致上我们可以将这种关系理解为LLM是引擎推理模型是一个增强版的引擎更强大但使用成本更高而Agent Harness则帮助我们使用模型。这个类比并不完美因为我们也可以将常规LLM和推理LLM作为独立的模型使用比如在聊天界面或Python会话中但我希望它能传达出主要的观点。传统 LLM、推理 LLM或推理模型以及封装在Agent Harness中的 LLM 之间的关系。换句话说Agent是一个在环境中反复调用模型的系统。简而言之我们可以将其总结如下LLM原始模型推理模型一个优化过的LLM旨在输出中间推理轨迹并进行自我验证Agent一个使用模型、工具、记忆和环境反馈的循环Agent Harness围绕Agent的软硬件框架管理上下文、工具使用、提示、状态和控制流Coding HarnessAgent Harness的一个特例即用于软件工程的任务特定框架管理代码上下文、工具、执行和迭代反馈如上所列在Agent和编码工具的上下文中我们也有两个流行的术语Agent Harness 和AgenticCoding Harness。Coding Harness是围绕模型的软硬件框架帮助模型有效地编写和编辑代码。而Agent Harness则更广泛并不专门针对编码例如想想OpenClaw。Codex和Claude Code可以被视为编码工具。无论如何更强大的LLM为推理模型提供了更好的基础这涉及额外的训练而Agent Harness则能更好地发挥推理模型的潜力。当然LLM和推理模型本身也能解决编码任务没有Agent Harness的情况下但编码工作不仅仅是下一个词的生成。很多时候它涉及到代码库的导航、搜索、函数查找、差异应用、测试执行、错误检查并且要保持所有相关信息的上下文一致性。程序员可能知道这是一项艰难的脑力工作这就是为什么我们不喜欢在编码过程中被打扰Coding Harness由三层组成模型族、Agent循环和运行时支持。模型提供“引擎”Agent循环驱动迭代问题求解运行时支持提供底层架构。在循环中“观察”从环境中收集信息“检查”分析这些信息“选择”选择下一步“执行”执行下一步。重点是一个好的Coding Harness可以使推理模型和非推理模型的表现远超在普通聊天框中的表现因为它有助于上下文管理等方面。Coding Harness正如前面部分提到的当我们说到Harness时通常是指围绕模型的软件层它负责组装提示、暴露工具、跟踪文件状态、应用编辑、运行命令、管理权限、缓存稳定的前缀、存储记忆等多个功能。今天在使用LLM时这一层比直接提示模型或使用网页聊天UI更接近于“与上传的文件聊天”在用户体验中起着更大的作用。在我看来现今LLM的原版版本具有非常相似的能力例如GPT-5.4、Opus 4.6和GLM-5等原版因此Harness通常是区分不同LLM性能的关键因素。虽然这只是推测但我怀疑如果我们将最新的、最强大的开源LLM之一如GLM-5放入一个类似的Harness中它的表现可能会与GPT-5.4在Codex中的表现或与Claude Opus 4.6在Claude Code中的表现不相上下。也就是说一些针对特定Harness的后训练通常是有益的。例如OpenAI历史上曾分别维护GPT-5.3和GPT-5.3-Codex的不同版本。在下一部分我将更深入地讨论具体细节并使用我的Mini Coding Agenthttps://github.com/rasbt/mini-coding-agent来介绍Coding Harness的核心组成部分。将在接下来的部分讨论的coding agent / coding harness的主要功能特性。顺便提一下在本文中为了简化起见我将Coding Agent和Coding Harness这两个术语交替使用。严格来说Agent是基于模型的决策循环而Harness是围绕它的软件框架提供上下文、工具和执行支持。最小但完全可用的从零开始实现的Mini Coding Agent纯Python实现以下是Coding Agent的六个主要组成部分。你可以查看我最小但完全可用的、从零开始实现的Mini Coding Agent的源代码用纯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_delegateLive Repo Context实时代码库上下文这可能是最显而易见的组成部分但它也是最重要的之一。当用户说“修复测试”或“实现xyz”时模型应该知道它是否处于一个Git仓库中当前所在的分支是什么哪些项目文档可能包含指令等等。这是因为这些细节通常会发生变化或会影响正确的操作是什么。例如“修复测试”并不是一个自包含的指令。如果代理看到AGENTS.md或项目的README文件它可能会了解到该运行哪个测试命令等等。如果它知道代码库的根目录和结构它可以直接去正确的位置查找而不是去猜测。此外Git分支、状态和提交记录有助于提供更多关于当前正在进行的更改的上下文并帮助确定应该集中精力的地方。Agent Harness首先构建一个小的工作区摘要并将其与用户请求结合起来以获取额外的项目上下文。重点是Coding Agent在执行任何工作之前先收集信息作为工作区摘要的“稳定事实”这样它就不是每次都从零开始没有上下文地处理每个提示。Prompt Shape And Cache Reuse提示形状和缓存重用一旦Agent获得了代码库视图接下来的问题就是如何将这些信息传递给模型。前面的图示展示了一个简化的视图“合并提示前缀 请求”但实际上每次用户查询时重新组合并重新处理工作区摘要是相对浪费的。也就是说编码会话是重复性的Agent规则通常保持不变。工具描述通常也保持不变。甚至工作区摘要通常也大部分保持不变。主要的变化通常是最新的用户请求、最近的对话记录或许还有短期记忆。“智能”运行时不会在每一轮中将所有内容重新构建为一个巨大的、无差异的提示正如下面的图示所示。Agent Harness构建一个稳定的提示前缀添加变化的会话状态然后将这个合并后的提示传递给模型。与第1节的主要区别在于第1节是关于收集代码库事实的而在这里我们现在关注的是如何高效地打包和缓存这些事实以便反复调用模型。“Stable prompt prefix”“稳定的提示前缀”意味着其中包含的信息变化不大。它通常包含一般指令、工具描述和工作区摘要。如果没有重要的变化我们不希望在每次交互中都浪费计算资源重新构建这些内容。其他组件更新的频率较高通常是每次交互。这包括短期记忆、最近的对话记录以及最新的用户请求。简而言之对于“Stable prompt prefix”的缓存方面智能运行时会尽量重用这一部分。工具访问与使用工具访问和工具使用是开始让它更像一个Agent而不再是聊天的地方。一个普通的模型可以以散文的形式建议命令但在一个Coding Harness中LLM应该做一些更具体、更有用的事情并且能够实际执行命令并获取结果而不是我们手动调用命令并将结果粘贴回聊天中。但是Agent Harness通常不会让模型随意编写语法而是提供一个预定义的、允许使用的工具列表这些工具有清晰的输入和明确的边界。当然像Python的subprocess.call这样的功能也可以是其中的一部分这样Agent就可以执行任意广泛的shell命令。工具使用流程如下图所示。模型生成一个结构化的动作Agent Harness验证它按需请求批准执行它并将有界的结果反馈到循环中。为了说明这一点下面是一个使用我的Mini Coding Agent时用户通常会看到的示例。这不像Claude Code或Codex那么漂亮因为它非常简约并且使用的是纯Python没有任何外部依赖。Mini Coding Agent中工具调用审批请求的示意图。在这里模型必须选择一个代Agent Harness能够识别的动作比如列出文件、读取文件、搜索、运行shell命令、写入文件等。它还需要以Agent Harness可以检查的形式提供参数。因此当模型请求执行某个动作时运行时可以暂停并进行程序化检查比如“这是一个已知的工具吗”“参数有效吗”“这需要用户批准吗”“请求的路径在工作区内吗”只有当这些检查通过后动作才会被执行。当然运行Coding Agent时存在一些风险但Agent Harness的检查也提高了可靠性因为模型不会执行完全随意的命令。此外除了拒绝格式不正确的动作和审批控制之外还可以通过检查文件路径将文件访问限制在代码库内部。从某种意义上说Agent Harness给模型减少了自由度但同时也提高了可用性。Minimizing Context Bloat最小化上下文膨胀上下文膨胀不是Coding Agent的独特问题而是LLM普遍存在的问题。确实现今LLM支持越来越长的上下文但长上下文仍然昂贵并且可能引入额外的噪声如果有很多无关的信息。在多轮对话中Coding Agent比常规LLM更容易受到上下文膨胀的影响因为会涉及重复的文件读取、冗长的工具输出、日志等。如果运行时保持所有这些内容的完整准确性它会很快耗尽可用的上下文token。因此一个好的Coding Harness通常会非常精细地处理上下文膨胀而不仅仅是像常规聊天UI那样切割和总结信息。从概念上讲Coding Agent中的上下文压缩可能如下图所示。具体来说我们正在进一步放大前一部分图8中的剪辑第6步部分。大型输出被剪裁较早的读取被去重且对话记录在重新输入提示之前会被压缩。一个最小化的Harness至少使用两种压缩策略来管理这个问题。第一种是剪裁它会缩短长文档片段、大型工具输出、记忆记录和对话记录条目。换句话说它防止任何一段文字因为恰好冗长而占用过多的提示预算。第二种策略是对话记录减少或总结它将完整的会话历史在下一部分会详细讨论转化为一个更小的可输入的总结。这里的一个关键技巧是保持近期事件的详细性因为它们更有可能对当前步骤产生影响。而我们则更加积极地压缩较早的事件因为它们可能不太相关。此外我们还会去重较早的文件读取以便模型不会因为文件内容在会话中多次被读取而反复看到相同的内容。总体来说我认为这是Coding Agent设计中一个被低估、但却很重要的部分。很多看似“模型质量”的问题实际上是上下文质量的问题。Structured Session Memory结构化会话记忆在实际操作中本文涵盖的这六个核心概念是高度交织在一起的不同的部分和图示以不同的焦点或缩放级别呈现它们。在前一部分中我们讨论了提示时间如何使用历史记录以及如何构建一个紧凑的对话记录。那个部分的重点是在下一轮中多少过去的内容应该返回到模型中因此强调的是压缩、剪裁、去重和近期性。而这一部分——结构化会话记忆则是关于历史记录的存储时间结构。这里的问题是Agent应该保存哪些内容作为永久记录因此重点在于运行时将完整的对话记录作为持久状态保存并且有一个较轻的记忆层它比较小且会被修改和压缩而不是简单地附加内容。总结Coding Agent将状态分为至少两个层次工作记忆Agent显式保存的小型、精炼的状态完整对话记录涵盖所有用户请求、工具输出和LLM响应新的事件会被追加到完整对话记录中同时在工作记忆中进行总结。磁盘上的会话文件通常以JSON文件形式存储。上图展示了两个主要的会话文件完整对话记录和工作记忆这些通常会以JSON文件形式存储在磁盘上。如前所述完整对话记录保存了整个历史并且如果关闭Agent它仍然可以恢复。工作记忆则是一个更精炼的版本包含当前最重要的信息这与紧凑对话记录有所关联。但是紧凑对话记录和工作记忆的作用略有不同。紧凑对话记录用于提示重建。它的作用是为模型提供近期历史的压缩视图使模型在每轮对话中无需看到完整记录即可继续对话。工作记忆更多用于任务连续性。它的作用是保持一份小型、显式维护的跨轮次重要信息总结比如当前任务、关键文件和近期笔记。按照上图第4步的流程最新的用户请求连同LLM响应和工具输出会在下一轮被记录为完整对话记录和工作记忆中的“新事件”图中为了减少杂乱未显示这一部分。Delegation With (Bounded) Subagents使用有界子Agent进行委派一旦Agent拥有工具和状态其中一个有用的能力就是委派。原因是它允许我们通过子Agent将某些工作并行化为子任务从而加快主任务的进度。例如主Agent可能正在执行一个任务但仍然需要处理一个附带的问题例如哪个文件定义了某个符号、某个配置的内容是什么、或者为什么测试失败。将这些拆分为有界的子任务比强制一个循环同时处理所有任务更有用。子Agent只有在继承了足够的上下文以执行实际工作时才有用。但如果不加限制我们就可能出现多个Agent重复工作、操作同一文件或生成更多子Agent等问题。因此设计中的难点不仅是如何生成子Agent还包括如何给子Agent绑定上下文。子Agent继承了足够的上下文以发挥作用但其运行边界比主Agent更严格。这里的技巧在于子Agent继承足够的上下文以便有用同时又受到约束例如只读并限制递归深度。Claude Code长期以来就支持子Agent而Codex则在最近添加了这一功能。Codex通常不会强制子Agent进入只读模式。相反子Agent通常继承了主Agent的大部分沙箱和审批设置。因此边界更多地涉及任务范围、上下文和递归深度。总结上面一节尝试涵盖了Coding Agent的主要组成部分。如前所述这些组件在实现中或多或少高度交织。然而我希望逐一介绍它们有助于建立整体的心理模型理解Coding Harness如何工作以及为什么它们能让LLM比简单的多轮聊天更有用。与OpenClaw相比如何OpenClaw可能是一个有趣的对比但它并不是完全相同类型的系统。OpenClaw更像是一个本地的、通用的Agent平台它也能进行编码而不是一个专门的终端编码助手。它与Coding Harness仍有若干重叠之处在工作区中使用提示和指令文件例如AGENTS.md、SOUL.md和TOOLS.md保存JSONL格式的会话文件并包括对话记录压缩和会话管理可以生成辅助会话和子Agent等等然而如上所述重点不同。Coding Agent针对的是在代码库中工作的用户优化了让编码助手高效地检查文件、编辑代码和运行本地工具的流程。而OpenClaw则更优化于在多个聊天、频道和工作区中运行许多长期存在的本地Agent其中编码只是众多工作负载中的一个重要部分。这里给大家精心整理了一份全面的AI大模型学习资源包括AI大模型全套学习路线图从入门到实战、精品AI大模型学习书籍手册、视频教程、实战学习、面试题等资料免费分享扫码免费领取全部内容1. 成长路线图学习规划要学习一门新的技术作为新手一定要先学习成长路线图方向不对努力白费。这里我们为新手和想要进一步提升的专业人士准备了一份详细的学习成长路线图和规划。可以说是最科学最系统的学习成长路线。2. 大模型经典PDF书籍书籍和学习文档资料是学习大模型过程中必不可少的我们精选了一系列深入探讨大模型技术的书籍和学习文档它们由领域内的顶尖专家撰写内容全面、深入、详尽为你学习大模型提供坚实的理论基础。书籍含电子版PDF3. 大模型视频教程对于很多自学或者没有基础的同学来说书籍这些纯文字类的学习教材会觉得比较晦涩难以理解因此我们提供了丰富的大模型视频教程以动态、形象的方式展示技术概念帮助你更快、更轻松地掌握核心知识。4. 2026行业报告行业分析主要包括对不同行业的现状、趋势、问题、机会等进行系统地调研和评估以了解哪些行业更适合引入大模型的技术和应用以及在哪些方面可以发挥大模型的优势。5. 大模型项目实战学以致用当你的理论知识积累到一定程度就需要通过项目实战在实际操作中检验和巩固你所学到的知识同时为你找工作和职业发展打下坚实的基础。6. 大模型面试题面试不仅是技术的较量更需要充分的准备。在你已经掌握了大模型技术之后就需要开始准备面试我们将提供精心整理的大模型面试题库涵盖当前面试中可能遇到的各种技术问题让你在面试中游刃有余。7. 资料领取全套内容免费抱走学 AI 不用再找第二份不管你是 0 基础想入门 AI 大模型还是有基础想冲刺大厂、了解行业趋势这份资料都能满足你现在只需按照提示操作就能免费领取扫码免费领取全部内容