OpenOS-Agent：面向 openEuler 的自适应资源管控 Agent

环境：鲲鹏 920 (AArch64) + KVM + openEuler 24.03 LTS SP4
语言：Python (Agent/Monitor/TUI) + Rust (Scheduler/scx) + C (eBPF)
包管理：uv + pyproject.toml | 构建：Makefile + hatchling

---

项目简介

OpenOS-Agent 是一个基于用户态调度（sched_ext）的自适应资源管控 Agent 框架。通过 eBPF 感知系统 workload 特征，结合 LLM 进行策略学习与优化，动态调整 CPU 调度策略，实现对不同负载场景的自适应调度。

核心特性

• 双回路架构：毫秒级确定性快路径（无 AI）+ 秒~分钟级 LLM 慢路径策略学习
• 策略即数据（Policy-as-Data）：策略为声明式 JSON/YAML 工件，支持热加载、版本化、灰度晋升与自动回滚；LLM 输出经严格 JSON 校验与自动修复，坏策略不落库
• 多场景 Agent 框架：标准化接口支持 CPU 调度 / 网络 QoS / 资源管控 / 安全策略等多域 Agent 快速构建
• 动作分层：调参等轻动作优先；换调度器是重动作（detach/attach 有全局停顿），需跨过高置信门槛，低置信时 HOLD 保持当前/默认调度器
• 防抖动机制：四道防抖闸（debounce + hysteresis + dwell + cooldown）+ 切换频率熔断（60s 内 ≥3 次切换即锁定 120s），杜绝策略颠簸
• 真实 reward 闭环：动作前后 KPI 对比（对稳定 baseline 参照 + 3% 显著性门槛滤噪）+ Guard 自动回滚护栏 + cgroup 原值快照回滚
• 跨平台后端抽象（HAL）：sched_ext / cgroup v2 / sched_attr 多后端，优雅降级
• Agent 可视化监控（TUI）：参考成熟 Agent CLI 设计的终端监控界面，实时呈现感知-决策-执行全链路

---

架构概览

┌─────────────────── 慢路径 (秒~分钟, LLM, 异步) ───────────────────┐
│  Experience Store ──> LLM 策略合成/调参 ──> 校验 ──> Policy Store   │
└───────────────────────────────┬────────────────────────────────────┘
                                │  热加载 (原子替换 active 表)
┌───────────────────────────────▼── 快路径 (毫秒, 无 AI, 确定性) ────┐
│  Observe ─> Classify ─> PolicyMatcher ─> HysteresisFSM ─> Apply    │
│  /proc+eBPF  时间加权投票   谓词匹配      防抖/迟滞      热加载     │
└────────────────────────────────────────────────────────────────────┘

---

监控界面（TUI）

截图为鲲鹏 920 宿主机上 openEuler 测试虚拟机（16 vCPU）的真实运行模式：后端 FastLoopController 驱动，Agent 已自主完成 scx_lavd → scx_flash 的调度器切换。

基于 Textual 构建，视觉语言参考 Hermes 等成熟 Agent CLI（低对比暗色底 + 欧拉蓝品牌强调色，设计令牌统一收敛于 monitor/tui/theme.py）。界面分为三层：

• 系统感知层（上）：CPU 逐核热图 / 内存 / 网络 sparkline / Disk I/O，数据来自 /proc + eBPF 传感器
• 决策状态层（中）：Workload 分类结果与置信度、Scheduler 当前/上一个调度器及切换原因（FSM 防抖状态一目了然）
• Agent 活动层（下）：transcript 式决策日志、7 步工作流实时进度（Observe → Store Experience）、最近命中的策略时间线

# 一键启动（真实模式，需 Linux + sched_ext 环境；自动引导 .venv）
./openos-agent

# Mock 模式（任意平台可跑，用于演示/开发）
./openos-agent --mock

# 等价方式：uv run -m monitor.tui.app [--mock]

把启动器加入 PATH 后，任意目录可直接 openos-agent 一键启动：

./openos-agent install     # 写入 ~/.bashrc（及 ~/.zshrc），source 后生效；uninstall 可移除

常用快捷键：l 日志 · p 策略 · s 技能 · t 拓扑 · m 切换 LLM 模型 · h 帮助 · q 退出

---

演示视频

目录结构

