ToolHub 使用文档

一个运行在 system_server 的可视化悬浮工具箱

一、ToolHub 是什么？

ToolHub 是一个运行在 ShortX + Rhino（ES5） 环境中的系统级悬浮工具箱。

它不是普通 App，也不是前台界面程序，而是通过 WindowManager 直接创建系统悬浮窗，在任何界面之上提供一个始终可用的操作入口。

它解决的问题很简单：

把分散的 Shell、广播、系统跳转、调试入口，集中到一个随时能点到的悬浮球里。

二、运行环境与前提条件

在使用 ToolHub 之前，需要明确它的运行边界：

• Android 14 及以上（SDK 34）
• ShortX 环境
• JavaScript 引擎：Rhino（仅 ES5）
• 具备悬浮窗权限
• Shell 功能建议配合 Root 使用

需要特别说明的是：

• ToolHub 不使用 Activity
• 不使用 WebView / HTML / DOM
• 所有 UI 都由原生 View + WindowManager 构建
• 所有窗口操作都运行在独立的 HandlerThread 中

三、整体使用方式概览

ToolHub 的交互逻辑非常克制，只有三种操作：

1️⃣ 单击悬浮球

• 打开 主工具面板
• 显示你配置好的所有工具按钮

2️⃣ 长按悬浮球

• 打开 设置 / 管理面板
• 进行按钮管理和界面设置

3️⃣ 拖动悬浮球

• 改变位置
• 松手后自动吸边
• 闲置后半隐藏，减少遮挡

没有多余手势，也没有学习成本。

四、主工具面板（按钮系统）

1️⃣ 什么是“按钮”？

在 ToolHub 中，一个按钮代表一次完整、可执行的操作。

每个按钮都包含：

• 标题
• 图标
• 类型
• 对应的执行参数

按钮的定义全部存储在：

/data/system/ShortX_ToolHub/buttons.json

UI 只是对这个文件的可视化编辑与执行入口。

2️⃣ 支持的按钮类型

在 UI 中可以创建和管理多种类型的按钮，包括但不限于：

• Shell 命令
  • 支持 root
  • 支持多行命令
  • 自动编码存储，避免明文风险
• 应用启动
  • 通过包名拉起应用
  • 适合系统工具或隐藏入口
• 广播（Intent）
  • 发送自定义 action
  • 作为自动化流程的触发点
• 系统功能
  • 打开设置页
  • 打开日志查看器
  • 执行内部管理动作

3️⃣ 按钮管理（UI 功能）

按钮管理完全在 UI 中完成，不需要手动编辑 JSON：

• 新增按钮
• 编辑按钮参数
• 修改标题与图标
• 删除按钮（带二次确认）

所有操作都是：

• 即时生效
• 自动持久化
• 可随时再编辑

4️⃣ Shell 按钮的执行机制说明

为了保证稳定性，ToolHub 对 Shell 执行做了双层设计：

• 优先使用 ShortX 的 ShellCommand Action
• 若不可用，自动降级为广播桥接执行

这意味着即使环境发生变化，大多数 Shell 按钮仍然可以正常工作。

五、设置面板（可视化配置系统）

1️⃣ 设置面板的设计思路

ToolHub 的设置面板不是“写死的界面”，而是由一个 Schema 文件动态生成。

• UI 结构来自 schema.json
• 实际数值存储在 settings.json
• 设置项与 UI 自动绑定

这种方式带来的好处是：

• 新增配置 ≠ 重写 UI

2️⃣ 可配置内容一览

设置面板覆盖了 ToolHub 的几乎所有行为：

悬浮球相关

• 大小
• 图标类型
• 文字与颜色
• 闲置透明度

面板布局

• 行数 / 列数
• 单元格大小
• 间距与内边距
• 图标与文字显示方式

主题与外观

• 跟随系统 / 强制亮色 / 强制暗色
• 日夜背景色
• 文字颜色
• 面板透明度

动画与交互

• 吸边动画时长
• 点击回弹效果
• 长按判定时间
• 震动反馈

执行与日志

• Shell 执行策略
• 日志开关
• Debug 级别
• 日志保留天数

六、实时预览机制（核心特性）

1️⃣ 什么是实时预览？

在 ToolHub 中：

你在设置面板中做的每一次修改，都会立刻反映到 UI 上。

例如：

• 改悬浮球大小 → 球立即变化
• 改面板行列 → 面板即时重排
• 改颜色 → 背景和文字立刻刷新

2️⃣ 预览是如何实现的？

ToolHub 在内部使用了三层状态：

• 当前生效配置
• 临时编辑配置
• UI 使用的有效配置快照

当你修改某个设置时：

• 不会立即破坏现有 UI
• 只刷新受影响的部分
• 刷新过程全部在 WM 专属线程中完成

这样做的结果是：

• 无闪烁
• 无重建风暴
• 无跨线程异常

3️⃣ 为什么这在 system_server 中很重要？

在 system_server 环境里：

• View 重复 add/remove 很容易崩
• 线程切换错误会直接抛异常
• UI 状态一旦乱掉就无法恢复

实时预览机制的本质是：

• 把“危险操作”拆小、拆慢、拆可控。

七、日志与故障排查

ToolHub 内置完整日志系统：

• 日志路径：

/data/system/ShortX_ToolHub/logs/

• 按日期分文件
• 自动清理旧日志
• 支持 DEBUG / INFO / WARN / ERROR / FATAL

在 system_server 里，日志不是可选项，而是必需品。

八、适合怎样使用 ToolHub？

ToolHub 更适合以下场景：

• 常用 Shell / 广播 / 系统跳转
• 自动化调试入口集合
• 系统级工具快捷面板
• 开发 / 折腾 / 调试用途

你可以把它理解为：

• Android 的系统级“工具抽屉”。

九、结语

ToolHub 并不追求花哨的 UI，也不试图伪装成普通 App。

它的目标很明确：

• 在 system_server 这种高风险环境中
• 提供一个稳定、可配置、可恢复的操作入口
• 让复杂操作变成一次点击

如果你习惯用配置描述行为，
如果你希望对系统有更直接的控制权，
那 ToolHub 会是一个长期驻留在你屏幕一角的工具。

ToolHub 配置文件下载：