OpenHive 生产级多智能体 Harness 实战指南:Queen 驱动的 Colony 架构、快速上手与可靠性机制

原创2026-09-23 12:12:551,862 阅读
文章标签:人工智能AI AgentAgent 框架多智能体大模型Agent 编排工具调用Agent 记忆

OpenHive 生产级多智能体 Harness 实战指南:Queen 驱动的 Colony 架构、快速上手与可靠性机制

本指南以 OpenHive(仓库 gh_mirrors/hive48/hive,即 GitHub 加速计划中的 hive 镜像)的核心文档为主体,系统讲解其「无配置、模型无关」的多智能体运行时:从 Queen/Worker 的 Colony 架构、单一执行原语 AgentLoop,到快速开始、构建第一个 Agent、集成 LLM 与企业系统,再到 park/resume、Sentinel 人工介入与成本控制等生产级能力。读完本文,你将掌握 OpenHive 的部署流程、核心概念与源码级实现原理,能够独立把原型 Agent 升级为可运行真实业务流程的 Colony。

OpenHive 是什么:面向生产工作负载的 Agent Harness

OpenHive 是一个 零配置、模型无关(model-agnostic)的 agent 运行时,专为 agent 集群(colony) 设计。与大多数把「单个 Agent」或「手工连接 Agent 图」作为交付物的框架不同,OpenHive 的部署单元是 colony——一组为执行单一业务流程而协作的专业化 Agent:

  • Queen(女王):持久化、面向客户的主导 Agent,负责会话、计划与早期执行;
  • worker(工蜂):按需生成的克隆 Agent,承担并行与长时工作。

你只需要描述期望的结果(outcome),Queen 会先亲自完成一部分工作,再围绕它"培育"出一个 colony,以可靠且可扩展的方式执行整个流程。其底层机制被概括为 "一个 loop 控制许多 loop"(one loop controlling many loops):Hive 只有唯一的执行原语——agent loop;Queen 本身就是一个 agent loop,每个 worker 都是它的克隆(相同的工具、相同的模型,只是注入各自的任务)。没有需要编译的图(graph),也没有需要手写的编排样板代码,colony 通过共享账本(ledger)与持久化计划完成协调,并将防故障状态、深度可观测性与人工监督内建在这一共享原语之中。

核心概念:Colony、Queen 与 Worker

理解 OpenHive 的关键是理解它的三个核心概念,以及它们如何由同一个原语统一起来。

Colony:部署单元

一个 colony 在磁盘上就是单一目录 colonies/<name>/,包含其所有 Agent 共享的内容:

  • Queen——持久化、面向客户的 Agent,拥有会话、计划与 colony;
  • worker 克隆——Queen 按需生成的临时 Agent,用于并行完成工作单元;
  • tracker——一个 tracker.db(SQLite),作为 colony 的共享账本;
  • 任务计划(task plan)——持久化的、文件备份的待办清单,是 Queen 的主干。

colony 具备可移植性(可导出为 tarball 并通过 POST /api/colonies/import 导入)、可调度性(cron 触发器直接进入 Queen 的会话,让 colony 可以按时钟自我唤醒)与长寿性(Queen 跨会话持久存在,worker 随工作来去)。

Queen:身份而非通用编排器

Queen 不是可互换的"协调器",而是一种 persona(身份)。Hive 内置 13 个默认 Queen,每个都相当于一个部门负责人,拥有各自的专长与语气——覆盖销售/外呼/线索生成、增长/市场调研、财务与融资、法务、人才、运营、产品策略、品牌与设计/内容、技术等领域。每个 persona 都是一个 YAML 配置文件(特质、背景、行为触发器),注入其系统提示词中,使其带来领域判断力而不仅是任务执行能力。

在 Queen 文档 中可以看到,当新请求到来时,由一个 LLM 路由器(CEO 式路由) 读取请求并指派最匹配的 Queen——就像 CEO 把工作分派给对应的部门负责人一样。你描述结果,路由自动完成。

