MARS：Multi-Agent Runtime with Shared Memory

MARS 是面向 openEuler 的多智能体协作原型系统，通过结构化通信、非文本状态传递、共享记忆和 Linux 进程监督，降低多 Agent 协作中的上下文复制与状态传输开销，并提供可复现、可核验的实验与交付证据。

默认实现完全离线，不依赖 GPU、在线 LLM、模型下载或外部服务。Docker 构建和首次安装依赖时需要联网。

材料清单

应用场景

多 Agent 在单机内协作，需要降低全文上下文重复传递；
向量、文件等中间状态需要跨进程安全共享，而不是重新文本化；
Agent Worker 需要崩溃检测、超时控制、替代进程启动和资源回收；
历史证据需要在身份、摘要、输入指纹和 StateRef 全部校验后复用；
比赛或研究实验需要绑定源码提交、环境、命令和 SHA-256 的可复现证据。

主要功能

Rust/Python canonical message、Action、StateRef 和稳定错误模型；
Unix SOCK_SEQPACKET、SCM_RIGHTS、sealed MEMFD 和 mmap 状态传递；
pidfd + epoll + timerfd Worker 监督、取消、超时和 FD 生命周期管理；
FILE、DEV_SHM、MEMFD 分层状态后端；
SQLite 共享记忆、离线哈希嵌入和严格复用校验；
text/structured 通信评测、release benchmark、Rust metrics 复核；
FastAPI/React 通信开销对比界面；/api/reliability、/api/topology 只读接口；
non-root 单容器 production image 与固定命令 Web API；
manifest、命令日志、逐文件 SHA-256 和 canonical verifier。

决赛目录

.
├── README.md
├── src/                    # 项目源代码、schema、场景和工程脚本
├── docs/                   # 决赛文档（PDF）
├── tests/                  # fixtures、正式结果和统一验证入口
├── demo/                   # 单容器可运行交付入口
├── presentation/           # 决赛演示 PPT 与视频
└── 作品原创承诺书.pdf

源码模块：

src/crates/mars-protocol：canonical 协议；
src/crates/mars-ipc：SOCK_SEQPACKET frame、ancillary data 和 SCM_RIGHTS；
src/crates/mars-state：FILE、DEV_SHM、MEMFD 和 mmap；
src/crates/mars-runtime：Worker 启动、路由、监督、取消和 FD 生命周期；
src/crates/mars-metrics、src/crates/mars-bench：指标复核和 release benchmark；
src/crates/mars-observer：/proc、PSI 和可选 eBPF；
src/python/mars：Agent、记忆、评测、CLI、FastAPI 和 native client；
src/frontend：React/Vite 产品界面；
src/schemas、src/examples：JSON schema 和固定评测场景；
src/scripts：质量门、production smoke、native host gate 和 release bundle 工具。

系统环境

目标环境：

openEuler 24.03-LTS-SP3；
aarch64 或 x86_64；
Python 3.11；
stable Rust 1.90.0；
Node.js 24（仅前端构建/检查）；
Docker（推荐运行方式）。

开发宿主可以是 Linux 或 macOS，但 DEV_SHM、MEMFD、原生 runtime、strict capability 和 eBPF 等 Linux 能力只能在相应 Linux/openEuler 环境验证。

依赖要求

本机开发

Python 3.11 与 uv；
stable Rust 1.90.0 与 Cargo；
Node.js 24 与 npm；
Linux 原生能力仅在 Linux 上可用。

可选在线 LLM 使用 OpenAI-compatible API。请复制 .env.example 后自行填写端点、模型和凭据；仓库不提供或保存共享 API Key。

构建方法

Production image

docker build --pull -t mars:finals .

仓库只维护一个根 Dockerfile，无 Docker Compose。默认最终 stage 是 non-root production image；development、repository-check、frontend-check、frontend-dev 为开发和检查 target。

本机构建

uv sync --frozen
cargo build --locked --release -p mars-runtime -p mars-metrics

pushd src/frontend
npm ci --no-audit --no-fund
npm run build
popd

运行方法

一键离线 Demo

demo/run.sh
demo/verify.sh

访问：

http://127.0.0.1:5550

停止并清理：

docker stop mars-finals-demo
docker image rm mars:finals-demo
docker volume rm mars-finals-demo-artifacts

完整说明见 demo/README.md。

CLI 单任务

uv run --frozen mars run \
  --task "How should I create a reliable personal backup plan?" \
  --runtime-backend in-process \
  --json

Linux 上构建 runtime 后可显式选择 native：

