LiteAgentOS——面向多智能体的按需信息传递与可验证经验复用系统

项目简介

LiteAgentOS 是面向多智能体协作的系统层原型，运行于 openEuler / Linux 用户态。系统以统一协议组织任务规划、资料检索、工具执行、结果总结和质量审查，让 Agent 按需交换信息，并将经过验证的任务经验用于后续任务。

项目围绕三个机制展开：结构化引用通信、非文本状态交换、可验证共享记忆。既保留纯文本协作作为对照，也记录消息、模型调用、状态资源和经验应用过程，使优化效果能够追溯到具体传输内容与执行步骤。

完整作品备份下载

决赛提交内容已整理为百度网盘备份，便于整体下载源码、测试与实验数据、项目文档、演示 PPT 和视频。

• 备份文件：LiteAgentOS决赛作品.rar
• 下载链接：百度网盘 · LiteAgentOS 决赛作品
• 提取码：cjg3

仓库中保留完整提交文件，模型及演示媒体均通过普通 Git 保存。网盘提供提交内容的整包备份，后续更新以仓库提交记录为准。

1. 应用场景

场景	处理过程
知识分析与检索增强生成	从领域知识库或网络来源获取资料，组织证据并生成回答。
复杂任务规划	拆解目标与约束，按能力调度 Agent，根据执行结果调整后续步骤。
代码协作与数据处理	生成或修复 Python 代码，执行工具与测试，汇总当前产物和结果。
连续任务与经验积累	在相关任务中复用适用的证据、策略或局部修复方法，并重新验证当前结果。

仓库内置 Linux / 操作系统、项目管理两类知识库示例，并提供数据处理与接口适配的连续代码任务实验。办公场景可围绕会议纪要、行动清单和数据报告组织任务；外部办公软件接入需通过工具接口适配。

2. 主要功能与系统流程

2.1 三项核心机制

机制	实现方式	可观察内容
按需信息传递	用动作、参数、结果组织协作消息；长证据和产物以引用传递；接收者按角色、当前动作及预算选择必要上下文。	消息次数、序列化字节、Wire Token、上下文选择记录、Provider 输入与输出 Token。
非文本状态交换	将查询向量、证据质心等中间表示封装为 StatePacket，支持 float32、float16、int8；Linux 多进程模式通过 UDS 传控制消息、共享内存传二进制状态。	状态生成、传递、消费、决策与释放记录，以及数据规模和编码误差。
可验证经验复用	统一记忆模型与选择性写入，处理重复和冲突；召回后检查适用性、安全与时效，按角色提供短卡和引用，由运行时校验采纳动作并验证当前结果。	记忆来源、写入决策、召回／注入／采纳／有效复用记录、当前测试结果与成本反馈。

能力描述由 AgentCard 和控制握手提供，支持能力注册与发现；并非只把完整自然语言包进 JSON。共享记忆中的经验提炼、多因素检索与成本选择均通过现有服务和策略组织，不需要为不同实验复制一套执行流程。

2.2 多 Agent 协作

系统按 Planner、Research、Executor、Summarizer、Critic 五类业务职责组织协作。Research 由本地 RetrieverAgent 与 WebSearchAgent 承担；MemoryService 提供共享记忆服务，MemoryAgent 保留消息访问入口。完整配置可注册七个 Agent 实现，单次任务只调度必要角色。

任务与约束
    ↓
规划与能力路由 ← 适用的记忆短卡
    ↓
按需检索 / 工具或代码执行
    ↓
基于当前证据与产物总结
    ↓
质量审查 ── 不满足要求 → 补充资料 / 修复 / 重规划
    ↓
返回结果、选择性保存经验、反馈应用效果、回收状态资源

记忆处理明确区分“召回、注入、声明采纳、实际应用、验证有效”：收到一条历史记忆不等于完成复用；应用旧修复后仍需执行当前任务测试。直接返回历史答案采用比策略、证据和组件复用更严格的条件。

2.3 运行与观测

• Web 协作运行台：提交任务，查看动态协作图、阶段状态、最终回答及产物。
• 三项机制演示页：分别解释通信、状态与记忆流程，并展示当前任务的真实证据。
• 任务与资源管理：查看历史记录、知识与记忆、安全执行、运行节点及底层日志。
• 统一命令行与实验入口：支持配置查看、任务运行、实验套件和 Provider 连通性检查。
• CodeAct 执行：支持模型生成 Python 代码、执行前检查、受限运行和结果回传；可选择 Podman 容器后端。

3. 系统环境与依赖要求

