# MAS LiteState

一种面向多智能体协作的低开销通信、状态传递与共享记忆机制。

MAS LiteState 面向多 Agent 协作过程中常见的上下文膨胀、重复状态传输和跨任务记忆复用困难问题，提出一种“控制消息结构化传输、较大状态对象引用化复用、共享记忆跨任务检索”的轻量化实现方案。系统以 Python 为主要实现语言，可在 Windows 与 openEuler/Linux 环境中运行，并支持真实 GPT 调用、批量 token 对比、本地 IPC benchmark 与 HTML 可视化展示。

项目特点

• 多 Agent 协作链路：包含 PlannerAgent、RetrieverAgent、ExecutorAgent、SummarizerAgent，用于模拟任务拆解、检索、执行与总结流程。
• 结构化通信协议：使用 action、params、result_ref、state_ref 等字段传递控制信息，避免在 Agent 间重复传输长文本。
• 状态引用机制：将 embedding、检索证据、benchmark 结果和中间摘要写入 StateStore，再通过引用传递。
• 共享记忆复用：基于 SQLite 实现跨任务记忆存储与检索，支持 memory_hits 统计。
• 跨平台通信后端：支持 inprocess、tcp、unix、auto；Linux/openEuler 可使用 Unix Domain Socket，Windows 自动回退到 TCP loopback。
• 真实 GPT 实验：同一批 20 个问题分别运行传统文本协作轮与 MAS LiteState 结构化协作轮，统计真实 input_tokens、total_tokens 与记忆命中。
• 可视化展示：生成 dashboard.html、showcase.html、llm_dashboard.html，便于截图、汇报、复验和演示。

核心机制

MAS LiteState 将多 Agent 协作中的信息流拆分为三层：

控制面只传递轻量化结构化消息；数据面保存较大的中间状态；记忆面负责跨任务历史结果检索。通过这种分层方式，系统减少了传统纯文本协作中“每个 Agent 都重复携带完整上下文”的开销。

项目结构

mas_litestate/
├── mas_litestate/                 # 核心源码
│   ├── agents/                    # 多 Agent 实现
│   ├── eval/                      # 批量实验任务集
│   ├── llm/                       # GPT / Responses API 客户端
│   ├── memory/                    # SQLite 共享记忆
│   ├── protocol/                  # 结构化消息协议
│   ├── runtime/                   # 调度器、指标统计、IPC benchmark
│   ├── state/                     # StateStore 与 shared-memory 状态后端
│   ├── transport/                 # inprocess / TCP / Unix Domain Socket
│   └── utils/                     # 工具函数
├── config/                        # LLM 配置示例
├── data/                          # CSV、SQLite 和中间数据
├── docs/                          # 设计文档与 README 图片
├── reports/                       # HTML、JSON、归档实验结果
├── run_menu.py                    # 主菜单入口
├── run_menu.sh                    # Linux/openEuler 菜单入口
├── run_llm_compare.py             # 单题 GPT 对比
├── run_llm_batch_compare.py       # 20 题真实 GPT 两轮隔离实验
├── generate_llm_dashboard.py      # 生成真实 GPT 对比 dashboard
├── generate_showcase.py           # 生成单题 showcase 页面
├── run_benchmark.py               # 本地 benchmark
├── compare_metrics.py             # benchmark 指标对比
└── generate_dashboard.py          # 本地 benchmark dashboard

适用场景

MAS LiteState 适合用于研究或演示以下问题：

• 多 Agent 系统中上下文膨胀与 prompt 传输开销问题。
• 本机 Agent 编排中的 IPC 选择与传输后端适配。
• 大状态对象从文本传递改为引用传递后的工程收益。
• 共享记忆在跨任务复用中的命中统计与可视化。
• openEuler/Linux 环境下轻量级 Agent 运行时原型验证。

快速开始

Windows

python run_menu.py

openEuler / Linux

chmod +x run_menu.sh
./run_menu.sh

菜单入口如下：

1. 输入问题并进行 GPT 回答
2. 运行 Benchmark，生成并打开 dashboard
3. 生成并打开 showcase 展示页面
4. 退出

其中，菜单 2 会运行真实 GPT 20 题批量实验，会产生实际模型调用消耗。若只想查看页面效果，可优先使用已经归档的数据重新生成页面。

