openEuler ASA + LLM Enhanced Scheduler Agent

本项目实现一个面向 openEuler 的自适应 CPU 调度 Agent。系统以 ASA 快速闭环为主路径：实时采集系统指标，使用本地分类器输出场景概率，经过时间加权投票得到稳定场景，再通过场景到 sched_ext 调度器的映射执行切换。新增的 LLM 监督层只在异常或不确定事件触发时介入，并且不能直接执行 shell、不能直接调用调度 Skill，所有建议必须经过确定性 PolicyGuard 校验。

当前实现是单机本地 Agent，node_id 默认是 local。代码中已经保留 node_id、hardware_fingerprint、policy_version、decision_id、created_at、expires_at 等字段，便于未来演进到中央控制器，但本仓库尚未实现多台 openEuler 节点控制。

核心能力

实时指标采集：agent/perception.py 采集 CPU、内存、IO、网络和进程相关特征。
本地分类：agent/decision.py 调用 model/model/scene_classifier.joblib，输出完整概率分布、raw_top3、raw confidence/margin/entropy。
时间加权投票：对概率分布做指数时间加权和阈值过滤，输出 voted_top3、voted confidence/margin/entropy、stable_label，并防止全零向量直接 argmax。
快速调度路径：agent/mapping.py 和 scheduler_mapping.json 作为场景到调度器映射的事实来源，最终切换仍由 agent/skills/cpu_sched_skill.py 调用 agent/action.py 中的 SchedulerController 完成。
LLM 监督层：agent/supervisor/ 提供数据契约、触发门、候选生成、DeepSeek 客户端、异步执行、PolicyGuard、经验存储和性能反馈闭环。
经验记忆：使用标准库 sqlite3 保存在线观察和离线 benchmark 经验；检索默认只使用 validated 和可信 bootstrap，支持经过验证的负面经验。
Dashboard：FastAPI 后端和 React 前端展示快速路径决策、LLM 触发原因、LLM 建议、PolicyGuard 结果、最终动作、最近经验和真实性能收益。

快速路径与 LLM 慢速路径

默认配置 LLM_SUPERVISOR_ENABLED = False。在 LLM 关闭时，系统保持原 ASA 本地行为：采样、分类、时间投票、映射、可选 sched_ext 切换。

开启 LLM 路径后，实时循环仍然每秒采样。常规高置信场景不调用 DeepSeek；只有 TriggerGate 命中以下事件时才提交后台 LLM 请求：

分类置信度低；
Top-1/Top-2 间隔过小；
预测熵过高；
时间窗口场景振荡；
Top-3 场景映射冲突或映射缺失；
运行性能下降；
调度器切换失败；
优化目标变化；
未知硬件。

LLM 请求在线程池后台执行，不阻塞每秒采样循环。LLM 返回后先检查上下文是否过期，再经过 PolicyGuard。超时、网络/API 错误、空响应、非法 JSON、非法调度器、PolicyGuard 拒绝都会回退到本地快速路径。

DeepSeek 配置

DeepSeek 使用 OpenAI 兼容客户端，base_url 为 https://api.deepseek.com，默认模型为 deepseek-v4-flash。生产环境建议使用环境变量：

export DEEPSEEK_API_KEY="你的 DeepSeek API Key"

当前 agent/config.py 中保留了测试用 key 以便本地快速验证。公开提交、比赛归档或生产部署前应删除明文 key，并只使用环境变量或密钥管理系统。

Dashboard

启动后端：

python dashboard/backend/main.py

启动前端：

cd dashboard/frontend
npm install
npm run dev

浏览器打开：

http://127.0.0.1:5173

Dashboard 的三个控制按钮有固定顺序：

Benchmark Recognition：启动/停止本地 Agent 识别链路。
Scheduler Switch：启用真实调度器切换；开启时会自动开启 Benchmark Recognition。
LLM Path：启用事件触发式 LLM 监督；开启时会自动开启 Benchmark Recognition 和 Scheduler Switch。

关闭 Benchmark Recognition 时，Scheduler Switch 和 LLM Path 会同时关闭。

openEuler 24.03-LTS-SP4 真实联调

以下步骤用于真机验证，不应把 mock 单元测试结果解释为 openEuler 真实调度成功。

准备系统：

cat /etc/os-release
uname -a
python3 --version

安装 Python 依赖：

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

