IT架构师

奔赴山海，保持热爱

0%

AI Harness 工程崛起：Agent 的操作系统

发表于 更新于 分类于
本文字数： 7.5k 阅读时长 ≈ 14 分钟
AI Harness 是决定 AI Agents 能否在生产环境工作的缺失架构层。本文详解 Harness 的核心定位、六大组件和 OpenClaw 实战实现。

AI Harness 工程崛起：Agent 的操作系统

写在前面：2026 年，OpenAI 和 Anthropic 不约而同地使用了一个新术语——Harness。这不是流行词，而是决定 AI Agents 能否在生产环境真正工作的缺失架构层。

一、核心定义：Harness 不是什么

1.1 一个精妙的类比

2025 年 6 月，Philipp Schmid 提出了一个被广泛引用的计算机架构类比：

计算机组件 图标 AI Agent 对应 作用
CPU 🖥️ Model (模型) 原始处理能力
RAM 💾 Context Window (上下文窗口) 有限工作记忆
OS ☁️💻 Agent Harness 操作系统
Application 🖥️ Agent (智能体) 最终应用

核心洞察：

1
2
Harness ≠ Agent
Harness 是管理 Agent 如何运行的软件系统

1.2 为什么需要 Harness？

没有 Harness 的 Agent 就像没有操作系统的 CPU：

问题 没有 Harness 有 Harness
上下文管理 手动加载，容易溢出 自动压缩 + 检索
工具调用 硬编码，难以扩展 声明式注册，即插即用
错误处理 每次都要自己实现 内置重试 + 恢复
子任务编排 无法管理 可 spawn 多个子 Agent
记忆持久化 会话结束即丢失 向量数据库长期存储
安全控制 无防护 敏感操作需人工批准

Harness 的目标：让模型专注于推理，其他一切都自动化。

二、架构位置：Harness 与 SDK/Framework 的关系

2.1 四层架构栈

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
┌─────────────────────────────────────────┐
│  How you build (如何构建 Agent)          │
│  ┌─────────┬─────────────┬───────────┐ │
│  │   SDK   │ Scaffolding │ Framework │ │
│  │(灵活)    │ (有主见)     │ (有主见)   │ │
│  └─────────┴─────────────┴───────────┘ │
│           "the agent layer"              │
├─────────────────────────────────────────┤
│         Harness (如何运行 Agent)          │
│   (runtime & orchestration layer)       │
│  ├─ Agent Lifecycle Management          │
│  ├─ Tool Management                     │
│  ├─ Memory & Context                    │
│  └─ Safety & Observability              │
└─────────────────────────────────────────┘

关键理解：

  • SDK/Framework/Scaffolding 回答的是”如何构建“AI Agent
  • Harness 回答的是”如何运行“AI Agent
  • Harness 不是替代品，而是更高的一层

2.2 实际例子

项目 构建方式 Harness
Claude Code Anthropic SDK Anthropic 自研 Harness
OpenAI Codex OpenAI API OpenAI 自研 Harness
OpenClaw 多模型 API 自研 ACP Harness

三、Harness 的六大核心组件

根据 parallel.ai 团队的研究，结合 OpenAI/Anthropic 的实践，Harness 包含六个核心组件：

3.1 工具集成层 (Tool Integrations)

职责：通过定义的协议将模型连接到外部 API、数据库、代码执行环境和自定义工具。

设计要点：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 声明式工具注册
@tool
def get_weather(city: str) -> str:
    """Get current weather for a city"""
    return weather_api.get(city)

@tool
def execute_command(cmd: str) -> str:
    """Execute shell command (requires approval)"""
    if is_destructive(cmd):
        require_human_approval()
    return subprocess.run(cmd, shell=True)

# Harness 自动处理：
# 1. 解析模型的工具调用请求
# 2. 验证参数
# 3. 执行工具
# 4. 注入结果到上下文
# 5. 继续推理

OpenClaw 实现：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# OpenClaw 工具注册配置
tools:
  - name: web_search
    handler: src/tools/web-search.ts
    requiresApproval: false
    timeoutMs: 10000
    
  - name: exec
    handler: src/tools/exec.ts
    requiresApproval: true  # 需要人工批准
    allowlist:
      - "ls"
      - "cat"
      - "grep"
    denylist:
      - "rm"
      - "sudo"

3.2 内存与状态管理 (Memory & State)

职责：多层内存管理，在单个上下文窗口之外持久化状态。

三层记忆架构：

层级 存储内容 访问方式 示例
工作记忆 当前任务状态 内存驻留 进行中任务的中间结果
短期记忆 对话历史 自动加载 最近 10 轮对话
长期记忆 向量数据库 检索召回 用户偏好、历史决策

OpenClaw 实现：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// OpenClaw 记忆系统架构
interface MemorySystem {
  // 工作记忆 - 当前 Session 状态
  workingMemory: SessionState;
  
