ZeroAgent

基于共享内存与语义管道的高性能多智能体协作系统。

当前 README 根据《ZeroAgent 项目书》整理。项目书未给出实际代码仓库目录、启动入口和配置文件名称，因此文中的 <...> 为需要根据最终仓库替换的路径或命令。

项目介绍

ZeroAgent 面向多智能体系统中的底层协作效率问题，重点解决以下三类瓶颈：

1. Agent 之间依赖自然语言或 JSON 传递中间结果，通信内容冗长，序列化和解析开销较高。
2. Embedding、语义向量和隐藏状态等非文本数据需要反复文本化，造成额外时延和语义损耗。
3. 任务执行过程中产生的摘要、证据、策略和经验难以持续沉淀，跨任务复用能力不足。

ZeroAgent 通过结构化二进制协议、POSIX 共享内存零拷贝管道和语义记忆总线，构建低开销、可复用、可扩展的多 Agent 协作基础设施。系统同时集成 CodeAct 沙箱，使 Agent 能够在受限环境中执行由大模型生成的 Python 代码。

核心特性

• 结构化通信协议
  使用 Protocol Buffers 定义 Agent 消息，统一描述动作类型、输入参数、执行结果、能力信息、握手请求和共享内存句柄。

• 共享内存零拷贝传递
  使用 POSIX Shared Memory 和 mmap 传递 Embedding、语义向量及隐藏状态，仅在通信消息中传递轻量句柄，减少文本编解码和数据复制。

• 语义记忆总线
  使用 FAISS 保存向量索引，使用 SQLite 保存记忆元数据，支持关键词、标签和语义相似度检索。

• 多 Agent 运行时
  支持 Planner、Retriever、Executor、Summarizer 等角色的注册、发现、调度和生命周期管理。

• CodeAct 沙箱
  使用 Bubblewrap 和 cgroups 对 Python 代码执行过程进行文件系统、网络、CPU 和内存隔离。

• 性能评测
  采集消息次数、通信开销、状态传递规模、任务耗时、记忆命中率等指标，对比纯文本协作模式与结构化协议模式。

系统架构

flowchart TB
    U[用户任务] --> P[Planner Agent]
    P --> R[Retriever Agent]
    P --> E[Executor Agent]
    R --> M[Semantic Memory Bus]
    E --> C[CodeAct Sandbox]
    R --> S[共享内存状态交换]
    E --> S
    P --> Z[Summarizer Agent]
    R --> Z
    E --> Z
    M --> P
    Z --> O[最终结果]

    B[Protobuf Message Bus] --- P
    B --- R
    B --- E
    B --- Z

系统主要由以下模块组成：

模块	主要职责	技术选型
多 Agent 运行时	Agent 注册、调度与生命周期管理	Python 多进程、UNIX Domain Socket
协议解析与调度	消息编解码、路由、握手与能力发现	Protocol Buffers 3
状态交换	非文本状态零拷贝传递	POSIX Shared Memory、NumPy
共享记忆	记忆持久化与语义检索	FAISS、SQLite
CodeAct 沙箱	隔离执行 Python 代码	Bubblewrap、cgroups
评测模块	指标采集、对比分析和报告生成	MetricCollector

Agent 角色

Agent	职责	典型能力
Planner	接收任务、分解任务并协调其他 Agent	plan_task、decompose、coordinate
Retriever	执行向量检索、日志查询和文档检索	vector_search、search_logs、retrieve_docs
Executor	运行代码、调用工具或访问 API	run_python、exec_code、call_api
Summarizer	汇总中间结果并生成最终输出	summarize、generate_report、format_output

协作流程

1. Planner 接收用户任务并完成任务分解。
2. Planner 通过 Protobuf 消息总线向 Retriever 或 Executor 分发结构化动作请求。
3. Retriever 生成的 Embedding 或中间语义状态写入共享内存。
4. 接收方通过 ShmTensorHandle 映射读取数据，不再传输完整文本化向量。
5. Executor 可将待执行代码提交至 CodeAct 沙箱。
6. 任务摘要、证据链和语义向量写入 Semantic Memory Bus。
7. Summarizer 汇总各 Agent 的输出并生成最终结果。
8. 后续相似任务优先检索历史记忆，减少重复检索和执行。

技术栈

• 操作系统：openEuler 24.03 LTS SP3 或通用 Linux
• 编程语言：Python 3.10+
• 通信协议：Protocol Buffers 3
• 进程通信：UNIX Domain Socket
• 共享内存：POSIX Shared Memory
• 数值计算：NumPy、PyTorch
• 向量检索：FAISS
• 元数据存储：SQLite
• 沙箱隔离：Bubblewrap、cgroups
• 可选增强：eBPF、WASM

运行说明

1. 环境要求

建议在 Linux 环境运行。Windows 和 macOS 不直接提供与 Linux 完全一致的 POSIX Shared Memory、Bubblewrap 和 cgroups 行为，不建议作为正式评测环境。

