Harness 是什么 — 从聊天到编排

Harness 不是 wrapper，不是 prompt engineering，是 AI Agent 的操作系统

📝 本章目标

读完本章，你将了解：

1. AI Agent 系统经历了哪三代演进，以及每一代解决了什么问题
2. Harness 的精确定义——它由哪六大模块组成，边界在哪里
3. Claude Code 51 万行代码背后的全景架构
4. 本书的学习路径和最终产出

你可能已经用过 ChatGPT，也许还试过让 Claude 帮你写代码。你输入一段话，AI 给你一段回复，看起来很简单。但你有没有想过这样一个问题：

当你让 Claude Code 帮你重构一个项目时，它是怎么做到的？

它不只是”回答问题”——它会阅读你的代码、理解项目结构、修改文件、运行测试、发现错误后再修改。有时候它甚至会同时派出好几个”分身”并行工作。这背后不是一个简单的 API 调用，而是一整套精密的编排系统在运转。

这个编排系统，就是本书的主角——Harness。

如果 LLM 是引擎，那么 Harness 就是整辆车：底盘、变速箱、方向盘、刹车、安全气囊，一个都不能少。光有引擎，你哪也去不了。

Agent 系统的三代演进

要理解 Harness，我们先回头看看 AI Agent 是怎么一步步走到今天的。这不是学术考古，而是帮你建立一个坐标系：知道过去踩过什么坑，才能理解现在为什么要这样设计。

第一代：Prompt Chaining（2023 早期）

2023 年初，AutoGPT 和 BabyAGI 横空出世，一夜之间在 GitHub 上拿到几万 star。它们的核心想法很朴素：让 LLM 自己规划任务，然后一步步执行。

具体做法是把多个 LLM 调用串成链——先让 AI 分析需求，再让 AI 写代码，再让 AI 检查错误，循环往复。听起来很酷，但很快所有人都发现了同一个问题：它不好用。

⚠️ 第一代系统的致命缺陷

• 没有工具——AI 只能”想”，不能”做”。需要读文件？对不起，它只能猜
• 没有上下文管理——对话一长就忘记前面说了什么
• 没有安全治理——AI 决定要 rm -rf /，没人拦得住
• 成功率极低——一个 10 步的计划，每步 80% 成功率，10 步下来只剩 10.7%

第一代的价值在于证明了一件事：AI 可以不只是回答问题，它可以主动行动。但它也暴露了一个根本问题——光靠 LLM 本身，撑不起一个可靠的系统。

第二代：Tool + RAG（2023–2024）

LangChain、LlamaIndex、MemGPT 代表了第二代。它们的核心进步是：给 AI 装上了手和眼睛。

“手”是工具调用（Function Calling / Tool Use）——AI 不再只能输出文字，它可以调用函数、查数据库、读文件。“眼睛”是 RAG（检索增强生成）——不用把所有知识塞进提示词，需要什么就去向量数据库里查。

# 第二代典型模式
# 工具定义
tools = [search_web, read_file, run_sql]

# 一次对话
response = llm.call(prompt, tools=tools)
if response.tool_call:
    result = execute(response.tool_call)
    # 把结果拼回去，再调一次
    final = llm.call(prompt + result)

这已经比第一代好太多了——AI 终于能”做事”了。但第二代的问题在于拼凑：上下文管理是手动拼字符串，权限检查是 if-else 硬编码，记忆是往向量数据库里塞完事，工具之间没有统一的注册和执行机制。一旦系统复杂起来，整个代码库就变成一锅意大利面。

第三代：Harness（2025–2026）

2025 年，Claude Code、Codex CLI、Devin 等系统的出现标志着第三代的到来。它们和前两代有什么本质区别？

一句话概括：上下文管理和安全治理同时从 ad-hoc 变成了系统工程。

图 1-1 展示了三代 Agent 系统的演进脉络。

图 1-1：AI Agent 系统的三代演进

1. 第一代 Prompt Chaining → LLM 串联调用，无工具、无上下文、无治理
2. 第二代 Tool + RAG → 工具调用、向量检索，拼凑式上下文、无权限
3. 第三代 Harness → 系统化编排，分层记忆、权限治理、多 Agent

