理解OpenHarness核心概念:无状态Agent、事件流与工具循环,5大关键设计深度解析

原创2026-11-13 15:13:182,231 阅读

理解OpenHarness核心概念:无状态Agent、事件流与工具循环,5大关键设计深度解析

OpenHarness 是一个基于 Vercel AI SDK 的开源 AI Agent 框架,用代码即可构建通用的 AI 智能体。对于新手来说,上手 OpenHarness 的关键是理解它的核心概念:无状态 Agent、类型化事件流、多步工具循环、有状态 Session 和可组合 Middleware。本文用通俗的类比和少量示例,带你一次性读懂这 5 大关键设计,帮你快速搭建自己的 Agent 应用。

一图看懂整体架构:谁负责什么?

在深入细节之前,先建立一个整体认知。OpenHarness 把"让 AI 干活"这件事拆成了四层,各层职责清晰、层层组合:

层级 核心类 职责 一句话类比
执行层 Agent 无状态执行器:跑模型、调工具、吐事件 一台"不记事"的发动机
事件层 AgentEvent 类型化事件流:文本增量、工具调用、步骤结束 发动机运转时的实时仪表盘
会话层 Session 有状态管理:历史、压缩、重试、持久化 给发动机装上"记忆 + 保险"
组合层 Runner / Middleware / Conversation 中间件自由拼装:只装你需要的能力 乐高式积木,随取随用

💡 理解了这四层分工,你就理解了 OpenHarness 80% 的设计。下面逐个拆解。

核心概念一:无状态 Agent,为什么"不记事"反而更灵活?

Agent 是 OpenHarness 的核心原语。它把一个语言模型、一组工具和一个多步执行循环封装在一起,但它本身是无状态的——不内部累积任何对话历史。

工作方式非常简洁:

const agent = new Agent({
  name: "dev",
  model: openai("gpt-5.4"),
  tools: { ...fsTools, bash },
  maxSteps: 20,
});

// 传入历史 history + 新输入 input,事件流式产出
for await (const event of agent.run(history, "重构 auth 模块")) {
  if (event.type === "text.delta") console.log(event.text);
}

run() 是一个异步生成器:你传入历史消息,它边执行边"吐"事件,最后通过 done 事件把更新后的完整历史还给你。下一轮对话时,把这份历史再传进去即可实现多轮交互。

为什么这样设计? 好处有三点:

  1. 完全掌控历史——你可以随时检查、修改、裁剪,甚至把同一份历史共享给多个 Agent;
  2. 易于测试和复用——无副作用的执行器,天然适合单元测试(参见 agent.ts 中 Agent 类的定义);
  3. 可预测——输入决定输出,没有隐藏的内存状态。

事件类型的完整定义见 AgentEvent,这是整个框架的"通用语言"。

核心概念二:类型化事件流,Agent 干活的"实时仪表盘"

agent.run() 不是一次性返回结果,而是流式产出一系列类型化事件。每一种事件都精确对应 Agent 运转中的一个动作:

事件 含义 典型用途
text.delta / text.done 模型文本增量 / 整段完成 打字机效果的实时渲染
reasoning.delta / reasoning.done 推理/思考过程增量与完成 展示"思考中"面板
tool.start / tool.done / tool.error 工具调用开始 / 成功 / 失败 展示"正在读取文件…"状态
step.start / step.done 一个 Agent 步骤的开始 / 结束(含 token 用量) 进度指示、成本统计
error 执行出错 错误提示
done 结束,result 为 complete / stopped / max_steps / error 拿到最终消息与总用量

以 CLI 场景为例,事件流让你能精确呈现每个阶段:

for await (const event of agent.run(messages, "列出所有文件")) {
  switch (event.type) {
    case "text.delta":  process.stdout.write(event.text); break;
    case "tool.start":  console.log(`正在调用 ${event.toolName}…`); break;
    case "tool.done":   console.log(`${event.toolName} 完成`); break;
    case "done":        messages = event.messages; break;
  }
}

🎯 这种设计让 UI 层无需关心 Agent 内部实现,只需订阅事件即可渲染任何界面——CLI、React、Vue 通用。

此外,OpenHarness 还提供了 4 个轻量级的流操作符(stream.ts):tap(旁路观察)、filter(过滤事件)、map(转换事件)、takeUntil(提前终止),方便对事件流做管道式加工。

核心概念三:工具循环,让 Agent 真正"动手"干活

"工具循环"(agentic tool loop)是 Agent 与聊天机器人的本质区别:模型不是一次性回答,而是反复执行"思考 → 调工具 → 看结果 → 再思考",直到任务完成或达到上限。

OpenHarness 的工具循环机制包括三个要点:

1. 多步循环由 maxSteps 兜底

每一步(step)模型可能发起多个工具调用。maxSteps(默认 100)限制最大步骤数,防止模型陷入无限循环,超限后 done 事件的 result 会是 max_steps。核心循环逻辑在 Agent.run() 中实现。

2. 内置工具开箱即用

工具基于 Vercel AI SDK 的 tool() 助手 + Zod 校验,内置工厂函数直接可用:

  • 文件系统工具:readFile、writeFile、editFile、listFiles、grep、deleteFile(create-fs-tools.ts)
  • Bash 工具:执行 shell 命令,支持超时和输出截断(create-bash-tool.ts)

