Harness 深度技术解析：构建「观察-知识-工具-行动」新风口

以下是一篇技术导向的Harness技术文章，围绕你给出的**Tools、Knowledge、Observation、Action、Permissions**体系展开，并融入MCP、Shell、A2A、WebSocket等关键元素。

Harness 深度技术解析：构建「观察-知识-工具-行动」闭环的AI代理架构

**摘要**：在现代AI代理（Agent）设计中，如何将大语言模型（LLM）的推理能力转化为真实世界的行动，是一个核心挑战。Harness 提出了一种以 **Knowledge（知识）** 为中枢，**Observation（观察）** 为输入，**Tools（工具）** 为执行载体的架构。本文将从技术层面剖析 Harness 如何通过 MCP、Shell、CLI/API、A2UI 以及 WebSocket/A2A 协议，构建一个安全、实时、可扩展的智能代理运行时。

1. 核心架构全景

Harness 的设计哲学可抽象为一个五层模型：

Tools 工具：MCP、shell

Knowledge 知识

Observation 观察

↑

A2A/WebSocket        ← 通信与事件总线

↓

Action 行动：CLI/API/A2UI

Permissions 权限：沙箱

• **Knowledge**：系统对任务、环境、用户上下文的结构化理解，是决策的静态基础。
• **Observation**：来自外部世界的实时反馈，驱动动态决策。
• **Tools**：代理可调用的能力单元，包括本地进程（shell）和远程服务（MCP 工具）。
• **Action**：将决策转化为具体执行，涵盖命令行操作、API 调用和用户界面交互。
• **Permissions**：全程嵌入的沙箱安全层，确保行动受控。

这一模型的核心优势在于**闭环反馈**：Observation 持续流入 Knowledge，驱动下一步 Tools 选择与 Action 执行。

2. Knowledge：不只是 RAG，是代理的认知基座

在 Harness 中，**Knowledge** 远超简单的向量检索增强生成（RAG）。它是一个动态更新的**认知状态机**，包含：

• **任务知识**：从用户目标拆解的步骤和约束。
• **环境知识**：可用工具清单、系统状态、权限边界。
• **上下文知识**：对话历史、中间执行结果、错误堆栈。

技术实现上，Knowledge 层采用**混合存储**：

• **结构化知识**：基于 JSON Schema 的任务图和状态树，存储在内存或轻量级数据库中。
• **非结构化知识**：基于嵌入向量的长程记忆，支持语义检索。

Observation 数据到达后，通过一个**知识融合引擎**更新认知状态：如果是工具返回的结构化数据，直接合并入任务图；如果是文本日志，经过 LLM 摘要后注入上下文窗口。

3. Tools：MCP 与 Shell 的深度集成

Harness 的 **Tools** 层采用插件化设计，当前主要支持两大工具类型：

3.1 MCP 工具

Model Context Protocol (MCP) 提供了标准化的工具发现与调用接口。Harness 作为 MCP 客户端，连接多个 MCP 服务器（如文件系统服务、数据库服务、第三方 API 网关）。技术要点：

• **工具发现**：启动时通过 tools/list 获取所有可用工具及其 JSON Schema 定义。
• **延迟绑定**：LLM 根据 Observation 动态选择工具，而非预编译工具链。
• **流式响应**：通过 MCP 的流式扩展，支持长耗时工具（如模型训练）的进度观测。

3.2 Shell 工具

Shell 是本地系统的最强接口。Harness 对 Shell 的封装不是简单的 subprocess.run()，而是：

• **PTY 模拟**：支持交互式命令（如 vim、ssh）。
• **会话持久化**：维护 Shell 会话的工作目录和环境变量，支持多步操作上下文。
• **输出智能截断**：对超大输出流进行 LLM 引导式摘要，防止上下文窗口溢出。

两种工具通过统一的 **ToolExecutor** 抽象调度，对外暴露一致的调用接口：(tool\_name, params) -> Observation。

4. Observation 与 A2A/WebSocket 事件通道

**Observation** 是来自外部世界的任何信号。Harness 设计了两层观测通道：

4.1 本地工具观测

工具执行产生的结构化输出、标准输出/错误流、退出码，被封装为 Observation 对象。该对象携带元数据：来源工具、时间戳、执行耗时。

4.2 远程代理观测（A2A 协议）

