面向 openEuler 的多智能体低开销通信、状态传递与共享记忆系统

本项目是第三届中国研究生操作系统开源创新大赛 赛题 10：多智能体协作通信与记忆机制 的完整实现，位于本仓库根目录下。

完整文档与实验入口见文档导航。

1. 核心目标

针对当前多智能体系统存在的“高 Token 开销、状态重复传输、协作记忆难以复用、代码执行不安全”等问题，构建一个支持以下特性的多 Agent 协作框架：

SCP 结构化通信协议：基于消息类型的轻量级总线，支持进程内 Queue、Unix Domain Socket 与 Protobuf + gRPC 三种后端；能力发现参考 Google A2A / Anthropic MCP。
非文本状态引用传递：通过 POSIX 共享内存 / mmap 存放 embedding、检索得分等结构化张量，Agent 消息只携带带 HMAC 的 StateRef；当前写入和读取各有一次内存拷贝。
混合共享记忆：SQLite + FTS5 关键词检索 + 向量语义检索（可选 FAISS）+ 记忆图关系，支持跨任务复用。
带标准答案的连续任务基准：由 MuSiQue decomposition 构造 T1→T2 任务对；T2 移除第一跳支持段落，通过独立 workspace 验证记忆对最终 EM/F1 的真实贡献。
CodeAct 安全沙箱：子进程 + 资源限制 + 模块白名单执行 LLM 生成的 Python 代码；当前安全边界不等同于容器隔离。
结构化 vs 纯文本双模式评测：收集延迟、消息数、文本字符数、状态传输量、记忆命中率等指标并可视化。
非文本状态驱动证据选择：Retriever 通过共享内存传递逐证据 embedding 矩阵，Planner 执行余弦 Top-K，Summarizer 只消费被选证据；选择索引、分数和失败原因均可审计。

2. 系统架构

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Planner   │────▶│  Retriever  │────▶│  Executor   │────▶│ Summarizer  │
│  规划/协调   │     │ 检索/证据收集 │     │ CodeAct 执行 │     │  总结/沉淀   │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │                   │
       └───────────────────┴───────────────────┴───────────────────┘
                           │  MessageBus (SCP)
       ┌───────────────────┴───────────────────┐
       ▼                                       ▼
┌─────────────────────┐             ┌─────────────────────┐
│  HybridMemoryStore  │             │ SharedMemoryManager │
│  SQLite + 向量 + 图  │             │ POSIX SHM / mmap    │
└─────────────────────┘             └─────────────────────┘

3. 目录结构

├── .env                  # API Key 与运行时配置（不提交到 git）
├── .env.example          # 配置模板
├── requirements.txt      # Python 依赖（最小约束）
├── requirements-lock.txt # 依赖锁定（pip freeze，可精确复现实验环境）
├── README.md             # 本文件
├── docs/                 # 技术文档、复现指南与演示材料
│   ├── 技术方案与技术报告.md
│   └── 多智能体通信与记忆机制综述.md
├── reports/              # 实验结果、显著性检验与错误分析
├── scripts/
│   ├── deploy.sh                      # 一键部署/运行脚本
│   ├── build_hotpotqa_tasks.py        # 构造 HotpotQA 任务 JSON
│   ├── build_multihop_tasks.py        # 构造 2WikiMultiHopQA / MuSiQue 任务 JSON
│   ├── benchmark_chinese.py           # 中文百科 QA 评测
│   ├── run_benchmark_suite.py         # 多数据集一键 benchmark 套件
│   ├── summarize_experiments.py       # 汇总 reports/ 下所有实验到 Markdown
│   ├── analyze_errors.py              # 三模式错误分类与重叠热力图
│   ├── significance_test.py           # McNemar + bootstrap 统计显著性检验
│   ├── visualize_memory_graph.py      # 记忆图可视化
│   ├── ab_memory_experiment.py        # 记忆复用 A/B 实验
│   ├── ablation_experiment.py         # 记忆/反馈/通信模式消融实验
│   ├── baseline_autogen.py            # AutoGen 横向 baseline
│   ├── baseline_crewai.py             # CrewAI 横向 baseline
│   ├── baseline_langgraph_codeact.py  # LangGraph ReAct/CodeAct 横向 baseline
│   └── install_embedding.sh           # 本地 embedding 模型安装
├── deploy/                            # openEuler 24.03 系统服务部署
├── src/
│   ├── agents/           # Planner / Retriever / Executor / Summarizer
│   ├── protocol/         # SCP 消息与总线
│   ├── memory/           # 混合记忆存储
│   ├── state_exchange/   # 共享内存状态传递
│   ├── sandbox/          # CodeAct 沙箱
│   ├── evaluation/       # 评测指标与报告
│   ├── utils/            # LLM 客户端与 embedding 兜底
│   ├── config.py         # 全局配置
│   ├── workflow.py       # 任务编排
│   └── main.py           # CLI 入口
├── tasks/                # 任务定义 JSON
└── tests/                # 单元测试

4. 快速开始

4.1 环境准备

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
# 或精确复现实验环境（含传递依赖锁定）：
# pip install -r requirements-lock.txt

如需本地 embedding 模型，可取消注释 requirements.txt 中的 sentence-transformers、faiss-cpu、torch 并重新安装。系统默认支持 DeepSeek/OpenAI 兼容 API 或伪 embedding 兜底。

4.2 配置 API Key

复制模板并填写：

cp .env.example .env
# 编辑 .env，将 LLM_API_KEY 替换为你的真实 key

.env 已加入 .gitignore。真实 API Key 只保存在本地运行环境，不得提交到仓库。

4.3 配置 Embedding（可选）

当前开发环境（.venv）已安装 sentence-transformers，主实验默认使用本地 all-MiniLM-L6-v2 真实 embedding。若在未安装该依赖的环境中运行，系统会自动回退到伪 embedding（PseudoEmbedding），仅保证流程可运行、不保证语义检索质量。如需显式选择 embedding 后端，可使用以下方式之一：

