SAGE-Mesh

Semantic Agent Gateway and Efficient Memory Mesh

SAGE-Mesh 是一个面向多智能体协作基础设施的可运行原型，核心目标是把 Agent 之间的 协作拆分为类型化控制面、非文本状态数据面和可追溯共享记忆面，并用四组消融实验分别 验证它们的作用。

已实现能力

• 四个独立进程角色：Planner、Retriever、Executor、Synthesizer；
• SACP 类型化协议：握手、能力发现、动作调用、结果返回、状态引用与错误处理；
• Unix Domain Socket 目标传输；Windows 开发环境使用 loopback TCP 回退；
• Semantic State Capsule：Float32、Float16、Int8、校验和、TTL 和只读消费；
• Linux memfd_create + mmap + SCM_RIGHTS 数据面及跨平台共享内存回退；
• SQLite、FTS5、向量 BLOB 和混合排序构成的共享记忆；
• 记忆兼容性、过期、负例过滤和复用审计；
• M0 文本基线、M1 协议、M2 协议加状态、M3 完整系统四组模式；
• 两个关联任务族、共十个固定任务和可复现证据包；
• 默认离线确定性后端，以及可选 OpenAI-compatible LLM/Embedding 接口；
• 失败关闭的 CodeAct 接口；任意代码仅允许在可用的 rootless Podman 沙箱中执行。

架构

Planner ─────┐
Retriever ───┼── SACP 控制面 ── State Capsule 数据面
Executor ────┤                   ├─ Shared Memory Mesh
Synthesizer ─┘                   └─ Trace / Benchmark / Evidence

模式	类型化协议	状态胶囊	跨任务记忆
M0 文本基线	否	否	否
M1 协议	是	否	否
M2 协议 + 状态	是	是	否
M3 完整系统	是	是	是

当前真实验证状态

主证据于 2026-07-25 在独立 VMware 虚拟机原生完成：

• openEuler 24.03-LTS-SP3 x86_64、内核 6.6.0-132.0.0.111.oe2403sp3.x86_64、Python 3.11.6、SELinux Enforcing；
• 严格 doctor 检查 Python、FTS5、Unix Socket、共享内存、memfd_create + mmap + SCM_RIGHTS 全部通过；
• Ruff、mypy、43 项测试全部通过，Linux 专用测试无跳过，覆盖率 86%；
• 强制 memfd 后端完成四 Agent Demo 和 4 模式 × 10 任务 × 3 次完整实验；
• Run ID：oe-native-20260725-v2，共 120 个任务运行；
• 四种模式任务成功率、根因准确率和证据 F1 均为 100%；
• M1 相对 M0 将 Agent 文本交接字符降为 0，线传输字节减少约 19.9%；
• M3 正确复用 9 次记忆，跳过 18 次工具调用，相对 M2 减少 30% 工具工作；
• 记忆 Recall@3、复用精确率和负例拒绝率均为 100%，错误复用为 0。

Windows 开发 Run 与官方 openEuler 容器 Run 仍作为补充证据保留，但最终平台声明以独立 虚拟机 Run 为准。原生实验中 M3 平均耗时 10.39 ms，高于 M0 的 4.93 ms；M3 线字节也 高约 6.0%。因此项目只声明协议减少文本交接、memfd 状态数据面真实工作、记忆减少 30% 工具调用，不声称当前原型已经获得端到端加速。

快速运行

在 Linux/openEuler：

make bootstrap
source .venv/bin/activate
make doctor
make test
make demo
make benchmark-smoke
make benchmark
make report
make reproduce
make audit
make package          # 生成草稿包，保留人工门禁提醒
make package-final    # 仅在最终 MP4 与手写承诺书 PDF 均存在时成功

在独立 openEuler 24.03-LTS-SP3 虚拟机复验最终平台时，使用：

make validate-native-openeuler

该目标会拒绝容器和 WSL，强制执行严格 doctor、memfd 主路径、完整测试/覆盖率、120 次 任务实验、报告复算、匿名审计与打包，并生成脱敏的 validation/openEuler-native-* 证据。

在当前 Windows 开发环境可直接使用：

py -3.13 -m pip install -e ".[dev,presentation]"
py -3.13 -m pytest -q
py -3.13 -m sage_mesh demo
py -3.13 -m sage_mesh benchmark --repeats 1
py -3.13 -m sage_mesh report

真实证据

• 最新汇总：results/summary.json
• 离线报告：results/report.html
• 最新 Run ID：results/latest_run.txt
• 原始证据：evidence/oe-native-20260725-v2/
• CSV：results/benchmark_runs.csv 与 results/summary.csv
• 复算命令：sage-mesh reproduce --evidence evidence/oe-native-20260725-v2
• 原生目标机验收：validation/openEuler-native-oe-native-20260725-v2/
• openEuler 容器补充证据：validation/openEuler-container-20260724-v5/
• 实验报告：docs/18_EXPERIMENT_REPORT.md

文档与材料

• 项目说明书.docx 与 项目说明书.pdf：基于官方 Word 模板生成并完成逐页检查；
• 作品介绍PPT.pptx：基于官方 PPT 模板生成，18 页均完成渲染和溢出检查；
• 作品原创承诺书.pdf：参赛者已按正式队名“布布一二”完整手抄、签署并扫描的正式承诺书；
• 06_SAGE-Mesh_演示视频.mp4：已合成参赛者本人口播的 3 分 10 秒 1080p VMware/openEuler 纯实录成片；
• deliverables/ 保留补充报告、可编辑 Markdown 和材料索引；
• 系统架构
• SACP 协议
• 状态胶囊
• 共享记忆
• 实验方法
• openEuler 部署
• 演示讲稿
• 视频分镜与成片证明
• 已知限制
• 提交检查表
• 逐项完成性审计
• 官方提交要求基线

目标平台

openEuler 24.03-LTS-SP3、x86_64、Python 3.11。

许可证

Apache-2.0，见 LICENSE。