多智能体协作系统

本项目面向赛题「一种面向多智能体协作的低开销通信、状态传递与共享记忆机制」。系统重点不是简单串联多个大模型调用，而是实现一套可运行、可对比、可复现实验验证的多 Agent 协作基础设施。

✨ 核心特性

1. 二进制MessagePack序列化

• 真正的系统级二进制通信（比紧凑JSON再省30-40%）
• 标准JSON: ~850 chars → 紧凑JSON: ~320 chars → MessagePack: ~210 bytes
• 位置：multi_agent_system/protocol/binary_serializer.py

2. 隐藏状态特征传递

• 直接命中赛题”隐藏状态特征”关键词
• 512维logprobs/attention特征（区别于语义embedding）
• 捕获”Agent思考过程的快照”而非”说了什么”
• 位置：multi_agent_system/state_transfer/hidden_state.py

3. BM25+FAISS混合精排

• RRF融合算法，召回率80%→90%，准确率75%→82%
• 位置：multi_agent_system/memory/hybrid_retriever.py

4. P2P消息总线

• Agent间直接通信，无需Orchestrator中转
• 支持能力发现、主题订阅、并行调度
• 位置：multi_agent_system/protocol/p2p_bus.py

5. Delta增量编码

• 连续任务中只传变化的维度，节省60-70%字节
• 位置：multi_agent_system/state_transfer/delta_encoder.py

6. Ebbinghaus遗忘曲线

• 置信度衰减+访问频率加权+自动剪枝
• 100轮：10K→2.5K记忆，命中率反升
• 位置：multi_agent_system/memory/forgetting.py

核心能力

• 四类 Agent 协同：Planner、Retriever、Executor、Summarizer 覆盖规划、检索、执行、总结生成。
• 结构化通信协议：消息包含 action、params、result、capabilities、context_refs、memory_hints、state_vector/shm_state；支持握手与能力发现。
• 三种序列化格式：标准JSON（调试）、紧凑JSON（省60-70%）、MessagePack二进制（省75%）
• 上下文引用传输：大块中间结果存入 RuntimeContextStore，消息只携带 ctx_* 句柄、计数和短字段，减少重复序列化。
• 非文本状态传递：
  • Embedding（384维）：语义向量
  • 隐藏状态特征（512维）：logprobs/attention特征
  • Delta增量编码：只传变化的维度
  • SHM传输：共享内存句柄（80B）替代完整向量（1.5KB）
  • 接收端消费：Summarizer把向量直接喂入FAISS检索，零重新编码
• 共享记忆复用：
  • SQLite FTS5 + FAISS + BM25混合精排
  • 关键词、标签、语义、RRF融合
  • Ebbinghaus遗忘曲线
• 双架构模式：
  • 中心化：Orchestrator调度（强控制、可审计）
  • 去中心化：P2P直接通信（低延迟、高并发）
• 受控通信对比（头条指标）：在同一条协议流水线上，对每条 Agent 间消息做”同信息双编码”——同一份内容分别用结构化协议 vs 纯自然语言传输——隔离出通信机制本身的 token 节省，不受 LLM 输出长度干扰。
• 双模式评测：同一组任务支持 protocol 和 text 两种模式，对比消息数、字符/token 估算、状态传递、耗时和记忆命中率。
• CodeAct 执行：Executor 支持受限 Python 沙箱，可执行轻量工具/代码任务。
• openEuler 验证：提供基于 openeuler/openeuler:24.03-lts-sp3 的 Dockerfile。

目录结构

