1. 系统简介

本项目实现一套面向多智能体协作的低开销运行时原型，围绕赛题要求完成以下核心机制：

• 4 个 Agent 协同完成规划、检索、工具执行和总结任务。
• 同时支持纯文本协作与结构化协议协作，并在相同任务条件下进行对照实验。
• 使用 OS 共享内存传递二进制中间状态和语义向量，消息只携带状态引用。
• 使用 SQLite 保存可标识、可检索、可复用的共享记忆。
• 真实 LLM 输出结构化计划，并实际决定任务步骤、工具调用和记忆摘要。
• 后续任务复用历史工具产物，实际跳过重复工具调用。
• 自动生成原始指标、中文实验结果、消息轨迹和 HTML 可视化页面。

系统面向 openEuler 24.03-LTS-SP3 开发，核心运行时仅依赖 Python 3.10+ 标准库。

Agent	角色	核心职责
PlannerAgent	任务规划	调用 LLM 生成步骤、记忆查询和工具调用计划
RetrieverAgent	信息检索	按任务组、关键词、标签和语义相似度检索共享记忆
ExecutorAgent	工具执行	执行注册工具，或复用历史产物跳过重复工作
SummarizerAgent	总结生成	生成证据关联记忆并写入共享存储

2. 目录结构

.
├── src/
│   └── agent_collab/
│       ├── agents.py          # LLM 决策解析及四类 Agent
│       ├── runtime.py         # 双模式运行时和任务生命周期
│       ├── protocol.py        # 握手、能力发现及动作路由
│       ├── state.py           # OS 共享内存 arena 和状态引用
│       ├── memory.py          # SQLite/JSON 记忆存储及混合检索
│       ├── tools.py           # 可复现的 openEuler 运维工具注册表
│       ├── llm.py             # OpenAI-compatible Provider、重试及缓存
│       ├── embeddings.py      # 本地确定性语义向量生成
│       ├── models.py          # 消息模型及评测指标
│       ├── benchmark.py       # 双模式实验和结果生成
│       ├── visualize.py       # 静态 HTML 页面
│       └── sandbox.py         # 可选的受限 CodeAct 执行环境
├── scripts/
│   ├── run_benchmark.py       # 唯一完整实验入口
│   ├── verify_requirements.py # 赛题要求验收
│   ├── check_llm_config.py    # LLM 配置和连通性检查
│   └── install.sh             # openEuler 安装脚本
├── reports/
│   └── run_YYYYMMDD_HHMMSS_xxxxxx/
│       ├── benchmark_summary.json     # 机器可读的指标事实来源
│       ├── experiment_report.md       # 自动生成的中文实验结果
│       ├── dashboard.html             # 独立静态可视化页面
│       ├── structured_messages.json   # 结构化协议模式的消息轨迹
│       ├── text_messages.json         # 纯文本协作模式的消息轨迹
│       ├── structured_memory.sqlite   # 结构化模式的共享记忆数据库
│       └── text_memory.sqlite         # 纯文本模式的共享记忆数据库
├── tasks.json                 # 两组连续任务及可复现实验数据
├── .env.example               # 不含真实密钥的配置模板
├── pyproject.toml
├── requirements.txt
└── LICENSE

3. 系统总体设计

用户任务
   |
   v
