LiteAgent-Memory-LLM

作品简介

本作品面向第三届中国研究生操作系统开源创新大赛暨开放原子大赛操作系统专项赛应用创新方向第 9 题，构建了一个面向多智能体协作的低开销通信、状态传递与共享记忆运行时原型。

系统实现 Planner、Retriever、Executor、Critic、Summarizer 五类 Agent，重点解决多 Agent 协作中的长上下文重复传输、状态表达低效、跨任务经验无法复用等问题。

核心能力：

• 结构化协作协议：以 action、params、result、state_ref、memory_refs 等字段替代大段自然语言透传。
• 非文本状态传递：使用 StatePacket 将语义向量写入 mmap 文件，Agent 间只传递 state_id。
• 共享记忆复用：使用 SQLite 保存 MemoryCell，支持摘要、证据、标签、复用次数和质量评分。
• 多模式对比实验：提供 text、structured、memory 三种模式，对比通信字符数、估算 token、状态传递、记忆命中率、LLM 调用和端到端耗时。
• openEuler 复现支持：提供 openEuler 原生运行脚本和基于 Docker 的 openEuler 容器运行脚本。

增强点：

1. 从规则化多 Agent 升级为 LLM-enabled 五 Agent 协作运行时。
2. 保留离线可复现 provider，同时支持 OpenAI-compatible 真实 LLM。
3. 增加 Critic Agent，用于质量检查和一致性验证。
4. 增加 UNIX Domain Socket 传输，统计 IPC 字节与时延。
5. 增加 15 轮连续任务和重复实验，输出 CSV、JSON 和 Markdown 报告。
6. 增加真实应用任务组，避免实验只围绕系统自身自证明。

运行说明

推荐环境：

• openEuler 24.03 LTS-SP3
• Python 3.9+
• 可选：Docker，用于在 openEuler 容器中复现实验

仓库根目录只保留 README.md 和 code/。所有代码、配置、脚本和赛题文档都放在 code/ 下，运行命令前先进入代码目录：

cd code

运行前先生成统一配置文件：

cp configs/runtime.env.example configs/runtime.env

后续所有需要修改的参数都在 configs/runtime.env 中配置，不需要改代码。

API 配置位置：

# configs/runtime.env
LLM_BASE_URL="https://api.example.com/v1"
LLM_API_KEY="sk-..."
LLM_MODEL="gpt-4o-2024-05-13"

如果使用自己的 OpenAI-compatible 服务，只需要把上面三个字段改成自己的接口地址、API Key 和模型名。离线可复现实验不需要填写 API。

常用实验参数也在同一个配置文件中修改：

# configs/runtime.env
TASK_FILE="configs/tasks_15_rounds.json"
MODES="text structured memory"
REPEATS=3
PROVIDER="offline"
TRANSPORT="unix"

LIVE_TASK_FILE="configs/tasks_15_rounds.json"
LIVE_MODES="text structured memory"
LIVE_REPEATS=1

在 openEuler 原生环境中安装依赖并运行离线可复现实验：

bash scripts/install_openeuler.sh
bash scripts/run_all_benchmarks.sh

输出结果：