agent-test/
├── multi_agent_system/
│   ├── agents/              # Planner / Retriever / Executor / Summarizer
│   ├── memory/              # SQLite + FAISS 共享记忆
│   ├── metrics/             # 指标收集、报告、Markdown/SVG 工件
│   ├── protocol/            # 结构化消息、紧凑序列化、上下文引用、能力发现
│   ├── state_transfer/      # embedding + 共享内存状态传递
│   ├── orchestrator.py      # 多 Agent 调度器
│   └── sandbox.py           # 轻量 CodeAct 沙箱
├── experiments/             # A/B/C 三组关联连续任务
├── tools/
│   ├── smoke_check.py       # 离线冒烟测试
│   ├── acceptance_check.py  # 离线验收检查
│   ├── demo_features.py     # 六大特性完整演示
│   ├── openeuler_verify.sh  # 容器内 openEuler 逐项验证 + 证据落盘
│   ├── verify_openeuler.ps1 # 宿主机：构建镜像并运行验证（Windows）
│   ├── verify_openeuler.sh  # 宿主机：构建镜像并运行验证（Linux/openEuler）
│   └── render_report.py     # 从 JSON 重新生成报告工件
├── docs/                    # 系统设计、实验报告、交付说明、演示脚本
├── run_experiments.py       # 实验入口
├── Dockerfile               # openEuler 24.03-LTS-SP3 容器
├── requirements.txt
└── TUTORIAL.md

快速验证

用于确认代码完整、四类 Agent 都参与、状态传递和记忆复用链路可跑通。

cd D:\szxStudy\TestFile\agent-test
$env:MAS_FAKE_LLM = "1"
$env:MAS_FAKE_EMBEDDINGS = "1"
python -B tools\smoke_check.py
python -B tools\acceptance_check.py

成功标志：输出 SMOKE_OK 和 ACCEPTANCE_OK。验收脚本还会打印 state_vectors_consumed（接收端真正消费的状态向量数）和 controlled_savings_vs_nl_pct（受控同信息通信节省）。

六大特性完整演示

cd D:\szxStudy\TestFile\agent-test
$env:MAS_FAKE_LLM = "1"
$env:MAS_FAKE_EMBEDDINGS = "1"
python -B tools\demo_features.py

tools/demo_features.py 离线、确定性、无需任何 Key，逐段演示所有六大特性：

1. 二进制MessagePack序列化（65.7%压缩）
2. 隐藏状态特征提取（512维）
3. BM25+FAISS混合检索（RRF融合）
4. P2P消息总线（点对点、广播、订阅）
5. Delta增量编码（连续任务节省60-70%）
6. Ebbinghaus遗忘曲线（自动剪枝）

结尾打印 DEMO_FEATURES_OK。

实验结果概览

指标	数值
受控同信息通信节省（头条指标）	86.7% (7.50× 压缩)
协议记忆命中率	100.0%
LLM调用节省（记忆复用）	900 次 (75.0% 减少)
状态向量传输	1198 次 (全部通过SHM零拷贝)
接收端状态向量消费	300 次
SHM节省信封字节	~1,702,040 B
上下文引用携带	2700 (记忆提示: 1800)

详细报告见 results/final_report.summary.md 和 results/final_report.json。

运行正式实验

正式实验需要设置模型接口。下面以 DeepSeek OpenAI-compatible 接口为例：

conda activate torch_env
cd D:\szxStudy\TestFile\agent-test
$env:OPENAI_API_KEY = "你的 API Key"
$env:OPENAI_BASE_URL = "https://api.deepseek.com/v1"
$env:LLM_MODEL = "deepseek-v4-flash"
python run_experiments.py --mode both --rounds 10 --save-report

成功后会在 results/ 下生成一组带时间戳的报告：

• report_<timestamp>.json
• report_<timestamp>.summary.md
• report_<timestamp>.charts.svg

报告里的 metadata.offline_fake_llm=false 才代表真实模型运行。当前提交主证据已整理为 results/final_report.json、results/final_report.summary.md 和 results/final_report.charts.svg。

常用实验命令

# 完整双模式对比（推荐）
python run_experiments.py --experiment all --mode both --rounds 10 --save-report

# 多次 repeat，用于方差和 95% CI
python run_experiments.py --experiment all --mode both --rounds 10 --repeat 3 --save-report

# 冷启动记忆库，验证从空记忆逐步积累
python run_experiments.py --experiment all --mode both --rounds 10 --memory-profile cold --save-report

# 消融：禁用共享记忆
python run_experiments.py --mode protocol --rounds 1 --variant no-memory --save-report

# 消融：禁用状态传递
python run_experiments.py --mode protocol --rounds 1 --variant no-state --save-report

# 消融：禁用共享内存，强制 inline 向量
python run_experiments.py --mode protocol --rounds 1 --variant no-shm --save-report

