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

参赛队伍：AgentOS队

赛题：赛题10：多智能体低开销通信、状态传递与共享记忆机制

项目简介

CoMemBus是面向单机多智能体协作的系统软件基础设施。它使用Unix Domain Socket传递轻量控制消息，用共享内存引用交换日志、附件和float32向量，以TaskState/StatePatch维护版本化任务状态，并通过SharedBlackboard管理具有来源、有效期和替代关系的共享记忆。分层成本策略根据本机profile在固定路径、轻量Fast Gate和完整成本比较之间选择。

应用场景

多角色日志与配置故障诊断。
同机Agent之间的大对象和非文本向量交换。
任务状态增量更新、冲突处理与SQLite恢复。
跨任务经验的有效性过滤、检索和条件复用。
对对象传输、状态表示、精确解析复用和上下文表达进行成本感知选择。

主要功能

通过Unix Domain Socket传递控制消息，并以ObjectRef、SharedEmbeddingRef引用共享内存中的大对象和向量。
通过TaskState、StatePatch实现版本化任务状态、增量更新和冲突处理。
通过SharedBlackboard管理带来源、有效期、替代关系和检索条件的共享记忆。
根据本机校准profile，在固定路径、Fast Gate和完整成本比较之间选择运行机制，并在profile缺失或失配时安全回退。
提供SQLite检查点、恢复流程、Trace记录、五种演示入口和自动化测试脚本。
提供Windows可视化观测台，用于离线查看冻结结果，或通过SSH连接openEuler虚拟机采集演示状态。

三个核心创新

控制面与数据面分离的多智能体对象交换机制。
版本化增量状态与生命周期感知共享记忆机制。
分层成本感知的多机制自适应运行时。

详细的已有工作对照、代码位置和验证依据见 docs/项目创新说明.pdf；总体设计与实验边界见 docs/项目说明书.pdf。

目录说明

README.md
src/                       项目源代码（工程根目录为src/project/）
docs/                      四份项目文档PDF
tests/                     测试入口与冻结验证材料
demo/                      五种演示入口及新运行结果
presentation/              决赛现场演示PPT与视频
作品原创承诺书.pdf           作品原创承诺书

系统环境

团队已由具备相应环境的成员在以下环境完成最终原生验证：

操作系统：openEuler 24.03 LTS-SP3（x86_64）。
Linux内核：6.6.0-132.0.0.111.oe2403sp3.x86_64。
Python：3.11.6。
SQLite：3.42.0。
共享内存：/dev/shm可用。

环境记录位于 tests/validation/final_results/environment.json 和 tests/validation/final_results/logs/environment.log。最新P1-03原生验收包、独立复核结论和冻结源码位于 tests/finals-native/。

依赖要求

需要Bash、Unix Domain Socket、POSIX共享内存（/dev/shm）和Python内置sqlite3模块。
核心运行和自动化测试不需要pip第三方包；src/project/requirements-core.txt用于记录该依赖边界。
默认演示和最终离线测试不需要API Key，也不调用远程模型。
其他Linux发行版或Python版本不属于本轮最终验证范围；如更换环境，应重新执行环境检查、测试和演示。

构建方法

项目为Python源码工程，无本地编译步骤。以下命令均从仓库根目录（包含本README的目录）执行；括号内的命令结束后不会改变当前目录：

(
cd src/project || exit
export PYTHONPATH="$PWD/src:$PWD${PYTHONPATH:+:$PYTHONPATH}"
python3 -m compileall -q src examples tests benchmarks scripts
)

不建议以root权限运行。测试结果写入src/project/results/，normal/recovery演示结果写入demo/results/；运行中还会使用临时目录、SQLite文件及/dev/shm，结束后应检查共享内存残留。

运行方法

bash tests/check_env.sh
bash demo/run_demo.sh minimal
bash demo/run_demo.sh agents
bash demo/run_demo.sh normal
bash demo/run_demo.sh recovery
bash demo/run_demo.sh cost-aware

推荐答辩演示顺序：环境检查 → normal → recovery → cost-aware → 查看输出和Trace。各模式说明见 demo/README.md。

Windows观测台位于 src/project/src/CoMemBus-Windows-Dashboard/。在Windows中双击其中的 Start-Dashboard.cmd 可启动离线展示；连接虚拟机前应按该目录README配置本机连接信息，连接信息和密钥不得提交到仓库。

测试方法

运行完整自动化测试：

bash tests/run_tests.sh

或从仓库根目录直接执行：

(
cd src/project || exit
export PYTHONPATH="$PWD/src:$PWD${PYTHONPATH:+:$PYTHONPATH}"
python3 -m unittest discover -s tests -p 'test_*.py' -v
)

最终原生日志记录439项测试：437项通过、2项跳过、0项失败或错误。五种演示均成功。原始日志、环境、演示报告、360个主任务和30任务冷序列记录位于 tests/validation/final_results/；说明书使用的派生CSV/JSON位于 tests/validation/report_data/；最新P1-03验收归档位于 tests/finals-native/。材料使用方法见 tests/README.md。

主要结果

State-heavy：Fixed均值1.364682 ms，Adaptive均值1.731028 ms；Adaptive在该负载下慢约26.84%。
Tiny 1 KiB：Fixed均值1.132840 ms，Adaptive均值1.113513 ms；差异约1.71%，不作显著提速结论。
Parse-heavy冷序列：1个新进程序列、30个任务；首任务未命中，后29次精确命中。
20任务资源检查：FD为19，记录RSS为69,252 kB，检查点队列和SHM对象数为0；dedup与SQLite随任务增长。

这些结果是明确条件下的组件与机制记录，不代表生产工作负载、完整多Agent应用或所有机器上的普遍性能。

已知限制

当前范围为同机Linux进程，SHM引用不能直接跨机器使用。
完整多角色纯文本/结构化公平对照、两组在线关联任务、不少于十轮完整应用、完整消息与Token/字符指标仍需补充。
Adaptive的收益依赖负载和本机profile；profile缺失或机器身份不匹配时会安全回退。
共享内存仍有写入、映射、校验和清理成本；项目只声称减少部分中间复制，不声称端到端严格零拷贝。
CodeAct为受限执行原型，不构成完整容器、namespace或内核级安全隔离。
可选远程模型入口需要独立配置凭据、隐私和服务许可证；最终离线证据未调用远程模型。