results/benchmark_summary.csv
results/benchmark_summary.json
reports/comparison.md
runtime/*/liteagent.db

验证 openEuler 原生运行证据：

bash scripts/run_native_openeuler_full.sh

输出日志：

logs/native_openeuler_run.log
logs/env.txt

在支持 Docker 的机器上运行 openEuler 容器实验：

bash scripts/run_in_openeuler_docker.sh

输出日志：

logs/openeuler_docker_run.log

单独运行 memory 模式：

python -m liteagent_memory run \
  --mode memory \
  --provider offline \
  --transport unix \
  --task-file configs/tasks_15_rounds.json \
  --output results/memory_mode.json

接入 OpenAI-compatible 在线模型时，先确认 configs/runtime.env 中的 API 配置已经填写，然后运行：

bash scripts/run_full_live_api.sh

在线模型实验输出：

results_live/benchmark_summary.csv
results_live/benchmark_summary.json
reports_live/comparison.md
logs/full_live_api.log

小规模真实 API 演示曾在 openEuler 容器中运行，核心指标如下：

指标	数值
task_count	10
message_count	50
llm_call_count	50
llm_total_tokens	50265
memory_hit_count	28
memory_hit_rate	0.9
state_transfer_count	10
state_checksum_failures	0
quality_score_avg	0.9445

文件说明

GitLink 文件列表右侧显示的 Add LiteAgent Memory LLM solution、Unify runtime configuration 等文字是 Git 提交说明，表示该文件最近一次是在哪次提交中被修改的，不是文件用途说明。下面是仓库中主要文件的用途。

根目录文件

文件	说明
README.md	根目录总说明文档，包含作品简介、运行说明和文件说明。
code/	项目代码目录，包含源码、配置、脚本、Dockerfile、测试和赛题文档。
code/README.md	代码目录内的快速运行说明，重点说明配置文件和运行命令。

code 根目录

文件	说明
code/.dockerignore	Docker 构建时忽略无关文件，减少镜像构建上下文。
code/.gitignore	Git 忽略规则，排除虚拟环境、运行结果、日志、真实 API 配置和压缩包等不应提交的文件。
code/Dockerfile	构建 openEuler 容器实验环境，用于 Docker 方式复现实验。
code/pyproject.toml	Python 项目元数据和安装配置，支持 pip install -e .。
code/requirements_openeuler.txt	openEuler 核心运行依赖说明，核心 benchmark 仅依赖 Python 标准库。
code/requirements_ui.txt	可选 UI 和绘图依赖，包括 Streamlit、pandas、matplotlib。

configs

文件	说明
code/configs/config.json	运行时基础参数，包括向量维度、记忆阈值、离线 provider 延迟参数等。
code/configs/knowledge_base.json	内置知识库卡片，为 Retriever Agent 提供协议、状态、记忆、评测和 openEuler 相关知识。
code/configs/runtime.env.example	统一运行配置模板。复制为 code/configs/runtime.env 后可配置 API 地址、Key、模型名、任务文件、运行模式、重复次数和输出目录。
code/configs/tasks_10_rounds.json	10 轮小规模任务集，用于快速测试和在线模型小规模演示。
code/configs/tasks_15_rounds.json	15 轮完整任务集，用于正式 benchmark 和赛题要求对齐。

doce

文件	说明
code/doce/第三届中国研究生操作系统开源创新大赛暨开放原子大赛操作系统专项赛赛题.docx	原始赛题文档，用于保留题目要求和验收依据。

liteagent_memory

文件	说明
code/liteagent_memory/__init__.py	Python 包初始化文件。
code/liteagent_memory/__main__.py	支持 python -m liteagent_memory 方式启动命令行入口。
code/liteagent_memory/agents.py	Planner、Retriever、Executor、Critic、Summarizer 五类 Agent 的核心逻辑。
code/liteagent_memory/cli.py	命令行入口，提供 doctor、run、benchmark 等子命令。
code/liteagent_memory/llm_provider.py	LLM provider 实现，支持离线可复现 provider 和 OpenAI-compatible 在线 provider。
code/liteagent_memory/memory_store.py	SQLite 共享记忆存储，管理 MemoryCell 写入、检索和复用统计。
code/liteagent_memory/models.py	数据模型定义，包括任务、消息、状态包、记忆单元和运行结果。
code/liteagent_memory/protocol.py	结构化协作协议校验和消息构造逻辑。
code/liteagent_memory/report.py	benchmark 统计和报告生成模块，输出 CSV、JSON 和 Markdown 报告。
code/liteagent_memory/runtime.py	多 Agent 运行时主流程，调度三种模式下的任务执行。
code/liteagent_memory/sandbox.py	CodeAct 轻量沙箱，限制代码执行环境并收集结构化结果。
code/liteagent_memory/state_store.py	mmap 非文本状态存储，管理 StatePacket 向量写入、读取和校验。
code/liteagent_memory/transport.py	Agent 间传输层，支持本地调用和 UNIX Domain Socket 传输统计。
code/liteagent_memory/utils.py	通用工具函数，包括 JSON、哈希、时间、token 估算等辅助能力。
code/liteagent_memory/vectorizer.py	轻量向量化工具，用于生成可复现的语义向量。

scripts

文件	说明
code/scripts/check_topic_alignment.sh	检查文档和代码是否出现错误赛题描述。
code/scripts/clean_runtime.sh	清理运行时目录、结果目录和日志文件。
code/scripts/collect_env.sh	收集系统版本、内核、Python、CPU、内存等环境证据，输出到 logs/env.txt。
code/scripts/docker_entrypoint_openeuler.sh	openEuler Docker 容器入口脚本，容器内执行安装、测试和 benchmark。
code/scripts/install_openeuler.sh	openEuler 安装脚本，安装系统包、创建虚拟环境并安装项目。
code/scripts/pull_docker_rootfs.py	辅助拉取 Docker rootfs 的脚本，用于无 Docker 场景的实验准备。
code/scripts/run_all_benchmarks.sh	离线可复现实验入口，运行 text、structured、memory 三模式 benchmark。
code/scripts/run_demo.sh	演示入口脚本，优先启动可选 UI 或提示查看报告。
code/scripts/run_full_live_api.sh	真实在线 LLM 全量实验入口，读取 configs/runtime.env 并输出 results_live/ 与 reports_live/。
code/scripts/run_in_openeuler_docker.sh	基于 Docker 构建并运行 openEuler 容器实验。
code/scripts/run_in_openeuler_proot.sh	基于 proot 的 openEuler 运行尝试脚本，用于特殊无 Docker 环境。
code/scripts/run_live_llm_demo.sh	在线 LLM 小规模 memory 模式演示入口。
code/scripts/run_native_openeuler_full.sh	openEuler 原生完整验证脚本，检查系统、安装依赖、运行测试和 benchmark。
code/scripts/run_tests.sh	测试入口脚本，执行基础 smoke test。
code/scripts/verify_final_artifacts.py	最终交付物校验脚本，检查关键结果、报告和 openEuler 证据是否存在。

tests 和 ui

文件	说明
code/tests/test_smoke.py	基础冒烟测试，验证核心流程可以运行并输出结果。
code/ui/app.py	可选 Streamlit 展示界面，用于查看 benchmark 结果和报告。