Memlink-MA：多智能体低开销通信、状态传递与共享记忆机制

本项目针对多 Agent 协作系统的基础设施问题，实现了一套可复现的原型系统：围绕 Agent 间通信协议、非文本状态传递、共享记忆复用和运行效率验证构建系统层机制。

2026-09-23 决赛审计：本轮正确性与可靠性修复已通过 Windows 与 openEuler 24.03 LTS SP3 / WSL2 的 125 项测试（另有 54 个 subtest）；openEuler 的真实 ONNX 模型、MessagePack 四进程十轮离线演示，以及使用 CC Switch 外围大模型配置的四进程真实模型调用均通过。真实模型部分只是一次部署验收冒烟任务，不是正式性能或准确率实验；历史 benchmark 数字仍不代表修复后版本的新实测。详见 决赛代码与方向审计、openEuler 验证记录 和 大模型 实时联调记录。

作品信息与提交材料

Memlink-MA 是一个面向 Linux 用户态的多智能体协作运行时原型。它把 Agent 间的控制消息、需要保真的中间状态和可复用记忆分开处理：控制面用结构化消息传递，数据面用共享内存按需取回，记忆复用必须经过一致性与预算检查。

评审者建议阅读顺序

1. 先看本 README 的“核心能力”“快速开始”和“现场演示主线”。
2. 运行 demo/run_demo.sh（Linux/openEuler）或 demo/run_demo.ps1（Windows），确认四个角色和 IPC 链路。
3. 查看 openEuler 验证记录 与 My Claude 实时联调记录。
4. 再看演示 PPT、视频和项目说明书，材料路径见下表。

作品要解决的问题

• 多 Agent 之间反复透传长文本，通信成本和上下文长度随协作链路增长。
• 摘要、向量和完整状态混在一起传递，容易出现状态丢失、误复用和无法追责。
• 进程异常、共享内存释放和失败统计若没有明确边界，演示成功不等于运行时可靠。

三个核心创新点

1. 控制面与数据面分离。 用 StructuredMessage/MessagePack 传动作和元数据，用 StatePacket 引用共享内存中的中间状态，消费方按预算和相似度决定是否取回。
2. 带约束的记忆复用。 共享记忆采用 FAISS + SQLite，全文一致性、置信条件和冷/暖任务边界共同决定是否跳过后续 Agent 调用，不把向量相似度直接当作事实一致。
3. 可验收的多进程生命周期。 Planner、Retriever、Executor、Summarizer 在独立进程中完成握手、任务消息、状态读取和释放；失败时保留报告并回收进程，不把异常伪装成成功。

项目定位是 Linux 用户态协作运行时原型：将结构化通信、共享内存状态引用和带置信条件的记忆复用组合验证。共享内存使用标准 OS 接口，不能据此宣称修改了内核、实现端到端零拷贝或直接传递大模型隐藏层状态。目前 Retriever 角色调用 LLM 整理信息，没有连接可核验的外部文档检索；现有质量分是规则代理指标，不是事实正确率。

核心能力

能力	实现
多 Agent 协作	Planner / Retriever / Executor / Summarizer 四类 Agent
真多进程 IPC	--ipc-demo 离线验证机制；--ipc-task 用真实 LLM 承载四进程端到端任务
结构化通信	StructuredMessage + ActionType + AgentCapability
二进制协议	msgpack 编码 + action shortcode + JSON/binary bytes 统计
真实语义向量	本地 ONNX 模型 fastembed+bge-small-zh-v1.5(512维, 无 torch)，离线降级哈希
非文本状态传递	StatePacket(句柄+向量+摘要) + 共享内存数据面 + 消费端向量门控 deref/skip
共享记忆	FAISS 向量索引 + SQLite 元数据存储，真实语义向量
记忆复用	完整任务指纹优先匹配；否则稠密召回+术语筛选，唯一高置信候选跳过 planner / retriever / executor，保留总结
CodeAct	Executor 使用受限算术执行器计算可明确解析的指标；不执行模型生成的任意代码
Web 控制台	--ui 启动本地控制台：跑任务、实时协作事件流、指标面板、共享记忆浏览，纯标准库实现
评测	text / text-fair / structured / full 四模式 benchmark；同任务同轮次配对统计
记忆检索评测	40 条正例/改写正例/困难负例/无关负例，报告 Precision/Recall/F1/FPR
消融实验	full-no-memory / full-no-vector / full-no-memory-no-vector
质量评估	deterministic rubric 评估 relevance、completeness、depth 等
openEuler 验证	src/scripts/openeuler_setup.sh + src/scripts/openeuler_verify.sh

