Cloud-Kernel 开发文档

01 项目概述

1.1 项目简介

Cloud-Kernel（云内核）是一款面向 Android 平台的内核驱动管理套件，提供内核驱动选择与注入、PTY 终端命令行交互、系统信息检测、在线更新和主题自定义等功能。该应用运行在已获取 Root 权限的 Android 设备上，通过 JNI 调用原生 C/C++ 代码，利用 PTY（伪终端）技术与系统 Shell 进行交互。

1.2 基本信息

1.3 权限声明

02 项目结构

03 核心架构

3.1 整体架构图

3.2 页面导航

应用采用单 Activity + 四页面切换架构，通过底部 Dock 导航栏在四个页面间切换：

页面切换采用淡入淡出动画（alpha 属性动画，200ms），标签栏随选中状态改变颜色、字号和粗体。

04 启动页 (SplashActivity)

4.1 功能描述

SplashActivity 作为应用入口（LAUNCHER），展示品牌启动动画，2.5 秒后自动跳转到 MainActivity。

4.2 动画流程

4.3 界面元素

4.4 状态栏处理

• 白色状态栏背景 (0xFFFFFFFF)
• API 26+ 设置浅色状态栏图标 (SYSTEM_UI_FLAG_LIGHT_STATUS_BAR)
• API 28+ 适配刘海屏 (LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES)

05 主界面 (MainActivity)

5.1 初始化流程

MainActivity.onCreate() 按以下顺序执行初始化：

1. setContentView(R.layout.activity_main)
2. applyFullScreenImmersive() — 全屏沉浸式
3. 页面引用绑定 (pages[0-3], tabLabels, tabIcons, tabContainers)
4. 终端视图引用 (tvTerminal, scrollTerminal, inputTerminal)
5. Root 检测按钮绑定
6. initKernelDriver() — 驱动选择初始化
7. initBackgroundImage() — 背景图片初始化
8. initThemeColor() — 主题颜色初始化
9. initTerminal() — 终端初始化
10. initDriverPage() — 驱动页面初始化
11. initSoftwareUpdate() — 软件更新初始化
12. initKernelUpdate() — 内核更新初始化
13. 标签页点击事件绑定
14. fillDeviceInfo() — 填充设备信息
15. refreshRootStatus() — 刷新 Root 状态
16. loadCachedContent() — 加载缓存内容
17. checkAnnouncementPopup() — 检查公告弹窗
18. 延迟 1000ms → checkSoftwareUpdate()
19. 延迟 1500ms → checkCloudUpdate()
20. 延迟 2000ms → syncContent（公告）
21. 延迟 2500ms → syncContent（资助）

5.2 生命周期

5.3 全屏沉浸式

applyFullScreenImmersive() 方法设置的标志位：

View.SYSTEM_UI_FLAG_LAYOUT_STABLE
| View.SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION
| View.SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN
| View.SYSTEM_UI_FLAG_HIDE_NAVIGATION
| View.SYSTEM_UI_FLAG_FULLSCREEN
| View.SYSTEM_UI_FLAG_IMMERSIVE_STICKY

状态栏和导航栏颜色设为 #F9F9F7，API 30+ 额外调用 WindowInsetsController.hide() 隐藏状态栏。500ms 后重新应用标志位以确保生效。

06 首页 —— 设备信息与 Root 检测

6.1 设备信息展示

fillDeviceInfo() 方法通过 Build 类获取以下设备信息：

6.2 Root 权限检测

checkRootPermission() 方法采用双重检测策略：

第一层——文件存在检测：遍历以下 su 路径，检查文件是否存在：

• /system/bin/su, /system/xbin/su, /system/app/Superuser.apk
• /sbin/su, /system/sbin/su, /vendor/bin/su
• /data/local/su, /data/local/xbin/su, /su/bin/su

第二层——功能验证：创建临时脚本 check_su.sh（内容为 id），通过 su -c 执行，读取输出并检查退出码是否为 0。

检测结果通过 indicator_root（绿色 / 灰色圆点）和 info_root_status（"已获取"/"未获取"，颜色绿/红）显示。

07 驱动内核管理

7.1 驱动选择器