最低建议环境：

• Python 3.10 或更高版本
• Protocol Buffers 编译器 protoc
• Bubblewrap bwrap
• 支持 POSIX Shared Memory 的 Linux 内核
• 可用的 /dev/shm
• 至少 4 GB 内存

检查环境：

python3 --version
protoc --version
bwrap --version
df -h /dev/shm

2. 获取项目

git clone <REPOSITORY_URL>
cd <REPOSITORY_DIRECTORY>

3. 创建 Python 虚拟环境

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

4. 安装依赖

仓库包含 requirements.txt 时：

pip install -r requirements.txt

项目书涉及的主要 Python 依赖包括：

pip install protobuf numpy torch faiss-cpu

SQLite 通常随 Python 标准库提供，无需单独安装。

在 openEuler 上安装系统依赖时，可根据软件源中的实际包名执行：

sudo dnf install python3 python3-pip protobuf-compiler bubblewrap

在 Debian 或 Ubuntu 系统上可使用：

sudo apt update
sudo apt install -y python3 python3-venv python3-pip protobuf-compiler bubblewrap

5. 编译 Protobuf 协议

将下面的协议文件路径替换为仓库中的实际路径：

protoc \
  --python_out=<GENERATED_CODE_DIRECTORY> \
  <PROTO_DIRECTORY>/agent_protocol.proto

示例：

protoc --python_out=. proto/agent_protocol.proto

编译后应生成类似以下 Python 文件：

agent_protocol_pb2.py

如果项目使用 gRPC，还需要安装 grpcio-tools 并生成对应代码。当前项目书仅明确使用 Protocol Buffers 和 UNIX Domain Socket，不要求 gRPC。

6. 初始化存储

创建运行目录：

mkdir -p data logs run

Semantic Memory Bus 至少需要以下持久化文件：

data/
├── memory_faiss.index
└── memory_meta.db

如果仓库提供初始化脚本，执行：

python <MEMORY_INIT_SCRIPT>

如果尚未提供初始化脚本，需要在程序启动时完成以下操作：

• 创建 SQLite 数据表。
• 初始化空 FAISS 索引。
• 建立 memory_id 与 FAISS 向量序号之间的映射。
• 检查向量维度是否与 Embedding 模型一致。

7. 检查共享内存

确认 /dev/shm 可用：

ls -ld /dev/shm
df -h /dev/shm

清理异常退出后遗留的共享内存对象时，应先确认没有 ZeroAgent 进程正在运行，再删除对应对象。不要直接清空整个 /dev/shm。

8. 启动系统

项目书未明确最终入口文件。建议按以下顺序启动，具体命令应替换为仓库中的实际模块路径。

方式一：统一入口启动

python <MAIN_ENTRY> --config <CONFIG_FILE>

示例形式：

python main.py --config config/default.yaml

方式二：分别启动运行时和 Agent

终端 1，启动消息总线或调度器：

python <RUNTIME_ENTRY>

终端 2，启动 Planner：

python <PLANNER_ENTRY>

终端 3，启动 Retriever：

python <RETRIEVER_ENTRY>

终端 4，启动 Executor：

python <EXECUTOR_ENTRY>

终端 5，启动 Summarizer：

python <SUMMARIZER_ENTRY>

方式三：运行演示任务

python <DEMO_ENTRY> \
  --task "分析指定日志中的异常原因并生成排障建议"

正常运行时应能够观察到：

1. 各 Agent 完成握手与能力注册。
2. Planner 生成结构化任务计划。
3. Retriever 或 Executor 收到 ActionRequest。
4. 非文本状态通过共享内存句柄传递。
5. 执行结果以 ActionResponse 返回。
6. 任务记忆写入 FAISS 和 SQLite。
7. Summarizer 输出最终结果。

CodeAct 沙箱配置

CodeAct 用于执行由 Agent 生成的 Python 代码。正式运行时不应直接使用宿主机 Python 无限制执行生成代码。

检查 Bubblewrap：

bwrap --version

建议限制项：

• 系统目录只读挂载。
• 工作目录使用临时文件系统。
• 默认禁用网络访问。
• 限制 CPU 时间。
• 限制内存使用量。
• 限制子进程数量。
• 设置执行超时。
• 捕获并结构化返回 stdout、stderr 和退出码。

示例命令框架：

bwrap \
  --ro-bind /usr /usr \
  --ro-bind /lib /lib \
  --ro-bind /lib64 /lib64 \
  --proc /proc \
  --dev /dev \
  --tmpfs /tmp \
  --unshare-net \
  python3 <SANDBOX_SCRIPT>

不同 Linux 发行版的动态库目录可能不同，实际挂载路径必须根据运行环境调整。

测试与评测

单元测试

仓库使用 pytest 时：

