编程 Agent 的组成部件

中文精读

原文约 3,893 词 · 18 节

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 下载链接和平台介绍，均属与正文无关的导航内容，不涉及文章的技术论点。