LLM 配置

编辑 config/llm_config.local.json：

{
  "api_key": "你的 GPT 文本模型 key",
  "base_url": "url链接",
  "model": "gpt-5.5",
  "reasoning_effort": "medium"
}

连接测试：

python run_llm_compare.py --debug --list-models --probe-only

单题问答演示

通过菜单选择 1，输入中文问题即可运行一次完整链路。系统会先执行本地 Agent 协作，再构造传统 prompt 与 MAS LiteState 优化 prompt 调用 GPT，并输出回答与 token 对比。

也可以直接执行：

python run_llm_compare.py --task "请解释 Agent 和大模型的区别" --transport auto --state-store shared-memory
python generate_showcase.py

输出文件：

reports/llm_compare.json
reports/showcase.html

真实 GPT 批量实验

真实 GPT 批量实验是当前项目最重要的评测入口，用于展示通信效率与记忆复用效果。实验采用两轮隔离设计：第一轮完整运行传统文本协作，第二轮完整运行 MAS LiteState 结构化协作，两轮之间不交叉执行，避免上下文污染。

运行命令：

python run_llm_batch_compare.py --limit 20 --transport auto --state-store shared-memory
python generate_llm_dashboard.py

若已经跑过真实 GPT 实验，后续只修改页面或图表时，不需要重新消耗 token，可直接使用归档结果生成：

python generate_llm_dashboard.py --latest-archive

主要输出：

data/llm_batch_compare.csv
reports/llm_batch_compare.json
reports/llm_dashboard.html
reports/llm_runs/llm_batch_compare_latest.csv
reports/llm_runs/llm_batch_compare_latest.json

当前 20 题真实实验结果：

指标	传统文本协作	MAS LiteState	效果
输入 token	94,944	90,599	节省 4.58%
总 token	125,913	122,333	节省 2.84%
重复任务可命中次数	9	9	命中率 100%

说明：输入 token 更能直接反映通信效率，因为输出 token 会受模型生成长度影响；总 token 可作为辅助指标。20 个问题中设置了非连续重复任务，用于验证共享记忆是否能跨任务命中历史结果。

本地 Benchmark

本地 benchmark 不调用 GPT，主要用于验证通信机制和状态复用机制本身。

python run_benchmark.py --mode structured --rounds 50 --transport auto --state-store shared-memory
python run_benchmark.py --mode text --rounds 50 --transport auto --state-store shared-memory
python compare_metrics.py
python generate_dashboard.py

输出文件：

data/metrics_structured.csv
data/metrics_text.csv
reports/dashboard.html

常用指标：

指标	含义
text_chars	传统文本模式传输的字符规模
structured_bytes	结构化消息序列化后的字节规模
transport_bytes	传输层记录的数据规模
state_transfer_count	状态对象引用或转移次数
memory_hits	共享记忆命中次数
elapsed_ms	批量任务端到端耗时

页面查看

Windows 可直接双击或用浏览器打开：

reports/llm_dashboard.html
reports/showcase.html
reports/dashboard.html

openEuler/Linux：

firefox reports/llm_dashboard.html
firefox reports/showcase.html

如果当前目录不是项目根目录，请使用绝对路径：

firefox /root/mas_litestate/reports/llm_dashboard.html

openEuler 部署示例

假设压缩包 mas_litestate.zip 位于 VMware 共享目录中：

mkdir -p /mnt/hgfs
vmhgfs-fuse .host:/ /mnt/hgfs -o allow_other

rm -rf /root/mas_litestate
unzip /mnt/hgfs/mas_litestate/release/mas_litestate.zip -d /root/

cd /root/mas_litestate
chmod +x run_menu.sh
./run_menu.sh

环境检查：

cat /etc/os-release
uname -a
python3 --version
python3 -c "import sqlite3, multiprocessing.shared_memory, socket; print('sqlite/shared_memory/socket ok'); print(hasattr(socket, 'AF_UNIX'))"

DNS 或网络异常时可先检查：

ip addr
ip route
cat /etc/resolv.conf
ping -c 3 223.5.5.5
ping -c 3 www.baidu.com

若只有 DNS 解析失败，可临时写入：

cat > /etc/resolv.conf <<EOF
nameserver 223.5.5.5
nameserver 114.114.114.114
nameserver 8.8.8.8
EOF