一个通用的AI Agent平台应该具备哪些Harness工程技术底座能力

大家好，今天继续讲Harness技术平台能力。今天这篇文章结合开源项目Abu-Cowork源代码进行逆向工程后进行分析整理。但是大家注意，这些Harness的底层技术能力实际是我们构建任何通用智能体，或者去构建一个通用的Harness技术底座的必备能力。

Harness 是 AI Agent 平台的"底盘"——它不是大模型本身，也不是面向用户的 UI，而是连接模型与真实世界的执行骨架：管理记忆、调度工具、控制权限、编排任务。本文从一个通用 Agent 平台的工程视角出发，系统梳理构成 Harness 的各项关键技术底座。

一、整体架构概览

在深入各项能力之前，先看 Harness 在 Agent 平台中的位置：

Harness 的核心职责：让 Agent 安全、可靠、有记忆地连接模型能力和真实世界。下面逐一展开。

二、存储与记忆系统：让 Agent 拥有"长期记忆"

2.1 三层记忆架构

通用 Agent 的记忆系统应设计为分层结构，每层有明确的职责边界和生命周期：

2.2 记忆的自动积累与召回

一个好的记忆系统不应要求用户手动编写，而应具备自动积累机制：

• 写入：Agent 在对话中识别有价值的信息（用户说"我习惯用 TypeScript"），自动写入对应层级的记忆文件。
• 召回：每次新对话开始时，根据相关性评分自动加载相关记忆片段到上下文窗口。相关性算法可以基于关键词匹配、语义相似度或时间衰减加权。
• 老化：记忆应有时效性——用户两年前的习惯可能已经改变，需要基于 TTL（Time To Live）的衰减机制。

2.3 项目规则与指令

除了自动积累的记忆，还需要支持确定性规则——用户手动编写的项目级指令（如"始终使用 pnpm 不要用 npm""禁止引入超过 500KB 的依赖"）。这些规则不会被自动修改，Agent 每次都严格遵守，且可作为项目代码的一部分随 git 提交。

三、会话状态管理：对话的生命周期

3.1 会话模型

一个通用 Agent 平台需要管理完整的会话生命周期：

[创建] → [活跃] → [暂停/归档] → [恢复] → [删除]
   |         |
   |         +→ [Checkpoint 快照]
   |         +→ [消息流式传输]
   |         +→ [工作区绑定]
   +→ [标题自动生成]

核心状态包括：

• 消息列表：user、assistant、system 三种角色，支持多模态内容（文本、图片、文件、工具调用结果）
• 对话元数据：标题、创建时间、最后活跃时间、工作区路径
• 执行状态：idle（空闲）、running（运行中）、waiting_for_user（等待用户输入）、error（出错）
• 工具调用状态：每个工具调用的入参、返回结果、执行时间，以便回放和分析

3.2 持久化与恢复

• 自动持久化：每条消息到达时立即写入本地存储，不能依赖"会话结束时批量保存"（进程可能随时退出）。
• Checkpoint 快照：在关键节点（完成一个工具调用、用户打断、发生错误）自动创建快照，支持回退到任意历史点恢复对话。
• 跨设备同步：通过云端存储实现会话在不同设备间的无缝切换。

3.3 状态一致性

多个组件（UI、Agent Loop、调度器）可能同时读取会话状态，需要保证一致性。推荐使用事件驱动的状态同步，而非共享可变状态——每个模块持有自己的状态视图，通过事件总线同步变更。

四、上下文工程：Token 窗口的精细管理

4.1 上下文的组成

发送给 LLM 的上下文不是简单的"把所有历史消息串起来"。一个良好的上下文结构应分层组织：

4.2 Token 估算与压缩

