MAOS-Lite

MAOS-Lite 是一个完全离线、确定性运行的多智能体协作原型，围绕赛题要求实现四项核心能力：四 Agent 协同、纯文本与结构化协议对比、共享内存非文本状态传递、SQLite 跨任务共享记忆。

本版本以“可复现、可解释、能在 openEuler 24.03-LTS-SP3 上部署”为目标，不依赖在线大模型、API Key、外部数据库或 Docker。

1. 已实现功能

四类 Agent：Planner、Retriever、Executor、Summarizer。
握手与能力发现：每次运行先发送 HELLO、CAPABILITY 和 ACK，能力通过 CapabilityRegistry 注册后才允许调度。
两种通信模式：
- text 使用带必要路由头部的自然语言文本信封；
- struct 使用紧凑 AgentMessage JSON，只发送接收方实际需要的语义字段。
非文本状态传递：Retriever 的证据摘要生成 384 维 float32 embedding，写入 Linux /dev/shm 内存文件，并通过 mmap 供 Executor 读取；Executor 计算余弦相似度，结果实际参与记忆复用决策。
共享记忆：SQLite 保存 memory ID、来源 Agent、创建时间、任务主题、摘要、正文、标签和元数据；检索融合关键词、主题标签和向量相似度。
可靠复用：只有主题一致、综合分过阈值、状态相似度过阈值且记忆标记为可复用时，Executor 才跳过重复工具调用。测试中包含无关三角形任务负例。
真实 Unix Socket：UDSBus 使用 AF_UNIX、长度前缀帧和 Socket 文件清理完成本地结构化消息往返。
轻量 CodeAct 演示：CodeTool 对代码进行规则校验，在独立子进程中执行，并提供超时终止机制。
评测与追踪：输出 CSV、JSON、Markdown，统计消息数、字符、UTF-8 字节、token 估算、P50/P95、状态读写、记忆命中、工具节省和错误复用。

2. 赛题要求对应关系

赛题要求	本项目实现
不少于 3 个 Agent	4 个 Agent：规划、检索、执行、总结
复杂多步骤任务	规划→检索→状态生成→执行/复用→总结→记忆沉淀
动作、参数、结果、能力描述	`AgentMessage` 与 `CapabilityDescriptor`
握手、能力发现或协议映射	HELLO、CAPABILITY、ACK、`CapabilityRegistry`
纯文本与结构化模式	`TextBus` 与 `StructBus`
非文本中间状态	Retriever 证据 embedding、共享内存、`StateRef`、Executor 相似度使用
共享记忆元数据	`MemoryItem` 完整字段与 SQLite 持久化
关键词、标签、语义检索	混合检索器与 NumPy 余弦索引
至少 2 组连续任务	赛题、架构、部署、测试等多组关联任务，另含负例
不少于 10 轮	`configs/scenarios.yaml` 固定 10 轮
性能统计	通信、时延、状态、记忆、工具调用、错误复用等指标
openEuler 交付	`scripts/init_env.sh`、`scripts/verify_openeuler.sh`，已在 24.03-LTS-SP3 实机通过

3. 架构

CLI / EvalRunner
        │
        ▼
Runtime ── Handshake ── CapabilityRegistry ── TraceManager
        │
        ▼
FixedPipelineScheduler
        │
        ├── PlannerAgent
        ├── RetrieverAgent ── HybridRetriever ── SQLite / VectorIndex
        │                         │
        │                         └── evidence text
        │                                  │ embedding
        │                                  ▼
        │                         SharedMemoryStateStore
        │                                  │ StateRef
        ├── ExecutorAgent ◄─────────────────┘
        └── SummarizerAgent ── MemoryWriter
        │
        ▼
TextBus / StructBus / UDSBus

详细设计、部署方法和实验结果见随提交材料提供的 项目说明书.docx。

4. 环境要求

Python 3.10 或更高版本；建议 Python 3.11。
Linux x86_64 或 aarch64；目标系统为 openEuler 24.03-LTS-SP3。
/dev/shm 可用。
安装依赖时需要访问 Python 包源；运行和评测阶段完全离线。

