ToolHub 悬浮球正式版 – ShortX 模块化悬浮工具框架

🎯 ToolHub 悬浮球正式版

面向 ShortX / Rhino ES5 的模块化悬浮工具框架，把常用的 App 启动、Shell 执行、广播发送、设置调整放进一个可拖拽的悬浮球。

✨ 核心特性

🚀 快速部署

1. 复制仓库中的 ToolHub.js，粘贴到 ShortX 的 JS 任务中运行。

2. 首次运行会自动完成：

• 创建 shortx.getShortXDir()/ToolHub/code/
• 下载或读取 manifest.json
• 按安全模式校验清单与模块
• 下载 18 个子模块到临时文件，校验 size 与 sha256 后覆盖本地
• 加载模块并启动悬浮球

⚙️ 入口配置

ToolHub.js 顶部可配置更新源与安全模式：

var UPDATE_SOURCE = 1;          // 0: Gitea, 1: GitHub
var UPDATE_SECURITY_MODE = 0;   // 0: 普通, 1: manifest hash, 2: 完整验签

更新源

• Gitea：https://git.xin-blog.com/linshenjianlu/ShortX_ToolHub/raw/branch/main/
• GitHub：https://raw.githubusercontent.com/7015725/Toolhub-FloatBall/main/

安全模式

模式	含义
0	普通更新，不启用签名 / manifest 严格校验
1	读取 manifest，按 sha256 / size 校验模块
2	完整验签：清单签名、keyId、版本、防回滚、模块校验

📁 实机目录结构

shortx.getShortXDir()/
└── ToolHub/
    ├── code/
    │   ├── th_01_base.js
    │   ├── th_02_core.js
    │   ├── th_03_icon.js
    │   ├── th_04_theme.js
    │   ├── th_05_persistence.js
    │   ├── th_06_icon_parser.js
    │   ├── th_08_content.js
    │   ├── th_09_animation.js
    │   ├── th_10_shell.js
    │   ├── th_11_action.js
    │   ├── th_12_rebuild.js
    │   ├── th_13_panel_ui.js
    │   ├── th_14_panels.js
    │   ├── th_14_color_picker.js
    │   ├── th_14_icon_picker.js
    │   ├── th_14_schema_editor.js
    │   ├── th_15_extra.js
    │   ├── th_16_entry.js
    │   ├── .trusted_manifest_version
    │   └── .trusted_sha_<module>
    ├── logs/
    │   ├── init.log
    │   └── ShortX_ToolHub_yyyyMMdd.log
    ├── settings.json
    ├── buttons.json
    └── schema.json

📤 启动返回示例

正常启动：

{
  "ok": true,
  "状态": "ToolHub 启动成功",
  "安全": "✓ 已验签 v20260507155220 / toolhub-targets-2026-rsa3072",
  "同步": "✓ 子模块已是最新",
  "布局": "4×4",
  "关闭广播": "shortx.wm.floatball.CLOSE"
}

失败时返回 ok: false，并给出失败原因与加载异常列表。

🔐 安全更新链路

1. ToolHub.js 内置可信 RSA 公钥
2. 远端仓库分发 manifest.json、manifest.sig、code/*.js
3. 下载清单和签名，用 SHA256withRSA 验签
4. 检查 keyId 是否在信任列表内
5. 检查 manifest.version 是否低于最低可信版本或本地已信任版本
6. 模块下载到 .tmp，校验 size 和 sha256
7. 全部通过后覆盖本地模块并保存可信清单版本

🧩 主要模块职责

模块	职责
th_01_base	基础工具、配置校验、路径常量、文件 IO、原子写、日志基础
th_02_core	FloatBallAppWM 构造、核心 state、UI 工具对象初始化
th_03_icon / th_06_icon_parser	图标加载、缓存、Drawable 处理、ShortX 图标解析
th_04_theme	屏幕尺寸、旋转、Toast、振动、主题与 Monet 颜色
th_05_persistence	位置保存、设置保存、临时编辑缓存、实时预览刷新
th_08_content	ContentProvider 查询、Content 类型按钮读取
th_09_animation	悬浮球动画、吸边、面板显隐、系统返回、预测性返回
th_10_shell / th_11_action	Shell 广播桥执行层与按钮动作分发
th_12_rebuild	悬浮球重建、尺寸/图标/配置变化刷新
th_13_panel_ui / th_14_panels	设置项基础 UI、设置主页、按钮管理、按钮编辑
th_14_color_picker	颜色选择器：最近色、常用色、RGB、透明度、实时预览
th_14_icon_picker	ShortX 图标选择器：搜索、分页、收藏、最近、过滤
th_14_schema_editor	Schema 编辑器
th_15_extra / th_16_entry	ToolApp Shell、页面栈、响应式布局、主线程同步与生命周期

🎮 按钮动作类型

type	行为
open_settings	打开设置 / ToolApp
open_viewer	打开日志查看器
toast	显示 Toast
app	启动 App，支持 launchUserId
shell	通过 shell 广播桥发送 base64 命令
broadcast	发送自定义广播，兼容 extra / extras
shortcut	执行 shortcutJsCode，用于锁定主/分身快捷方式

💾 配置与持久化

主要配置文件：

• settings.json
• buttons.json
• schema.json

写入策略：临时文件 → flush / sync → rename；去抖合并写入，关闭时强制落盘。

📍 悬浮球位置保存

保存时同时记录像素、比例、吸边侧等元数据，横竖屏切换后按比例恢复，吸边状态优先回到 left/right 边缘。

📝 日志路径

• 启动日志：shortx.getShortXDir()/ToolHub/logs/init.log
• 运行日志：shortx.getShortXDir()/ToolHub/logs/ShortX_ToolHub_yyyyMMdd.log

🛠️ 常见问题

📋 更新日志

1. 2026-05-23
   新增 STRUCTURE.md；README 同步 18 子模块；ToolApp 返回体验优化；颜色面板固定 footer、支持边缘滑动关闭；新增 UPDATE_SECURITY_MODE 三档安全更新；模块化与日志系统稳定。
2. 2026-05-22
   设置页响应式与横屏适配；修复颜色面板 overlay 与返回预览冲突；修复 UI 按钮点击无反馈；重构 ToolApp surface 滑动返回，减少全屏透明边缘条对按钮的影响。
3. 2026-05-19
   新增悬浮球背景色、角标、返回手势设置；ShortX 图标选择器风格统一；优化横竖屏切换位置恢复。
4. 2026-05-13
   新增 ToolApp 式设置主页与页面栈；内置左右边缘交互式滑动返回；按钮管理与编辑层级导航；ShortX 图标浮窗选择器改为分页模式。
5. 2026-05-07
   引入 manifest.json + manifest.sig 签名清单；子模块按 size/sha256 校验；增加最低可信清单版本与防回滚。

---

作者：林深见鹿 | 博客：xin-blog.com
仓库：GitHub / Gitea
最后更新：2026-06-14