• Tokenizer：在将内容发送给 LLM 之前，需要精确计算每条消息、每个工具定义的 token 消耗。不同模型有不同的 tokenizer（如 Claude 用 claude-tokenizer，OpenAI 用 tiktoken），需要按模型适配。
• Compaction（压缩）：当对话历史超过模型的上下文窗口限制时，自动将早期对话压缩为结构化摘要。压缩策略应区分"工具调用执行结果"（可高度压缩）和"用户表达偏好"（需保留语义）。
• 智能裁剪：不是机械地从最早的开始删，而是根据信息相关性决定保留哪些。用户 50 轮前说的"我的名字是张三"比 5 轮前的工具成功提示更重要。

4.3 Cacheable 标记

对于每次对话都相同的静态内容（如 system prompt 中的工具定义、技能列表），应标记为"可缓存"——利用 LLM 提供商的 prompt caching 能力（如 Anthropic 的 cache_control），大幅降低延迟和成本。

五、Skills 技能系统：Agent 的可编程扩展

5.1 技能的生命周期

Skill 是 Agent 能力的模块化扩展单元。一个完整的 Skills 系统需要覆盖：

+------------------------------------------------------------------+
| Skill 生命周期                                                      |
|                                                                    |
|  [创建] ──→ [安装] ──→ [注册] ──→ [调用] ──→ [更新] ──→ [卸载]     |
|    |          |         |         |         |         |            |
|    |   从市场安装   注入到     Agent按    用户/Agent   清理文件      |
|    |   或本地导入   System     需调用      触发更新    和注册        |
|    |             Prompt                                            |
+------------------------------------------------------------------+

5.2 技能的分层来源

5.3 技能的结构

每个 Skill 是一个包含以下文件的目录：

my-skill/
├── SKILL.md          # 技能描述（给 LLM 看的 instructions）
├── scripts/          # 可执行脚本
├── templates/        # 模板文件
└── references/       # 参考文档

SKILL.md 是核心——它包含：

• 技能名称和描述
• 触发条件（什么时候 Agent 应该调用这个技能）
• 使用指南（参数说明、输入输出格式）
• 示例

5.4 技能的自进化

当 Agent 在对话中发现"这个操作模式经常重复出现"，它应该有能力：

1. 建议用户创建 Skill
2. 自动提炼操作方法为 Skill 模板
3. 在使用中持续优化 Skill 的说明和脚本

六、MCP 协议：工具生态的标准化

6.1 MCP 架构

MCP（Model Context Protocol）是一个开放协议，定义了 AI 模型与外部工具/数据源之间的标准接口。Agent 平台作为 MCP Client，连接各种 MCP Server：

+-------------------+       stdio/HTTP/SSE        +-----------------+
|                   | ◄──────────────────────────► |  MCP Server A   |
|   Agent Platform  |                              | (filesystem)    |
|   (MCP Client)    | ◄──────────────────────────► +-----------------+
|                   |
|                   | ◄──────────────────────────► +-----------------+
|                   |        transport              |  MCP Server B   |
|                   |                              | (database)      |
+-------------------+                              +-----------------+

6.2 MCP Client 的关键能力

• 多传输协议：同时支持 stdio（子进程通信）和 HTTP/SSE（远程服务），自动发现和连接。
• 工具发现：启动时列出所有已配置的 MCP Server 的工具，合并到 Agent 的工具注册表。
• 懒加载与健康检查：不在启动时连接所有 Server（太慢），而是按需连接；定期心跳检测 Server 状态。
• 资源与提示词：MCP 不仅提供 "tools"，还支持 "resources"（数据文件、数据库表）和 "prompts"（预定义的对话模板）。

6.3 运行时管理

• 环境隔离：为 MCP Server 进程提供独立的 Node.js 运行时或 Python 运行时，不依赖系统全局环境。
• 权限代理：MCP Server 的操作权限最终由 Agent 平台的权限系统统一管理，Server 本身不受信任。
• 日志与监控：记录每次 MCP 调用的请求/响应、耗时、错误，用于调试和优化。

七、自动化任务与触发器：Agent 的自主运行

7.1 任务调度系统

Agent 不应只在用户对话时工作——许多场景需要 Agent 自主定时执行：

