Harness 不是一个具体的软件或代码库，而是一种设计和架构 AI Agent 的工程范式。其核心公式为：
Agent = Model + Harness
模型决定 Agent 的智商上限，Harness 决定 Agent 的交付下限。
总体架构全景
业界目前比较认可的架构是六层模型，从底层到顶层依次为：
┌─────────────────────────────────────────────┐
│ 第六层：约束与恢复层 │
├─────────────────────────────────────────────┤
│ 第五层：评估与观测层 │
├─────────────────────────────────────────────┤
│ 第四层：状态与记忆层 │
├─────────────────────────────────────────────┤
│ 第三层：编排与规划层 │
├─────────────────────────────────────────────┤
│ 第二层：工具与执行层 │
├─────────────────────────────────────────────┤
│ 第一层：上下文管理层 │
└─────────────────────────────────────────────┘
第一层：上下文管理层（Context Management）
核心问题：如何让模型在有限的窗口里，看到此刻应该看到的东西。
虽然大模型上下文窗口已卷到 200K 甚至 1M token，但仍不能把所有 context 一股脑塞进去，原因有三：
-
长上下文衰减：模型在中间段的注意力明显下降（Lost in the Middle 效应）
-
成本爆炸：每次调用都带着几十万 token，费用极高
-
噪声干扰：无关信息太多，模型抓不住重点
工程实践
-
动态组装上下文：每轮对话前，根据当前任务动态检索相关文件、历史决策、工具输出
-
上下文压缩：当上下文接近上限时，自动摘要早期对话，释放空间
-
分层加载：核心指令常驻，工作记忆按需加载，长期记忆按查询拉取
-
结构化切片：把大文件切成语义块，用 embedding 或关键词检索按需注入
OpenAI 的实战经验
OpenAI 放弃了早期"给 Agent 塞一个 1000 页规则文档"的做法，转而构建层次化知识库：AGENTS.md 仅保留约 100 行作为"地图"，指向深层次的架构、设计与参考文档。同时设置专门的"知识库检修 Agent"，定期扫描文档，发现过时时自动提交 PR 修正。
第二层：工具与执行层（Tool & Execution）
核心问题：如何让模型精准地调用工具。模型输出的本质是文本，要使文本"动起来"，必须依赖工具调用。这一层决定了 Agent 的物理能力边界。
两大工具类型
MCP 工具（Model Context Protocol）：提供标准化的工具发现与调用接口，Harness 作为 MCP 客户端连接多个 MCP 服务器（文件系统、数据库、第三方 API 网关等）。
-
工具发现：启动时通过
tools/list获取所有可用工具及其 JSON Schema 定义 -
延迟绑定：LLM 根据 Observation 动态选择工具，而非预编译工具链
-
流式响应：通过 MCP 的流式扩展，支持长耗时工具的进度观测
Shell 工具：本地系统的最强接口，不是简单的 subprocess.run()，而是：
-
PTY 模拟：支持交互式命令（如
vim、ssh） -
会话持久化：维护 Shell 会话的工作目录和环境变量，支持多步操作上下文
-
输出智能截断：对超大输出流进行 LLM 引导式摘要，防止上下文窗口溢出
两种工具通过统一的 ToolExecutor 抽象调度，对外暴露一致的调用接口：(tool_name, params) -> Observation。
关键设计原则
-
工具描述的精确性：工具名、参数 schema、描述文案，每一个字都会影响模型的调用准确率
-
执行沙箱：代码执行、Shell 命令、浏览器等操作都需要隔离环境
-
结果结构化反馈：执行成功/失败、错误信息、输出摘要，都要以模型能理解的方式回传
第三层：编排与规划层（Orchestration & Planning）
核心问题：面对一个复杂目标，如何把任务拆解成模型能一步步执行的动作序列。这一层是 Agent 从"单轮问答"升级为"多步任务执行"的关键。
四种编排模式
ReAct 循环：Reason（思考）→ Act（行动）→ Observe（观察）→ 再思考，这是最经典的单 Agent 循环。
Plan-and-Execute：先生成完整计划，再逐步执行，中途可重规划。Claude Code 的 Plan Mode 就是这个思路。
多 Agent 协作：主 Agent 负责统筹，子 Agent 负责专项任务（如一个负责搜索、一个负责写代码、一个负责审查）。Anthropic 实践中采用三智能体架构：规划器（Planner）、生成器（Generator）和评估器（Evaluator）。
任务图（Task Graph）调度：把任务拆成 DAG（有向无环图），有并行、有依赖，像 CI/CD 流水线一样执行。
通信与事件总线
在分布式场景中，Agent 之间通过 A2A（Agent-to-Agent）协议 实现协作：
-
状态广播：代理上线、下线、任务进度
-
子任务委托：主代理将子任务发布到 A2A 通道，工作代理领取并回传 Observation
-
心跳与熔断：断连检测和任务重分配
-
WebSocket 传输层：全双工推拉，支持 Protocol Buffers 序列化
第四层：状态与记忆层（State & Memory）
核心问题：如何让 Agent 记得自己是谁、做过什么、还要做什么。这是 Agent 和 Chatbot 最本质的区别之一——Agent 有状态。
三层记忆体系
工作记忆（Working Memory）：当前任务的状态、当前执行到哪一步、中间变量等。
会话记忆（Session Memory）：本次会话的完整历史、用户偏好、已做的决策等。
长期记忆（Long-term Memory）：跨会话的持久偏好、知识库、文件存储。
工程实现
-
向量记忆库：用 embedding 存储历史经验，检索相似场景
-
结构化记忆文件：如 CLAUDE.md、AGENTS.md，把稳定知识固化成文件，每次会话自动加载
-
状态快照与恢复：长任务中断后能断点续传
-
TODO 系统：规划任务清单，把计划物化成可追踪的状态
Knowledge 层的混合存储设计
Knowledge 层远超简单的 RAG，它是一个动态更新的认知状态机：
-
结构化知识：基于 JSON Schema 的任务图和状态树，存储在内存或轻量级数据库中
-
非结构化知识：基于嵌入向量的长程记忆，支持语义检索
-
知识融合引擎：Observation 数据到达后，结构化数据直接合并入任务图；文本日志经 LLM 摘要后注入上下文窗口
第五层：评估与观测层（Evaluation & Observability）
核心问题：如何知道 Agent 到底在干什么、干得好不好。这一层往往不受重视，但特别重要。
反馈循环（Feedback Loop）
这是 Harness 中最核心的闭环机制——写-测-修循环（Write-Test-Fix Cycle）：
用户请求 → Agent 生成结果 → 沙箱测试/评估
↓
通过 → 交付结果
失败 → 错误信息回传 Agent → 修正 → 再次测试
关键设计原则：
-
错误信息要具体（指明哪个用例失败、期望 vs 实际）
-
反馈要及时（每次测试结果立即回传）
-
循环要有上限（如最多 5 次，避免无限循环）
确定性约束门控
这是 Harness Engineering 与传统 AI 应用最大的不同——不请求代理遵循规则，而是通过工程手段强制执行：
-
架构 Linter：自动检测代码变更是否违反预定义的依赖规则
-
重试上限（Retry Caps）：Stripe 发现两轮重试是平衡成本与成功率的临界值
-
前置提交钩子（Pre-commit Hooks）：代理生成的任何内容都必须先通过死代码检测、静态类型检查（如 Pyright）和 Shell 脚本校验
可观测性
-
全链路 Tracing：每一次模型调用、工具调用、上下文变化都可追溯
-
结构化日志：带有 trace_id、span、token 消耗、延迟、成本的结构化事件
-
自动化 Eval：用测试集定期回归，监控准确率、完成率、幻觉率的变化
-
LLM-as-a-Judge：用更强的模型评估 Agent 输出质量，实现规模化自动评估
第六层：约束与恢复层（Constraints & Recovery）
核心问题：当 Agent 做错事、卡死、或被诱导时，谁来踩刹车。越是能力强、权限大的 Agent，这一层越不能省。
三大机制
约束：哪些能做，哪些不能做。通过权限控制实现——哪些命令可以自动执行，哪些必须人工确认。
校验：输出前怎么检查。通过评估层的 Linter、类型检查、测试用例实现。
恢复：失败以后怎么重试、切路径、回滚到稳定状态。包括重试上限、Fallback 策略、人工接管机制。
安全沙箱分级
| 级别 | 隔离方式 | 适用场景 |
|---|---|---|
| L1 | 进程级隔离 | 受信任的内部工具 |
| L2 | 容器隔离（Docker） | 大多数工具执行 |
| L3 | 微虚拟机（Firecracker） | 多租户/不受信任代码 |
| L4 | 完全虚拟机 | 最高安全性场景 |
三大典型失败模式与 Harness 的应对
Anthropic 工程师总结了 Agent 在长时间运行中的三种典型翻车姿势：
| 失败模式 | 表现 | Harness 应对 |
|---|---|---|
| 试图一步到位（One-shooting） | 上下文窗口耗尽，留下半成品代码 | 任务分解 + 增量开发 + 结构化交接 |
| 上下文焦虑（Context Anxiety） | 上下文过长后模型行为退化 | 上下文重置 + 子代理隔离噪声 |
| 熵增失控（Entropy Drift） | 复制现有坏代码模式，质量逐步下降 | 定期运行"园艺 Agent"执行代码重构 |
业界标杆实践数据
-
OpenAI：3~5 名工程师在 5 个月内，通过 Codex Agent 交付超过 100 万行生产级代码，无一行人类手写，效率达传统模式的 10 倍
-
LangChain：在 Terminal Bench 2.0 基准测试中，仅通过优化 Harness，同一模型得分从 52.8% 提升至 66.5%，排名从第 30 名跃升至第 5 名
-
Anthropic：双智能体设计（初始化智能体 + 编码智能体）可稳定完成数小时至数天的长时任务
一句话总结
Harness Engineering 的本质：模型像 CPU 负责计算，Harness 像操作系统负责调度、内存、IO、约束、恢复和反馈。没有操作系统，再强的 CPU 也只是裸奔的计算单元。
浙公网安备 33010602011771号