Agent Harness 架构全面解读：模型是司机，Harness 才是车

当我们说「AI Agent」时，大多数人想到的是模型本身——Claude、GPT、Gemini。但真正让 Agent 能在现实世界中工作的，不是模型的智能，而是包裹在模型外面的那层「Harness」（执行框架）。Harness 给模型提供工具、记忆、权限和执行环境，就像汽车之于司机。本文从 0 到 1 拆解 Harness 工程的核心架构、20 个关键机制、实战应用和未来方向。

188K

ECC Stars

62K

learn-claude-code

20

核心课程

125K

Claude Code Stars

什么是 Harness？为什么它比模型更重要？

在 AI Agent 领域，有一个被广泛误解的概念：人们以为「构建 Agent」就是训练模型或者用 prompt 编排工作流。但事实上，绝大多数开发者做的事情是构建 Harness——给模型提供一个可以操作的执行环境。

这个概念由 shareAI-lab 的 learn-claude-code 项目（62K Stars）明确提出，并被 ECC（188K Stars）等项目验证和扩展：

核心公式

Agent 产品 = 模型（驱动智能）+ Harness（执行环境）

模型是司机，Harness 是车。司机决定去哪里，但没有车就哪也去不了。Harness 包含五大要素：

模型（Model）

• 感知、推理、决策

• 训练得来，不可编码

• 决定「做什么」

• Claude / GPT / Gemini

Harness（框架）

• 工具 + 知识 + 权限

• 工程构建，持续优化

• 执行「怎么做」

• Claude Code / Cursor / Codex

2

Agent Loop：一切的起点

整个 Harness 架构的核心是一个极其简洁的 Agent Loop——一个 while True 循环。模型调用工具就继续循环，不调用就退出。就这么简单。

Python核心 Agent Loop

def agent_loop(messages): while True: response = client.messages.create( model=MODEL, system=SYSTEM, messages=messages, tools=TOOLS, ) messages.append({"role": "assistant", "content": response.content}) if response.stop_reason != "tool_use": return # 模型说"做完了"，退出 # 执行模型要求的工具，收集结果 results = [] for block in response.content: if block.type == "tool_use": output = TOOL_HANDLERS[block.name]( **block.input) results.append({ "type": "tool_result", "tool_use_id": block.id, "content": output, }) messages.append({"role": "user", "content": results})

这段代码就是 Claude Code、Codex CLI 等所有 Agent 产品的骨架。后续所有 20 个机制，都是在这个循环外面叠加的——循环本身永远不变。模型决定何时调用工具、调用哪个工具、何时停止；代码只负责执行模型的指令。

💡 INSIGHT

learn-claude-code 的核心理念是「循环属于 Agent，机制属于 Harness」。你永远不应该重写循环——所有新功能（工具、权限、记忆、子Agent）都是围绕这个循环添加的扩展。这也是为什么标题叫「Bash is all you need」——一个工具加一个循环就是一个完整的 Agent。

Harness 五层架构

Harness 五层架构：从循环到记忆，层层解耦

第 1 层：Agent Loop（循环引擎）

while True + stop_reason 判断。模型说用工具就执行，说完了就退出。整个 Harness 的心跳，永不修改。

第 2 层：Tool Dispatch（工具分发）

一个字典映射 tool_name → handler。添加新工具只需注册一个 handler，循环代码不变。Claude Code 有 40+ 工具：Bash、Read、Write、Edit、Grep、Glob、Agent、WebSearch 等。

第 3 层：Permission（权限管控）

每次工具调用前，权限系统进行三级判定：自动放行（安全操作如 Read）、需要审批（如 Bash 执行命令）、直接拒绝（如删除系统文件）。先设边界，再给自由。

第 4 层：Context Management（上下文管理）

上下文总会填满——必须有清理策略。四级压缩：工具结果预算裁剪 → 微压缩（单轮摘要）→ 片段压缩 → 全量自动压缩。子 Agent 隔离防止噪声泄漏。System Prompt 运行时动态拼装。

第 5 层：Memory + Skills（记忆与技能）

持久记忆三步走：选择（什么值得记）→ 提取（抽取结构化信息）→ 整合（合并同类、删除过期）。Skills 按需加载，不预加载；复杂任务后自动创建新 Skill。

20 课 Harness 工程全景

learn-claude-code 将 Harness 工程拆解为 20 节渐进式课程，每节只增加一个机制。我们将其分为六大阶段：

20 课渐进式学习路径

5

关键机制深度拆解

Context Compaction（上下文压缩）

四级策略：toolResultBudget（截断单次工具输出）→microCompact（单轮摘要）→snipCompact（多轮片段压缩）→autoCompact（全量自动压缩）。让 Agent 可以进行无限长会话。

Subagent（子 Agent）

生成全新的 messages[]，隔离上下文。子 Agent 做侧面工作（搜索、分析），只带回结果。主 Agent 的上下文不会被搜索噪声污染。这是「上下文即注意力」的核心原则。

Hooks（钩子系统）

在PreToolUse和PostToolUse时机注入自定义逻辑——安全扫描、日志记录、Token 统计等。不修改核心循环，通过扩展点叠加功能。ECC 的 997+ 测试大量依赖 Hook 机制。

