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

第三届中国研究生操作系统开源创新大赛 · 赛题：一种面向多智能体协作的低开销通信、状态传递与共享记忆机制（社区赛题）

项目简介

MASLink 是一个运行在通用 Linux / openEuler 上的多智能体协作运行时。四个 Agent（规划 Planner、检索 Retriever、执行 Executor、总结 Summarizer）作为独立进程运行，协作被拆成三个平面：

控制平面：结构化消息 StructuredMessage，收敛为动作类型、输入参数、返回结果、能力描述四类语义单元，支持握手、能力发现与作用域校验；决赛新增会话级持久运行时，四个进程每会话只启动、握手一次。
状态平面：证据特征编码为 float32 向量，经 POSIX 共享内存直接传递，消息中只带 SHA-256 引用；真实大模型路径上，原始观测由所有者持有，接收方按需请求有类型、有上界的投影。
记忆平面：任务结果沉淀为带记忆 ID、来源 Agent、创建时间、任务主题、摘要描述的记忆单元（SQLite），按依赖指纹判定是否仍然有效，经消费确认才计为实际复用。

所有结论都对应机器可读的证据。系统侧主要实验（测试、Demo、四模式消融、会话基准、公平记忆对照、10 轮稳定性）与 Formal 实验（OpenRCA 上的真实大模型正式对照实验）的聚合重算可用一条命令离线复现（见测试方法）；Formal 的完整离线重放需要封存的模型调用录制与评测数据，不在公开仓库中（见已知限制第 6 条）。

应用场景

多个 Agent 分工处理多步骤任务、且相邻任务之间存在关联的场景，例如：运维故障根因分析（本项目的基准任务与 OpenRCA 实验）、检索增强问答中的多角色流水线、代码协作中的规划—检索—执行—总结链路。MASLink 关注的是这些场景共同的系统层问题：Agent 间通信冗长、中间状态反复文本编解码、相似任务重复计算。

主要功能与结果

功能	说明	结果（证据位置）
多 Agent 运行时	4 个独立进程、握手、能力发现、按能力路由、错误响应、会话级持久运行	10 轮连续任务（每轮新建记忆库，运行公平任务集的 10 个任务，共 100 次任务执行）10/10 通过，结果哈希一致
纯文本 / 结构化双模式	相同任务、相同评分下对比 text、structured、structured_state、full 四种模式	10 个原始关联任务（MRS10：A1–A5、B1–B5）上结构化会话的总 payload 比纯文本低 34.36%，管理消息 240 → 24（2026-10-04 openEuler 容器复现，`tests/evidence/final_round/openeuler_public_20261004/`）
非文本状态传递	float32 证据向量经共享内存直传，引用 + SHA-256 校验，篡改即拒绝	创建/附着/使用/释放全生命周期计数一致，`/dev/shm` 残留 0（`tests/evidence/fsa/state/`）
真实大模型按需物化	所有者持有状态 + 引用 + 有类型投影，接收方计量	OpenRCA 12 对任务：以每个任务一次运行内全部模型调用的输入 token 之和配对比较，减少比例的中位数为 63.70%，12/12 为正；质量保持 INCONCLUSIVE（`tests/evidence/formal/`）
共享记忆	记忆单元元数据、关键词/标签/复用键/来源检索、依赖指纹失效、消费确认	公平记忆对照（公平任务集 A1–A4、A5F、B1–B3、B4F、B5F，记忆关闭 / 开启）：13 次实际复用，工具调用 33 → 14，先决任务重算 10 → 0；依赖变化即拒绝复用（`tests/evidence/final_round/phase6_full_session_20261001/`）
评测与证据	消息次数、字节、token、状态次数与规模、耗时、记忆命中与复用统计；离线 Evidence Cockpit	一键复现 `demo/reproduce_all.sh`（系统侧实验与 Formal 聚合重算）；Cockpit 页面数值逐项核验

系统环境

操作系统：openEuler 24.03-LTS-SP3（目标平台），或任意 x86_64 Linux（开发环境为 Ubuntu 24.04 / WSL2）。需要 POSIX 共享内存（/dev/shm）与多进程支持。
Python：3.11 或 3.12（openEuler 24.03-LTS-SP3 自带 Python 3.11.6）。
不需要 GPU 或任何大模型 API。依赖与 tiktoken 编码缓存就绪后，演示、测试与复现全部离线完成。

依赖要求

依赖	版本	用途	许可证
tiktoken	0.14.0	文本 token 计量	MIT
pytest	8.4.2	测试（开发依赖）	MIT

其余全部使用 Python 标准库（multiprocessing、multiprocessing.shared_memory、sqlite3 等）。tiktoken 首次使用时会下载 cl100k_base 编码文件；离线环境可预先下载后用 TIKTOKEN_CACHE_DIR 指定缓存目录。

构建方法

本项目为纯 Python 实现，无需编译。在 openEuler 24.03-LTS-SP3 上：

sudo dnf install -y python3 python3-pip git
git clone <本仓库地址> maslink && cd maslink
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'

不安装本项目也可以运行：python3 -m pip install pytest==8.4.2 tiktoken==0.14.0 后设置 export PYTHONPATH=$PWD/src:$PWD。一键复现脚本会自动设置 PYTHONPATH，并按 $PYTHON、.venv/bin/python、python3 的顺序选择解释器。

运行方法

# 1. 离线演示：启动 4 个 Agent 进程运行公平变体 Chain A（A1–A4、A5F），验证 A5F 对 4 个先决任务摘要的实际复用
#    与一次非文本状态生命周期，并生成证据页面
.venv/bin/python demo/demo_offline.py --out demo_output
#    浏览器打开 demo_output/cockpit/cockpit.html（单文件、无网络依赖）；演示顺序见 demo/DEMO_WALKTHROUGH.md

