LeanMAS

LeanMAS：面向多智能体协作的指针优先低开销通信与共享记忆运行时

LeanMAS 是面向 openEuler 24.03-LTS-SP3/通用 Linux 的 Python 3.11 原型。它用二进制 TLV 控制协议、共享内存语义向量与 SQLite 共享记忆，比较传统纯文本协作和结构化协议协作。系统包含 Planner、Retriever、Executor、Summarizer 四个逻辑 Agent，内置 10 个可离线复现的连续任务。

运行

python -m unittest discover -v
python scripts/run_demo.py --mode structured --backend offline
python scripts/run_benchmark.py --backend offline --tasks 10 --output results/offline

运行 DeepSeek 对照实验前，在根目录创建 .env：

DEEPSEEK_API_KEY=your_key
# 可选；默认 https://api.deepseek.com/v1/chat/completions
DEEPSEEK_BASE_URL=https://api.deepseek.com/v1/chat/completions

python scripts/run_benchmark.py --backend deepseek --tasks 10 --output results/deepseek

模型 API 名称为 deepseek-v4-flash。DeepSeek 为 Planner 生成策略注释；检索、工具执行和总结由本地运行时完成。API 调用失败时，程序返回相应错误信息。

核心机制

• 控制面：每种协作模式启动时，Agent 执行一次 HELLO/CAPABILITY_ADVERTISE。结构化模式使用 TLV，纯文本模式使用长度定界的 UTF-8 文本信封；两种模式均按“编码 → 解码 → 校验 → 分发”处理消息。文本信封保留任务证据与协作历史；运行时从解码信封读取 receiver、action、capability、params、result_ref、state_ref 和 memory_refs 完成路由。
• 数据面：确定性哈希特征投影把任务编码成 128 维向量，写入 multiprocessing.shared_memory。结构化模式的 Retriever 与 Executor 按解码信封的 state_ref 校验并读取 float32 向量，分别用于证据排序和记忆复用可靠性判断；每次成功读取都单独计入非文本状态指标。
• 记忆面：SQLite MemoryUnit 保存 ID、来源、创建时间、主题、摘要、标签、证据引用、策略、向量、可复用 result_label 和复用计数，支持关键词、标签和语义检索。评测分别统计“候选记忆命中”和“验证后实际复用”。当候选含有 result_label，且至少两个标签相同或向量相似度达到阈值时，Executor 使用 memory_targeted 路径；其余任务使用 full_scan。

数据和复现

data/tasks.json 是冻结的小型切片：5 个来自 Loghub Linux 数据集的真实日志行与 5 个来自 PyPA Advisory Database 的 Requests 漏洞审计任务。来源、许可条件及上游 SHA-256 位于 data/SOURCES.md。程序运行时不下载任何数据。

目录

leanmas/       运行时、协议、向量、记忆、评测与 DeepSeek 客户端
data/          冻结任务、来源、许可及校验信息
scripts/       Demo 与 benchmark 命令
tests/         32 个标准库 unittest
results/       已生成的 offline/DeepSeek 实验原始记录与汇总
docs/          系统设计、部署与实验说明

详细说明见 docs/design.md、docs/deployment.md 与 docs/experiment.md。