+------------------------------------------------------------------+
| Task Scheduler                                                    |
|                                                                    |
|  +------------------+  +------------------+  +----------------+  |
|  | Cron-based Tasks |  | Event Triggers   |  | Webhook         |  |
|  | "每天 9 点生成   |  | "文件变化时      |  | "GitHub PR      |  |
|  |  日报"           |  |  运行检查"       |  |  创建时触发"    |  |
|  +------------------+  +------------------+  +----------------+  |
+------------------------------------------------------------------+

7.2 任务定义

每个自动任务包含：

• 触发器：定时（cron 表达式）、事件（文件监听、webhook）、条件（某个指标超过阈值）
• Prompt：Agent 执行的指令
• 工作区：在哪个目录/项目上下文中执行
• 通知配置：完成后是否推送通知、发送 IM 消息
• 输出处理：执行结果保存到哪里

7.3 Headless 执行模式

自动任务需要在 headless 模式 下运行——不弹窗、不等待用户确认、不与 UI 交互。这个模式下的关键约束：

• 禁用需要用户确认的工具（如 request_workspace）
• 自动批准低风险操作
• 错误时降级处理（记录日志 + 通知，而不是 crash）

八、浏览器自动化：让 Agent 操作 Web

8.1 架构

浏览器自动化需要两部分协作：

+------------------+     Chrome Extension Bridge      +-----------------+
| Agent Platform   | ◄──────────────────────────────► | Browser          |
|                  |   (Native Messaging / WebSocket)  | (Chrome/Edge)    |
| +--------------+ |                                   | +-------------+ |
| | Bridge Client| |                                   | | Extension   | |
| +--------------+ |                                   | +-------------+ |
+------------------+                                   +-----------------+

8.2 核心能力

• 页面导航与内容提取：打开 URL、获取页面文本、提取结构化数据（表格、列表）
• 表单填写与提交：定位输入框、选择器，自动填写并提交
• 截图与视觉分析：截取页面截图，传给多模态模型进行分析
• Cookie/Session 管理：维护登录状态，处理认证流程
• 文件下载与上传：处理页面中的文件操作

8.3 安全边界

浏览器是高风险操作环境——Agent 可能误操作导致数据泄露或不可逆提交：

• 敏感域名单（银行、内部系统）默认禁止自动操作
• 金额输入、删除确认等高风险操作需用户二次确认
• 操作审计日志完整记录每一步

九、Computer Use：操作桌面应用的"眼睛和手"

9.1 能力图谱

Computer Use 让 Agent 能够像人一样操作图形界面应用：

+------------------------------------------------------------------+
| Computer Use Capabilities                                         |
|                                                                    |
|  +------------+  +------------+  +------------+  +------------+  |
|  | Screenshot |  | Mouse      |  | Keyboard   |  | Window     |  |
|  | Capture    |  | Click/Move |  | Type/Short |  | Management |  |
|  | (截屏)     |  | (鼠标操控)  |  | cut (键盘)  |  | (窗口管理)  |  |
|  +------------+  +------------+  +------------+  +------------+  |
+------------------------------------------------------------------+

9.2 技术实现要点

• 截图排除：截屏时需要排除 Agent 自身的窗口，否则会形成"无限镜子"效应。在 macOS 上可通过 CGWindowListCreateImage 排除指定窗口 ID；Windows 上需要先隐藏 Agent 窗口再截图。
• 窗口管理：自动隐藏/显示 Agent 窗口，确保不遮挡目标操作区域；在操作完成后恢复窗口。
• 坐标映射：多显示器、不同缩放比例下的坐标精确映射。
• 操作验证：每次操作后截屏对比，验证操作是否生效（如点击是否成功打开了菜单）。

9.3 安全与可中断

• 屏幕边框提醒：当 Computer Use 处于活跃状态时，在屏幕边缘显示醒目的边框（如红色脉冲动画），让用户知道"Agent 正在操作电脑"。
• 一键中断：提供一个悬浮停止按钮（Stop Button），用户可随时打断 Agent 的操作，恢复控制权。
• 窗口白名单/黑名单：限制 Agent 只能操作特定应用窗口（如只能操作浏览器和 Excel，不能碰终端和财务软件）。