# 2. 四模式消融：纯文本 / 结构化会话 / +非文本状态 / +共享记忆，10 个连续任务，5 次平衡顺序重复
.venv/bin/python -m tools.phase6_2_final_ablation --repeats 5 --context-policy mode_native \
    --expected-source-sha "$(.venv/bin/python -m tools.phase6_2_final_ablation --print-source-sha | cut -d' ' -f1)"

# 3. 会话摊薄基准：N = 1、2、5、10 个任务下纯文本、逐任务结构化与会话结构化的消息、载荷与耗时
.venv/bin/python -m tools.phase5_session_benchmark --repeats 1

# 4. 公平记忆对照：公平任务集的 10 个关联任务，记忆关闭 / 开启各 3 次配对
.venv/bin/python -m tools.phase6_full_session_benchmark --repeats 3

# 5. 10 轮稳定性：每轮新建记忆库，连续运行公平任务集的 10 个任务
.venv/bin/python -m tools.fsa.stability --root results/stability --rounds 10

# 6. 单个模式跑完两组关联连续任务（A1–A5、B1–B5），模式可选 text / structured / structured_state / full
.venv/bin/python -m agent_runtime.cli benchmark --provider fixture --mode full --results-dir results/full_run

结果写入 04_evidence/local_verification/ 或 results/ 下的新目录（均已被 .gitignore 忽略），命令结束时打印路径；demo/summarize_ablation.py <summary.json> 打印消融中位数表。

测试方法

一键复现（推荐）：

bash demo/reproduce_all.sh            # 可选参数：输出目录；默认 results/reproduce_<时间>/

依次运行：公开测试集（916 项）→ 离线 Demo 与 Cockpit 核验 → Formal 聚合重算（由逐任务脱敏结果重算 12 对任务，0 次模型调用）→ 四模式消融 → 会话摊薄基准 → 公平记忆对照 → 10 轮稳定性，最后打印结果表与 REPRODUCE PASS/FAIL。运行前需按构建方法安装依赖；离线环境另需 tiktoken 编码缓存（见 docs/部署与复现说明.md 2.3 节）。

提交前，在 openEuler 24.03-LTS-SP3 容器（无网络）中对提交树执行了这条命令并全部通过，完整输出见 tests/evidence/final_round/openeuler_public_submission_20261005/。其中 TREE_SHA256SUMS.txt 是被验证树的逐文件哈希；此后没有改动任何代码、测试或脚本，只加入了该运行记录，并修订了文档类文件（README、说明文档、PPT、视频与字幕）的措辞；手写声明扫描件也属于文档类文件。

只运行测试：.venv/bin/python -m pytest -q -p no:cacheprovider。

测试与验证材料的组织方式、每类证据能支持哪些结论，见 tests/README.md。

目录结构

本仓库按决赛作品提交规范组织：

路径	内容
`README.md`	本文件
`src/agent_runtime/`	项目源代码：协议、调度与会话、worker、状态平面、共享记忆、计量、评测
`docs/`	项目说明书、项目创新说明、成员分工及主要贡献说明、人工智能及第三方工具使用说明（PDF）；`docs/部署与复现说明.md`；`docs/sources/` 为文档源稿与图
`tests/`	单元 / 集成 / smoke / OpenRCA 工具测试；`tests/evidence/` 为封存的实验结果、运行日志与失败记录
`demo/`	离线 Demo、Evidence Cockpit 生成与核验、一键复现脚本
`presentation/`	决赛现场演示 PPT 与演示视频（视频中的终端与浏览器画面均为真实运行录制：大模型一段在联网环境中真实调用模型 API，其余为提交版本在无网络的 openEuler 容器中运行；旁白为语音合成，字幕即旁白原文）
`作品原创承诺书.pdf`	作品原创承诺书
`bench/`、`config/`	运行所需的基准任务（两组关联连续任务 A1–A5、B1–B5 及公平对照变体）与配置
`tools/`	运行所需的验收、基准与实验工具（会话基准、四模式消融、系统验收、OpenRCA 实验与离线重放）
`third_party/`	第三方代码（OpenRCA 评分器与适配代码，MIT，含 LICENSE / UPSTREAM / MODIFICATIONS）
`scripts/`	基准任务规格校验

bench/、config/、tools/、third_party/、scripts/ 被源代码通过相对路径直接引用，因此保留在根目录以保证仓库克隆后即可运行。

已知限制

系统侧（四模式消融、会话、记忆实验）的四个 Agent 使用确定性 fixture 逻辑，不是四个大模型 Agent；真实大模型验证是独立的 OpenRCA Formal 实验，两类证据分别陈述，不合并宣称。
Formal 实验只有 12 对任务、单一模型，质量保持结论为 INCONCLUSIVE（严格正确 T2+S 2/12、M 1/12）；只主张通信效率与状态机制，不主张质量提升。
共享记忆减少了重复工具调用与重算，但开启后端到端时延更高；非文本状态在本任务集上没有带来时延收益（用于证据排序，不改变诊断结论）。
结构化会话的节省随任务数增加出现：单个任务时结构化仍比纯文本多传输数据。
openEuler 验证在容器用户态完成（宿主为 WSL2 内核），不等同于物理机或原生内核验证。
完整的 Formal 离线重放需要封存的模型调用录制与 OpenRCA 评测数据（数据为 CC BY-NC 4.0，不在本仓库分发）；公开仓库提供脱敏聚合与可重算的逐任务结果。