系统架构

相同任务的复用边界（2026-10-07 修复）

full 模式优先使用完整任务的可查询已成功保存的结果，不依赖向量 top-k；同一输入有多个历史版本时选最近的成功版本。命中后跳过规划、信息整理与执行，仍调用总结模型。相同输入的快捷复用不会再追加一条总结记忆。未命中完整任务时，原有语义检索阈值与唯一候选门控保持不变。

Multi-Agent Runtime
├── Planner Agent
├── Retriever Agent
├── Executor Agent
│   └── CodeActSandbox
├── Summarizer Agent
├── ProtocolHandler
│   ├── StructuredMessage
│   ├── msgpack codec
│   └── action shortcodes
├── VectorBridge (fastembed ONNX 真实语义向量 / 哈希降级)
│   ├── StatePacket
│   └── SharedStateStore (multiprocessing.shared_memory 数据面)
├── MemoryStore (混合检索: 稠密召回 + 区分性术语精排)
│   ├── FAISS
│   └── SQLite
└── Eval
    ├── benchmark
    ├── quality evaluation
    └── ablation

IPC Demo Runtime
├── planner process
├── retriever process
├── executor process
├── summarizer process
├── control plane: multiprocessing.connection over localhost
└── data plane: multiprocessing.shared_memory

四种协作模式

模式	说明	用途
text	Agent 间累积透传自然语言长文本	朴素高开销基线
text-fair	Agent 间只传上一步输出（精简）	公平基线
structured	Agent 间通过动作、参数、结果等结构化消息通信	验证协议通信
full	结构化协议 + 非文本状态传递(共享内存) + 共享记忆复用	完整机制

另有消融模式：

模式	说明
full-no-memory	关闭共享记忆，保留 StatePacket
full-no-vector	关闭 StatePacket / state vector，保留共享记忆
full-no-memory-no-vector	同时关闭共享记忆和 StatePacket，用于关键任务消融

现场演示主线

建议按下面顺序演示，先证明机制，再展示真实模型联调：

# 1. 无需 API Key 的四进程离线演示
bash demo/run_demo.sh

# 2. 直接运行共享内存与 MessagePack 验收
python src/main.py --ipc-demo

# 3. openEuler 目标环境复核（需要已安装依赖和本地 ONNX 模型）
bash src/scripts/openeuler_verify.sh ./output/finals_linux_verify

# 4. 在线四进程任务（需要自行配置可用的模型服务和密钥）
python src/main.py --ipc-task --prompt "比较两种共享内存释放策略并给出取舍"

现场只把第 4 步作为模型服务联调，不把一次在线请求的耗时或返回文本当作性能、成本或准确率结论；离线 IPC 报告和完整测试结果才是机制验收依据。

第三方与原创边界

项目核心代码、协议、StatePacket、共享内存生命周期控制、记忆复用策略和测试由本项目实现。依赖库、fastembed 使用的公开 ONNX 模型、外部 LLM 服务及其返回内容不属于本项目自研；许可证与通知见 src/LICENSE 和 src/NOTICE。提交项目说明书时，按模板补充第三方库/模型来源、许可证和实际引用范围，不把外部模型或服务写成自研成果。

快速开始

1. 安装依赖

pip install -r src/requirements.txt
mkdir -p data/memory output/eval

2. 配置 API Key

当前默认使用 DeepSeek OpenAI-compatible API。

Linux / openEuler:

export DEEPSEEK_API_KEY="your-api-key"

Windows PowerShell:

$env:DEEPSEEK_API_KEY="your-api-key"

也可以在 src/config.yaml 中临时填写：

