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

本项目对应“第三届中国研究生操作系统开源创新大赛暨开放原子大赛操作系统专项赛”社区赛题：面向 openEuler 的自适应资源管控 Agent。

作品简介

本作品是一套运行在 openEuler 用户态的自适应资源管控框架。项目以 CPU 调度为核心，通过 /proc 和可选 eBPF 观测获取 workload 的真实运行特征，构建 Workload Fingerprint；随后结合历史兼容状态形成调度选择，并通过安全生命周期管理将 baseline 或 scx profile 作用于 Linux sched_ext 调度路径。任务结束后，系统统一记录前台性能、后台影响、公平性、实际执行状态和清理结果，为下一兼容轮提供反馈。

项目没有重新实现 Linux 内核调度框架，也不让 Python 进入高频调度热路径。Python Agent 负责低频感知、策略选择、运行编排和证据组织，真实任务调度由内核 sched_ext/scx 执行；C/libbpf 与 BPF 负责近内核观测及隔离式扩展能力。

最终稳定参考为 Agent v1。它采用两阶段 Replay：首次遇到某一运行上下文时主动使用 baseline 完成观测并建立状态；下一兼容轮对历史 Fingerprint、环境和 profile 可用性进行检查，再选择 baseline 或适配的 scx profile。所有真实 scx 操作必须经过配置授权、命令行确认、非 dry-run 状态和 M6 Safety Gate，并在任务结束后恢复默认调度状态。

除 CPU 调度主线外，项目还提供：

• 64 个标准 Tool 与 6 个 Skill，用于统一注册、组合和审计系统能力；
• eBPF 调度观测，以及 Resource、Network、Security 三类隔离式 Policy Agent；
• 轻量 ML Shadow 分类器，用于验证 Fingerprint 特征的可学习性，不参与调度决策；
• 本地离线 LLM Copilot，用于解释项目文档和实验依据，不参与调度或系统控制；
• 只读 Web Dashboard，用于展示运行闭环、性能证据和扩展能力。

核心运行闭环

用户目标与配置
      |
      v
运行状态采集 (/proc，可选 eBPF)
      |
      v
Workload Fingerprint
      |
      v
Replay State 兼容性检查与 Profile Select
      |
      v
M6 Safety Gate
      |
      +--------------------+
      |                    |
      v                    v
   baseline          sched_ext / scx
      |                    |
      +---------+----------+
                |
                v
       测量、清理与 Run Record
                |
                v
       更新下一兼容轮状态

稳定路径只使用运行时可观测信息形成决策，不读取 benchmark 名称、预期类别或性能结果作为策略输入。ML Shadow、eBPF Shadow 和离线 LLM 均作为辅助验证或解释路径，不改变本轮选中的 scheduler profile。

赛题要求完成情况

赛题要求	项目实现	状态
用户态资源管控 Agent	Python 控制面组织感知、决策、scx 生命周期和反馈	已完成
标准 Tools/Skills 接口	Capability Registry、64 Tools、6 Skills、统一 metadata 与调用审计	已完成
Workload 感知	/proc 采样、进程树、Fingerprint、可选 eBPF 调度观测	已完成
自适应 CPU 调度	两阶段 Replay、profile 选择、主动 baseline 与安全回退	已完成
sched_ext/scx 集成	真实集成 scx_simple、scx_qmap、scx_central、scx_flatcg	已完成
eBPF hook 扩展	调度观测、tc 网络策略、BPF LSM 安全策略	已完成
资源控制扩展	cgroup CPU quota/weight 的真实应用、验证与回滚	已完成
性能测试与复现	对照矩阵、独立 holdout、置信区间、证据清单和严格验收	已完成

核心成果

1. 真实行为驱动的跨轮自适应

Agent 将分散的运行时指标聚合为结构化 Fingerprint，并通过 workload signature 隔离不同运行上下文。首次运行负责建立真实观测，下一兼容轮才复用经过检查的历史状态，从而解决“调度策略需要在任务运行前确定，而行为特征需要在运行后获得”的时序问题。

2. 用户态决策与内核态高效执行

策略形成和实验控制位于 Python 用户态，scx 调度器在 Linux 内核调度路径执行。该边界兼顾了策略迭代的灵活性与内核热路径的执行效率。

3. 完整的安全生命周期

真实 scx 启动前必须通过权限、内核能力、环境冲突和双重授权检查。启动后需要确认 active/confirmed，结束时只回收本轮持有的资源；条件不满足时主动保持 baseline，执行异常时安全回退。

4. 可扩展的 Policy Agent 框架

Resource、Network 和 Security Policy Agent 复用统一的 observe -> decide -> apply -> verify -> measure -> rollback -> explain 生命周期，并在隔离对象上完成真实控制与清理验证。这些能力默认关闭，不与 CPU 性能实验并行运行。

5. 证据驱动的结果治理

项目同时保留正向、候选、未决和回归结果。正式结论由预先确定的样本资格、配对统计、安全门槛和执行完整性共同决定，配置、运行记录、二进制哈希、统计结果和报告通过 Evidence Manifest 建立对应关系。

