MAS-Light

面向多智能体协作的低开销通信、状态传递与共享记忆系统

MAS-Light 面向多智能体协作场景，围绕自然语言通信冗余、中间状态反复文本化、历史经验难以跨运行复用，以及真实系统任务缺少确定性验证等问题，构建了一套可运行、可评测、可追踪的四 Agent 协作框架。

系统由 Planner、Retriever、Executor 和 Summarizer 四个 Agent 组成，并通过 A/B/C/D 四种消融模式，在相同任务、工具、Judge 和重复规则下比较文本通信、结构化通信、StateRef 状态传递与共享 Memory 复用效果。

---

. 演示作品视频链接名称

链接：https://pan.baidu.com/s/1ByR6HQNvuZEP9CJwZ4uWuA 提取码：9981

. 最终代码地址位置

最终代码版本在develop分支下面

1. 仓库说明

本项目早期开发阶段曾使用 Gitee 进行代码协作，后根据大赛作品提交要求迁移至 GitLink。

当前 GitLink 仓库为项目唯一正式开发、提交与评审仓库。后续分支管理、版本发布及竞赛作品材料均以本仓库为准，原 Gitee 仓库仅保留为历史开发记录，不作为当前作品提交基线。

正式 GitLink 仓库：

https://gitlink.org.cn/IxjP7CtKTu/yzmxdzntxzddkxtxztcdygxjyjz

HTTPS 克隆地址：

git clone https://gitlink.org.cn/IxjP7CtKTu/yzmxdzntxzddkxtxztcdygxjyjz.git mas-light

---

2. 核心功能

• 结构化通信
  使用 TaskPlan、ToolCall、ExecutionResult 等结构化对象组织动作、参数和执行结果，减少自然语言重复描述与二次解析。

• StateRef 状态传递
  Agent 消息仅传递轻量状态引用，真实 StateObject 由 StateStore 保存、加载、复用和清理。

• 共享 Memory
  D 模式按任务保存经 Judge 验证的经验，并在后续运行中完成检索、复用与反馈更新。

• 四 Agent 协作
  Planner 负责任务规划，Retriever 负责证据检索，Executor 负责受控执行，Summarizer 负责结果归纳与可复用经验整理。

• 受控工具边界
  通过工具注册、Schema 校验、路径限制、风险等级、超时和结构化错误，阻止越界或不规范调用。

• 确定性评测
  使用 Benchmark、Judge、Trace、Cleanup、Residue、Manifest 和 SHA256 构成完整证据链。

• 真实 systemd 场景
  覆盖环境变量缺失、文件权限异常和端口占用等受控系统服务故障。

---

3. A/B/C/D 消融模式

模式	通信形式	State	Memory	主要用途
A	文本通信	关闭	关闭	纯文本协作基线
B	结构化通信	关闭	关闭	观察结构化通信对通信开销和时延的影响
C	结构化通信	开启	关闭	验证 StateRef 非文本状态传递
D	结构化通信	开启	开启	验证跨运行 Memory 检索与复用

四种模式共享相同任务、工具能力、Judge、重复次数、稳定性设置和终止条件，仅改变通信形式、State 和 Memory 三类变量。

---

4. 系统架构

MAS-Light 的主要组成包括：

任务合同
  └── Benchmark 配置 / TaskPlan / 模式参数

四 Agent Runtime
  ├── Planner
  ├── Retriever
  ├── Executor
  └── Summarizer

状态与记忆
  ├── StateRef
  ├── StateStore
  └── shared_memory.db

执行与安全
  ├── ToolRegistry
  ├── 路径与命令边界
  ├── 风险等级
  └── Timeout

评测与证据
  ├── Evaluation
  ├── Judge
  ├── Trace
  ├── Cleanup
  ├── Residue
  ├── Manifest
  └── SHA256

系统遵循以下责任边界：

• Planner 负责规划，不直接修改系统；
• Retriever 负责读取证据，不扩大执行权限；
• Executor 只消费经过校验的 ToolCall；
• Summarizer 负责整理结果，不绕过工具层执行操作；
• Candidate 的自述不能替代 Judge；
• State 与 Memory 必须保留可追踪生命周期；
• 真实 systemd 任务完成后必须执行 Cleanup 和 Residue 检查。

---

5. 运行环境

推荐环境：

• openEuler 24.03 LTS-SP3
• x86_64
• Python 3.11.6
• systemd
• SELinux Enforcing
• Git
• Bash

真实 Task Group B systemd 测试还需要：