3. approve 审批回调守住安全门

默认所有工具调用都被放行。传入 approve 回调后,每次工具执行前都会询问你——返回 true 放行,false 拒绝。被拒绝的调用会以工具错误形式反馈给模型,让它自行调整策略。这让"读操作自动放行、写操作需人工确认"这类权限策略轻松落地。

const agent = new Agent({
  name: "safe-agent",
  model: openai("gpt-5.4"),
  tools: { ...fsTools, bash },
  approve: async ({ toolName }) => {
    const readOnly = ["readFile", "listFiles", "grep"];
    return readOnly.includes(toolName) || askUser(`允许 ${toolName}?`);
  },
});

🔁 工具循环 + 事件流 + 审批回调三者结合,就是 Claude Code 类智能体"自主干活且可控"的秘密。

核心概念四:Session,给无状态 Agent 装上"记忆与保险"

无状态很灵活,但真实的多轮对话需要三样东西:记住历史、上下文爆了能压缩、网络抖动能重试。这正是 Session 存在的意义——它包裹一个 Agent,自动处理这一切:

const session = new Session({ agent, contextWindow: 128_000 });

for await (const event of session.send("列出所有 TypeScript 文件")) {
  if (event.type === "text.delta") process.stdout.write(event.text);
}
// 再发一条——Session 自动记得上文
for await (const event of session.send("把最大的那个重构一下")) {
  if (event.type === "text.delta") process.stdout.write(event.text);
}

Session(session.ts)内置四大能力:

  • 自动压缩(Compaction):对话接近上下文窗口时自动触发,分两阶段——先剪枝旧工具结果(无需调用模型),剪不出来再用模型生成结构化摘要替换整段历史;
  • 自动重试(Retry):429/500/502/503 等瞬时错误按指数退避 + 抖动自动重试,且只在尚未产出任何内容前才重试,避免重复副作用;
  • 持久化(Persistence):实现 SessionStore 接口即可接入任意存储(内存、SQLite、数据库),每轮结束后自动保存;
  • 生命周期钩子(Hooks):onBeforeSend / onAfterResponse / onCompaction / onError,在每个节点插桩定制。

session.send() 除产出全部 AgentEvent 外,还额外发出 turn.start、turn.done、compaction.*、retry 等生命周期事件,让你对"幕后操作"也了如指掌。

核心概念五:可组合 Middleware,只装你需要的积木

Session 把压缩、重试、持久化、钩子捆绑成一个类。如果你只想挑其中几样,或想写自定义逻辑,就用 Runner / Middleware / Conversation 这套函数式 API:

  • Runner:与 agent.run() 同形的异步生成器函数(runner.ts);
  • Middleware:一个"把 Runner 变成 Runner"的函数,apply() 按顺序组合,pipe() 打包成可复用管道;
  • Conversation:组合好 Runner 后的轻量有状态封装,自动从 done 事件更新消息历史(conversation.ts)。
import {
  Conversation, toRunner, apply,
  withTurnTracking, withCompaction, withRetry,
} from "@openharness/core";

// 只组合你需要的中间件,顺序即包装层次
const runner = apply(
  toRunner(agent),
  withTurnTracking(),
  withCompaction({ contextWindow: 200_000, model: agent.model }),
  withRetry({ maxRetries: 5 }),
);

const chat = new Conversation({ runner });
for await (const event of chat.send("修复 auth.ts 的 bug")) {
  if (event.type === "text.delta") process.stdout.write(event.text);
}

内置中间件一览:

中间件 作用
withTurnTracking() 发出 turn.start / turn.done,跨调用维护轮次计数
withCompaction(config) 接近上下文上限时自动压缩历史
withRetry(config?) 瞬时错误指数退避重试
withPersistence(config) 每次 done 后自动保存消息
withHooks(hooks) 挂接 onBeforeSend / onAfterResponse / onError

写自定义中间件也很简单——就是一个包裹 Runner 的函数,在事件流前后插入你的逻辑(详见 middleware/index.ts)。

动手体验:快速上手步骤

准备好后,按下面三步跑起来:

  1. 克隆仓库(可选,直接 npm install 也行):

    git clone https://gitcode.com/gh_mirrors/op/open-harness
    cd open-harness
    
  2. 安装核心包:

    npm install @openharness/core @ai-sdk/openai
    
  3. 参考官方示例:仓库 examples/ 下有三个可运行示例——终端 CLI Agent(含工具审批与子 Agent)、Next.js 流式聊天、Nuxt 流式聊天,分别对应不同集成场景。

小结:5 大设计如何协同

设计 解决的问题
无状态 Agent 历史可控、易测、可复用
类型化事件流 UI 与执行解耦,实时可观测
工具循环 + maxSteps + approve 自主干活且有安全边界
有状态 Session 历史管理、压缩、重试、持久化开箱即用
可组合 Middleware 能力自由拼装,避免"全有或全无"

一句话总结:Agent 负责"跑",事件流负责"看得见",工具循环负责"干得完",Session 负责"记得住",Middleware 负责"随便组"。掌握这 5 个概念,你就能在 OpenHarness 上快速构建从 CLI 助手到 Web 聊天应用的完整 Agent 系统。更多细节可查阅仓库内的 agents.mdx、sessions.mdx 和 middleware.mdx 文档。

登录后查看全文
open-harness