llm:
  provider: "deepseek"
  model: "deepseek-v4-flash"
  base_url: "https://api.deepseek.com"
  api_protocol: "openai"       # openai 或 anthropic
  anthropic_auth_mode: "api_key" # api_key 或 bearer；仅 anthropic 协议使用
  api_key_env: "DEEPSEEK_API_KEY"
  api_key: ""
  temperature: 0.7
  max_tokens: 4096
  timeout_seconds: 120
  max_retries: 4
  retry_backoff_max_seconds: 8

正式交付前建议清空 api_key，改用环境变量。

默认路径是 OpenAI-compatible Chat Completions。若使用 Anthropic Messages 兼容服务，将 api_protocol 改为 anthropic，并按服务要求设置 anthropic_auth_mode；仓库不保存任何真实密钥或第三方网关地址。

正式 benchmark 会在运行分支内把模型温度锁定为 0.0，并记录模型、温度、Git commit、平台、数据集哈希和 UTC 时间；日常单任务仍可使用配置文件中的温度。

3. 运行单任务

python src/main.py --single
python src/main.py --mode text --single
python src/main.py --mode structured --single
python src/main.py --mode full --single

自定义任务：

python src/main.py --mode full --single --prompt "调研Linux主流调度器的核心设计思路，给出对比分析。"

4. 运行评测

# 冒烟测试必须写入隔离目录，不覆盖冻结正式结果
python src/main.py --benchmark --trials 1 --eval-output-dir ./output/smoke

# 正式评测
python src/main.py --benchmark --trials 5 --benchmark-max-tokens 1600 --eval-output-dir ./output/finals_new_run
python src/main.py --quality-eval --eval-output-dir ./output/finals_new_run
python src/main.py --ipc-demo

输出：

output/finals_new_run/benchmark_results.json
output/finals_new_run/report.md
output/finals_new_run/quality_scores.json
output/finals_new_run/quality_report.md
output/ipc_demo/ipc_demo_report.json
output/ipc_demo/ipc_demo_report.md

5. 一键验证包

自动生成提交包：

python src/main.py --submission-pack

输出目录：

output/submission/

其中包含：

• docs/：项目说明书、审计记录和技术说明；最终提交材料以“作品信息与提交材料”表为准
• eval/：benchmark、质量评估、性能基线、openEuler 验证结果
• README_SUBMISSION.md：建议阅读顺序与核心结论
• manifest.json：提交包文件清单、字节数与 SHA-256；缺少必需材料时拒绝生成

建议正式提交前按以下顺序执行：

python src/main.py --benchmark --trials 5 --benchmark-max-tokens 1600 --eval-output-dir ./output/finals_new_run
python src/main.py --quality-eval --eval-output-dir ./output/finals_new_run
python src/main.py --error-bars --eval-output-dir ./output/finals_new_run
python src/main.py --memory-benchmark --memory-dataset all --eval-output-dir ./output/finals_new_run
python src/main.py --ipc-demo --eval-output-dir ./output/finals_new_run
python src/main.py --perf-baseline --rounds 10 --eval-output-dir ./output/finals_new_run
python src/main.py --publish --eval-output-dir ./output/finals_new_run
python src/main.py --submission-pack --eval-output-dir ./output/finals_new_run

6. Web 控制台

python src/main.py --ui            # 默认 http://127.0.0.1:8123
python src/main.py --ui --port 9000

浏览器打开后可以：提交任务并选择协作模式、实时查看协作事件流（记忆命中、StatePacket 传递会打标）、查看运行指标、浏览共享记忆条目、一键运行 IPC demo（不需要 API key）。服务端为纯标准库 http.server 实现，未新增任何依赖；启动时会自动读取项目根目录 .env 中的 DEEPSEEK_API_KEY。

7. openEuler 验证

# 部署阶段使用，需要安装依赖和下载模型；不要现场执行
bash src/scripts/openeuler_setup.sh
# 验收阶段使用：离线四进程 IPC，10 次复用，无需 API Key
bash src/scripts/openeuler_verify.sh ./output/finals_linux_verify

脚本运行后会在以下路径生成验证日志：

output/finals_linux_verify/environment.log
output/finals_linux_verify/verification.log
output/finals_linux_verify/ipc_demo_report.json
output/finals_linux_verify/ipc_demo_report.md

