Hive 多智能体生产级 Harness 实战指南:从 Colony 架构到快速上手
Hive 多智能体生产级 Harness 实战指南:从 Colony 架构到快速上手
导读
Hive 是一个面向生产环境的开源多智能体(Multi-Agent)运行时层,核心思路是"一个循环控制许多循环"(one loop controls many loops):以 Queen 为持久化、面向客户的主智能体,按需孵化出大量 Worker 克隆并行执行真实业务流程。本文以仓库 README.md 为骨架,结合 架构总览 与源码实现,系统讲解 Hive 的 Colony(蜂群)概念、单一 AgentLoop 执行原语、协调基质(Tracker / Task Plan / Event Bus / Reminder Hub)、可靠性机制与快速上手流程。读完本文,你将掌握 Hive 的核心架构、环境搭建、首个 Agent 的构建方式,以及它区别于"单 Agent"与"手工接线图式框架"的设计哲学。
一、Overview:Hive 是什么
Hive(本仓库即其开源镜像,项目定位为 "Multi-Agent Harness for Production AI")是一个零配置、模型无关(model-agnostic)的多智能体运行时,用于运行"智能体群体"(colonies of agents)。
一个 colony 是一组协同完成同一业务流程的专业化智能体,包含两个角色:
- Queen(女王):持久化、面向客户的主智能体,负责对话、制定计划、亲自完成早期工作,并在需要规模化时孵化 Worker;
- Worker(工蚁):由 Queen 按需生成的克隆体,各自领取一个明确子任务,并行执行后回报结果。
你只需要描述期望的结果(outcome),Queen 会先自己动手验证路径,再围绕该工作"长出"一个 colony 来可靠、规模化地运行它。
底层的机制是 "一个循环控制许多循环":Hive 只有唯一一个执行原语——AgentLoop。Queen 本身就是一个 agent loop,每个 Worker 都是它的克隆(同样的工具、同样的模型、各自独立的任务),无需编译任何图结构,也没有编排样板代码。colony 通过共享账本(shared ledger)与持久化计划进行协调,内置崩溃安全的状态、深度可观测性与人工监督能力。完整的机制说明见 docs/architecture/README.md。
二、核心特性一览
- ✅ Agent 群体(Colonies):Queen 按需孵化 Worker 克隆,用于并行、长时运行的工作;
- ✅ 单一原语、多循环:无需接线图,Queen 在运行时动态"生长"出 colony;
- ✅ 共享 Tracker 账本 + 持久化任务计划:替代数据缓冲实现协调;
- ✅ Queen 人格(persona):CEO 式路由 + 不断演进的限定范围记忆;
- ✅ 崩溃安全的 Park/Resume、成本约束、带外(out-of-band)人工介入(Sentinel);
- ✅ 零配置:无需技术配置即可起步;
- ✅ 通用计算使用(General Compute Use)与浏览器使用(Browser Use),支持原生扩展;
- ✅ 自定义模型支持(Custom Model Support)。
三、适用场景:Hive 适合谁、何时用
Hive 是面向"把 AI 智能体从原型推进到生产"的团队的多智能体 harness 层。适合 Hive 的场景:
- 希望 AI 智能体执行真实业务流程,而非演示;
- 需要规模化地处理状态、恢复与并行执行的运行时;
- 需要通过反思(reflexion)、记忆与习得技能实现随时间自我改进的自适应智能体;
- 需要人工介入控制(human-in-the-loop)、可观测性与成本上限;
- 计划在生产环境中运行智能体,可用性、成本与可审计性至关重要。
而如果只是尝试简单的 Agent 链或一次性脚本,Hive 可能不是最轻的选择。
判断"何时该用 Hive"的标尺是:当瓶颈不再是模型本身、而是模型周围的 harness 时——比如需要状态持久化与崩溃恢复的长运行智能体、需要成本强制与审计轨迹的生产负载、需要反思 + 限定记忆 + 习得技能持续改进的智能体、需要共享 Tracker 账本 + 持久化计划协调的并行多智能体工作。
四、快速开始:环境搭建与首个 Agent
4.1 前置条件(Prerequisites)
- Python 3.11+(用于 Agent 开发);
- 一个可用的 LLM Provider(为智能体提供算力);
- 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 也可用但非必需。
4.2 安装(Installation)
重要:Hive 采用
uvworkspace 布局,不支持pip install。在仓库根目录执行pip install -e .只会创建一个占位包,导致 Hive 无法正常工作。请务必使用 quickstart 脚本完成环境搭建。
# 克隆仓库(以当前开源镜像为例)
git clone <仓库地址>
cd hive
# macOS/Linux 快速启动
./quickstart.sh
# Windows(PowerShell)
.\quickstart.ps1
快速启动脚本(仓库根目录的 quickstart.sh)是一个交互式向导,依次完成:
- framework —— 核心 Agent 运行时与 Colony 运行时(安装在
core/.venv); - aden_tools —— 提供 Agent 能力的 MCP 工具集(安装在
tools/.venv); - credential store —— 加密的 API Key 存储(
~/.hive/credentials); - LLM provider —— 交互式默认模型配置,支持 Hive LLM 与 OpenRouter 等;
- 使用
uv安装全部 Python 依赖; - 最后在浏览器中打开 Hive 界面。
提示:之后想重新打开 Dashboard,在项目目录运行
hive open即可。
4.3 构建你的第一个 Agent
在首页输入框直接输入你想构建的 Agent 描述。Queen 会向你提问、与你一起把方案敲定下来,然后开始执行——这是一个"人机协作澄清 + 自动执行"的过程。
4.4 使用模板 Agent
点击 "Try a sample agent" 浏览模板:可以直接运行模板,也可以在既有模板之上构建你自己的版本。仓库 examples/templates 下提供了多种可直接复用的模板,例如:
competitive_intel_agent(竞品情报)、deep_research_agent(深度研究)、email_inbox_management(邮箱管理)、meeting_scheduler(会议日程)、sdr_agent(SDR 外联)、tech_news_reporter(科技新闻)、twitter_news_agent(Twitter 新闻)、vulnerability_assessment(漏洞评估)等。
每个模板都包含 agent.json(或 agent.py)、config.py、flowchart.json、mcp_servers.json 等完整定义,可直接运行或作为二次开发的起点。
4.5 运行 Agent
选定 Agent(既有的或示例的)后,点击左上角的 Run 按钮即可运行;也可以直接与 Queen 对话,由她代为运行 Agent。
五、架构核心:Why Hive 与执行流程
Hive 的立场是:模型越强,Agent 能力的上限越高——但可靠性与生产价值取决于 harness。与其让你手工接线工作流图、定义每一次 Agent 交互、被动处理故障,Hive 翻转了范式:你描述结果,Queen 先亲自干,再长出 colony 规模化。这是结果驱动(outcome-driven)、自适应,且附带易用工具与集成。
其核心流程("How It Works",共 5 步):
- 描述结果 → 用自然语言说清目标;一个 CEO 式的 LLM 路由器挑选合适的 Queen;
- Queen 试点(pilot) → 她亲自完成一个单元的工作,验证路径并把过程记录进共享 Tracker;
- 系统化(Systematize) → 把验证过的协议提炼为 skill + playbook,形成可复现的流程;
- 扇出(Fan out) →
run_worker孵化 Worker 克隆 并行执行并回报; - 收敛与监控(Converge & monitor) → Worker 把结果写入 Tracker;Queen 用 SQL 校验,实时指标、预算强制、崩溃安全恢复全程生效。
对应关系可以概括为:自然语言描述 → Queen 试点证明路径 → 可复现流程 → 规模化并行 → 构造即恢复 → 可靠产出。
六、深入架构:一个循环控制许多循环
6.1 唯一执行原语:AgentLoop
core/framework/agent_loop/agent_loop.py 中的 AgentLoop 是一个多轮流式 LLM 循环,也是 Hive 唯一的执行单元。每一轮(turn):
- 流式输出模型的响应(文本与工具调用);
- 并行批量执行工具调用;
- 把结果回填到对话;
- 由 judge(评审器)决定是终止(judge 判定通过,或遇到干净的纯文本轮)还是继续迭代。
这个类运行一切:
- Queen 是一个
AgentLoop,配置为长时对话监督——迭代次数近乎无界、上下文窗口大、工具预算宽裕(对应 worker_definition 注释中所述 Queen 配置约为 999_999 次迭代、180k 上下文); - 每个 Worker 是同一循环的克隆,但使用更紧的
LoopConfig。
6.2 Worker 的默认配置:单一事实来源
Worker 的运行时画像定义在 core/framework/agents/queen/worker_definition.py 中,DEFAULT_LOOP_CONFIG 是 Worker 工具调用画像的单一事实来源:
DEFAULT_LOOP_CONFIG: dict[str, int] = {
"max_iterations": 3, # 3 个"工作"迭代
"grace_iterations": 1, # + 1 个宽限迭代(保证回报)
"tool_call_budget": 30, # 每轮工具调用软预算
"tool_call_hard_multiple": 3, # 硬上限倍数:30/60 软检查点,90 硬停
"tool_call_lifetime_budget": 200, # 跨所有轮的累计工具调用上限
"max_context_tokens": 180_000, # 压缩触发前的上下文预算
}
关键设计点:
- Grace 迭代(宽限迭代):保证的收尾轮。即使 Worker 耗尽预算,也至少还有一次只允许调用
report_to_parent/task_update/tracker_upsert的收尾机会——避免 Worker 静默死亡、永远没有回报; - 终身工具调用预算(lifetime budget):跨所有轮次的累计上限,防止被 Queen 抬高
max_iterations的 Worker 无限扇出;达到上限后强制进入宽限收尾; - 上限白名单与边界:在 core/framework/host/colony_runtime.py 中,Queen 只能通过
run_worker覆盖白名单内的字段(max_iterations、grace_iterations、tool_call_budget、tool_call_lifetime_budget、max_context_tokens),且值必须在_LOOP_OVERRIDE_BOUNDS边界内(如grace_iterations上限 3、tool_call_lifetime_budget上限 2000);tool_call_hard_multiple等其余字段由框架锁定,防止配置漂移。
6.3 Worker 的"刻意缺失"
Worker 是 Queen 的克隆,但刻意被收窄:无 persona、无历史记忆、无升级通道、不能孵化或委派子任务。它读取任务、使用工具、调用 report_to_parent。Fail-fast 是契约:被阻塞时,Worker 把部分状态持久化到 Tracker,并回报 failed/partial,而不是在变通方案上打转。
Worker 的系统提示词(同文件中的 WORKER_SYSTEM_PROMPT)把这些规则写成"不可协商"条款:不能孵化 Worker 或委派、不能提问或建议下一步(没有实时听众)、不能添加元评论等。
6.4 扇出工具:run_worker
在 colony 阶段,Queen 通过唯一工具 run_worker(实现于 core/framework/tools/queen_lifecycle_tools.py)进行委派:
run_worker(tasks=[{"task": ..., "data": {...}}, ...], timeout=600)
- Fire-and-forget(即发即忘):
run_worker立即返回;Worker 在后台运行,Queen 保持不被阻塞,可以继续与用户对话或派发更多工作; - 报告以"轮次"形式回家:Worker 完成时发出
SUBAGENT_REPORT事件,Queen 在自己的对话中将其视为[WORKER_REPORT]用户轮——包含状态、一段话摘要与可选的结构化载荷。这就是"多循环"向"单循环"汇报的方式,不需要共享调用栈; - 并发是调度出来的,不是手工维护的:colony 接收全部 N 个任务,最多
max_concurrent_workers(默认 4,可用环境变量HIVE_MAX_CONCURRENT_WORKERS覆盖,见 core/framework/host/colony_runtime.py 中_DEFAULT_MAX_CONCURRENT_WORKERS)同时运行,其余排队,前者结束后者补位。Queen 可以看到running_now/queued/batch_remaining的拆分; - 超时先软后硬:
timeout(默认 600 秒)是软截止,向仍在运行的 Worker 注入"现在回报"的提示;由它派生的硬截止会强制停止掉队者。被强制停止或超时的 Worker 可通过resume_worker_ids(可选guidance)从保存的对话中恢复。
Worker 之间互相不可见、不可通信、不可等待,协调完全通过下面的共享基质完成。
七、Colony:部署单元与目录结构
一个 colony 是 Hive 的部署单元。在磁盘上它是一个独立目录 colonies/<name>/,存放该 colony 共享的一切:Worker 规格(worker.json)、Tracker 账本(data/tracker.db)与任务计划。Colony 具备三个特性:
- 可移植(Portable)—— 通过
POST /api/colonies/import以 tarball 形式导出/导入,一个运行良好的 colony 可以整体交给另一用户或机器; - 可调度(Schedulable)—— cron 触发器直接注入所属 Queen 的会话,colony 可以按时钟自行唤醒;
- 长寿命(Long-lived)—— Queen 跨会话持久存在,Worker 随工作需求来去。
7.1 协调基质:替代"边"与数据缓冲的四件套
colony 没有图、没有边、没有共享数据缓冲,它通过四个轻量基质保持 Queen 与 Worker 舰队同步:
1. Tracker —— 共享 SQLite 黑板
每个 colony 有且仅有一个 tracker.db,由不可变的 ColonyBinding {name, dir, tracker_db}(见 core/framework/host/colony_binding.py)标识。binding 通过工具执行上下文穿线给 Queen、通过 input_data 穿线给 Worker,双方始终解析同一个数据库。没有 binding 的工具会拒绝调用——绝不自行拼路径(这防止了"幽灵 colony"目录的分裂脑问题)。
Tracker 是 colony 的结构化共享状态:
- Queen 用
tracker_sql建表(DDL),并用tracker_register_writable声明哪些列允许 Worker 写入; - Worker 用
tracker_upsert记录发现——每个工作单元一行; - Queen 用
tracker_query(只读 SELECT)校验进度。"做了什么/还剩什么"永远是新鲜的 SQL 查询,而非可能因崩溃丢失的内存态。
2. Task Plan —— Queen 的持久化脊柱
文件备份的任务系统(core/framework/tasks/)为 Queen 的每一次对话提供持久化、结构化的计划(task_create / task_update / task_list)。它对用户可见、可随时编辑、并在会话重载后依然存在——计划比任何一次 Agent 运行都长寿。Colony 可以携带模板任务清单,Queen 进入时直接采纳,因此重复性工作流总能从同一份计划开始。
这里有一个清晰的分工:Tracker 保存结果(结构化行),Task Plan 保存意图(Queen 打算做什么)。Worker 也维护自己的小任务清单,在单次任务内保持组织性。
3. Event Bus —— 事件总线
core/framework/host/event_bus.py 是 colony 的发布/订阅骨干:SUBAGENT_REPORT 把 Worker 结果送回 Queen,CLIENT_* 事件把实时转录流式推送到 UI。它是"多循环"汇入"单循环"并上屏的方式,不需要共享调用栈。
4. Reminder Hub —— 工程化的注意力管理
单一长时循环在扇出几十个 Worker 时容易"忘事"——忘记还有 Worker 在跑、忘记在上下文被修剪前持久化状态、忘记还有哪些工具可用。框架在约定好的时机持续注入建议性 <system-reminder> 上下文(core/framework/agent_loop/reminders.py 中的 ReminderHub / ReminderSource / ReminderPoint):
- 生命周期点:
SESSION_START、POST_TOOL_USE、TOOL_BUDGET_CHECKPOINT、PRE_COMPACT、POST_COMPACT、STOP; - 时间点:
IDLE_TICK(后台计时器即使在 loop 停驻时也能轻推)与STREAM_STALLED(流看门狗触发时的反应式提醒)。
具体来源包括:active_workers_reminder(用户重新参与时重新浮现进行中的 Worker,防止重复派发)、tracker_snapshot_reminder 与 colony_worker_snapshot_reminder(在工具预算检查点展示 Tracker 表与实时 Worker 舰队)、colony_parallel_nudge(试点后建议把协议沉淀为 playbook)、idle_nudge、tool_skill_reminders(按名称列出可用工具/技能面及按需加载完整 schema 的方式,而不是全部烘进静态提示词)。这是工程化的元认知——框架在管理长时、高扇出会话中模型的注意力。
7.2 成熟化弧线:先执行,后系统化
Queen 不会一开始就设计好 colony,而是分三阶段"长"出来(相关逻辑见 core/framework/agents/queen/incubating_evaluator.py):
- Independent(独立)—— Queen 作为独立对话 Agent 亲自干活;当任务表现出并行、重复或长时特征时,她可通过
suggest_colony提议扩容; - Incubating(孵化)——
start_incubating_colony运行一个 fail-closed 的 LLM 门控,判断计划是否足够成熟值得提交。因为 fork 成本高昂(会结束交互式聊天、colony 转为无人值守运行),门控失败或不确定时返回ready=False,Queen 自我纠正而不是贸然推进; - Colony(蜂群)—— Queen 把 headless Worker 规格 fork 到磁盘,进入扇出模式。
标志性动作是 execute-first-then-systematize(先执行后系统化):Queen 亲自端到端完成一个单元的工作——pilot——把结果记入 Tracker;然后把验证过的协议提炼为可复用的 skill + playbook,并调用 run_playbook("收敛脊柱",见 core/framework/host/playbook/runner.py):一个确定性运行器,自身不持有持久状态、以 Tracker 为事实来源、为每行数据派发一个 Worker 克隆(带重试/退避、泳道与死信路径)。因为"还剩什么"永远是新鲜的 Tracker 查询,重跑 playbook 就是构造式的恢复(resume by construction)。
八、Queen 作为身份:人格、路由与记忆
8.1 13 个 YAML 人格
Queen 不是可互换的编排器,而是人格(persona)。仓库内置 13 个 YAML 定义的 Queen(目录 core/framework/agents/queen/queen_defaults/):sales、growth、legal、finance、fundraising、talent、technology、operations、product strategy、brand & design、content、market research、outbound、lead-gen 等,每个都带有注入系统提示词的 traits、background 与 behavior triggers。
以 queen_sales.yaml 为例,其结构包含:name(如 "Larry Ellison")、title(如 "Head of RevOps")、default_tool_categories(默认工具分类:email_senders、file_ops、terminal_basic、browser_basic、browser_interaction、research、context_awareness、charts、media 等)、default_preset_skills、core_traits、hidden_background(past_wound / deep_motive / behavioral_mapping)与 psychological_profile、behavior_triggers(触发条件 + 反应)等字段——让人格在业务判断上带来领域智慧,而不仅是任务执行。
8.2 CEO 式路由
你不需要从菜单里挑选 Queen。新请求到来时,一个 LLM 路由器读取请求并分派最匹配的 Queen——就像 CEO 把工作路由给对口的部门负责人。你描述结果,路由是自动的。
8.3 Queen Memory v2:限定范围的记忆
每位 Queen 携带 Queen Memory v2(见 core/framework/agents/queen/queen_memory_v2.py、reflection_agent.py、recall_selector.py):~/.hive/memories/ 下按 global / per-colony / per-queen 分域存放的 markdown 记忆文件,由冷却门控(cooldown-gated)的反思代理写入、由召回选择器在后续会话中检索——不是向量库,而是她反思进去、再读回来的结构化文件。这让她跨会话积累关于你与你的业务的上下文。与之相对,Worker 是无记忆的:每次运行都是全新开始。
8.4 Queen 拥有什么
- 对话(The conversation)—— colony 唯一的客户端面向;
- 计划(The plan)—— 文件备份、跨重载存活的 任务清单;
- Tracker(The tracker)—— 她建立 colony 的共享 账本、分派工作、用 SQL 校验结果;
- 升级(Escalation)—— 需要人介入时,她通过 Sentinel 带外升级,等对方回复后恢复。
九、可靠性内建于原语:每个 Agent 都继承
因为所有角色都是同一个 loop,harness 特性只写一处,每个 Agent 自动继承:
- Park / Resume(停驻/恢复):loop 把游标持久化到磁盘,需要等待时停驻——包括
ASK_USER、CREDENTIAL_FORM、COLONY_SUGGESTION、AWAITING_QUEEN、USER_STOPPED、COLD_INTERRUPTED(运行时中途死亡)、LLM_ERROR、DOOM_LOOP等场景。磁盘是事实来源,崩溃或重启后精确地从断点恢复(见 core/framework/agent_loop/internals/cursor_persistence.py); - 上下文管理:结构保持型压缩(structure-preserving compaction)+ 工具结果的 pointer/spillover 模式,让长会话不超上下文预算、也不丢信息;
- 停滞与末日循环检测:TTFT/事件间隔流看门狗 + n-gram 相似度检查,捕获卡住的轮次与重复的工具调用;
- Judge 门控的终止:只有当 judge 流水线满足条件时,一轮才"验收"(详见下节);
- 人工介入是带外的(out-of-band):升级不是图中的一个节点——Queen 通过 Sentinel(core/framework/sentinel/)升级给人类,这是账号绑定的 Slack/Telegram 频道。loop 停驻,人类回复被注入,loop 恢复。
9.1 工具结果截断与 Pointer 模式
Agent 经常产生或消费超出上下文预算的工具结果(网页搜索、抓取页面、大型 API 响应)。Hive 使用 pointer 模式:大结果持久化到磁盘,对话中替换为紧凑的文件引用,Agent 按需通过 load_data() 解引用。工作方式:
- 每个工具结果都保存为文件(配置了 spillover 目录时),使用短单调命名(如
web_search_1.txt)最小化 token 开销;JSON 做 pretty-print 以便load_data的按行分页;计数器在恢复时从已有文件复原; - 对话拿到的是指针而非载荷:≤ 30KB 的结果带
[Saved to '…']注解直接透传(Agent 当轮即可操作);更大的结果替换为预览 +load_data(...)指针。30KB 阈值刻意宽松以减少额外往返; load_data(filename, offset, limit)按需取回完整结果,且自身永不被再次 spill(无循环引用);超大load_data结果会被截断并附分页提示;- 指针在压缩后依然存活:结构保持型压缩保留工具调用消息(已是微型指针),把自由文本散文 spill 到编号的
conversation_N.md文件中并替换为引用。Agent 精确知道它调用过每个工具、每个结果在哪; - 系统提示词每轮列出全部 spillover 文件,Agent 永远知道可以重读什么。
9.2 Judge 流水线
终止由三级 judge 决定(core/framework/agent_loop/internals/judge_pipeline.py),按序评估:
| 级别 | 触发 | 机制 | 判定 |
|---|---|---|---|
| Level 0(短路) | 总是 | 必需输出键是否已设置?工具调用是否仍在进行? | 键缺失则 RETRY;工具运行中则继续 |
| Level 1(自定义 judge) | 设置了 JudgeProtocol |
用户提供的 judge 检查助手文本、工具调用、累加器状态、迭代次数——拥有完整权限 | 带反馈的 ACCEPT / RETRY / ESCALATE |
| Level 2(隐式) | 无自定义 judge、键齐备 | 输出键检查 + 可选的、针对 success_criteria 的对话感知质量门 |
ACCEPT 或带反馈的 RETRY |
RETRY 判定的反馈以 [Judge feedback] 用户消息注入,下一轮 Agent 能看到自己的上一次尝试与批评并调整。这种上下文内反思(in-context reflexion)——反馈 → 反思 → 修正——是 Agent 在单次会话内自我纠正的方式,无需任何模型重训练。
十、目标与结果驱动:Goal 是一等公民
Hive 信奉 Outcome-Driven Development(ODD,结果驱动开发),它对比了三种范式:
- **Task-Driven(任务驱动)**问"代码正确吗?"——定义显式步骤,成功 = 步骤无错跑完;但 Agent 可能步骤全对、产出无用;
- **Goal-Driven(目标驱动)**问"我们在解决对的问题吗?"——捕获意图,但目标可能含糊("提升客户满意度"无法告诉你何时算完);
- Outcome-Driven(结果驱动)问"系统产出期望的结果了吗?"——定义可度量的成功标准、硬约束与上下文,按实际结果评估。这正是 Hive 的实现。
在 Hive 中,Goal 不是字符串描述,而是结构化对象(core/framework/schemas/goal.py):
- Success Criteria(成功标准):带权重的成功标准定义"完成"长什么样,是多维质量度量而非二元通过/失败。指标类型可为
output_contains、output_equals、llm_judge或custom;权重表达什么最重要; - Constraints(约束):定义不允许发生什么,是护栏。
hard约束不可协商(违反即升级或失败),soft约束是偏好(可适度变通);类别包括time、cost、safety、scope、quality; - Context(上下文):领域知识、偏好、背景信息,注入到 Agent 的每一次 LLM 调用,使其始终带着全貌推理。
Goal 生命周期为 DRAFT → READY → ACTIVE → COMPLETED / FAILED / SUSPENDED,执行期间每个目标的状态全程可见。好处有三:Agent 可自我纠正(judge 用这些标准决定 accept/retry/escalate)、改进有靶点(框架知道它错过了哪条标准,这正是驱动 colony 改进的精确信号)、人类保持控制(约束划出边界,边界内 Agent 自由探索)。
十一、Colony 如何改进:四个带内机制
Hive 不跨"世代"重生成图(旧文档中的"进化"概念已不存在于当前架构),而是通过四个带内机制改进——都属运行系统的一部分,无需手工编辑工作流或重训模型。两个在会话内、两个跨会话:
- 会话内:Reflexion(反思)—— judge 每次判定 retry 时把反馈注入对话,下一轮 Agent 看到上次尝试与批评并调整;
- 跨会话:限定范围的演化记忆—— Queen 工作期间,冷却门控的反思步骤把持久笔记写入分域 markdown 记忆,召回选择器在后续会话检索;这是"靠记住"改进,不是"靠重写";
- 跨会话:习得的、工具门控的技能—— Queen 验证过的做法可成为 skill 加入基线;skill 是工具门控的,只有所需工具实际存在时才激活,Queen 不会尝试运行她无装备的协议;
- 跨会话:系统化(playbook)—— pilot 验证路径后提炼为 skill + playbook,确定性运行器跨 Worker 克隆收敛剩余批次;playbook 自身无状态、Tracker 为事实来源、每单元派发一个 Worker(带重试/退避/死信路径),重跑即恢复——一次性成功变成可复现、自恢复的流程。
重要区分:这些机制让 colony 更可靠,而非更"通用智能"。它记住什么有效、编码为技能、把验证过的 pilot 变成可复现流程——这是对已遇到过的问题类型的改进。真正的新情况交给 human-in-the-loop,而每次人类介入的决策都会成为 Queen 可记住、可复用的上下文。
十二、集成:模型无关与系统无关
Hive 生来模型无关、系统无关:
- LLM 灵活性:通过 LiteLLM 兼容 provider 支持 Anthropic、OpenAI、OpenRouter、Hive LLM 以及其他托管或本地模型(100+ 提供商)。设置对应 API Key 环境变量并指定模型名即可(provider 配置示例见 docs/configuration.md);本地模型(如 Ollama)使用
ollama/model-name格式(例如ollama/llama3); - 业务系统连通性:通过 MCP 把各类业务系统接入为工具——CRM、客服、消息、数据、文件与内部 API 等。因为 Queen 与 Worker 共享同一工具面,你添加的一个能力整个 colony 都可用(100+ 集成工具,另有 General Compute Use 与 Browser Use 原生扩展)。
十三、常见问题(FAQ)
Q: Hive 支持哪些 LLM provider? A: 通过 LiteLLM 支持 100+ provider,包括 OpenAI(GPT-4、GPT-4o)、Anthropic(Claude 系列)、Google Gemini、DeepSeek、Mistral、Groq、OpenRouter 与 Hive LLM。设置对应 API Key 环境变量并指定模型名即可。
Q: 能用本地模型(如 Ollama)吗?
A: 可以。用 ollama/model-name 格式(如 ollama/llama3、ollama/mistral),确保本地运行 Ollama 即可。
Q: Hive 与其他 Agent 框架有何不同?
A: Hive 运行的是 Agent 群体(colonies),而非单 Agent 或手工接线的图。多数框架要求你编译由节点和边组成的图;Hive 只有一个执行原语——Queen 本身是 agent loop,每个 Worker 是它的 克隆。编排是运行时 run_worker 扇出,而非编译好的 DAG;colony 通过 共享 Tracker 账本 而非数据缓冲协调。在此核心之上,Hive 是生产级 harness——崩溃安全 park/resume、成本强制、实时可观测性、带外人工介入——因为只有一种 Agent,所以每个 Agent 都继承这一切。
Q: Hive 是开源的? A: 是,Apache License 2.0 全开源(见 LICENSE),欢迎社区贡献(指南见 CONTRIBUTING.md)。
Q: 支持 human-in-the-loop 工作流吗? A: 支持。Queen 通过 Sentinel(账号绑定的 Slack/Telegram 频道)带外升级给人类。Agent loop 停驻(状态持久化到磁盘)、通知人类、在对方回复时从断点恢复。因为升级不是图中的一个节点,colony 中任何 Agent 都可在任意时刻暂停等待人工判断,且支持可配置超时与升级策略(详见 架构总览 的可靠性章节)。
Q: Hive 用什么语言编写? A: 框架为 Python;JavaScript/TypeScript SDK 在路线图上。
Q: Hive Agent 能交互外部工具与 API 吗? A: 能。colony 中每个 Agent 都有内置工具访问能力;通过 MCP 连接外部 API、数据库与服务——包括 100+ 集成工具与 General Compute Use / Browser Use 原生扩展。
Q: 成本控制如何工作? A: 提供细粒度预算控制:支出上限、节流、自动模型降级策略;可在团队、Agent 或工作流层级设置预算,并实时跟踪成本与告警。
十四、进一步阅读
- 架构总览 —— 代码级系统设计(ColonyRuntime、协调基质、judge 流水线、pointer 模式);
- 开发者指南 —— 面向开发者的综合指南;
- 快速入门 —— 环境搭建说明;
- 配置指南 —— 全部配置项(含各 provider 的配置示例);
- 核心概念: The Colony · The Queen · The Loop · The Worker Agent · Coordination · Goals & Outcome · How a Colony Improves;
- 示例模板: examples/templates;
- 多入口 Agent 设计: docs/architecture/multi-entry-point-agents.md;
- 版本更新: docs/releases。
结语
Hive 的架构主张可以浓缩为五点(与 架构总览 的总结一致):Colony 是单元(Queen + 若干 Worker 克隆共享一个磁盘工作区、一个 Tracker、一个计划);一个循环、许多循环(单一 AgentLoop 原语既是 Queen 也是每个 Worker,编排是运行时扇出而非编译图);无图协调(共享 SQLite Tracker、持久化任务计划、事件总线、提醒中枢取代边与数据缓冲);先执行后系统化(Independent → Incubating → Colony;先 pilot,再沉淀为 skill + playbook 用 run_playbook 收敛);可靠性内建于原语(磁盘 park/resume、压缩 + pointer 模式、停滞/末日循环检测、judge 门控终止、Sentinel 带外升级——因为只有一种 Agent,所以每个 Agent 都继承)。对于想把真实业务流程交给多智能体系统、又需要生产级可靠性保障的团队,这是一个值得从 quickstart 开始实际跑通的架构范本。