企业官网建设流程全解析

【Harness Agent】源码剖析（一）：项目全景——SOTA Coding Agent 的架构哲学

写在前面：拆完 OpenClaw（43 万行）、LangGraph（3 万行）、Pocket Flow（100 行）之后，今天我们来看一个"中间路线"的项目——Harness Agent。它不是最大的，不是最小的，但它是唯一在 Harness-Bench 上得分100%的开源 Coding Agent，超越了 Claude Code 和 Cursor。它的核心论点是：LLM 提供智能，Harness 提供一切其他——手（工具执行）、眼（文件读取）、记忆（Memory）、安全（沙箱+权限）、协作（多 Agent）。今天起，我将用3 篇文章，带你从源码层面彻底搞懂 Harness Agent 的每一个核心子系统。这是第一篇——理解 Harness Agent 的架构全貌。

📑 文章目录

• 📌 一、Harness Agent 是什么？不是什么？
• 🏗️ 二、五层架构：从 CLI 到 Plugin 的分层设计
• 🔄 三、Agent Loop：五阶段循环引擎
• 📂 四、源码目录结构：16 个子包的精巧布局
• 🤖 五、双 Agent 模式：Initializer + Coder
• ⚖️ 六、Harness vs LangGraph vs OpenClaw：三种 Agent 哲学
• 🔮 七、系列预告

📌 一、Harness Agent 是什么？不是什么？

1.1 Harness Agent 不是什么

很多人看到 “Harness Agent” 这个名字，第一反应是：这不就是又一个 Coding Agent 吗？和 Claude Code、Cursor、Aider 有什么区别？这种理解太浅了。Harness Agent 不是一个"编辑器插件"——它是一个完整的Agent 运行时基础设施。它不绑定任何 IDE，不绑定任何模型，甚至不绑定任何编程语言。

1.2 Harness Agent 是什么

Harness Agent 是一个开源的、模型无关的 Coding Agent 运行时，提供从 LLM 调用到工具执行、沙箱隔离、审计追溯的全栈基础设施。这句话里有四个关键词：

1.3 “Agent Harness” 概念

Harness 这个名字来自一个核心概念——Agent Harness。它的定义是：

An Agent Harness is the complete infrastructure that wraps around an LLM to make it a functional agent. The model provides intelligence; the harness provides hands, eyes, memory, and guardrails.

翻译过来就是：Harness 是包裹在 LLM 外面的完整基础设施。模型提供智能，Harness 提供手（工具执行）、眼（文件读取）、记忆（Memory）和护栏（安全机制）。

这个概念非常重要，因为它定义了 Harness 的设计边界——Harness 不关心 LLM 内部怎么"思考"，只关心 LLM “想做什么"和"做了什么”。这种分离使得 Harness 可以适配任何 LLM，而不需要修改基础设施代码。

🏗️ 二、五层架构：从 CLI 到 Plugin 的分层设计

Harness Agent 的架构可以清晰地分为五层，每层职责明确，层间通过定义良好的接口通信：

2.1 五层概览

2.2 层间通信

层间通信遵循一个简单原则：上层依赖下层，下层不知道上层存在。具体来说：

• CLI/SDK 调用 Core Engine 的engine.py启动 Agent Loop
• Core Engine 通过agents/registry.py获取 Agent 配置
• Core Engine 通过sandbox/executor.py执行工具
• Core Engine 通过providers/调用 LLM
• 工具执行前后触发hooks/钩子

这种分层设计的好处是：每一层都可以独立测试和替换。比如，你可以用不同的 Provider（Claude/GPT/Ollama）而不影响 Core Engine 的逻辑；你可以用不同的 Sandbox（Docker/本地/远程）而不影响 Agent Loop 的流程。

🔄 三、Agent Loop：五阶段循环引擎

Harness Agent 的核心运行时是一个五阶段循环，定义在core/loop.py和core/engine.py中：

3.1 五阶段详解

Phase 1: Steering（导航）— 决定下一步做什么。Steering 模块读取当前上下文（对话历史 + 工作区状态），决定是继续推理、调用工具还是结束循环。这是整个循环的"大脑"。

Phase 2: LLM Call（模型调用）— 调用 LLM 生成响应。通过providers/适配不同的模型 API，支持流式输出。LLM 的响应可能包含文本输出或工具调用请求。

Phase 3: Tool Execution（工具执行）— 如果 LLM 请求调用工具，解析工具调用参数，通过tools/或mcp/执行。工具执行在沙箱中进行，受权限系统约束。

