AgentMesh

AgentMesh 是面向多智能体协作的低开销通信、语义状态传递与演化共享记忆 Runtime。项目面向“中国研究生创新实践系列大赛——第三届中国研究生操作系统开源创新大赛暨开放原子大赛操作系统专项赛”赛题 10。

当前仓库已实现 Phase 0、B0（Full-Text）、Phase 2 Runtime Core 的 B0–B4 纵切、B1（Structured）、B2（Adaptive Sparse）、B3（Semantic State）、B4（Evolving Shared Memory）和 Phase 7 deterministic benchmark foundation。B0 保持为冻结基线；可选 Runtime transport 将 B0–B4 的实际 Agent 调用放入独立 UDS worker process；B1 改用结构协议；B2 选择安全稀疏链路；B3 让 mmap 非文本向量参与 routing 和 fixture ranking，并由 worker 依据 opaque ref 实际映射读取；B4 将成功诊断沉淀为可检索、有关联且可演化的共享记忆。当前不包含 B5 KV cache。

当前已实现

Task
  -> Planner
  -> Retriever (offline fixtures only)
  -> Executor
  -> Reviewer
  -> Final answer

• B0 后继 Agent 接收完整自然语言历史；B1 只传 action、parameters、result 和 capability 等结构字段。
• Phase 2 B0–B4 Runtime 使用四个独立 spawn process、Unix Domain Socket、能力注册、超时、有限重试和 worker crash recovery；B2–B4 的 routing/memory control 保持在父进程，只调度选中角色；默认 in-process 模式保持不变。
• B1 使用 MsgPack wire codec、JSON debug view、严格角色输出 schema 和四角色 capability handshake。
• B2 根据 relevance、novelty、confidence、dependency、历史 token/latency cost 和 queue pressure 给候选角色打分。
• B2 保留 mandatory dependency 和低置信完整链 fallback；不会为了降低成本剪掉 Executor/Reviewer。
• B3 使用离线 deterministic hashing vector、float32 mmap store、opaque state ref 和 checksum；它不是神经 embedding 模型。
• B3 process worker 注册 semantic_state_mmap capability，在限定 state root 内校验 task/shape/dtype/nbytes/SHA-256 后 mmap 读取；本机路径不进入消息或 trace。
• B3 分别统计 Agent state transfer 与 Runtime 内部 state access，不把控制消息和向量数据混为一项。
• B4 提供任务内 Working Memory、SQLite Episodic/Long-Term Memory，以及 similar_to/supports 关系。
• B4 只写入 deterministic evaluator 判定成功的 episode；达到阈值的同类 episode 会创建或演化 long-term memory。
• B4 命中时仍强制执行 Executor/Reviewer，只替换可由历史知识覆盖的 Planner/Retriever，并按 B3 counterfactual route 统计实际避免的调用。
• B4 process 模式由父控制器持有临时 SQLite、检索与 consolidation；选中的 Agent 在 worker 内读取 B3 mmap state。数据库路径和 state 路径不进入 task message/trace。
• MockBackend 完全离线、确定性运行；另有可配置的 OpenAI-compatible HTTP backend。
• 每任务自动记录成功状态、端到端/各 Agent 延迟、LLM 调用、输入/输出 token、消息数、序列化通信字节和 trace event。
• Phase 7 统一 suite 包含 8 个 Linux operations 和 6 个 SWE diagnostic tasks、5 组连续序列，并支持 in-process/UDS 重复实验、均值/总体标准差、IPC 指标、CSV/JSON/SVG 与环境 manifest。

详细设计见 B0、Runtime Core、B1、B2、B3、B4、Phase 7 benchmark 和 openEuler validation，代码真实状态见 decision log。

环境与安装

当前开发基线是 Python 3.11。Runtime 依赖只有 PyYAML 和 MsgPack；测试额外依赖 pytest。请使用已有的 agentmesh Conda 环境，不需要创建新环境：

conda activate agentmesh
python --version
python -m pip install -e ".[dev]"

代码不依赖 WSL 或 Windows 路径，目标是在普通 Linux 和 openEuler 24.03-LTS-SP3 上以同样命令安装和测试。

Linux/openEuler portability preflight

安装后可以无网络、无特权地验证 AgentMesh 所需的 Linux 原语：

