KernAdapt

KernAdapt 是面向混合负载的自适应内核资源管控运行时。系统把 sched_ext 调度器、机制级监控器和在线策略控制连接起来，通过显式契约、证据检查、有限验证、provenance 和回退机制，让内核资源管控从“固定加载某个策略”变成“按运行时证据选择合适机制”。

本仓库面向研究生操作系统大赛提交，包含可运行源码、机制源码、分析脚本、中文文档、PDF 交付材料和公开审计脚本。

KernAdapt 控制平面

评委快速入口

想看什么	推荐入口
作品总体说明	01-技术报告.pdf
KernAdapt 中文报告	02-KernAdapt.pdf
LockCausal 中文报告	03-LockCausal.pdf
FlowCausal 中文报告	04-FlowCausal.pdf
答辩幻灯片	05-比赛答辩PPT.pdf
KernAdapt 控制器源码	agent/
控制器分析脚本	analysis/
lockcausal/	lockcausal/
flowcausal/	flowcausal/
仓库结构说明	docs/REPOSITORY_LAYOUT.md
公开审计脚本	scripts/audit-public.sh

建议评阅路线

先阅读根目录五份 PDF，快速掌握研究问题、系统设计和答辩材料。
看 agent/README.md，了解 KernAdapt 在线控制器如何生成 profile、选择机制、执行检查和记录 provenance。
看 lockcausal/README.md 与 flowcausal/README.md，了解两个机制子工程的源码、脚本和运行入口。
运行 make test 与 make audit，确认仓库可测试、可公开提交。
如需复现实验流程，可从 lockcausal/scripts/ and flowcausal/scripts/ 和 analysis/ 进入；涉及 sched_ext 的真实加载需要兼容内核和特权环境。

系统图

KernAdapt 的控制路径强调“先形成证据，再执行动作，再记录结果”。在线专家只参与机制选择和受保护执行，逐次唤醒调度仍由具体内核机制完成。

flowchart LR
    workload[混合负载] --> profile[运行时 profile]
    profile --> policy[KernAdapt 策略专家]
    policy --> guard[契约检查 / runtime guard]
    guard --> executor[受保护执行器]
    executor --> mechanism{机制}
    mechanism --> lock[LockCausal]
    mechanism --> flow[FlowCausal]
    executor --> provenance[provenance / ledger]
    provenance --> memory[经验记忆与策略卡]
    memory --> policy

仓库内容

agent/                 KernAdapt 在线控制器、策略检查、执行器和 provenance
analysis/              证据包、批处理结果和 benchmark 汇总工具
lockcausal/            LockCausal 机制源码、脚本和辅助工具
flowcausal/            FlowCausal 机制源码、脚本和辅助工具
skills/                调度器策略卡和选择契约
results/               KernAdapt 默认运行输出位置
docs/                  仓库结构、结果目录和图片资产
scripts/               测试和公开发布审计入口
*.pdf                  比赛 PDF 交付材料，全部位于根目录

机制子工程

LockCausal 面向锁竞争场景，围绕 waiter、lock owner、handoff locality 和 owner progress 组织调度信息。

LockCausal 架构

FlowCausal 面向 code-agent、CI 和 sandbox 工作流，围绕 session、stage、process cohort 和 critical frontier 组织调度信息。

FlowCausal 架构

两个机制目录都整理成了独立入口，便于单独阅读：

目录	主要内容
lockcausal/	`src/sched_ext/` 里的调度器源码，`scripts/` 里的评测脚本，`tools/` 里的监控工具。
flowcausal/	`src/` 里的 BPF/loader/控制器，`experiments/` 里的实验脚本，`benchmarks/` 里的回放基准。

快速开始

运行时使用 Python 标准库，建议 Python 3.11 或更高版本。

make test
make audit
python3 agent/run_kernadapt_online.py --help

本地最安全的路径是使用 dry-run 检查控制器流程。真实 sched_ext 加载、BPF map 操作和数据库 benchmark 需要兼容的 Linux 内核、调度器构建产物以及特权环境。

python3 agent/run_kernadapt_online.py \
  --workload mariadb-sysbench \
  --threads 64 \
  --dry-run

关键入口命令

命令	用途
`make test`	运行仓库 smoke tests。
`make audit`	检查公开提交中不应出现的私有路径、联系方式、LaTeX 源文件和生成缓存。
`python3 agent/run_kernadapt_online.py --help`	查看 KernAdapt 在线控制器参数。
`python3 agent/run_mariadb_comparison.py --help`	查看同批次 MariaDB 对比运行入口。
`python3 flowcausal/src/controller/flowctl.py --help`	查看 FlowCausal 原型控制器参数。
`python3 flowcausal/experiments/run_live_sandbox.py --help`	查看 FlowCausal live sandbox harness 参数。

设计要点

控制平面与调度机制分离：KernAdapt 管策略选择、证据检查和执行边界；具体调度行为由机制实现。
决策可审计：profile、decision、critic、guard、execution status 和 provenance 都有结构化记录。
风险有回退：dry-run、runtime guard、postflight、rollback 和策略卡更新都作为控制路径的一部分。
机制可扩展：LockCausal 和 FlowCausal 作为两个机制子工程进入仓库，后续机制可按同样方式接入。

测试与公开审计

标准检查：

./scripts/test.sh
./scripts/audit-public.sh

公开审计会检查：

是否残留私有路径、联系方式或明显个人信息；
是否误放论文写作/PPT LaTeX 源文件；
是否存在 Python 缓存或 LaTeX 构建中间文件；
根目录 PDF 的作者元数据是否为空。

仓库约定

本仓库面向公开评阅组织，不包含论文写作源文件、演示源文件、参考文献数据库、模板、原始 benchmark 大日志和本机私有路径。运行结果默认写入 results/，结果目录说明见 docs/results/README.md。

安全与贡献

运行特权动作前请阅读 SECURITY.md。提交修改时应附带针对性测试或可复现的验证命令，详见 CONTRIBUTING.md。

许可证

运行时和仓库文档采用 MIT License。第三方参考资料、字体、内核接口和渲染报告仍受其各自上游许可约束。