应用提供 8 个驱动选项按钮：

7.2 子项选择（驱动 0 专属）

当选择"多驱动"时，展开子项选择行：

7.3 触摸模式（驱动 4 专属）

7.4 防录屏开关

7.5 运行内核命令

点击"运行"按钮时，根据当前驱动类型拼接命令：

# 驱动 0（多驱动）
printf "1\n0\n1\n" | {updateFilePath}

# 驱动 4（LQ驱动）
printf "5\n{touchInput}\n1\n" | {updateFilePath}

# 其他驱动
printf "N\n1\n" | {updateFilePath}

执行前检查 updateFilePath 文件是否存在，执行后设置 5 秒冷却时间。

08 驱动管理页面 (Dits)

8.1 概述

驱动管理页面提供 dits 工具的下载和 6 种操作选项的执行。dits 是一个外部二进制工具，通过 execViaScript 方法以 root 权限执行。

8.2 下载流程

1. 检查 ditsFilePath 文件是否存在，若存在则标记 ditsDownloaded = true
2. 点击下载按钮或执行操作时自动触发下载
3. 下载 URL：DITS_DOWNLOAD_URL（123 云盘链接）
4. 下载完成后自动执行 chmod 755 设置可执行权限
5. 状态更新为绿色"下载完成"，操作按钮文字变为主题色

8.3 操作选项

6 个操作按钮对应 btn_drv_opt0_exec 到 btn_drv_opt5_exec，执行时：

1. 若未下载，弹出下载提示对话框
2. 若正在运行，忽略点击
3. 将 drvOptSelected 设为对应值
4. 切换到终端页面显示输出
5. 通过 startExecuteDits(option) 执行

8.4 卡片折叠

驱动管理卡片头部 drv_card_header 点击可展开/折叠 drv_card_body，折叠时 drv_chevron 图标旋转 180°。

09 PTY 终端系统

9.1 JNI 接口 (PtyTerminal.java)

PtyTerminal 是 final 类，私有构造函数，通过静态块加载 libptyterm.so：

9.2 C++ 原生实现 (ptyterm.cpp)

9.2.1 构建配置

LOCAL_MODULE := ptyterm
LOCAL_SRC_FILES := ptyterm.cpp
LOCAL_LDLIBS := -llog
include $(BUILD_SHARED_LIBRARY)

APP_ABI := armeabi-v7a arm64-v8a
APP_PLATFORM := android-21
APP_STL := c++_static

9.2.2 my_openpty() —— PTY 创建

static int my_openpty(int *amaster, int *aslave, char *name,
                      const struct termios *termp,
                      const struct winsize *winp)

流程：

1. posix_openpt(O_RDWR | O_NOCTTY) 打开主 PTY 设备
2. grantpt(master) 授予从设备权限
3. unlockpt(master) 解锁从设备
4. ptsname(master) 获取从设备名称
5. open(slave_name, O_RDWR | O_NOCTTY) 打开从设备
6. 若提供 winsize，通过 ioctl(TIOCSWINSZ) 设置窗口大小

9.2.3 startPty() —— 创建 PTY 并 Fork 进程

static jintArray startPty(JNIEnv *env, const char *cmd, jint rows, jint cols)

流程：

1. 设置 winsize（默认 24 行 x 80 列）
2. 调用 my_openpty() 创建 PTY
3. fork() 创建子进程

子进程：

• setsid() 创建新会话
• ioctl(slave_fd, TIOCSCTTY, 0) 设置控制终端
• dup2() 将 stdin/stdout/stderr 重定向到从设备
• 关闭主设备 fd
• 设置环境变量：TERM=dumb，PATH 为 Android 系统路径，清空 PS1/PS2/PS4/PROMPT_COMMAND/BASH_ENV，HISTFILE=/dev/null
• 若提供 cmd，执行 sh -c cmd；否则执行 sh
• _exit(127) 兜底

父进程：

• 关闭从设备 fd
• 设置 master fd 为 FD_CLOEXEC
• 返回 int[2]：{master_fd, pid}

9.2.4 nativeStartShell() —— 启动指定 Shell 的 PTY

