Orbit for Android

在已 Root 的 Android 设备上管理 Mihomo：导入自己的 YAML，启动独立后台，并按 Android 用户身份选择需要绕过 TUN 的应用。

当前版本 0.1.54，适用于 Android 9 及以上的 ARM64 设备。应用使用 Kotlin、Jetpack Compose 与 Material 3，随包提供官方 Mihomo ARM64 内核。

YAML 编辑副本使用通过 AndroidView 接入的 Sora 原生编辑器，外围界面继续使用 Compose / Material 3；支持语法高亮、查找替换、两空格缩进、跳转行、自动换行及撤销重做。保存成功后才关闭编辑器，失败保留草稿，屏幕旋转后继续编辑。详见 编辑器说明。

界面使用原生 Jetpack Compose 与 Material 3 Expressive + Bento 布局。首页运行卡片右上角使用与 Windows 主页同等视觉比例的淡色细描边静态 Logo，随内容宽度适配。首页运行卡片提供独立的启动 / 停止与重启按钮，按下时使用系统触觉及轻微放大反馈，重启不再需要滑动。Web UI 与应用绕过各用两行、等高并排显示，统一 18dp 图标、14sp 标题和 12sp 次级说明；绕过状态示例为“已开启 · 221 有效”，数量来自实际运行状态。首页不显示临时 Root 授权卡片，授权与组件检查统一在设置页操作。延迟卡片收紧上下留白及标题与结果间距，与当前配置等宽，横向显示三个备注及 HTTP(S) 延迟，右上角分别打开设置和手动刷新；真实测试链接仅在设置中展示。延迟、CPU 和内存读数统一使用 16sp 中等字重及正文色。CPU 与内存使用紧凑的两张资源卡片，窄屏大字体下自适应单列，CPU 显示实际百分比，内存按 1024 进制显示 MiB；进入首页采样一次，点击任一资源卡片刷新，长按内存卡片可开启内存软限制并设置 64–8192 MiB 上限，通过 Go 运行时 GOMEMLIMIT 促进回收。运行中保存会受控重启当前运行配置，停止时保存仅供下次启动使用；关闭限制同样通过重启生效。卡片区分已生效、待生效与待核验。软限制针对 Go 管理的内存，RSS 可能超过设定值；它不是进程 RSS 硬上限。旧版仅供显示的数值保留，升级不会自动启用限制。

设置中的色彩风格保留系统 Monet，并提供 Tonal Spot、Neutral、Vibrant、Expressive、Rainbow、Fruit Salad、Monochrome、Fidelity、Content 九种预设。配色使用 Google 官方 Material Color Utilities，明确选择 2025 规范及手机平台；部分风格依照官方实现沿用基础规则。Android 12+ 从系统色提取种子色，旧系统使用内置种子色，保留跟随系统 / 手动深色设置。主题选择保存后即时生效。主题、应用排序筛选、配置操作和 AI 模型选择使用圆角弹出菜单，可切换项有选中底色；删除、重启更新等确认流程保持各自语义。

顶栏底部常驻 8dp 状态轨道：加载条占上方 4dp，下方保留 4dp 间隔，空闲时也不改变轨道高度。准备组件、读取应用列表等操作不会移动卡片或改变滚动范围，也不会覆盖应用绕过页顶部开关；任务说明保留给无障碍读取。圆角统一按功能分级：运行主卡 / 对话框 32dp、分区卡片 / 菜单外壳 28dp、紧凑卡片 / 列表 20dp、内嵌操作 12dp、状态标记 8dp；胶囊导航与按钮保留完整圆角。页面可连续延伸到底栏后方，末尾单独避让。悬浮底栏仅保留首页、配置、应用、设置四页，日志移至“设置 → 日志”二级页面。底栏按 Telegram 参考图收紧为可用宽度的 80%（最大 400dp）、高度 56dp，包含 24dp 图标、12sp 标签、浅色选中胶囊及柔和阴影；选中图标由空心过渡为实心，按下轻微压扁并回弹。长按拖动胶囊采用 1.08 倍形变，保留磁性吸附、系统短震 / 点击声反馈及未保存修改离页保护。日志保留筛选、跟随、手动刷新和正常停止记录折叠，返回设置后停止日志查询，再次进入保留筛选和跟随选择。常规页面切换立即响应，隐藏页面保留草稿但不参与测量。设置中的下游设备代理、日志二级页支持系统预测返回：手势过程中缩放并移动二级页，后方提前布局真实设置页，保留滚动位置和底栏。预览期间设置页不接收操作，取消手势回到原二级页，完成后才返回；旧版 Android、顶部返回按钮及普通系统返回保留相同返回目标。配置列表卡片压缩操作区底部留白，应用绕过总开关采用紧凑单行；常驻说明精简，保留必要状态、错误和确认提示。卡片与操作保留窄屏、大字体和横屏回归。