agentmesh-portability --output results/portability/preflight.json

该命令检查 Python/依赖/配置、临时文件系统、AF_UNIX 0600 ping-pong、mmap、SQLite CRUD 和 multiprocessing spawn。在 openEuler 24.03-LTS-SP3 实机验收时使用严格发行版 gate：

agentmesh-portability \
  --require-openeuler \
  --output results/openeuler_validation/preflight.json

./scripts/validate_openeuler.sh

一键脚本在 preflight 后继续执行 pip check、全量 pytest、B4 UDS smoke 和三轮 Phase 7 UDS。它不安装依赖、不联网、不提权。WSL/Ubuntu 可以通过通用 Linux prerequisites，但 Target openEuler validated 必须为 False；这不等于 openEuler 实机验收。

运行离线 benchmark 与消融

从仓库根目录执行：

python -m benchmarks.run_benchmark --mode text --suite smoke
python -m benchmarks.run_benchmark --mode structured --suite smoke
python -m benchmarks.run_benchmark --mode adaptive --suite smoke
python -m benchmarks.run_benchmark --mode semantic --suite smoke
python -m benchmarks.run_benchmark --mode semantic --suite routing_smoke
python -m benchmarks.run_benchmark --mode memory --suite memory_smoke
python -m benchmarks.run_benchmark --mode text --transport uds_process --suite smoke
python -m benchmarks.run_benchmark --mode structured --transport uds_process --suite smoke
python -m benchmarks.run_benchmark --mode adaptive --transport uds_process --suite smoke
python -m benchmarks.run_benchmark --mode semantic --transport uds_process --suite smoke
python -m benchmarks.run_benchmark --mode memory --transport uds_process --suite memory_smoke
python -m benchmarks.run_ablation --suite smoke
python -m benchmarks.run_b2_ablation --suite smoke
python -m benchmarks.run_b3_ablation --suite smoke
python -m benchmarks.run_b4_ablation --suite memory_smoke
python -m benchmarks.run_phase7 --suite phase7 --repetitions 3 --backend mock
python -m benchmarks.run_phase7 --suite phase7 --repetitions 3 --backend mock --transport uds_process
python -m benchmarks.run_runtime_ablation --suite smoke --backend mock
python -m benchmarks.run_runtime_ablation --mode structured --suite smoke --backend mock --results-root results/runtime_ablation_b1
python -m benchmarks.run_runtime_ablation --mode adaptive --suite smoke --backend mock --results-root results/runtime_ablation_b2
python -m benchmarks.run_runtime_ablation --mode semantic --suite smoke --backend mock --results-root results/runtime_ablation_b3
python -m benchmarks.run_runtime_ablation --mode memory --suite memory_smoke --backend mock --results-root results/runtime_ablation_b4

默认配置为 configs/default.yaml，默认 backend 是 mock。Mock 模式不读取 API key、不加载模型，也不发起网络请求。运行结果写入：

results/
├── b0_text/
│   ├── summary.json
│   ├── tasks.jsonl
│   └── traces/<task_id>.jsonl
├── b1_structured/
│   ├── summary.json
│   ├── tasks.jsonl
│   └── traces/{setup,<task_id>}.jsonl
├── b2_adaptive/
│   ├── summary.json
│   ├── tasks.jsonl
│   └── traces/{setup,<task_id>}.jsonl
├── b3_semantic/
│   ├── summary.json
│   ├── tasks.jsonl
│   └── traces/{setup,<task_id>}.jsonl
├── b4_memory/
│   ├── summary.json
│   ├── tasks.jsonl
│   ├── memory_snapshot.json
│   └── traces/{setup,<task_id>}.jsonl
├── ablation_b0_b1/comparison.json
├── ablation_b0_b1_b2/comparison.json
├── ablation_b0_b1_b2_b3/comparison.json
├── ablation_b0_b1_b2_b3_b4/comparison.json
├── runtime_ablation/{in_process,uds_process,comparison.json}
├── runtime_ablation_b1/{in_process,uds_process,comparison.json}
├── runtime_ablation_b2/{in_process,uds_process,comparison.json}
├── runtime_ablation_b3/{in_process,uds_process,comparison.json}
├── runtime_ablation_b4/{in_process,uds_process,comparison.json}
├── phase7/
    ├── manifest.json
    ├── aggregate.json
    ├── runs.csv
    ├── comparison.svg
    └── runs/run-NNN/{b0_text,...,b4_memory}/
