一篇详细的技术解析：Coding Agent（编码智能体）的构成

Created time

Apr 6, 2026 03:53 AM

tags

技术解读

Agent

实用教程

type

post

原文链接：Components of A Coding Agent
Components of A Coding Agent
How coding agents use tools, memory, and repo context to make LLMs work better in practice

以下为AI翻译，有润色。

在这篇文章里，我想聊聊编码智能体（Coding Agents）和智能体框架（Agent Harnesses）的整体设计：它们是什么、怎么运作，以及在实践中各个部分是如何咬合在一起的。

我的两本书《Build a Large Language Model (From Scratch)》和《Build a Large Reasoning Model (From Scratch)》的读者，时常问起关于智能体的问题，所以我觉得有必要写一篇可供参考的指南。

更宏观地看，智能体之所以成为一个重要议题，是因为近期实用型 LLM 系统的进步，很大程度上并不只来自模型本身的提升，更来自我们如何使用这些模型。在许多实际应用场景中，外围系统——工具调用、上下文管理、记忆机制——所发挥的作用，丝毫不亚于模型本身。这也解释了为什么 Claude Code 或 Codex 这类系统，用起来会比在普通聊天界面中使用同款模型强大得多。

本文将逐一拆解编码智能体的六个核心构建模块。

你可能已经接触过 Claude Code 或 Codex CLI。简单介绍一下背景：它们本质上都是代理式编码工具，将 LLM 包裹在一个应用层（即所谓的代理框架）中，从而让模型在编码任务上更顺手、表现更好。

图 1： Claude Code CLI、Codex CLI，以及我自己搭建的迷你编码智能体。

编码智能体专为软件开发工作而设计，其核心不仅在于模型的选择，更在于周边系统的质量——包括代码库上下文的注入、工具的设计、提示词缓存的稳定性、记忆能力，以及长会话的连续性。

这个区分至关重要。我们在谈论 LLM 的编码能力时，很容易把模型、推理行为和智能体产品混为一谈。所以在深入探讨编码智能体的细节之前，先简单厘清几个核心概念之间的区别：LLM、推理模型和智能体。

LLM：核心的下一个 token 预测模型。

推理模型：本质上仍是 LLM，但特指那些经过训练或提示之后，能在推理、验证或搜索候选答案时投入更多计算资源的模型。

智能体（Agent）：架设在模型之上的一层，可以理解为围绕模型运行的控制循环。给定一个目标，智能体层（或框架）负责决定下一步该检查什么、调用哪些工具、如何更新状态，以及何时停下来。

粗略地说：LLM 是引擎，推理模型是强化版引擎（能力更强，但调用成本更高），而智能体框架则是帮我们驾驭模型的系统。这个类比不完美——LLM 和推理模型当然也能独立使用（在聊天界面或 Python 环境里）——但核心思想是清晰的。

图 2： 传统 LLM、推理 LLM（推理模型），以及封装在智能体框架中的 LLM，三者之间的关系。

换句话说，智能体是一个在环境中反复调用模型的系统。

简单总结一下各概念的定义：

LLM：原始模型

推理模型：经过优化、能输出中间推理步骤并进行更多自我验证的 LLM

智能体（Agent）：结合了模型、工具、记忆与环境反馈的循环系统

智能体框架（Agent Harness）：围绕智能体构建的软件脚手架，负责管理上下文、工具调用、提示词、状态与控制流

编码框架（Coding Harness）：智能体框架的一种特例，专为软件工程设计，重点处理代码上下文、工具使用、执行与迭代反馈

如上所述，在智能体和编码工具的语境下，还有两个常见术语：智能体框架（Agent Harness）和编码框架（Coding Harness）。

编码框架是指围绕模型搭建的软件脚手架，旨在帮助模型高效地编写和编辑代码；而智能体框架的适用范围更广，不局限于编码场景（例如 OpenClaw）。Codex 和 Claude Code 都可以视为编码框架。

总结：更好的 LLM 为推理模型奠定更优的基础，而 Harness 则让推理模型发挥出更大的潜力。

当然，LLM 和推理模型本身也完全可以独立完成编码任务，无需借助框架。但编码工作远不止是生成下一个 token——它涉及代码库导航、搜索、函数查找、差异应用、测试执行、错误检查，以及在上下文中同时保持所有相关信息。（程序员应该深有体会：这是极耗脑力的工作，这也是为什么写代码时最怕被打断。）