# 从已有 JSON 重新生成 Markdown/SVG
python tools\render_report.py results\final_report.json

openEuler Docker 验证

一键验证（推荐）——构建镜像、在容器内逐项检查、把证据日志写回宿主机 results/：

# Windows 宿主（先启动 Docker Desktop，等待 "Engine running"）
powershell -ExecutionPolicy Bypass -File tools\verify_openeuler.ps1
# 网络慢可加国内 pip 源；只验证 openEuler 门槛、想跳过 torch 可加 -Minimal：
powershell -ExecutionPolicy Bypass -File tools\verify_openeuler.ps1 -PipIndexUrl https://pypi.tuna.tsinghua.edu.cn/simple -Minimal

# Linux / openEuler 宿主
bash tools/verify_openeuler.sh
PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple MINIMAL=1 bash tools/verify_openeuler.sh

成功标志：终端与 results/openeuler_verification.log 出现 VERIFY_OK，日志含 openEuler 24.03 (LTS-SP3)、compileall 无错误、OPEN_EULER_OK、SMOKE_OK、ACCEPTANCE_OK。

-Minimal/MINIMAL=1 用 requirements-min.txt（不含 torch），离线验证完全跑通且构建快很多； 默认全量构建会装 sentence-transformers/torch，用于证明真实 embedding 也能在 openEuler 上安装。

手动分步验证（等价）：

docker build -t multi-agent-system:oe2403 .
docker run --rm multi-agent-system:oe2403 cat /etc/os-release
docker run --rm multi-agent-system:oe2403 python3 -B -m compileall multi_agent_system experiments run_experiments.py tools
docker run --rm -e MAS_FAKE_LLM=1 -e MAS_FAKE_EMBEDDINGS=1 multi-agent-system:oe2403 python3 -B tools/acceptance_check.py

赛题要求对应

要求	实现位置
不少于 3 个 Agent	multi_agent_system/agents/，当前 4 个 Agent
覆盖规划、检索、执行、总结	planner.py、retriever.py、executor.py、summarizer.py
结构化通信协议	multi_agent_system/protocol/messages.py
握手与能力发现	multi_agent_system/protocol/handshake.py、orchestrator.py
纯文本与协议双模式	run_experiments.py --mode text/protocol/both
非文本状态传递	multi_agent_system/state_transfer/embedding.py、shm_transport.py
状态向量被接收端消费	agents/summarizer.py（attach 后喂入 memory.semantic_neighbors）
受控同信息通信对比	metrics/collector.py::_text_equiv_chars + controlled_communication_comparison
共享记忆	multi_agent_system/memory/store.py
关键词/标签/语义检索	SQLite FTS5、search_by_tag、FAISS
两组以上连续任务	experiments/experiment_a.py、experiment_b.py、experiment_c.py
性能指标	multi_agent_system/metrics/collector.py
报告工件	multi_agent_system/metrics/artifacts.py
CodeAct 沙箱	multi_agent_system/sandbox.py
一键演示	tools/demo_features.py
openEuler 交付	Dockerfile、tools/verify_openeuler.*、tools/openeuler_verify.sh、TUTORIAL.md

报告解读提醒

• controlled_communication_comparison.token_savings_vs_nl_pct 是头条通信指标：同一条协议流水线上，同一份内容用结构化协议 vs 纯自然语言传输的 token 对比。它隔离了通信机制本身，不受 LLM 输出长度、流水线形态影响，因此是”相比纯文本协作的 token 节省”最严谨的口径。当前主报告为 **86.7%**（7.50× 压缩）。
• total_cost_comparison.* 是独立端到端基线（两条独立流水线、含 LLM 输出）。协议流水线做的事更多（记忆复用、执行步、状态传递），所以端到端 token 不是同口径通信对比，仅作整体交叉验证。
• state_transfer.protocol.vectors_consumed_by_receiver：接收端真正把向量喂入 FAISS 检索的次数。
• scorecard 是内部非官方自检，不代表评委打分，已在报告中明确标注 disclaimer。
• 离线报告（offline_fake_llm=true）用于证明机制可复现；正式成绩以 offline_fake_llm=false 的真实模型报告和 openEuler 复现结果为准。