什么是 AI Agent Harness

哓番茄大约 4 分钟

什么是 AI Agent Harness

一个观察：同一个模型，不同的能力

同一个 Claude/GPT 模型：

在网页聊天框里，它能聊代码，但改不了你磁盘上的任何文件
在 Claude Code / Codex CLI / Cursor Agent 里，它能读你的仓库、改代码、跑测试、提交 PR

模型没变，差距来自外面套的那层软件系统——Agent Harness（代理运行时/脚手架）。

┌───────────────────────────────────────┐
│            Agent Harness              │
│  ┌─────────┐ ┌──────┐ ┌───────────┐  │
│  │ 核心循环  │ │ 工具集│ │ 上下文管理  │  │
│  └─────────┘ └──────┘ └───────────┘  │
│  ┌─────────┐ ┌──────┐ ┌───────────┐  │
│  │ 权限/安全 │ │ 子代理│ │ 记忆与扩展  │  │
│  └─────────┘ └──────┘ └───────────┘  │
└──────────────────┬────────────────────┘
                   │ API
            ┌──────▼──────┐
            │   LLM 模型   │  ← 只是「大脑」，没有手
            └─────────────┘

一句话定义：Harness = 把「能说会道的大脑」变成「能干活的系统」所需的一切运行时设施。

为什么需要 Harness：裸模型的五个缺陷

裸调用 LLM API 的缺陷	Harness 的补齐
无状态，每次调用只看到一个 prompt	会话管理 + 上下文工程（自动维护对话历史、压缩、记忆）
只能生成文本，不能执行动作	工具调用协议（读文件、跑命令、搜索、联网）
一次响应就结束，无法多步推进	Agentic Loop（循环执行直到任务完成）
无法访问你的环境	环境集成（文件系统、git、shell、编辑器、浏览器）
无约束地执行有风险	权限模型、沙箱、审批流程

演进史：四个阶段

阶段一：Chatbot（2022-2023）
  网页对话框 + 单轮生成。模型只输出文本。

阶段二：RAG / 工具增强（2023）
  给 prompt 里塞检索结果、让模型调一个搜索 API。
  「单次调用增强」，仍无多步自主性。→ 见本站 RAG 笔记

阶段三：Agent 框架（2023-2024）
  LangChain / LangGraph 等：ReAct 循环 + 工具注册。
  自主性有了，但每个项目要自己搭基础设施。→ 见本站 AI Agent 笔记

阶段四：Agent Harness（2024-）
  Claude Code、Codex CLI、Cursor、Devin 等：
  把循环、工具、上下文、安全、扩展做成「产品级运行时」，
  通用任务（尤其编码）开箱即用。

与阶段三的关键区别：Agent 框架是「给你零件自己拼」；Harness 是「整车交付」，并且把上下文工程和安全做成了系统能力。

Harness 的六大组成

1. 核心循环（Agentic Loop）

模型输出 → 执行工具 → 结果回注 → 再输出……直到模型给出最终回答。这是心跳，详见核心循环篇。

2. 工具系统

文件读写、shell、搜索、网络……工具的描述文本本身就是提示词——harness 的工具设计直接决定模型行为上限。详见工具与 MCP 篇。

3. 上下文工程

上下文窗口是稀缺资源：系统提示、对话历史、文件内容、工具结果全在争抢。压缩、记忆、缓存策略决定长任务成败。详见上下文工程篇。

4. 权限与安全

模型每一步动作都要过权限闸门（只读放行 / 询问用户 / 沙箱内执行），防止 prompt injection 等攻击造成破坏。详见评估安全篇。

5. 子代理与并行

一个上下文装不下的任务，拆给多个独立上下文的 subagent 并行处理。详见子代理篇。

6. 扩展机制

Hooks（事件钩子）、Skills（技能包）、自定义命令、插件市场——让用户把团队流程「编译」进 harness。详见扩展机制篇。

主流产品对照

产品	形态	特点
Claude Code	CLI / IDE 插件 / SDK	文件系统优先，hooks+skills+MCP 扩展体系完整
Codex CLI	CLI	OpenAI 的终端编码代理
Cursor	IDE	编辑器原生集成，Tab 补全 + Agent 模式
Devin	云端 Web	全自主云端 VM + 浏览器操作
OpenHands	开源	开源自主代理平台

一个心智模型：Harness 是「操作系统」

LLM       ↔ CPU：算力本身，不存储、不感知外设
上下文窗口  ↔ 寄存器/内存：稀缺、易失，要精心调度
工具调用    ↔ 系统调用：用户态程序请求内核做事
系统提示词  ↔ 内核常驻代码：定义基本行为
MCP       ↔ 设备驱动协议：标准化外设接入
Skills    ↔ 可执行程序：按需加载的能力包

理解了这个类比，后面每一篇都在讲「这个操作系统的某个子系统」。

为什么要学 Harness

用得更好：理解机制后，你写的 prompt / CLAUDE.md / 工具描述质量会完全不同
调得动：知道上下文怎么消耗、工具怎么被选中，才能诊断「AI 为什么做蠢事」
造得出：Agent SDK + 本系列原理，可以为自己的业务构建专属 harness