🚀 零开销多智能体底层协作基础设施 (Zero-Overhead Multi-Agent Infrastructure)

本项目是针对当前大模型多智能体协作系统中存在的“通信冗长、状态转换损耗大、跨任务知识难复用”三大痛点，设计并实现的一套面向系统层的轻量级基础设施。

系统摒弃了低效的纯文本透传，深度结合 Socket、POSIX 共享内存 (IPC) 与轻量级沙箱，特别针对高维科学计算（如空间多组学严谨仿真数据的处理）场景，实现了特征矩阵在未拆解状态下的零拷贝传递，并具备跨任务的经验沉淀能力。

✨ 核心特性机制

1. **结构化通信网关 (Structured RPC)**：摒弃自然语言长文本广播，采用基于 FIPA-ACL 标准的 Pydantic Schema 进行 Agent 间的三次握手与调度，Token 消耗降至 0。
2. **非文本状态零拷贝 (Zero-Copy State Transfer)**：依托 Linux /dev/shm 共享内存引擎，支持高维张量、Embedding 及未拆解的 AnnData 级别巨型矩阵在独立 Agent 进程间瞬间流转，打破 LLM 序列化带来的 OOM 瓶颈。
3. **基于特征哈希的共享记忆引擎 (Semantic Memory)**：无需外挂重型向量数据库，基于纯 Numpy 与字符 Bi-gram 哈希实现降维语义匹配，固化并复用跨任务的逻辑策略与证据链。
4. **CodeAct 安全沙箱 (Code-Driven Sandbox)**：支持接入真实大模型生成 Python 脚本，并在基于 subprocess 的隔离工作区内安全执行与低延迟状态回传。

---

📂 项目结构说明

为了保证项目在系统运行时的模块导入鲁棒性与一键复现，所有核心代码与测试评测脚本均采用扁平化部署在项目根目录下：

multi_agent_system/
├── agent_node.py            # 节点通信基类与状态交换实现
├── benchmark_evaluator.py   # 10 轮自动化连续压测与指标统计脚本
├── codeact_agent.py         # 真实 LLM 驱动的代码执行 Agent
├── codeact_sandbox.py       # CodeAct 轻量代码执行安全沙箱
├── demo_run_stage2.py       # 阶段二验证脚本
├── demo_run_stage3.py       # 阶段三验证脚本
├── demo_run_stage4.py       # A/B Test: 纯文本 vs 结构化零拷贝对比
├── demo_run.py              # 阶段一验证脚本
├── demo_run_real_llm.py     # 多智能体全景与架构调度
├── memory_manager.py        # 共享记忆模块 (特征向量化与检索)
├── protocol.py              # 结构化通信协议与数据结构 (Pydantic)
├── registry.py              # 中心化 Agent 注册表与消息路由
├── shared_memory_manager.py # POSIX 共享内存与 IPC 管理模块
├── requirements.txt         # 环境依赖清单
├── 演示视频.mp4              # 演示视频
├── README.md                # 部署与快速复现指南 (本文档)
├── SYSTEM_DESIGN.md         # 系统架构设计文档
└── EXPERIMENT_REPORT.md     # 性能评测实验报告
🛠️ 部署与安装环境
系统依赖：本系统利用了底层操作系统级特性，要求运行在 通用 Linux 环境 (如 Ubuntu 20.04/22.04，支持 AutoDL 等容器沙箱) 下，且内核支持 POSIX 共享内存 (/dev/shm)。
Python 版本：Python 3.8+
克隆或进入项目根目录
Bash

cd multi_agent_system
安装极简依赖
为追求极致启动速度与轻量化，本系统无重型 ML 框架依赖。
Bash

pip install -r requirements.txt
(依赖清单：pydantic 用于协议校验，numpy 用于矩阵与余弦相似度计算，openai 用于驱动 CodeAct 节点)
📊 实验复现指南 (评审现场执行)
本项目包含完善的自动化评测模块，评审专家可一键运行以下脚本复现核心性能指标。请确保在项目根目录 (包含 tests/ 和 core/ 等) 下执行，或将所有模块置于同一工作目录。
实验一：传统纯文本 vs 系统级零拷贝 (通信开销与时延消融)
该实验强制 Planner 使用“巨型 JSON 纯文本”和“底层共享内存结构化协议”分别向 Executor 传递 $1000 \times 2000$ 的严格仿真特征矩阵。
运行指令：
Bash

python3 tests/demo_run_stage4.py
预期评测结果：
纯文本模式 (Baseline)：将暴露出严重的数据序列化阻塞，通信负载激增至 ~38 MB，引发严重的内核内存告警甚至 Socket 断连。
结构化协议模式 (Proposed)：耗时 < 0.01s 瞬间完成状态传递，证明不拆解数据的零拷贝机制在科学计算协作中的绝对优势。
实验二：10 轮连续任务压测 (记忆复用与整体性能提升)
该实验在 10 轮交替的生物信息学多组学分析任务中，验证共享记忆模块在减少重复计算上的真实收益。
运行指令：
Bash

python3 tests/benchmark_evaluator.py
预期评测结果：
控制台将输出格式化的 ASCII 评测报告。您将观测到：
时延锐减：第 1 轮（冷启动）耗时 ~1.5s，随后的 9 轮凭借记忆策略 100% 命中，平均端到端时延衰减至 ~0.06s（效率提升超 95%）。
极低负载：无论矩阵多大，单次通信消耗的文本负载恒定在 0.01 MB，完美契合低开销结构化通信的赛题要求。
🔒 CodeAct 沙箱扩展配置 (可选)
系统内置了 codeact_sandbox.py 与相应的 Agent 实现。若需测试基于真实大模型生成代码并在隔离区执行，请在节点初始化代码中注入真实的兼容 OpenAI 格式的 API 密钥（如 DeepSeek-V3 或 Qwen）：
Python

from core.codeact_sandbox import LLMClient
client = LLMClient(api_key="sk-xxxxxx", base_url="YOUR_API_BASE", model_name="YOUR_MODEL")