# 编程 Agent 的组成部件 - 原标题：Components of A Coding Agent - 类型：博客 - 来源：Sebastian Raschka - 发布时间：2026-04-04 - 首次精选：2026-10-29 23:09 - 分级：值得看 - 学习层级：进阶 - 主题：[agent-architecture-harness]()（第 9 位）、[agent-context-memory]()（第 15 位）、[coding-agents-engineering]()（第 21 位） - 原文链接：[https://magazine.sebastianraschka.com/p/components-of-a-coding-agent]() - 本站页面：[https://oplearnx.com/resources/pk\_640e7c415dcb]() ## 摘要 Sebastian Raschka 在其 Substack 杂志上于 2026 年 4 月 4 日发布的文章。文章讨论编程 Agent 与 agent harness 的整体设计，说明它们是什么、如何工作以及各部分在实践中如何配合，并指出工具使用、上下文管理和记忆等外围系统在实际 LLM 应用中与模型本身同样重要，这解释了 Claude Code、Codex 等系统为何比在普通对话界面中使用同样模型显得更能干；文中列出编程 Agent 的六个主要构建模块。面向关注 Agent 设计与实现的读者。 ## 中文精读 ### 1. 编码代理由工具、记忆和仓库上下文组成，用来让 LLM 在实践中更好用 - 文章要讲编码代理（coding agent）与代理执行框架（agent harness）的整体设计：它们是什么、如何工作、各部分怎样配合。 - 作者常被读过其 LLM 与推理模型从零构建书籍的读者问到代理问题，因此写这篇可引用的参考。 - 近期实用 LLM 系统的进步不只在模型本身，也在于使用方式：工具调用、上下文管理、记忆等周边系统与模型同等重要。 - 这也能解释为什么 Claude Code、Codex 会比在普通聊天界面里用同样的模型显得强得多。 - 全文列出编码代理的六个主要构建模块。 ### 2. Claude Code、Codex CLI 及其他编码代理 - Claude Code 与 Codex CLI 本质上是把 LLM 包在应用层里，即所谓的代理执行框架（agentic harness），让编码任务更方便、表现更好。 - 编码代理是为软件工作专门设计的，关键部分不只是选哪个模型，还包括仓库上下文、工具设计、提示缓存稳定性、记忆和长会话连续性。 - 这些区分很重要，因为讨论 LLM 编码能力时，人们常把模型、推理行为和代理产品混为一谈。 - 在进入编码代理细节之前，作者先交代 LLM、推理模型与代理这几个更宽泛概念的差别。 ### 3. LLM、推理模型与代理之间的关系 - LLM 是核心的下一词元（next-token）模型；推理模型仍是 LLM，只是训练和/或提示上让它在推理期花更多算力做中间推理、验证或候选答案搜索。 - 代理是上面的一层，可理解为围绕模型的控制循环：给定目标后，它决定查看什么、调用哪些工具、如何更新状态、何时停止。 - 类比：LLM 是引擎，推理模型是加强版引擎（更强但更贵），代理执行框架让模型发挥作用；该类比不完美，因为传统与推理 LLM 也可单独使用。 - 作者给出术语清单：LLM 是原始模型；推理模型是优化为输出中间推理轨迹并更多自我验证的 LLM；代理是使用模型加工具、记忆和环境反馈的循环。 - 代理执行框架（agent harness）是管理上下文、工具使用、提示、状态与控制流的软件脚手架；编码框架（coding harness）是它面向软件工程的特例，Codex 和 Claude Code 可视为编码框架。 - 编码工作只有一部分是下一词元生成，大量工作在于仓库导航、搜索、函数查找、打补丁、跑测试、检查错误和保持相关信息在上下文中。 ### 4. 编码框架（Coding Harness） - 所谓框架（harness），一般指模型周围的软件层：组装提示、暴露工具、跟踪文件状态、应用编辑、运行命令、管理权限、缓存稳定的提示前缀、存储记忆等。 - 如今使用 LLM 时，这一层决定了大部分用户体验，远胜于直接对模型写提示或用网页聊天界面（后者更接近“与上传文件聊天”）。 - 按作者看法，如今各 LLM 的原生版本能力很接近（如 GPT-5.4、Opus 4.6、GLM-5 左右），因此框架常是让某个 LLM 表现优于另一个的区别因素。 - 作者推测：把最新的强开放权重模型（如 GLM-5）放进类似框架，表现可能接近 Codex 中的 GPT-5.4 或 Claude Code 中的 Opus 4.6；不过针对框架做的额外后训练通常有帮助，例如 OpenAI 曾维护 GPT-5.3 与 GPT-5.3-Codex 两个变体。 - 作者用自己纯 Python 实现的 Mini Coding Agent 讲核心组件；文中“编码代理”与“编码框架”基本互换使用（严格说代理是模型驱动的决策循环，框架是提供上下文、工具与执行支持的软件脚手架）。 - 六个组件：实时仓库上下文、提示形态与缓存复用、结构化工具/校验/权限、上下文压缩与输出管理、会话记录/记忆与恢复、受限子代理委派；原文指出 Mini Coding Agent 源码用代码注释逐条标注了这六个组件与对应实现的映射。 ```text ############################## #### 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 ``` ### 5. 编码框架（Coding Harness）（续） - 注释对应关系：1\) 实时仓库上下文 → WorkspaceContext；2\) 提示形态与缓存复用 → build\_prefix、memory\_text、prompt；3\) 结构化工具、校验与权限 → build\_tools、run\_tool、validate\_tool、approve、parse、path、tool\_\*；4\) 上下文压缩与输出管理 → clip、history\_text； - 5\) 会话记录、记忆与恢复 → SessionStore、record、note\_tool、ask、reset；6\) 委派与受限子代理 → tool\_delegate。 ### 6. 编码框架（Coding Harness） - 所谓框架，一般指模型周围的软件层：组装提示、暴露工具、跟踪文件状态、应用编辑、运行命令、管理权限、缓存稳定前缀、存储记忆等。 - 如今使用 LLM 时，这一层决定了大部分用户体验，远胜于直接提示模型或用网页聊天界面（后者更像“与上传文件聊天”）。 - 作者认为当前各 LLM 的原生版本能力非常接近（如 GPT-5.4、Opus 4.6、GLM-5 左右），框架常是让某个 LLM 表现更好的区别因素。 - 作者推测：把最新的强开放权重模型（如 GLM-5）放进类似框架，表现可能接近 Codex 中的 GPT-5.4 或 Claude Code 中的 Opus 4.6；不过针对框架的额外后训练通常有帮助，例如 OpenAI 曾维护 GPT-5.3 与 GPT-5.3-Codex 两个变体。 - 作者以自己纯 Python 实现的 Mini Coding Agent 讲解核心组件，文中“编码代理”与“编码框架”基本互换使用（严格说代理是模型驱动的决策循环，框架是提供上下文、工具和执行支持的软件脚手架）。 - 六个组件：实时仓库上下文、提示形态与缓存复用、结构化工具/校验/权限、上下文压缩与输出管理、会话记录/记忆/恢复、受限子代理委派，代码注释中一一对应。 ### 7. 编码框架（Coding Harness）中的六个组件（代码标注） - 原文第 4 节末尾指出，六个组件的划分在 Mini Coding Agent 源码中以代码注释形式一一标注，方便对照具体实现。 - 注释列出的六项依次为：1\) 实时仓库上下文对应 WorkspaceContext；2\) 提示形态与缓存复用对应 build\_prefix、memory\_text、prompt。 - 3\) 结构化工具、校验与权限对应 build\_tools、run\_tool、validate\_tool、approve、parse、path、tool\_\* 等函数。 - 4\) 上下文压缩与输出管理对应 clip、history\_text；5\) 会话记录、记忆与恢复对应 SessionStore、record、note\_tool、ask、reset。 - 6\) 委派与受限子代理对应 tool\_delegate。 ### 8. 1. 实时仓库上下文 - 这可能是最明显也最重要的组件。 - 用户说“修好测试”或“实现 xyz”时，模型应知道自己在不在 Git 仓库里、当前分支、哪些项目文档可能含指令等。 - “修好测试”不是自包含指令：若代理看到 AGENTS.md 或 README，可得知该跑哪条测试命令；知道仓库根目录和布局就能找对地方而不是猜。 - git 分支、状态和提交能补充信息，说明当前有哪些改动在进行、应聚焦何处。 - 要点：代理先收集“稳定事实”作为工作区摘要，再结合用户请求，避免每条提示都从零、无上下文开始。 ### 9. 2. 提示形态与缓存复用 - 有了仓库视图后，问题是如何把信息喂给模型；若每次用户查询都把工作区摘要重新组合、重新处理，相当浪费。 - 编码会话是重复的：代理规则、工具描述、工作区摘要通常基本不变，主要变化是最新用户请求、近期会话记录和可能的短期记忆。 - 聪明的运行时不会每轮把所有内容重建成一个没有区分的巨型提示，而是构建稳定的提示前缀，再叠加变化的会话状态。 - “稳定提示前缀”通常含通用指令、工具描述和工作区摘要，若无重要变化就不该每轮重算。 - 更新更频繁的部分（短期记忆、近期会话记录、最新用户请求）每轮刷新；缓存的核心就是尽量复用那段稳定前缀。 ### 10. 3. 工具的访问与使用 - 工具访问和使用是体验从聊天转向代理的地方：普通模型只能用文字建议命令，而编码框架中的 LLM 应能真正执行命令并取回结果。 - 框架通常不给模型随意发挥语法的空间，而是提供预定义的、有名称、有明确输入与边界的允许工具清单（但像 Python subprocess.call 之类也可在清单内，使代理能执行任意多 shell 命令）。 - 工具使用流程：模型发出结构化动作，框架校验、可选地请求批准、执行，并把有界的结果回灌进循环。 - 在 Mini Coding Agent 中，模型须选择框架认识的动作（列文件、读文件、搜索、跑 shell 命令、写文件等），并按框架可检查的形状提供参数。 - 校验包括：这是已知工具吗、参数是否有效、是否需要用户批准、请求路径是否在工作区内；全部通过后才真正执行。 - 这些检查既提升可靠性（模型不会执行完全任意的命令），也通过路径检查把文件访问限制在仓库内；框架是给模型更少自由，同时提升可用性。 ### 11. 4. 最小化上下文膨胀 - 上下文膨胀不是编码代理独有的问题，而是 LLM 的通病；上下文虽越来越长，但仍昂贵，且大量无关信息会引入噪声。 - 编码代理在多轮会话中更易膨胀，因为重复读文件、冗长的工具输出和日志很多；若运行时全保真保留，很快会用光上下文词元。 - 好的编码框架在单纯截断或摘要之外，会更精细地处理上下文膨胀。 - 压缩策略一：截断（clip），缩短长文档片段、大工具输出、记忆笔记和会话记录条目，防止某段啰嗦文本独占提示预算。 - 策略二：会话记录压缩或摘要，把完整会话历史转成较小的可提示摘要。 - 关键技巧是近期事件保留得更丰富（更可能与当前步骤相关），较早事件更激进地压缩；同时对早先读过的文件去重，避免因为之前读过多次就一直重复看到同一内容。 ### 12. 4. 最小化上下文膨胀（续） - 作者认为这是好的编码代理设计中被低估、无聊的部分：很多表面上的“模型质量”其实是上下文质量。 ### 13. 5. 结构化的会话记忆 - 上一节讲提示期如何使用历史、如何构建紧凑会话记录，问题是在下一轮把多少过去放回模型；重点是压缩、截断、去重和近期性。 - 本节讲历史在存储期的结构：代理长期保留什么作为永久记录；重点是把更完整的会话记录作为持久状态，同时有一层更轻、会被修改压缩而非只追加的记忆。 - 代理至少把状态分两层：工作记忆（代理显式维护的小型蒸馏状态）与完整会话记录（覆盖所有用户请求、工具输出和 LLM 响应）。 - 两个主要会话文件通常以 JSON 存在磁盘上：完整记录可让关闭代理后恢复；工作记忆是当前最重要信息的蒸馏版本，与紧凑会话记录相关但略有分工。 - 紧凑会话记录用于提示重建，给模型压缩的近期历史视图，使其不必每轮看完整记录；工作记忆用于任务连续性，维护当前任务、重要文件、近期笔记等小摘要。 - 最新用户请求连同 LLM 响应和工具输出，会在下一轮作为“新事件”同时记录到完整记录和工作记忆中。 ### 14. 6. 用（受限的）子代理做委派 - 代理有了工具和状态之后，一个有用的能力是委派：把某些工作并行拆成子任务交给子代理，加快主任务。 - 例如主代理正在做一件事，却仍需要旁支答案：哪个文件定义了某个符号、某个配置写了什么、某测试为何失败；把这类事情拆成有界子任务比让一个循环承担所有线索更好。 - 在作者的 mini coding agent 中实现较简单，子代理仍同步运行，但基本思路相同。 - 子代理必须继承足够上下文才能真正干活；但若不加限制，就会出现多个代理重复劳动、改同一批文件、再派生子代理等问题。 - 设计难点不只是如何派生，还包括如何约束：子代理继承足够上下文，同时被约束（如只读、限制递归深度）。 - Claude Code 长期支持子代理，Codex 较晚加入；Codex 通常不强制子代理只读，而是让它们继承主代理的大部分沙箱和审批设置，边界更多在于任务范围、上下文和深度。 ### 15. 组件小结 - 上述各组件在实现上互相交织较深，逐条讲解是为了帮助建立编码框架如何工作的整体心智模型。 - 也说明了相比简单的多轮聊天，它们为什么能让 LLM 更有用。 - 若想看用简洁极简 Python 代码实现的这些组件，可参考作者的 Mini Coding Agent。 ### 16. 与 OpenClaw 相比如何？ - OpenClaw 不是同类系统：它更像本地的通用代理平台（也能写代码），而不是专门的（终端）编码助手。 - 它与编码框架仍有多处重叠：使用工作区里的提示与指令文件（如 AGENTS.md、SOUL.md、TOOLS.md）；保留 JSONL 会话文件并含会话记录压缩与会话管理；能派生辅助会话和子代理等。 - 区别在侧重点：编码代理针对一个人在仓库中让助手检查文件、编辑代码、高效运行本地工具而优化；OpenClaw 更针对跨聊天、渠道和工作区运行许多长期存活的本地代理，编码只是其中一项重要负载。 ### 17. 评论区（关于本文的讨论） - 这两节都是文章末尾的评论区与订阅页脚，不含正文技术内容：第 1 节是读者 Aditya Sharan 于 4 月 4 日的留言，问 Sebastian Raschka 是否读过 Claude Code 的源码，并称时间点“相当吻合”。 - Raschka 对该留言作了 1 条回复，原页面只显示“1 reply”链接，未展开回复内容。 - 另一位读者于 4 月 5 日留言，把编码智能体与交易系统类比：大家只盯着模型（信号、指标、“优势”），但决定成败的是模型外面那层 harness（运行框架）。 - 按该读者的说法，harness 提供的是执行规则、对过去错误的记忆、行为约束和过滤噪音以聚焦重点的机制；模型相当于直觉，harness 相当于纪律，真正的表现来自二者长期互动。 - 该读者据此解释：面对同一市场、同一位置、同一形态，有人能稳定获利、有人来回折腾，差别不在看到什么，而在围绕所见建立起来的系统。 - 页面显示“还有 61 条评论”的入口，并标注“暂无文章”，其余评论内容未呈现。 ### 18. 更多内容 / 页脚 - 第 2 节只有“Ready for more?”的订阅提示和页脚：© 2026 Raschka AI Research \(RAIR\) Lab LLC，以及隐私政策、服务条款、数据收集声明等链接。 - 页脚还包含 Substack 的注册入口、App 下载链接和平台介绍，均属与正文无关的导航内容，不涉及文章的技术论点。 --- 来源：LearnMap · 学径（https://oplearnx.com）