图 3： 编码辅助框架融合了三个层级：模型系列、智能体循环和运行时支持。模型提供「引擎」，智能体循环驱动迭代式的问题解决过程，运行时支持提供底层架构。在循环中：「观察」从环境收集信息，「检查」分析信息，「选择」确定下一步行动，「执行」将其付诸实践。

核心结论：一套优秀的编码辅助框架，能让推理模型和非推理模型的表现都远超在普通聊天框中的水平——因为它承担了上下文管理等大量繁琐但关键的工作。

如上一节所述，当我们谈到「工具框架（Harness）」时，通常指的是模型周围的软件层，它负责：组装提示词、暴露工具接口、追踪文件状态、应用编辑、执行命令、管理权限、缓存稳定前缀、存储记忆……等等。

如今，使用 LLM 时，这一软件架构层所决定的用户体验，已经远超直接向模型发送提示词或使用网页聊天界面的方式（后者更接近「与上传的文件聊天」）。

在我看来，由于当今主流 LLM 的原生能力已非常接近（比如 GPT-5.4、Opus 4.6、GLM-5 等），工具框架往往才是决定某个 LLM 是否比另一个表现更好的关键因素。

这只是推测，但我怀疑：如果把目前能力最强的开源权重模型之一（比如 GLM-5）套入类似的工具框架，它在 Codex 或 Claude Code 中的表现，很可能与 GPT-5.4 或 Claude Opus 4.6 不相上下。当然，针对特定框架进行一些后期训练通常是有益的——例如，OpenAI 历史上曾维护过独立的 GPT-5.3 和 GPT-5.3-Codex 变体。

接下来，我想深入细节，以我的 Mini Coding Agent 为例，拆解编码工具的核心组件。

图 4： 后续章节将逐一介绍的编码智能体/编码工具的主要功能模块。

顺便说明：为了行文简便，本文中「编码智能体（Coding Agent）」和「编码工具（Coding Harness）」这两个术语会混用。严格来说，智能体指的是模型驱动的决策循环，而工具则是提供上下文、工具接口和执行支持的周边软件框架。

图 5： 一个极简但功能完备、从零构建的迷你编码智能体（纯 Python 实现）。

以下是编码智能体的六个主要组件。你可以查看我那个极简版迷你编码智能体的源代码，代码中通过注释标注了这六个组件的位置：

组件一：实时代码库上下文（Live Repo Context）

这或许是最显而易见的组件，却也是最重要的之一。

当用户说「修复测试」或「实现 xyz」时，模型需要知道：它是否处于一个 Git 仓库中？当前在哪个分支？哪些项目文档里可能有相关指令？

这些细节往往会直接影响正确的操作方式。「修复测试」并非一条自包含的指令。如果智能体能看到 AGENTS.md 或项目 README，它或许就能获知应该运行哪个测试命令。如果它了解仓库的根目录和目录结构，就能在正确的位置查找，而不是瞎猜。

此外，Git 分支、状态和提交记录也能帮助智能体了解当前正在进行哪些更改，以及重点应该放在哪里。

图 6： 智能体工具包会优先构建一份简短的工作区摘要，并将其与用户请求结合，提供额外的项目上下文。

核心要点：编码智能体在开始任何工作之前，会预先收集信息（作为工作区摘要的「稳定事实」），这样它在处理每个提示词时就不会从零开始，也不会陷入信息匮乏的困境。

组件二：提示词缓存——提示词结构与缓存复用（Prompt Shape & Cache Reuse）

一旦智能体掌握了代码库概览，下一个问题就是：如何高效地把这些信息喂给模型？

前面的图示展示的是简化视图（「组合提示词：前缀 + 请求」），但在实践中，每次用户查询都重新组合并处理一遍工作区摘要，显然是一种浪费。

道理很简单：编码会话具有重复性——

智能体规则通常保持不变；

工具描述通常保持不变；

工作区摘要通常（大部分）也保持不变。

主要变化的只有：最新的用户请求、最近的对话记录，以及可能的短期记忆。

「智能」运行时不会在每一轮都把所有内容重新打包成一个巨大的、无差别的提示词，如下图所示。