Worktree Isolation（工作树隔离）

每个 Agent Worker 在独立的 Git Worktree 中工作，互不干扰。TaskRecord 绑定目录 ID，任务与文件系统一一对应。这是多 Agent 并行的基础设施。

ECC：Harness 性能优化的工业级实践

ECC（188K Stars）是目前最大的 Harness 性能优化系统，由 Anthropic 黑客松获奖者 @affaan-m 开发。它不是重新造一个 Agent，而是在 Claude Code、Codex、Cursor 等现有 Harness上面叠加优化层。

7

实战：Harness 如何解决真实问题

理解了架构，来看看这些机制如何协同解决实际开发问题：

场景 1：跨文件大规模重构

TodoWrite先列出所有要改的文件和步骤 →Subagent并行处理独立的文件修改 →Worktree Isolation确保每个子任务在独立分支工作 →Task System追踪依赖关系，确保正确的合并顺序。

场景 2：生产环境 Bug 排查

Agent Loop接收问题描述 →Tool Use（Bash+Read+Grep）读日志、搜代码 →Error Recovery遇到权限问题自动尝试备选方案 →Memory记住这个 Bug 的模式，下次遇到类似问题直接应用修复。

场景 3：自动化巡检

Cron Scheduler每天凌晨触发 →Skill Loading加载安全扫描技能 →Background Tasks后台跑测试 →Hooks在 PostToolUse 时收集结果 → 异常时通过MCP发送通知。

开发者快速上手指南

想亲手实践 Harness 工程？三条路线：

1

从零学习：learn-claude-code

clone 仓库，从 s01 到 s20 跑一遍 code.py，每节课 30 分钟，20 节课掌握全部机制

2

直接应用：ECC

npm i -g ecc-universal 安装，即时获得 232 个 Skills + 60 个 Agent 的生产级配置

3

构建产品：Kode Agent

npm i -g @shareai-lab/kode 安装，一个基于 Harness 理念构建的开源编程 Agent CLI

Bash快速开始

# 学习路线 git clone https://github.com/shareAI-lab/learn-claude-code cd learn-claude-code pip install -r requirements.txt python s01_agent_loop/code.py # 从这里开始 # 生产应用 npm i -g ecc-universal # ECC 性能优化 npm i -g @shareai-lab/kode # Kode Agent CLI

未来发展方向

1. 从单 Agent 到 Agent 团队

s15-s18 已经铺设了多 Agent 协作的基础——邮箱通信、协议规范、自主认领、工作树隔离。下一步是更复杂的团队拓扑：层级式、网状式、专家委员会式的 Agent 组织结构。

2. 跨 Harness 统一标准

ECC 已经实现了跨 7 个 Harness（Claude Code/Codex/Cursor 等）的统一 Skills/Agents/Rules。MCP 协议的普及正在建立工具层的互操作标准。未来的 Harness 将像容器编排一样标准化。

3. 自进化 Harness

从 ECC 的 Continuous Learning（从会话中自动提取模式为 Skill）到 Hermes Agent 的 Curator（自动修剪 Skills 库），Harness 正在从「被动执行」走向「主动优化」。未来的 Harness 将能自主调整工具集、权限策略和上下文管理策略。

4. 轨迹数据飞轮

Harness 执行的每个动作序列都是训练信号。learn-claude-code 明确指出：「你的 Agent 在 Harness 中产生的真实部署轨迹，是微调下一代 Agent 模型的原材料。」这构成了模型→Harness→轨迹→更好的模型的正反馈循环。

🎯 TAKEAWAY

智能来自模型训练，不来自代码编排。但一个能工作的 Agent 产品，需要模型和 Harness 的结合。模型是司机，Harness 是车。最好的 Agent 产品，来自那些理解自己的工作是造车而不是造司机的工程师。把 Harness 造好，模型自然会发挥到极致。

学AI大模型的正确顺序，千万不要搞错了

🤔2026年AI风口已来！各行各业的AI渗透肉眼可见，超多公司要么转型做AI相关产品，要么高薪挖AI技术人才，机遇直接摆在眼前！

有往AI方向发展，或者本身有后端编程基础的朋友，直接冲AI大模型应用开发转岗超合适！

就算暂时不打算转岗，了解大模型、RAG、Prompt、Agent这些热门概念，能上手做简单项目，也绝对是求职加分王🔋

📝给大家整理了超全最新的AI大模型应用开发学习清单和资料，手把手帮你快速入门！👇👇

学习路线:

✅大模型基础认知—大模型核心原理、发展历程、主流模型（GPT、文心一言等）特点解析
✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑
✅开发基础能力—Python进阶、API接口调用、大模型开发框架（LangChain等）实操
✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用
✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代
✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经

以上6大模块，看似清晰好上手，实则每个部分都有扎实的核心内容需要吃透！

我把大模型的学习全流程已经整理📚好了！抓住AI时代风口，轻松解锁职业新可能，希望大家都能把握机遇，实现薪资/职业跃迁～

这份完整版的大模型 AI 学习资料已经上传CSDN，朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】