Agent X-Ray
RuntimeNotesAbout
Notes/源码拆解/Harness Engineering/研究报告

Harness Engineering 研究报告

约 10 分钟 · 更新于 2026-09-01

Harness Engineering 研究报告

摘要 本报告系统梳理 Harness Engineering（驾驭工程）这一新兴 AI 工程学科的核心概念、技术体系、最佳实践和行业趋势。研究目标是为飞常准国际机票 AI 订票助手的智能体能力建设提供理论基础和工程参考。报告基于 300+ 篇外部资料的综合分析，核心引用 25 篇原文（保存在 原始资料/ 目录）。

一、Harness Engineering 是什么

1.1 起源与定义

Harness Engineering 由 OpenAI 在 2026 年初正式提出。他们的 Codex 团队用 3 人、5 个月时间，在零人工编码的情况下交付了 100 万行代码——靠的不是更强的模型，而是一套精心设计的"驾驭系统"。

OpenAI 核心论述 "When the agent struggles, we treat it as a signal: identify what is missing—tools, guardrails, documentation—and feed it back into the repository." —— OpenAI: Harness Engineering

Martin Fowler / Thoughtworks 团队随后将其系统化为三个组成部分 (Fowler: Harness Engineering)：

  1. Context Engineering（上下文工程）：增强代码库内的知识库 + 动态上下文（可观测性、浏览器导航）
  2. Architectural Constraints（架构约束）：LLM 代理 + 确定性 linter/结构测试双重监控
  3. Garbage Collection（垃圾回收）：周期性代理检测文档不一致性和约束违规

1.2 核心公式

LangChain 在其「Agent Harness 解剖学」一文中给出了最简洁的定义 (LangChain: Anatomy of an Agent Harness)：

Agent=Model+Harness\text{Agent} = \text{Model} + \text{Harness}

Harness（驾驭系统） = 模型本身之外的所有代码、配置和执行逻辑。

包括：系统提示词、工具描述、基础设施（文件系统、沙箱、浏览器）、子代理编排逻辑、中间件 Hooks 等。

1.3 为什么重要？

HumanLayer 的文章 (HumanLayer: Skill Issue) 一语中的：

"The model is probably fine. It's just a skill issue."

LangChain 用实验证明了这一点 (LangChain: Improving Deep Agents)：仅通过优化 Harness（不换模型），他们的 coding agent 在 Terminal Bench 2.0 上从第 30 名跃升至第 5 名，得分从 52.8% 提升到 66.5%——纯粹靠工程，不靠模型升级。

对机票业务的启示 我们构建 AI 订票助手时，不应把重心放在"等更好的模型"上，而应投资于 Harness——工具面、上下文管理、治理规则、评估体系。这才是真正的竞争壁垒。

二、技术体系全景

2.1 三层架构：Framework → Runtime → Harness

LangChain 提出了清晰的三层分类 (LangChain: Frameworks vs Runtimes vs Harnesses)：

层级定义代表产品
Framework（框架）提供核心抽象，建立心智模型LangChain, Vercel AI SDK, CrewAI, OpenAI Agents SDK
Runtime（运行时）生产级基础设施：持久执行、流式、HITL、持久化LangGraph, Temporal, Inngest
Harness（驾驭系统）"Batteries-included"——默认提示词、固执己见的工具处理、规划能力、文件系统Claude Code, DeepAgents, Codex

对我们的映射

  • Framework 层：选用 Claude Agent SDK 或 LangGraph 作为底层框架
  • Runtime 层：需要自建或选型持久执行引擎（支持断点续跑、人工介入）
  • Harness 层：这是核心投资方向——即 AI订票助手-Harness工程方案 中定义的 6 层架构

2.2 Harness 的六大基础原语

根据 LangChain 的解剖 (08-anatomy)：

mermaid
graph TB
    A[Agent Harness] --> B[1. Filesystems<br/>持久化存储]
    A --> C[2. Bash + Code Execution<br/>通用问题解决]
    A --> D[3. Sandboxes<br/>安全隔离执行]
    A --> E[4. Memory Systems<br/>AGENTS.md 等跨会话记忆]
    A --> F[5. Context Management<br/>压缩/卸载/渐进披露]
    A --> G[6. Long-Horizon Execution<br/>规划/自验证/循环]

三、六大核心能力域

3.1 指令层 (Instruction Layer)

核心文件：AGENTS.md / CLAUDE.md

