KernelSU 开发指南从 AGENTS.md 解析跨内核/用户空间/Manager 的协作契约与构建验证流程【免费下载链接】KernelSUA Kernel based root solution for Android项目地址: https://gitcode.com/GitHub_Trending/ke/KernelSUKernelSU 的AGENTS.md是面向开发者和 AI 编码代理的工程化指南它明确了 KernelSU 四大组件内核模块、Rust 用户空间守护进程、Kotlin Manager 应用、文档/JS 资产的职责边界、跨层契约supercall / module / app profile 等六大核心概念以及每个组件的强制构建验证命令。读完本文你能准确理解内核 IOCTLsupercall接口如何在ksud与 Manager JNI 之间保持一致掌握cargo ndk/ Gradle / VitePress 各组件的正确验证流程并避开“JNI 镜像漂移”“缺少 libksud.so”等高频踩坑点。Agent 快速启动规则AGENTS.md开篇给出了协作总则这几条规则的价值在于它们针对 KernelSU 这种“内核 用户空间 App”三层耦合项目的风险特征而设计重大功能或重构先拟计划Plan并在推进过程中持续更新触及不熟悉的 crate、Android API 或 JS 依赖时先查阅对应的库/接口文档再动手默认用rg做代码搜索除非文件本身已含非 ASCII 字符否则编辑保持 ASCII交付前必须运行下文各组件对应的检查命令不允许跳过失败步骤路径不明时优先做“最小风险改动”保持内核与用户空间之间的契约UAPI 头文件、IOCTL 语义、持久化格式不被破坏。最后一条是全文最重要的一条KernelSU 的 C 内核模块、Rustksud、C JNI 和 Kotlin 层共享同一套二进制契约以 supercall UAPI 头 为代表任何一侧单方面变更都会造成“运行时漂移”。仓库结构与组件映射AGENTS.md给出的目录总览与当前仓库实际结构基本一致注意其正文中引用的部分文件路径属于早期平铺布局本文已按当前仓库实际路径修正kernel/ # 内核模块 —— C 代码Linux 内核集成 userspace/ksud/ # 用户空间守护进程 —— Rust 二进制负责用户/内核通信 userspace/ksuinit/ # 启动阶段的 init 组件Rust manager/ # Android Manager 应用 —— Kotlin/Jetpack Compose website/ # 文档网站 —— VitePress js/ # 模块 WebUI 的 JavaScript 库 scripts/ # 构建自动化脚本Python内核模块内部已按职责分层理解这一层对定位契约代码至关重要kernel/supercall/supercall 驱动 fd 安装与 IOCTL 分发supercall.c、dispatch.ckernel/policy/allowlist、app profile、feature 的策略实现allowlist.c、app_profile.c、feature.ckernel/hook/系统调用钩子与 setuid 钩子setuid_hook.c、syscall_hook_manager.ckernel/selinux/、kernel/manager/、kernel/sulog/、kernel/feature/sepolicy 注入、Manager 身份识别、su 日志、adb_root/内核 umount 等特性。核心概念之一supercall —— 三层共享的 IOCTL 契约AGENTS.md将supercall定义为“内核侧通过[ksu_driver]anon-inode 暴露、经 reboot kprobe 钩子安装的 IOCTL 接口”用于映射 allowlist/app-profile 管理、feature 开关、sepolicy 变更等命令。这一描述与当前源码完全吻合且可以在 supercall.c 中看到完整实现细节1. 驱动 fd 的安装机制。内核在ksu_supercalls_init()中注册一个挂在REBOOT_SYMBOL上的 kprobereboot_kp。当用户空间进程用特定魔数调用 reboot 系统调用KSU_INSTALL_MAGIC1 0xDEADBEEF、KSU_INSTALL_MAGIC2 0xCAFEBABE见 supercall.h时reboot_handler_pre()通过task_work_add把ksu_install_fd()延迟到系统调用返回前执行从而在“看似失败”的 reboot 调用里把一个 anon-inode fd 偷偷塞给调用进程// kernel/supercall/supercall.c static int reboot_handler_pre(struct kprobe *p, struct pt_regs *regs) { int magic1 (int)PT_REGS_PARM1(real_regs); int magic2 (int)PT_REGS_PARM2(real_regs); if (magic1 KSU_INSTALL_MAGIC1 magic2 KSU_INSTALL_MAGIC2) { /* 通过 task_work 在系统调用返回前安装 ksu fd 并写回用户缓冲区 */ tw-outp (int __user *)arg4; tw-cb.func ksu_install_fd_tw_func; task_work_add(current, tw-cb, TWA_RESUME); } return 0; }ksu_install_fd_with_permissions()会创建两种命名的 anon-inode普通场景为[ksu_driver]SU 会话exec 进 ksud 之后为[ksu_driver_su]后者携带KSU_DRIVER_PERMISSION_SU_SESSION权限位——这就是 UAPI 注释中 “3: scoped su-session driver fd” 的含义见 supercall.hKERNEL_SU_UAPI_VERSION 3。2. 用户空间如何拿到这个 fd。Rust 侧 ksucalls.rs 的策略是先扫描/proc/self/fd中符号链接指向anon_inode:[ksu_driver]/anon_inode:[ksu_driver_su]的已继承 fd找不到才回落到SYS_reboot 双魔数触发内核钩子把 fd 写回用户缓冲区。该调用还包裹在with_svc_call中并安装 SIGSYS 处理器——若 seccomp 拦截了这次系统调用处理器会把返回值改成-EPERM并置位SIGSYS_OCCURREDksud随即打印 “blocked by seccomp” 日志这正是“内核/用户空间契约被破坏”时的第一现场。3. IOCTL 命令表与权限模型。所有命令在 dispatch.c 中集中注册每个条目绑定 handler 与perm_checkalways_allow/only_root/manager_or_root/only_manager例如IOCTL 命令权限检查用途KSU_IOCTL_GRANT_ROOTallowed_for_su为 allowlist 内的 UID 授予 rootKSU_IOCTL_GET_INFO/_LEGACYalways_allow版本/运行模式built-in/LKM/late-load查询KSU_IOCTL_REPORT_EVENTonly_rootksud 上报 post-fs-data / boot-completed / module-mountedKSU_IOCTL_SET_SEPOLICYonly_root注入 sepolicy 规则KSU_IOCTL_NEW_GET_ALLOW_LIST/_DENY_LISTmanager_or_root分页读取允许/拒绝清单KSU_IOCTL_GET/SET_APP_PROFILEonly_manager读写 per-app 策略KSU_IOCTL_GET/SET_FEATUREmanager_or_root特性开关如 sucompatKSU_IOCTL_MANAGE_MARKmanager_or_root任务标记反检测/策略标记KSU_IOCTL_ADD_TRY_UMOUNTmanager_or_root维护按 UID umount 模块的挂载点列表KSU_IOCTL_GET_SULOG_FDonly_root获取 sulog 日志 fd分发入口ksu_supercall_handle_ioctl()先做权限校验SU 会话 fd 可额外放行allow_su_session命令未注册命令返回-ENOTTY。do_get_info()还会把KSU_GET_INFO_FLAG_LKM/MANAGER/LATE_LOAD等位回传给ksud后者据此报告runtime_mode()built-in / lkm / late-load并做 UAPI 版本匹配检查ensure_uapi_version_matched()见 ksucalls.rs。4. 契约的双镜像。AGENTS.md明确要求Rust 侧通过ksudksucalls.rs访问 supercallManager 的 JNI 桥在 ksu.cc 中镜像同一批 IOCTL。因此AGENTS.md的 Kernel 工作流规则是硬性的——改动 IOCTL 或 profile 时必须同步更新ksud的ksucalls.rs与 Manager 的ksu.ccUAPI 结构体以 uapi/supercall.h 及 kernel/include/uapi/ 为单一事实来源。核心概念之二module —— 可刷入模块的完整生命周期module指可刷入的 ZIP 模块其生命周期在ksud中闭环解包module.rs 将 ZIP 解包到模块根目录常量定义于 defs.rs即/data/adb/modules/生命周期脚本模块内的post-fs-data.sh、service.sh等脚本由 ksud 的 init 事件驱动执行见 init_event.rs这些脚本的执行时机对应 supercall 的KSU_IOCTL_REPORT_EVENT——ksud 在对应阶段通过report_post_fs_data()/report_boot_complete()/report_module_mounted()通知内核dispatch.c 的do_report_event()内用静态锁保证每类事件只触发一次late-load 模式下跳过Manager 呈现Manager 侧从 ksud 读取模块状态见 ModuleViewModel.ktAGENTS.md原文引用的ui/screen/Module.kt在当前仓库已重构为ui/screen/module/目录下的ModuleScreen.kt等文件。核心概念之三metamodule —— 唯一激活的特殊模块metamodule 是module.prop中标记metamodule1的特殊模块。ksud的行为约束见 metamodule.rs强制单一激活同一时间只能有一个 metamodule 处于激活态创建/data/adb/metamodule - /data/adb/modules/id符号链接作为模块脚本引用 meta 挂载内容的稳定入口meta 安装钩子mount hook的委托逻辑集中在metamodule.rs在 init_event.rs 中metamodule 的脚本先于普通模块执行Manager UI 会对 metamodule 高亮显示并在卸载时给出警告。需要提醒AGENTS.md的目录表中列出了userspace/meta-overlayfs/meta-overlay 文件系统实现当前仓库的userspace/下仅存ksud/与ksuinit/该目录已从主仓库移除——涉及 meta-overlay 的实现细节请以ksud内保留的 meta 集成代码为准。核心概念之四app profile —— per-app 策略app profile是 per-app 策略结构控制某个应用的 root 授权与非 root 行为例如累计 umount 策略。跨层链路为结构定义kernel/include/uapi/app_profile.huapi 头与根目录 uapi/app_profile.h 保持一致校验与持久化kernel/policy/app_profile.c 与 kernel/policy/allowlist.csupercall 入口KSU_IOCTL_GET/SET_APP_PROFILE权限为only_manager见 dispatch.cdo_set_app_profile()成功写入后会调用ksu_persistent_allow_list()持久化并ksu_mark_running_process()刷新在跑进程的标记——这解释了“改一次 profile 立即对新 fork 生效、对已运行进程刷新”的行为用户空间消费ksud 与 Manager 经 JNI 桥ksu.cc调用Kotlin 侧模型为 Natives.kt 中的Natives.ProfileUI 配置界面在ui/component/profile/下如 AppProfileConfigMaterial.kt。另注意 dispatch.c 中的CONFIG_KSU_DISABLE_POLICY编译开关内核若以该配置编译app profile IOCTL 直接返回-EOPNOTSUPP这是“同一 UAPI、不同内核配置能力不同”的典型例子。核心概念之五sucompat —— 兼容传统su调用sucompat是一个 exec/文件系统兼容层对 allowlist 内的 UID把/system/bin/su的执行重定向到ksud从而让“调su命令拿 root”的旧工作流继续可用。实现与暴露链路钩子实现kernel/feature/sucompat.c由系统调用钩子管理器注册kernel/hook/syscall_hook_manager.c特性开关KSU_FEATURE_SU_COMPAT通过KSU_IOCTL_GET/SET_FEATURE暴露kernel/policy/feature.c 提供ksu_get_feature()/ksu_set_feature()后端Manager 侧ksu.cc中的is_su_enabled/set_su_enabledJNI 接口直接映射这对 IOCTL。这也说明 feature 机制是“内核能力 → UAPI → ksud/ksucalls.rsfeature.rs→ JNI → Kotlin”的标准四级镜像任何一级漏改都会出现“Manager 显示开启但内核不生效”的漂移。核心概念之六allowlist —— 内核管理的 root 白名单allowlist是内核维护的“允许 root 的 UID 列表”持久化于/data/adb/ksu/.allowlist并为 root/non-root 提供默认 profile。要点核心逻辑在 kernel/policy/allowlist.c位图存储、持久化、默认 profile 缓存由内核初始化路径装配supercall 层暴露GET/NEW_GET_ALLOW_LIST、GET/NEW_GET_DENY_LIST、UID_GRANTED_ROOT即ksu_is_allow_uid_for_current()、UID_SHOULD_UMOUNT“该 UID 是否应 umount 模块”的判定全部见 dispatch.c其中KSU_IOCTL_NEW_GET_*采用“入参 buffer 长度 输出 total_count”的分页结构supercall.h旧的固定 128 长度结构已标记 deprecatedManager 通过 JNIksu.cc与 KotlinNatives门面读写该清单对应 UI 为ui/screen/superuser/与viewmodel/SuperUserViewModel.kt。GRANT_ROOTIOCTL 的权限检查allowed_for_su正是基于这份 allowlist——allowlist 是整个 root 授权体系的最终事实来源。各组件的构建与验证流程内核kernel/内核改动仅限 C必须与用户空间/Manager 对 supercall、allowlist 的预期保持接口对齐若改动 IOCTL 或 profile必须同步更新 ksudksucalls.rs与 Manager JNIksu.cc内核源码的构建由kernel/下的 Kbuild/Makefile/setup.sh 支撑配合设备树中的内核源码编译。用户空间 Rustuserspace/ksud对userspace/ksud的代码改动AGENTS.md要求严格按顺序执行cargo ndk -t arm64-v8a check # 1. 验证编译 cargo ndk -t arm64-v8a clippy # 2. Lint 与告警 cargo fmt # 3. 格式化 # 4. 任何错误/告警未清零前任务不得视为完成仓库根 justfile 提供了基于cross的等价一键流程可用于了解实际产物路径just build_ksud # cross build --target aarch64-linux-android --release just clippy # cargo fmt cross clippy --target aarch64-linux-android --releaseAndroid Manager 应用manager/Manager 的构建强依赖ksud 二进制先行就绪cd manager # 必须先准备 ksud 二进制 mkdir -p app/src/main/jniLibs/arm64-v8a cp ../userspace/ksud/target/aarch64-linux-android/release/ksud \ app/src/main/jniLibs/arm64-v8a/libksud.so # 然后再构建 ./gradlew clean assembleRelease要点AGENTS.md原文强调Manager 构建要求jniLibs中已存在 ksud 二进制缺失即构建失败justfile中的build_manager目标cp target/aarch64-linux-android/release/ksud ... ./gradlew aDebug正是这一依赖顺序的自动化体现。文档网站website/与 JS 库js/cd website bun install bun run docs:build # 生产构建js/下的包支撑模块 WebUIAGENTS.md要求遵循现有 lockfilejs/package.json 定义了该包发布前运行相应的 lint/test 脚本。常见陷阱Common PitfallsAGENTS.md列出的四条陷阱每一条都对应真实故障模式值得逐条对照源码理解同一时间只能有一个激活的 metamodulemeta 钩子必须与 ksud 的期望保持同步——违反会导致 meta 符号链接悬挂或脚本执行顺序错乱Manager JNI 镜像每一个 supercall内核或 ksud 的 API 变更必须反映到 ksu.cc否则产生运行时漂移表现常为 IOCTL 返回-ENOTTY或语义错位不要跳过cargo ndk步骤普通cargo check校验的是宿主目标无法发现 Android 目标特有的编译问题缺少libksud.so时 Manager 构建必然失败在任何 Gradle 命令之前先创建该文件即上文“先 cp ksud 再 assemble”的顺序。Git 提交规范AGENTS.md的 Git 章节约定了与仓库历史一致的提交风格沿用scope: summary格式scope 为小写、对应改动区域如kernel、ksud、manager、meta-overlayfs、docs、scripts优先单一 scope多区域改动时选主 scope不链式堆叠。纯文档改动用docs:多语言字符串更新按历史惯例可用translations:标题简短目标 ≤72 字符、sentence case、句尾无句号非必要不写 body引用 PR/issue 时在末尾追加(#1234)提交前先看一遍git log --oneline的近期记录保持前缀与大小写风格与现状一致。小结AGENTS.md的真正价值不在目录罗列而在于它把 KernelSU 跨 C/Rust/C/Kotlin 四层的契约维护规则写成了可执行清单supercall 命令表dispatch.c是中心ksucalls.rs、ksu.cc、UAPI 头文件是它的三个镜像cargo ndk检查与“先备 ksud 再编 Manager”是防止镜像漂移的工程护栏。遵循这些规则是向 KernelSU 内核或用户空间提交任何改动的正确起点。【免费下载链接】KernelSUA Kernel based root solution for Android项目地址: https://gitcode.com/GitHub_Trending/ke/KernelSU创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考