export MARS_RUNTIME_BINARY="$PWD/target/release/mars-runtime"
uv run --frozen mars run \
  --task "How should I create a reliable personal backup plan?" \
  --runtime-backend native \
  --json

通信对比与连续评测

run_id=$(date -u +%Y%m%dT%H%M%SZ)

uv run --frozen mars compare \
  --task "请解释 Homo sapiens 的含义。" \
  --iterations 100 \
  --warmup 10 \
  --environment-label local-development \
  --output-dir "artifacts/compare-$run_id"

uv run --frozen mars eval \
  --scenario continuous-10 \
  --mode both \
  --environment-label local-development \
  --output-dir "artifacts/eval-$run_id"

cargo run --locked --release -p mars-metrics -- \
  "artifacts/eval-$run_id/metrics.csv"

测试方法

统一验证入口

tests/verify.sh

该命令运行宿主 Python/Rust 质量门，并验证 tests/results/ 中正式 bundle 的证据关系、manifest 和逐文件 SHA-256。详见 tests/README.md。

openEuler 容器质量门

src/scripts/check-container.sh

显式指定平台：

env MARS_PLATFORM=linux/arm64 src/scripts/check-container.sh
env MARS_PLATFORM=linux/amd64 src/scripts/check-container.sh

Production smoke

src/scripts/check-production.sh

该脚本验证 non-root 用户、health、可靠性快照、运行时拓扑、静态页面、最终镜像内容和退出码。

前端检查

pushd src/frontend
npm ci --no-audit --no-fund
npm run check
popd

物理 openEuler 专属门

src/scripts/check-native-host.sh --help

该入口包含 strict capability、100 轮 Worker crash/restart、eBPF load/attach 和 observer overhead；不得在 Docker/QEMU 中冒充物理机通过。

测试与证据

决赛证据已冻结并纳入仓库（openEuler 24.03-LTS-SP3 / aarch64 / Docker VM）：

finals-15f0c74-docker-vm-arm64：绑定 clean source 15f0c740d9a82d575c5dd524c262082a7ba61435；8 条成功命令，包含 release benchmark、双模式 eval、memory reuse、semantic memory、native structured eval。
finals-15f0c74-specialists-docker-vm-arm64：同一 source 的 communication v2 与 Tool v1；18 项 SHA-256。通信两组均 10/10 语义一致，Tool 覆盖 15 任务/132 消息。
latency-repeat-15f0c74：同一 source 的双模式 eval 连续 11 轮端到端总耗时；中位数文本 44.753 ms、结构化 43.868 ms。
native-stress-15f0c74：同一 source 的原生 Worker 100 轮崩溃恢复。

运行 uv run --frozen python tests/verify_evidence.py 可复核两个包的固定 manifest、精确文件集合和 canonical 语义；完整源码与证据门为 tests/verify.sh。摘要、容器入口和复现边界见 tests/README.md。实验 source commit 与纳入证据的 delivery commit 分开记录，不能把后者冒充测量源码。

新通信 v2 的离线 wire/logical/token 降低比例为 93.6845% / 92.1434% / 93.7344%；固定 2 ms mock 为 94.5425% / 92.9386% / 95.0769%，不是在线 LLM 或网络性能。共享记忆 warm 实际消费 4 条、跳过 4 次扫描、避免处理 24 项，但中位数 9.416 ms 仍慢于 disabled 的 3.564 ms；仅作为当次 Docker VM 观测。

普通 eval 仅在 text/structured 任务集合完整配对时给出跨模式比例；单模式或不完整结果显示 N/A。Git 不可用时 commit/dirty 为 null，不代表 clean。历史 communication v1 仍可只读核验；v1/v2 的字节/token 数不得混用。

已知限制

Web 只接受固定 command：run、eval、compare、capability-eval；
默认 production 容器为 non-root，不包含 Node、npm、Git、Cargo、rustc 或 uv；
在线 LLM 只是可选解释能力，不是默认正确性依赖；
Docker VM timing 只表示该环境下的观测，不代表物理 openEuler 性能；
物理机 strict capability、原生 eBPF load/attach 和 observer overhead 需要真实设备；
默认 DEV_SHM compare 需要 Linux /dev/shm，不能在 macOS 宿主服务中直接运行；
共享记忆 warm 可能慢于 disabled，项目保留负收益结果；
受限 Tool Agent 是固定 allowlist 业务工具，不是 CodeAct 或通用 OS sandbox；

许可证

项目使用木兰宽松许可证第 2 版，见 LICENSE。第三方依赖通过 Cargo、uv 和 npm lockfile 管理；AI 及第三方工具使用声明见 docs/人工智能及第三方工具使用说明.pdf。