euler_agent_bus

面向 openEuler 的低开销 Multi-Agent 通信与共享记忆总线 —— 操作系统开源创新大赛参赛项目。

用结构化协议 + 共享内存非文本状态 + SQLite 向量记忆 + CodeAct 沙箱，替代传统多 Agent 长文本透传，显著降低 Token 与时延。

---

亮点

• 高密度结构化协议：AgentMessage + 能力握手，控制面只传字段，不传“整段聊天史”
• 非文本零拷贝通道：multiprocessing.shared_memory 传递 Embedding，经 StateRef 引用
• L1/L2 共享记忆：任务内证据链 + SQLite Cosine 检索，支持跨任务复用
• CodeAct 沙箱：子进程隔离执行 Python，回传 stdout/stderr/return_value
• 双模式公平对比：同一任务集分别跑 TEXT / STRUCTURED，一键出 Markdown 评测表

---

Benchmark 成果（摘自 docs/benchmark_report.md）

Metric	TEXT	STRUCTURED	Improvement
Message Count	32	32	+0.00%
Total Chars	41802	10418	+75.08%
Total Tokens (est.)	10462	2615	+75.00%
Non-text Transfer Bytes	0	2048	enabled
Latency (seconds)	61.51	48.71	+20.82%
Memory Hit Rate	100%	100%	—
Overall Efficiency Gain	—	—	+42.73%

结论：**Token 约降 75%，延时约降 21%，综合效率提升 42.73%**。完整表格与方法见 docs/benchmark_report.md。

---

快速开始

1. 依赖

python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt    # 或: pip install numpy

2. 配置 API（可选，默认也可 mock 跑通）

cp .env.example .env
# 编辑 .env，填入百炼等 OpenAI 兼容 Key

# 或使用环境变量（赛题常用写法）
export EAB_LLM_BACKEND=llm
export QWEN_API_KEY=sk-xxxx
export LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
export LLM_MODEL=qwen-plus

3. 运行

python main.py                 # 复杂任务双模式演示
python benchmark.py            # 自动评测并打印/保存对比表

---

文档索引（参赛提交）

文档	说明
docs/design_doc.md	系统设计与技术实现报告（含 Mermaid 架构图）
docs/deploy_doc.md	openEuler 24.03-LTS-SP3 部署与测试
docs/benchmark_report.md	实验对比数据（自动生成）

---

架构一览

flowchart LR
    U[任务] --> P[Planner]
    P --> R[Retriever]
    R --> E[Executor/CodeAct]
    E --> S[Summarizer]
    P & R & E & S --- Proto[AgentMessage 协议]
    R --- SHM[SharedMemory 向量池]
    R --- DB[SQLite 共享记忆]

四 Agent 协作：Planner → Retriever → Executor → Summarizer，详细设计见设计文档。

---

目录结构

euler_agent_bus/
├── config.py / llm_client.py
├── protocol.py              # 结构化协议与能力握手
├── shared_state.py          # 非文本 SharedMemory 传递
├── shared_memory.py         # SQLite + 向量检索
├── sandbox.py               # CodeAct 沙箱
├── agents/                  # Planner / Retriever / Executor / Summarizer
├── benchmark.py             # 评测与 Markdown 对比表
├── main.py                  # 入口
├── requirements.txt
├── .env.example
├── README.md
└── docs/
    ├── design_doc.md
    ├── deploy_doc.md
    └── benchmark_report.md

---

模式开关

变量	取值	含义
EAB_COMM_MODE	TEXT / STRUCTURED	通信模式
EAB_LLM_BACKEND	mock / llm	是否调用真实大模型

---

许可证与说明

本项目用于操作系统开源创新大赛演示与评测。API Key 请放入 .env，不要提交到公开仓库。