Synapse · 多智能体协作框架

面向”低开销通信 · 非文本状态 · 共享记忆”的多 Agent 协作框架。在 openEuler 24.03-LTS-SP3 上完成 5 方案 × 4 任务 × 3 seed = 60 cell 评测,59/60 PASS(含 1 次 retry,98.3%)。

---

✨ 核心特性

特性	一句话	实测亮点
DSL 协议层通信	用指令式极简语法替代自然语言往返,4 种协议可插拔	T3 任务压缩 tokens -89%
bge-m3 非文本状态	1024d 向量代替自然语言复述语义证据,纯 ONNX Runtime(不依赖 torch)	T1 任务 elapsed -93%
Hybrid RRF 记忆	BM25 关键词 + bge 向量双通道融合,跨 case pickle 持久化	T1 任务 Hybrid vs BM25 加速 49x
Registry 能力握手	AgentDefinition 声明 required_capabilities / provided_capabilities,启动前静态校验依赖	类 K8s readinessProbe
Mailbox 多 Agent 协作	持久化 inbox/outbox,TeammateSpawner 后台线程拉起,poll_task / delegate_task / send_message 异步编排
S3.1 闭环控制	Delegate 门控 + Checker-in-the-loop(修复循环)+ 卡死检测 + 严格 turn budget 隔离	T1 任务 3 seed 全部首次通过
Web 仪表盘 + TraceWriter	FastAPI 4 页面(/ /e2e /ablate /memory /audit),每个 case 同步生成 JSONL trace

---

5 方案梯度

方案	通信	状态	记忆	协作
S0	文本	文本	—	Coordinator
S1	DSL	文本	BM25	Coordinator
S2	DSL	bge	Hybrid RRF	Coordinator
S3.1 ★	DSL	bge	Hybrid	Coordinator + 闭环控制(Delegate 门控 + Checker + 卡死检测)
S4	DSL	bge	Hybrid	共享白板 + 自主认领

★ = 推荐主方案

---

架构总览

┌─────────────────────────────────────────────────────────────────────┐
│  Layer 3 — 评测与可视化                                              │
│  pytest 集成测试 · 6 CSV + 130+ trace JSONL · Web 仪表盘 (FastAPI)   │
├─────────────────────────────────────────────────────────────────────┤
│  Layer 2 — Agent 运行时 + 多 Agent 协同                              │
│  Agent Loop · Mailbox · TeammateSpawner · SharedBoard               │
│  工具:read/write/diff/grep/search/run_tests/exec_python             │
│        delegate/send_message/poll_task/board_*                       │
│        write_memory/search_memory                                  │
├─────────────────────────────────────────────────────────────────────┤
│  Layer 1 — 四大可插拔机制 (A 通信 / B 状态 / C 记忆 / D 握手)         │
│  A Protocol:    Text · Protobuf · DSL · JSON                         │
│  B State:       TextState · BGEStateEncoder (bge-m3, 1024d)          │
│  C Memory:      NoMemory · Keyword (BM25) · Hybrid (RRF)            │
│  D Registry:    AgentDefinition + capability + cost_hint            │
└─────────────────────────────────────────────────────────────────────┘

---

快速开始

1. 装环境 + 装项目

git clone <repo-url> synapse
cd synapse

pip install -r requirements.txt
pip install -e .

2. 跑单元测试验证(~5s,无需 API key)

pytest tests/unit/ -v

3. (可选)下载 bge-m3 模型

只有用到 bge 状态 / Hybrid 记忆时才需要。模型 INT8 ONNX,~600MB,首次自动下载。两种路径任选:

路径 A:HuggingFace Hub

python3 -c "
from huggingface_hub import snapshot_download
snapshot_download('BAAI/bge-m3', allow_patterns=['onnx/*', '*.json', 'tokenizer*'])
"

路径 B:ModelScope(国内推荐)

pip install modelscope
modelscope download --model onnx-community/bge-m3-ONNX

验证编码

python3 -c "
from src.synapse.agents.state import BGEStateEncoder
import numpy as np
e = BGEStateEncoder()
v = e.encode_raw('hello')
print(f'OK: shape={v.shape}, dtype={v.dtype}, norm={np.linalg.norm(v):.3f}')
"

---

跑完整评测(可选)

bash scripts/run_full_eval.sh    # ~7h on openEuler,需 OPENAI_API_KEY

跑完数据自动落 experiments/results/*.csv,可通过 Web 仪表盘查看:

python dashboard/scripts/dashboard_gen.py
python -m uvicorn dashboard.app:app --host 127.0.0.1 --port 8000
# 浏览器打开 http://localhost:8000

---

文档导航

📊 docs/experiments/eval-report-final.md — v7 3-seed 完整评测报告(60 cell + 4 维度 ablate + S3.1 闭环 + 排雷叙事)