note-md

Harness 工程总览

1. 什么是 Harness 工程

Harness（线束）是围绕 LLM 的运行时编排系统。如果说 LLM 是引擎，Harness 就是整辆车——底盘、传动、制动、导航。

Martin Fowler 的定义：

Harness Engineering 是用于保持 AI Agent 可控的工具和实践——管理工具执行、消息历史、上下文和安全的”外层循环”。

1.1 Scaffolding vs Harness

这两个概念经常混用，但有明确的时间维度区别：

概念 时机 职责 类比
Scaffolding 构建时（启动前） 组装系统提示、工具 Schema、子 Agent 注册 搭建舞台
Harness 运行时（启动后） 协调工具执行、管理上下文、安全执行、会话持久化 演出导演

典型的 Agent 系统中，两者分工明确：

具体到 Claude Code 的 Scaffolding/Harness 实现，详见第8章 Claude Code 深度解析。

2. 三部分架构（Martin Fowler / OpenAI）

2.1 上下文工程层

Harness 的第一职责是管理上下文的组装和维护：

2.2 架构约束层

通过确定性工具而非 LLM 来强制执行规则：

关键洞察：不要让 LLM 自己判断是否遵守规则——用代码强制执行。

2.3 周期性清理

自主 Agent 对抗熵增：

3. 工具系统设计

3.1 Registry-Based Dispatch

中央 ToolRegistry 将工具名映射到类型化的处理器：

ToolRegistry
├── read    → ReadHandler (file_path, offset, limit)
├── write   → WriteHandler (file_path, content)
├── execute → ExecuteHandler (command, timeout)
└── connect → ConnectHandler (target, payload)

通用设计原则：

3.2 工具描述设计

工具描述（description）是 LLM 决定何时调用工具的唯一依据：

3.3 鲁棒性增强

LLM 输出的工具调用参数可能存在微小偏差。生产系统需要容错机制：

4. 安全防御体系

五层纵深防御（Defense-in-Depth）：

Layer 1: Prompt 护栏
│  系统提示中的行为约束和规则
│
Layer 2: Schema 限制
│  工具参数的类型和范围验证
│
Layer 3: 运行时审批
│  高危操作需用户确认（destructive actions）
│
Layer 4: 工具验证
│  执行前检查（文件存在性、权限、安全扫描）
│
Layer 5: 生命周期钩子
   执行前/后的自定义逻辑（pre-hook, post-hook）

关键设计决策：

安全体系的完整讨论，包括评测和可观测性，详见第9章 评测、可观测性与安全。

5. 运行时约束与渐进式降级

当资源（token、时间、工具调用次数）接近上限时，Harness 执行渐进式降级：

  1. 上下文压缩：自动总结历史对话
  2. 工具限制：减少可用工具集合
  3. 任务分解：将剩余工作拆分给子 Agent
  4. 优雅终止：保存进度，提示用户继续

原则：”当 Agent 挣扎时，不是 Agent 的问题——是 Harness 缺少了什么（工具、护栏、文档），把缺失的东西补上。”

6. 什么情况下不需要复杂 Harness

并非所有 Agent 系统都需要重型 Harness：

常见陷阱：

7. 实践建议

参考