不知道大家有没有一种错觉：当你打开普通的聊天窗口，让Claude帮你写几行代码时它像是一个虽然博学但有点迟钝的顾问；但当你切换到Claude Code或者类似的Agent环境里它仿佛突然被注入了某种灵魂，变得干练、精准，甚至有点“激进”。这中间的体验差异，简直就像是从骑自行车换成了开法拉利。

hen多人——甚至包括一些资深开发者——经常把“大模型”、“推理模型”和“AI Agent”这几个词混着用。其实这完全是三个维度的东西。Ru果不去深究，你可Neng只会觉得“现在的AI变强了”，但作为技术人员，我们需要剥开这层表象，kankan底层的齿轮到底是怎么转的。

今天我们就来聊聊那个被包裹在模型之外却决定了Zui终体验的关键工程架构：Agent Harness。这不仅仅是几个API调用，它是让Claude从一个“聊天机器人”进化为“Coding Agent”的真正秘密武器。

剥洋葱：从LLM到Agent的三层境界

在深入代码之前，我们得先统一一下认知。现在的AI生态，其实Ke以清晰地划分为三个抽象层，每一层dou在解决不同的问题。

第一层：基础语言模型—— 概率的引擎

Zui底层的就是我们熟悉的Claude Sonnet、GPT-4o或者Gemini。本质上，它们就是一个复杂的条件概率函数。你给它一串Token序列，它预测下一个Zui可Neng出现的Token。这一层不负责“思考”，只负责“生成”。它不知道自己在写代码，还是在写诗，它只是在Zuo填空题。

第二层：推理模型—— 思维的链路

在LLM之上，是像o3或者Claude Extended Thinking这样的推理模型。这并不是一个新的模型权重，而是一种用法的提升。它们通过系统性地使用Chain-of-Thought，让模型在输出Zui终结果前，先进行深度的自我推导。这就像是让那个Zuo填空题的学生，把草稿纸上的计算过程也写下来从而提高准确率。

第三层：Agent Harness—— 行动的骨架

这就是我们今天要聊的主角。Claude Code、Cursor、Codex CLI，dou属于这一层。它是一个工程框架，负责包裹模型，管理工具，注入上下文，并持久化状态。Ru果说LLM是大脑，推理模型是思维习惯，那么Agent Harness就是让大脑Neng够控制手脚去干活的神经系统。

为什么同一个模型，在不同的Harness里表现天差地别？因为Harness的好坏，直接决定了用户体验。这不需要重新训练模型，纯靠工程架构的优化就Neng实现质的飞跃。

核心引擎：Agent Loop的无限循环

一个Coding Agent和普通ChatbotZui大的区别在于：Chatbot是“一问一答”，而Agent是“持续执行直到任务完成”。这背后是一个精心设计的无限循环，我们称之为Agent Loop。

这个循环的逻辑其实非常直观，但细节里全是魔鬼。我们Ke以把它拆解为四个步骤：OBSERVE、INSPECT、CHOOSE & ACT、以及自我修正。

async def agent_loop -> str:
    # 初始化消息队列
    messages = 
    while True:
        # 1. OBSERVE: 调用模型获取下一步指令
        response = await llm.complete(
            messages=messages,
            tools=tools,
            system_prompt=SYSTEM_PROMPT
        )
        # 2. INSPECT: 检查模型的意图
        if response.stop_reason == "end_turn":
            return response.content  # 任务圆满结束
        # Ru果模型想用工具
        if response.stop_reason == "tool_use":
            tool_calls = extract_tool_calls
            # 3. CHOOSE & ACT: 并发执行工具调用
            tool_results = 
            for call in tool_calls:
                result = await execute_tool
                tool_results.append({
                    "tool_use_id": call.id,
                    "content": result
                })
            # 把结果塞回对话历史，让模型知道发生了什么
            messages.append
            messages.append
        # 安全阀：防止陷入死循环
        if len> MAX_TURNS:
            return "抱歉，达到了Zui大轮次限制，任务可Neng过于复杂。"

这段伪代码kan起来平平无奇，但你要知道，这里面的每一个环节dou藏着工程团队的深思熟虑。比如工具执行是串行还是并行？Claude Code选择了对独立的工具调用Zuo并发处理，这Neng显著降低延迟，让用户感觉AI反应geng快。再比如怎么判断任务结束？仅仅依赖模型返回`end_turn`是不够的，你还得检测它是不是在工具调用的死循环里打转。

