SwarmLink

面向多智能体协作的低开销通信、非文本状态传递与共享记忆原型。

SwarmLink 基于 OpenAI Swarm 的轻量 Agent/handoff 思想进行扩展，保留上游 MIT 许可证和源码，并新增一套可离线复现的系统层协作机制。演示与基准程序只使用 Python 标准库，不需要模型 API、向量数据库或网络服务。

核心能力

4 类 Agent：规划、检索、执行、总结，超过赛题不少于 3 类的要求。
结构化协议：swarmlink/1.0 紧凑 JSON 消息，包含动作、参数、结果、能力描述、关联 ID，并支持握手、能力发现和动作别名映射。
双协作模式：相同任务可选择纯文本模式或结构化协议模式。
非文本状态传递：检索 Agent 生成 64 维特征哈希向量，按 little-endian float32 写入 OS 共享内存；接收方只拿描述符，校验 SHA-256 后直接映射读取。
共享记忆：SQLite 统一记忆单元包含 ID、来源 Agent、UTC 创建时间、任务主题、摘要、标签、证据、策略和向量；支持关键词、标签和语义相似度联合检索。
可复现实验：内置 5 组、每组 2 个关联任务，共 10 轮；自动产出 JSON、CSV、 Markdown 报告和 HTML 仪表板。
openEuler 交付：提供 openEuler 24.03-LTS-SP4 容器和 amd64/arm64 远端 CI。

架构

flowchart LR
    R["运行时 / 协议调度"] --> P["规划 Agent"]
    P --> Q["检索 Agent"]
    Q -->|"共享内存 float32 向量"| E["执行 Agent"]
    E --> S["总结 Agent"]
    S --> M[("SQLite 共享记忆")]
    M -->|"跨任务检索与复用"| P
    R --> V["评测模块"]

模块对应关系：

赛题模块	实现
多 Agent 运行时	`swarmlink/runtime.py`
协议解析与调度	`swarmlink/protocol.py`
状态交换	`swarmlink/vector.py`
共享记忆存储与检索	`swarmlink/memory.py`
评测与可视化	`swarmlink/metrics.py`、`swarmlink/benchmark.py`

快速开始

要求 Python 3.10+。从源码目录直接运行，无第三方运行时依赖。

python3 -m swarmlink demo --mode structured --output artifacts/demo
python3 -m swarmlink benchmark --rounds 10 --output artifacts/benchmark
python3 -m unittest discover -s tests_swarmlink -v

实验输出：

benchmark.json：完整原始结果与逐任务指标；
benchmark.csv：便于导入表格或论文绘图；
benchmark.md：自动生成的可复现实验报告；
dashboard.html：离线可打开的结果仪表板；
memory-text.sqlite3 / memory-structured.sqlite3：两种模式的独立记忆库。

openEuler 24.03-LTS-SP4

容器

docker build -t swarmlink:oe2403sp4 .
docker run --rm --shm-size=64m \
  -v "$PWD/artifacts:/opt/swarmlink/artifacts" \
  swarmlink:oe2403sp4

原生系统

sudo dnf install -y python3
bash scripts/verify_openeuler.sh

详细步骤、架构差异和故障排查见 docs/deployment-openeuler.md。

实验公平性

文本模式与结构化模式：

使用相同任务、事实、语料和 Agent 实现；
任务顺序一致，分别使用全新的记忆数据库；
都真实执行协议序列化、协议解析、检索、计算和记忆读写；
仅改变通信表示：文本模式把向量转成数字文本，结构化模式通过共享内存传递；
所有报告数值均由程序在目标机实时生成，不提交伪造的性能结果。

“估算 token”采用 4 字符/token 的透明粗略口径。正式答辩时可接入目标模型 tokenizer 复核，原始字符数和字节数不受 tokenizer 选择影响。

文档

上游兼容

原 OpenAI Swarm 包仍保留在 swarm/。若需要运行上游在线模型示例：

python3 -m pip install --no-build-isolation ".[upstream]"

上游项目已由 OpenAI Agents SDK 取代；SwarmLink 只把它作为明确、可追溯的教育型基线，不宣称为上游官方扩展。