OS-Agent Mesh · Agent 协作运行时

让 Agent 像操作系统进程一样协作：消息走协议，长状态走引用，经验进入共享记忆。

OS-Agent Mesh 是面向操作系统开源创新大赛第 10 题的可复现运行时：面向多智能体协作的低开销通信、状态传递与共享记忆机制。

它不是把多个模型简单串起来，而是把 Agent 协作落到可测量的系统机制：消息协议、进程边界、IPC 帧、文件映射、持久化记忆和故障恢复。

它把多 Agent 协作拆成三个可以被操作系统工程验证的问题：

Agent 之间是否可以用版本化、可校验的结构化消息协作？
长状态是否可以脱离消息正文，以固定维度二进制状态和 state_ref 传递？
第一个任务得到的证据，是否能被第二个相关任务检索和复用？

这是一条可以运行、观测、故障注入、压测和复现的 Agent 运行时链路。

30 秒看懂项目

评审关注点	OS-Agent Mesh 的回答
协作对象	Planner、Retriever、Tool Executor、Summarizer 四个角色，支持独立进程边界
通信方式	版本化 `Message` 协议；Linux/openEuler 可使用命名 Unix Domain Socket
状态传递	固定维度 `float32` 状态向量；可落盘为 `mmap` 文件，消息只携带 `state_ref`
共享记忆	SQLite 元数据 + 证据 + 向量；余弦相似度检索，支持跨任务命中
安全边界	默认确定性离线后端；系统观测使用只读 `systemd-analyze` 适配器
可验证性	11 项测试、10 轮基准、UDS + mmap 演示、时间戳证据和 SHA-256 校验

已验证证据（真实运行结果）

证据来自仓库内 evidence/openeuler/20260713T074259Z/，运行环境是官方 openEuler 24.03-LTS-SP3 WSL 镜像。下面的数字由 benchmark.json 和 demo_uds_mmap.json 生成，不是手填的宣传指标。

结果	数值	说明
单元与集成测试	11/11 通过	见 `evidence/openeuler/20260713T074259Z/tests.log`
基准轮数	10 轮	每轮包含两个连续相关任务
结构化协议字节数	9,167 B	`structured_only` 平均消息字节数
相对文本基线	减少 24.9%	9,167 B 对比 12,214 B，按真实结果计算
全链路记忆命中率	95%	`structured_state_memory`，第 1 轮建立记忆，后续轮次复用
成功率	100%	三种模式均为 10/10 轮成功
UDS + mmap 演示	18 帧 / 2 次状态传递	状态数据 520 B，失败 0 次，重试 0 次

这里有一个刻意保留的工程取舍：structured_only 追求最低消息开销；structured_state_memory 额外携带记忆查询、证据和状态引用，平均为 11,981 B，但获得 95% 的跨任务记忆命中率。项目不把两种模式混成一个“万能指标”，而是把开销与复用能力同时展示。

证据边界：当前记录证明的是 openEuler 24.03-LTS-SP3 用户态部署和 WSL2 内核环境上的运行结果，不宣称裸机内核验证。真实系统启动数据需在目标 systemd 主机使用 --real-systemd 重新采集。

架构一览

flowchart LR
    O[Orchestrator] --> P[PlannerAgent\n任务拆解 / PLAN]
    P --> R[RetrieverAgent\nSQLite 共享记忆]
    R --> X[ToolExecutorAgent\n只读观测 / mmap 状态]
    X --> S[SummarizerAgent\n证据汇总 / RESULT]
    X -. state_ref .-> M[(mmap StateStore)]
    R <--> D[(SQLite MemoryStore)]
    O -. metrics .-> Q[MetricsCollector\n字节 / 延迟 / 命中率 / 重试]

核心链路是：短消息传控制面，二进制状态传数据面，共享记忆传经验面。

核心接口

@dataclass
class Message:
    schema_version: str
    message_id: str
    task_id: str
    sender: str
    receiver: str
    message_type: str
    payload: dict
    state_ref: str | None
    correlation_id: str | None

Message 负责控制面；StateVector 负责数据面；SQLite memory ID 负责经验面。三者都有独立的字节、延迟、引用或命中指标，评测结果可以沿着同一条任务链回溯到具体实现。

为什么默认不依赖大模型

运行时协议与后端模型解耦。确定性后端让评审可以在没有 API Key、没有 GPU、没有网络的环境中复现同一条消息链；Ollama 和 OpenAI-compatible 适配器只替换 Agent 的生成后端，不改变协议、状态存储、传输和指标接口。

一键运行

Windows / 普通 PC

$env:PYTHONPATH = "$PWD/src"
python -m os_agent_mesh test
python -m os_agent_mesh demo
python -m os_agent_mesh benchmark --rounds 10 --out results

Linux / openEuler

PYTHONPATH="$PWD/src" python3 -m os_agent_mesh test
PYTHONPATH="$PWD/src" python3 -m os_agent_mesh demo --mmap-state --uds --isolate --real-systemd
PYTHONPATH="$PWD/src" python3 -m os_agent_mesh benchmark --rounds 10 --out results_ipc --mmap-state --uds
./scripts/verify_openeuler.sh

verify_openeuler.sh 会生成新的时间戳证据目录，包含环境指纹、安装日志、编译日志、测试日志、UDS + mmap 演示、10 轮基准、Markdown/JSON/CSV 结果和校验和。

评审入口

评审一页卡：先看问题、创新点、证据和演示路径。
自动生成的证据卡：从 openEuler evidence 读取真实指标。
系统设计：协议、状态、记忆和故障边界。
架构与数据流：控制面、数据面、经验面的映射。
实验协议：三种模式、负载、指标和公平性边界。
openEuler 验收：目标系统部署与复现门禁。
5 分钟演示脚本：按“先现象、再机制、最后证据”组织演示。

代码布局

src/os_agent_mesh/       运行时、协议、Agent、状态、记忆、传输、指标
tests/                    标准库单元测试与跨进程集成测试
scripts/                  Windows/Linux 运行脚本与 openEuler 验收脚本
docs/                     设计、实验、部署、演示说明
evidence/openeuler/       可审查的时间戳验收证据
submission/               初赛交付材料、证据卡与评审入口
tools/                    报告和证据卡生成工具

设计边界

默认后端是确定性的离线后端，保证没有 API Key 时仍可复现；Ollama/OpenAI-compatible 后端是可选适配层。
默认演示使用固定 fixture，确保 Windows 也能完成协议、状态和记忆链路；--real-systemd 只在实际 systemd 主机启用只读采集。
工具执行器不会自动修改 systemd 配置、禁用服务或删除系统文件；优化建议只作为报告输出，执行权留给人工审核。
estimated_tokens = ceil(UTF-8 message bytes / 4) 仅用于相对比较，不冒充特定大模型 tokenizer 的精确结果。

许可证

Apache License 2.0。项目归属、第三方组件和许可证边界见项目归属与许可说明。