目录
master
分支1
标签0
+ 疑修
Web IDE
Sheng Li
 change readme
3个月前30次提交
README.md

AgentLink-Mem

面向多智能体的低开销通信、状态传递与共享记忆运行时。项目使用 Planner、Retriever、Executor、Reviewer 四个 Agent 完成操作系统故障诊断， 并比较四种协作模式：

模式 协作机制
A 纯文本基线，不使用记忆
B MessagePack 结构化协议
C 结构化协议 + state_ref 状态交换
D 状态交换 + 跨任务记忆自动复用

1. 系统框架

FastAPI 任务入口
       │
       ▼
LangGraph 多 Agent 流程
Planner → Retriever → Executor → Reviewer
       │
       ├─ OpenAI-compatible / Mock Provider
       ├─ 只读操作系统诊断工具
       ├─ MessagePack 结构化协议
       ├─ shared_memory 状态交换
       └─ SQLite 持久共享记忆
       │
       ▼
JSON / CSV / Markdown 报告 / Dashboard

核心指标：

  • Input Token：模型收到的输入 Token，包括系统指令、任务和必要证据。
  • Total Token：Input Token + Output Token，按任务内所有模型调用求和。
  • 端到端延迟：从提交任务到 Reviewer 给出最终结果的墙钟时间，包含模型、 工具采集和运行时处理。

真实 API 实验的 Token 只读取 Provider usage；缺失时保持 null，不使用估算值补齐。

2. 实验真实性

平台 场景 数据来源
Windows systemd 启动缓慢 固定模拟数据，simulated=true
Windows 高 CPU psutil 真实采集，simulated=false
openEuler systemd 启动缓慢 真实 systemd 采集，simulated=false
openEuler 高 CPU 真实 Worker 与进程采集，simulated=false
openEuler 连续相关联任务 多个相关联任务，simulated=false

Windows 没有 systemd，不能把 Windows systemd 结果解释为真实操作系统证据。

3. 通用准备

要求：

  • Python 3.11
  • Windows 10/11，或 openEuler 24.03-LTS-SP3
  • 核心运行时代码保持干净；Tag 为可选项，Benchmark 外围改动会被记录
  • 正式实验使用真实 OpenAI-compatible Provider

复制环境文件：

LLM_PROVIDER=openai_compatible
LLM_API_KEY=<请填写自己的 Key>
LLM_BASE_URL=<OpenAI-compatible API 地址>
LLM_MODEL=<模型名称>
LLM_TIMEOUT_SECONDS=120
LLM_MAX_RETRIES=2
LLM_TEMPERATURE=0

不要提交 .env，不要在日志或视频中展示 API Key。

4. Windows 测试

4.1 安装与门禁

在 PowerShell 中执行：

cd <项目目录>

py -3.11 -m venv .venv
$python = (Resolve-Path .\.venv\Scripts\python.exe).Path

& $python -m pip install --upgrade pip
& $python -m pip install -r requirements.txt
Copy-Item .env.example .env

& $python --version
& $python -m pytest
git status --short

预期：Python 为 3.11、pytest 全部通过、正式实验前 git status --short 没有输出。

4.2 启动 Dashboard

cd E:\ProgramFiles\code\mycode\os-agent-system

$env:BENCHMARK_DASHBOARD_ROOT = `
    (Resolve-Path .\data\benchmark_results).Path

& "E:\ProgramFiles\.conda\conda_envs\os_agent_system_311\python.exe" `
    -m uvicorn app.web.dashboard_app:app `
    --host 127.0.0.1 `
    --port 8765

浏览器访问：

http://127.0.0.1:8765/benchmark-dashboard

4.3 Windows systemd 单轮测试

该场景使用模拟 systemd 数据，但使用真实 LLM API。

cd E:\ProgramFiles\code\mycode\os-agent-system
git status --short
$python = "E:\ProgramFiles\.conda\conda_envs\os_agent_system_311\python.exe"
$stamp = Get-Date -Format "yyyyMMdd_HHmmss"
$output = "data\benchmark_results\wp8_windows_systemd_simulated_$stamp"

& $python .\scripts\run_wp7_real_api_benchmark.py `
  --allow-real-api `
  --scenario systemd `
  --rounds 1 `
  --temperature 0 `
  --thinking-mode disabled `
  --modes `
    A_text_memory_disabled `
    B_protocol_memory_disabled `
    C_protocol_state_exchange `
    D_protocol_state_auto_reuse `
  --output-dir $output

共执行 1 × 4 = 4 个任务。

4.4 Windows 高 CPU 单轮测试

$stamp = Get-Date -Format "yyyyMMdd_HHmmss"
$output = "data\benchmark_results\windows_cpu_1round_$stamp"

& $python .\scripts\run_wp7_real_api_benchmark.py `
    --allow-real-api --preflight `
    --scenario cpu --rounds 1 --temperature 0 `
    --thinking-mode disabled `
    --modes A_text_memory_disabled B_protocol_memory_disabled `
        C_protocol_state_exchange D_protocol_state_auto_reuse `
    --cpu-load-workers 2 --cpu-load-duration 120 `
    --output-dir $output