5. Linux/openEuler 安装

openEuler 首次准备系统依赖：

sudo dnf install -y python3 python3-pip python3-devel gcc gcc-c++ git

进入项目根目录：

bash scripts/init_env.sh
source .venv/bin/activate

手动安装等价命令：

python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip setuptools wheel
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m pip install -e .

6. 快速运行

.venv/bin/python -m maos.main init

.venv/bin/python -m maos.main compare \
  --task "分析赛题通信协议、状态传递和共享记忆要求"

.venv/bin/python -m maos.main run \
  --mode text \
  --task "分析赛题通信协议、状态传递和共享记忆要求"

.venv/bin/python -m maos.main run \
  --mode struct_state_memory \
  --task "分析赛题通信协议、状态传递和共享记忆要求"

.venv/bin/python -m maos.main scenario \
  --scenario contest_analysis \
  --mode struct_state_memory

四种模式：

模式	通信	非文本状态	共享记忆
`text`	自然语言	否	否
`struct`	紧凑 JSON	否	否
`struct_state`	紧凑 JSON	共享内存 embedding	否
`struct_state_memory`	紧凑 JSON	共享内存 embedding	SQLite 混合检索与复用

7. 测试与完整评测

.venv/bin/python -m pytest -q

.venv/bin/python -m maos.main eval \
  --modes text,struct,struct_state,struct_state_memory \
  --rounds 10 \
  --scenarios configs/scenarios.yaml \
  --out reports/eval_report.md

完整 openEuler 验收：

bash scripts/verify_openeuler.sh

在非 openEuler Linux 上预验证：

REQUIRE_OPENEULER=0 bash scripts/verify_openeuler.sh

8. openEuler 验收结果

本项目已在以下目标环境完成验收：

openEuler 24.03 (LTS-SP3) x86_64
Python 3.11.6

验收包括：

90 项 pytest 测试；
状态包新进程独立导入；
wheel 构建和 pip check；
四模式各 10 轮；
共享内存创建、读取和释放；
相关任务记忆复用与无关任务负例；
UDS 真正 AF_UNIX 往返；
CodeTool 死循环超时终止。

REQUIRE_OPENEULER=1 bash scripts/verify_openeuler.sh 已完整输出 === 验收通过 ===。具体数值以 reports/eval_summary.json 和逐轮 CSV 为准。

完整 openEuler 实机验收日志：reports/openeuler_validation.log。评审可通过同一脚本复验。

9. 目录结构

configs/                 默认配置与十轮场景
reports/                 评测 CSV、JSON 数据
scripts/                 环境初始化与 openEuler 验证
src/maos/agents/         四类 Agent
src/maos/protocol/       协议、编解码、握手
src/maos/runtime/        Bus、调度、注册、Trace、运行装配
src/maos/state/          embedding、共享内存、mmap、StateRef 生命周期
src/maos/memory/         SQLite、混合检索、向量索引、写入
src/maos/tools/          本地分析和轻量 CodeTool
src/maos/eval/           场景、指标、报告
tests/                   单元、集成、负例和 CLI 测试

10. 实验口径与实现范围

Agent 使用确定性离线规则与本地工具，使各模式能够在相同任务和步骤下重复比较。
token_estimate 用统一公式近似；通信结论以可直接复核的字符数和 UTF-8 字节数为主。
四 Agent 主链路通过 StateRef 交换 shared memory 状态；UDS 模块验证 AF_UNIX 结构化消息往返。
CodeTool 面向项目内的小型受控代码演示，提供规则校验、独立进程和超时终止。
通信、状态、记忆和时延分别统计；记忆效果由有效命中和跳过重复工具调用衡量。

11. 许可证

Apache License 2.0。第三方依赖分别遵循其自身许可证。

12. 仓库交付内容

GitLink 仓库包含完整项目源码、README、测试、配置、评测数据和以下三份正式文档：

scripts/verify_openeuler.sh 会在验收过程中构建并检查 wheel。演示视频由参赛队按赛事平台要求录制和提交。