报告记录实际发行版。2026-09-23 已在临时安装的 openEuler 24.03 LTS SP3 / WSL2 中完成当前代码 125 项测试、54 个 subtest、真实 ONNX 512 维模型和离线四进程复测；随后使用 CC Switch 的 My Claude 配置完成四进程真实模型调用。临时发行版已删除，证据保留在 output/finals_openeuler_myclaude_20260923/。在线部分是一次合成部署验收冒烟任务，不是性能或准确率 benchmark；详见 openEuler 验证记录 和 My Claude 联调记录。

关键实验结果

发布检查： 历史正式结果采用 schema 2.0、4 模式 × 4 任务 × 5 次重复、temperature=0、thinking=false 和每次调用 1600 可见 token 上限。当前检查同时要求主任务及关联任务保存完整输出、正常结束状态和真实 API 用量；历史关联任务记录不齐，不能直接通过更新后的发布检查。默认目录已有 benchmark 时拒绝覆盖，新实验请显式指定独立目录；实验冷启动清理使用临时记忆库，不删除用户的持久化记忆。下方 Legacy 数据仅作版本追溯。

历史机制实验及当前验证入口

python src/main.py --memory-benchmark --memory-dataset all
python src/main.py --ipc-demo
python src/main.py --ipc-task --prompt "你的实际任务"
python src/scripts/run_budget_sweep.py --summary-only
python -m unittest discover -s tests -v

• 记忆检索分三层报告：内部回归集 hybrid F1 100%；门限校准压力集 F1 56.34%；门限冻结后独立 audit 集 F1 75.00%。独立集只有 12 个正例和 12 个负例：3/12 负例被检索为候选证据，8 次快路径触发均正确，观察到的负例快路径错误为 0/12。这个样本量不能证明普遍零误复用。逐条记录见 output/eval/memory_benchmark_audit.json。
• 真实 IPC 任务：4 个独立 Agent 进程均执行真实 LLM 工作负载；完整 Retriever/Executor 状态走 shared memory，控制面仅携带 64 维路由状态、摘要和句柄；API 实际 token、内部控制面字节、数据面字节和 PID 均写入 output/eval/ipc_task_report.json。
• 主 benchmark 使用进程内 Orchestrator，四进程 LLM 使用另一条固定流水线；前者的记忆收益不能直接作为后者的实测收益。旧 IPC LLM 报告也需要补齐最终输出完整性验证。
• 按需取数：natural/full 的 12 组配对样本中，--deref-budget 0 相对不限 deref 将 provider 总 token 降低 **18.5%**、prompt token 降低 **42.6%**；规则质量分差值为 -0.31±1.18（95%CI 跨 0）。它是显式效率档，不改变历史兼容默认值。
• 自动化测试：当前测试可由一条命令完整结束；准确数量以命令输出为准。

正式四模式 benchmark（5 轮）

正式命令：

python src/main.py --benchmark --trials 5 --benchmark-max-tokens 1600 --eval-output-dir ./output/finals_new_run
python src/main.py --quality-eval --eval-output-dir ./output/finals_new_run
python src/main.py --error-bars --eval-output-dir ./output/finals_new_run
python src/main.py --memory-benchmark --memory-dataset all --eval-output-dir ./output/finals_new_run
python src/main.py --publish --eval-output-dir ./output/finals_new_run
python src/main.py --submission-pack --eval-output-dir ./output/finals_new_run

下表是修复前已保存的 80 条主任务结果；质量列仅为规则代理分。旧综合分直接包含 20% 记忆命中奖励，不作质量比较，因此不再列入这张表。

模式	平均耗时(s)	API 实际 Token	规则质量分
text	19.188	3918	68.19
text-fair	17.771	2505	62.87
structured	27.197	4443	70.57
full	16.553	2812	70.13