方式 A：远程 Embedding API 在 .env 中配置：

EMBEDDING_BASE_URL=https://api.openai.com/v1
EMBEDDING_API_KEY=sk-...
EMBEDDING_MODEL=text-embedding-3-small

方式 B：本地 sentence-transformers 确保能访问 HuggingFace（或镜像站），然后执行：

bash scripts/install_embedding.sh

默认下载 sentence-transformers/all-MiniLM-L6-v2（384 维，约 80 MB）。

当前开发环境若无法访问 HuggingFace，系统会自动回退到伪 embedding，不影响主流程。

4.4 运行演示

# 结构化模式单任务演示
python3 -m src.main --mode structured --tasks tasks/demo.json --rounds 1

# 纯文本模式
python3 -m src.main --mode text --tasks tasks/demo.json --rounds 1

# 双模式对比评测（推荐）
python3 -m src.main --mode both --tasks tasks/group_a.json --rounds 1

# 三模式对比（structured + text + direct_qa）
python3 -m src.main --mode all --tasks tasks/hotpotqa_10.json

# 三模式对比 + 断点续跑（网络中断后可恢复已完成的模式）
python3 -m src.main --mode all --tasks tasks/musique_20.json --output reports/musique_deepseek_20_all --resume

# 新增基线：直接 LLM 不检索
python3 -m src.main --mode no_retrieval_qa --tasks tasks/hotpotqa_10.json --output reports/no_retrieval_qa

# 新增基线：CodeAct 单 Agent
python3 -m src.main --mode codeact_qa --tasks tasks/hotpotqa_10.json --output reports/codeact_qa

# 消融实验：无记忆 / 有记忆无反馈 / 有记忆有反馈 / text 模式
python3 scripts/ablation_experiment.py --tasks tasks/hotpotqa_10.json --output reports/ablation

# 使用 Unix Domain Socket 总线（跨进程）
SCP_USE_UNIX_SOCKET=1 python3 -m src.main --mode both --tasks tasks/hotpotqa_10.json

# 使用 gRPC + Protobuf 总线（跨机/跨语言部署）
SCP_BUS_TYPE=grpc python3 -m src.main --mode both --tasks tasks/hotpotqa_10.json

# 中文任务评测（默认英文 embedding）
python3 scripts/benchmark_chinese.py

# 中文任务评测（使用多语言 embedding，需先安装）
EMBEDDING_LOCAL_MODEL=sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 \
    python3 scripts/benchmark_chinese.py

# 一键汇总所有实验结果到 Markdown 表格
python3 scripts/summarize_experiments.py

# 一键运行多数据集 benchmark 套件（默认 HotpotQA/MuSiQue/2WikiMultiHopQA 各 100 样本）
python3 scripts/run_benchmark_suite.py

# 只跑指定数据集与样本数
python3 scripts/run_benchmark_suite.py --datasets musique 2wikimultihopqa --size 20

运行后会在 reports/ 目录生成：

comparison_report.json：完整对比报告
comparison_chart.png：可视化对比图

4.5 运行测试

# 默认快速测试（跳过需要真实 LLM / 慢速集成的测试）
LLM_API_KEY=mock python3 -m pytest

# 完整质量门禁：compileall、Ruff、mypy、Bandit、证据校验、测试与覆盖率
bash scripts/quality_gate.sh

# 完整测试（含真实 LLM 集成测试，需配置 API Key）
LLM_API_KEY=sk-... python3 -m pytest -m "slow" -v

# 单独跑慢测试
python3 -m pytest -m "slow or not slow" -q

4.6 部署为 openEuler 24.03 系统服务

sudo bash deploy/install.sh

脚本会自动创建 systemd service/timer，将项目安装到 /opt/yzmxdzntxzddkxtxztcdygxjyjz，并创建独立运行用户 agentwf。详细说明与卸载方法见 deploy/README.md。

5. 配置说明

.env 关键项：

变量	说明	示例
`LLM_BASE_URL`	大模型 API 基础地址	`https://api.deepseek.com/v1`
`LLM_API_KEY`	API Key	`sk-...`
`LLM_MODEL`	模型名	`deepseek-v4-pro`
`EMBEDDING_BASE_URL`	Embedding API（可选）	留空则使用本地/伪 embedding
`EMBEDDING_MODEL`	Embedding 模型名	`text-embedding-3-small`
`SANDBOX_TIMEOUT`	沙箱超时（秒）	`30`
`SANDBOX_MAX_MEMORY_MB`	沙箱内存限制（MB）	`512`

当 LLM_API_KEY 为空或 mock 时，系统自动使用 MockLLMClient，用于离线验证流程。

6. 任务定义格式