图 7： 智能体工具框架构建一个稳定的提示词前缀，叠加上不断变化的会话状态，再将组合后的提示词输入模型。

与组件一的区别在于：组件一侧重于「收集」代码库的事实信息，组件二侧重于「打包和缓存」这些事实，以便在后续模型调用中高效复用。

「稳定提示词前缀」之所以「稳定」，是因为它包含的信息变化不大——通常包括通用指令、工具描述和工作区摘要。如果没有重要内容发生变化，我们不希望每次交互都浪费计算资源从头重建它。

其他组件则更新频率更高（通常每轮对话都会更新），包括短期记忆、最近的对话记录和最新的用户请求。

简而言之，「稳定提示词前缀」的缓存机制，本质上就是让智能运行时尽量复用这部分内容，避免重复计算。

组件三：工具——结构化工具、验证与权限（Structured Tools, Validation & Permissions）

工具访问和工具使用，是让系统从「聊天」跨越到「智能体」的关键所在。

普通模型只能用文字建议命令，但处于编码框架中的 LLM 应该做得更具体、更有用——它能实际执行命令并获取结果，而不是让我们手动复制命令、再把结果粘贴回聊天窗口。

但与其让模型即兴发挥任意语法，工具框架通常会提供一份预定义的、命名明确的允许工具列表，并附带清晰的输入要求和边界。（当然，像 Python subprocess.call 这样的通用工具也可以包含进来，让智能体能执行更广泛的 shell 命令。）

工具使用的流程如下图所示：

图 8： 模型发出结构化操作 → 工具框架进行验证 → 必要时请求批准 → 执行操作 → 将受限的执行结果反馈回循环。

以我的 Mini Coding Agent 为例，以下是用户通常看到的交互效果（它非常精简，纯 Python 实现，没有任何外部依赖，所以不像 Claude Code 或 Codex 那么美观）：

图 9： Mini Coding Agent 中工具调用审批请求的示意图。

在这个框架中，模型必须选择一个运行时能够识别的操作，例如列出文件、读取文件、搜索、运行 shell 命令、写入文件等；并以运行时能够校验的格式提供参数。

当模型请求执行某项操作时，运行时会暂停并执行一系列程序化检查：

「这是一个已知的工具吗？」

「参数是否有效？」

「这是否需要用户批准？」

「所请求的路径是否在工作区范围内？」

只有通过所有检查，才会真正执行操作。

运行编码智能体确实存在一定风险，但这套检查机制大幅提升了可靠性——因为模型无法执行完全随意的命令。此外，除了拒绝格式错误的操作和设置审批门控之外，文件访问权限还可以通过路径校验限制在仓库内部。

某种意义上，框架对模型自由度的约束，恰恰成就了它的可用性。

组件四：上下文管理——上下文精简与输出管理（Context Reduction & Output Management）

上下文膨胀（Context Bloat）并非编码智能体独有的问题，而是 LLM 普遍面临的挑战。尽管如今的 LLM 支持越来越长的上下文（我最近也写过关于让长上下文在计算上更可行的注意力机制变体的文章），但长上下文依然成本高昂，且可能引入额外噪声（当其中包含大量无关信息时）。

与常规 LLM 多轮对话相比，编码智能体更容易受到上下文膨胀的影响——因为它涉及反复的文件读取、冗长的工具输出、执行日志等内容。

如果运行时完整保留所有这些信息，很快就会耗尽可用的上下文 token。因此，一个优秀的编码工具框架通常会采取非常精细的手段来应对上下文膨胀，而不只是像普通聊天界面那样简单地截断或总结。

从概念上看，编码智能体中的上下文压缩（Context Compaction）工作方式如下图所示（具体来说，是对上一节图 8 中「剪辑（clip，第 6 步）」部分的深入拆解）：

图 10： 过长的输出会被截断，较旧的读取内容会被去重，转录内容在返回提示词之前经过压缩。

一个最小化的工具框架至少会使用两种压缩策略：第一种：截断（Clipping）。缩短过长的文档片段、庞大的工具输出、记忆笔记和对话记录条目。换句话说，它能防止某段文本仅仅因为篇幅冗长就占用过多的提示词预算。第二种：对话记录精简或摘要（Transcript Reduction / Summarization）。将完整的会话历史（下一节会详细介绍）转化为更精简、可放入提示词的摘要。