与 nativeStart 类似，区别在于子进程端执行：

const char *initCmd = "stty -echo 2>/dev/null; export PS1=''; export PS2=''; "
                       "export PS4=''; export PROMPT_COMMAND=''; exec /system/bin/sh";
execlp(shellPath, shellPath, "-c", initCmd, nullptr);
execl("/system/bin/sh", "sh", "-c", initCmd, nullptr);  // 兜底

9.2.5 nativeRead() —— 读取终端输出

JNIEXPORT jbyteArray JNICALL
Java_com_js_fc_PtyTerminal_nativeRead(JNIEnv *env, jobject, jint fd, jint maxBytes)

• maxBytes 范围限制：≤ 0 时设为 4096，> 65536 时截断为 65536
• 通过 read() 系统调用读取数据
• 返回 byte[]，若读取失败返回空数组

9.2.6 nativeWrite() —— 写入终端输入

JNIEXPORT jint JNICALL
Java_com_js_fc_PtyTerminal_nativeWrite(JNIEnv *env, jobject, jint fd, jbyteArray data)

• 获取 Java 字节数组长度和内容
• 通过 write() 系统调用写入
• 返回实际写入字节数

9.2.7 nativeResize() —— 调整终端窗口

JNIEXPORT void JNICALL
Java_com_js_fc_PtyTerminal_nativeResize(JNIEnv *, jobject, jint fd, jint rows, jint cols)

通过 ioctl(fd, TIOCSWINSZ, &win) 发送窗口大小变更信号。

9.2.8 nativeWaitExit() —— 等待进程退出

JNIEXPORT jint JNICALL
Java_com_js_fc_PtyTerminal_nativeWaitExit(JNIEnv *, jobject, jint pid)

• 阻塞调用 waitpid(pid, &status, 0)
• 若被 EINTR 中断，继续等待
• 正常退出返回退出码，信号终止返回 128 + 信号编号

9.2.9 nativeClose() —— 关闭 PTY 和终止进程

JNIEXPORT void JNICALL
Java_com_js_fc_PtyTerminal_nativeClose(JNIEnv *, jobject, jint fd, jint pid)

1. 关闭 fd
2. 向进程发送 SIGTERM
3. 轮询等待最多 20 次（每次 50ms），检查进程是否退出
4. 若仍未退出，发送 SIGKILL 强制终止

9.3 Java 层终端管理

9.3.1 终端会话启动

startTerminalSession() 在后台线程中执行：

1. 通过 computeTermSize() 计算终端行列数
2. 优先尝试 PtyTerminal.nativeStartShell("su", rows, cols) 启动 root shell
3. 若失败，回退到 PtyTerminal.nativeStartShell("/system/bin/sh", rows, cols)
4. 保存 ptyFd 和 ptyPid，标记 ptySessionAlive = true
5. 清空终端显示，调整窗口大小
6. 启动读取线程

9.3.2 终端输出读取

startPtyReader() 在守护线程中循环读取：

while (ptyReading && ptyFd >= 0) {
    byte[] data = PtyTerminal.nativeRead(ptyFd, 4096);
    if (data == null || data.length == 0) break;
    String clean = sanitizeTerminalOutput(chunk);
    if (clean.length() > 0) appendTerminal(clean);
}

9.3.3 终端输出过滤

sanitizeTerminalOutput() 和 isUiTerminalNoise() 负责过滤不需要的输出：

• ANSI 转义序列过滤：stripAnsi() 移除 ESC 序列（CSI 序列和 OSC 序列）
• UI 噪音过滤：移除应用的 UI 提示消息（如 [错误]、[提示]、[完成]、[会话已结束] 等）
• 提示符过滤：移除单独的 $、#、>、% 提示符
• 命令回显过滤：移除以 #、$、>、% 开头的行，以及以这些符号结尾的路径行

9.3.4 终端大小计算

computeTermSize() 通过测量 TextView 的字符宽度和行高计算最优行列数：

float charW = paint.measureText("M");
float lineH = paint.getFontSpacing() + dp(3);
cols = Math.max(20, (int)(w / charW));
rows = Math.max(5,  (int)(h / lineH));

9.3.5 命令发送