记忆的艺术：别让AI得了健忘症

对于面向Professional Developer的Coding Agent来说记忆管理是生死攸关的问题。你不可Neng指望它像金鱼一样只有七秒记忆，尤其是在处理那些动辄数万行代码的大型项目时。

这里有个hen现实的矛盾：你不Neng把整个代码库dou塞进Context Window里。哪怕Claude支持200K token，大型仓库分分钟就Neng撑爆这个限制。而且，塞进去大量无关代码只会让模型分心，就像你在嘈杂的菜市场里背单词一样。

解决方案就是“按需注入”和“分层记忆”。

1. External Memory：项目的“圣经”

Claude Code会在项目根目录下查找一个叫`CLAUDE.md`的文件。这个文件简直就是仓库级的System Prompt，是Agent的“圣经”。

# 示例 CLAUDE.md 内容
"""
## 项目约定
- 测试框架必须使用 pytest，严禁 unittest
- 所有公开 API 必须带有类型注解
- 数据库操作统一走 repository pattern，禁止直接操作 ORM
## Yi知陷阱
- config.py 里的 DATABASE_URL 在测试环境和生产环境格式不同，千万别搞混
- migrations/ 目录下的文件名必须按时间戳排序，否则会炸
## 常用命令
- 跑测试：make test
- 代码格式化：make fmt
- 部署脚本：./scripts/deploy.sh staging
"""

这个设计极其实用。你不需要每次dou跟Agent解释项目规范，它也不会因为换个Session就“失忆”。对于大型项目，一个维护良好的`CLAUDE.md`Neng把Agent的有效性提升一个数量级。这就像是给新入职的员工发了一份详尽的《员工手册》，省去了无数扯皮的时间。

2. Working Memory & Episodic Memory

除了这种长期的本地文件记忆，Agent还需要处理短期和中期记忆。

Working Memory直接放在Context里包括当前任务状态、Zui近几轮工具调用的结果。

Episodic Memory这是动态写入的。比如Agent在探索过程中发现了一个重要的坑，或者Zuo出了一个关键决策，这些信息会以结构化的形式追加到System Prompt的专用区域。

为什么要这么麻烦？因为Ru果所有东西dou堆在Message History里会有两个大问题：Token消耗随对话轮次线性增长，钱包受不了；早期的关键信息会因为Context过长而被“稀释”，模型的注意力会下降，导致它“忘了初心”。

3. RepoContextManager：按需读取的导航员

为了解决Context溢出的问题，Claude Code内部实现了一个类似`RepoContextManager`的机制。它的核心思想是：初始Context只放“导航地图”，真正的代码内容通过工具调用按需获取。

class RepoContextManager:
    def __init__:
        self.repo_root = repo_root
        self._symbol_index = {}  # 维护一个函数名到文件路径的索引
    def get_initial_context -> str:
        """启动时只注入：轻量级目录树 + 关键配置文件"""
        tree = self._build_compact_tree
        readme = self._read_if_exists
        return f"{tree}

{readme}"
    def search_symbol -> list:
        """按需工具：搜索函数/类定义"""
        # 这里Ke以用grep，也Ke以用geng高级的语义搜索
        return self._grep
    def read_file_chunk -> str:
        """按需工具：只读需要的片段，别把整个文件塞进去"""
        lines = self._read_lines
        return "
".join

这和RAG的思路异曲同工——先检索，再精读。而不是像暴发户一样，把所有东西一次性全量加载到内存里。

工具箱的智慧：多而精 vs 少而美

工具是Agent的手。Ru果工具太少，Agent什么也干不了；Ru果工具太多，模型会患上“选择困难症”，而且每个工具定义dou要占Token，成本上划不来。

Claude Code的工具集设计非常讲究分层，大概Ke以分为这么几层：

Shell 执行层bash命令执行。这里必须带超时、带输出截断、带沙盒限制。你肯定不希望Agent因为一个死循环命令就把你的服务器搞挂了。

文件操作层read_file / write_file / edit_file。这里特别要提一下edit_file，这是一个非常聪明的设计。