Queen 通过三个阶段使工作成熟(这也是 colony 生长的过程,详见 How a Colony Grows):

  1. 独立阶段(Independent)——作为独立 Agent 直接完成任务;若发现任务具有并行、重复或长时特性,可建议组建 colony;
  2. 孵化阶段(Incubating)——一个 fail-closed 门控确认计划已稳定后才提交(因为 fork 代价高昂:交互式聊天会结束,colony 转为无人值守运行);
  3. Colony 阶段——将 colony fork 到磁盘,切换为 fan-out 模式,委托给 worker 克隆并通过 tracker 验证结果。

其主线是 "先执行,后系统化"(execute first, then systematize):Queen 先亲自证明路径,再将其提炼为可复用的流程。Queen 还携带有作用域、持续演进的记忆——按全局/按 colony/按 Queen 分层的 markdown 记忆文件,通过冷却门控的反思步骤写入持久笔记,并在后续会话中由召回选择器(recall selector)调出相关笔记。

Worker:Queen 的克隆

worker 不是与 Queen 不同的程序,而是她 agent loop 的克隆——更紧的预算、注入单一任务。让 worker 成为 worker 的,恰恰是它刻意缺失的东西(详见 The Worker Agent):

  • 专注——只做一件事,严格限定范围,发现范围外的工作就在报告中提及而不追做;
  • 临时性——没有先前的记忆、没有 persona,每次全新开始,做完即终止;
  • 无升级通道——没有实时听众,中途不能向 Queen 或用户提问,因此永不阻塞等待回答;
  • 不能委派——worker 不能生成自己的 worker,fan-out 专属于 Queen;
  • 快速失败(fail-fast)——工具调用失败时对错误分类(瞬时→重试一次;结构性→修复后重试一次;不可修复→停止),不陷入 workaround 死循环。

worker 的最终动作是 report_to_parent(status, summary, data),状态为 success / partial / failed。该报告作为 [WORKER_REPORT] 回合送达 Queen 的会话。为确保 worker 即使耗尽迭代也能上报,其 loop 包含一次 grace iteration(宽限迭代)——最终的收尾回合仅开放 report_to_parent、task_update、tracker_upsert 三个工具,避免 worker 静默死亡。

一个原语:AgentLoop

在 架构文档 中明确了:AgentLoop(core/framework/agent_loop/agent_loop.py)是 Hive 唯一的执行单元——多轮、流式的 LLM 对话循环。每一轮:流式接收模型响应 → 并行执行工具调用批次 → 将结果回填会话 → 决定终止(judge 门控)或继续迭代。

Queen 与 worker 是同一套代码、不同的 LoopConfig。worker 配置(agents/queen/worker_definition.py)是事实来源:3 次工作迭代 + 1 次宽限迭代、每次工具调用预算与终身工具调用预算,保证 worker 不会无界 fan-out。因为只有一个原语,所有可靠性特性(崩溃安全恢复、上下文压缩、成本追踪、停滞检测)只需构建一次,colony 中每个 Agent 都能继承。

功能特性一览

根据仓库根 README(即本关联文档),OpenHive 的核心特性包括:

  • ✅ Agent 集群(Colonies)——Queen 按需生成 worker 克隆,用于并行与长时工作;
  • ✅ 一个原语,多个 loop——无需连接图;Queen 在运行时培育 colony;
  • ✅ 共享 tracker 账本 + 持久化任务计划——无需数据缓冲区的协调机制;
  • ✅ CEO 式路由的 Queen personas + 有作用域的演进记忆;
  • ✅ 防故障 park/resume、成本执行与带外(out-of-band)人工介入(Sentinel);
  • ✅ 零配置——无需技术配置;
  • ✅ General Compute Use 与带原生扩展的 Browser Use;
  • ✅ 自定义模型支持。

适用场景:谁应该使用 OpenHive

