AgentHub：面向多智能体协作的低开销通信与共享记忆系统

AgentHub 是面向“多智能体协作中的低开销通信、非文本状态传递与共享记忆复用”赛题实现的可运行原型。系统在 Linux/openEuler 环境中以 HTTP Router 为协作中枢，由 planner、retriever、executor、summarizer 四类 LLM Agent 分工完成规划、检索、工具执行与总结任务，并通过结构化协议、结果引用和 SQLite 共享记忆降低多轮协作中的重复传输与重复计算。

项目同时实现 plaintext（纯文本）与 structured（结构化协议）两种协作模式，并提供两组各 10 步的连续任务、质量合同、配对统计与离线复评能力，用于在完成质量相同的前提下比较通信字节、LLM 调用、token 和任务耗时。

项目目标

本项目聚焦多 Agent 系统的基础设施机制，而不是简单的工作流编排，主要解决以下问题：

• 通信开销高：使用规范化动作、参数和能力描述替代冗长自然语言，并通过 result_ref 引用共享状态中的长结果。
• 状态反复文本化：中间结果先持久化，再以引用传递；共享记忆使用字符 n-gram TF-IDF 语义向量和余弦相似度进行非文本检索。
• 历史经验难复用：将摘要、证据和策略保存为带元数据的统一记忆单元，支持关键词、标签和语义相似度检索。
• 效果难以客观比较：提供双模式同任务实验、确定性角色拓扑、质量匹配配对和 95% 置信区间，避免通过少做任务获得表面上的低消耗。

系统架构

用户 / CLI
    |
    v
HTTP Router :8765
    |-- 消息路由、Inbox、ACK/NACK、Presence、Trace
    |-- 协议解析与双模式映射
    |
    +--> planner-01 ---- 任务理解与分派
    +--> retriever-01 -- 文件检索与记忆查询
    +--> executor-01 --- 白名单命令执行
    +--> summarizer-01 - 结果汇总与记忆写入
              |
              v
    SQLite 共享状态与共享记忆
    （任务结果、result_ref、语义向量、记忆元数据、统计信息）

一次典型任务由 CLI 提交给 Router，planner 根据目标将子任务交给 retriever 或 executor，中间结果写入共享状态后通过 result_ref 回传，最后强制交由 summarizer 汇总并按需写入共享记忆。Router 负责消息持久化、确认、重试、在线状态和完整链路追踪。

已有成果

1. 四角色多 Agent 运行时

• 支持 4 个 Agent 协同运行，覆盖规划、信息检索、工具执行和总结生成。
• 每个角色具有独立工具权限和轮次限制，summarizer 是统一最终出口。
• Router 支持 Inbox、ACK/NACK、Presence、Trace、状态持久化和故障恢复。
• executor 使用命令白名单与超时限制，降低工具执行风险。

2. 双模式结构化通信协议

• plaintext：Agent 间正文使用自然语言，作为传统协作基线。
• structured：任务使用 op/path/goal/detail/result_refs 等规范化字段，结果通过 result_ref 传递。
• 支持握手、能力发现、模式规范化、协议校验和 Router 往返保持。
• 两种模式可按任务选择，无需重启 Worker。

3. 非文本状态传递与语义表示

• 长结果保存在共享状态中，线上消息仅携带 result_ref，接收端按引用解析和组装结果。
• 实现零第三方依赖的字符 n-gram TF-IDF embedding，使用 L2 归一化和余弦相似度完成中文短文本语义检索。
• 提供向量语料库统计、写入时向量记录和检索时现场重算机制，避免语料库变化导致冻结向量口径漂移。

4. 共享记忆存储、检索与复用

• 使用 SQLite 保存统一记忆单元，包含记忆 ID、来源 Agent、创建时间、任务主题、摘要、类型、标签和语义向量等信息。
• 支持关键词、标签、类型和语义相似度混合检索，并记录命中与复用统计。
• 已实现精确匹配短路、语义分档复用和路径级确定性缓存，减少重复 LLM 调用或文件扫描。
• 所有 Agent 进程共享同一记忆库，能够在后续关联任务中复用既有摘要、证据和策略。

5. 可复现实验与质量评测

• 任务组 A：AgentHub 架构与通信链路审计，共 10 个关联步骤。
• 任务组 B：通信协议测试与回归验收，共 10 个关联步骤。
• 每组正式执行 4 个 run，仅将两种模式均通过全部质量合同的 run 纳入配对统计。
• 自动采集消息数、线上正文字节数、LLM 调用数、输入/输出 token、LLM 耗时和任务总耗时。
• 支持原始报告保存、失败步骤定位、质量规则离线复评和 95% Student-t 置信区间计算。

6. 项目交付物

• 完整源码、启动/停止脚本、单元测试与协议 fixtures。
• 系统设计、实验实施记录、openEuler 调研与部署说明。
• 正式量化分析报告、项目说明书、答辩 PPT 和演示视频。

实验结果

正式实验中，A、B 两组均取得 3 个质量匹配配对样本，配对通过率均为 75%。在 Agent 消息数不变的条件下，structured 相对 plaintext 的结果如下。