下游设置页退到后台时暂停状态轮询，回到前台立即刷新。本次检查见 0.1.41 本地验证记录。界面示例以长边 3168、短边 1440 的原生像素尺寸验证。

下载 APK · 更新记录 · 发行与签名说明

从配置开始

1. 安装 Release 中的 Orbit-Android-v0.1.54-arm64.apk，打开应用；如需手动授权，在设置页的“Root 与运行环境”点击“授权并准备”。
2. 从本地文件或 HTTPS 地址导入 Mihomo YAML，选择配置后主动启动内核。
3. 在首页查看运行状态、进程资源、端口和 HTTP 延迟；通过“设置 → 日志”排查启动与运行问题。
4. 如需使用面板，在自己的 YAML 中配置 HTTP(S) 控制接口、密钥及 external-ui。Orbit 从实际运行配置读取这些信息，并打开对应的 /ui/。

TUN、DNS、端口、代理组和分流规则均由用户 YAML 决定。Orbit 保存和导出原始配置字节，编辑时另存副本；不会补建控制接口或安装内置面板。仅配置 Unix / Pipe 控制接口时，应用的 HTTP API 和 Web UI 能力不可用。

从其他管理器导入的配置可能仍引用旧目录。若检查提示 path is not subpath of home directory or SAFE_PATHS，请在配置副本中将相关文件路径改到 /data/adb/orbit 下，例如 Tailscale 的 state-dir: /data/adb/orbit/meizu20tailscale。更改状态目录可能需要重新登录；保留原登录身份需要单独迁移对应状态。Orbit 不自动迁移旧目录或放宽 Mihomo 的路径检查。

应用绕过与后台运行

• 应用绕过：按包名及 Android 用户身份选择本体、分身和其他用户的应用，保存时重新解析完整 UID，合并到 tun.exclude-uid。共享 UID 的应用会一同绕过；进入 TUN 后的 DIRECT / PROXY 仍由 YAML 决定。
• 统一保存：绕过开关和勾选先保留在页面暂存中，有修改时显示底部保存栏；内核运行时可“保存并热重载”，未运行时仅保存，不自动启动。可取消修改，离页仍提示保存 / 放弃 / 取消；失败或取消智能选择不会清空原选择。
• 应用筛选：支持名称、包名、Android 用户及 UID 搜索，全部 / 用户 / 系统分类，以及名称 / 包名 / UID 排序和仅显示已选；筛选与滚动保留暂存勾选。
• 可选智能选择：统一从应用页的“AI 智能选择”入口配置 OpenAI 兼容接口及模型；可单独保存配置，主动开始分析才发送完整应用名单。结果只更新暂存勾选，API Key 由 Android Keystore 加密保存。
• 独立 Root 后台：组件位于 /data/adb/orbit。划掉应用后内核继续运行，再次打开只接管通过身份核验的现有实例。已确认运行的内核异常退出时，原 supervisor 最多按 2 / 4 / 8 秒恢复三次；主动停止不会触发恢复。
• 开机自启：默认关闭，开启后通过 Orbit 自己的 service.d 入口，在首次解锁后尝试恢复上次配置与已保存的绕过名单，重新解析完整应用 UID。发送前检查系统命令能力，支持时为本次显式广播附加临时后台启动授权，适配魅族的第三方 APP 冷启动限制；不修改永久系统白名单。Android 12+ 使用加急一次性任务，Root 在整个配置准备和启动期间持有事务锁；任务取消、失败或调用进程中断后本次开机不重试，不影响后续手动启动。升级后先正常打开应用完成组件准备，新事务从下一次开机生效，保留现有后台。日志区分派发模式、广播回执、调度停止原因和按 boot ID 区分的恢复记录；广播确认不等于内核已启动，加急任务仍受系统及 OEM 策略影响。
• 内核更新：从 Mihomo 官方稳定发行获取 ARM64 资产并校验完整性，沿用受控重启和失败回滚。应用更新另从本仓库 Release 获取。