OpenHive 是面向把 AI Agent 从原型推向生产的团队的多智能体 harness 层。它适合你:

  • 想要 AI Agent 执行真实的业务流程而非 demo;
  • 需要一个管理状态、恢复与并行执行的运行时并规模化运行;
  • 需要可自愈、可自适应、随时间改进的 Agent;
  • 要求 human-in-the-loop 控制、可观测性与成本上限;
  • 计划在生产环境运行 Agent——其中可用性、成本与可审计性至关重要。

而如果你只是尝试简单的 agent 链或一次性脚本,OpenHive 可能不是最佳选择。从架构角度看,架构文档 用一个 mermaid 图完整描述了 User → Queen loop → worker clones → tracker.db → Sentinel 的系统拓扑。

何时应该使用 OpenHive?当瓶颈不再是模型,而是围绕它的 harness 时:

  • 需要状态持久化与故障恢复的长时 Agent;
  • 需要成本执行、可观测性与审计追踪的生产工作负载;
  • 通过反思(reflexion)、有作用域的记忆与习得技能随时间改进的 Agent;
  • 通过共享 tracker 账本与持久化计划协调的并行多智能体工作;
  • 一个随模型进步而扩展而非与之对抗的框架。

快速开始:安装、配置与第一个 Agent

环境要求

  • Python 3.11+(用于 Agent 开发);
  • 一个为 Agent 提供算力的 LLM 提供商;
  • ripgrep(可选,Windows 上推荐):搜索工具 terminal_rg / terminal_glob 使用 ripgrep 加速文件搜索;未安装时自动回退到 Python 实现。Windows 上可用 winget install BurntSushi.ripgrep 或 scoop install ripgrep 安装。

Windows 用户:Windows 原生支持通过 quickstart.ps1 与 hive.ps1 完成,请在 PowerShell 5.1+ 中运行。WSL 也是选项之一,但非必需。

安装步骤

注意:Hive 使用 uv workspace 布局,不是通过 pip install 安装的。在仓库根目录执行 pip install -e . 会创建一个占位包,导致 Hive 无法正常工作。请使用下面的 quickstart 脚本配置环境。

# 克隆仓库
git clone https://github.com/aden-hive/hive.git
cd hive

# 运行 quickstart 设置(macOS/Linux)
./quickstart.sh

# Windows(PowerShell)
.\quickstart.ps1

从 quickstart.sh 的实现可以看到,该脚本实际完成:

  • framework——核心 Agent 运行时与图执行器(位于 core/.venv);
  • aden_tools——MCP 工具集,提供 Agent 能力(位于 tools/.venv);
  • credential store——API 密钥的加密存储(~/.hive/credentials);
  • LLM provider——默认模型的交互式配置,包括 Hive LLM 与 OpenRouter;
  • 通过 uv 安装全部 Python 依赖;
  • 最后在你的浏览器中打开 Hive 界面。

脚本内部还会依次检查 Python 版本(优先 python3.11 及更高)、自动安装缺失的 uv、检测 Node.js 20+(用于前端仪表盘构建)、检查 sqlite3(colony 进度追踪)、tesseract(扫描 PDF 的 OCR)、Chrome/Edge(浏览器工具)并安装 Playwright Chromium。之后构建前端到 core/frontend/dist/,再通过 scripts/check_requirements.py 批量验证 framework / aden_tools / litellm 的导入,最后引导你选择 LLM 提供商并写入 ~/.hive/configuration.json。

提示:之后想重新打开仪表盘,在项目目录执行 hive open 即可。仓库根目录的 hive 包装脚本定义了 ./hive open(启动 Web 仪表盘)、./hive run <agent>(运行 Agent)与 ./hive --help 等命令。

构建你的第一个 Agent

在首页输入框中输入你想构建的 Agent 描述。Queen 会提出问题,并与你一起设计出解决方案——这是一个交互式共创过程。

使用模板 Agent

点击 "Try a sample agent" 查看模板列表。你可以直接运行某个模板,也可以选择在现有模板之上构建自己的版本。仓库中 examples/templates/ 提供了 competitive_intel_agent、deep_research_agent、email_reply_agent、job_hunter、meeting_scheduler、sdr_agent、tech_news_reporter、vulnerability_assessment 等可直接运行的示例模板。