从图中可以看出，每一代不是替换前一代，而是叠加——第三代仍然有 prompt chaining，仍然有工具调用和 RAG，但它把这些能力纳入了一个统一的、经过工程化设计的系统。

💡 关键认知：第三代跃迁的标志

从第二代到第三代，不是多加了几个功能，而是发生了质变：

• 上下文管理：从”拼字符串”变成分层记忆 + 4 种压缩策略 + Prompt Cache
• 安全治理：从”没有”变成 7 层权限规则 + ML 分类器 + 生命周期钩子
• 工具系统：从”注册几个函数”变成 Schema 校验 + 并发控制 + MCP 标准化
• Agent 协调：从”单打独斗”变成委托 + 后台 + Swarm 三种模式

表 1-1：三代 Agent 系统对比

Harness 的定义与边界

了解了演进历程，现在我们可以给 Harness 一个精确的定义。

什么是 Harness

Harness 这个词的原意是”马具”——套在马身上的一整套缰绳、鞍具和挽具。马有力气，但没有马具，力气就是散的；有了马具，人才能驾驭这股力量，让马拉车、耕地、载人。

LLM 就是那匹马——强大但需要驾驭。Harness 就是那套马具。

💡 核心概念：Harness

Harness（AI Agent 运行时编排系统）由六大模块组成：

1. 查询引擎（Query Engine）——核心循环：调用 LLM → 执行工具 → 回传结果
2. 工具系统（Tool System）——Agent 的能力边界：Schema 校验 + 并发执行
3. 权限治理（Permission System）——安全保障：规则匹配 + 危险操作拦截
4. Agent 编排（Agent Orchestration）——多 Agent 协调：委托 + 后台 + 团队
5. 记忆持久化（Memory System）——跨会话记忆：热记忆 + 冷记忆
6. 生命周期钩子（Hooks & Skills）——可扩展性：事件拦截 + 能力复用

图 1-2 展示了这六大模块的结构关系。查询引擎是心脏，其余五个模块围绕它运转。

图 1-2：Harness 六大核心模块

1. Hooks — 生命周期钩子、技能系统、插件 → 拦截与扩展
2. Agent 编排 — 委托、后台、Swarm 团队 → 派发子任务
3. 查询引擎 — while(true)、流式处理、上下文压缩 → 调用工具
4. 工具 + 权限 — Schema 校验、并发控制、7 层规则
5. 记忆系统 — 热记忆、冷记忆、会话记忆

从图中可以看出，Harness 不是一个扁平的组件列表，而是有层次的。Hooks 在最外层拦截一切，Agent 编排管理任务分配，查询引擎驱动核心循环，工具和权限在执行层面把关，记忆系统则为整个系统提供持久化的知识基础。

什么不是 Harness

理解一个概念，知道它”不是什么”同样重要。

❗ Harness 不是这些东西

• 不是 API Client——OpenAI 的 Python SDK、Anthropic SDK 只是”发 HTTP 请求”，它们是 Harness 的一个零件，不是 Harness 本身
• 不是 Chatbot UI——Streamlit 聊天界面、ChatGPT 网页只是展示层，Harness 是背后的编排逻辑
• 不是 MCP Server——MCP Server 提供单个能力（比如读数据库），Harness 是消费和协调这些能力的系统
• 不是 Prompt 模板——一个精心设计的 System Prompt 只是 Harness 的配置文件之一，不是 Harness 本身

一个类比可以帮助理解这些区别：如果 Harness 是一辆汽车，那么 API Client 是发动机里的点火器，Chatbot UI 是仪表盘和方向盘，MCP Server 是加油站，Prompt 模板是驾驶手册。它们都很重要，但单独拿出来哪个都不是一辆车。

Wrapper 和 Harness 的区别

很多人把 Agent 框架笼统地叫做”LLM Wrapper”，这是一个常见的误解。Wrapper 只是在 API 外面包了一层薄薄的壳，加点错误处理和格式转换，本质上是透传。Harness 则完全不同——它有自己的循环、自己的状态管理、自己的决策逻辑。