├── phase7_uds_process/
    ├── manifest.json
    ├── aggregate.json
    ├── runs.csv
    └── runs/run-NNN/{b0_text,...,b4_memory}/
└── portability/preflight.json

临时运行结果默认由 Git 忽略；未来经过复核的正式实验结果可放入 results/official/ 单独提交。

Mock token 数是无 tokenizer 条件下的确定性估算，trace 中标记为 deterministic_estimate；OpenAI-compatible backend 使用服务端返回的 usage。Mock benchmark 的成功率验证 pipeline、证据传播和评估规则，不代表真实模型诊断准确率。

当前 Runtime Core checkpoint

uds_process transport 为 Planner、Retriever、Executor、Reviewer 启动四个独立 worker。每个 worker 同时注册 B0 full-text 与 B1 structured capability。父进程通过 versioned length-prefixed MsgPack/UDS 请求进行 capability handshake 和调用，只对 transport failure 做有限重试并重建 worker。

在最初的 B0-only Runtime checkpoint（源码 4d3594d）中，in-process 与 UDS process 都是 5/5、20 calls、8,254 tokens、20 logical messages 和 27,289 logical bytes。UDS 路径实际产生 20 次 task exchanges / 52,437 B，另有 8 条 setup messages / 1,024 B；本机单轮平均 task latency 为 0.374 ms vs 1.358 ms。详见 Runtime ablation。当前双能力 descriptor 使 worker setup 增为 1,094 B，但不改变 B0 task semantics 或 task IPC bytes。

B1 的进程内/UDS 路径同样保持 5/5、20 calls、10,602 tokens、20 logical messages、19,609 logical bytes，以及 8 条/2,626 B 的 B1 协议握手。UDS 任务流量为 20 次交换/57,289 B；Runtime worker 握手另计 8 条/1,094 B。详见 B1 Runtime ablation。两份报告均为单轮 Mock 机制检查，不能作为正式性能结论。

B2 smoke 的进程内/UDS 路径均为 5/5、15 calls、9,176 tokens、15 logical messages 和 16,085 logical bytes；5 次 Planner 剪枝及 15/25 active edges 逐任务一致。UDS 只产生 15 次 task exchanges / 48,807 B，证明剪枝发生在 worker dispatch 之前。详见 B2 Runtime ablation。

B3 smoke 的进程内/UDS 路径均为 5/5、15 calls、9,176 tokens、15 logical messages、19,553 logical bytes，以及 15 次 Agent state read / 3,840 B。每个选中 worker 在调用 Agent 前实际 mmap 并验证同一个 opaque state ref；UDS 任务流量为 15 次交换/54,165 B。详见 B3 Runtime ablation。

B4 memory_smoke 的进程内/UDS 路径均为 4/4、11 calls、11,511 tokens、11 logical messages、21,519 logical bytes、2 次 effective reuse 和 3 次 avoided calls；两侧规范化 memory snapshot 也完全一致。UDS 路径执行 11 次 task exchange / 64,687 B。详见 B4 Runtime ablation。

当前 B0–B4 Agent 执行均已进入 process Runtime；B4 memory control 仍位于父进程，不是独立服务。受限 sandbox 可能禁止 AF_UNIX bind，此时九项集成测试会 skip；在普通 Linux 权限下完整测试为 69 passed。所有 Runtime checkpoint 都是 Mock 机制检查，不能作为正式性能结论。

运行测试

python -m pytest
python -m pip check

测试不访问网络，覆盖 backend、五类 pipeline、UDS framing、worker/registry/scheduler/recovery、MsgPack、Router/fallback、hashing encoder、mmap lifecycle/checksum、分层记忆、关联与 consolidation、统一 Metrics、evaluator 和 B0–B4 对照。

OpenAI-compatible 模式（可选）

不要把 key 写进 YAML 或代码。通过环境变量配置 endpoint、model 和 key：

export AGENTMESH_LLM_API_KEY="..."
export AGENTMESH_LLM_BASE_URL="https://example.invalid/v1"
export AGENTMESH_LLM_MODEL="your-model"
python -m benchmarks.run_benchmark --mode text --suite smoke --backend openai-compatible