AgentRuntime
   |-- 协议握手、能力发现、动作路由
   |
   |-- PlannerAgent ---- 真实 LLM JSON 决策
   |         |
   |         v
   |   计划状态写入共享内存
   |         |
   |-- RetrieverAgent -- SQLite 混合检索
   |         |
   |         v
   |   plan_ref + retrieval_ref
   |         |
   |-- ExecutorAgent --- 工具执行 / 历史产物复用
   |         |
   |         v
   |   execution_ref
   |         |
   `-- SummarizerAgent - 证据、摘要、策略写入共享记忆

结构化模式启动时，Agent 向 ProtocolRegistry 发布角色和动作能力。运行时建立 action 到 Agent 的映射，例如 plan_task -> planner、execute_plan -> executor，随后所有控制消息都通过统一协议路由。

每项任务的状态依次经历：

1. 用户任务以二进制形式写入共享内存，Planner 只接收 task_ref。
2. Planner 读取 task_ref，使用真实 LLM JSON 决策生成可执行计划。
3. 计划写入共享内存，Retriever 读取 plan_ref，并使用模型生成的 memory_query 检索记忆。
4. Retriever 将命中的 memory_id 写入检索状态。
5. Executor 根据 task_ref、plan_ref 和 retrieval_ref 重新映射状态并执行工具。
6. Summarizer 根据 task_ref 和 execution_ref 读取执行证据并保存共享记忆。
7. Runtime 对每次状态读取执行 schema 与 SHA-256 完整性校验。

4. 双模式通信设计

4.1 纯文本协作模式

纯文本模式表示传统多 Agent 协作。任务、计划、完整记忆记录和执行结果被编码为带边界标记的自然语言与 JSON 文本。接收 Agent 必须从文本中定位载荷并执行 JSON 解码，之后才能继续处理。

该模式不加入等待、循环或人为延迟。所有耗时均来自实际序列化、解析、检索、工具执行和存储操作。

4.2 结构化协议协作模式

结构化模式将消息收敛为动作、参数、结果、能力、状态引用和记忆引用：

{
  "from": "retriever",
  "to": "executor",
  "action": "execute_plan",
  "capability": "executes LLM-selected registered tools",
  "params": {"task_id": "incident-02"},
  "result": {
    "plan_state_id": "state_xxx",
    "retrieval_state_id": "state_yyy"
  },
  "state_refs": [
    {
      "state_id": "state_xxx",
      "segment_name": "ac_xxx",
      "offset": 0,
      "schema": "agent_collab.plan.v1",
      "payload_bytes": 1024,
      "vector_bytes": 384,
      "sha256": "..."
    }
  ],
  "memory_refs": ["mem_xxx"]
}

接收 Agent 不会通过 Python 变量直接获得计划或执行结果，而是根据 segment_name + offset + length 读取共享内存。两种模式使用相同任务、相同 LLM 决策、相同工具和独立记忆数据库，唯一主要变量是协作通信方式。

5. 非文本状态传递设计

StateStore 在运行开始时创建一个固定容量的 OS 共享内存 arena。所有 Agent 复用同一次映射，并使用 64 字节对齐的偏移分配状态，避免为每条状态反复创建共享内存段。

每条状态包括：

• state_id：状态唯一标识。
• segment_name：共享内存 arena 名称。
• offset：状态在 arena 中的起始偏移。
• schema：计划、检索或执行状态版本。
• payload_bytes：pickle protocol 5 二进制负载长度。
• vector_bytes：float32 语义向量长度。
• sha256：负载和向量的完整性校验值。
• owner_agent、kind、created_at：状态元数据。

语义向量由状态摘要生成，用于表达中间状态的紧凑语义特征。接收流程为：校验 task/plan/retrieval/execution schema、映射共享内存、按偏移读取、校验 SHA-256、反序列化负载、读取 float32 向量。评测分别统计状态负载和向量数据量。

6. 共享记忆设计

SharedMemoryStore 正式实验使用 SQLite。每条记忆包含：

• memory_id、source_agent、created_at、task_id、topic。
• summary、content、tags、embedding。
• artifacts、复用来源、LLM 决策来源和执行步骤等 evidence。

检索综合关键词、标签和余弦相似度。任务组标签作为强制过滤条件，避免故障诊断记忆误命中部署加固任务。每组第一个任务没有历史记忆，后续任务才能命中该组的相关记忆。

Executor 按 artifact_key 检查历史 evidence。若历史记忆已保存同一工具产物，Executor 直接复用并增加 avoided_tool_calls；否则执行注册工具并保存新产物。因此记忆命中会实际减少工具执行，而不是只在结果中记录 memory_id。

7. LLM 接入与统一实验

Planner 要求模型返回严格 JSON：

{
  "steps": ["分析证据", "调用工具", "生成结论"],
  "memory_query": "agent-api.service startup failure",
  "tool_calls": [
    {
      "name": "inspect_journal",
      "arguments": {"service": "agent-api.service"},
      "artifact_key": "incident.journal"
    }
  ],
  "memory_summary": "可供后续任务复用的结论"
}

模型输出会实际决定步骤、检索查询、工具及参数和记忆摘要。Runtime 只允许调用任务声明的工具，并补齐场景必须执行的能力。若模型没有返回合法 JSON 或没有选择有效工具，该任务会标记为 task-fallback，正式验收失败，不能再把“成功请求过模型”当作模型已生效。

为了公平比较通信机制，完整实验先为每个唯一任务请求一次真实模型，再让文本模式和结构化模式通过精确 payload 缓存复用同一决策。这样能够同时满足：

• 真实模型参与并控制任务行为。
• 两种模式得到完全相同的语义输入。
• 模型网络波动不被错误计入某一种通信模式。
• 10 个任务通常只需 10 次成功模型生成，重试单独计数。

Provider 支持 timeout、指数退避、可重试 HTTP 状态码、thinking 开关、精确响应缓存和脱敏运行元数据。公开使用只保留一次完整真实模型实验。

8. 工具执行与 CodeAct

Executor 使用 ToolRegistry 执行注册工具。当前可复现实验工具包括：

• systemd journal 故障签名提取。
• systemd unit 依赖及加固配置检查。
• 端口和进程快照检查。
• 环境变量名称完整性检查，不读取或输出密钥值。
• 敏感文件权限检查。
• 服务健康验证和证据报告生成。

这些工具处理 tasks.json 中固定的日志、unit、网络和权限快照，保证评委可以在相同输入上复现实验。sandbox.py 另提供可选 CodeAct 原型，使用 AST 白名单限制 import、属性访问和危险调用；正式基准默认不依赖 CodeAct 加分项。

9. 任务设计

tasks.json 包含两个任务组，每组 5 个连续任务。

9.1 服务故障诊断组

1. 从 agent-api.service journal 提取初始故障签名。
2. 复用 journal 证据并检查 systemd unit。
3. 复用故障签名并检查端口冲突。
4. 复用 unit 结果，检查环境配置并生成修复方案。
5. 复用初始证据，验证服务并生成最终故障结论。

9.2 部署加固组

1. 检查 LLM 环境变量名称完整性。
2. 复用环境审计并检查 systemd 加固项。
3. 复用 unit 结果并检查敏感文件权限。
4. 复用权限结果并检查端口可用性。
5. 复用环境和权限产物，完成服务验收和部署报告。

实验数据使用 fixture 与 task 分离的结构，避免重复内容，同时保留任务依赖、工具约束、预期证据和复用键。10 轮覆盖两组完整任务，满足不少于 10 轮连续运行要求。

10. 实验报告设计

10.1 对照原则

• 两种模式使用相同的 10 个任务和顺序。
• 两种模式复用同一批真实 LLM 决策。
• 两种模式调用同一 ToolRegistry。
• 两种模式分别使用独立 SQLite 数据库和状态空间。
• 比较前校验逐任务 result_digest，语义一致率必须为 100%。
• 不使用 sleep、重复 embedding 或人为计算放大文本模式耗时。

10.2 指标体系

指标	含义
messages	Agent 间消息数
text_chars / wire_bytes	通信字符数及 UTF-8 字节数
estimated_tokens	与模型 tokenizer 无关的确定性 token 估算
protocol_seconds	实际协议编码、状态写入、状态读取和解码耗时
total_task_seconds	包含检索、工具和存储的任务执行耗时
llm_seconds	模式执行阶段的模型调用或缓存读取耗时
state_transfers	接收 Agent 实际读取共享状态的次数
state_payload/vector_bytes	二进制负载和 float32 向量规模
state_integrity_checks	成功完成的状态完整性校验次数
memory_hit_rate	相关任务组内的记忆查询命中率
executed_tool_calls	实际执行的工具调用数
avoided_tool_calls	通过历史产物避免的工具调用数
semantic_equivalence_rate	两模式逐任务结果一致率
llm_decisions_applied	真正采用的真实 LLM 决策数

端到端时间会受 SQLite I/O 和系统调度影响，因此报告同时公开任务总耗时和更聚焦于通信机制的 protocol_seconds，不隐藏负收益或外部波动。

10.3 输出文件

每次运行只创建一个独立目录：

reports/run_YYYYMMDD_HHMMSS_xxxxxx/
├── benchmark_summary.json
├── experiment_report.md
├── dashboard.html
├── structured_messages.json
├── text_messages.json
├── structured_memory.sqlite
└── text_memory.sqlite

benchmark_summary.json 是机器可读事实来源；experiment_report.md 是自动生成的中文实验结果；dashboard.html、消息日志和 SQLite 数据库均由同一次运行产生。项目不会生成 latest_run.txt、根目录结果副本或预置历史结果。

10.4 验收规则

scripts/verify_requirements.py 不只检查文件存在，还检查：

• Agent 数量、角色、协议握手、能力发现和动作路由。
• 双模式均完成至少 10 项任务和两组连续依赖。
• 状态引用包含 segment、offset、schema、长度和 SHA-256。
• 每次状态读取均通过完整性校验。
• 记忆命中实际避免工具调用。
• 通信量和协议处理耗时相对文本模式得到改善。
• 两模式任务结果 100% 等价。
• 正式运行的每项任务都采用真实 LLM 决策且没有回退。
• 源码、任务数据、报告、页面、日志和数据库完整。

11. 部署与运行

11.1 环境要求

• openEuler 24.03-LTS-SP3。
• Python 3.10+，推荐 Python 3.11。
• 正式实验需要 OpenAI-compatible Chat Completions API。
• SQLite 和 multiprocessing.shared_memory 均来自 Python 标准库。

11.2 安装

cd /home/openeuler/vv/openos
bash scripts/install.sh
source .venv/bin/activate

也可以不创建虚拟环境，直接在项目根目录运行脚本。

11.3 配置真实模型

cp .env.example .env

编辑 .env：

AGENT_COLLAB_LLM_PROVIDER=openai-compatible
AGENT_COLLAB_LLM_ENDPOINT=https://your-provider.example/v1/chat/completions
AGENT_COLLAB_LLM_API_KEY=REPLACE_WITH_YOUR_API_KEY
AGENT_COLLAB_LLM_MODEL=REPLACE_WITH_YOUR_MODEL
AGENT_COLLAB_LLM_TIMEOUT_SECONDS=90
AGENT_COLLAB_LLM_MAX_TOKENS=512
AGENT_COLLAB_LLM_MAX_RETRIES=3
AGENT_COLLAB_LLM_RETRY_BACKOFF_SECONDS=2
AGENT_COLLAB_LLM_THINKING_MODE=disabled

检查配置和真实响应：

python3 scripts/check_llm_config.py --require-real
python3 scripts/check_llm_config.py --probe

检查结果只显示 api_key_present，不输出密钥明文。

11.4 运行完整实验

项目只保留这一套实验流程。首次运行前检查配置：

python3 scripts/check_llm_config.py --require-real

执行完整实验：

python3 scripts/run_benchmark.py

默认自动完成：

• 10 个连续关联任务。
• 纯文本与结构化协议两种模式。
• 真实 LLM 结构化决策。
• SQLite 共享记忆及跨任务复用。
• OS 共享内存状态传递。
• 通信、耗时、状态、记忆和结果一致性评测。
• 中文实验结果及 HTML 页面生成。

运行结束后验收：

python3 scripts/verify_requirements.py

不需要为正常实验传入 rounds、tasks、output、memory 或 LLM 调优参数；默认配置就是完整比赛实验。

11.5 查看结果

RUN_DIR=$(find reports -maxdepth 1 -type d -name 'run_*' | sort | tail -n 1)
cat "$RUN_DIR/experiment_report.md"

生成的 dashboard.html 是独立静态文件，可以下载到本机后直接打开，不依赖 Web 服务。