  // 短期记忆 - 对话历史
  shortTermMemory: Message[];
  
  // 长期记忆 - LanceDB 向量检索
  longTermMemory: LanceDBVectorStore;
  
  // 记忆检索
  async recall(query: string, limit: number = 5): Promise<Memory[]>;
  
  // 记忆存储
  async store(text: string, metadata: MemoryMeta): Promise<void>;
}

Anthropic 的方法：使用进度文件 (.progress.md) 和 git 历史记录来桥接会话，实现跨会话记忆。

3.3 上下文工程 (Context Engineering)

职责：动态策划每次模型调用中出现的信息，而不是静态的提示模板。

核心挑战：模型上下文窗口有限（如 128K），如何管理？

Harness 的解决方案：

1
2
3
4
5
6
7
8
9
10
11
1. 上下文压缩
   └─→ 移除冗余信息，保留关键决策点

2. 记忆检索
   └─→ 从向量数据库召回相关内容

3. 分层管理
   └─→ 系统提示词 / 短期记忆 / 长期记忆

4. 动态注入
   └─→ 按需加载，用完即释放

OpenClaw 实现：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// 上下文管理器
class ContextManager {
  private maxContextTokens = 128000;
  
  async buildContext(task: Task): Promise<string> {
    // 1. 基础系统提示词
    let context = this.systemPrompt;
    
    // 2. 检索相关记忆
    const memories = await this.memory.recall(task.description);
    context += this.formatMemories(memories);
    
    // 3. 加载相关文档
    const docs = await this.docs.findRelevant(task.tags);
    context += this.formatDocs(docs);
    
    // 4. 检查是否超限，自动压缩
    if (this.countTokens(context) > this.maxContextTokens) {
      context = await this.compress(context);
    }
    
    return context;
  }
}

3.4 规划与路由 (Planning & Routing)

职责：引导模型通过结构化的任务序列，而不是试图一次性完成所有事情。

任务分解流程：

1
2
3
用户任务 → 意图理解 → 任务分解 → 子任务执行 → 结果汇总
   ↓
"写个博客" → 确定主题 → 查资料 → 写大纲 → 写正文 → 格式化 → 发布

OpenClaw 的子 Agent 编排：

1
2
3
4
5
主 Agent (协调者)
    ├── 子 Agent 1 (产品经理) → 需求分析
    ├── 子 Agent 2 (架构师) → 技术方案
    ├── 子 Agent 3 (开发者) → 编码实现
    └── 子 Agent 4 (测试员) → 质量验证

关键设计：

  • 工作空间隔离 - 每个子 Agent 有自己的私有目录
  • 记忆共享 - 共享 MEMORY.md 和关键文档
  • 主 Agent 审核 - 合并前需要主 Agent 审核

3.5 验证与防护 (Validation & Guardrails)

职责：输出检查、格式验证、安全过滤器、自我纠正循环。

安全层级：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
┌─────────────────────────────────┐
│  L1: 输入验证                    │
│  - 参数类型检查                  │
│  - 长度限制                      │
│  - 敏感词过滤                    │
├─────────────────────────────────┤
│  L2: 执行控制                    │
│  - 破坏性命令需批准              │
│  - 外部 API 调用限流              │
│  - 资源使用配额                  │
├─────────────────────────────────┤
│  L3: 输出审核                    │
│  - 格式验证                      │
│  - 内容安全检查                  │
│  - 敏感信息脱敏                  │
└─────────────────────────────────┘

OpenClaw 实现：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// 执行批准流程
async function executeWithApproval(command: string): Promise<string> {
  // 1. 检查是否在允许列表中
  if (ALLOWED_COMMANDS.includes(command.split(' ')[0])) {
    return execute(command);
  }
  
  // 2. 检查是否在拒绝列表中
  if (DENIED_COMMANDS.includes(command.split(' ')[0])) {
    throw new Error(`Command not allowed: ${command}`);
  }
  
  // 3. 其他命令需要人工批准
  const approval = await requestHumanApproval(command);
  if (!approval) {
    throw new Error('Approval denied');
  }
  
  return execute(command);
}

3.6 模块化与可扩展性 (Modularity & Extensions)

职责：可插拔组件，可以独立启用、禁用或替换。

OpenClaw 插件架构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
// 插件接口
interface OpenClawPlugin {
  name: string;
  version: string;
  
  // 生命周期
  onStart(): Promise<void>;
  onStop(): Promise<void>;
  
  // 工具注册
  registerTools(): Tool[];
  
  // 事件订阅
  subscribeEvents(): EventHandler[];
}

// 插件示例：Feishu 集成
class FeishuPlugin implements OpenClawPlugin {
  name = 'feishu';
  version = '1.0.0';
  
  async onStart() {
    // 初始化 Feishu API 客户端
    this.client = new FeishuClient(config);
  }
  
