LightMAS

LightMAS 是一个面向多智能体协作的轻量级运行时，专注于降低 Agent 间通信开销、减少中间状态的文本编解码，并将可验证的任务经验沉淀为可检索、可复用的共享记忆。

项目采用 OS-inspired 架构：Runtime 负责调度、租约和资源门禁，Agent 通过 Protobuf 二进制协议协作，StateBus 传递向量化状态，Experience Memory 管理跨任务经验，Evaluation 对文本模式与结构化模式进行可复现对比。

核心能力

• 多 Agent 运行时：Planner、Retriever、Executor 通过 Runtime 完成注册、能力发现、任务认领、租约与结果回传。
• 低开销通信：使用 Protobuf Envelope 和带校验的二进制帧，Linux 正式路径使用 Unix Domain Socket。
• 双模式对比：在相同逻辑消息和任务输入上，对比文本/JSON 与 Protobuf 结构化工作流。
• 非文本状态：State Capsule 封装 embedding 及其 schema，支持 INLINE、memfd/mmap、OBJECT 和 STREAM 传输策略。
• 共享记忆：支持 Episodic、Semantic、Procedural 三类经验，按向量、标签和关键词联合检索。
• 安全 CodeAct：生成代码先经 AST 策略校验，再进入 rootless Podman 无网络、只读文件系统的受限环境。
• 可复现评测：提供 G0–G3 消融实验、通信微基准、工作流对比、记忆复用和 10 轮连续任务。

系统组成

模块	职责	代码位置
Agent Runtime	任务空间、能力匹配、资源门禁、租约与 fencing token	src/lightmas/runtime/
Binary Protocol	Protobuf 消息、帧编解码、UDS/TCP 传输和幂等路由	src/lightmas/protocol/
StateBus	State Capsule、编码器、传输策略、生命周期与确定性算子	src/lightmas/statebus/
Experience Memory	经验模型、权威存储、向量索引、检索门禁和复用反馈	src/lightmas/memory/
CodeAct	代码生成边界、AST 校验、沙箱和程序记忆	src/lightmas/execution/
Evaluation	消融实验、工作流对比、统计聚合与报告	src/lightmas/evaluation/

快速开始

需要 Python 3.11 或更高版本。

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-dev.txt
python -m pip install -e .

检查当前平台能力：

lightmas doctor --json

运行三 Agent 二进制协作演示：

python -m lightmas.cli.multi_agent_demo

演示中 Planner 只发布任务，随后离线；Runtime 继续调度 Retriever 和 Executor，并通过二进制 UDS 完成多步任务。

实验与验证

# 文本工作流 vs 结构化工作流
python -m lightmas.cli.bench_workflow --samples 10

# JSON 文本消息 vs Protobuf 二进制消息
python -m lightmas.cli.bench_communication --samples 30

# 跨任务共享记忆复用
python -m lightmas.evaluation.memory_reuse

# 10 轮连续三 Agent 任务
python -m lightmas.evaluation.continuous_run

# G0–G3 机制消融实验
lightmas experiment --output artifacts/evaluation --repetitions 10 --seed 42

# 竞赛验收项
lightmas verify --suite competition --export artifacts/acceptance

运行代码质量检查：

./scripts/ci.sh

openEuler 部署

目标系统为 openEuler 24.03-LTS-SP3。

./deploy/openeuler/setup_env.sh
sudo ./deploy/openeuler/install.sh
sudo ./deploy/openeuler/start.sh
./deploy/openeuler/run_demo.sh

完整说明见 部署文档。

项目现状

• 核心功能均有单元、契约、集成或端到端测试覆盖。
• 仓库已包含对比实验原始数据和报告生成链路，但数值只能在相同环境下比较，不作跨机器绝对性能承诺。
• 当前 artifacts/acceptance/ 由官方 openEuler 24.03-LTS-SP3 aarch64 容器生成，UDS、memfd、cgroup v2、mmap 和 namespace 已通过；rootless Podman 和 systemd 完整启动仍需在 openEuler VM/实体机补充验收。
• 中文验收结论见 deliverables/openeuler-acceptance-report.md，展示截图见 artifacts/acceptance/openeuler-container-summary.png。
• 演示视频需按赛事渠道单独提交，仓库通过 .gitignore 避免误上传大体积媒体。

文档

文档导航、要求覆盖表和各模块设计见 docs/index.md。

许可证

本项目使用 MIT License，第三方组件说明见 THIRD_PARTY_LICENSES.md 和 deliverables/sbom.spdx.json。