• PID 1 为 systemd；
• 当前用户可使用 sudo；
• 能够创建和清理专用测试服务 mas-demo.service；
• 能够访问项目预留的测试目录和端口；
• 不在生产主机或包含重要业务服务的环境中运行故障注入。

---

6. 安装

6.1 克隆仓库

git clone https://gitlink.org.cn/IxjP7CtKTu/yzmxdzntxzddkxtxztcdygxjyjz.git mas-light
cd mas-light

6.2 创建虚拟环境

python3.11 -m venv .venv
source .venv/bin/activate

6.3 安装依赖

python -m pip install --upgrade pip
python -m pip install -r requirements-lock.txt
python -m pip install -e .

6.4 检查依赖完整性

python -m pip check

---

7. 快速验证

7.1 全项目非特权回归

source .venv/bin/activate
python -m pytest -q

7.2 查看 Benchmark 参数

bash scripts/run_benchmark.sh --help

7.3 Benchmark 环境预检

下面的命令只检查任务计划、入口和环境合同，不执行完整实验矩阵：

bash scripts/run_benchmark.sh   --tasks A1,B1   --modes A,B,C,D   --repeats 3   --stability-rounds 10   --output-dir /tmp/mas-light-benchmark-check   --experiment-id readme-check   --check-only

---

8. 真实 systemd 演示

下面以 B1 环境变量缺失任务和 D 模式为例，运行 3 次重复，用于观察首轮 Memory 建立和后续跨运行复用。

执行真实 systemd 演示前，请确认当前环境允许使用 sudo。请勿在生产主机或包含重要业务服务的环境中运行。

source .venv/bin/activate
sudo -v

STAMP="$(date +%Y%m%d-%H%M%S)"
DEMO_ROOT="/tmp/mas-light-b1-d-${STAMP}"

bash scripts/run_benchmark.sh   --tasks B1   --modes D   --repeats 3   --stability-rounds 10   --output-dir "${DEMO_ROOT}"   --experiment-id "readme-b1-d-${STAMP}"   --real-systemd   --cleanup

成功完成时，终端应出现类似结果：

passed_runs=3
failed_runs=0
infrastructure_error_count=0
status=completed
BENCHMARK_RUN=COMPLETED

---

9. 结果与证据目录

一次 Benchmark 运行通常会生成以下证据：

<output_dir>/
├── benchmark_plan.json
├── tasks/
│   └── <task_id>/
│       └── runs/
│           └── <mode>/
│               └── <run_id>/
│                   ├── run.json
│                   ├── judge.json
│                   ├── raw_trace.jsonl
│                   ├── stdout.txt
│                   ├── stderr.txt
│                   ├── post_run_cleanup.json
│                   └── post_run_residue_evidence.json
├── summary.csv
├── final_cleanup.json
├── system_residue_evidence.json
├── manifest.tsv
└── SHA256 校验文件

关键文件说明：

文件	作用
run.json	单次运行结果与产物路径
judge.json	独立 Judge 的确定性判定
raw_trace.jsonl	Agent、工具、State 和 Memory 事件
post_run_cleanup.json	单次运行后的清理结果
post_run_residue_evidence.json	单次运行后的残留检查
final_cleanup.json	整体实验结束后的最终清理结果
system_residue_evidence.json	unit、目录、进程和端口的最终检查
summary.csv	实验结果汇总
manifest.tsv 与 SHA256	归档完整性校验

---

10. 项目目录

.
├── src/                         # MAS-Light 核心实现
├── tests/                       # 单元测试与集成测试
├── benchmarks/                  # Task Group A/B 与任务合同
├── scripts/                     # Benchmark 和辅助运行脚本
├── demo/                        # 示例与演示入口
├── docs/                        # 设计与技术文档
├── requirements-lock.txt        # 锁定依赖
├── pyproject.toml               # 项目配置
├── pytest.ini                   # 测试配置
└── README.md

---

11. 实验结果摘要

现有实验结果包括：

• 6 个任务 × 4 种模式 × 3 次重复，共 72 个 run；
• 72/72 个 run 在任务结果层面通过；
• 24/24 个任务—模式组合的 3 次重复结果一致；
• A、B、C、D 四种模式各 18/18 个 run 通过内部稳定性合同；
• B 模式相较 A 模式，总通信量下降约 8.89%；
• C 模式相较 B 模式，总通信量上升约 2.51%；
• D 模式相较 C 模式，总通信量上升约 25.56%；
• D 模式相较 C 模式，P50 时延下降约 5.32%，P95 时延上升约 1.12%；
• D 模式形成 6 次 Memory seed 和 12 次前序运行检索；
• 最终代码已在全新 openEuler 24.03 LTS-SP3 环境中完成安装、回归测试、真实 systemd 验证和零残留检查。