项目	要求或用途
目标系统	openEuler 24.03-LTS-SP3，x86_64；多进程 UDS 与正式资源管理验证在 Linux 环境进行。
Python	以 Python 3.11 为复现环境，已保存目标环境实验使用 3.11.6；使用独立虚拟环境安装依赖。
MySQL / MariaDB	存储知识与记忆元数据、来源关系及审计记录；数据库用户需具备项目库的建表和迁移权限。
Qdrant	知识与记忆向量检索；多进程及 Web 与实验并行运行时使用独立 Qdrant Server。
Embedding	默认 BAAI/bge-small-zh-v1.5，由 FastEmbed 加载；首次使用需下载模型或准备本地缓存。
LLM 服务	OpenAI Chat Completions 兼容接口，支持 JSON 响应模式并返回 usage；需自行配置可用模型和密钥。
Podman	可选，用于容器化代码执行或部署 Qdrant；沙箱资源限制须由宿主机实际支持。

Python 依赖以 requirements.txt 为准：PyMySQL、requests、python-dotenv、qdrant-client / FastEmbed、NumPy、tiktoken、LangGraph、FastAPI、Uvicorn。测试另需安装 pytest。

真实 LLM 与网络检索需要可用网络及正确的系统时间；本地向量检索需要完整的 Embedding 模型缓存。规则模式可用于不调用外部 LLM 的基础功能检查。

4. 构建与安装方法

项目为 Python 源码程序，前端由后端提供静态文件，无需单独执行 C/C++ 编译或 npm 构建。以下 Bash 命令均在源码根目录执行，该目录应包含 liteagent/、configs/ 和 requirements.txt。

4.1 创建虚拟环境

先准备 Python 3.11 解释器，并确认下面的 python3 指向该版本：

python3 --version
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m pip install pytest
python -m pip check

Windows 本地界面开发可用 py -3.11 -m venv .venv 创建环境，再执行 .\.venv\Scripts\Activate.ps1；其余单行 Python 命令相同。本文多行命令中的 \ 为 Bash 续行符，PowerShell 下请合并成一行。

4.2 配置数据库与环境变量

已有 MySQL / MariaDB 服务可直接使用；openEuler 上也可安装并启动 MariaDB：

sudo dnf install -y mariadb-server
sudo systemctl enable --now mariadb
sudo mariadb

在数据库管理终端创建项目专用账户，将示例密码替换为自己的密码：

CREATE DATABASE IF NOT EXISTS liteagentos
  CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER IF NOT EXISTS 'liteagent'@'127.0.0.1'
  IDENTIFIED BY 'REPLACE_WITH_A_STRONG_PASSWORD';
GRANT ALL PRIVILEGES ON liteagentos.* TO 'liteagent'@'127.0.0.1';
FLUSH PRIVILEGES;
EXIT;

首次安装时复制配置模板；已有 .env 时保留原文件，不要覆盖：

cp -n .env.example .env
chmod 600 .env

编辑根目录 .env，至少填写以下内容，所有占位值均需替换：

LITEAGENT_MYSQL_HOST=127.0.0.1
LITEAGENT_MYSQL_PORT=3306
LITEAGENT_MYSQL_USER=liteagent
LITEAGENT_MYSQL_PASSWORD=REPLACE_WITH_A_STRONG_PASSWORD
LITEAGENT_MYSQL_DATABASE=liteagentos

LITEAGENT_LLM_API_KEY=YOUR_API_KEY
LITEAGENT_LLM_BASE_URL=https://YOUR_PROVIDER_HOST
LITEAGENT_LLM_MODEL=YOUR_MODEL_ID

LITEAGENT_EMBEDDING_MODEL=BAAI/bge-small-zh-v1.5
LITEAGENT_EMBEDDING_CACHE=.cache/fastembed
LITEAGENT_EMBEDDING_THREADS=1
LITEAGENT_QDRANT_URL=http://127.0.0.1:6333
LITEAGENT_RETRIEVAL_MODE=hybrid

当前客户端会在 LITEAGENT_LLM_BASE_URL 后追加 /v1/chat/completions，因此不要重复填写 /v1 或完整请求路径。模型必须使用服务商实际支持的 ID；配置示例不包含可用凭据。若需使用系统代理，显式设置 LITEAGENT_LLM_TRUST_ENV=1，并正确配置代理和本地服务直连规则。

4.3 启动向量服务

已部署 Qdrant Server 时，将其地址填入上述变量即可。以下是在安装 Podman 后启动本机服务的示例：

sudo dnf install -y podman
mkdir -p "$HOME/.local/share/liteagentos/qdrant"
podman run -d --name liteagentos-qdrant \
  -p 127.0.0.1:6333:6333 \
  -v "$HOME/.local/share/liteagentos/qdrant:/qdrant/storage:Z" \
  docker.io/qdrant/qdrant:v1.18.2
curl --fail http://127.0.0.1:6333/readyz