Phase 4: Sandbox Validation（沙箱验证）— 在工具执行前和执行后，沙箱系统验证操作是否安全。包括：命令白名单检查、文件路径验证、网络访问限制。如果验证失败，拒绝执行并返回错误信息。

Phase 5: Audit（审计记录）— 记录所有工具调用、文件修改、模型响应到审计日志。支持回放、合规检查、事后追溯。

3.2 与其他框架的对比

📂 四、源码目录结构：16 个子包的精巧布局

Harness Agent 的源码组织在src/harness/下，共 16 个子包，按职责分为 5 大模块：

4.1 核心模块（core/）

core/ ├── engine.py # Agent Loop 主引擎 ├── loop.py # 循环逻辑 ├── session.py # 会话管理 ├── steering.py # 导航决策 ├── context.py # 上下文组装 └── config.py # 配置管理

这是整个框架的心脏。engine.py是入口，loop.py定义循环逻辑，steering.py决定每一步的方向，session.py管理会话状态，context.py组装 LLM 的输入上下文。

4.2 Agent 模块（agents/）

agents/ ├── registry.py # Agent 注册表 └── manager.py # Agent 生命周期管理

Harness Agent 支持双 Agent 模式——Initializer Agent 负责规划和分解任务，Coder Agent 负责执行具体编码。两个 Agent 通过 Shared Context 协作。

4.3 基础设施模块

sandbox/ # 沙箱执行环境 permissions/ # 权限控制系统 audit/ # 审计日志 observability/ # 可观测性

这四个子包构成了 Harness 的"安全底座"。沙箱隔离工具执行，权限控制文件访问，审计记录所有操作，可观测性提供追踪和监控。

4.4 插件生态模块

providers/ # 多模型适配（Claude/GPT/Gemini/Ollama） tools/ # 内置工具集（Bash/文件/搜索/Git） mcp/ # MCP 协议集成 skills/ # 技能系统 hooks/ # 钩子机制

4.5 其他模块

cli/ # 命令行入口 ui/ # 终端 UI 渲染 types/ # 类型定义 memory/ # 记忆管理 ci/ # CI/CD 集成

🤖 五、双 Agent 模式：Initializer + Coder

5.1 为什么需要两个 Agent？

单个 Agent 面临一个根本矛盾：规划需要"大局观"，执行需要"细节控"。一个 Agent 同时做两件事，容易顾此失彼——要么规划不够深入就急于编码，要么编码时忘记了整体架构。

Harness 的解法是双 Agent 模式：

5.2 协作流程

1. 用户输入任务描述
2. Initializer Agent 分析需求，生成任务分解和执行计划
3. 计划写入 Shared Context
4. Coder Agent 读取计划，逐步执行每个子任务
5. 每个子任务完成后，Coder 更新 Shared Context
6. 如果 Coder 遇到无法解决的问题，回退到 Initializer 重新规划

这种模式的优势是：Initializer 只在需要时运行（通常只在会话开始时），大部分时间由 Coder 高效执行。这既保证了规划质量，又不会因为频繁的"重新规划"拖慢执行速度。

⚖️ 六、Harness vs LangGraph vs OpenClaw：三种 Agent 哲学

6.1 三种哲学

• Harness：安全优先。所有工具执行都在沙箱中，所有操作都有审计记录。适合安全敏感的 Coding 场景。
• LangGraph：状态优先。Channel/Reducer 精确管理状态，BSP 模型天然支持 Checkpoint。适合复杂的有状态工作流。
• OpenClaw：调度优先。Gateway 统一调度 25+ 平台，Lane Queue 保证消息不串。适合多平台 Agent 部署。

🔮 七、系列预告

第二篇，我们将深入 Harness Agent 最核心的子系统——Core Engine 与 Steering：

关注我，不要错过后续更新！

🎁 总结速查卡

Harness Agent 核心概念

五层架构速查

一句话总结

Harness Agent 的核心论点是"Agent Harness"——LLM 提供智能，Harness 提供一切其他。五阶段循环（Steering → LLM → Tool → Sandbox → Audit）确保每一步都安全可控，双 Agent 模式（Initializer + Coder）确保规划与执行各司其职，16 个子包覆盖从 CLI 到 Plugin 的完整技术栈。它不是最大的框架，但它是唯一在 Harness-Bench 上得分 100% 的开源 Coding Agent——安全优先，全栈内置，模型无关。

参考链接：

• Harness Agent GitHub 仓库
• Harness Agent PyPI
• Harness SDK 教程
• OpenHarness 官网
• Harness-Bench 基准