目录
- crates代码提交4个月前
- docs代码提交4个月前
- examples代码提交4个月前
- prompts代码提交4个月前
- scripts代码提交4个月前
- src代码提交4个月前
- tests代码提交4个月前
- 教程教程提交4个月前
- .env.example代码提交4个月前
- Cargo.lock代码提交4个月前
- Cargo.toml代码提交4个月前
- Dockerfile代码提交4个月前
- README.md教程提交4个月前
- docker-compose.embedding.yml代码提交4个月前
- docker-compose.yml代码提交4个月前
- pyproject.toml代码提交4个月前
- uv.lock代码提交4个月前
邀请码
版权所有：中国计算机学会技术支持：开源发展技术委员会
京ICP备13000930号-9
京公网安备 11010802047560号
AgentMesh-Runtime
AgentMesh-Runtime 是一个面向多 Agent 协作的轻量级运行时原型。它的核心目标不是再做一个普通聊天机器人，而是验证一套可落地的协作机制：用结构化协议、状态引用、共享记忆、可选 Rust 热路径和可控工具执行，降低多 Agent 在连续任务中的重复上下文传递成本。
项目根目录是
E:/system-mvp/AgentMesh-Runtime。第一版保持离线可运行，默认不依赖外部模型、GPU、向量数据库、消息队列、LangChain、numpy 或 torch；配置大模型和 TEI embedding 后，可以切换到真实 Agent 互动。面向赛题的直接回答
本项目对应第三届中国研究生操作系统开源创新大赛社区赛题“应用创新-一种面向多智能体协作的低开销通信、状态传递与共享记忆机制”。README 后续内容围绕赛题要求展开：先说明系统如何满足每一项要求，再给出可复现实验和 benchmark 结果。
PlannerAgent、RetrieverAgent、ExecutorAgent、SummarizerAgent，覆盖规划、检索、工具执行和总结。msg_type、action、params、result、capability、state_refs等字段，并支持 HELLO、能力声明、能力查询和协议映射。agentmesh run --mode text是纯文本 baseline；agentmesh run --mode protocol是结构化协议方案；agentmesh compare和benchmark在相同任务条件下运行两套模式。TextState、EmbeddingState、EvidenceState、CodeResultState、SummaryState等 payload 写入文件/SQLite/可选共享内存，Agent 间传递state://...引用，不重复透传完整文本。HashEmbeddingEncoder可离线生成向量；启动 Docker TEI 后可使用BAAI/bge-small-zh-v1.5真实 embedding。向量写成EmbeddingState，由 Retriever 和 MemoryStore 用于语义检索。MemoryUnit包含memory_id、source_agent、created_at、task_topic、summary、tags、state_refs、embedding_ref、reuse_count等元数据；支持关键词、标签、语义相似度检索。continuous_tasks、long_context_tasks、showcase_protocol_advantage三组 suite，覆盖标准连续任务、长上下文链式任务、warm memory reuse 与 cold baseline 对比。核心结论：AgentMesh-Runtime 不是普通多 Agent 聊天应用，而是针对赛题提出的系统层原型。它用 Text Mode 作为传统自然语言协作基线，用 Protocol Mode 验证结构化协议、StateRef、embedding state 和共享记忆能否降低跨 Agent 重复上下文传递成本。
Benchmark 成果中展示 token、wire bytes、agent I/O bytes 降低率；Typed Envelope和StateRef章节解释低开销来源。StateStore 和 StateRef、Embedding、Typed Envelope章节说明非文本状态生成、传递、接收和使用方式。共享记忆章节说明 MemoryUnit、关键词/标签/语义检索；showcase_protocol_advantage验证 warm reuse 与 cold baseline。架构设计、CodeAct 和 Sandbox、Docker 和 openEuler、质量验证章节覆盖运行时、调度、沙箱、部署和测试。Benchmark 成果、Benchmark 和报告章节列出复现实验命令、dashboard、CSV、JSONL、Markdown 报告产物。Benchmark 成果
当前 benchmark 产物位于
runs/latest/benchmarks/，离线展示页为runs/latest/benchmarks/benchmark_dashboard.html。三组 suite 共覆盖 20 轮任务运行，其中continuous_tasks6 轮、long_context_tasks5 轮、showcase_protocol_advantage9 轮。continuous_taskslong_context_tasksshowcase_protocol_advantage结果解读：
state://...引用；benchmark 同时记录protocol_state_payload_bytes、typed envelope 和 payload store 字节数。memory_hit_rate均为 100%，showcase_protocol_advantage专门设计 Phase A 知识构建、Phase B warm reuse、Phase C cold baseline，验证相似任务能命中并复用历史记忆。quality_preservation_rate均为 100%，说明当前离线确定性评估中 Protocol Mode 在降低通信开销的同时没有牺牲结果完整性。复现实验命令：
主要实验产物：
当前实现概览
已经实现的主线能力：
PlannerAgent、RetrieverAgent、ExecutorAgent、SummarizerAgent。TextState、EmbeddingState、EvidenceState、CodeResultState、SummaryState、BlobState，Agent 之间只传state://...引用。HashEmbeddingEncoder离线运行，可选 Hugging Face TEI 服务。SandboxRunner执行，并写入CodeResultState。agentmesh shell、agentmesh chat、agentmesh compare、agentmesh memory、agentmesh trace等。agentmesh_core加速。公平对比边界
为了让评测结果能说明“通信机制”的差异，项目明确区分两套系统：
Text Mode 是传统 baseline。Agent 按固定链路协作，每次 handoff 都传递完整累积文本上下文，不使用 AMP、Typed Envelope、StateRef、Embedding、共享记忆、沙箱或 Rust Core。
Protocol Mode 是 AgentMesh 方案。Agent 通过 AMP 结构化消息协作，payload 落入 StateStore，handoff 中主要传递
state://...引用；运行时可使用 Typed Envelope、共享记忆、CodeAct、动态路由、反馈回合和可选 Rust Core。agentmesh run、agentmesh compare、agentmesh benchmark和 shell/compare、/benchmark默认加载.env中配置的 LLM；需要离线可复现实验时显式传--no-llm。架构设计
整体分层如下：
Protocol Mode 的主流程：
RuntimeContext，加载.env、prompt 模板、路径和 trace id。HELLO、CAPABILITY_ADVERTISE、CAPABILITY_QUERY、PROTOCOL_MAP。TextState，将查询向量写成EmbeddingState。PlannerDecision，决定是否需要检索、工具执行和总结。EvidenceState。CodeResultState。SummaryState。MemoryUnit，按写入策略进入当前 run 记忆和长期记忆。关键机制
AMP 协议
AMPMessage使用 Pydantic schema 校验消息。关键字段包括：trace_id：一次任务链路的追踪 id。source_agent/target_agent：消息发送方和接收方。msg_type：HELLO、CAPABILITY_ADVERTISE、CAPABILITY_QUERY、PROTOCOL_MAP、INVOKE、RESULT、ERROR等。action：能力动作，例如plan.create、memory.semantic_search、tool.run_python、summary.create。params/result：结构化参数和结果。state_refs：跨 Agent 传递的状态引用。capability：能力声明和握手信息。Typed Envelope
Protocol Mode 保留可读的 AMP JSONL 日志，同时额外统计低开销 envelope：
这避免在每条 handoff 中重复传递长字段名、Agent 名、action 名、capability 列表和完整
state://...字符串。Python 会优先调用 Rust Core 编解码；未安装扩展时回退到 Python/msgpack/orjson。StateStore 和 StateRef
StateStore 将大 payload 从消息中剥离，写入
runs/latest/data/states/或共享内存，并用 SQLite 建索引。Agent 之间传递的是引用：Agent 的
handle()会通过StateStore.get(ref)读取引用指向的 payload，并通过StateStore.add_consumer(ref, agent)记录真实消费关系；params只保留 action 控制信息，不再承载完整 task/evidence payload。每条
StateRecord记录 producer、consumer、parent refs、payload 大小、metadata、是否写入记忆等信息，因此可以追踪 lineage。配置AGENTMESH_STATE_PAYLOAD_BACKEND=shm后，大于阈值的 payload 会走 Python shared memory，并统计state_shm_transfer_count和state_shm_transfer_bytes。Embedding
默认离线方案是
HashEmbeddingEncoder：分词后加入 bigram 特征，用 SHA-256 映射到固定维度桶，带符号累加并 L2 归一化。它可复现、零依赖，适合比赛 MVP 和单元测试。可选 TEI 方案通过
AGENTMESH_EMBEDDING_PROVIDER=tei启用，调用/embed接口。TEI 不可用时会自动回退到 HashEmbedding，保证 Protocol Mode 仍可运行。共享记忆
记忆分两层：
runs/latest/data/memory.sqlite，随 run 产物生成。data/agentmesh_memory.sqlite，不会因为清理runs/latest而丢失。RetrieverAgent负责记忆检索：运行时发送memory.semantic_searchaction、query tags 和 query StateRef；RetrieverAgent 读取 StateRef 后调用HybridMemoryStore，并把命中的 MemoryUnit 作为 evidence 返回。HybridMemoryStore会合并两层检索结果并去重。检索方式包括：MemoryUnit.tags。写入策略由
MemoryWritePolicy控制：摘要长度、confidence、validity_score 达标后才写入；长期记忆还要求 importance 和 validity 达标，并过滤 transient/debug_noise。生命周期维护会按年龄、复用次数和 importance 归档低价值记忆。动态路由和反馈
PlannerDecision会根据用户意图和模型输出先归一化出所需 capability，再通过启动时能力声明形成的capability -> agent映射得到执行路线：如果任务不需要工具，Executor 会被跳过；如果需要 CodeAct，执行结果会以结构化 tool feedback 返回，最多触发一轮 Planner 和 Retriever refine。指标中会记录
dynamic_route、selected_agents、skipped_agents、feedback_round_count、planner_refine_count、retriever_refine_count和tool_feedback_count。CodeAct 和 Sandbox
Executor 在确定性模式下生成可复现 Python 校验代码；启用 LLM 后，会要求模型只返回 Python 代码。离线 fallback 只做通用任务校验和指标记录，不内置 quicksort 等样例任务答案；如果任务要求写入文件，默认写出
generated_code.py。SandboxRunner会加一层 Python guard，限制越界文件访问、网络和 subprocess，并支持三种后端：rust：安装 Rust Core 后优先使用 Rust subprocess runner。python：普通 Python subprocess 回退。warm_python_unsafe：可选热 worker，用于实验启动开销，不作为默认安全边界。Sandbox 输出
stdout、stderr、exit_code、latency_ms和 backend 信息，并写入CodeResultState。LLM 和提示词模板
真实可互动 Agent 通过 OpenAI-compatible Chat Completions 接口接入。只要
.env中配置了 base URL、API key 和 model，run、compare、chat、shell /ask和 shell/compare默认会调用模型；需要关闭模型时使用--no-llm。初始提示词模板单独存储在
prompts/：也可以用
AGENTMESH_PROMPT_DIR指向自定义模板目录。模板通过{task}、{query}、{input}、{user_input}等变量渲染；缺失模板时会使用内置 fallback。指标计算方式
核心指标来自
src/agentmesh/eval/metrics.py和src/agentmesh/eval/benchmark.py。单次运行指标
message_count：当前模式写出的消息数量。text_chars：参与 handoff 的文本字符量。estimated_tokens：估算 token 数。当前估算器为mixed_cjk：中文/CJK 字符按0.67token 计，其他字符按1/4token 计，结果至少为 1。text_wire_bytes：Text Mode 完整文本 handoff 的 UTF-8 字节数。protocol_bytes：Protocol Mode 可读 AMP JSONL 消息总字节数。wire_bytes：当前模式用于对比的总 wire bytes。Text Mode 使用text_wire_bytes；Protocol Mode 使用结构化 envelope、transport、状态引用和 payload 统计后的通信字节。structured_handoff_bytes：Protocol Mode 中 handoff 结构化消息的字节量。session_dictionary_bytes：Typed Envelope 会话字典字节量。typed_envelope_bytes：压缩 envelope 字节量。typed_payload_bytes：payload store 字节量。compact_structured_message_bytes：更紧凑结构化消息估算字节量。state_transfer_count：本次 trace 产生和传递的 state 数量。state_transfer_bytes：state payload 总字节量。memory_query_count：记忆检索次数。memory_hit_count：检索返回的 memory unit 数量。memory_query_hit_count：至少命中一条记忆的查询次数。memory_reused_unit_count：被复用并增加 reuse_count 的记忆数量。latency_ms：端到端耗时。stage_latency_ms：各阶段耗时拆分。answer_quality_score：确定性质量估计，空答案为 0，非空答案从 0.6 起，随长度增加到最高 1.0。transport_*：transport 发送次数、字节数、平均延迟、p99 延迟。state_shm_*：shared memory payload 次数和字节数。Benchmark 聚合指标
Benchmark 会对同一任务分别运行 Text Mode 和 Protocol Mode，再按总量计算：
当分母为 0 时，对应 rate 记为 0。
MemoryHitRate会限制在[0, 1]。Benchmark summary 还会汇总 Rust Core 启用次数、Rust sandbox 次数、transport 指标、shared memory 指标和反馈回合指标。快速开始
运行同一个任务的两种模式：
直接输入用户任务并对比两套系统：
离线运行，不调用
.env中配置的模型：单轮聊天：
交互式 Shell
启动：
Shell 中直接输入一段消息，默认等同于
/ask，会走 Protocol Mode 交互式 LLM Agent。需要实验对比时显式使用/compare。常用命令：直接输入文本和
/ask都会把当前问题及 shell 历史写成临时 task，然后调用 Protocol Mode，因此会经过 Planner、Retriever、Executor、Summarizer、AMP、StateRef、Memory 和 trace 链路；运行期间会流式打印每个 Protocol Agent 的输出面板，最后打印最终回答。/compare仍按公平边界同时跑 Text Mode 和 Protocol Mode。/compare和uv run agentmesh compare会并行启动 Text Mode 与 Protocol Mode，并在每个 Agent 完成时流式打印该 Agent 的输出。最终界面顺序为：两种模式的最终回答、两种模式的 Agent 输出明细、最后的指标表。Benchmark 和报告
标准连续任务：
长上下文连续任务：
展示型 A/B/C 任务：
showcase对应examples/benchmarks/showcase_benchmark.yaml，包含 Phase A 知识构建、Phase B warm memory reuse、Phase Ccold_startbaseline。Benchmark 运行时会在终端输出 suite 开始、每条任务的 Text/Protocol 阶段完成、cold_start 记忆重置，以及最终输出文件路径。Benchmark 运行期间会隔离项目级 global memory，只使用当前 benchmark run 内产生的记忆，避免历史长期记忆污染 standard/long/showcase 指标；
cold_start: true任务会在执行前清空本次 run 的记忆库。静态 Benchmark Dashboard
运行以下命令生成完全自包含的离线展示页：
默认输出为
runs/latest/benchmarks/benchmark_dashboard.html。页面自动汇总所有已配置和已生成的 suite，展示汇总指标、Text/Protocol 对比、全部任务明细、完整指标目录和实验报告证据。缺失或损坏的结果会显示为N/A、Not generated或诊断信息，不影响其他结果展示。可通过--output/-o指定其他输出位置。运行后主要产物：
experiment_report.md是 Markdown 格式，结构为：Rust Core
安装 Rust 工具链后，可以启用 PyO3 扩展：
Windows PowerShell 如果存在 Conda 环境变量冲突：
未安装 Rust Core 时，Python 实现会自动接管，功能仍可运行。
文件目录架构注释
下面按当前项目源文件列出每个文件的作用。
runs/、data/、.venv/、target/、缓存目录和.env是本地运行产物或本地密钥，不应提交。质量验证
常用质量门禁：
make all会串联 lint、typecheck、test、benchmark 和 report。文档修改不一定需要重新跑完整测试，但发布前建议至少跑一次。当前边界
run、compare、benchmark和 shell/compare、/benchmark默认使用.env中配置的 LLM；离线复现实验使用--no-llm。