容器已存在时使用 podman start liteagentos-qdrant，不要重复创建。仅做单进程本地调试时，可以将 LITEAGENT_QDRANT_URL 留空并设置 LITEAGENT_QDRANT_PATH=data/qdrant；多个进程不能同时打开同一个嵌入式目录。

4.4 初始化与构建知识索引

python init_mysql.py
python build_rag_index.py --list
python build_rag_index.py --knowledge-base linux_os --namespace default
python build_rag_index.py --knowledge-base project_management --namespace default
python -m liteagent config
python -m liteagent suites

索引命令会重建指定知识库和 namespace 的向量集合，使用新 namespace 时应构建对应索引，不要对正在使用的实验集合重复执行。第一次构建会加载模型，离线部署需事先准备依赖与 .cache/fastembed 模型缓存。

数据库就绪后检查真实 LLM 连接：

python -m liteagent doctor

该命令会检查数据库并发起一次真实模型 JSON 请求，可能产生 API 费用。确认 JSON 解析成功后再运行真实模型任务。

5. 运行方法

5.1 Web 界面

python -m liteagent_web.app --host 127.0.0.1 --port 8000

浏览器打开 **http://127.0.0.1:8000/**。在协作运行台输入任务，选择知识库和运行策略，再查看协作流程、最终回答及三项机制的证据。需要局域网访问时可将 --host 改为 0.0.0.0，并自行限制访问范围。

5.2 规则模式冒烟检查

以下命令显式关闭共享记忆和状态，采用同进程规则流程，不调用外部 LLM，可先确认基础链路可运行：

python -m liteagent demo \
  --mode structured --communication-policy structured \
  --state-policy off --memory-policy off --runtime in_process \
  --namespace readme_smoke \
  --task "分析时间片轮转调度，并生成一个最小 Python 示例"

规则模式用于功能检查，不作为真实 LLM 效果实验。

5.3 真实 LLM 与共享记忆任务

完成数据库、向量服务和索引初始化后执行：

python -m liteagent demo \
  --mode llm_memory --communication-policy structured_ref \
  --state-policy shm_float16 --memory-policy read_write \
  --runtime in_process --knowledge-base linux_os --namespace default \
  --task "为交互任务与批处理并存的系统设计时间片调优方案，说明监测指标、适用条件和验证步骤"

随后在相同知识库与记忆空间执行关联任务，例如“负载改为 CPU 密集型批处理，说明哪些已有调优方法仍适用、哪些需要调整”。记忆是否被采用取决于适用性和当前验证，不要求每个相关问题都直接返回历史答案。

在 openEuler 上演示多进程时，将上面命令中的 --runtime in_process 改为 --runtime multi_process，并确保使用 Qdrant Server。Web 高级设置可分别指定任务 namespace 和 memory_namespace；连续任务共享同一记忆空间，不同实验条件使用独立空间。

5.4 常用策略

配置项	常用值
通信 --communication-policy	text_natural、structured_inline、structured_ref
状态 --state-policy	off、json_float32、shm_float32、shm_float16、shm_int8
记忆 --memory-policy	off、read_only、write_only、read_write
运行时 --runtime	in_process、multi_process
知识库 --knowledge-base	linux_os、project_management

正式默认配置见 configs/system.json。CLI 会补入其中未显式指定的策略；做无记忆或无状态对照时，务必明确设置 off。自然文本真实模型模式使用 --mode llm_text_natural --communication-policy text_natural，其他策略保持与对照组一致。

CodeAct 默认使用子进程后端；启用容器后端需在 .env 中设置 LITEAGENT_SANDBOX=podman，安装 Podman 并执行 podman pull docker.io/library/python:3.11-alpine 准备默认镜像；离线环境需提前导入镜像。镜像及资源参数见 代码运行器。

6. 测试方法

6.1 自动化测试

在项目根目录、虚拟环境中执行：

python -m pytest -q

测试覆盖消息协议、状态编解码与生命周期、记忆写入与复用边界、计划采纳、代码验证、模型失败路径及 Web 接口等。通过数、跳过项和预期失败项以本次输出为准；自动化测试不能替代真实服务与目标平台验证。

可先运行一组较小的关键回归：

python -m pytest -q \
  tests/test_cleanup_architecture.py \
  tests/test_memory_collaboration_contract.py \
  tests/test_protocol_json_codec.py \
  tests/test_state_lifecycle.py \
  tests/test_code_answer_grounding.py

6.2 通信、状态与记忆实验

先准备所需外部服务，每次运行使用新的 suite-id。带 LLM 的实验会产生实际调用费用；以下命令用于启动实验，不代表预先保证结果达到某个百分比。

