HiveWorks

HiveWorks 是一个支持文本消息与潜向量消息的多智能体协作系统。它提供统一的 Agent 协议、可切换的协作拓扑、共享记忆、流式终端与网页 GUI、结构化运行日志，以及面向 六个通用数据集的可恢复评测和多机结果聚合流程。

项目包含两条相互独立但共享底层模型能力的使用路径：

• 协作运行时：使用 hiveworks_run.py 或 hiveworks_gui.py 处理用户任务；
• 基准评测：使用 evaluate_benchmarks.py 比较 HiveWorks 的三种功能模式，并由 aggregate_benchmarks.py 生成 Table 1 风格报告。

核心能力

能力	当前实现
协作拓扑	iterative、sequential、hierarchical
Agent	center、planner、critic、refiner、judger
通信表示	text 文本 JSON、latent 量化潜状态
模型来源	Mock、本地 Hugging Face、DeepSeek 远程文本模型
传输层	进程内 local、TCP、gRPC
共享记忆	内存、SQLite、Chroma，或自动选择
可观测性	终端流式事件、JSON 事件、分 Agent GUI、Sequence Diagram
运行记录	每次运行保存一份完整结构化 JSON，成功与失败均可记录
基准评测	ARC-E、ARC-C、GSM8K、MedQA、MBPP+、HumanEval+
评测指标	Acc.、Token、Speed
分布式评测	分片唯一命名、断点续传、协议校验、去重与冲突检测

安装

需要 uv 与传统 pip 两种安装方式、GUI/CLI/Benchmark 完整命令时，请阅读 简易运行指南。

环境要求

• Python >= 3.14
• uv
• 本地大模型推理建议使用 CUDA GPU

项目统一使用 uv 管理环境，不需要直接调用 python、pip 或 python -m pip。

uv sync

复制环境变量模板：

Copy-Item .env.example .env

按需修改 .env。密钥和访问令牌不要提交到 Git。

pyproject.toml 同时声明了 hiveworks、hiveworks-gui、hiveworks-eval 和 hiveworks-aggregate 命令。直接从源码运行时，推荐使用本文中的 uv run python <入口脚本>。

快速开始

Mock 后端

Mock 后端不下载模型，适合验证拓扑、事件、日志、GUI 和传输流程：

uv run python hiveworks_run.py "解释丁达尔效应" `
  --backend mock `
  --communication text `
  --topology iterative `
  --memory sqlite

本地 Hugging Face 文本协作

uv run python hiveworks_run.py "解释丁达尔效应" `
  --backend hf `
  --text-model-source local `
  --model Qwen/Qwen3.5-4B `
  --device cuda `
  --communication text `
  --topology iterative `
  --memory sqlite

本地 Hugging Face Latent 协作

uv run python hiveworks_run.py "解释丁达尔效应" `
  --backend hf `
  --text-model-source local `
  --model Qwen/Qwen3.5-4B `
  --device cuda `
  --communication latent `
  --topology iterative `
  --memory sqlite

latent 通信仅支持本地模型。它把语义模型状态编码为量化潜向量并作为接收 Agent 的 软前缀，在线缆上不传输自然语言 payload；当前运行时 Agent 仍可能在本地生成文本， 再由后端编码为潜状态。

DeepSeek 远程文本协作

先在 .env 中配置：

DEEPSEEK_API_KEY=你的密钥
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-v4-flash

运行：

uv run python hiveworks_run.py "解释丁达尔效应" `
  --text-model-source remote `
  --communication text `
  --topology iterative `
  --memory sqlite

--text-model-source remote 必须与 --communication text 一起使用。

网页 GUI

启动亮色单页 GUI：

uv run python hiveworks_gui.py `
  --backend mock `
  --communication text `
  --topology iterative `
  --memory sqlite

默认地址为 http://127.0.0.1:8765/，启动后会自动打开浏览器。常用参数：