openos-agent/
├── agent/                  # Agent 决策框架 (Python)
│   ├── core/               #   核心类型、编排器、事件总线
│   ├── evolution/          #   策略进化：聚类、编译、账本
│   ├── experience/         #   经验仓库
│   ├── llm/                #   LLM 提供商 (OpenAI/Anthropic/Mistral/Qwen)
│   ├── policy/             #   策略引擎、FSM、匹配器、检索器
│   ├── skills/             #   技能引擎 (Python + C++ FFI)
│   ├── fast_loop.py        #   快路径控制器
│   └── domains.py          #   多域定义 (CPU/Network/Resource/Security)
├── monitor/                # 系统感知层
│   ├── ebpf/               #   eBPF 内核探针 (workload.c)
│   ├── tui/                #   终端 UI (Textual)
│   ├── sensor.py           #   传感器 (/proc + eBPF)
│   └── classifier.py       #   工况分类器
├── scheduler/              # 调度器管理
│   ├── custom_schedulers/  #   自定义 scx 调度器
│   ├── scheduler_runner.py #   调度器启停管理
│   └── schedulers.json     #   调度器配置
├── config/                 # 配置文件
│   ├── policies/           #   策略工件目录
│   ├── experience/         #   预设经验
│   └── llm_config.yaml     #   LLM 提供商配置（本地创建，不入库，见「快速开始 · 配置 LLM」）
├── benchmark/              # 基准测试套件
│   ├── tools/              #   压测工具 (schbench/wrk2/memtier)
│   ├── setup_tools.sh      #   工具安装脚本
│   ├── run_*.py            #   各类测试脚本
│   └── check.sh            #   benchmark 模块环境检查/安装
├── scripts/                # 运维脚本
│   ├── agent_daemon.py     #   Agent 守护进程
│   ├── install_dependencies.sh
│   └── check_lib.sh        #   子目录 check.sh 共享函数库
├── skills/                 # C/C++ 技能引擎
│   └── check.sh            #   skills 模块环境检查/安装
├── agent/check.sh          # python 模块环境检查/安装
├── monitor/check.sh        # ebpf 模块环境检查/安装
├── scheduler/check.sh      # rust/scx 模块环境检查/安装
├── third_party/scx/        # sched_ext 调度器框架 (Git submodule)
├── docs/                   # 文档
├── check.sh                # 根协调器：调用子脚本 + 系统级模块
├── pyproject.toml          # Python 包定义
└── Makefile                # 全局构建入口

---

快速开始

1. 环境要求

项目	要求
操作系统	openEuler 24.03-LTS-SP4（必须），其他 Linux 鼓励
硬件	鲲鹏 920 (AArch64) 推荐，x86_64 亦可
内核	支持 sched_ext 机制（kernel 6.6+）
Python	>= 3.12
包管理	uv（推荐）或 pip

2. 安装依赖

项目提供解耦的一键环境检查与安装脚本，git clone 后运行单条命令即可完成全部依赖配置：

# 一键安装所有依赖（自动检测发行版并安装缺失项）
bash check.sh --install

# 仅检查不安装（默认模式）
bash check.sh

# 仅处理指定模块（逗号分隔）
bash check.sh --install --only python,rust

# 非交互式安装（适合 CI）
bash check.sh -y --install

请参考 check脚本的详细说明

子脚本可独立运行：

bash agent/check.sh check        # 仅检查 Python 模块
bash scheduler/check.sh install  # 单独安装 Rust + 编译 scx
bash skills/check.sh check       # 仅检查 skills 编译状态

3. 手动安装（可选）

如需绕过 check.sh 手动安装：

# 系统级构建依赖
bash scripts/install_dependencies.sh

# Python 依赖 (推荐使用 uv)
uv sync

# 或使用 pip
pip install -e .

# 开发依赖 / benchmark 依赖
uv sync --extra dev
uv sync --extra bench

4. 配置 LLM（运行前必做）

出于安全考虑，config/llm_config.yaml（含 API Key）不随仓库分发（已被 .gitignore 忽略，仅保留在本地）。首次运行 Agent 前，请先从模板创建该文件并填入你自己的 API 信息：

cp config/llm_config.yaml.example config/llm_config.yaml

然后编辑 config/llm_config.yaml，填入 LLM 提供商的 API Key 和 Base URL：

llm:
  provider: "openai_compat"
  base_url: "https://api.siliconflow.cn/v1"
  api_key: "your-api-key"
  model: "deepseek-ai/DeepSeek-V4-Pro"
  temperature: 0.2
  timeout: 120.0

支持的 LLM 提供商：OpenAI、Anthropic (Claude)、Mistral、Qwen (Dashscope)、SiliconFlow、OpenRouter 等 OpenAI 兼容接口。

说明：若未配置该文件，Agent 仍可启动（快环规则决策不受影响），但慢环 LLM 学习能力将不可用。配置文件路径可通过环境变量 OPENOS_LLM_CONFIG 覆盖。

5. 运行 Agent

# 方式 1: 一键启动（TUI + 后端 agent，推荐；./openos-agent install 后可全局使用）
./openos-agent

# 方式 2: 运行守护进程（无 TUI）
uv run scripts/agent_daemon.py

# 方式 3: 直接启动 TUI 监控界面
uv run -m monitor.tui.app

6. 运行基准测试

# 安装 benchmark 工具
cd benchmark && bash setup_tools.sh

# 运行多场景迭代学习基准
uv run benchmark/run_iterative_benchmark.py

# 运行 6 调度环境对比矩阵
uv run benchmark/run_matrix_benchmark.py

---

核心模块说明

Agent 快路径 (agent/fast_loop.py)

每 tick（~1秒）执行一次确定性控制循环：