运行 Agent

选择 Agent(无论是已有 Agent 还是示例 Agent)即可运行:点击左上角的 Executar(运行) 按钮,或直接与 Queen 对话,让她代为执行。

集成:模型无关与系统无关的设计

OpenHive 的定位是对模型和系统保持中立:

  • LLM 灵活性——Hive Framework 通过兼容 LiteLLM 的 provider 支持 Anthropic、OpenAI、OpenRouter、Hive LLM 以及其他托管或本地模型(详见 docs/configuration.md 中的各 provider 配置示例);
  • 企业系统连接——Hive Framework 被设计为通过 MCP 把各类企业系统(CRM、客服、消息、数据、文件、内部 API)作为工具接入。

这一设计的源码佐证体现在 core/framework/llm/ 下的 provider 抽象层与 tools/src/aden_tools/ 的 MCP 工具集,以及 core/framework/loader/mcp_*.py 的 MCP 连接管理模块中。

为什么选择 OpenHive:结果驱动,先执行后系统化

随着模型能力的提升,Agent 能力上限不断升高——但可靠性与生产价值由 harness 决定。OpenHive 专注于执行真实业务流程,而非通用 Agent。它反转了传统范式:你描述结果,Queen 先亲自工作,再培育 colony 将其规模化——一种自适应的、结果导向的体验,配以易用的工具与集成集。

下面的流程图(取自仓库 README)概括了核心循环:

flowchart LR
    GOAL["描述结果"] --> PILOT["Queen 先行\n(亲自完成一个单元)"]
    PILOT --> SYS["系统化\n(skill + playbook)"]
    SYS --> FAN["扇出\n(生成 worker 克隆)"]
    FAN --> CONV["收敛\n(共享 tracker 账本)"]
    CONV --> CHECK{{"完成?"}}
    CHECK -- "是" --> DONE["交付结果"]
    CHECK -- "否" --> FAN

    GOAL -.- V1["自然语言"]
    PILOT -.- V2["证明路径"]
    SYS -.- V3["可重复流程"]
    FAN -.- V4["规模化并行"]
    CONV -.- V5["按构造恢复"]
    DONE -.- V6["可靠产出"]

    style GOAL fill:#ffbe42,stroke:#cc5d00,stroke-width:2px,color:#333
    style PILOT fill:#ffb100,stroke:#cc5d00,stroke-width:2px,color:#333
    style SYS fill:#ff9800,stroke:#cc5d00,stroke-width:2px,color:#fff
    style FAN fill:#ff9800,stroke:#cc5d00,stroke-width:2px,color:#fff
    style CONV fill:#ff9800,stroke:#cc5d00,stroke-width:2px,color:#fff
    style CHECK fill:#fff59d,stroke:#ed8c00,stroke-width:2px,color:#333
    style DONE fill:#4caf50,stroke:#2e7d32,stroke-width:2px,color:#fff
    style V1 fill:#fff,stroke:#ed8c00,stroke-width:1px,color:#cc5d00
    style V2 fill:#fff,stroke:#ed8c00,stroke-width:1px,color:#cc5d00
    style V3 fill:#fff,stroke:#ed8c00,stroke-width:1px,color:#cc5d00
    style V4 fill:#fff,stroke:#ed8c00,stroke-width:1px,color:#cc5d00
    style V5 fill:#fff,stroke:#ed8c00,stroke-width:1px,color:#cc5d00
    style V6 fill:#fff,stroke:#ed8c00,stroke-width:1px,color:#cc5d00

工作原理的五步循环

  1. 描述结果 → 用简单语言说出你想要什么;一个 CEO 式路由器选择正确的 Queen;
  2. Queen 先行(pilot) → 她亲自完成一个工作单元,证明路径并记录到共享 tracker;
  3. 系统化 → 把验证过的协议提炼为 skill + playbook——一个可重复的流程;
  4. 扇出(Fan out) → run_worker 生成并行执行并回报的 worker 克隆;
  5. 收敛与监控 → worker 将结果写入 tracker;Queen 通过 SQL 验证,并配以实时指标、预算执行与防故障 resume。