十、多 Agent 编排：分工协作

10.1 编排模型

单 Agent 处理复杂任务时容易"迷路"——上下文过长、职责不清。多 Agent 编排通过任务分解和并行执行来解决：

                        +------------------+
                        |   Orchestrator   |
                        |   (主协调 Agent)   |
                        +--------+---------+
                                 |
              +------------------+------------------+
              |                  |                  |
     +--------v--------+ +------v------+ +--------v--------+
     | 子 Agent A       | | 子 Agent B  | | 子 Agent C       |
     | "代码审查"        | | "安全检查"   | | "文档生成"        |
     | 只读代码分析       | | 漏洞检测     | | 格式化输出         |
     +-----------------+ +-------------+ +-----------------+

10.2 子 Agent 的设计原则

• 独立性：每个子 Agent 有独立的 system prompt、工具集和上下文窗口，不共享状态。
• 专业化：子 Agent 应是"专才"而非"通才"——如"代码审查 Agent"不需要文件写入权限。
• 隔离执行：子 Agent 可以在独立的进程/线程中运行，互不干扰。
• 结构化输出：子 Agent 的返回结果应是结构化的（如 JSON），便于编排器解析和合并。

10.3 子 Agent 的来源

• 内置 Agent：平台预置的通用 Agent（代码审查、安全检测、翻译等）
• 用户自定义 Agent：通过 UI 配置的专用 Agent，定义其 system prompt、可用工具和技能
• 从对话中派生：Agent 在执行任务时自主派生临时子 Agent 处理子任务
• IM 集成 Agent：通过飞书、钉钉等 IM 渠道接收指令的 Agent（工作在同一条对话上下文中）

10.4 编排模式

• 顺序编排：A 完成后再启动 B（如先分析需求，再生成代码）
• 并行编排：A、B、C 同时启动处理不同子任务（如同时审查三个模块）
• 条件编排：根据前一步的结果决定下一步（如分析通过 → 生成代码，分析失败 → 请求用户澄清）
• 循环编排：重复执行直到满足条件（如"持续搜索直到找够 10 条结果"）

十一、安全沙箱：Agent 能力的护栏

11.1 分级权限模型

+------------------------------------------------------------------+
| Permission Levels                                                 |
|                                                                    |
|  Level 0 — 安全操作 (自动批准)                                        |
|  只读文件访问、列出目录、获取当前时间、搜索网页                          |
|                                                                    |
|  Level 1 — 低风险操作 (会话内批准一次)                                   |
|  在工作区内写入文件、执行只读 Shell 命令                                 |
|                                                                    |
|  Level 2 — 中风险操作 (每次确认)                                       |
|  在工作区外写入文件、执行修改性 Shell 命令                               |
|                                                                    |
|  Level 3 — 高风险操作 (用户必须显式批准 + 二次确认)                        |
|  删除文件、访问敏感路径（.ssh, .aws）、发送 HTTP 请求到外部服务             |
|                                                                    |
|  Level 4 — 禁止操作 (永不批准)                                        |
|  修改系统配置、访问密钥文件、执行可能破坏系统的命令                          |
+------------------------------------------------------------------+

11.2 路径安全

• 工作区绑定：每次对话需要绑定一个工作区目录。Agent 默认只能在工作区内自由读写，工作区外的操作需要授权。
• 敏感路径阻断：系统目录（/etc、/System、C:\Windows）、密钥目录（~/.ssh、~/.aws）、Git 内部目录（.git）永久禁止访问。
• 记忆路径保护：Agent 的内部记忆文件（~/.memory/）有独立的读写权限控制，防止 Agent 在工具调用中意外修改自己的记忆。

11.3 命令安全

