超越大模型：揭秘 Coding Agent 的六大核心架构组件

1. 文章引言：为什么你的 LLM 还是写不好代码？

作为开发者，你可能也经历过这种“幻灭感”：虽然 GPT-4 或 Claude 3.5 在编写孤立的函数或解决 LeetCode 题目时表现惊人，但当你把它丢进一个真实的、拥有数千行代码和复杂依赖的生产级仓库时，它往往会变得不知所措。你输入“修复测试用例”，它却因为不知道测试框架、找不到文件路径或看不见 .env 配置而开始“幻觉”。

为什么最强大的模型在面对复杂代码库时，单纯的聊天界面（Chat Interface）依然显得力不从心？

答案在于：模型本身只是“引擎”，而真正的生产力飞跃源于其外部的“Agent Harness”（代理铠甲/开发框架）。

正如 Sebastian Raschka 博士所指出的，像 Claude Code 或 Codex 这样的工具之所以比原生模型更强大，是因为它们被包裹在一层精心设计的“编码铠甲”中。本文将从 AI 架构师的角度，深度拆解 Coding Agent 的六大核心支柱，揭示如何通过系统工程将一个黑盒模型转变为真正的 AI 程序员。

2. 核心隐喻：LLM、推理模型与 Agent 的本质区别

为了理解架构设计，我们必须首先理清模型与系统之间的层级关系。我们可以沿用 Raschka 经典的“汽车”类比：

LLM (大语言模型)： 原始的引擎。它负责生成下一个 Token，提供最基础的预测能力。
推理模型 (Reasoning Model)： 一台经过强化的性能引擎。它通过增加“推理时计算”（Inference-time compute），生成中间思维链（Chain-of-thought）进行自我验证（Self-verification）和答案搜索。
Agent (代理)： 整车的控制系统。它是一个围绕模型运行的控制回路（Control Loop），决定何时观察环境、调用何种工具。
Agent Harness (代理铠甲/框架)： 支撑系统运行的软件脚手架。它管理着上下文、提示词打包、权限管控和状态流转。
Coding Harness (编码铠甲)： Agent Harness 的特化版本。它是专为软件工程设计的脚手架，负责处理差异比对（Diffs）、仓库导航及测试执行等特定任务。

“代理是系统在环境中反复调用模型的过程。大模型是引擎，推理模型是加强版引擎，而代理铠甲则帮助我们驾驭这些引擎。” —— Sebastian Raschka

在模型能力逐渐趋同的今天，Harness 的设计成为了决定胜负的关键。一个优秀的编码铠甲能让模型在特定的开发场景中表现得远超其原生状态。

3. 突破口一：实时仓库上下文 (Live Repo Context)

在没有上下文的情况下，要求 Agent “修复测试”是毫无意义的。Agent 必须首先具备“感知”能力。

Coding Agent 的第一步不是急着推理，而是构建一个准确的**“环境画像” (Workspace Summary)**。这涉及到对“稳定事实”的自动收集：

Git 状态： 当前分支是什么？哪些文件已被修改？
项目结构： 识别项目根目录，理解文件布局。
特定指令： 自动阅读 README.md 或项目特有的 AGENTS.md。这些文件可能包含特定的测试指令、依赖管理方式或编码规范。

这种预先构建的画像确保了 Agent 在接收用户请求时，已经拥有了对仓库现状的深刻理解，避免了盲目猜测。

4. 突破口二：提示词形态与缓存重用 (Prompt Shape and Cache Reuse)

一个高效的 Agent 必须是“智能运行时”，它需要同时兼顾响应速度与 Token 成本。

在多轮会话中，如果每次都全量重传整个仓库摘要和工具描述，会造成巨大的延迟和资源浪费。优秀的架构会采用稳定前缀 (Stable Prefix) 技术：

不可变前缀： 将通用的系统指令、工具描述和相对稳定的仓库摘要作为前缀。这部分内容在会话中极少变动，非常适合进行缓存 (Caching)。
可变状态： 仅在每一轮迭代中更新最近的对话副本、短时记忆和用户的新请求。

通过这种“动静分离”的提示词设计，Agent 能够实现快速响应，并在长会话中保持经济高效。