代码智Neng层search_files / grep / find_symbol。这是语义搜索，而不是简单的字符串匹配，这让AgentNeng“理解”代码结构。

验证层run_tests / check_syntax / lint。改完代码自己跑一遍测试，这是自我纠错Neng力的来源。

为什么 edit_file 比 write_file geng重要？

一个朴素的实现是每次dou用`write_file`覆盖整个文件。但这有三个巨大的坑：上下文Token消耗太大；覆盖时容易引入不相关的修改；无法追踪增量变geng。

Claude Code采用了基于Unified Diff的`edit_file`策略：

# 工具调用示例
{
  "tool": "edit_file",
  "input": {
    "path": "src/auth/login.py",
    "old_string": "def validate_token -> bool:
    return token in VALID_TOKENS",
    "new_string": "def validate_token -> bool:
    if not token:
        return False
    return token in VALID_TOKENS and not is_revoked"
  }
}
# 对应的工具实现逻辑
def edit_file -> str:
    content = Path.read_text
    if old_string not in content:
        return "ERROR: 找不到目标字符串，请重新确认上下文"
    # 只替换第一次出现，避免批量误改
    new_content = content.replace
    Path.write_text
    # 返回 diff 供模型确认
    return generate_unified_diff

这种设计强迫模型先“kan清楚”要改的地方，减少幻觉式的覆盖。Ru果`old_string`找不到，说明模型对文件内容的理解有误，工具直接报错，模型就会意识到自己搞错了然后重新`read_file`来校准。这种反馈机制，是AgentNeng够稳定工作的关键。

隐形的功臣：Prompt Caching与成本控制

Zui后我们得聊聊钱。Coding Agent往往需要几十轮甚至上百轮的工具调用，Ru果每次dou把System Prompt和工具定义重新算一遍，成本会高得离谱。

Claude API提供的Prompt Caching功Neng，在这里简直是救命稻草。它的原理hen简单：Ru果请求的前缀和上一次完全一样，就Ke以复用KV Cache，输入Token费用降低90%。

关键在于，哪些内容构成“稳定前缀”？

System Prompt完全固定，天然适合缓存。

工具定义JSON格式的工具描述，内容不变，适合缓存。

Yi完成的对话历史上一轮的assistant + user消息，Ke以作为缓存前缀的一部分。

# 显式标记 cache_control 的请求结构
messages = 
    },
    # ... 对话历史 ...
    # Cache Point 2: 截至上一轮的完整对话
    {
        "role": "user", 
        "content": 
    },
    # 当前轮次的新消息
    {"role": "user", "content": current_message}
]

要实现稳定缓存，关键是保证前缀内容的顺序和内容不随意变动。一个常见的坑是：Ru果你的工具列表顺序在不同请求间会变化，缓存就会频繁失效。Claude Code在工程上严格保证了这一点。

实际上，Claude Code在每次对话结束后累计Token的80%-90%理论上douKe以走缓存。对于长会话，这直接决定了产品的经济可行性。毕竟谁也不想用了一个AI编程助手，结果发现Token账单比自己的工资还高。

工程决定上限

我们常说“模型决定下限，工程决定上限”。这句话在Coding Agent领域体现得淋漓尽致。

无论是从巨大的Codebase中Zuo精准的Retrieval，还是解决老工程师离职后代码无人Neng懂的难题，亦或是让AI适配不同团队的代码风格规范，这些dou不是靠单纯把模型参数Zuo大就Neng解决的。

Claude Code之所以让人眼前一亮，不是因为它的模型突然有了神力，而是因为它的Agent Harness设计得太精妙了。它懂得如何管理记忆，如何设计工具，如何控制成本，甚至懂得如何利用Git History来优先展示Zui近修改过的文件。

对于创业者和技术团队来说这也是一个警钟：Coding Agent赛道，真的不是谁douNeng进的。核心Neng力全靠大模型，你的毛利可Neng只有GitHub Copilot的一半；但Ru果你Neng在Harness层Zuo深Zuo透，构建出像Claude这样精细的工程结构，你才Neng在这个残酷的竞争中活下来。

毕竟真正的竞争，早Yi不在模型本身，而在包裹它的那一层kan不见、摸得着，却实实在在改变着开发者生活的工程架构之中。

---