表 1-2：Wrapper 与 Harness 的关键区别

Claude Code 的全景架构

理论讲够了，让我们看一个真实的 Harness 长什么样。Claude Code 是 Anthropic 官方的 AI 编码助手，它的核心代码已经开源，总计 51.2 万行 TypeScript，分布在约 1900 个文件中。这是目前公开可见的、最成熟的生产级 Harness 实现。

十大模块速览

图 1-3 展示了 Claude Code 的十大核心模块。

图 1-3：Claude Code 十大核心模块

• 顶层入口：CLI / IDE — 用户入口
• 核心层：查询引擎（while 循环）、工具系统（45+ 内建）、权限系统（7 层规则）、Agent 系统（多模式）
• 底层：记忆系统（4 层架构）、Hooks（26 事件）、MCP（协议集成）

每个模块用一句话概括：

1. 查询引擎——一个 while(true) 循环，不断调用 LLM、执行工具、回传结果，直到任务完成
2. 工具系统——45+ 内建工具（文件读写、命令执行、代码搜索等），每个都带 Schema 校验和权限声明
3. 权限系统——7 层优先级规则，从企业策略到会话级设置，层层覆盖
4. Agent 系统——支持同步委托、异步后台、Swarm 团队三种多 Agent 模式
5. 记忆系统——4 层架构：项目指令 → 跨会话记忆 → 会话记忆 → 上下文压缩
6. Hooks 引擎——26 个生命周期事件，支持 shell、prompt、agent、http 四种 Hook
7. MCP 集成——既能消费外部 MCP Server 的能力，也能将自身能力暴露为 MCP Server
8. 技能系统——可复用的 Prompt + 工具组合，支持社区分享和团队定制
9. UI 渲染——流式 Markdown 渲染、工具执行状态反馈、快捷命令系统
10. 会话管理——对话持久化、多会话切换、上下文恢复

一次完整对话的数据流

当你在终端里输入一条消息时，背后到底发生了什么？图 1-4 展示了一次完整对话的数据流。

图 1-4：一次完整对话的数据流

1. 用户输入 → 你在终端敲下一段话
2. Hooks 拦截 → UserPromptSubmit 事件触发，Hook 可以修改或拒绝输入
3. 系统提示组装 → 基础指令 + 工具 Schema + 记忆 + 上下文 → 完整 Prompt
4. API 调用 → 带 Prompt Cache 的流式请求，发送到 Claude API
5. 工具执行 → 解析 tool_use 块 → 权限检查 → 并发执行 → 结果回传
6. 继续决策 → 还有工具调用？继续循环。没有？输出最终回复
7. 记忆提取 → 对话结束后，自动提取关键信息写入记忆系统

这个流程最关键的一点是：步骤 4 到步骤 6 是一个循环。AI 可能在一次对话中调用十几次工具——读文件、改代码、运行测试、发现问题、再改——每一轮都经过完整的权限检查和上下文管理。这就是 Harness 的核心机制：不是”一问一答”，而是”持续迭代直到完成”。

💡 理解 Harness 的关键直觉

把 Harness 想象成一个操作系统：

• 查询引擎 = CPU（不断执行指令循环）
• 工具系统 = 系统调用（应用程序通过它访问硬件）
• 权限系统 = 内核安全模块（防止非法操作）
• Agent 编排 = 进程调度（管理多个并发任务）
• 记忆系统 = 文件系统（持久化存储）
• Hooks = 中断处理（在特定事件点插入自定义逻辑）

这个类比不是随便说说——Harness 和操作系统面临的工程问题惊人地相似。

为什么是 51 万行

你可能会问：一个 CLI 工具，为什么需要 51 万行代码？

这恰恰说明了 Harness 的复杂性。粗略分布如下：

表 1-3：Claude Code 代码量分布（估算）

这些代码不是堆砌出来的——每个模块都在解决真实的工程问题。比如查询引擎里的 4 种压缩策略，是因为 LLM 的上下文窗口有限，而用户的任务可能需要上百轮工具调用；权限系统的 7 层规则，是因为个人开发者和企业团队的安全需求完全不同。