关于 run_worker 的源码实现,core/framework/tools/queen_lifecycle_tools.py 中 run_worker(tasks, timeout=600, max_iterations, tool_call_lifetime_budget, resume_worker_ids, guidance) 的定义揭示了关键细节:它是fire-and-forget 的——立即返回,worker 在后台运行,Queen 不被阻塞;timeout 是软截止(默认 600 秒),到期时向每个仍在运行的 worker 注入"立即上报"提示,派生出的硬截止会强制停止拖延者;被强制停止或超时的 worker 可通过 resume_worker_ids(可配 guidance 引导消息)从保存的会话中恢复。并发由调度器管理而非手工控制:colony 接受全部 N 个任务,最多 max_concurrent_workers(默认 4,可通过 HIVE_MAX_CONCURRENT_WORKERS 配置)个同时运行,其余排队,随前面的 worker 结束而启动。

生产级可靠性:从协调基板到人工介入

四大协调基板(取代了图的边与数据缓冲区)

正如 协调文档 与 架构文档 所详述,colony 没有图、没有边、没有共享数据缓冲区,而是通过四个轻量基板保持同步:

  1. tracker(共享账本)——每个 colony 一个 tracker.db(SQLite),是"什么已完成/什么未完成"的唯一事实来源。Queen 建立 schema(tracker_sql)并声明 worker 可写的列(tracker_register_writable),worker 通过 tracker_upsert 逐行记录发现,Queen 用 tracker_query(仅 SELECT)以 SQL 验证进度。每个 colony 的 tracker 由不可变的 binding(colony 名称、目录、数据库路径,见 core/framework/host/colony_binding.py)限定作用域;没有 binding 的工具拒绝执行而非猜测路径——这防止两个 colony 写入错误的账本;
  2. 任务计划——文件备份的持久化任务列表(core/framework/tasks/),对用户可见、可即时编辑、跨会话重载存活;colony 甚至可以携带模板计划,让 Queen 进入时直接采用;
  3. 事件总线——core/framework/host/event_bus.py 是 colony 的 pub/sub 主干:SUBAGENT_REPORT 把 worker 结果送回 Queen,CLIENT_* 事件把实时记录流式推送到 UI;
  4. 提醒中心(reminder hub)——core/framework/agent_loop/reminders.py 的 ReminderHub 在既定节点(会话开始、工具批次后、预算检查点、压缩前后、停止、空闲 tick、流停滞)注入建议性 <system-reminder>,让 Queen 保持对集群的感知与纪律:重新挂起时重新浮现进行中的 worker(避免重复派发)、在预算检查点快照 tracker 表与存活 worker 集群、压缩前提示持久化进度、建议把验证过的 pilot 提炼为 playbook、按名称列出可用工具/技能。

可靠性内建于原语

因为每个参与者都是同一个 loop,harness 特性只需构建一次,所有 Agent 自动继承:

  • Park/resume——loop 将游标持久化到磁盘,需要等待(ASK_USER、CREDENTIAL_FORM、USER_STOPPED、COLD_INTERRUPTED 等)时 park;崩溃、重启或部署后从磁盘精确恢复(core/framework/agent_loop/internals/cursor_persistence.py);
  • 上下文管理——结构保持型压缩(compaction)加工具结果的 pointer/spillover 模式:大结果持久化到磁盘,会话中以紧凑的文件引用替代,Agent 按需通过 load_data(filename, offset, limit) 解引用;
  • 停滞与死循环检测——TTFT/事件间流的 watchdog 加 n-gram 相似度检查,捕获卡住的回合与重复工具调用;
  • Judge 门控终止——三级 judge 管线(core/framework/agent_loop/internals/judge_pipeline.py):Level 0 检查必需输出键与未决工具调用;Level 1 自定义 judge 全面裁决;Level 2 对成功标准做质量门控。RETRY 判定的反馈被注入为 [Judge feedback] 消息,实现会话内的反思式自纠错;
  • Human-in-the-loop 是带外的——升级不是图中的节点:Queen 通过 Sentinel(core/framework/sentinel/)升级到人,这是一个与账户绑定的 Slack/Telegram 通道。loop park(状态持久化到磁盘),人类回复后答案被注入、loop 精确恢复。因为升级内建于原语而非图中,colony 中的任何 Agent 都能随时暂停等待人类判断,且可暂停数分钟、数小时甚至数天而不丢失位置。