正式性能结果

以下数据来自冻结的正式矩阵或独立 holdout，详细来源由 configs/final-claims.v2.json 和 experiments/evidence-manifest.json 索引。

场景	主要结果	结论范围
process_burst_parallel	Agent 相对 baseline 完成时间提升 12.214955%	confirmed_improvement
真实 kernel build	workload-only 提升 21.786524%	显式前台优先模式
真实 kernel build	计入感知与调度开销后端到端提升 7.878770%	confirmed_foreground_priority_improvement
真实 kernel build	后台相对保持率 0.916482，95% 单侧下界 0.900577	满足该模式预先设定的 0.90 资源边界
cpu_python	Agent 相对 baseline 提升 1.072175%	candidate_improvement
异构 workload holdout	Agent 相对 baseline 综合优势 9.9163%	candidate_adaptive_advantage

其中，kernel build 结果对应用户显式选择的 controlled_foreground_priority 目标，不能表述为默认 balanced 策略的无条件收益。M8-e3 的回归结果和 M8-e4c 的未决结果同样保留，用于说明策略泛化边界与独立验证机制。

功能与能力概览

CPU 调度主线

• 周期采集 workload 进程组的 CPU、进程结构、线程和上下文切换等运行信息；
• 构建可解释的 Workload Fingerprint 和质量状态；
• 使用 Replay State、Policy Mapping 和 profile 可用性形成选择；
• 通过 M6 Safety Gate 启动、确认、停止和清理真实 scx；
• 生成结构化 Run Record，并为下一兼容轮保存状态。

eBPF 与 Policy Agent

• sched_observer：跟踪 PID 或 process tree 的 fork、switch 和 wakeup 事件；
• Resource Control Agent：在临时 cgroup 中实施并验证 CPU quota/weight；
• Network Policy Agent：在隔离 netns/veth 上通过 tc eBPF 验证端口 allow/deny；
• Security Policy Agent：通过 BPF LSM 对指定测试进程和临时文件实施访问控制；
• 所有真实扩展均具有独立授权、所有权记录、验证与 rollback。

学习型 Shadow 感知

M13-a 使用 proc-based Fingerprint 特征训练轻量分类器，并在按 workload group 隔离的 75-run、21-group 测试中取得 Accuracy 与 Macro F1 均为 1.0，Accuracy Wilson 95% CI 为 [0.9513, 1.0]。该结果证明当前特征具有良好的行为区分能力，但模型固定为：

used_for_decision = false
used_for_actuation = false

离线 Copilot 与 Dashboard

Copilot 使用本地 llama.cpp 与 Qwen2.5 模型解释白名单项目文档和实验依据；无模型或输出校验失败时使用确定性模板回退。Dashboard 只读取已生成的结构化证据，不启动 workload、scx、eBPF 或 Policy Agent，也不写入 Policy State。

项目结构

OpenEuler-OS/
├── src/oe_agent/          # Python Agent、Policy、Runner、统计与能力接口
├── ebpf/                  # sched observer、tc network policy、BPF LSM
├── configs/               # 运行配置、实验协议和冻结 claims/catalog
├── scripts/               # 构建、验证、实验、报告和演示入口
├── schedulers/            # scx 集成与 profile 说明
├── experiments/           # 精选运行记录、统计报告与证据清单
├── web/dashboard/         # 只读 Web Dashboard
├── docs/                  # 架构、实验、结果和复现文档
├── examples/              # Tools/Skills 与 LLM 输入示例
├── pyproject.toml         # Python 项目定义
└── README.md              # 作品入口与运行说明

运行环境

主要验证环境：

项目	版本或要求
操作系统	openEuler 24.03-LTS-SP4
内核	Linux 6.6，启用 CONFIG_SCHED_CLASS_EXT
Python	3.11 或更高版本
底层构建	GCC/Clang、make、libbpf、libelf、bpftool
权限	静态检查和只读演示无需 root；真实 scx/eBPF/Policy Agent 需要 root

项目 Python 主线仅使用标准库，不要求联网安装 Python 依赖。若需要重新构建 eBPF 组件或外部 tools/sched_ext 调度器，请参考 环境搭建说明 和 调度器集成说明。

运行说明

以下命令均在项目根目录执行：

cd /path/to/OpenEuler-OS
export PYTHONPATH=src

1. 验证 Python 与能力注册