sendTerminalCmd() 从输入框获取命令，通过 nativeWrite 写入 PTY master fd，命令末尾追加 \n。

9.3.6 会话终止

stopPtySession() 停止读取线程，调用 nativeClose(fd, pid) 关闭 PTY 并终止进程。

10 内核命令执行

10.1 execViaScript()

内核命令通过写入临时 Shell 脚本文件执行，避免命令注入和参数转义问题：

private void execViaScript(File parentDir, String scriptName,
                           String cmdContent, ShellLineCallback cb)

流程：

1. 在 parentDir 下创建脚本文件
2. 写入 #!/system/bin/sh\n{cmdContent}
3. 通过 runPtyCommand("su -c 'sh {scriptPath}'", cb) 以 root 权限执行
4. 执行完成后删除脚本文件

10.2 runPtyCommand()

创建临时 PTY 会话执行命令，逐行回调输出：

private void runPtyCommand(String cmd, ShellLineCallback cb)

• 使用 nativeStart 而非 nativeStartShell（一次性命令执行）
• 循环读取输出，按 \n 分割逐行回调
• 忽略 \r 字符
• 命令结束后调用 nativeWaitExit 获取退出码，然后 nativeClose

10.3 stdbuf 检测

hasStdbuf() 检测系统中是否存在 stdbuf 命令，用于 wrapUnbuffered() 方法。若存在，在命令前添加 stdbuf -oL -eL 以禁用输出缓冲，确保实时获取输出。

11 在线更新系统

11.1 更新架构

应用包含两套独立的更新系统：

11.2 内核更新流程

手动检查（checkKernelUpdate()）不受 24 小时休眠限制，始终弹出更新对话框。

11.3 软件更新流程

11.4 下载引擎

downloadToFile() 方法特性：

• 支持 HTTP 重定向（301/302/303/307/308），最多 10 次
• 相对 URL 自动解析为绝对 URL
• 8KB 缓冲区流式写入
• 每 80ms 回调一次进度（下载量、总量、百分比、速度）
• 下载完成后自动 chmod 755 和 su -c chmod 755

11.5 更新休眠机制

取消更新后 24 小时内不再弹出相同类型的更新提示，通过 SharedPreferences 存储休眠截止时间戳。

12 内容同步系统

12.1 公告与资助

应用从服务器拉取公告和资助信息：

12.2 同步机制

syncContent() 方法：

1. 通过 fetchTextFile() 获取文本内容（5 秒超时）
2. 计算 SHA-256 哈希
3. 与缓存哈希比较，相同则跳过
4. 不同则更新 UI 和缓存

12.3 公告弹窗

应用启动时检查公告更新：

1. 获取最新公告内容
2. 计算 SHA-256 哈希
3. 与 PREF_ANNOUNCE_LAST_SHOWN_HASH 比较
4. 不同则弹出公告对话框
5. 用户点击"知道了"后记录已读哈希

12.4 可点击链接

buildClickableAnnouncementText() 解析公告文本中的 URL（https://、http://、www. 开头），将其渲染为可点击的 ClickableSpan，颜色为主题色，点击后通过 ACTION_VIEW 在浏览器中打开。

13 主题系统

13.1 预设主题

13.2 自定义颜色

通过 Rainbow SeekBar（0-359 色相）选择自定义颜色。SPECIAL_COLORS 数组定义了 9 个渐变色节点，通过 HSV 插值实现平滑过渡：

private static final int[] SPECIAL_COLORS = {
    0xFFFF6B6B, 0xFFFFA94D, 0xFFFFD93D, 0xFF6BCB77,
    0xFF4DD0E1, 0xFF4D96FF, 0xFFA55EEA, 0xFFFF6BB3, 0xFFFF6B6B
};

自定义颜色时 themeSchemeIndex = -1，渐变尾色通过降低饱和度（0.45）生成。

13.3 渐变开关

switch_theme_gradient 控制是否启用渐变效果。启用后按钮、进度条等使用 themeColor → themeGradientEnd 的线性渐变（TL_BR 方向）。

13.4 主题应用范围

applyThemeColor() 影响以下 UI 元素：