GitHub 分析了 2,500+ 个仓库后总结出六大核心覆盖领域 (GitHub: Great AGENTS.md)：

  1. Commands（可执行命令）：不只写工具名，要带具体参数
  2. Testing（测试方式）：明确用什么框架、怎么跑
  3. Project Structure（项目结构）：技术栈 + 版本 + 依赖
  4. Code Style（代码风格）：用代码示例而不是文字描述
  5. Git Workflow（Git 流程）：分支策略、commit 规范
  6. Boundaries（边界）：三级权限——Always / Ask First / Never

关键原则 "The best agent files grow through iteration, not upfront planning." —— GitHub: Great AGENTS.md

对机票 Agent 的映射：我们的 AGENTS.md 应定义订票 Agent 的操作契约——哪些工具可以自主调用（搜索类）、哪些需要确认（下单类）、哪些绝对禁止（跨用户数据访问）。

3.2 工具面 (Tool Surface)

Anthropic 的工具设计指南 (Anthropic: Writing Tools) 给出了核心原则：

3.2.1 少即是多——收敛工具面

"More tools don't guarantee better performance."

不要把每个 API 端点包成一个工具。应该：

  • 合并操作：一个 schedule_event 优于分开的 list_users + list_events + create_event
  • 命名空间：用一致前缀分组（asana_search, asana_projects_search）
  • 有意义的返回值：返回自然语言名称，不要裸 UUID

3.2.2 Token 效率

  • 实现分页、过滤、截断，设置合理默认值
  • 错误信息引导更高效的策略（鼓励精确搜索而非广泛查询）
  • 支持 response_format 参数（concise 72 tokens vs detailed 206 tokens）

3.2.3 高级工具使用模式

Anthropic 的高级工具使用 (Anthropic: Advanced Tool Use) 引入了三个关键能力：

能力解决的问题效果
Tool Search Tool工具库上下文膨胀77K → 8.7K tokens（-85%），准确率 49% → 74%
Programmatic Tool Calling中间结果污染上下文Token -37%，支持并行编排
Tool Use Examples参数使用模式不清准确率 72% → 90%

对机票工具面的启示 我们的 8 个核心工具（search_flights, evaluate_plans 等）需要：

  1. 每个工具附带 2-3 个使用示例（日期格式、航段表达、多乘客参数）
  2. 返回值用自然语言（"北京首都 → 东京成田"而非"PEK→NRT"）
  3. 搜索工具支持 concise/detailed 两种返回格式

3.3 上下文工程 (Context Engineering)

Anthropic 定义 (Anthropic: Context Engineering)：

Context = the set of tokens included when sampling from a LLM. Engineering = optimizing utility of those tokens against inherent LLM constraints.

四大策略

LangChain 总结了四大上下文管理策略 (LangChain: Context Engineering)：

策略含义关键技术
Write将信息保存到上下文窗口外Scratchpads, 跨会话记忆
Select按需检索相关信息RAG, 知识图谱, 语义检索
Compress仅保留必要 token自动压缩（Claude Code 在 95% 容量时触发）, 修剪
Isolate将信息分散到独立上下文子代理（上下文防火墙）, 沙箱, 状态隔离

Context Rot（上下文腐烂）

随着 token 增长，LLM 准确率下降——Transformer 的 n² 注意力关系被拉伸。

长期运行的 Agent 面临四种上下文退化：

  • Context Poisoning：幻觉污染存储的信息
  • Context Distraction：过多内容淹没关注点
  • Context Confusion：不相关内容影响响应
  • Context Clash：同一上下文中的矛盾信息

对订票 Agent 的启示 订票场景天然涉及大量结构化数据（航班列表、价格矩阵、中转方案），极易触发 context rot。我们需要：

  1. 工具返回值必须做压缩（只返回 Top 5 方案摘要，不是全量数据）
  2. 评估子任务使用子代理隔离（风险检查 Agent、价格比较 Agent 各自独立上下文）
  3. 建立 Booking Context Graph 作为结构化外部记忆

3.4 Agent Skills 渐进式披露

Anthropic 的 Agent Skills (Anthropic: Agent Skills) 引入了三级渐进式披露 (Progressive Disclosure)：

text
Level 1: Metadata（~80 tokens/skill）
         ↓ Agent 判断相关性
Level 2: Core Content（完整 SKILL.md）
         ↓ Agent 需要更多细节
Level 3: Supplementary Resources（reference.md, forms.md 等）

"This metadata is the first level of progressive disclosure: it provides just enough information for Claude to know when each skill should be used without loading all of it into context."

核心价值：在不膨胀上下文的前提下，给 Agent 注入领域专业知识。