.env.example 只列变量名；.env 已被 Git 忽略。AgentMesh 本身不会隐式加载 .env，需要由 shell 或用户自己的环境管理工具导出变量。

当前 B1 smoke 结论

同一 Mock smoke suite 中，B0/B1 都是 5/5、20 次 LLM 调用和 20 条任务消息。B1 任务内通信字节减少 28.14%，计入一次 8-message capability handshake 后减少 18.52%；但 Mock 估算 token 增加 28.45%。这说明小 payload 上结构 schema 有固定 token 成本，当前不能宣称 B1 同时降低 token。详见 B0 vs B1 smoke report。

当前 B2 smoke 结论

B2 在 5 个简单诊断 case 中均剪掉 Planner，保持 5/5 success，并将 calls/messages 从 20 降至 15。相对 B1，Mock token 减少 13.45%，任务通信 bytes 减少 17.97%；相对 B0，任务 bytes 减少 41.06%，但 Mock token 仍高 11.17%。当前 suite 缺少必须激活 Planner 的复杂正式 case，因此这只是机制 smoke，不是 Router 泛化能力结论。详见 B0/B1/B2 smoke report。

routing_smoke 另含一个多服务依赖 case：简单 case 剪掉 Planner，复杂 case 激活完整链，两题均通过 evaluator。

当前 B3 smoke 结论

B3 保持 5/5、15 calls/messages 和 9,176 Mock token，产生 15 次 Agent state transfer（3,840 bytes）与 15 次 Runtime state access（3,840 bytes）。相对 B2，opaque ref 使 control bytes 增加 21.56%，计入 Agent 向量后 task data movement 增加 45.43%；相对 B0 总 task movement 仍减少 14.28%。因此当前只主张非文本状态“真实参与决策并可观测”，不主张 B3 在小任务上降低总数据量。详见 B0–B3 smoke report。

当前 B4 continuous-task smoke 结论

memory_smoke 按顺序运行 CPU 首次/复发和 Redis 依赖首次/复发两组任务。B4 保持 4/4 success，产生 2/4 memory-hit tasks 和 2 次 effective reuse；相对同套件 B3，calls/messages 从 14 降至 11，Mock token 从 12,286 降至 11,511，task data movement 从 27,022 B 降至 24,335 B。4 个成功 episode 进一步形成 2 个 long-term unit，共产生 6 个关系 link。详见 B0–B4 continuous-task report。

该结果只证明确定性连续任务中的机制和测量闭环。默认 benchmark 使用临时 SQLite 数据库，以确保每次运行从空记忆开始；运行结束前导出 memory_snapshot.json。它不代表真实 embedding 的检索质量或长期线上效果。

当前 Phase 7 repeated checkpoint

phase7 suite 包含 14 题（Linux 8 + SWE diagnostics 6）和 5 组首次→复发序列。基于干净提交 d46dcd5 的 3 次 Mock 重复实验中，B0–B4 每轮均为 14/14；B4 相对 B3 将 calls 从 44 降到 38、Mock tokens 从 30,809 降到 29,339、task data movement 从 76,153 B 降到 71,111 B。B4 每轮有 5/14 hit tasks、5 次 effective reuse 和 6 次 avoided calls。

当前 SWE case 只做基于源码、失败测试和预制 pytest 输出的故障定位，不会自动应用 patch；B4 本机 Mock latency 也显著高于 B3。详见 Phase 7 repeated report。

基于干净提交 92f8149 的配对 3 轮实验进一步验证了 UDS transport：B0–B4 的 success/calls/tokens/logical bytes 与 in-process 完全一致，所有 Mock 确定性指标总体标准差为 0，三轮共 714 次 task IPC exchange，retry/restart 均为 0。B4 相对 B3 的 calls 减少 13.64%，但实际 task IPC bytes 只减少 1.10%，说明 transport envelope/response 固定成本必须单独报告。详见 Phase 7 UDS repeated report。

Planned（尚未实现）

• B5：KV Fast Lane（高风险可选增强）

本阶段仍未实现独立常驻 daemon、并发 scheduler、独立 state/memory service、cgroup、向量数据库、Web UI 或容器编排。长期方案与阶段路线见 development plan 和 docs/context/ 中的设计基线。