tasks/*.json 示例：

{
  "name": "group_a_tech_research",
  "description": "技术调研报告生成",
  "tasks": [
    {
      "topic": "openEuler 内核特性调研",
      "query": "调研 openEuler 操作系统的内核特性，并生成一份简洁的中文摘要。",
      "tags": ["openEuler", "kernel"],
      "workspace": "group_a",
      "use_memory": false
    },
    {
      "topic": "openEuler 服务器场景优势分析",
      "query": "基于之前对 openEuler 内核特性的调研，撰写优势分析。",
      "tags": ["openEuler", "server"],
      "workspace": "group_a",
      "use_memory": true,
      "strategy": "复用前序任务的摘要向量和证据记忆。"
    }
  ]
}

7. 关键实现与参考

7.1 参考论文（精华提炼）

论文/项目	核心思想	在本项目中的体现
AutoGen (Microsoft)	Conversable Agent + Group Chat	Agent 角色分工与消息总线
CAMEL	Role-playing + Inception Prompting	Planner 的 task 分解与 agent 指派
CrewAI	Task → Agent → Tool 编排	`tasks/*.json` 任务配置
CodeAct	LLM 生成可执行代码作为动作	`src/sandbox/executor.py`
MemGPT	分层记忆与上下文管理	`src/memory/store.py` 混合记忆
ChromaDB	向量记忆存储	向量索引与检索接口设计参考
Google A2A Protocol	Agent 能力发现与跨平台协作	`protocol/bus.py` 能力广播/发现
Anthropic MCP	Model Context Protocol	结构化消息与状态引用设计
AAFLOW+ / KVComm	分布式状态与 KV Cache 编排	`state_exchange/manager.py` 的共享内存 `StateRef` 受其选择性状态共享思想启发；本项目未实现 KV Cache 共享
E-mem / MRAgent / MemGraphRAG	episodic 记忆与图关系	记忆图关系 `memory_graph` 表

完整研究背景、论文引用与设计取舍见 多智能体通信与记忆机制综述.md 和 技术方案与技术报告.md。

7.2 参考开源代码

以下开源项目与协议在本地开发时作为设计参考（未包含在本仓库中，可另行 clone）：

仓库	主要参考点	在本项目中的体现
`autogen`	Conversable Agent、Group Chat、工具调用模式	`MessageBus` + `SCPMessage` 消息总线
`camel`	Role-playing、Inception Prompting、数据生成	`PlannerAgent` 任务分解与角色指派
`crewAI`	Task → Agent → Tool 编排、任务队列	`tasks/*.json` 配置与 `workflow.py` 编排
`code-act`	CodeAct 数据集与执行流程	`sandbox/executor.py` CodeAct 沙箱
`chroma`	向量数据库接口与索引设计	`memory/store.py` 向量检索接口（可选 FAISS/SQLite 实现）
`A2A` / `specification`	Agent 能力发现、跨平台消息格式	`protocol/bus.py` 能力广播/发现接口，当前为静态能力表
`KVComm` / `AAFLOW`	分布式 KV Cache、状态共享	`state_exchange/manager.py` 实现 POSIX 共享内存 `StateRef`；已验证同机跨进程读取，未实现 KV-cache
`E-mem` / `MRAgent` / `MemGraphRAG`	情节记忆、记忆图关系、上下文重建	`memory_graph` 表与证据链保留
`Mandol` / `hylat` / `MOC` / `PACT`	语义通信、动作-状态压缩、潜态传输	`StateRef` 引用传递与结构化消息设计

8. 实验结果

8.0 评测口径与可复现性声明

主实验采用以下统一口径：

关闭 ground-truth 记忆反馈：src/workflow.py 新增 enable_memory_feedback=False 默认参数，评测入口（--mode structured/text/all）不会用标准答案调整记忆置信度；--enable-memory-feedback 仅用于在线学习/消融实验。
临时记忆数据库：MultiAgentWorkflow 默认使用安全临时目录创建独立 SQLite，避免跨任务、跨运行污染；需要持久记忆时通过 --memory-db-path 显式指定。
记忆召回阈值：MEMORY_MIN_RELEVANCE 默认值从 0.0 提升至 0.3，hit_rate 仅统计真正相关的记忆召回。
文本截断统一：EVIDENCE_TEXT_MAX_CHARS=1200 用于传入 LLM 的证据正文，RETRIEVAL_EMBED_MAX_CHARS=512 用于 embedding 排序，避免不同模式输入上下文差异。
开销指标：主报告以 总 token 数（prompt_tokens + completion_tokens，由 LLM API usage 精确返回）作为可验证的开销指标；估算金额（元）仅按默认单价换算，用于横向相对比较，不等同于真实账单。
FAISS 默认开启：USE_FAISS=1（环境变量）控制向量索引后端，未安装时自动回退 numpy 暴力搜索。
新增基线：--mode no_retrieval_qa（直接 LLM 不检索）、--mode codeact_qa（代码执行增强单 Agent）。
新增消融脚本：scripts/ablation_experiment.py 一次运行可产出“无记忆 / 有记忆无反馈 / 有记忆有反馈 / text 模式”四条件对比。

HotpotQA 100 主实验采用上述口径，结果见 reports/hotpotqa_100_v3/（显式临时 memory.db，避免跨任务污染）。 2WikiMultiHopQA / MuSiQue 100 样本结果见 reports/2wikimultihopqa_deepseek_100_all_v2/ 与 reports/musique_deepseek_100_all_v2/，同样采用临时 memory.db 口径。

8.1 多跳 QA 公开数据集

评测使用以下公开数据集，均从 reference_repos/MemGraphRAG/dataset/ 抽取并统一格式化为 tasks/*.json：

数据集	样本文件	样本数	来源说明
HotpotQA	`tasks/hotpotqa_100.json`	100	HotpotQA distractor 训练集前 100 条
2WikiMultiHopQA	`tasks/2wikimultihopqa_20.json`	20	2WikiMultiHopQA 验证集前 20 条
2WikiMultiHopQA	`tasks/2wikimultihopqa_100.json`	100	2WikiMultiHopQA 验证集前 100 条
MuSiQue	`tasks/musique_20.json`	20	MuSiQue 验证集前 20 条
MuSiQue	`tasks/musique_100.json`	100	MuSiQue 验证集前 100 条

采样说明：上表任务文件均为 head 采样（取前 N 条）。scripts/build_multihop_tasks.py 另支持 --strategy random|stratified（默认 seed=42，可复现）。head-100 与全集（各 1000 条）的题型分布偏差较小（HotpotQA bridge 占比 83% vs 全集 81.1%；MuSiQue 4hop1 占比 16% vs 全集 10.8%），但 head 采样仍可能引入轻微选择偏差。为验证该偏差是否影响核心结论，额外生成分层采样任务文件并跑三模式对比，结果见下表。

HotpotQA 结果

样本数	模式	EM	F1	ROUGE-L	平均延迟(s)	平均文本字符	总 token 数	备注
100	structured	0.52	0.637	0.634	22.5	1870	265597	独立临时 memory.db
100	text	0.53	0.656	0.654	24.6	9884	252120	独立临时 memory.db
100	direct_qa	0.27	0.404	0.400	4.7	2995	98345	无 Agent 基线
100	codeact_qa	0.38	0.510	0.501	21.5	887	157372	代码执行增强单 Agent
100	no_retrieval_qa	0.18	0.351	0.346	10.6	198	62864	直接 LLM，无检索

数据来源：reports/hotpotqa_100_v3/three_way_comparison_report.json、reports/codeact_qa_hotpotqa_100/report_codeact_qa.json、reports/no_retrieval_qa_hotpotqa_100/report_no_retrieval_qa.json。

说明：在真实 deepseek-v4-pro + 本地 all-MiniLM-L6-v2 embedding 下完成；默认关闭 ground-truth 记忆反馈，每轮显式临时 memory.db，召回阈值 0.3。总 token 数 由 LLM API usage 精确返回，是主开销指标；对应估算金额约为 structured 0.1544 元 / text 0.1443 元 / direct_qa 0.0549 元（按 deepseek-v4-pro 近似价）。

结果说明：

structured 与 text 的准确率差异很小（EM 0.52 vs 0.53），统计上不显著（McNemar p=1.0，F1 95% CI [-0.089, +0.051]），见 reports/significance/hotpotqa_100_v3_with_baselines.md。

structured 的已验证收益是 Agent 间应用层文本字段缩短：平均文本字符 1870 vs 9884，约为 text 的 **18.9%**；总 token 数 265597 vs 252120，structured 反而高约 5.3%。历史报告未记录完整协议编码字节，不能由该字符指标直接推出总通信量下降；新实验将同时记录协议编码和共享状态字节。

在当前任务、检索器与提示配置下，两种 Agent 模式均显著优于 direct_qa 基线（structured vs direct_qa：EM p<0.001，F1 +0.233 [+0.138, +0.331]）；该对比支持显式分解协作链路的有效性，但不外推为对所有单 Agent 方案的普遍优势。

codeact_qa（EM 0.38）优于 no_retrieval_qa（EM 0.18），但仍远低于 structured/text，说明在 HotpotQA 这类依赖外部知识的任务上，代码执行本身无法替代检索；当前沙箱未向 LLM 开放网络检索工具，若补充 search/retrieve 工具后结果可能提升。

no_retrieval_qa（EM 0.18）与 direct_qa（EM 0.27）相比，direct_qa 因带检索而略高，说明单跳无检索问答上限有限。

记忆命中率在临时 DB 口径下为 0，符合 HotpotQA 100 题主题独立、跨题记忆复用空间有限的预期；记忆复用结果见 8.5 和 8.6 节。

指标口径说明：平均文本字符 只度量 Agent 消息中应用层文本 payload 的字符数，不是完整序列化消息，也不是 LLM API 计费 token。serialized_message_bytes 记录总线实际生成的 JSON UTF-8 或 Protobuf 字节；total_communication_bytes 再加上共享状态字节。历史结果没有后两个字段，须重新运行后才能据此宣称总通信压缩。

HotpotQA 分层采样验证（stratified-100）

为检验 head-100 采样是否引入选择偏差，使用 --strategy stratified 生成 tasks/hotpotqa_100_stratified.json 并跑三模式对比：

样本数	模式	EM	F1	ROUGE-L	平均延迟(s)	平均文本字符	总 token 数
100	structured	0.56	0.678	0.678	23.4	1855	238494
100	text	0.64	0.770	0.770	21.6	9540	234231
100	direct_qa	0.22	0.350	0.350	5.4	2832	99239

数据来源：reports/hotpotqa_100_stratified/three_way_comparison_report.json。完整显著性检验见 reports/significance/hotpotqa_100_stratified.md。

分层采样关键结论：

structured vs direct_qa 仍高度显著（p<0.001），text vs direct_qa 也高度显著；在当前 direct_qa 实现下，显式分解协作链路的优势对采样方式稳健。
structured vs text 在 stratified 下 F1 差异显著（text 更高，CI [-0.157, -0.033]），EM 边缘显著（p=0.057）。这与 head-100（structured vs text 不显著）存在差异，说明 head 采样可能轻微低估了 text 模式的表现。
head-100 与 stratified-100 在 structured 模式上差异不显著（McNemar p=0.67），在 direct_qa 上亦不显著（p=0.49），因此主实验对 structured/direct_qa 的数字与结论是稳健的。
综合 head 与 stratified 两个 100 样本结果，structured 与 text 的准确率结论依赖采样（stratified 下 text 的 F1 显著更高）；structured 的稳定收益是 Agent 消息中应用层文本字段更短。历史主实验没有完整协议字节，不能据此宣称总通信量更低。

HotpotQA 消融实验（4 条件）

使用 scripts/ablation_experiment.py 在 HotpotQA 100 上隔离记忆复用、ground-truth 反馈与通信模式的影响：

条件	记忆复用	反馈	EM	F1	Rouge-L	平均延迟(s)	平均文本字符	总 token 数	记忆命中率
structured_no_memory	否	否	0.51	0.636	0.633	12.49	1831	256644	0.000
structured_memory_no_feedback	是	否	0.56	0.678	0.675	14.08	1801	262656	0.007
structured_memory_with_feedback	是	是	0.55	0.667	0.661	14.80	1828	271594	0.010
text_memory_no_feedback	是	否	0.51	0.622	0.619	15.79	10515	266094	0.013

数据来源：reports/ablation_hotpotqa_100/20260718_114025/ablation_report.md。

关键发现：

在主题独立的 HotpotQA 上，开启记忆复用仍带来 EM +9.8% / F1 +6.6% 的收益（0.51 → 0.56），说明即使跨题命中率极低（0.7%），记忆机制仍能通过召回少量相关中间结论或证据辅助推理。

ground-truth 反馈并未提升准确率（EM 0.56 → 0.55），反而增加总 token 数约 **3.4%**（262656 → 271594），说明默认关闭反馈是正确口径。

结构化通信 vs 文本通信在均开启记忆复用时，EM 0.56 vs 0.51、文本字符 1801 vs 10515，结构化在保持更高准确率的同时将 Agent 间消息字符压缩约 **83%**；总 token 数基本持平（262656 vs 266094），说明压缩的是序列化消息长度，而非 LLM 调用量。

消融实验在旧 memory.db 口径下完成，用于隔离记忆/通信模式影响；主实验已改用严格临时 memory.db 口径，故绝对 EM 与消融表存在小幅差异。

外部框架横向基线（HotpotQA 100，新口径已重跑）

下表为同一批 tasks/hotpotqa_100.json、同一证据检索器，仅替换 Agent 协作层的横向对比。三个外部框架均已按新口径（关闭 ground-truth 反馈、临时 memory.db、记忆召回阈值 0.3）重跑完成。

系统	EM	F1	ROUGE-L	平均延迟(s)	总 token 数	平均 token/题	备注
本项目 structured（新口径）	0.52	0.637	0.634	22.5	265597	2656	SCP 结构化通信
本项目 text（新口径）	0.53	0.656	0.654	24.6	252120	2521	纯文本通信
CrewAI 单 Agent	0.53	0.655	0.649	3.1	102300	1023	`crewai` Agent/Task/Crew，无共享记忆
AutoGen 单 Agent	0.20	0.362	0.358	8.5	94500	945	`autogen-agentchat` AssistantAgent
LangGraph ReAct v2	0.36	0.507	0.504	10.5	550339	5503	已修复 verbose 答案二次提取

数据来源：reports/crewai_hotpotqa_100/crewai_baseline_report.json、reports/autogen_hotpotqa_100/autogen_baseline_report.json、reports/langgraph_hotpotqa_100_v2/langgraph_baseline_report.json。

关键发现：

CrewAI 单 Agent 与本项目 structured 的准确率接近（EM 0.53 vs 0.52，McNemar p=1.0，不显著），但 CrewAI 总 token 数 102300、平均 1023/题，低于本项目（因单 Agent 不做多轮分解）；本项目 structured 的优势在于 Agent 间消息字符更低（1870 vs 2824）且具备可复用的共享记忆机制。

AutoGen 单 Agent（EM 0.20）与本项目 direct_qa 处于同一档，structured 相对 AutoGen 显著领先（p<0.001）；说明仅引入框架而不设计协作机制，无法解决多跳推理问题。

LangGraph ReAct 修复 verbose 答案二次提取后，EM 从 0.00 提升至 0.36，但仍显著低于 structured（p=0.007）；其总 token 数最高（550339），主要因部分题目触发多轮 ReAct 循环。

本项目 structured 的准确率与表现最好的 text/CrewAI 接近，Agent 间消息字符更低，且具备可复用的记忆机制。

外部框架依赖较重且可能与主项目依赖冲突，推荐在独立虚拟环境运行：
python3 -m venv .venv_baselines
bash scripts/run_external_baselines.sh
开销口径说明：外部 baseline 的 总 token 数 / 平均 token/题 由 scripts/parse_baseline_log_cost.py 从 baseline 运行日志解析 prompt/completion tokens 后求和得到，是可直接复现的主开销指标。估算金额（CrewAI 0.0556 元 / AutoGen 0.0512 元 / LangGraph 0.2631 元）仅按默认 deepseek-v4-pro 单价换算，用于横向相对比较，不包含 embedding、检索中间调用、网络超时重试等额外开销，可能与实际账单存在偏差。

关于“平均文本字符”：外部框架的 Agent 间消息格式与本项目不同，无法直接对比“Agent 间序列化消息字符”这一指标，因此本表不再列出外部 baseline 的文本字符；如需通信开销对比，请以总 token 数与本项目 Agent 间消息字符分别评估。

2WikiMultiHopQA / MuSiQue 结果

数据集	样本数	模式	EM	F1	ROUGE-L	BLEU	平均文本字符	总 token 数	平均延迟(s)	备注
2WikiMultiHopQA	100	structured	0.62	0.669	0.669	—	1960	194488	11.6	临时 memory.db，100 样本
2WikiMultiHopQA	100	text	0.60	0.652	0.652	—	7310	188902	19.1	临时 memory.db
2WikiMultiHopQA	100	direct_qa	0.03	0.130	0.130	—	2091	78537	4.3	无 Agent 基线
MuSiQue	100	structured	0.40	0.508	0.508	—	3034	358270	34.3	临时 memory.db，100 样本
MuSiQue	100	text	0.37	0.465	0.463	—	15226	352035	44.5	临时 memory.db
MuSiQue	100	direct_qa	0.07	0.145	0.145	—	2867	137959	11.1	无 Agent 基线

两个数据集均自带 10 篇候选文档作为 corpus，因此检索不依赖 Wikipedia API。完整汇总见 reports/experiment_summary.md。

2WikiMultiHopQA 100 样本结果（v2 口径）：structured 模式 EM 0.62、F1 0.669，略高于 text（EM 0.60 / F1 0.652）与 direct_qa（EM 0.03 / F1 0.130）；结构化模式平均文本字符 1960，约为 text 模式（7310）的 **26.8%**；总 token 数 194488 vs 188902，基本持平（差异来自输出长度波动）。structured vs text 差异不显著（McNemar p=0.69），vs direct_qa 高度显著（p<0.001）。

MuSiQue 100 样本结果（v2 口径）：structured 模式 EM 0.40、F1 0.508，略高于 text（EM 0.37 / F1 0.465）与 direct_qa（EM 0.07 / F1 0.145）；结构化模式平均文本字符 3034，约为 text 模式（15226）的 **19.9%**；总 token 数 358270 vs 352035，基本持平。structured vs text 差异不显著（McNemar p=0.45），vs direct_qa 高度显著（p<0.001）。

跳数分层（MuSiQue 100 v1）显示：2-hop structured 47.9% vs text 33.3%；3-hop 30.0% vs 26.7%；4-hop 22.7% vs 22.7%。structured 在 2-hop 优势明显，但 4-hop 与 text 持平，提示高跳数仍需更强的中间答案推理或检索策略。详细错误分析见 reports/2wikimultihopqa_deepseek_100_all_v2/error_analysis.md 与 reports/musique_deepseek_100_all_v2/error_analysis.md。

8.2 中文百科 QA 演示（手工构造）

Embedding 模型	模式	EM	F1	估算总 token 数
all-MiniLM-L6-v2	structured	0.40	0.400	~17000
all-MiniLM-L6-v2	text	0.40	0.400	~16300
paraphrase-multilingual-MiniLM-L12-v2	structured	1.00	1.000	~24000
paraphrase-multilingual-MiniLM-L12-v2	text	1.00	1.000	~24000

说明：上表为 5 题演示集（tasks/chinese_qa_demo.json）的结果，仅用于验证中文场景下的流程正确性，不构成统计结论。multilingual 模型 + Summarizer 简洁答案约束后，这 5 题 EM/F1 均达到 1.0。估算总 token 数由历史估算金额按默认单价反推，供横向相对比较；精确值需在重新运行后从 API usage 读取。已扩展手工构造 30 题中文评测集（tasks/chinese_qa_30.json），覆盖历史、地理、文学、科学、开源技术，可用于更大规模的中文能力验证：
python3 scripts/benchmark_chinese.py --tasks tasks/chinese_qa_30.json --output-name chinese_qa_30
EMBEDDING_LOCAL_MODEL=sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 \
    python3 scripts/benchmark_chinese.py --tasks tasks/chinese_qa_30.json --output-name chinese_qa_30

8.3 统计显著性检验

对三个 100 样本实验做 McNemar 精确检验（EM 正确性，双侧）与配对 bootstrap（F1 差值，10000 次重采样，seed=42，95% CI），逐题分数由 src/evaluation/quality.py 重新计算，脚本为 scripts/significance_test.py，完整结果见 reports/significance/：

数据集	对比	EM(A) vs EM(B)	McNemar p	F1 差值 95% CI	结论
HotpotQA 100（临时 DB 口径）	structured vs text	0.52 vs 0.53	1.0000	[-0.089, +0.051]	不显著
HotpotQA 100（临时 DB 口径）	structured vs direct_qa	0.52 vs 0.27	<0.001	[+0.138, +0.331]	显著
HotpotQA 100（临时 DB 口径）	structured vs CrewAI	0.52 vs 0.53	1.0000	[-0.102, +0.065]	不显著
HotpotQA 100（临时 DB 口径）	structured vs AutoGen	0.52 vs 0.20	<0.001	[+0.185, +0.365]	显著
HotpotQA 100（临时 DB 口径）	structured vs LangGraph v2	0.52 vs 0.36	0.007	[+0.034, +0.225]	显著
2WikiMultiHopQA 100（临时 DB 口径）	structured vs text	0.62 vs 0.60	0.688	[-0.032, +0.070]	不显著
2WikiMultiHopQA 100（临时 DB 口径）	structured vs direct_qa	0.62 vs 0.03	<0.001	[+0.452, +0.622]	显著
MuSiQue 100（临时 DB 口径）	structured vs text	0.40 vs 0.37	0.453	[-0.011, +0.102]	不显著
MuSiQue 100（临时 DB 口径）	structured vs direct_qa	0.40 vs 0.07	<0.001	[+0.276, +0.454]	显著

结果说明：

HotpotQA 100 临时 DB 口径：
- structured 相对 text 的准确率差异很小且不显著（EM 0.52 vs 0.53，p=1.0），但相对 direct_qa 仍高度显著（p<0.001）。
- structured 相对 CrewAI 单 Agent 差异亦不显著（EM 0.52 vs 0.53，p=1.0），说明在 HotpotQA 这类主题独立的多跳 QA 上，CrewAI 单 Agent 已能达到与本项目 structured 相近的准确率；但本项目 structured 的 Agent 间消息字符仅 1870，显著低于 CrewAI 的 2824，且具备共享记忆机制。
- structured 相对 AutoGen（EM 0.20，p<0.001）与 LangGraph ReAct v2（EM 0.36，p=0.007）均显著领先。
- 结构化协议的核心收益体现在 Agent 消息应用层文本字段压缩（降至 text 的 18.9%，总 token 数基本持平）与可审计状态引用，而非单纯准确率提升；该历史实验未记录完整协议字节。
HotpotQA 100 分层采样进一步说明：在更严格的 stratified 采样下，text 模式 F1 显著高于 structured（CI [-0.157, -0.033]），提示“structured 准确率更高”不能作为通用结论；结构化协议的收益应聚焦于更短的应用层文本字段、可审计状态和已验证的同机跨进程部署。
2WikiMultiHopQA / MuSiQue 100 已按同样临时 DB 口径重跑；structured vs direct_qa 均高度显著，structured vs text 不显著，与 HotpotQA 趋势一致。
完整外部 baseline 显著性检验见 reports/significance/hotpotqa_100_v3_with_baselines.md。

8.4 错误分析与记忆图可视化

数据集	错误分析	错误重叠热力图	记忆关系图
HotpotQA 100	`reports/hotpotqa_100_v3/error_analysis.md`	`error_overlap_matrix.png`	`memory_graph.png`
2WikiMultiHopQA 100	`reports/2wikimultihopqa_deepseek_100_all_v2/error_analysis.md`	`error_overlap_matrix.png`	`memory_graph.png`
MuSiQue 100	`reports/musique_deepseek_100_all_v2/error_analysis.md`	`error_overlap_matrix.png`	`memory_graph.png`

2WikiMultiHopQA 100 v2 的错误分析（旧 v1 分层结论，供趋势参考）：

structured 在 bridge_comparison 上达 95.7%（22/23），comparison 上 92.0%（23/25），compositional 类型下降至 33.3%（15/45），inference 上 57.1%（4/7）；
text 模式 bridge_comparison 100%（23/23），comparison 84.0%（21/25），compositional 仅 15.6%（7/45），inference 仅 14.3%（1/7）；
direct_qa 基线在多跳问题上几乎失效，验证了 Agent 分解与检索的必要性；
错误重叠矩阵：structured 与 text 同时答错 35 题，说明复杂组合推理仍是共同瓶颈。

MuSiQue 100 v1 的错误分析（按跳数与结构子类型分层）显示：

structured 与 text 正确率接近，但 structured 的 F1 更高，说明结构化通信在答案完整度上仍有优势；
text 模式平均应用层文本字符远高于 structured；由于该批历史结果未记录完整协议字节，这里只比较文本字段长度，不外推为总传输字节优势；
direct_qa 基线再次失效，说明 MuSiQue 的 4-hop 组合推理对显式分解与检索的依赖更强；
按跳数看：2-hop 题目 structured 优势明显，4-hop 与 text 持平，提示高跳数仍需更强的中间答案推理或检索策略。

生成命令示例：

python scripts/analyze_errors.py reports/hotpotqa_100_v3
python scripts/analyze_errors.py reports/2wikimultihopqa_deepseek_100_all_v2
python scripts/analyze_errors.py reports/musique_deepseek_100_all_v2
python scripts/visualize_memory_graph.py --output reports/memory_graph.png

8.5 跨任务记忆复用 A/B 实验（受控）

为验证“记忆复用”的真实收益（而非随机召回），scripts/memory_reuse_20_experiment.py 对 20 组强顺序依赖任务做受控 A/B：唯一变量是是否在每个任务前清空记忆，模型、温度、检索 top-k 均一致。任务已补充本地语料，避免 Wikipedia 超时。真实 DeepSeek API、structured 模式下的结果（reports/memory_reuse_20/20260718_184636/）：

指标	开启记忆复用	关闭记忆复用	变化率
任务数	40	40	-
平均延迟 (s)	18.416	28.459	-35.3%
平均文本字符	2937	2693	+9.1%
记忆命中率	0.212	0.000	-
T2 命中前序记忆的对数	9/20	0/20	-
平均消息数	5.30	5.00	+6.0%
总 token 数	80864	76859	+5.2%
平均 token 数/题	2022	1921	+5.2%

结果说明：

开启记忆复用后 T2 命中前序记忆 9/20，关闭后严格为 0，证明受控开关生效；
强顺序依赖任务上，命中记忆使平均延迟降低 **35.3%**，证明共享记忆在语义关联、顺序依赖场景中的真实收益；
总 token 数上升约 5.2%，主要来自记忆召回后额外的推理与整合步骤，但延迟下降说明检索/规划重复开销被更大程度消除；
准确率说明：本任务集为开放式调研/分析题（如“调研 openEuler 内核特性”），无唯一标准答案，因此不适用 EM/F1。T2 是否命中前序记忆是答案质量的替代指标；如需客观准确率，可在具有标准答案的下游任务上构造强顺序依赖 pair；
20 组任务规模有限，上述百分比只作为机制验证；正式质量结论以 100 对带标准答案实验为准。

运行命令：

python scripts/memory_reuse_20_experiment.py --mode structured

8.6 带标准答案的记忆复用消融（正式）

正式实验基于 MuSiQue decomposition 构造 100 对 T1→T2 连续任务，采用固定 seed 的 memory-on/off 随机交叉顺序并重复 3 轮。共 1200 次任务全部成功、0 错误。

条件	T2 样本	EM	F1	平均延迟(s)	总 Token	P@K	R@K	nDCG	总通信字节
memory-on	300	0.340	0.424	28.979	929151	0.182	0.523	0.426	40033626
memory-off	300	0.343	0.440	31.595	985880	0.000	0.000	0.000	17554864

memory-on 将平均延迟降低 **8.28%**、总 Token 减少 **5.75%**，但总通信字节增加 **128.05%**。EM McNemar p=1.0000，F1 差值 -0.0160、95% CI [-0.0601, 0.0280]，答案质量差异不显著。157 次相关命中中有 24 次改善对应答案 F1，有效命中率为 15.29%。因此当前证据支持“降低重复推理开销”，不支持“提升答案质量”；P@K=0.182 也明确暴露了负候选排序和注入门控的改进空间。

.venv/bin/python scripts/memory_qa_ablation.py \
  --tasks tasks/memory_qa_pairs_100.json \
  --output reports/memory_qa_ablation \
  --repeats 3 --seed 42 --resume

完整汇总、逐题结果和显著性检验见 reports/memory_qa_ablation/。

8.6.1 记忆动态门控、重排与压缩

在同一 100 对 MuSiQue 强依赖任务、相同模型、seed=42 和交叉顺序下，新增 fixed-top-k、dynamic-gated 与 memory-off 三条件，各重复 3 轮。动态方案将语义、词法、时效性和置信度用于重排，并只注入带 ID/分数审计的定长事实摘要。

条件	T2	F1	P@K	平均注入数	平均 Token	总通信字节
fixed-top-k	300	0.477	0.020	2.980	3206.5	46345207
dynamic-gated	300	0.511	1.000	1.000	3146.1	18781221
memory-off	300	0.457	0.000	0.000	3250.8	17808004

dynamic-gated 相对 fixed 的总通信降低 **59.48%**，但 F1 差异未显著；相对 memory-off 的 F1 +0.0542（95% CI [0.0105, 0.0998]），总通信仅 +5.47%。因此，这一受控任务上的结果支持动态门控在质量与通信之间的改进，不外推为开放域问答的普遍结论。

.venv/bin/python scripts/memory_gating_experiment.py \
  --tasks tasks/memory_qa_pairs_100.json \
  --output reports/memory_gating_experiment \
  --repeats 3 --seed 42 --resume

8.7 十轮稳定性与资源泄漏验证

HotpotQA 10 题在同一 Python 进程内连续运行 10 轮，共 100/100 次任务成功、 0 异常。每轮墙钟均值 137.547s，P95 153.768s。清理后 FD 始终为 5、线程始终为 32，共享内存与临时 SQLite 残留均为 0；第 2 至第 10 轮 RSS 净增 3.81%，末 3 轮趋势 +1.012 MB/轮，达到稳态验收边界。

.venv/bin/python scripts/stability_experiment.py \
  --tasks tasks/hotpotqa_10.json \
  --output reports/stability_10_rounds \
  --rounds 10 --mode structured --resume

实验修复并验证了临时记忆库、消息队列和 LLM usage 回调的完整生命周期。逐轮资源、100 条原始结果与判据见 reports/stability_10_rounds/。

8.8 四个独立 Agent 进程演示

Planner、Retriever、Executor、Summarizer 可作为四个独立 OS 进程连接独立 gRPC MessageBus。正式演示完成能力发现、健康握手、任务路由、跨进程 StateRef/HMAC 校验、Executor 故障重启、优雅停止和残留检查，所有验收项通过。

.venv/bin/python scripts/multiprocess_demo.py demo \
  --output reports/multiprocess_demo

正式结果包含四角色独立 PID、11 个消息链路事件、Executor 新旧 PID、完整 StateRef 审计、进程日志和零共享内存残留证据。分步启动、健康检查与停止命令见 docs/experiment_reproduction.md。

8.9 通信与状态微基准

JSON、Protobuf Struct、POSIX StateRef 在 1/4/16/64 KiB 和并发 1/4 下共完成 24 case × 50 次往返，0 校验失败。64 KiB、并发 1 时，StateRef 达到 1374 op/s、P95 791us、线上引用 267B；JSON 为 77 op/s、P95 18221us、编码 321872B。

.venv/bin/python scripts/communication_microbenchmark.py run \
  --output reports/communication_microbenchmark \
  --sizes 256 1024 4096 16384 \
  --concurrency 1 4 --iterations 50

小状态并发场景存在 POSIX 对象创建竞争，建议设置尺寸阈值。共享内存路径仍有 tobytes() 写拷贝和读取后的 copy()，因此项目只宣称避免在消息中编码大向量；当前实现不是端到端零拷贝。完整结果见 reports/communication_microbenchmark/。

9. 评测指标

三模式对比报告（comparison.reduction 与 comparison.* 字段）包含：

latency_reduction：结构化相对纯文本的延迟变化（负值表示 structured 更慢）
message_reduction：消息数量减少率
text_chars_reduction：Agent 间传输文本字符数减少率（注意：非 LLM API 计费 token）
serialized_message_bytes_reduction：总线实际生成的 JSON UTF-8 / Protobuf 协议字节减少率
total_communication_bytes_reduction：协议消息字节与非文本状态字节之和的减少率
token_reduction：LLM API 总 token 数变化率，由 API usage 精确返回
state_transfers_structured/text：非文本状态传输次数
state_bytes_structured/text：非文本状态传输字节数
memory_hit_rate_structured/text：共享记忆命中率
prompt_tokens / completion_tokens / total_tokens：主开销指标（精确可验证）
estimated_total_cost：估算金额，仅作横向相对比较，不等同于真实账单

通信字节口径不包含内核 socket、HTTP/2/TCP 等随运行环境变化的链路头部。广播消息的协议字节按实际成功投递次数累计，并通过 message_delivery_count 披露；序列化与反序列化耗时分别记录，便于后续通信微基准分析。

非文本状态证据选择消融

结构化模式默认启用 evidence embedding Top-K 选择：

ENABLE_STATE_EVIDENCE_SELECTION=1|0：启用或关闭向量决策，默认启用。
STATE_EVIDENCE_TOP_K=3：传给 Summarizer 的证据数量。

.venv/bin/python scripts/state_selection_ablation.py \
  --tasks tasks/hotpotqa_100.json \
  --repeats 3 \
  --top-k 3 \
  --output reports/state_selection_ablation

脚本按 AB/BA 顺序交替 state-on/state-off，并汇总 EM/F1、Token、延迟、协议消息字节、状态字节、总通信字节和选择失败次数。使用远程 LLM 时，公开任务中的问题和 corpus 会发送至 .env 配置的 API，运行前应确认数据外发授权；Mock 运行只能验证链路，不可作为比赛效果结果。

正式 HotpotQA 100 × 3轮结果：state-on 相对 state-off 的 LLM Token 减少 **21.49%**、延迟减少 **5.76%**；EM/F1 差异均不显著（EM p=0.7754，F1 差值 95% CI [-0.0557,+0.0294]）；543 次向量选择、0 次失败。总通信字节基本持平（+0.61%），因此结论限定为降低模型上下文与推理开销。原始结果见 reports/state_selection_ablation/。

10. CodeAct 主流程验证

MultiAgentWorkflow 已支持 Planner→Executor 沙箱执行→Planner 审查/修复 →Summarizer 的完整 CodeAct 协作链路。正式 20 题三条件实验中，多智能体 CodeAct、单智能体 CodeAct 和无执行静态修复均为 19/20（95%），差异不显著；多智能体流程完成 21 次重试和 4 次安全拦截记录，但延迟和 Token 更高。该结果证明的是主流程闭环、安全拒绝后的协作修复与可审计性，不证明简单任务上的性能优势。复现命令与逐任务证据见 docs/experiment_reproduction.md 和 reports/codeact_workflow/。

11. 许可证与声明

本项目为比赛原创作品，参考了上述开源项目与论文的设计思想，源码独立实现。运行配置由 .env.example 提供模板，真实密钥不进入版本控制。