对机票 Agent 的映射 订票 Agent 可以按以下方式组织 Skills：

  • booking-rules.skill：订票规则（退改签政策、行李规则等）
  • risk-assessment.skill：风险评估（天气、签证、中转时间等）
  • pricing-strategy.skill：比价策略（日历低价、临近机场、混合舱位等）

这些 Skill 平时只占 ~80 tokens，仅在相关场景被触发时才加载完整内容。

3.5 治理层 (Governance)

OWASP Agentic Top 10 (2026)

OWASP 发布了专门针对 Agent 应用的安全风险清单（OWASP Top 10 for Agentic Applications），10 大风险包括：

  1. Goal Hijacking：目标劫持
  2. Privilege Abuse：权限滥用
  3. Remote Code Execution：远程代码执行
  4. Insecure Inter-Agent Comms：不安全的代理间通信
  5. Tool Misuse：工具误用
  6. Supply Chain：供应链攻击
  7. Memory Poisoning：记忆污染
  8. Cascading Failures：级联故障
  9. Rogue Agents：失控代理

Human-on-the-Loop 模式

Martin Fowler 团队 (Fowler: Humans and Agents) 提出三种人机协作模式：

模式描述适用性
Outside the Loop人类只定义目标，Agent 全权执行低风险、可验证的任务
In the Loop人类逐步审批 Agent 的每个动作高风险但会成为瓶颈
On the Loop（推荐）人类设计约束系统，Agent 在其中运作Harness Engineering 的本质

对机票治理的映射

  • 搜索组工具（search_flights 等）：Outside the Loop — 自主执行
  • 评估工具（evaluate_plans）：Outside the Loop — 自主执行但结果需风险标签
  • 下单工具（create_booking）：In the Loop — 必须持有 confirmation token
  • 售后转接（handoff_aftersales）：In the Loop — 必须转人工

3.6 评估层 (Evaluation)

LangChain 的行业调查 (LangChain: State of Agent Engineering) 显示：

  • 89% 的团队已实施 Agent 可观测性
  • 但只有 52.4% 跑离线评估，37.3% 做在线评估
  • Quality（质量） 是 33% 团队的首要障碍

> "Context engineering is the dividing line between teams that ship and those that don't." —— LangChain State of Agent Engineering 2026

评估维度

结合各方最佳实践，建议按四个维度建立评估体系：

维度指标来源
任务质量推荐方案可执行率、价格偏差、对话完成率Anthropic + Sierra tau-bench
工具质量调用成功率、平均时延、误用率、无效调用占比Anthropic Writing Tools
治理质量红线违规次数、token 绕过尝试、人工接管率OWASP Agentic Top 10
业务价值单次决策时长、每单平均成本、售后率、投诉率Klarna Case Study

四、Anthropic 的长期运行 Agent Harness 模式

Anthropic 的「Effective Harnesses for Long-Running Agents」(Anthropic: Effective Harnesses) 提供了一个特别有参考价值的模式：

4.1 两部分架构

组件职责
Initializer Agent首次会话建立基础设施：init.sh、claude-progress.txt、功能清单、初始 git commit
Coding Agent后续会话：读进度文件 → 选优先功能 → 实现 → 测试 → 提交

4.2 关键发现

  • 功能清单 (Feature Lists)：JSON 文件描述所需功能及 pass/fail 状态，防止"过早宣告完成"
  • 测试工具至关重要："Providing Claude with testing tools dramatically improved performance"
  • 每次会话只做一个功能：避免"过度雄心"导致半成品

对机票 Agent 的启示 订票 Agent 的长期运行场景（如复杂多段行程规划）可以借鉴这个模式：

  • 建立 booking-progress.json 跟踪多步骤订票过程
  • 每个"会话"（用户交互轮次）只推进一个确定步骤
  • 通过 init 步骤自动加载用户上下文、偏好、历史

五、生产案例：Klarna 的经验与教训

Klarna 是目前最知名的 AI Agent 生产案例 (Klarna Case Study)：

成功数据

  • 处理了 2/3 的客服聊天
  • 匹配人类客服的满意度评分
  • 解决时间从 11 分钟降至 2 分钟
  • 相当于 700 名全职客服的工作量
  • 预计年利润提升 $40M

关键教训

  • Klarna 后来回退到混合模式（重新引入人类客服处理复杂场景）
  • 纯 AI 处理无法覆盖所有 edge case
  • 治理和回退机制必须在第一天就设计好，不能事后补

对机票业务的警示 机票订购比客服更复杂（涉及资金、合约、不可逆操作）。必须：

  1. 从 Day 1 就建立"确认 → 执行"的二步链路
  2. 高风险操作绝对不能靠"提醒模型小心"，必须结构性不允许
  3. 预留人工接管通道，且接管时能看到完整操作轨迹

