Harness 工程概念：把 LLM 变成 Agent 的”外壳”

一、什么是 Harness

Harness（工程外壳） 是包裹在 LLM 外面的运行时环境，负责把一个”能对话的模型”改造成一个”能干活的 Agent”。

一句话定义：

Harness = LLM 之外的一切工程 —— 让模型拥有工具、记忆、上下文管理、协作能力的那层胶水。

类比

类比	说明
人 vs 汽车	LLM 是引擎，Harness 是底盘、油路、方向盘、座舱
CPU vs 电脑	LLM 是 CPU，Harness 是主板 + 操作系统 + 外设
演员 vs 剧组	LLM 是演员，Harness 是导演、道具、场景、剪辑

没有 Harness 的 LLM 只是一个”接收文本、返回文本”的函数。 有了 Harness，它才成为能读文件、写代码、调工具、开子任务、跨会话记忆的 Agent。

二、为什么需要 Harness

LLM 本身的”缺陷”

缺陷	Harness 提供的解决方案
不能执行代码	工具调用循环、沙盒执行
上下文有限	压缩、摘要、渐进式披露
无状态、无记忆	会话持久化、Memory 系统
不能读文件	Read/Write/Edit 工具封装
不能协作	Subagent 派发机制
不能自动化触发	Hook / Event 系统
不认识”技能”	Skills 加载协议
单独调用效率低	请求缓存、并发调度

Harness 补齐了 LLM 的所有”非智能”能力。

三、Harness 的核心组件

一个完整的 Agent Harness 通常包含以下模块：

┌────────────────────────────────────────────────────┐
│                  Agent Harness                     │
├────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌─────────┐   │
│  │   工具系统    │  │ Context 管理 │  │ Skills  │   │
│  │  Tool Loop   │  │ Compression  │  │ Loader  │   │
│  └──────────────┘  └──────────────┘  └─────────┘   │
│  ┌──────────────┐  ┌──────────────┐  ┌─────────┐   │
│  │  Subagent    │  │   Memory     │  │  Hooks  │   │
│  │ Orchestrator │  │    Store     │  │ System  │   │
│  └──────────────┘  └──────────────┘  └─────────┘   │
│  ┌──────────────┐  ┌──────────────┐  ┌─────────┐   │
│  │  Permission  │  │  MCP Client  │  │ Session │   │
│  │   Manager    │  │              │  │  State  │   │
│  └──────────────┘  └──────────────┘  └─────────┘   │
├────────────────────────────────────────────────────┤
│                     LLM (Model)                    │
└────────────────────────────────────────────────────┘

1. 工具执行循环（Tool Loop）

接收模型的 tool_use
分派到对应工具执行
把结果作为 tool_result 回填
循环直到模型输出最终文本

2. Context 管理

窗口监控：接近上限时触发压缩
摘要：把历史对话浓缩成 summary
截断策略：保留系统 prompt + 近期消息
缓存：Anthropic Prompt Caching / KV Cache 复用

3. Skills 加载器

扫描 skill 目录
注入元数据到 system prompt
拦截 Skill 工具调用，读取正文
（详见 [[04-skills使用]]）

4. Subagent 编排

派发独立上下文的子任务
管理生命周期、资源限制
收集返回结果回传主 agent
处理并发、隔离、超时

5. Memory 系统

项目级：CLAUDE.md / AGENTS.md
用户级：~/.claude/memory/
类型化：user / feedback / project / reference
每次会话自动注入

6. Hook 系统

事件驱动：SessionStart、PreToolUse、PostToolUse、Stop、UserPromptSubmit
可执行外部脚本
修改/阻止工具调用
注入额外上下文

7. Permission 管理

工具白名单/黑名单
危险操作确认
模式：ask / allow / deny
项目级 vs 用户级配置

8. MCP 客户端

连接 MCP server
动态发现工具/资源/prompt
转发调用、返回结果

9. Session State

对话历史持久化
断点恢复
分支切换

四、主流 Harness 一览

Harness	定位	特色能力
Claude Code	Anthropic 官方 CLI	完整 Skills、MCP、Subagent、Hooks 生态
Cursor	IDE 集成	深度编辑器集成、`.cursorrules`
Windsurf	IDE + Agent	Cascade、多文件编辑、Memories
Codex CLI	OpenAI 官方 CLI	GPT 系模型专用
Aider	终端 pair programming	Git 集成、diff 化编辑
deepagents	LangChain 出品	Middleware 架构、多 Backend
OpenHands（原 OpenDevin）	开源 SWE agent	完整开发环境模拟
Continue.dev	IDE 插件	自定义 provider 灵活

共同点：都在做同一件事 —— 用工程手段扩展 LLM 的能力边界。

五、Harness vs Framework vs Agent

三个概念常被混用，其实层次不同：

                 ┌──────────────────┐
                 │   Agent（个体）   │  ← 一个具体的智能体实例
                 │  "Code Reviewer" │
                 └────────┬─────────┘
                          │ 运行在
                          ↓
                 ┌──────────────────┐
                 │  Harness（外壳）  │  ← 让 LLM 变 Agent 的运行时
                 │  "Claude Code"   │
                 └────────┬─────────┘
                          │ 基于
                          ↓
                 ┌──────────────────┐
                 │ Framework（框架）│  ← 底层 SDK / 编排库
                 │   "LangGraph"    │
                 └────────┬─────────┘
                          │ 调用
                          ↓
                 ┌──────────────────┐
                 │   LLM（模型）     │  ← 智能核心
                 │   "Claude 4.7"   │
                 └──────────────────┘

