LiteAgent-Memory

面向多智能体协作的低开销通信、非文本状态传递与共享记忆原型系统。

本仓库采用匿名化展示，不包含参赛单位、指导教师和成员姓名。系统面向 openEuler 24.03-LTS-SP3，支持 Planner、Retriever、Executor、Summarizer 四类 Agent，能够在纯文本、结构化协议、状态胶囊、共享记忆和完整优化五种模式下执行同一批任务并生成可复现实验结果。

核心创新

AgentLink Compact Protocol：以 MessagePack 编码动作、参数、结果、能力与状态引用；通过 HELLO、CAPABILITY_ADVERTISE、ACTION_REQUEST 和 ACTION_RESULT 完成握手、能力发现与协议映射。
动作感知语义投影：调度器按接收 Agent 的动作需求裁剪状态。Executor 获得必要证据，Summarizer 只获得标题、证据 ID 和状态引用，避免全文反复序列化。
State Capsule 非文本状态胶囊：将稠密向量、摘要哈希和元数据编码为二进制状态，通过持久化共享内存通道传递；Agent 交换 state:// 引用，而不是重复长文本。
可核验跨进程 IPC：实验启动独立子进程附着同一共享内存，完成 20 轮状态读写和完整性校验，证明状态交换并非单进程字典模拟。
共享记忆复用：统一记忆单元包含 memory ID、来源 Agent、创建时间、任务主题、摘要、标签、向量、证据链和置信度，支持关键词、标签和语义相似度混合检索。
质量门控与去重证据：共享记忆使用域词门控抑制无关复用；24 例基准同时评估同义改写和困难负例；独立重复状态对照验证内容寻址去重。
公平消融实验：同一任务、同一角色、同一确定性数据分别运行五种模式，拆分协议、状态、记忆和完整优化的贡献。

系统架构

Vue 3 评审控制台
       |
FastAPI / NDJSON 事件流
       |
Multi-Agent Runtime
       |
Protocol Parser + Scheduler
       |
+----------------------+----------------------+
| State Capsule Store  | Shared Memory IPC    |
+----------------------+----------------------+
       |
Hybrid Shared Memory Store
       |
Evaluation + Evidence Artifacts

源码模块：

agents/：四类 Agent。
runtime/：运行时、调度器和执行事件。
protocol/：协议消息、编码、握手和能力发现。
transport/：传输适配、共享内存和跨进程 IPC 基准。
state/：非文本状态生成、内容寻址、引用解析和去重。
memory/：统一记忆模型、存储、混合检索和质量门控。
evaluation/：五模式消融、连续任务、统计和报告。
webapp/：FastAPI 服务、事件流和静态资源。
frontend/：Vue 3 + TypeScript + Vite 前端源码。
tests/：单元、集成、Web、实验和传输测试。

当前候选结果

outputs/ 当前保存的是最新源码在 Windows 上执行 10 个任务、3 次重复得到的候选结果。最终提交前必须在 openEuler 24.03-LTS-SP3 上重新运行并使用提升脚本替换，不能把该目录描述为最终 openEuler 数据。

指标	当前候选值
纯文本平均 Token	3354.3
结构化协议平均 Token	2906.1
协议层 Token 节省率	13.36%
状态模式平均 Token	1763.9
记忆模式平均 Token	1898.5
完整优化平均 Token	1437.7
完整优化 Token 节省率	57.14%
字符节省率	52.98%
MessagePack 相对 JSON 字节节省率	14.39%
连续任务记忆命中率	80.00%
任务级记忆 Precision / Recall	100% / 100%
24 例记忆基准 Hit@2 / MRR	100% / 100%
12 个困难负例拒绝率	100%
重复状态独立对照通过率	3 / 3
跨进程 IPC 完整性	20 / 20
模型调用估算端到端节省率	55.90%
本地框架实测耗时变化	-1.14%

最后一项表示当前确定性本地工作负载中，Python 框架实测时间没有取得正收益；模型调用估算值只用于说明减少 Token 后的潜在收益，二者在报告中分开呈现。

Windows 快速运行

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
python run_demo.py
python -m pytest -q
python run_experiment.py --repeat 3 --output-dir outputs

启动评审控制台：

python run_webapp.py --host 127.0.0.1 --port 8000

浏览器访问 http://127.0.0.1:8000。控制台可实时查看 Agent 消息、状态引用、共享记忆、五模式消融和系统证据。

前端源码发生变化时，在 Windows 上重新构建：

cd frontend
npm install
npm run build
cd ..

构建产物写入 webapp/static/，openEuler 运行阶段不需要安装 Node.js。

openEuler 最终复验

在 Windows PowerShell 的项目根目录执行：

.\scripts\deploy_openeuler.ps1 -VmIp 192.168.184.128

脚本会打包当前源码、上传虚拟机、创建虚拟环境、安装依赖、执行演示、3 次重复实验、81 项测试、Python 编译检查和 Web 冒烟测试，再把结果拉回 vm-results/<时间戳>/。

确认日志后，将该批 openEuler 结果提升为根目录正式结果：

.\scripts\promote_verified_outputs.ps1 `
  -ResultDir .\vm-results\<时间戳>

提升脚本只有在日志同时包含 openEuler 24.03-LTS-SP3、81 passed 和完成标记时才会覆盖 outputs/。完整说明见部署文档。

结果证据

outputs/experiment_results.json：逐任务、逐模式原始记录。
outputs/metrics_summary.json：聚合指标。
outputs/protocol_negotiation.json：握手与能力发现轨迹。
outputs/state_dedup_controls.json：重复状态去重对照。
outputs/ipc_benchmark.json：独立子进程共享内存基准。
outputs/memory_quality_benchmark.json：24 例记忆质量基准。
outputs/experiment_report.md：自动生成实验摘要。
outputs/dashboard.html：离线实验看板。
outputs/openeuler_verification.log：最终 openEuler 环境与测试日志。

文档

已知边界

默认向量生成器是确定性的哈希嵌入，保证离线复现；可选模型适配器不作为当前结果的前提。
当前任务集聚焦 openEuler 运维诊断，不代表跨领域泛化能力。
所有百分比均来自仓库内原始 JSON；最终奖项由评审决定，项目不作获奖保证。