MARS: Multi-Agent Runtime with Shared Memory

MARS 是一个面向 openEuler 的多智能体协作原型系统，用来验证三件事：

• 结构化消息能否减少多 Agent 间反复传全文上下文的开销。
• 向量等中间状态能否通过 StateRef、共享内存或 sealed MEMFD 传递，而不是被重新文本化。
• 历史 evidence 能否在严格校验后进入共享记忆，并在后续任务中被真实复用。

项目用于“中国研究生操作系统开源创新大赛”赛题：一种面向多智能体协作的低开销通信、状态传递与共享记忆机制。目标环境为 openEuler 24.03-LTS-SP3，默认离线运行（Docker 构建需联网），不依赖 GPU、在线 LLM、模型下载或外部服务。

我们也提供了一个 API Key 与自建代理端点，用于您方便地接入在线 LLM 验证。由于代码开源，为了防止滥用，我们设定了 token 限额，并提供一个脚本生成它，而不是直接明文放置在仓库中。

材料清单

• 项目说明书（设计文档、技术报告）DOCX / PDF
• 参赛承诺书 PDF
• 演示 PPT PPTX / PDF
• 演示视频 MP4

模块清单

• crates/mars-protocol：Rust canonical 协议，定义 Agent message、Action、StateRef、附件和错误类型。
• crates/mars-ipc：Unix SOCK_SEQPACKET frame、ancillary data 和 SCM_RIGHTS 基础 IPC。
• crates/mars-state：FILE、DEV_SHM、memfd 相关状态存储和 mmap 读取。
• crates/mars-runtime：Rust native runtime，负责 worker 启动、路由、监督、取消和 FD 生命周期。
• crates/mars-metrics：读取评测 metrics.csv 并汇总通信、状态、记忆和延迟指标。
• crates/mars-bench：release microbenchmark，覆盖文本、结构化消息、StateRef 和本地状态后端。
• crates/mars-observer：/proc、PSI 和可选 eBPF 观测路径。
• python/mars：Python Agent、共享记忆、CLI、评测、FastAPI 服务和 native runtime 调用层。
• frontend：React/Vite 前端，提供任务运行和结果展示界面。
• scripts：Docker 质量门、native host gate、eBPF object 构建和 release bundle 辅助脚本。
• schemas：OS capability、metrics、timeline、observer overhead 等 JSON schema。
• examples/scenarios：连续任务和记忆复用评测场景。

运行与测试

仓库只维护一个根目录 Dockerfile，没有 Docker Compose。默认 target 是 production image；development、repository-check、frontend-check 和 frontend-dev 用于开发、检查和前端调试。

下面的 docker run 命令统一用 --env-file .env 注入环境变量。生成的文件提供的 API Key 与 LLM 服务为作者自己搭建，启用了额度限制，请勿滥用。该文件不在仓库中，首次使用先生成（如前文所述）：

bash scripts/gen-env.sh

Docker openEuler 启动前端进行流程演示、效果验证

docker build --pull \
  --build-arg NODE_IMAGE=docker.m.daocloud.io/library/node:24-bookworm-slim@sha256:6f7b03f7c2c8e2e784dcf9295400527b9b1270fd37b7e9a7285cf83b6951452d \
  --build-arg OPENEULER_IMAGE=docker.m.daocloud.io/openeuler/openeuler:24.03-lts-sp3@sha256:03b3f365bbba13e9f90c70b08bd9aa0002bc69db858c2808cfab8a55d6e184e3 \
  -t mars:demo .

docker volume create mars-demo-artifacts

docker run --pull never --rm -d \
  --name mars-demo \
  --env-file .env \
  -p 127.0.0.1:5550:5550 \
  --shm-size 256m \
  -v mars-demo-artifacts:/workspace/artifacts \
  mars:demo

访问：

http://localhost:5550

健康检查：

curl --fail http://127.0.0.1:5550/api/health
curl --fail http://127.0.0.1:5550/api/config

停止：

docker stop mars-demo

Docker openEuler 命令行效果验证

docker build --pull \
  --target development \
  --build-arg OPENEULER_IMAGE=docker.m.daocloud.io/openeuler/openeuler:24.03-lts-sp3@sha256:03b3f365bbba13e9f90c70b08bd9aa0002bc69db858c2808cfab8a55d6e184e3 \
  -t mars:development .

docker volume create mars-cli-venv
docker volume create mars-cli-target

docker run --rm \
  --env-file .env \
  -e MARS_LLM_PROVIDER=offline \
  -e MARS_RUNTIME_BINARY=/workspace/target/release/mars-runtime \
  -v "$PWD":/workspace \
  -v mars-cli-venv:/opt/mars-venv \
  -v mars-cli-target:/workspace/target \
  -w /workspace \
  mars:development \
  sh -lc '
    set -eu
    run_id=$(date -u +%Y%m%dT%H%M%SZ)
    uv sync --frozen
    cargo build --locked --release -p mars-runtime -p mars-metrics
    uv run --frozen mars run \
      --task "How should I create a reliable personal backup plan?" \
      --runtime-backend native \
      --json
    uv run --frozen mars compare \
      --task "请解释 Homo sapiens 的含义。" \
      --iterations 100 \
      --warmup 10 \
      --environment-label docker-openeuler \
      --output-dir "artifacts/readme-compare-$run_id"
    uv run --frozen mars eval \
      --scenario continuous-10 \
      --mode both \
      --environment-label docker-openeuler \
      --output-dir "artifacts/readme-eval-$run_id"
    cargo run --locked --release -p mars-metrics -- \
      "artifacts/readme-eval-$run_id/metrics.csv"
  '

Docker openEuler 代码测试

scripts/check-container.sh

该脚本会构建 openEuler repository-check image 和 Node 24 frontend-check image：Python/Rust 检查在 openEuler 容器中运行，前端 ESLint、TypeScript 和 production build 在 Node 容器中运行。

如需显式指定 Docker 平台：

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

本机 openEuler 启动前端进行流程演示、效果验证

本机需要已安装 uv、Rust/Cargo 和 Node 24/npm。

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

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

export MARS_STATIC_DIR="$PWD/frontend/dist"
export MARS_RUNTIME_BINARY="$PWD/target/release/mars-runtime"
export MARS_RUNTIME_BACKENDS=in-process,native
export MARS_LLM_PROVIDER=offline

uv run --frozen mars-server

访问：

http://localhost:5550

本机 openEuler 命令行效果验证

本机需要已安装 uv 和 Rust/Cargo。

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

export MARS_LLM_PROVIDER=offline
export MARS_RUNTIME_BINARY="$PWD/target/release/mars-runtime"
run_id=$(date -u +%Y%m%dT%H%M%SZ)

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

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

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

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

本机 openEuler 代码测试

本机需要已安装 uv、Rust/Cargo 和 Node 24/npm。

uv sync --frozen
scripts/check.sh

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

scripts/check.sh 覆盖仓库拓扑、Shell 脚本语法、Python 格式/lint/test/type/security/dependency 检查，以及 Rust fmt/Clippy/workspace tests。前端检查在 frontend 目录单独运行。

说明边界

• Web 只接受固定 command：run、eval、compare、capability-eval。
• 默认 production 容器以非 root 用户运行，不包含 Node、npm、Git、Cargo、Rust compiler 或 uv。
• 可选在线 LLM 只作为解释能力，不是默认正确性依赖。
• eBPF、strict capability、100 轮 native stress 和 observer overhead 只应在真实物理 openEuler 主机上单独验收。