关键区别

概念	边界	例子
Framework	提供构建能力的库（API）	LangChain, LangGraph, LlamaIndex
Harness	面向用户的完整运行环境	Claude Code, Cursor, Aider
Agent	特定任务的智能体实例	code-reviewer, deep-research

Framework 是零件商，Harness 是整车厂，Agent 是开出去的车。

六、Harness 的设计原则

1. 让智能归智能，让工程归工程

模型负责决策（选工具、判断相关性、生成内容）
Harness 负责执行（读文件、调 API、管理状态）
不把工程逻辑塞进 prompt，也不让模型做机械事务

2. 渐进式披露（Progressive Disclosure）

元数据轻量常驻，正文按需加载
应用于：Skills、MCP Tools、Files、Memory
避免上下文爆炸

3. 可组合、可拔插

Tool、Skill、Subagent、Hook 都应能独立开发/替换
deepagents 的 Middleware 化是典型代表

4. 边界清晰的权限模型

危险操作明确要用户确认
只读 vs 写入 vs 网络分级
沙盒隔离子进程

5. 可观测、可调试

完整的 tool call 日志
session 快照与回放
中间状态可导出

6. 模型无关（Model Agnostic）

Harness 层不绑定特定 LLM 厂商
通过 adapter 抽象不同 API 的差异
Claude Code 是反例（绑定 Claude），deepagents 是正例

七、Harness 的典型执行流程

[用户请求]
   ↓
① Session 初始化
   ├─ 加载 Memory (CLAUDE.md, MEMORY.md)
   ├─ 扫描 Skills 元数据
   ├─ 连接 MCP servers
   └─ 触发 SessionStart hooks
   ↓
② 构造首次 LLM 请求
   ├─ System prompt + Skills 列表 + Tools schema
   └─ 用户消息
   ↓
③ 模型响应
   ├─ 文本 → 直接输出给用户
   └─ tool_use → 进入工具循环
   ↓
④ 工具执行循环
   ├─ PreToolUse hook 检查
   ├─ Permission 检查（必要时询问用户）
   ├─ 分派执行（Read / Bash / Skill / Agent / MCP …）
   ├─ PostToolUse hook
   ├─ tool_result 回填
   └─ 回到 ③
   ↓
⑤ Context 监控
   ├─ 接近上限 → 触发压缩
   └─ 持久化会话状态
   ↓
⑥ 会话结束
   └─ Stop hooks（如自动 commit、通知）

八、Harness 工程的兴起

为什么”Harness”最近才成为独立概念

早期（2022-2023）：

大家把 Agent 直接堆在 LangChain 里
Prompt + Tool + Loop 混杂在业务代码
“框架”和”运行时”没有分层

现在（2024-2026）：

Claude Code 定义了范式 —— Harness 是一等公民
deepagents 把它标准化 —— Harness 可以独立于 Framework 存在
Codex/Cursor/Windsurf 各自造轮子 —— 说明这是刚需
Agent Skills 标准（agentskills.io） —— Harness 之间开始互通

Anthropic 的贡献

Anthropic 把 Harness 工程的方法论显式化：

Skills 协议 —— 方法论的模块化
MCP 协议 —— 工具的标准化接入
Agent SDK —— Harness 组件的开源化
Sub-agent 模型 —— 上下文隔离的原语化

九、判断一个 Harness 好不好的标准

维度	好 Harness	差 Harness
上手成本	装完就能用	要写一堆胶水
扩展性	加 skill/tool 只需扔文件	加功能要改核心
可观测	完整 trace、可回放	出错只能看模型输出
模型无关	一键切换 provider	绑死一家
安全	分级权限、明确确认	默认全开
性能	缓存、并发、批处理	每次都全量请求
社区	有生态（skills/plugins/MCP servers）	孤岛

十、Harness 工程的未来方向

1. 标准化协议层

Skills → agentskills.io
Tools → MCP
Memory → 尚无标准（AGENTS.md 是雏形）
Hook → 各家自定义，未来可能统一

2. 组件市场化

类似 npm/pip：一个命令安装 skill/plugin/tool
已有雏形：Claude Code Plugins、Cursor Marketplace

3. Harness 互操作

一份 skill 能在 Claude Code、deepagents、Cursor 之间通用
一个 subagent 定义能跨 harness 派发

4. Harness 作为服务

云端托管的 Harness（Devin、E2B）
无需本地环境，浏览器即可跑 Agent

5. 多 Agent 编排上升到 Harness 级

不再是 CrewAI 那种”业务代码里定义”
而是 Harness 原生支持”团队协作模式”

十一、一句话总结

Harness 工程 = 把 LLM 从”文本函数”改造成”能干活的 Agent”所需的一切运行时能力。 它决定了 Agent 的能力上限、开发体验、扩展方式。未来 Agent 的竞争，很大程度上是 Harness 之战：谁的 Harness 更开放、更可扩展、更好用，谁就赢得开发者。

Harness 工程概念：把 LLM 变成 Agent 的"外壳"