• 标签栏文字和图标颜色
• 设置页标题文字颜色
• 进度条颜色（PorterDuffColorFilter）
• 按钮背景渐变（applyGradientToButton）
• Switch 组件的 thumb 和 track 颜色
• Chevron 图标颜色
• RGB 十六进制标签背景和文字颜色

13.5 主题预览

updateThemePreviewBar() 在设置页显示当前主题的实时预览条，支持纯色和渐变两种模式。

14 背景图片系统

14.1 功能

用户可为首页、驱动页、终端页设置自定义背景图片，并调整透明度。

14.2 图片选择

pickBackgroundImage() 根据 Android 版本采用不同策略：

• API 33+：先通过 su -c pm grant 授予 READ_MEDIA_IMAGES 权限，再调用 ACTION_OPEN_DOCUMENT 选择图片
• API 23-32：检查 READ_EXTERNAL_STORAGE 权限，必要时请求运行时权限
• API 22 及以下：直接启动图片选择器

14.3 图片加载

loadBgImageFromUri() 使用 BitmapFactory.Options 采样加载，限制最大宽度为 2048px，避免 OOM。通过 BitmapDrawable 设置背景，初始 alpha 值由 imgAlpha 决定。

14.4 透明度调节

SeekBar（0-255）控制背景透明度，updateBgImageAlpha() 实时更新三个页面的背景 alpha。

14.5 持久化

图片 URI 通过 takePersistableUriPermission() 获取持久读取权限，URI 字符串和 alpha 值保存到 SharedPreferences。

15 动画系统

15.1 弹性动画

springAnim(View v) 实现按钮点击弹性效果：

15.2 按压效果

applyPressEffect(View v) 为按钮添加触摸反馈：

applyPressEffectNoShadow() 是简化版，无前景叠加效果。

15.3 对话框动画

animateUnifiedDialog() 为对话框添加弹出动画：

15.4 页面切换动画

switchPage() 在页面间切换时：

• 旧页面：alpha 1→0 (200ms)，完成后隐藏
• 新页面：alpha 0→1 (200ms，延迟 100ms)
• 标签栏：选中态颜色、字号、粗体变化
• 轻量弹性动画：scale 1.0→0.94→1.0 (320ms, OvershootInterpolator 1.8f)

16 数据持久化

16.1 SharedPreferences

应用使用两个 SharedPreferences 实例：

16.2 持久化字段

17 颜色系统

17.1 颜色定义 (colors.xml)

18 Drawable 资源说明

19 构建与部署

19.1 构建前提

• Android SDK（API 29）
• Android NDK（支持 ndk-build）
• JDK 8+

19.2 NDK 构建

在 jni/ 目录执行：

ndk-build

生成产物：

• libs/armeabi-v7a/libptyterm.so
• libs/arm64-v8a/libptyterm.so

19.3 APK 构建

使用 Android SDK 构建工具：

android update project --path . --target android-29
ant debug

或使用 Android Studio / Gradle 导入项目后构建。

19.4 签名与发布

应用使用 HTTP 明文通信，部署时需注意：

• 确保服务器支持 HTTP 访问
• 目标设备需已获取 Root 权限
• 应用通过在线更新分发，初始安装通过 APK 侧载

20 关键类与方法索引

20.1 MainActivity 成员变量

20.2 MainActivity 方法索引

21 注意事项

21.1 安全性

21.2 兼容性

• 最低支持 Android 5.0 (API 21)，但实际功能依赖 Root 权限和 su 命令
• 不同厂商的 Android 系统对 PTY 的支持可能不同
• 存储权限处理区分了 API 33（READ_MEDIA_IMAGES）和 API 23（READ_EXTERNAL_STORAGE）
• 背景图片选择在 API 33+ 设备上通过 pm grant 授权，依赖 su 可用

21.3 性能

• PTY 终端输出在 4KB 缓冲区中循环读取，高频输出时可能存在延迟
• 背景图片加载限制最大宽度 2048px，通过采样减少内存占用
• 下载使用 8KB 缓冲区，进度回调间隔 80ms
• 更新休眠机制 24 小时，避免频繁网络请求

21.4 代码规范