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

AgentCGroup 面向多种工作负载共同运行、争用系统资源的场景，持续采集负载状态和应用性能，通过 MoS 选择适合当前状态的 CPU 调度器，并协调 CPU、内存和 I/O 控制。项目包含负载感知、调度器选择、在线策略更新和资源管理模块，以及相应的演示和测试入口。

应用场景与主要功能

在线服务与计算、内存或文件 I/O 负载混部，兼顾响应延迟与其他负载的执行进度。
负载加入、退出或运行阶段变化后重新判断；没有适用的已验证策略时保留或恢复 EEVDF。
接入社区 sched_ext 调度器、DLS/scx_layered 和自研 scx_agent；全局同一时刻只有一种 CPU 调度路径实际生效。
scx_agent 的 cgroup 间调度支持虚拟时间（virtual-time）和轮转调度（service-credit）两种算法，并按 cgroup 配置策略，在同一调度器进程中更新、核对和回退策略。
统一协调 CPU、内存和 I/O 控制；保留进程观测、网络、安全等受控扩展。
记录调度器实际身份、策略、性能指标和清理情况。LLM 仅在可选的异步分析支路提出候选，不直接修改内核状态。

目录与材料

路径	内容
src/agentcg/	主要实现、构建入口、测试脚本及技术文档
src/kernel/	openEuler 内核适配补丁、配置和构建说明
src/third_party/	锁定的第三方源码、工具、源码包及原许可证
docs/	项目说明书、创新说明、成员贡献及 AI／第三方工具声明
tests/	测试入口、实验配置、公开证据摘要和结果图表
demo/	可运行演示、只读环境检查和离线结果导航
presentation/	现场演示 PPT 和演示视频
作品原创承诺书.pdf	作品原创承诺书

详细设计见源码文档导航，第三方来源及贡献边界见组件说明。源码位于 src/，其中 agentcg、kernel、third_party、evidence 保持同级关系。

系统环境与依赖

已验证平台为 openEuler 24.03-LTS-SP4 x86_64，运行内核为 6.6.0-157.0.0.149.20260612.scxfull5.oe2403sp4。真实运行需要 sched_ext、cgroup v2、BTF 和所启用 Agent 对应的 BPF 能力。内核适配方式见 src/kernel/README.md。不能假定未经适配的发行版默认内核具备全部能力。

已验证工具链包括 Python 3.11.6、Clang/LLVM 17.0.6、GCC 12.3.1、Rust/Cargo 1.96.0 和 Make 4.4.1，另需 ELF、zlib、zstd 等开发库。核心 Python 控制链使用标准库；LLM 和机器学习依赖为可选项，分别列于 src/agentcg/requirements/。锁定源码、版本及安装准备步骤见依赖说明和依赖锁文件。本目录不包含完整内核源码、RPM 仓库或用户的 Cargo／Python 缓存，不声称任意新主机均可完全离线安装。

构建与安装准备

在 openEuler 测试机器上校验依赖与内核能力，并构建项目：

cd src/agentcg
make verify-sources
sudo -E make check-env-sp4
make core
make extensions

以上步骤不会替用户安装或替换内核。环境或锁定源码不满足要求时应停止。二进制和 BPF 对象必须在测试机器上生成；不要复用其他内核生成的 vmlinux.h、skeleton 或 BPF 对象。上游调度器构建及测试机器准备方法见依赖说明。

运行

cd src/agentcg
make runtime-check     # 查看初始运行状态
sudo -E make run-agent

实际执行需要当前主机验证过的调度器 Catalog、PolicyBundle 和切换成本记录。仓库保留的配置对应历史验证主机，不可直接视为新主机的执行授权；更换内核、二进制或主机后，应按验证过程重新生成并验证这些材料。停止后检查 EEVDF 恢复、调度器进程、BPF 对象和项目 cgroup 是否清理。LLM 不启用时核心功能仍可运行；启用时只通过环境变量提供密钥，禁止把密钥写入源码或日志。

测试与结果

python3 tests/run_tests.py --suite contract
python3 tests/run_tests.py --suite unit

上述为离线代码测试，不等于 openEuler 真机性能复测。真机兼容、资源控制、成对性能和动态负载的入口、权限及结果使用方法见 tests/README.md。可直接离线打开测试总览、Phoronix 图表和动态切换图表。

验证记录包括 20 个调度器的加载、运行、退出与清理，40 项统一切换检查，以及 19 个正式场景、57 对测试、114 个有效 60 秒运行点，分别对应兼容性、切换机制和应用性能验证。测试结果对应上述 openEuler 验证主机及负载配置。公开图表和证据摘要已脱敏，材料导航见 tests/README.md。

scx_agent 的 service-credit 算法已完成框架接入、冷启动、预加载交接与在线调参验证，并进行了 Phoronix 对照和动态负载测试。结果见scx_agent Phoronix 图表和算法对照说明，图表分别展示吞吐、尾延迟与后台进度。

演示与复现

两个示例分别展示 scx_agent 在线策略更新和完整 Agent 动态混部。从仓库根目录执行：

bash demo/run_demo.sh --describe
sudo -E bash demo/run_demo.sh --run \
  --part scx-agent --algorithm service-credit
sudo -E bash demo/run_demo.sh --run --part mainstream

运行步骤和输出说明见 demo/README.md，已保存的结果见 demo/index.html。Phoronix 对照和兼容验证见测试说明。

当前验证范围

MoS 依据已经验证的负载特征和测试结果选择调度器，未知或证据不足的状态回退 EEVDF。更多混部组合、负载强度和业务场景仍需验证。
20 个调度器已完成兼容验证。当前正式非 EEVDF 策略使用 scx_agent、scx_qmap、scx_rustland 和 scx_flash，各自的适用条件见测试报告。
DLS 已验证配置生成和动态调整机制，当前正式 60 秒性能路线不包含 DLS。scx_agent 的结果覆盖指定混部场景，与 scx_flatcg 的直接性能对照尚未开展。
正式性能结果来自一台 x86_64 测试机器；aarch64、跨机器和跨业务的正式性能对照仍待开展。NUMA、网络和安全扩展目前主要完成能力检查。
LLM 是可选建议模块，其建议经过检查和测试后采用。正式性能结果来自独立的成对实验，演示和短时测试用于观察功能与运行过程。

许可证与版本来源

项目许可证为 GPL-2.0，第三方组件保留原许可证、署名及文件头。公开基线为提交 2714c412e146d112eb8085b72c1aee6ba9fcff63。开发记录见项目提交说明；项目贡献、第三方工具及 AI 使用说明见 docs/。