脚本会自动创建 CPU Worker、选择实际高 CPU PID，并在 finally 中清理进程。

4.5 Windows 多轮稳定性测试

每个模式运行 20 轮，即每个场景 80 个任务。

# systemd 模拟场景：80 个任务
$stamp = Get-Date -Format "yyyyMMdd_HHmmss"
$output = "data\benchmark_results\windows_systemd_80_$stamp"

& $python .\scripts\run_wp7_real_api_benchmark.py `
    --allow-real-api `
    --scenario systemd --rounds 20 --temperature 0 `
    --thinking-mode disabled `
    --modes A_text_memory_disabled B_protocol_memory_disabled `
        C_protocol_state_exchange D_protocol_state_auto_reuse `
    --output-dir $output

# 真实高 CPU 场景：80 个任务
$stamp = Get-Date -Format "yyyyMMdd_HHmmss"
$output = "data\benchmark_results\windows_cpu_80_$stamp"

& $python .\scripts\run_wp7_real_api_benchmark.py `
    --allow-real-api `
    --scenario cpu --rounds 20 --temperature 0 `
    --thinking-mode disabled `
    --modes A_text_memory_disabled B_protocol_memory_disabled `
        C_protocol_state_exchange D_protocol_state_auto_reuse `
    --cpu-load-workers 2 --cpu-load-duration 120 `
    --output-dir $output

如运行中断，使用原命令、原 $output，并增加 --resume。已完成任务不会重复 调用 API。

5. openEuler 测试

5.0 用powersell 连接openeuler：

ssh ls@192.168.115.130 //应改为正确的用户名和IP地址

5.1 安装与服务检查

cd /opt/agentlink-mem

python3.11 -m venv .venv
./.venv/bin/python -m pip install --upgrade pip
./.venv/bin/python -m pip install -r requirements.txt

./.venv/bin/python --version
./.venv/bin/python -m pytest
git status --short

systemctl is-active agentlink-mem.service
curl -fsS http://127.0.0.1:8000/health

预期平台身份：

platform=openEuler
platform_family=linux
platform_distribution=openEuler
platform_version=24.03-LTS-SP3
acquisition_kind=openeuler_real
simulated=false

5.2 D 模式只读记忆快照

首次测试前创建受控快照：

./.venv/bin/python scripts/create_wp7_openeuler_memory_snapshot.py \
  --output data/wp7_openeuler_systemd_snapshot.db \
  --manifest data/wp7_openeuler_systemd_snapshot.manifest.json

将服务配置为：

MEMORY_MODE=read_only
MEMORY_DB_PATH=/opt/agentlink-mem/data/wp7_openeuler_systemd_snapshot.db

然后按部署流程重启并确认服务正常：

sudo systemctl daemon-reload
sudo systemctl restart agentlink-mem.service
systemctl is-active agentlink-mem.service
curl -fsS http://127.0.0.1:8000/health

5.3 openEuler systemd 单轮测试

先执行零 API 预检：

./.venv/bin/python scripts/run_wp7_openeuler_real_api_benchmark.py \
  --preflight-only --rounds 1 --modes A B C D

预检通过后运行四模式单轮实验：

stamp="$(date +%Y%m%d_%H%M%S)"
output="data/benchmark_results/openeuler_systemd_1round_${stamp}"

./.venv/bin/python scripts/run_wp7_openeuler_real_api_benchmark.py \
  --allow-real-api \
  --rounds 1 --modes A B C D \
  --target-service agentlink-slow-demo.service \
  --output-dir "$output"

预期诊断根因是 agentlink-db-ready.service，主要等待约 8 秒。

5.4 openEuler 高 CPU 单轮测试

./.venv/bin/python scripts/run_wp7_openeuler_cpu_real_api_benchmark.py \
  --preflight-only --rounds 1 --modes A B C D

stamp="$(date +%Y%m%d_%H%M%S)"
output="data/benchmark_results/openeuler_cpu_1round_${stamp}"

./.venv/bin/python scripts/run_wp7_openeuler_cpu_real_api_benchmark.py \
  --allow-real-api \
  --rounds 1 --modes A B C D \
  --cpu-load-workers 2 \
  --cpu-load-duration-seconds 120 \
  --cpu-load-target-percent 100 \
  --output-dir "$output"

浏览器打开下面这个网址，即可查看结果

http://192.168.115.130:8000/benchmark-dashboard

5.5 openEuler 多轮稳定性测试

# 真实 systemd：20 轮 × 4 模式 = 80 个任务
stamp="$(date +%Y%m%d_%H%M%S)"
output="data/benchmark_results/openeuler_systemd_80_${stamp}"

./.venv/bin/python scripts/run_wp7_openeuler_real_api_benchmark.py \
  --allow-real-api \
  --rounds 20 --modes A B C D \
  --target-service agentlink-slow-demo.service \
  --output-dir "$output"

# 真实高 CPU：20 轮 × 4 模式 = 80 个任务
stamp="$(date +%Y%m%d_%H%M%S)"
output="data/benchmark_results/openeuler_cpu_80_${stamp}"

./.venv/bin/python scripts/run_wp7_openeuler_cpu_real_api_benchmark.py \
  --allow-real-api \
  --rounds 20 --modes A B C D \
  --cpu-load-workers 2 \
  --cpu-load-duration-seconds 120 \
  --cpu-load-target-percent 100 \
  --output-dir "$output"

浏览器打开下面这个网址，即可查看结果

http://192.168.115.130:8000/benchmark-dashboard

中断后使用相同 output 并增加 --resume。

5.5 openEuler 连续相关联任务测试

./.venv/bin/python scripts/run_cross_task_memory_benchmark.py \
  --require-openeuler \
  --allow-real-api \
  --thinking-mode disabled \
  --system-source mock \
  --modes A B C D \
  --rounds 1 \
  --output-root /opt/agentlink-mem/data/benchmark_results

6. 查看 openEuler 结果

可将结果复制到 Windows 后统一展示：

scp -r `
  agentlink-openeuler:/opt/agentlink-mem/data/benchmark_results/<结果目录> `
  .\data\benchmark_results\

回到 Dashboard 点击“刷新”，选择复制后的实验目录。

每个正式结果目录至少包含：

  • raw_results.json：逐任务原始数据
  • checkpoint.json：断点续跑记录
  • summary.csv：四模式汇总
  • report.md：实验报告
  • run_config.json：固定实验配置
  • environment.json：平台、Python、Git 和模型信息
  • errors.json：失败类型与重试信息
  • prompt_audit.json：Prompt 组成审计

7. 结果判读

按以下顺序检查：

  1. provider_type=real_api、token_source=provider_usage。
  2. 平台和 simulated 标记正确。
  3. A/B/C/D 的 Input Token、Total Token 和端到端延迟。
  4. reviewer_verdict、证据完整性和根因准确性。
  5. CPU Worker 或共享状态是否清理完成。
  6. 是否存在 STATE_EXPIRED、格式错误、Token 为 null 或 Mock 回退。

单轮实验只用于功能演示；稳定性能结论必须来自多轮实验。

8. 常见问题

  • Dashboard 没有数据：确认 BENCHMARK_DASHBOARD_ROOT 指向 data/benchmark_results，实验完成后点击“刷新”。
  • 端口被占用：更换 Dashboard 端口，例如 --port 8766。
  • 正式实验被拒绝：检查提示中的核心代码文件。HEAD 没有 Tag 不会阻止 运行，报告会记录 untagged@<commit>；Benchmark 外围改动也会进入审计信息。
  • D 模式提示快照为空：重新按第 5.2 节创建并配置只读快照。
  • 认证失败：检查 .env，认证失败不会重复重试，也不会回退 Mock。
  • 运行中断：使用原结果目录加 --resume，不要创建新目录。

更详细设计见：

  • docs/AgentLink-Mem_System_Project_Book.md
  • docs/AgentLink-Mem_Benchmark_Design_v1.md
  • docs/AgentLink-Mem_WP8_Dashboard.md
  • docs/AgentLink-Mem_Cross_Task_Memory_Benchmark.md

Cross-task memory functional check:

python scripts/run_cross_task_memory_benchmark.py \
  --rounds 1 \
  --system-source mock

The openEuler preflight, measured run, and Dashboard commands are documented in docs/AgentLink-Mem_Cross_Task_Memory_Benchmark.md.

关于
README.md
354.8 MB
邀请码
    Gitlink（确实开源）
  • 加入我们
  • 官网邮箱：gitlink@ccf.org.cn
    • QQ群
  • QQ群
    • 公众号
  • 公众号

版权所有：中国计算机学会技术支持：开源发展技术委员会
京ICP备13000930号-9 京公网安备 11010802047560号