--host 127.0.0.1
--port 8765
--no-open

GUI 提供：

• 按 Agent 分栏的实时流式输出，避免并发文本混杂；
• 每一步 Agent 的输入 prompt、输出和调用信息；
• 高清 Sequence Diagram；
• 鼠标悬停查看事件详情；
• 点击时序项固定详情窗口，窗口外区域变暗，点击外部解除固定；
• 固定后可滚动详情窗口内部内容；
• 任务输入、Prompt、输入消息和 Agent 输出支持轻量 Markdown 预览；
• 上传、拖放日志，或从本地 logs 目录选择结构化日志，复刻历史运行现场。

GUI 上传的是 hiveworks_run.py --save-log 产生的完整 JSON 日志，不是 benchmark 目录中的 samples.jsonl。

协作运行时

默认架构

iterative 是推荐拓扑。center 读取共享记忆、拆分任务并并行分发给子 Agent； 子 Agent 可以在执行过程中继续调用其他 Agent，所有调用完成后结果返回 center 进行最终综合。

flowchart TD
    U["用户任务"] --> C0["center
读取记忆、拆解和分发"]

    C0 --> P["planner"]
    C0 --> K["critic"]
    C0 --> R["refiner"]
    C0 --> J["judger"]

    P <-. "按需互相调用" .-> K
    K <-. "按需互相调用" .-> R
    R <-. "按需互相调用" .-> J

    P --> W["等待全部调用完成"]
    K --> W
    R --> W
    J --> W
    W --> C1["center
汇总结果并更新记忆"]
    C1 --> A["最终回答"]

默认 Agent：

Agent	职责
center	动态拆解、并行分发、协调调用与最终综合
planner	规划和任务分解
critic	事实、逻辑和风险检查
refiner	综合证据并形成可执行方案
judger	独立复核并给出最终判断

Topology

参数	行为
iterative	center 动态分发；子 Agent 并行执行并可互相调用
sequential	固定链路：planner → critic → refiner → judger
hierarchical	planner、critic、refiner 并行输出，再由 judger 汇总

资源保护参数：

• --max-agent-rounds：限制并行子 Agent 的执行/恢复轮数；
• --max-agent-calls：限制一个 session 中累计发生的子 Agent 调用次数。

前者控制调度可以推进多少轮，后者控制调用边的总数量。达到限制时运行会明确失败， 而不是无限递归。

Communication

参数	含义
text	Agent 间发送 UTF-8 JSON 文本消息
latent	Agent 间发送带元数据、量化信息和完整性校验的二进制潜状态

这里的 text/latent 是运行时通信表示。它与后文 benchmark 的 No Agent/Text Multi-Agent/Latent Multi-Agent 三种评测功能模式不是同一层参数。

比较两种通信表示的线缆开销：

uv run python compare_communication.py "比较两种通信模式"

Transport

参数	行为
local	同一进程内传输
tcp	启动嵌入式 TCP broker，并通过真实 socket 传输
grpc	启动嵌入式 gRPC broker，并传输原始协议字节

示例：

uv run python hiveworks_run.py "检查传输链路" `
  --backend mock `
  --communication latent `
  --transport grpc `
  --grpc-target 127.0.0.1:50051

Shared Memory

参数	存储方式
memory	进程内存，退出后丢失
sqlite	本地 SQLite，默认路径 .hiveworks-memory
chroma	Chroma 持久化向量存储
auto	Chroma 可用时选择 Chroma，否则回退 SQLite

所有 Agent 共享同一个记忆库。每条记忆包含来源、时间、主题、摘要、正文和 metadata。

uv run python hiveworks_run.py "记住并复用这个结论" `
  --backend mock `
  --memory sqlite `
  --memory-path .hiveworks-memory `
  --memory-results 3

事件、日志与现场复刻

终端事件

默认终端会输出 session、Agent、消息传输、共享记忆和调用链事件，并流式显示模型输出。

输出机器可读 JSON Lines：

uv run python hiveworks_run.py "分析任务" `
  --backend mock `
  --json-events

显示传输 payload 预览：

--show-payload-preview

结构化运行日志

为每次运行保存完整 JSON：

uv run python hiveworks_run.py "解释丁达尔效应" `
  --backend mock `
  --save-log `
  --log-path logs

输出文件：

logs/hiveworks-<时间>-<run-id>.json

日志包含：

• run_id、session_id、状态和起止时间；
• 原始任务和任务类别；
• topology、communication、transport、memory 等完整配置；
• 后端、模型和设备信息；
• 全量有序事件，包括 Agent prompt、token、消息与调用链；
• 最终答案、trace、线缆统计；
• 失败时的异常类型与错误信息。

日志采用临时文件加原子替换的方式写入。运行失败时，只要日志目录可写，也会保存错误现场。

.env 加载顺序

当前进程已有环境变量始终优先，CLI 默认值最低。文件加载规则为：

• 设置 HIVEWORKS_ENV_FILE 时，只加载这个显式文件；
• 否则先加载当前工作目录的 .env，再加载项目根目录的 .env；
• 加载时不覆盖已有变量，因此工作目录 .env 比项目根目录 .env 优先。

常用变量：

环境变量	用途
HIVEWORKS_BACKEND	mock 或 hf
HIVEWORKS_MODEL	本地 Hugging Face 模型
HIVEWORKS_DEVICE	cpu、cuda、cuda:0 等
HIVEWORKS_COMMUNICATION	text 或 latent
HIVEWORKS_TEXT_MODEL_SOURCE	local 或 remote
HIVEWORKS_TOPOLOGY	三种 topology
HIVEWORKS_TRANSPORT	local、tcp、grpc
HIVEWORKS_MEMORY	memory、sqlite、chroma、auto
HIVEWORKS_MAX_AGENT_ROUNDS	最大调度轮数
HIVEWORKS_MAX_AGENT_CALLS	最大 Agent 调用数
HIVEWORKS_SAVE_LOG	是否保存结构化 JSON
HIVEWORKS_LOG_PATH	运行日志目录
HF_HOME / HF_TOKEN	Hugging Face 缓存和令牌
DEEPSEEK_API_KEY	DeepSeek API 密钥

完整模板见 .env.example。

六数据集评测

评测入口：

evaluate_benchmarks.py

该入口比较的是同一 HiveWorks 的三种功能启用方式，不是三个独立模块：

展示名称	CLI 值	内部兼容 ID	行为
HiveWorks (No Agent)	no_agent	single	模型直接完成问题，不启用 Agent 协作
HiveWorks (Text Multi-Agent)	text_multi_agent	text_mas	四个 Agent 串行协作，以文字传递中间结果
HiveWorks (Latent Multi-Agent)	latent_multi_agent	latent_mas	前三个 Agent 在 latent 空间推理和传递缓存，最终 Agent 解码答案

--feature-modes 是推荐参数名；旧的 --methods 仍作为兼容别名保留。JSON 中继续保存 稳定内部 ID，并同时提供 method_display_name，确保旧日志、断点和聚合键不失效。

数据集与指标

CLI 数据集名	数据集	任务类型
arc_easy	ARC-Easy	多项选择
arc_challenge	ARC-Challenge	多项选择
gsm8k	GSM8K	数学推理
medqa	MedQA	医学多项选择
mbppplus	MBPP+	代码生成
humanevalplus	HumanEval+	代码生成

指标：

• **Acc.**：每个 repeat 的准确率，再对 repeats 求均值；
• Token：每个样本的系统总输出 token 均值；
• Speed：一次 repeat 跑完整个数据集的端到端推理总秒数均值。

Table 中的 Latent feature gain 表示 Latent Multi-Agent 相对 Text Multi-Agent 的准确率百分点差、token 降幅和加速倍数。HTML 报告仅对 严格优于 Text Multi-Agent 的 Latent 数值和 gain 单元格进行强调。

小规模验证

uv run python evaluate_benchmarks.py `
  --models Qwen/Qwen3.5-4B `
  --datasets arc_easy gsm8k `
  --feature-modes no_agent text_multi_agent latent_multi_agent `
  --repeats 1 `
  --max-samples 10

--max-samples N 表示每个数据集最多取前 N 条，不是所有数据集合计 N 条。

上述命令的进度总数为：

2 个数据集 × 10 样本 × 1 模型 × 3 功能模式 × 1 repeat = 60

常用取值：

• --max-samples 1：仅用于检查完整调用链；当 --repeats 1 时，每个 Acc. 单元格只能是 0.0 或 100.0；
• --max-samples 10：小规模实验；单个 repeat 的 Acc. 分辨率为 10 个百分点；
• --max-samples -1 或省略：使用每个数据集的全部样本。

论文参数与 Qwen3.5 扩展

默认采样参数：

temperature = 0.6
top_p = 0.95
latent_steps = 40
repeats = 3

每个 Agent 的最大输出长度：

数据集	默认最大输出
ARC-E、ARC-C、GSM8K	2,048 token
MedQA、MBPP+、HumanEval+	4,096 token

可用 --max-new-tokens 统一覆盖。

参考论文评测 Qwen3-4B/8B/14B；本项目默认使用 Qwen/Qwen3.5-4B 和 Qwen/Qwen3.5-9B。这是基于 Qwen3.5 混合 Gated DeltaNet/全注意力缓存的扩展实验，不应表述为论文 Qwen3 结果的逐位复现。

代码题安全

MBPP+ 和 HumanEval+ 只有在执行生成代码后才能得到 Acc.：

--allow-unsafe-code-execution

该参数会在本机执行模型生成的 Python。只应在隔离机器或容器中启用。不传该参数时， 模型输出和 Token/Speed 仍会保存，但代码题的 Acc. 为 null。

评测输出

每次新运行创建：

benchmark_results/
└── benchmark-<时间>-<shard>-<完整 run-id>/
    ├── config.json
    ├── events.jsonl
    ├── samples.jsonl
    ├── summary.json
    └── summary.csv

文件	内容
config.json	参数、协议 fingerprint、数据集 fingerprint、软件和 GPU 环境
events.jsonl	模型加载、组合开始/完成、失败和恢复事件
samples.jsonl	每个样本的 prompt、Agent trace、输出、评分、Token 和 Speed
summary.json	repeat 级和聚合级指标，包括每个 repeat 的样本数、已评分数和正确数
summary.csv	便于表格软件读取的聚合指标及评分分母

每条样本完成后立即追加到 JSONL，并刷新 summary，因此中断时已完成的数据不会丢失。

断点续传

使用运行开始时打印的具体目录：

uv run python evaluate_benchmarks.py `
  --resume benchmark_results/benchmark-<时间>-<shard>-<run-id>

恢复时从原 config.json 读取实验参数，并跳过已经完成的唯一键：

协议 + 模型 + 数据集 + 功能模式 + repeat + sample_id

不要通过修改参数把不同实验协议续写进同一目录。需要改变 token 上限、latent steps、 采样参数或代码执行策略时，应创建新运行。

多机器评测与 Table 1 聚合

不同机器只需要运行互不重叠的数据集/模型分片。--shard-name 和完整 UUID 会进入目录名 与记录，复制整个 benchmark-* 子目录时不会因同名而覆盖。

下面的示例得到两个模型、六个数据集、三种 HiveWorks 功能模式、三个 repeats、每个 数据集 10 条样本的完整矩阵。

机器 A：Qwen3.5-4B，全部六个数据集

uv run python evaluate_benchmarks.py `
  --shard-name machine-a `
  --models Qwen/Qwen3.5-4B `
  --datasets arc_easy arc_challenge gsm8k medqa mbppplus humanevalplus `
  --feature-modes no_agent text_multi_agent latent_multi_agent `
  --repeats 3 `
  --max-samples 10 `
  --device cuda `
  --latent-steps 40 `
  --allow-unsafe-code-execution

机器 B：Qwen3.5-9B，ARC-E 与 GSM8K

uv run python evaluate_benchmarks.py `
  --shard-name machine-b `
  --models Qwen/Qwen3.5-9B `
  --datasets arc_easy gsm8k `
  --feature-modes no_agent text_multi_agent latent_multi_agent `
  --repeats 3 `
  --max-samples 10 `
  --device cuda `
  --latent-steps 40 `
  --allow-unsafe-code-execution

机器 C：Qwen3.5-9B，其余四个数据集

uv run python evaluate_benchmarks.py `
  --shard-name machine-c `
  --models Qwen/Qwen3.5-9B `
  --datasets arc_challenge medqa mbppplus humanevalplus `
  --feature-modes no_agent text_multi_agent latent_multi_agent `
  --repeats 3 `
  --max-samples 10 `
  --device cuda `
  --latent-steps 40 `
  --allow-unsafe-code-execution

完成后，将三个完整的 benchmark-* 子目录复制到同一个 benchmark_results 中。 聚合脚本也支持直接传入多个结果根目录，因此物理合并不是必须的。

聚合与完整性检查

uv run python aggregate_benchmarks.py benchmark_results `
  --models Qwen/Qwen3.5-4B Qwen/Qwen3.5-9B `
  --datasets arc_easy arc_challenge gsm8k medqa mbppplus humanevalplus `
  --feature-modes no_agent text_multi_agent latent_multi_agent `
  --repeats 3 `
  --expected-samples 10

预期唯一记录数：

2 模型 × 6 数据集 × 3 功能模式 × 3 repeats × 10 样本 = 1080

严格模式默认开启。聚合器会：

• 递归发现所有合法 benchmark 分片；
• 选择单一实验协议；
• 检查数据集 fingerprint 和样本数；
• 检查每个模型/数据集/功能模式/repeat 是否完整评分；
• 对完全相同的复制副本安全去重；
• 对同一逻辑键但内容不同的记录报告冲突；
• 检测不同 GPU，并对 Speed 的硬件可比性给出警告。

缺失、冲突、未评分或协议不一致时会返回非零退出码，不会静默挑选一个结果。

聚合输出：

benchmark_results/
└── table1-<时间>-<id>/
    ├── table1.html
    ├── table1.md
    ├── table1.csv
    ├── table1.json
    └── merged_samples.jsonl

文件	用途
table1.html	亮色、分模型表头的 Table 1 风格报告
table1.md	Markdown 表格
table1.csv	表格软件和统计工具输入
table1.json	来源、协议、完整性矩阵、冲突、指标和增益
merged_samples.jsonl	按唯一实验键去重后的逐样本结果

常用 CLI 参数

协作运行时

--backend mock|hf
--text-model-source local|remote
--model <Hugging Face model>
--device cpu|cuda|cuda:0
--communication text|latent
--topology iterative|sequential|hierarchical
--transport local|tcp|grpc
--memory auto|memory|sqlite|chroma
--max-agent-rounds N
--max-agent-calls N
--save-log
--log-path <directory>

完整帮助：

uv run python hiveworks_run.py --help
uv run python hiveworks_gui.py --help

Benchmark

--models <one or more model IDs>
--datasets <one or more dataset IDs>
--feature-modes no_agent text_multi_agent latent_multi_agent
--repeats N
--max-samples N
--batch-size N
--latent-steps N
--max-new-tokens N
--device auto|cpu|cuda|cuda:0
--output-dir <directory>
--shard-name <machine label>
--resume <run directory>
--allow-unsafe-code-execution

完整帮助：

uv run python evaluate_benchmarks.py --help
uv run python aggregate_benchmarks.py --help

测试

运行评测与聚合相关测试：

uv run python -m unittest tests.test_evaluation tests.test_evaluation_report -v

运行全部测试：

uv run python -m unittest discover -s tests -v

测试覆盖协议编解码、传输层、共享记忆、远程模型、结构化日志、GUI 事件流、 Qwen3.5 hybrid cache、三种 HiveWorks 评测功能模式、断点续传和多机结果聚合。

故障排查

text payload cannot be empty

DeepSeek thinking 模式可能在生成预算过小时只返回 reasoning_content，尚未产生最终 content。可以提高 --max-new-tokens，或设置：

DEEPSEEK_THINKING=disabled

远程模型不能使用 Latent 通信

远程 API 只返回文本，无法提供 HiveWorks latent 通信所需的本地隐藏状态。使用：

--text-model-source remote --communication text

Latent 通信必须使用本地 Hugging Face 模型。

代码题 Acc. 为 null

这是未启用 --allow-unsafe-code-execution 时的预期行为。请先确认隔离环境，再决定 是否执行模型生成代码。

Benchmark 很慢或输出 token 异常大

先检查 config.json 中的 max_new_tokens_by_dataset。当前论文默认值为 2,048/4,096，而不是 20,480/40,960。Text Multi-Agent 会连续运行四个 Agent， 生成开销天然高于 No Agent。

没有安装 fla 或 causal_conv1d 时，Qwen3.5 可能回退到较慢的 PyTorch 路径； 实际加速库状态会写入 benchmark 的 config.json。

终端中的 Agent 输出交错

终端会标记当前 agent_id，但多 Agent 并发时仍可能快速切换。需要清晰分栏、prompt 和调用链时，使用网页 GUI。

如何恢复中断的 Benchmark

不要重新运行原命令并期望自动找到旧目录。使用：

--resume benchmark_results/benchmark-<时间>-<shard>-<run-id>

项目结构

HiveWorks/
├── hiveworks/
│   ├── agents.py                 # Agent 定义、prompt 与执行
│   ├── backends.py               # Mock 与本地模型适配
│   ├── cli.py                    # 协作运行时 CLI
│   ├── codecs.py                 # 文本与 latent 编解码
│   ├── config.py                 # topology、通信、传输和记忆配置
│   ├── evaluation.py             # 六数据集评测入口实现
│   ├── evaluation_data.py        # 数据集加载与标准化
│   ├── evaluation_methods.py     # 三种 HiveWorks 功能模式
│   ├── evaluation_report.py      # 多机聚合与 Table 1
│   ├── evaluation_scoring.py     # 选择题、数学和代码评分
│   ├── evaluation_store.py       # JSONL、summary 与断点续传
│   ├── events.py                 # 流式事件
│   ├── memory.py                 # 内存、SQLite、Chroma
│   ├── models.py                 # Hugging Face 与 latent cache
│   ├── orchestrator.py           # center 调度和 Agent 调用
│   ├── protocol.py               # 消息协议与潜状态
│   ├── remote.py                 # DeepSeek 远程文本后端
│   ├── runlog.py                 # 原子结构化运行日志
│   ├── transport.py              # local、TCP、gRPC
│   ├── web.py                    # GUI HTTP/NDJSON 服务
│   ├── proto/hiveworks.proto      # gRPC 协议说明
│   └── web_static/               # GUI HTML、CSS、JavaScript
├── tests/
├── aggregate_benchmarks.py
├── compare_communication.py
├── evaluate_benchmarks.py
├── hiveworks_gui.py
├── hiveworks_run.py
├── .env.example
├── pyproject.toml
└── uv.lock

参考

• Latent Collaboration in Multi-Agent Systems
• Gen-Verse/LatentMAS
• Qwen/Qwen3.5-4B
• Qwen/Qwen3.5-9B
• DeepSeek API 文档