1. Observe：从 /proc + eBPF 采集系统特征
2. Classify：时间加权投票分类工况（latency_sensitive / throughput / io_bound / idle / mixed），含中断风暴信号——CPU 占用低但唤醒/切换风暴的工况判为延迟敏感，不会误切节能调度器
3. Match：在活跃策略表中谓词匹配 → 候选排序 → 动作分层裁决（轻动作同分优先；重动作低置信时 HOLD）
4. FSM + 熔断：迟滞状态机判定是否切换（四道防抖闸）；窗口内切换超频即熔断锁定，阻断抖动
5. Apply：通过 sched_ext 后端热加载调度器
6. Guard：按工况选定 KPI（io_bound 看 io_wait，其余看运行队列延迟）记录基线，观察窗口内恶化则自动回滚

策略进化与账本 (agent/evolution/)

慢路径闭环的记忆与信用分配：

• PerfLedger：跨轮记录场景 best-so-far 与每条策略的 reward_ema / 生命周期；reward 对稳定 baseline 参照计算，3% 显著性门槛内的变化视为测量噪声不产生学习信号，避免好策略被噪声误杀进 cooldown
• 生命周期仲裁：持续劣化的策略打入 cooldown，灾难性劣化单轮即熔断；负证据策略不再参与检索，给探索让路
• LLM 策略合成：输出经严格 JSON 校验（自动剥除代码栅栏/冗余文本，缺字段/空动作/非法置信度直接拒绝）后才能落库

多场景编排器 (agent/core/orchestrator.py)

协调多域 Agent 的三段式 tick：

• Propose：各域独立提议（只读、不执行）
• Arbitrate：按资源归属 + 域优先级 + 置信度裁决冲突
• Commit：仅执行获胜动作，经验落库

系统感知 (monitor/sensor.py)

• ProcSensor：从 /proc/stat、/proc/meminfo、/proc/net/dev 等读取低频指标
• EbpfSensor：通过 BCC 挂载 eBPF 探针，采集上下文切换（含主动/被动区分，用于计算真实 voluntary 占比）、runqueue 延迟、唤醒频率等高频内核事件

调度器管理 (scheduler/scheduler_runner.py)

统一管理 scx 调度器的启动/停止/切换：

• 支持调度器：scx_simple, scx_rusty, scx_bpfland, scx_flash, scx_lavd, scx_layered, scx_nest, scx_p2dq, scx_flatcg
• 提供 SchedulerBenchmark 类进行跨调度器对比测试

---

性能测试结果

真实机器实测（vm-agent / aarch64 / Linux 6.12.98-scx），以 openEuler 原生默认调度器 CFS 为基线（代表“不装 agent”的开箱起点），每场景重复 3 次取中位数：

21 个真实工作负载场景中，OpenOS-Agent（ASA，经 10 轮迭代学习）相对原生 CFS 取得 13 胜 / 4 平 / 4 负，胜出场景平均提升 +11.3%，最高单场景 +30.6%，含负向场景的全景平均 +3.9%。

代表性胜出场景（相对 CFS）

场景	负载类型	指标	CFS 基线	ASA	提升
S7_Iperf3	网络吞吐	bw_gbits ↑	25.2	32.9	+30.6%
S11_LLM_Contention	LLM 推理竞争	p99_ms ↓	2.319	1.687	+27.3%
S15_Network_QoS	网络 QoS 延迟	p99_ms ↓	7.231	5.951	+17.7%
S5_FFmpeg	视频转码吞吐	speed_x ↑	4.50	5.20	+15.6%
S3_Nginx	Web 服务延迟	p99_ms ↓	1.350	1.200	+11.1%
S9_Colocation	混部延迟	p99_ms ↓	2.415	2.191	+9.3%
S1_Redis	KV 存储延迟	p99_ms ↓	1.599	1.471	+8.0%

自适应调度在网络吞吐、延迟敏感服务、混部隔离三类负载上收益最显著。

学习有效性（策略进化）

策略库经 10 轮闭环学习（n0 初始种子 → n10），多数签名场景性能随学习持续提升： S11 学习增益 +27.3%、S3 +8.4%、S9 +7.4%、S1 +6.1%，胜出场景平均学习增益 +3.8%，印证了慢路径策略进化机制的价值。

诚实声明与改进

• 已知劣化场景：S13_Interrupt_Contention（−44.7%）、S10_Colocation_Schbench_Fio（−15.4%）等 4 个，根因为高频切换抖动与中断竞争工况误分类。

完整报告（实验设置、全部场景数据与复现指引）见 benchmark/reports/SHOWCASE_PRELIMINARY_REPORT.md。

---

开发指南

详见 AGENTS.md 获取完整的代码开发规范和贡献指南。

代码检查

# Lint
ruff check .

# 类型检查
mypy agent/ monitor/

# 单元测试
pytest test/ -v

---

环境配置参考

详见 docs/ENV.md 获取 KVM 虚拟机创建、SSH 配置、VSCode SFTP 同步等完整环境搭建指南。

---

参考资料

• Towards Agentic OS: An LLM Agent Framework for Linux Schedulers
• Mixture-of-Schedulers: An Adaptive Scheduling Agent as a Learned Router
• sched_ext (scx) GitHub
• openEuler 官方

---

许可证

Apache-2.0