六、Claude Agent SDK 与工具体系

6.1 Agent Loop 架构

Claude Agent SDK (Anthropic: Claude Agent SDK) 定义了标准的 Agent 循环：

text
Gather Context → Take Action → Verify Work → Iterate

6.2 五大编排模式

Anthropic 的经典指南 (Anthropic: Building Effective Agents) 定义了五个可组合模式：

模式适用场景订票场景映射
Prompt Chaining顺序拆解固定子任务搜索 → 风险评估 → 推荐排序
Routing按输入类型分发到专门处理器国内/国际、单程/往返/多程
Parallelization独立子任务并行跑多航线同时搜索、多维度并行评估
Orchestrator-Workers动态拆解任务给多个 worker复杂多段行程的分段规划
Evaluator-Optimizer一个生成、一个评估迭代优化方案生成 + 方案质量审查

核心原则 "Success in the LLM space isn't about building the most sophisticated system. It's about building the right system for your needs." —— Anthropic: Building Effective Agents

七、对机票 AI 订票助手的总体建议

综合以上研究，对照 AI订票助手-Harness工程方案，补充以下建议：

7.1 架构层面

层级当前状态建议补充
Instruction Layer方案分散在多份文档中建立统一 AGENTS.md，按 GitHub 六大核心领域组织
Tool Surface8 个核心工具已定义补充工具示例、response_format、命名空间，参考 Anthropic 工具设计原则
Context Layer概念阶段定义 Booking Context Graph 最小实体模型，实现 Write/Select/Compress/Isolate 四策略
Governance Layer有红线意识落实结构化治理：confirmation token、三级权限、审计日志
Evaluation Layer提了 promptfoo按四维度（任务/工具/治理/业务）建立评估基线
Skills无按渐进式披露设计 booking-rules / risk-assessment / pricing-strategy Skills

7.2 工程实践

  1. 先跑最小闭环：搜索 → 评估 → 推荐，不急着打通交易
  2. Harness 优先于 Prompt：把精力投在工具面设计、上下文管理上，而不是雕 Prompt
  3. 评估驱动迭代：每轮优化都先看 eval 指标，不靠感觉
  4. 子代理做上下文隔离：风险评估、价格比较、行程规划各用独立子代理
  5. 治理内嵌而非外挂：下单必须 token 门控，不能靠"提醒模型"

7.3 推荐阅读优先级

必读清单（按优先级排序）

  1. OpenAI: Harness Engineering — 开创性文章，理解整体理念
  2. Anthropic: Building Effective Agents — 五大模式，最实用的架构指南
  3. LangChain: Anatomy of Agent Harness — Agent = Model + Harness 核心公式
  4. Anthropic: Writing Tools — 工具设计原则，直接指导我们的 8 个工具
  5. Anthropic: Context Engineering — 四策略框架，解决订票场景的上下文膨胀
  6. LangChain: Improving Deep Agents — 纯 Harness 优化提升 13.7 分的实证
  7. Fowler: Humans and Agents — "On the Loop" 治理哲学
  8. Anthropic: Agent Skills — 渐进式披露，解决领域知识注入
  9. GitHub: Great AGENTS.md — 指令层设计最佳实践
  10. LangChain: State of Agent Engineering — 行业基准数据

八、关键结论

三句话总结

  1. Harness Engineering 是 2026 年 AI Agent 工程的核心学科——模型是商品化的，基础设施才是护城河
  2. Agent = Model + Harness——投资方向应是工具面、上下文管理、治理规则、评估体系，而非等更好的模型
  3. 先跑最小闭环，再扩展能力图谱——Anthropic、OpenAI、LangChain 三大阵营的共识

一个等式

订票 Agent 竞争力=Model Quality×Harness Quality2\text{订票 Agent 竞争力} = \text{Model Quality} \times \text{Harness Quality}^2

模型质量线性增长（且所有竞对共享），而 Harness 质量是指数级放大器——这才是我们应该投资的方向。

  • AI订票助手-Harness工程方案
  • Harness Engineering 资料索引
  • 原始资料目录：学习分享/Harness Engineering/原始资料/
本章目录
一、Harness Engineering 是什么二、技术体系全景三、六大核心能力域四、Anthropic 的长期运行 Agent Harness 模式五、生产案例：Klarna 的经验与教训六、Claude Agent SDK 与工具体系七、对机票 AI 订票助手的总体建议八、关键结论Related Documents
苏ICP备2025204887号-2