LightMAS

LightMAS 是面向“多智能体协作中的低开销通信、非文本状态传递与共享记忆”赛题的 Python 原型系统。项目以可审计、可离线、可复现为优先目标，在同一批任务上分别测量完整文本、结构化状态和共享记忆的真实通信成本，适合在 openEuler 24.03-LTS-SP3 CPU 环境演示和复现，不依赖 GPU，也不强制下载本地大模型。

1. 赛题对应关系

LightMAS 对应赛题要求的实现如下：

多 Agent 协作：Planner、Retriever、Executor、Summarizer 四个 Agent 分工完成同一任务。
结构化协议：业务消息统一使用经过校验的 AgentMessage，并全部通过 Dispatcher。
非文本状态：PlanState、RetrievalState、ExecutionState 以 JSON 正文和 float32 embedding 分区序列化，通过 state_ref 获取。
共享记忆：SQLite 保存元数据，numpy 保存向量，支持关键词、标签和语义相似度检索。
公平评估：逐条统计消息、状态元数据、状态正文、向量和总传输字节。
离线复现：默认使用 MockLLMClient 和 sklearn HashingVectorizer，不联网下载模型。

2. 系统架构与四个 Agent

External task
    |
LightMASRuntime
    +-- LLMClient: Mock / OpenAI-compatible
    +-- AgentRegistry + AgentCapability
    +-- MessageDispatcher
    +-- StateStore
    +-- SharedMemory
    +-- CommunicationMetrics
    |
    +-- PlannerAgent
    |      拆解任务并生成 PlanState
    +-- RetrieverAgent
    |      检索历史记忆和本地文档，生成 RetrievalState
    +-- ExecutorAgent
    |      执行统计、关键词和安全表达式工具，生成 ExecutionState
    +-- SummarizerAgent
           汇总结果，并在启用共享记忆时写入当前任务记忆

Agent 之间不直接调用彼此业务函数。Runtime 从 Dispatcher 收件箱触发 Agent，所有业务消息经过结构化校验，并记录发送方、接收方、消息类型、序列化大小和处理耗时。

3. 三种实验模式

text_mode：传递完成相同任务所需的完整文本；不使用 StateStore、embedding 状态或共享记忆。
structured_no_memory：使用结构化 AgentMessage 和类型化非文本状态；不使用共享记忆。
structured_with_memory：使用结构化消息、类型化状态和 SQLite/numpy 共享记忆。

三种模式运行同一批 10 个任务，并分别创建独立 Runtime、StateStore、SharedMemory、 Metrics 和 Mock LLM，不会跨模式污染。

4. 项目结构

LightMAS-submit/
├── agents/                 # 四个协作 Agent
├── data/                   # 实验任务和配置
├── docs/                   # 设计、部署、实验与演示文档
├── evaluation/             # 通信与共享记忆评估
├── llm/                    # Mock 与 OpenAI 兼容模型客户端
├── memory/                 # MemoryUnit 和 SharedMemory
├── protocol/               # AgentMessage、枚举、能力与握手
├── runtime/                # Runtime、Dispatcher 和 Registry
├── state/                  # 三种类型化状态和 StateStore
├── tests/                  # 自动化测试
├── outputs/                # 正式实验产物，不应清理
├── app.py                  # Streamlit 页面
├── run_demo.py             # 三模式演示
└── run_experiment.py       # 可复现实验入口

5. 安装

建议使用 Python 3.10 及以上版本：

python -m venv .venv

Linux/openEuler：

source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

Windows PowerShell：

.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

6. 运行 Demo、实验和页面

python run_demo.py
python run_experiment.py
python -m pytest -q
python -m streamlit run app.py

run_demo.py 展示握手、能力发现、三模式轨迹、类型化状态、共享记忆和统一模型客户端。 run_experiment.py 无论外部环境如何配置都强制使用 Mock，保证主实验可复现。

7. Mock 模式与真实模型模式

默认不设置任何变量，即使用离线 MockLLMClient。相同消息生成相同 SHA-256 标识和预览文本，不产生网络请求。

可选真实模型通过 OpenAI 兼容 /chat/completions 接口接入。Qwen、DeepSeek 或其他兼容服务均使用以下四个环境变量：

export LLM_PROVIDER=openai_compatible
export LLM_BASE_URL=https://your-compatible-endpoint.example/v1
export LLM_API_KEY=your-secret-key
export LLM_MODEL=your-model-name
python run_demo.py

Windows PowerShell：

$env:LLM_PROVIDER="openai_compatible"
$env:LLM_BASE_URL="https://your-compatible-endpoint.example/v1"
$env:LLM_API_KEY="your-secret-key"
$env:LLM_MODEL="your-model-name"
python run_demo.py

安全规则：

API Key 只能从 LLM_API_KEY 环境变量读取，不能通过构造参数或项目配置文件传入。
缺少 API Key、Base URL 或模型名时自动回退 Mock，并记录非敏感回退原因。
客户端对象和安全配置展示不保存、打印或返回 API Key 内容。
.env 已加入 .gitignore；项目不会自动读取 .env 文件。

8. 实验任务、记忆检索与通信口径

data/tasks.json 包含 A/B 两组各 5 个连续任务。每条任务标注：

expected_memory_topics
expected_source_task_ids
expected_reuse
irrelevant_memory_topics

共享记忆顺序固定为：检索历史记忆 → 执行当前任务 → 写入当前任务记忆。检索过滤 current_task_id 并按 task_group 隔离。每组首任务没有本组历史候选；显式负样本在首任务完成后才加入。

正确命中必须同时满足：

相似度达到配置阈值。
来源任务属于 expected_source_task_ids。
Retriever 实际把该记忆加入当前上下文。

主要通信指标为：

total_transfer_bytes =
    message_utf8_bytes
  + state_metadata_bytes
  + state_body_bytes
  + state_vector_bytes

字符数和 token 数仅作辅助，其中 token 明确为估算值。

9. 输出文件

outputs/metrics_text.csv
outputs/metrics_structured_no_memory.csv
outputs/metrics_structured_with_memory.csv
outputs/comparison_report.md
outputs/raw_transfer_log.jsonl
outputs/memory_retrieval_detail.csv
outputs/memory_evaluation_report.md

正式 outputs/ 不在 .gitignore 中，属于可复现实验交付物。

10. openEuler 24.03-LTS-SP3 部署

sudo dnf install -y python3 python3-pip python3-devel gcc git
cd /path/to/LightMAS-submit
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m pytest -q
python run_demo.py
python run_experiment.py

启动只监听本机的展示页面：

python -m streamlit run app.py \
  --server.headless true \
  --server.address 127.0.0.1 \
  --server.port 8501

如需对外开放，应根据实际安全策略配置绑定地址、防火墙、反向代理和认证；不要直接把 API Key 写入 shell 历史、服务文件或代码仓库。完整部署说明见 docs/deployment_guide.md。

11. 最新实验结果

最后验证日期：2026-07-15。当前正式输出的摘要：

模式	total_transfer_bytes	记忆查询	严格命中任务
text_mode	98,743	0	0
structured_no_memory	149,583	0	0
structured_with_memory	265,959	10	8

共享记忆评估：Precision@1 0.700000、Precision@3 0.566667、Recall@3 0.937500、MRR 0.750000、false_positive_rate 0.227273、memory_hit_rate 0.800000。这些值由当前代码和任务真实计算；结构化模式字节数高于文本基线的结果被如实保留，没有硬编码“必须节省”。