• 命令解析与风险评估：在 Shell 命令执行前，解析命令意图并评估风险等级。检测危险操作模式：rm -rf、sudo、curl | bash、> /dev/sda 等。
• 平台感知：Windows 和 macOS/Linux 有不同的危险命令模式，安全规则需要覆盖所有目标平台。
• 沙箱执行：高风险的命令应在受限环境中执行（如 macOS 的 Seatbelt/App Sandbox，或容器化的子进程）。

11.4 文件操作安全

• 垃圾箱保护：删除操作默认移入系统垃圾箱（而非永久删除），用户可以从垃圾箱恢复。
• 原子写入：文件的写入操作先写入临时文件，成功后替换原文件，避免写入中断导致文件损坏。
• 文件类型验证：根据 MIME 类型和魔数验证文件类型，防止文件伪装（如将 .exe 伪装为 .txt）。

十二、观测性：让 Agent 行为可追溯

12.1 全链路追踪

每次 Agent 执行都应记录为一条完整的 Trace：

+------------------------------------------------------------------+
| Trace: conversation-abc123                                        |
|                                                                    |
|  +-- Span: agent-loop          (总耗时 45.2s)                        |
|       +-- Span: llm-call-1     (耗时 3.2s, tokens: 输入 4500)        |
|       +-- Span: tool-list-dir  (耗时 0.1s, path: /workspace)          |
|       +-- Span: llm-call-2     (耗时 5.1s, tokens: 输入 6200)        |
|       +-- Span: tool-run-cmd   (耗时 2.3s, cmd: npm install)         |
|       +-- Span: compaction     (耗时 0.5s, 压缩 45 条消息 → 摘要)      |
|       +-- Span: llm-call-3     (耗时 8.2s, tokens: 输入 3800)        |
+------------------------------------------------------------------+

12.2 关键指标

• Token 消耗：每次 LLM 调用的输入/输出 token 数、缓存命中率
• 工具调用成功率：各工具的成功/失败比例、平均耗时
• 用户满意度：用户打断频率、任务完成率
• 成本追踪：按会话/项目/用户维度的 LLM API 成本

12.3 隐私保护

观测数据属于敏感的遥测信息，需遵循：

• 默认关闭：开源版本默认不采集任何数据
• 明确授权：数据采集需用户显式 opt-in
• 数据脱敏：不记录用户输入的具体内容，只记录元数据（长度、类型）
• 本地优先：敏感数据优先存储在本地，仅匿名聚合数据可上报云端

十三、总结：Harness 的设计哲学

回顾上述十二项能力，一个优秀的 Agent Harness 应遵循以下设计原则：

1. 分层解耦：每一层能力有明确的接口和边界。记忆系统不关心 LLM 适配器，调度器不关心 UI 渲染。层与层之间通过标准化接口通信。
2. 安全优先：权限控制不是"附加功能"，而是贯穿所有能力的核心约束。每一条文件路径、每一个 Shell 命令、每一次网络请求都需要经过同一套安全策略的评估。
3. 渐进增强：平台应能以最小配置跑起来（一个 API Key + 默认设置），然后逐步解锁高级能力（自定义 Skills、MCP 扩展、多 Agent 编排、自动任务）。
4. 可观测：Agent 的每一步行为都应有据可查——不是黑盒，而是可审计、可调试、可优化的系统。
5. 开放生态：通过 MCP 协议连接外部工具，通过 Skills 系统连接社区贡献，通过 Agent 定义让用户自主编排——平台本身保持克制，把扩展能力交给生态。
6. 用户体验不可妥协：流式输出（每个 token 即时渲染到 UI）、可中断执行（用户随时 Stop）、清晰的权限提示（不是冷冰冰的 Permission denied，而是"Agent 想访问你的桌面文件夹，允许吗？"）——这些看似"前端"的事，其实是从 Harness 层就开始设计的执行约束。

Harness 的本质：不是让模型更聪明，而是让模型更可靠——给它记忆、给它工具、给它规则、给它边界。在这个框架内，模型才能放心地把能力发挥到极致。