Claude Code 和 Codex CLI 为什么比直接在聊天框里用同款模型强那么多？答案不在模型本身，而在包裹在模型外面的那层「Coding harness」（编程运行框架）。本文拆解编程智能体的六大核心组件，帮你理解 Agent 为什么比裸模型好用，以及如何构建自己的编程智能体。

核心概念：模型 vs 智能体

先厘清三个关键概念：

• 大语言模型 (LLM): 基础模型，本质是预测下一个词的引擎
• 推理模型 (Reasoning Model): 经过特殊训练的 LLM，投入更多算力做中间推理和自我验证
• 智能体 (Agent): 模型 + 工具 + 记忆 + 环境反馈的循环系统

一个类比：LLM 是普通发动机，推理模型是爆改后的高马力发动机，Agent harness 则是帮你驾驭发动机的整车系统。

基础模型、推理模型与 Agent 之间的关系。Agent 在特定环境里不断循环调用模型，处理真实开发中的复杂任务。

组件一：实时代码仓库上下文

这是最关键也最基础的组件。当你说「修一下测试代码」时，模型不能两眼一抹黑。它需要知道：

• 当前是否在 Git 仓库里，在哪个分支
• 项目有哪些文档、开发规范（如 AGENTS.md、README）
• 代码库的文件结构

Coding harness 在收到指令后，会先收集这些信息，生成一份「工作区摘要」。这样模型面对每次提示时，都不是从零开始。

Coding harness 先生成工作区摘要，再与用户请求合并，为模型提供充分的上下文。

组件二：提示词缓存复用

收集了上下文后，怎么高效地喂给模型？如果每次都把全部信息重新拼一遍，算力和成本浪费巨大。

核心策略：把提示词拆成「稳定的」和「变化的」两部分：

• 稳定前缀（几乎不变）：系统指令、工具说明、工作区摘要 -- 缓存复用
• 变化部分（每轮更新）：短期记忆、近期对话、最新指令 -- 每次重建

提示词分为稳定前缀和变化部分。主流 LLM API 都支持 Prompt Cache，缓存稳定前缀可以大幅降低成本。

组件三：工具的接入与调用

装在 Coding harness 里的 LLM 不只是提建议，它还能实打实地执行命令。但不是随意执行 -- Harness 提供预定义的工具箱，每个工具都有明确的输入要求和边界。

完整的工具调用流程：

1. 模型输出结构化的动作请求
2. Harness 验证动作（是否在白名单？参数是否合法？）
3. 高危操作需要人工批准
4. 执行动作，返回结果给模型

# Harness 的安全检查逻辑
def validate_tool(action):
    if action.tool not in KNOWN_TOOLS:
        return reject("未知工具")
    if not action.params_valid():
        return reject("参数非法")
    if action.is_dangerous() and not user_approved():
        return reject("需要人工批准")
    if action.path_outside_repo():
        return reject("路径越界")
    return execute(action)

组件四：上下文瘦身

编程智能体比普通聊天更容易「吃撑」上下文窗口，因为它频繁读取文件，工具输出往往又臭又长。优秀的 Harness 至少用两招应对：

• 裁剪 (Clipping): 无情截断过长的文档片段和工具输出
• 对话精简 (Transcript Reduction): 把完整历史提炼成轻量级摘要

核心秘诀：越近的事情保留细节越多，越久远的压缩越狠。早期读取的重复文件要做去重处理。

组件五：结构化会话记忆

编程智能体把状态分为两层：

工作记忆和完整记录通常以 JSON 格式存储在硬盘上，关闭智能体后下次打开可以无缝恢复。

组件六：任务委派与受限子智能体

把某些子任务分给子智能体并行处理，可以大幅加速主线任务。但关键在于约束：

• 子智能体只能只读访问文件（或限制修改范围）
• 限制递归深度，防止无限生成子智能体
• 限制上下文大小和执行时间

子智能体既要继承足够的上下文来干活，又必须受到严格约束，这是设计上最考验功力的地方。

动手实践

Sebastian Raschka 用纯 Python 从零构建了一个 Mini Coding Agent，把上述六大组件全部实现，没有任何外部依赖。

• 项目地址: https://github.com/rasbt/mini-coding-agent
• 核心文件: mini_coding_agent.py，代码中用注释标注了六大组件的对应位置

如果你想深入理解编程智能体的内部机制，阅读这个项目的源码是最好的起点。

Mini Coding Agent 是一个极简但功能完整的编程智能体实现。