  registerTools() {
    return [
      { name: 'feishu_send_message', handler: this.sendMessage },
      { name: 'feishu_read_doc', handler: this.readDoc },
      { name: 'feishu_create_doc', handler: this.createDoc },
    ];
  }
}

四、生产环境中的真实 Harness

4.1 Claude Code

Claude Code 本质上是一个 Harness：

  • ✅ 读取整个代码库
  • ✅ 管理文件系统访问
  • ✅ 生成子 agent（如 test-runner、linter）
  • ✅ 处理工具编排
  • ✅ 跨会话维护内存（.progress.md）
  • ✅ 实现防护（敏感操作需确认）

用户体验：

1
2
3
4
5
6
7
8
9
$ claude "添加用户登录功能"

Claude 内部流程：
1. 读取项目结构（工具：read_dir）
2. 分析现有认证代码（工具：read_file）
3. 生成实现方案（模型推理）
4. 编写代码（工具：write_file）
5. 运行测试（工具：exec，spawn 子 agent）
6. 提交 git（工具：exec，需确认）

开发者专注于任务，Harness 管理其他所有事情。

4.2 OpenAI Codex

OpenAI 团队的实践：

  • 构建了超过 100 万行 的代码库
  • 完全没有手动输入的代码
  • Harness 作为主要接口

关键实践：

  1. 上下文工程 - 维护代码库的向量索引
  2. 架构约束 - 定义代码规范和目录结构
  3. 定期清理 - Agent 自动重构和清理代码
  4. 反馈循环 - 当 Agent 遇到困难时，改进存储库

4.3 OpenClaw ACP Harness

OpenClaw 的 Harness 实现：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
┌─────────────────────────────────────┐
│      OpenClaw Gateway (控制平面)     │
├─────────────────────────────────────┤
│  AcpSessionManager (每 Session 一 Actor)│
│  ├── SQLite 持久化                   │
│  ├── 幂等性控制                      │
│  ├── 事件日志 (append-only)          │
│  └── 交付检查点                      │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│      ACP Runtime Backend (插件化)    │
├─────────────────────────────────────┤
│  第一个实现：acpx (Codex/Claude Code) │
└─────────────────────────────────────┘

关键特性：

特性 实现方式
Thread Binding Discord 线程绑定到 Session
流式交付 分块 coalesce，避免 rate limit
故障恢复 Gateway 重启后从 SQLite 恢复
并发控制 每 Account 最大并发 Session 数
幂等性 所有命令带 idempotency key

Session 状态机：

1
2
3
4
5
creating → idle → running → idle
            ↓        ↓
         cancelling → error
            ↓        ↓
           closed ←──┘

五、为什么 Harness 很重要？

5.1 对开发者的价值

价值 说明
降低门槛 不用重复造轮子，专注业务逻辑
提高效率 内置最佳实践，开箱即用
保证质量 内置错误处理、重试、日志

5.2 对企业的价值

价值 说明
可审计 所有操作有日志，可追溯
可控制 敏感操作需批准，风险可控
可扩展 插件化架构，按需扩展

5.3 对未来的意义

Harness 是 AI Agent 大规模应用的基础设施：

1
2
3
2024-2025: Agent 探索期 (各种 Framework 涌现)
2026-2027: Harness 成熟期 (OpenAI/Anthropic 入局)
2028+:    生态爆发期 (Harness 成为标准基础设施)

类比历史：

  • 1980s：个人电脑爆发 → 需要操作系统
  • 2000s：智能手机爆发 → 需要 iOS/Android
  • 2020s：AI Agent 爆发 → 需要 Harness

结论：今天的 Harness = 明天的操作系统

六、总结

核心要点回顾

  1. Harness ≠ Agent，Harness 是管理 Agent 如何运行的系统
  2. 架构位置：Harness 在 SDK/Framework 之上，是运行时管理层
  3. 六大组件：工具集成、记忆管理、上下文工程、规划路由、安全验证、模块化扩展
  4. 生产案例：Claude Code、OpenAI Codex、OpenClaw ACP
  5. 未来趋势：Harness 将成为 AI Agent 的标准基础设施

下一步

  • 第 99 篇：《AI Harness 实战：Thread-Bound Agent 的完整链路》
  • 第 100 篇：《100 篇博客复盘：用 AI Harness 管理技术写作》🎯

参考资源

  1. Philipp Schmid 的计算机类比
  2. parallel.ai 团队研究
  3. OpenAI Codex 技术博客
  4. Anthropic Claude Code 文档
  5. OpenClaw ACP 架构文档：https://docs.openclaw.ai/experiments/plans/acp-thread-bound-agents.md
  6. Martin Fowler 关于 Harness 的文章

本文是 AI Harness 系列的第 98 篇，下一篇将深入实战，详解如何在 OpenClaw 中实现完整的 Harness 系统。