pip install pytest
pytest -v

建议至少覆盖：

• Protobuf 消息编解码。
• Agent 握手与能力发现。
• ActionRequest 和 ActionResponse 路由。
• Shared Memory 写入、读取和释放。
• FAISS 索引写入与 Top-K 检索。
• SQLite 元数据一致性。
• CodeAct 超时和资源限制。
• Agent 异常退出后的恢复机制。

对比实验

系统应支持两种模式：

1. 纯文本协作模式。
2. 结构化协议协作模式。

在相同任务、相同模型和相同运行环境下执行多轮测试，记录：

• 消息数量。
• 文本字符数或 Token 消耗。
• 消息传输延迟。
• 非文本状态传递次数和数据规模。
• 单任务端到端耗时。
• 共享记忆命中率。
• 任务成功率。
• CPU 和内存使用情况。

运行评测脚本：

python <BENCHMARK_ENTRY> \
  --mode all \
  --rounds 10 \
  --output reports/benchmark.json

生成报告：

python <REPORT_ENTRY> \
  --input reports/benchmark.json \
  --output reports/benchmark_report.html

以上入口名称需根据实际仓库调整。

推荐目录结构

下列结构用于指导代码整理，不代表当前仓库已经采用该结构：

ZeroAgent/
├── README.md
├── requirements.txt
├── main.py
├── config/
│   └── default.yaml
├── proto/
│   └── agent_protocol.proto
├── zeroagent/
│   ├── runtime/
│   ├── protocol/
│   ├── agents/
│   │   ├── planner.py
│   │   ├── retriever.py
│   │   ├── executor.py
│   │   └── summarizer.py
│   ├── shared_memory/
│   ├── memory/
│   ├── sandbox/
│   └── metrics/
├── scripts/
│   ├── init_memory.py
│   └── run_demo.py
├── tests/
├── data/
├── logs/
└── reports/

常见问题

1. 无法创建共享内存

检查：

df -h /dev/shm
ls -ld /dev/shm

常见原因：

• /dev/shm 空间不足。
• 共享内存对象未释放。
• 容器未正确挂载 /dev/shm。
• 当前用户无访问权限。

2. FAISS 安装失败

优先尝试：

pip install faiss-cpu

如果 openEuler 环境缺少可用预编译包，可使用 Conda、源码编译或将 HNSWlib 作为备选向量索引实现。

3. Protobuf 版本不一致

检查：

protoc --version
python -c "import google.protobuf; print(google.protobuf.__version__)"

应避免 protoc 编译器与 Python protobuf 运行库之间存在明显版本不兼容。

4. Bubblewrap 无法启动

可能原因：

• 内核未启用用户命名空间。
• 当前运行环境禁止创建 namespace。
• 容器缺少必要权限。
• 系统目录挂载路径不正确。

可以先使用最小沙箱命令验证环境，再逐步增加隔离参数。Docker 可作为兼容性备选方案，但其启动开销通常高于 Bubblewrap。

5. Agent 无法互相发现

检查：

• UNIX Domain Socket 文件是否存在。
• Socket 路径长度是否超出系统限制。
• Agent 是否完成 HandshakeReq 和 HandshakeResp。
• agent_role 和 capabilities 是否正确注册。
• 是否存在重复的 Agent ID。
• 调度器是否已启动。

6. FAISS 检索结果与 SQLite 元数据不一致

应保证：

• FAISS 序号与 memory_id 映射持久化。
• 删除记忆时同步更新索引和数据库。
• 写入失败时执行事务回滚或补偿。
• Embedding 模型和向量维度保持一致。

安全说明

• 不要在无隔离环境中执行大模型生成的代码。
• 不要默认向沙箱开放网络。
• 不要将宿主机敏感目录以可写方式挂载到沙箱。
• 不要信任 Agent 生成的文件路径、Shell 参数或 API 地址。
• 对所有任务设置超时、内存限制和最大输出长度。
• 共享内存句柄应校验名称、偏移量、数据长度、形状和数据类型。
• Agent 消息应校验发送方身份、接收方身份和消息类型。

开源组件

ZeroAgent 计划使用以下开源组件：

• Protocol Buffers
• NumPy
• PyTorch
• FAISS
• SQLite
• Bubblewrap
• Linux cgroups

正式发布前，应在源码和文档中补充各组件的版本、许可证和引用范围，并核对所有第三方代码是否满足参赛要求。

项目状态

当前项目书定义了系统架构、协议格式、共享内存传递机制、语义记忆模块、CodeAct 沙箱和评测方案。实际可运行性仍取决于最终源码、依赖版本、启动入口和 openEuler 环境验证结果。

License

待根据参赛要求和所使用开源组件的许可证确定。

致谢

感谢 openEuler 社区以及 Protocol Buffers、NumPy、PyTorch、FAISS、SQLite、Bubblewrap 等开源项目提供的基础能力。