本书的学习路径

理解了 Harness 是什么，接下来的问题是：怎么学？

三段式结构

本书每一章都遵循”架构原理 → Prompt 实战构建 → 核心代码”的三段式结构：

图 1-5：每章的三段式结构

1. 架构原理 → 为什么这样设计
2. Prompt 实战 → 用 AI 一步步构建
3. 核心代码 → 理解关键实现

• 架构原理部分解释”为什么”——为什么需要这个模块，它解决什么问题，设计上有哪些取舍
• Prompt 实战部分示范”怎么做”——给出真实的 Prompt，展示 AI 输出的核心代码片段
• 核心代码部分聚焦”是什么”——展示 20–30 行关键代码，完整实现在 GitHub 仓库

这个结构的设计理念是：你不需要自己写代码——你需要学会如何向 AI 提出正确的问题。每章的 Prompt 都是经过精心设计的，你可以直接复制到 Claude Code 中运行，看着 AI 一步步帮你把模块构建出来。

递进式学习路线

全书分为三个部分，难度递进：

图 1-6：全书学习路线

1. I — 认知基础 — Harness、循环、架构
2. II — 核心模块 — 工具、权限、Agent、记忆、Hooks
3. III — 集成实战 — MCP、终端、发布

从图中可以看出，第一部分（你正在读的）建立概念框架，第二部分逐一构建六大核心模块，第三部分把它们集成为一个完整的产品。

最终产物

跟着全书走完，你将拥有一个完整的 Python 项目：

harness/
├── cli.py             ← 命令行入口
├── engine.py          ← 查询引擎（while 循环 + 流式处理）
├── tools/             ← 工具系统（FileRead / FileWrite / Bash）
├── permissions.py     ← 权限系统（规则匹配 + 危险检测）
├── agents.py          ← Agent 编排（委托 + 后台 + 团队）
├── memory/            ← 记忆系统（热记忆 + 冷记忆）
├── hooks.py           ← Hooks 引擎（生命周期事件）
├── skills/            ← 技能系统（可复用 Prompt）
├── mcp/               ← MCP 集成（Client + Server）
└── ui/                ← 终端 UI（流式渲染 + 命令系统）

这不是一个练习项目——它可以 pip install 直接使用，带完整的命令行界面、MCP 接口和记忆系统。每章对应一个 Git Tag，你可以随时跳到任意章节的起点继续。

💡 给不同读者的建议

• 零基础读者——按顺序阅读，每章的 Prompt 都可以直接运行。不懂的代码先跳过，重点理解架构思想
• 有经验的开发者——可以直接跳到感兴趣的章节。每章独立成文，但建议至少先读完本章建立全局认知
• 想构建自己 Agent 系统的人——重点关注每章的”架构原理”部分，理解设计取舍后再决定自己的方案

延伸思考

在进入下一章之前，不妨思考几个问题：

1. 你日常使用的 AI 工具（ChatGPT、Cursor、Claude Code），它们属于哪一代 Agent 系统？判断依据是什么？
2. 如果让你从零设计一个 Harness，你会先实现哪个模块？为什么？
3. Harness 和传统的”中间件”（如 Web 框架的 middleware）有什么异同？

这些问题没有标准答案，但思考它们会帮助你在后续章节中建立更深的理解。

章节小结

• AI Agent 系统经历了三代演进：Prompt Chaining → Tool + RAG → Harness。每一代是叠加而非替换
• Harness 是 AI Agent 的运行时编排系统，由六大模块组成：查询引擎、工具系统、权限治理、Agent 编排、记忆持久化、生命周期钩子
• Harness 不是 API Client、Chatbot UI 或 MCP Server——它是协调所有这些组件的编排系统
• Claude Code 是目前公开可见的最成熟的 Harness 实现，51.2 万行 TypeScript，10 大核心模块
• 本书每章遵循”架构原理 → Prompt 实战 → 核心代码”的三段式结构，最终产出一个可用的 Python Agent Harness