5. 突破口三：受控的工具访问与执行 (Tool Access and Use)

Agent 与普通聊天机器人的核心区别在于它能通过“代理循环”产生实效。Raschka 将这个循环拆解为四个关键阶段：观察 (Observe)、检查 (Inspect)、选择 (Choose) 和 执行 (Act)。

在这个过程中，Harness 扮演着严密的监管者角色，确保每一个动作都在安全边界内：

发出动作： 模型根据当前的观察和检查结果，发出结构化的指令（如 read_file）。
安全性校验（Path Validation）： Harness 必须程序化地检查指令。例如，验证 Agent 请求的文件路径是否确实在当前工作空间内，防止其越权访问系统文件。
用户审批（Approval Gating）： 在执行危险操作（如 run_shell_command 或修改代码）前，Harness 会挂起任务并请求用户确认。
结果回传： 在沙盒环境中执行动作后，将受限的输出结果反馈给模型，进入下一个循环。

典型的 Coding Agent 必备工具集包括：

list_files: 探索目录结构。
read_file: 读取文件具体内容。
run_shell_command: 执行测试或构建脚本。
write_file: 应用代码变更。

6. 突破口四：对抗上下文膨胀 (Minimizing Context Bloat)

随着会话深入，反复的文件读取、冗长的日志和工具输出会产生大量的“信息噪音”。

为了维持上下文质量，优秀的编码铠甲会执行以下优化：

裁剪 (Clipping)： 自动缩短过长的文档片段或工具日志，防止单一输出占据过多的 Token 预算。
去重 (Deduplication)： 如果模型在同一会话中多次读取同一文件，Harness 会在上下文中去除冗余内容，确保模型不被重复信息误导。
对话压缩 (Transcript Reduction)： 对较早的会话事件进行总结，保留最近事件的细节。

这种“断舍离”确保了模型始终聚焦于最相关的核心信息。

7. 突破口五：结构化会话内存 (Structured Session Memory)

为了实现任务的“断点续传”，架构必须对内存进行精细化的结构设计。Raschka 强调了两个具有不同功能的层级：

工作记忆 (Working Memory)： 用于任务连续性。这是一个小而精简的、显式维护的状态，存储当前任务的阶段性结论、重要文件路径和笔记。
压缩副本 (Compact Transcript)： 用于提示词重组。它为模型提供最近历史的压缩视图，让模型了解对话脉络。
完整副本 (Full Transcript)： 这是一个持久化的、存储在磁盘上的 JSONL 文件，记录了所有原始请求和模型响应。

即使 Agent 重启，这些结构化文件也能让它迅速找回状态，保持开发流的连贯。

8. 突破口六：子代理的委派机制 (Delegation with Subagents)

处理复杂任务时，单一循环往往效率低下。通过委派机制，主代理可以将特定的子任务（如“查找特定配置定义”）分派给子代理 (Subagents)。

委派成功的关键在于如何“约束”子代理：

受限边界： 子代理通常以只读模式运行，且被严格限制递归深度。这防止了子代理因无限创建自己的下属而导致资源失控。
继承上下文： 子代理继承主代理的部分上下文信息，在受限范围内并行化搜索或验证任务，从而加速整体目标的达成。

这种设计与 OpenClaw 等通用 Agent 平台不同，它更侧重于在本地开发环境下的瞬时高并发协作。

9. 结论：Agent 是编程的未来，而非 LLM

总结来说，单纯的模型（LLM）只是半成品，Coding Harness 才是将其转化为生产力工具的关键层。通过对上述六个组件的深度优化，我们不仅是在使用一个模型，而是在运行一个由模型驱动的复杂软件系统。

如果你对这些组件的底层实现感兴趣，我强烈建议去研究一些极简的 Python 实现（如 Sebastian Raschka 的 mini-coding-agent）。你会发现，所谓的“模型质量”，很大程度上取决于“上下文质量”和“反馈回路的严密性”。

未来的程序员可能不再仅仅是代码的编写者，而更多地成为了 Harness 的优化者。当铠甲变得足够完美，我们或许不再关心底层引擎究竟来自哪家大厂，因为真正的竞争力，已经沉淀在如何驾驭引擎的系统设计之中。