在分布式场景中，一个 Harness 代理需要观察另一个代理的状态。**Agent-to-Agent (A2A) 协议** 通过 WebSocket 实现双向事件流。该协议定义了：

• **状态广播**：代理上线、下线、任务进度。
• **子任务委托**：主代理将子任务发布到 A2A 通道，工作代理领取并回传 Observation。
• **心跳与熔断**：断连检测和任务重分配。

4.3 WebSocket 传输层

WebSocket 是 A2A 的底层传输，也是 Harness 与前端 UI (A2UI) 通信的桥梁。技术细节：

• **全双工推拉**：代理主动推送 Observation 流到 UI，用户可在任意时刻注入人工观察（Human-in-the-Loop）。
• **二进制帧优化**：使用 Protocol Buffers 序列化 Observation 对象，减少大尺寸输出的传输开销。

5. Action：CLI、API 与 A2UI 的三维执行器

Action 层将 LLM 决策转化为现实世界的副作用。Harness 定义了三种 Action 类型：

• **CLI Action**：执行本地或远程 Shell 命令，通过工具层的 Shell 能力实现。
• **API Action**：发起 HTTP/gRPC 调用，集成企业微服务或外部 SaaS。
• **A2UI Action**：这是 Harness 的独特设计——**将代理行动指向用户界面**。代理可生成 UI 片段（如表单、确认对话框、数据可视化），要求用户完成某些操作，用户的交互结果作为 Observation 回流。

A2UI Action 的实现基于 **微前端沙箱**：代理输出的 UI 组件在浏览器隔离的 Shadow DOM 中渲染，通过 postMessage 与主应用通信，受权限策略严格控制。

6. Permissions：全程嵌入的沙箱安全

权限不是外围的“守门人”，而是嵌入每一层的正交切面。

6.1 工具级权限

每个工具注册时声明所需权限（如 filesystem.read:/data/\*）。ToolExecutor 在调用前查询权限策略引擎（基于 OPA/Rego）。

6.2 Shell 沙箱

Shell 工具运行在**双重沙箱**中：

• **OS 级**：Linux Capabilities 限制、Seccomp 系统调用过滤、只读根文件系统。
• **用户级**：Bash 的 restricted mode 或 Firejail 封装。

6.3 A2UI 沙箱

代理生成的 UI 只能访问显式许可的浏览器 API，所有用户输入数据在传回代理前经过净化。

6.4 动态最小权限

Knowledge 层的任务图包含预期操作范围，Harness 动态计算最小必需权限集，当 Action 超出范围时自动阻断并要求人工审批（A2UI 交互）。

7. 闭环运行全景：一个 DevOps 排障案例

假设代理收到“分析 Nginx 最近 5 分钟的 500 错误”任务，技术闭环如下：

1. **Knowledge** 初始化任务图：解析日志 → 分析原因 → 建议修复。
2. **Action (CLI)**：grep " 500 " /var/log/nginx/access.log。
3. **Tools (Shell)**：ToolExecutor 检查权限（filesystem.read:/var/log/nginx/\*）后，在沙箱中执行。
4. **Observation**：标准输出（500 错误条目）封装为 Observation。
5. **Knowledge 更新**：LLM 分析发现多个 /api/payment 错误。
6. **Action (API)**：调用监控 API 获取 payment-service 健康状态。
7. **Observation**：API 返回 503，服务不可用。
8. **Action (A2UI)**：代理生成诊断报告 UI，包含建议重启服务按钮。
9. **等待用户交互**：用户点击“确认重启”，该交互作为 Observation 回流。
10. **Action (CLI)**：sudo systemctl restart payment-service，需 process.manage 权限，策略引擎放行。
11. **Observation**：服务恢复正常，任务闭环。

全程 WebSocket 将每一步 Observation 实时推送至监控仪表板，A2A 协议允许运维团队中的其他代理（如安全审计代理）监听事件。

结语

Harness 通过严格分离 **Tools、Knowledge、Observation、Action、Permissions** 五个正交层，并借助 **MCP** 实现工具标准化，**A2A/WebSocket** 实现通信实时化，**A2UI** 实现人机协同闭环，构建了一套生产级 AI 代理架构。这一模式不仅适用于 DevOps 场景，也可推广至智能客服、自动化测试、数据工程等广泛领域。

论文地址 30658.t.kuaisou.com