• 80/80 个主实验任务成功，80/80 最终调用正常 stop，截断和 length 结束均为 0。
• full 相对传统 text：平均耗时下降 **13.7%**，provider API 实际 Token 下降 **28.2%**，质量分提高 1.94。
• full 相对精简公平基线 text-fair：整体平均耗时下降 **6.9%**、质量分提高 7.26；整体 API Token 增加 **12.3%**，原因是首次任务仍承担结构化规划、检索和记忆写入成本，不能宣称冷暖任务混合后的总体 Token 优于 text-fair。
• 在两项记忆命中任务上，同任务同轮次的配对结果均优于 text-fair：task_B 节省 8.86±2.10s 和 592±308 API Token，task_D 节省 8.83±0.99s 和 624±190 API Token（均值±95%CI，n=5）。这两项任务的热路径只调用 Summarizer，并跳过 Planner、Retriever、Executor。
• 历史隔离序列的成本统计存在收益，但缺少种子和后续任务的完整答案，当前发布门禁拒绝采用；C→D 的时延区间还受一次上游离群值影响而跨 0，不能主张稳定加速。

误差棒报告以“同任务、同轮次”的配对差值为主，同时保留每任务统计；API 服务返回的 prompt/completion/total token 与内部通信估算、JSON/msgpack 字节分栏展示。完整证据见 output/eval/latest_run_summary.md、output/eval/experiment_report.md 与 output/eval/error_bars_report.md。

输出预算 × deref 名额辅助扫描

该实验不覆盖上面的正式 tight 档冻结结果，而是验证机制边界。5 个组合均通过完整性门禁， 汇总中的 14 行模式结果各含 12 个样本，全部 finish_reason=stop、0 截断。

python src/scripts/run_budget_sweep.py --trials 3
python src/scripts/run_budget_sweep.py --summary-only

在 natural/full 档中，k=0 相对不限 deref 的同任务、同轮次配对结果为：

• provider 总 token：-3127.50±2093.52，即 **-18.5%**；
• prompt token：-2040.08±1555.96，即 **-42.6%**；
• 质量规则分：-0.31±1.18，区间跨 0，当前未检出差异，但不等同于证明统计等价；
• 平均耗时：-8.77±40.63s，区间跨 0，不宣称稳定时延收益。

若与初赛相同地对比传统 text 路径，并严格保持双方都是 natural 输出预算，最终 full+k0 的 provider **真实总 token 下降 40.0%**（-9163.50±3046.78），其中 prompt token 下降 **71.5%**；质量规则分 +0.47±1.87，区间跨 0。耗时差值 +8.23±20.09s 也跨 0，因此这组结果只主张通信成本下降，不主张稳定加速。

完整均值、配对区间与口径说明见 output/eval/sweep/sweep_summary.md 和 docs/项目说明书.pdf。推荐效率运行方式：

python src/main.py --single --mode full --output-budget natural --deref-budget 0 --prompt "你的任务"

历史实验结果

旧三模式 benchmark（trials=3，均值 ± 95%CI）

命令：python src/main.py --benchmark --trials 3 && python src/main.py --error-bars

以下结果来自旧版评测，仅保留用于版本追溯。它把字符数粗略换算为 token，且保存文件缺少部分完整 result，因此旧质量分和旧 token 降幅不得进入新答辩材料：

模式	平均耗时(s)	平均Token	平均消息	质量综合分
text	92.0 ± 9.5	24004 ± 2740	4.0	32.3
structured	132.6 ± 17.2	15273 ± 1725	10.0	32.2
full	84.8 ± 30.1	7524 ± 512	7.5	63.4

结论：

• 68.7% 是旧字符估算口径的降幅，不是 provider API 实际 Token 降幅。
• 旧误差区间与下方暖任务/消融表仅描述当时的小样本运行，不保证评委重跑得到相同数值。
• 当时的 msgpack/JSON 字节比为编码层对照，不能替代真实跨进程传输和端到端成本测量。

连续任务记忆复用（trials=3，per-task）

任务	角色	text耗时(s)	full耗时(s)	full vs text
task_A	调度器调研（话题首次·冷）	88.9	138.9	写入记忆
task_B	调度优化（命中 A 记忆·暖）	98.4	37.5	↓62%
task_C	eBPF 调研（话题首次·冷）	94.4	119.1	写入记忆
task_D	eBPF 优化（命中 C 记忆·暖）	86.4	43.8	↓49%

该历史运行中 A→B、C→D 命中前序记忆，暖任务耗时下降 49–62%；仅保留作历史记录，不能替代修复后版本的记忆正确性和收益测试。

关键机制消融（与 full 同冷启动口径，4 任务平均）