成本控制

OpenHive 提供细粒度预算控制,包括支出上限、throttle 与自动降级模型策略。可在团队、Agent 或工作流级别设定预算,并配有实时成本追踪与告警。这与 目标与结果文档 中 Goal 的软/硬约束(constraint_type="hard" / "soft",类别涵盖 time、cost、safety、scope、quality)相互印证。

常见问题(FAQ)

Q:Hive 支持哪些 LLM 提供商?

通过 LiteLLM 集成支持 100+ LLM 提供商,包括 OpenAI(GPT-4、GPT-4o)、Anthropic(Claude 系列)、Google Gemini、DeepSeek、Mistral、Groq、OpenRouter 与 Hive LLM。只需配置相应的 API 密钥环境变量并指定模型名。各 provider 的具体配置示例见 docs/configuration.md。

Q:可以用本地模型(如 Ollama)吗?

可以。通过 LiteLLM 支持本地模型:使用 ollama/model-name 格式(如 ollama/llama3、ollama/mistral),并确保 Ollama 在本地运行。

Q:Hive 与其他 Agent 框架有何不同?

Hive 运行的是 agent 集群(colonies),而非单个 Agent 或手工连接的 Agent 图。多数框架需要你编译由不同节点与边构成的图;Hive 只有单一执行原语——Queen 就是 agent loop,每个 worker 都是它的克隆。编排是运行时的 run_worker fan-out,而非编译好的 DAG;colony 通过共享 tracker 账本协调,而非数据缓冲区。在这一"一个 loop、多个 loop"的核心之上,Hive 是生产级 harness——防故障 park/resume、成本执行、实时可观测性与带外 human-in-the-loop——因为只有一种 Agent,这些能力被所有 Agent 继承。

Q:Hive 是开源的么?

是的,Hive 在 Apache 2.0 许可下完全开源。

Q:Hive 支持 human-in-the-loop 工作流吗?

支持。Queen 通过 Sentinel(绑定账户的 Slack/Telegram 通道)带外升级到人。Agent loop 执行 park(状态持久化到磁盘)、通知人类,并在其回复后精确恢复。因为升级不是图中的节点,colony 中任何 Agent 都能随时暂停等待人类判断,并配有可配置超时与升级策略。

Q:支持哪些编程语言?

Hive Framework 用 Python 构建。JavaScript/TypeScript SDK 在路线图中。

Q:Hive Agent 能与外部工具和 API 交互吗?

可以。colony 中每个 Agent 都有内建工具访问,Hive 通过 MCP 连接外部 API、数据库与服务——包括 100+ 集成工具,以及通过原生扩展提供的 General Compute Use 与 Browser Use。由于 Queen 与其 worker 共享单一工具面,你添加的一项能力会惠及整个 colony。

Q:成本控制如何工作?

提供细粒度预算控制,包括支出上限、throttle 与自动降级模型策略;可在团队、Agent 或工作流级别设定预算,并配以实时成本追踪与告警。

Q:如何贡献?

欢迎贡献:fork 仓库、创建 feature 分支、实现修改并提交 pull request。详细指引见 CONTRIBUTING.md。重要:提交 PR 前请先认领一个 issue(在 issue 下评论声明,维护者会将其分配给你),以避免重复工作。

深入阅读

项目基于 Apache 2.0 许可开源,详见 LICENSE;安全相关问题请参阅 SECURITY.md。

登录后查看全文
hive