python3 -m py_compile src/oe_agent/*.py scripts/*.py scripts/workloads/*.py
python3 -m oe_agent.capabilities validate-registry

预期结果：Python 编译无错误，Capability Registry 显示 64 个 Tool、6 个 Skill，且校验通过。

2. 运行最小安全闭环

python3 -m oe_agent --config configs/agent.example.toml --once

示例配置默认使用 dry_run 与 mock/baseline backend，只执行配置加载、感知、决策计划和结果记录，不改变系统调度状态。输出写入 experiments/runs/。

3. 执行最终只读验收

python3 scripts/validate-all.py --strict --format json
python3 scripts/final-precheck.py --strict
python3 scripts/build-evidence-manifest.py --verify

这组命令核对源码、Tools/Skills、冻结 claims、正式证据、M12 rollback、M13 Shadow 结果和交付索引，不重跑大型性能矩阵。

4. 运行安全演示

python3 scripts/run-demo-flow.py

该入口读取已有证据并展示 CPU 调度、eBPF、性能结论和扩展能力，不启动真实 scx，不挂载 eBPF，也不加载本地模型。

5. 启动只读 Dashboard

python3 scripts/run-dashboard.py --host 127.0.0.1 --port 8787

浏览器访问：

http://127.0.0.1:8787

如需从同一局域网的宿主机访问虚拟机页面，可将监听地址改为 0.0.0.0，并使用虚拟机 IP：

python3 scripts/run-dashboard.py --host 0.0.0.0 --port 8787

Dashboard 是只读展示入口。启用本地 Copilot 的可选方式见 Dashboard 说明 和 离线 LLM Copilot 说明。

6. 构建 eBPF 组件

make -C ebpf/sched_observer
make -C ebpf/network_policy
make -C ebpf/security_policy

构建不会自动挂载程序。真实 attach 仍需使用受控验证入口。

7. 检查并验证真实 scx 生命周期

先执行只读 precheck：

python3 scripts/validate-m6-scx.py --mode precheck
python3 scripts/check-scx-schedulers.py \
  --config configs/scx.multi-profile.example.toml

确认内核、权限、binary 和当前 sched_ext 状态满足要求后，才可显式运行正向验证：

sudo env PYTHONPATH=src python3 scripts/validate-m6-scx.py \
  --mode positive \
  --allow-real-scx

正向验证会启动真实 scx，并在 workload 结束后停止受管 scheduler、恢复 sched_ext=disabled。请勿与性能实验、本地 LLM 或其他系统控制任务并行运行。

8. 验证 Policy Agent 扩展

静态验证和安全 dry-run：

python3 scripts/validate-m12.py --mode static
python3 scripts/run-policy-agent-smoke.py \
  --config configs/policy-agents.m12.example.toml \
  --agent all \
  --dry-run

仅在专用测试环境中执行真实正向验收：

sudo env PYTHONPATH=src python3 scripts/run-policy-agent-smoke.py \
  --config configs/policy-agents.m12.positive.toml \
  --agent all \
  --allow-real-control

该命令只应作用于配置中定义的临时 cgroup、netns/veth 和测试文件。任一 rollback 不完整时，应先按 journal 执行恢复，不应继续其他真实控制。

9. 验证 ML Shadow 感知

python3 scripts/validate-m13a.py

该命令验证数据分组、模型、置信区间、OOD 逻辑和历史报告，不赋予模型 scheduler 决策权限。

安全边界

1. 默认不实施真实控制：示例配置默认 dry-run，eBPF、LLM 和 Policy Agent 默认关闭。
2. 真实 scx 需要多重条件：配置允许、CLI 显式授权、非 dry-run、root 和 M6 环境检查缺一不可。
3. 主动 baseline 与失败回退分开记录：证据不足或策略不适用时主动保持 baseline；执行失败才记录 fallback。
4. 按所有权清理：只停止和删除本轮创建、持有并记录的资源，不使用通配清理宿主对象。
5. 实验与 LLM 错峰运行：LLM 不参与策略，但其计算负载会污染性能测量，因此禁止与性能实验并行。
6. Dashboard 不具备控制权：页面仅展示证据，不调用真实调度或 Policy Agent。

证据与复现

推荐按以下顺序审查项目：

1. 最终交付说明
2. 当前最佳状态
3. 赛题要求映射
4. 总体架构介绍
5. 正式证据索引
6. M8-h Kernel Build 结果
7. M12 Policy Agent
8. M13-a Shadow 分类器

机器可读入口：

configs/final-claims.v2.json
experiments/evidence-manifest.json
experiments/reports/m11b2b-delivery-freeze.json

历史实验的正向、候选、未决和回归结果均保留在 docs/ 与 experiments/ 中。README 只呈现最终稳定主线和冻结结论，不使用 smoke 或 exploration 结果替代正式性能声明。

第三方组件与原创边界

项目基于 openEuler/Linux、Linux tools/sched_ext 提供的 scx 调度器、libbpf/BPF 和可选的 llama.cpp/Qwen2.5 构建。仓库不把这些第三方组件描述为原创实现。

项目自主实现的主要部分包括：Python Agent 主控框架、Workload Fingerprint、两阶段 Replay、策略映射与 profile 选择、M6 安全生命周期、Tools/Skills Registry、实验编排与可信统计、eBPF/Policy Agent 集成、ML Shadow 验证、证据治理和只读 Dashboard。更完整的来源与依赖说明见 项目说明 和各组件文档。

许可证

本项目许可证见 LICENSE。第三方组件继续遵循各自的开源许可证与使用条款。