ProtoMem-MAS：多智能体低开销协作原型

ProtoMem-MAS 面向社区赛题“一种面向多智能体协作的低开销通信、状态传递与共享记忆机制”。项目提供可运行的多智能体基础设施原型：用结构化协议替代冗长的 Agent 间文本转发，用二进制 StateBlob 传递中间语义特征，并以共享记忆支持跨任务检索和复用。

赛题原始说明保留在 docs/original_readme.md。

已实现能力

四类协作角色：规划、检索、执行、总结 Agent；运行时负责注册、握手、调度、路由和追踪。
LACP 结构化协议：消息包含动作、参数、结果、能力、状态引用和记忆引用，并在调度前完成模式校验。
非文本状态传递：将上游内容编码为固定 128 维 float32 StateBlob，通过 .npy、POSIX 共享内存或 memfd 传递；下游按 state_id 装载并用于向量检索。
共享记忆：SQLite MemoryUnit 记录记忆 ID、来源 Agent、创建时间、主题、摘要、标签、向量引用与复用次数，支持关键词、标签、语义和精确任务检索。
CodeAct 执行：Executor 可在受约束的轻量运行器中执行生成的 Python 代码并返回结构化结果。
评测体系：包含文本/结构化对照、State-only 对照、连续任务链、十轮稳定性和外部基准适配器。

当前实验概览

远端 LLM 实验读取本地 .env 模型配置，采用单进程串行调用。主证据采用 ≥50 题 固定切片。Bus Token 衡量 Agent 总线传输开销，API Token 为模型服务用量。

实验	当前可复现结果
MultiAgentBench Research（50 题）	总线 Token -62.3%，API Token -9.6%，代理分 `0.7192 -> 0.9374`，StateBlob 247 次，记忆命中率 0.98。
MultiAgentBench Coding（50 题）	总线 Token -52.0%，API Token -18.2%，代理分 `0.3363 -> 0.4009`，StateBlob 150 次。
MultiAgentBench Database（50 题）	总线 Token -54.8%，时延 -48.4%，StateBlob 250 次，记忆命中率 0.98。
Research State-only（50 题）	下游不转发角色正文，仅靠 StateBlob 检索即可完成任务：向量命中 247/247，代理分保持约 0.93。
HumanEval（50 题）	CodeAct 执行率 `1.00`，pass@1 `0.96`。
HotpotQA（50 题）	总线 Token -85.6%，时延 -20.2%，F1 `0.7619 -> 0.7743`，成功率 `0.84 -> 0.92`，StateBlob 100 次。
SWE-bench Lite（50 实例）	analyze→patch 共 100 任务；StateBlob 200 次；记忆命中率 0.99，实际复用 628。
MuSiQue（50 关联组）	chain B memory-on 复用 2033、命中率 0.98；memory-off 复用与命中均为 0，形成跨任务记忆因果对照。
连续任务与十轮稳定性	Memory on 可跳过 Retriever；十轮全栈 `10/10` 成功，协议校验与 StateBlob 传递完整。

赛题要求的通信压缩、非文本状态传递、共享记忆复用与十轮稳定性均已在 ≥50 样本下得到验证。完整指标与复现入口见当前模型重跑结果与赛题逐项核验。

快速开始

环境要求：Linux、Python 3.10+。默认单元测试不依赖第三方包。

git clone https://www.gitlink.org.cn/HBrEYHLFWo/yzmxdzntxzddkxtxztcdygxjyjz.git
cd yzmxdzntxzddkxtxztcdygxjyjz

# 验证核心模块
python3 -m unittest discover -s tests -q

# 运行结构化协作演示
python3 run_demo.py --mode structured --task contest_solution

真实 LLM 实验从本地 .env 读取配置，不会将密钥写入仓库：

cp .env.example .env
# 编辑 .env，设置 LLM_API_KEY、LLM_BASE_URL、LLM_MODEL

复现实验

# 串行真实 LLM 对照：每次仅运行一个 50 题场景
python3 -u run_exp15_mab_all_llm.py --scenario research --limit 50
python3 -u run_exp15_mab_all_llm.py --scenario coding --limit 50
python3 -u run_exp15_mab_all_llm.py --scenario database --limit 50

# 非文本 StateBlob 下游对照：50 题
python3 -u run_exp17_state_only_mab.py --scenario research --limit 50

# 外部问答基准：50 题 B0/B3 全角色 LLM 成对对照
python3 -u run_authoritative_eval.py --benchmark hotpotqa \
  --dataset history/data/benchmarks/hotpotqa/hotpot_validation_first100.json \
  --limit 50 --mode both --variant full --llm --require-agent-llm \
  --output-dir verification/results/current_reruns/hotpotqa_50_all_role_llm --resume

run_authoritative_eval.py 为输出目录加锁，并支持 --resume，可在中断后续跑而不重复发起 API 调用。

文档导航

答辩材料：Blueprint 答辩版 PPT、创新点与全量指标重组稿及使用说明。
系统设计：架构、协议、状态和记忆的数据流。
部署指南：环境、配置、运行与排障。
赛题逐项核验：每项要求对应的实现和验证入口。
当前模型重跑结果：端到端、基准和单机制的当前汇总。
完整实验报告：指标定义、实验设计和结果分析。
操作系统运行时设计：状态分页、共享对象和隔离能力。
演示脚本与项目结构。
验证材料与历史材料索引。

目录结构

agents/       核心角色和基准角色 Agent
protocol/     LACP 模式、编解码、能力卡与路由
runtime/      注册、握手、调度、消息总线与追踪
state/        StateBlob、嵌入、共享内存和 memfd 后端
memory/       MemoryUnit、SQLite 存储与向量检索
evaluation/   指标、基准适配、评分与评测运行器
tools/        CodeAct 轻量运行器与系统工具
presentation/ 答辩版 PPT、创新点与全量指标重组稿
verification/ 可复现的机制验证脚本和汇总报告
history/      已归档的旧脚本、报告和本地原始材料索引