0.1.50 已在当前接入的一加 13 和魅族 20 Pro 上分别完成真实重启、首次解锁及 Mihomo 自动恢复确认，原始配置与保存名单保持一致，详见 开机验收记录。该记录针对测试时的设备、ROM 和配置，不代替后续系统升级后的验证。

下游 IPv4 放行已有独立开关，用于在核验后的系统共享转发链中添加精确放行规则，不改写 YAML、路由或 DNS。UDP、DNS、IPv6 及原生恢复尚未完成验收，不能据此视为完整热点代理方案。

魅族出现 read packages list: invalid interned reference 时，可选装独立的 Orbit-Meizu-Packages Root 模块，配合 Orbit 0.1.47+ 使用。模块只在 Orbit 内核启动时生成应用身份 XML，并在该内核的私有挂载命名空间提供只读视图；监听系统包数据库更新，退出时结束同步。没有开机常驻服务，不改系统数据库或网络策略。安装 / 禁用后在下次手动启动内核生效，现有后台不会因打开 APP 被替换。详见模块说明。

源码与构建

使用 JDK 17、Android SDK 35、NDK 27.0.12077973、Rust / Cargo（验证版本 1.99.0，安装 aarch64-linux-android target）和仓库自带的 Gradle Wrapper，在仓库根目录执行：

.\gradlew.bat :app:testDebugUnitTest :app:lintDebug :app:assembleRelease

APK 输出到 app/build/outputs/apk/release/。需要归档 APK 与 SHA-256 时执行：

.\tools\build.ps1

归档路径为 release/<version>/Orbit-Android-v<version>-arm64.apk；版本从 Gradle 读取，已有正式产物不会被覆盖。自行构建的签名不一定与公开 APK 一致，固定发行身份及 CI 要求见签名说明。

v0.1.18 将 Root 运行时统一为 Rust：下游控制器、独立 Guard、supervisor、进程身份 / 采样、配置提交与运行快照、内核更新回滚、网络事务执行均由同一 ARM64 原生程序处理。APP 准备组件时按内容哈希保留版本并选择新命令入口；准备与重新打开只查询 / 接管现有实例，不启动或强制替换正在运行的旧后台。Kotlin/Compose、安全 YAML 解析、UID 选择、Keystore 和官方 Mihomo 保留。

正常运行不再派发 Shell tick / Guard / supervisor；有界原生 worker 保留操作锁与超时隔离，系统 iptables、ip、dumpsys / pm / am 继续通过精确参数调用。没有改写路由、DNS、YAML 或扩展下游放行范围。重构的本地验证没有向真机安装或启用这些程序，也没有性能、耗电或 OEM 兼容性验收结论。 当前 main 的独立 CI 会执行 Linux ARM64 / Android 交叉构建并按固定签名只发布当前版本，进度与结果见仓库 Actions。 架构、升级 / 回滚前提及剩余真机验收项见 Rust 原生运行时，测试与产物见 0.1.20 验证记录。原 第一阶段说明 保留为历史资料。

入口	职责
app/src/main/java/dev/orbit/android/MainActivity.kt	Compose 界面
OrbitCardStyle.kt / ProfileCards.kt / SettingsUi.kt（同目录）	共享卡片规范及配置 / 设置展示组件
OrbitModel.kt / OrbitStore.kt（同目录）	串行生命周期、原始配置和设置
ConfigEngine.kt / ControlConfig.kt / CoreApi.kt（同目录）	安全 YAML 解析、应用绕过、运行接口
RootClient.kt（同目录）与 app/src/main/assets/manager.sh	Root 传输 / 组件准备与旧版兼容入口
native/downstream/ / tools/build_downstream.py	Rust Root 运行时、隔离故障测试及 Android ARM64 交叉构建
app/src/test/	配置、接口、更新及生命周期回归测试

本项目采用 GPL-3.0；内核及其他组件的来源见第三方说明。