命令：python src/main.py --benchmark --trials 3 --ablation（详见 docs/项目说明书.pdf）

模式	耗时(s)	Token	记忆命中	shm写入	deref
full	84.8	7524	0.50	1.50	1.25
full-no-memory	151.4	8622	0.00	2.75	2.75
full-no-vector	102.7	12864	0.50	0.00	0.00

消融结论（隔离各机制贡献，回答“收益从哪来”）：

• 历史共享记忆消融耗时为 151.4s → 84.8s（约 44%），不是总体基线加速。
• 12864 → 7524 为旧 token 估算字段，不属于真实 API 用量。
• 当时的综合分包含记忆命中奖励，不能用于证明最终答案质量优于其他模式。

性能基线（P50/P95/P99，固定任务 10 轮）

命令：python src/main.py --perf-baseline --rounds 10

模式	成功率	平均(s)	P50(s)	P95(s)
text	100%	78.3	82.2	91.8
text-fair	100%	110.6	56.1	597.7*
structured	100%	131.1	129.3	186.0
full	100%	61.7	52.6	96.1

• 该表是旧版本的 10 轮观测；没有同版本、同预算的当前证据，不能从这张表推出 full 在 Token 或质量上优于 text-fair。
• * text-fair 的 P95=597.7s 是单轮 API 超时重试造成的离群点（10 轮中其余 9 轮均为 42–78s），非模式本身特性。

CodeAct 验证

任务：

请计算 text 模式耗时88.8秒、full模式耗时37.4秒时的耗时下降百分比，并给出简短结论。

结果：

codeact_executions: 2
codeact_successes: 2
计算结果: 57.88%

评测指标

系统自动统计：

指标	说明
structured_messages / text_messages	结构化 / 纯文本消息次数
api_prompt_tokens / api_completion_tokens / api_total_tokens	Provider 返回的 API 实际 token
estimated_tokens_structured / estimated_tokens_text	无 tokenizer 时的内部通信 token 估算
total_tokens_structured / total_tokens_text	兼容旧报告的估算字段别名
total_text_utf8_bytes	纯文本通信的 UTF-8 精确字节数
total_json_bytes_structured	JSON 结构化通信体积
total_binary_bytes_structured	msgpack 二进制通信体积
avg_binary_compression_ratio	二进制/JSON 体积比
non_text_state_transfers	非文本状态传递次数
non_text_state_bytes	非文本状态数据规模
state_packets	StatePacket 传递数量
state_packet_bytes	StatePacket 元数据规模
memory_reuse_hits	共享记忆复用次数
skipped_agent_calls	记忆复用跳过的 Agent 调用
compressed_results	被摘要 + 状态向量替代的中间结果数
compressed_text_chars_saved	压缩节省的文本字符数
codeact_executions / codeact_successes	CodeAct 执行次数 / 成功次数

项目结构

master 分支按大赛要求组织。运行配置、依赖清单和辅助脚本放在 src/ 内；运行结果写到未入库的 output/。

Memlink-MA/
├── README.md
├── src/
│   ├── main.py
│   ├── config.yaml
│   ├── requirements.txt
│   ├── scripts/
│   └── 其他项目源代码
├── docs/
│   ├── 项目说明书.pdf
│   ├── finals_code_audit_20260923.md
│   ├── openeuler_validation_20260923.md
│   └── myclaude_openeuler_validation_20260923.md
├── tests/
├── demo/
│   ├── README.md
│   ├── run_demo.sh
│   └── run_demo.ps1
├── presentation/
│   ├── 决赛现场演示.pptx
│   └── 决赛演示视频.mp4
└── 作品原创承诺书.pdf

提交前再做一次材料自检：视频时长与大小、PPT/视频/截图/项目说明书/src/NOTICE 中的项目名是否统一为 Memlink-MA，以及材料中是否意外出现不应公开的密钥、个人信息或临时路径。若当届规则要求匿名，还要人工复核项目说明书、src/NOTICE 和视频画面；README 只保留作品名。评审材料以截止时间前提交的版本为准；历史 benchmark 和本 README 中的审计数字都要连同平台、日期和测试口径一起理解。

注意

需要自行配置llm.api_key