11.1 结果边界

以上“72/72”仅表示任务结果层面通过。

历史 A 组和 B 组来自不同执行提交，原始 B 组产物也未完整保存逐 run Cleanup/Residue 映射证据。因此当前状态为：

JOINT_72_RUN_ELIGIBILITY=BLOCKED
FINAL_JOINT_RESULT_ISSUED=NO

后续干净环境复现证明当前代码可以正确安装、运行、测试和清理，但不能反向替代历史运行证据。

---

12. 干净环境复现结果

最终代码已在全新 openEuler 24.03 LTS-SP3、x86_64、SELinux Enforcing 环境中完成复现。

主要结果包括：

• 严格环境检查通过；
• Demo 的 structured、text 和 state 模式通过；
• Benchmark check-only 通过；
• 全项目非特权回归：644 passed，15 skipped；
• 文档测试：13 passed；
• 入口与安装相关测试：41 passed；
• Task Group A Runtime：29 passed；
• Task Group B 基础真实 systemd：3 passed；
• Task Group B Runtime 真实 systemd：12 passed；
• Cleanup/Residue 专项：10 passed；
• 最终 unit、目录、进程和端口残留均为 NONE；
• 仓库工作区保持 clean；
• SELinux 最终保持 Enforcing。

该复现用于验证最终代码的可安装、可运行和可清理能力，不属于历史 72-run 的重新执行。

---

13. 竞赛提交材料

根据大赛要求，master 分支根目录应包含以下材料：

README.md
MAS-Light_项目说明书.pdf
MAS-Light_参赛承诺书.pdf
MAS-Light_演示PPT.pptx
MAS-Light_演示视频.mp4

其中：

• README.md：作品简介、安装和运行说明；
• MAS-Light_项目说明书.pdf：按照大赛官方模板编写，同时覆盖系统设计文档与技术报告内容；
• MAS-Light_参赛承诺书.pdf：使用大赛官方模板填写并完成手写承诺；
• MAS-Light_演示PPT.pptx：项目介绍、亮点、难点、测试与作品演示；
• 演示视频.mp4：时长不超过 5 分钟，文件大小不超过 100 MB。

GitLink 平台不使用 Git LFS 存放本项目视频。演示视频采用普通 Git 文件提交。

---

14. 第三方组件与许可证

项目使用 Python 标准库及公开开源依赖。最终版本以 requirements-lock.txt 和项目说明书中的依赖清单为准。

核心依赖类别包括：

• Python
• pytest
• SQLite
• NumPy
• openEuler
• systemd

第三方依赖通过系统环境或包管理方式引入，不作为团队自研代码统计。直接引用或修改的第三方源码、许可证及引用范围，应在项目说明书“代码原创说明”中单独列明。

---

15. 安全说明

• 真实 systemd 测试仅操作专用服务、测试目录和预留端口；
• 不应在生产环境或包含重要业务的主机中运行真实故障注入；
• 执行 Task Group B 测试前，应阅读 benchmarks/task_group_b/README.md；
• 测试结束后，应检查 system_residue_evidence.json，确认 unit、目录、进程和端口均已清理；
• 仓库、PPT、视频和文档中不得包含参赛单位、指导教师、参赛成员、单位邮箱、密码、Token、内网 IP 或其他可识别信息；
• 提交记录作者邮箱不得使用单位邮箱，建议使用个人匿名邮箱或 GitLink 系统邮箱。

---

16. 文档

• 项目说明书：MAS-Light_项目说明书.pdf
• 演示 PPT：MAS-Light_演示PPT.pptx
• 演示视频：演示视频.mp4
• 详细设计与接口说明：docs/
• Task Group B 说明：benchmarks/task_group_b/README.md

---

17. 已知限制

• 当前 Benchmark 主要覆盖代码修复和真实 systemd 服务修复场景；
• Memory 实验以每个任务 3 次重复为主，尚未覆盖大规模长期记忆库；
• D 模式增加 Memory 检索和反馈元数据，因此通信量和尾部时延仍有优化空间；
• Trace 保留已知 completion-event 排序 warning，该问题不影响 Judge、State 和 Memory 合同，但仍需后续修正；
• 当前联合正式资格仍为 BLOCKED，尚未签发最终联合结果。

---

18. 作品名称

MAS-Light：面向多智能体协作的低开销通信、状态传递与共享记忆系统

19. 演示作品视频链接名称

链接：https://pan.baidu.com/s/1ByR6HQNvuZEP9CJwZ4uWuA 提取码：9981

20. 最终代码在地址

最终代码版本在develop分支下面