指标	任务组 A	任务组 B
线上正文字节数	下降 91.89%	下降 91.19%
LLM 调用数	下降 10.17%	下降 13.55%
输入 token	下降 17.40%	下降 27.41%
输出 token	下降 15.82%	下降 8.70%
LLM 耗时	下降 9.37%	下降 16.28%
任务总耗时	下降 6.29%	下降 14.52%
Agent 消息数	52 -> 52	50 -> 50

主要结论：

1. 结构化模式在相同消息拓扑下将线上正文字节稳定降低约 91%，说明 result_ref 能显著减少长结果的重复传输。
2. 两组输入 token 分别降低 17.40% 和 27.41%，LLM 调用及模型耗时也同步下降。
3. B 组总耗时下降 14.52%，其 95% 置信区间完全低于 0；A 组下降 6.29%，但区间上界略跨过 0，只能视为稳定改善趋势，不能宣称在 95% 置信水平下显著。
4. 当前每组有效样本数为 3，结论适用于本项目的两类任务、当前模型与运行环境，不直接外推到所有多 Agent 工作负载。

完整实验口径、失败样本和置信区间见 任务验证结果，实验实现过程见 连续实验说明。

本地验证状态

当前仓库已完成以下无 API 本地验证：

23 项单元测试通过
10 个消息协议 fixture 全部有效

验证命令：

cd AgentHub
python3 -m unittest discover -s tests -v
python3 src/validation/check_fixtures.py

完整端到端运行和正式实验需要可用的 DeepSeek API Key。

快速开始

1. 准备环境

• Python 3.9 及以上
• Linux、openEuler 24.03 LTS SP3 或 macOS
• DeepSeek API Key

cd AgentHub
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

编辑 .env，至少配置：

DEEPSEEK_API_KEY="your-api-key"
DEEPSEEK_BASE_URL="https://api.deepseek.com"
DEEPSEEK_MODEL="deepseek-v4-flash"

2. 启动并提交任务

bash scripts/start.sh

python3 src/cli/team.py task \
  "扫描 src 目录并总结模块功能" \
  --files src \
  --collaboration-mode structured

切换到纯文本基线只需将模式改为 plaintext。任务状态、结果、Trace 和共享记忆等完整命令说明见 AgentHub 使用文档。

3. 运行连续对比实验

AGENTHUB_DEBUG_TIMING=1 AGENTHUB_LLM_TEMPERATURE=0 bash scripts/restart.sh

python3 scripts/continuous_comm_experiment.py \
  --groups A,B \
  --runs 4 \
  --min-qualified-pairs 3 \
  --output reports/continuous-quality.json

实验会调用模型并在每条新任务链开始前清理共享记忆。重要运行数据应提前备份；详细的数据口径和复现实验要求请先阅读正式实验文档。

目录结构

.
├── README.md                              # 项目总览与评审入口
├── AgentHub/                              # 可运行系统源码
│   ├── README.md                          # 安装、配置、操作与排错详解
│   ├── src/
│   │   ├── agents/                        # Agent 主循环、角色 Prompt、上下文组装
│   │   ├── api/                           # Router HTTP Server 与 Client
│   │   ├── cli/                           # 任务、状态、Trace、记忆管理命令
│   │   ├── llm/                           # DeepSeek/OpenAI 兼容接口封装
│   │   ├── protocol/                      # 双模式协议、消息构建与枚举
│   │   ├── router/                        # 路由、Inbox、ACK、Presence 与 Trace
│   │   ├── state/                         # 任务状态持久化与故障恢复
│   │   ├── storage/                       # 共享状态、SQLite 记忆与 embedding
│   │   ├── tools/                         # Agent 工具注册与执行逻辑
│   │   └── validation/                    # 协议 fixture 校验
│   ├── tests/                             # 单元与回归测试
│   ├── fixtures/messages/                 # 10 类协议消息样例
│   ├── scripts/                           # 启停、诊断、记忆与通信实验脚本
│   ├── docs/                              # 设计、实验过程与交接文档
│   ├── runtime/                           # 本地运行数据与日志（不提交）
│   ├── 任务验证结果.md                    # 正式量化分析报告
│   └── requirements.txt                   # Python 依赖
├── openEuler-24.03-LTS-SP3-Agent协作机制调研.md
│                                           # openEuler 环境与部署调研
├── agenthub项目说明书.pdf                 # 项目说明书
├── 操作系统开源创新大赛PPT.pptx           # 答辩演示文稿
├── PPT中的演示视频/演示视频.mp4            # 系统演示视频
└── 操作系统开源创新大赛 作品原创承诺书.docx # 参赛承诺书

文档索引

文档	内容
AgentHub/README.md	完整安装、配置、运行、实验和排错手册
AgentHub/任务验证结果.md	双模式连续任务的量化数据与统计结论
AgentHub/docs/design-llm-2.md	LLM Agent、共享记忆、embedding 与复用机制设计
AgentHub/docs/expirement-5.md	连续实验框架、质量合同和复现过程
openEuler 调研	openEuler 24.03 LTS SP3 部署与安全建议

适用范围与后续工作

当前系统是面向赛题验证的研究原型。后续可继续扩大每组有效配对样本量，细分 Router、共享状态、队列等待和 Agent 调度耗时，并增强 Router 鉴权、执行沙箱和 systemd 服务化能力，以支持更严格的生产环境部署。