# 自然文本、结构化内联与结构化引用对照
python -m liteagent experiment fair --suite-id readme_fair_001 --rounds 3

# 状态编码、传输与决策消融；在 Linux 上运行
python -m liteagent experiment state \
  --suite-id readme_state_001 --rounds 3 --runtime multi_process

# 操作系统、项目管理两组连续任务
python -m liteagent experiment memory --suite-id readme_memory_001

# 当前完整代码任务链：数据处理、接口适配；包含学习、正例与负例
python -m experiments.full_memory_chains \
  --suite-id readme_code_memory_001 --repetitions 3 --positive-reuses 2

full_memory_chains 比较 M0 无记忆与 M3 验证后复用，检查调用方预设断言、最终回答与测试产物一致性，并统计整条任务链成本。更细的记忆分项实验入口为 python -m liteagent experiment memory-economics --help 和 python -m liteagent experiment memory-plan --help。

6.3 连续运行与安全执行

# 多进程连续 10 轮，默认规则推理，用于运行时稳定性检查
python -m liteagent experiment stability --suite-id readme_stability_001 --rounds 10

# 真实 LLM 连续 10 轮：另用一组标识，单独保存结果
python -m liteagent experiment stability \
  --suite-id readme_stability_llm_001 --rounds 10 --use-llm

# Podman 已安装、镜像已准备后，执行安全沙箱用例
python -m liteagent experiment sandbox --suite-id readme_sandbox_001

稳定性测试关注任务结果、进程与心跳、UDS 和共享内存资源回收。真实模型实验应额外核对 Provider 调用成功、usage 完整及失败／降级记录；状态检索命中率和 Critic 接受率不等同于独立答案准确率。

6.4 查看实验数据

运行日志和结果位于 experiments/runs/，具体文件依套件而定，通常包含配置或 manifest、JSONL 逐任务记录、结果摘要与执行产物。已整理的当前版本实验依据见 实验报告与汇报口径，其他分项报告见 experiments/reports/。

指标分别核算：Wire Token 衡量 Agent 间序列化文本，Provider Token 来自模型 API 的实际 usage，状态字节衡量非文本数据面。记忆实验同时检查实际省掉的工作、当前质量和前置学习成本；不将三类指标相加为一个节省率。

7. 代码目录

LiteAgentOS/
├── liteagent/
│   ├── agents/          # 规划、检索、执行、总结和审查角色
│   ├── runtime/         # 任务调度、协议分发、多进程、IPC 与遥测
│   ├── protocol/        # 统一消息、自然文本基线、控制握手
│   ├── context/         # 接收者上下文、卡片选择与预算
│   ├── state/           # StatePacket、编解码、交换与资源回收
│   ├── memory/          # MemoryService、写入、检索、经验学习与验证复用
│   ├── contracts/       # 记忆与状态引用接口契约
│   ├── knowledge/       # 知识库插件
│   ├── rag/             # 检索增强生成
│   ├── embedding/       # 语义向量生成
│   ├── vector/          # 向量存储适配
│   ├── storage/         # 数据库持久化
│   ├── tools/           # 工具与代码沙箱
│   ├── llm/             # 模型接口、响应解析和错误处理
│   └── eval/            # 指标与评估支持
├── liteagent_web/       # Web API 与静态界面
├── configs/             # 正式配置与实验配置归档
├── knowledge_bases/     # 领域知识库及插件描述
├── experiments/         # 实验脚本、原始数据与报告
├── tests/               # 自动化测试
├── deploy/              # 部署配置参考
├── docs/                # 设计与开发说明
├── archive/             # 兼容运行器；部分由统一 CLI 调用，需保留
├── init_mysql.py        # 数据库初始化与迁移
├── build_rag_index.py   # 知识索引构建
├── requirements.txt    # Python 依赖
├── .env.example        # 环境变量模板
└── README.md

新增 Agent、知识来源或工具时，通过能力注册、消息映射及 contracts 接入；记忆策略集中在 MemoryService，状态实现集中在状态交换层。部分 Agent 内部流程使用 LangGraph，外层协作协议、引用交换和多进程调度由 LiteAgentOS 组织。

8. 已知限制

真实模型任务依赖外部服务，端到端时延会受网络、模型后端与冷启动影响。UDS 多进程验证以 Linux 为准，默认子进程执行不等同于容器强隔离，正式沙箱演示需启用并核查 Podman 后端。

9. 配置与提交注意事项

• .env 仅用于本地凭据，不提交 API Key、数据库密码、个人账户或含敏感内容的截图。
• 启动服务、重建索引和实验前确认 namespace；保留原始失败记录，不覆盖已有实验结果。
• 本 README 对应当前源码入口；历史报告保留各自实验日期和条件，不能直接当作新版本已复测的结果。