准备 sched_ext / scx：

ls /sys/kernel/sched_ext/state
which scx_cake || true
which scx_lavd || true
which scx_rusty || true
which scx_bpfland || true

需要 root 权限、启用 sched_ext 的内核，以及可执行的 scx 调度器二进制。不同 openEuler 内核构建可能需要额外安装或编译 scx 工具。

训练或确认模型文件：

python model/train.py
ls model/model/scene_classifier.joblib

只运行本地快速路径，不启用 LLM：

python run_agent.py

Dashboard 控制真实切换：

python dashboard/backend/main.py
cd dashboard/frontend
npm run dev

在 Dashboard 中按顺序启用 Benchmark Recognition、Scheduler Switch、LLM Path。没有 root 或 scx 二进制时，切换会失败并写入失败经验，但这不代表调度器真实性能结果。

记录验证数据：

tail -f runtime/agent/decision_history.jsonl
sqlite3 runtime/agent/supervisor_memory.sqlite3 ".tables"

关注 decision_id，它用于关联决策、切换、评估和经验写入。

消融实验

建议在相同硬件、相同 openEuler 版本、相同 workload 顺序、相同采样时长下比较四组：

A. 默认 EEVDF

不启动 sched_ext。
只运行 workload 和指标采集。
作为 Linux 默认调度基线。

B. 原始 ASA 本地快速路径

启动本地分类器、时间加权投票和场景映射。
关闭 LLM。
允许 sched_ext 根据本地快速路径切换。

C. 每次循环调用 LLM

实验性对照组，不建议作为生产路径。
每个采样周期都调用 LLM，记录 API 延迟、决策延迟、失败回退和额外资源消耗。

D. 事件触发式双层架构

正常高置信场景使用 ASA 快速路径。
仅在 TriggerGate 命中时后台调用 LLM。
LLM 建议必须经过 PolicyGuard，失败时回退本地路径。

每组至少记录：

性能得分：使用 evaluation/score.py 的用户体验导向评分，必要时补充 workload KPI。
切换次数：统计 decision_history.jsonl 中 switched=true。
LLM 触发率：llm_trigger.triggered=true 次数 / 总轮数。
API 延迟：DeepSeek 客户端调用耗时。
决策延迟：采样到最终动作落地的耗时。
CPU/内存开销：Agent 进程和 scx 进程资源占用。
失败回退次数：LLM API 失败、非法输出、PolicyGuard 拒绝、sched_ext 切换失败。
未知场景决策效果：未知硬件、映射缺失或低置信场景下是否返回 benchmark_required，以及后续 benchmark 证据是否改善选择。

测试

Python 全量测试：

pytest test -q

Python 语法编译检查：

python -m py_compile run_agent.py agent/config.py agent/perception.py agent/decision.py agent/mapping.py agent/memory.py agent/action.py agent/runtime_state.py agent/skills/base.py agent/skills/cpu_sched_skill.py model/realtime.py model/train.py evaluation/evaluator.py evaluation/score.py dashboard/backend/services/agent_service.py dashboard/backend/main.py agent/supervisor/types.py agent/supervisor/deepseek_client.py agent/supervisor/async_runtime.py agent/supervisor/trigger_gate.py agent/supervisor/candidate_builder.py agent/supervisor/policy_guard.py agent/supervisor/experience_store.py agent/supervisor/feedback.py

前端构建：

cd dashboard/frontend
npm run build

这些自动化测试主要验证代码契约、回退逻辑、Dashboard 状态展示和 mock 调度路径；不能替代 openEuler 真机上的 sched_ext 效果验证。

关键文件

run_agent.py：实时 Agent 主循环。
agent/config.py：全局配置、LLM 开关、触发阈值、策略参数。
agent/perception.py：实时系统指标采集。
agent/decision.py：分类器概率输出和时间加权投票。
agent/mapping.py：场景到调度器映射。
agent/action.py：sched_ext/scx 调度器真实切换控制。
agent/skills/cpu_sched_skill.py：ASA 快速路径和 Supervisor 接入点。
agent/supervisor/：LLM 监督层、PolicyGuard、经验库和反馈闭环。
evaluation/score.py：性能评分函数。
dashboard/backend/：Dashboard API。
dashboard/frontend/：Dashboard UI。
docs/central_controller_evolution.md：未来中央控制器演进说明。