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

🎯 ToolHub 悬浮球正式版

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

✨ 核心特性

🚀 快速部署

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

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

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

⚙️ 入口配置

ToolHub.js 顶部可配置安全模式。更新源固定为 GitHub，已取消镜像源选择：

var UPDATE_SECURITY_MODE = 2; // 0: 普通更新, 1: manifest哈希校验, 2: 完整验签安全更新
var TOOLHUB_ENTRY_VERSION = 20260810005000; // 入口文件版本，仅在 ToolHub.js 变化时提升

更新源

• GitHub：https://raw.githubusercontent.com/7015725/Toolhub-FloatBall/main/（固定，未通过校验时不覆盖本地模块）
• Beta 通道走同一仓库的 beta 分支，目录为 ToolHub-Beta

安全模式

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

配置值无效时自动强制回落到完整验签模式 2，避免误关签名校验。

📁 实机目录结构

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_button_editor.js
    │   ├── th_14_button_icon_editor.js
    │   ├── th_14_button_shortcut.js
    │   ├── th_14_color_picker.js
    │   ├── th_14_icon_picker.js
    │   ├── th_14_panels.js
    │   ├── th_14_schema_editor.js
    │   ├── th_15_extra.js
    │   ├── th_15_main_panel.js
    │   ├── th_16_entry.js
    │   ├── th_17_pointer.js
    │   ├── th_18_pointer_ocr.js
    │   ├── th_19_position_state.js
    │   ├── th_20_pickword.js
    │   ├── th_21_result_preview.js
    │   ├── th_22_image_viewer.js
    │   ├── th_23_screenshot_manager.js
    │   ├── .installed_manifest.json
    │   ├── .trusted_manifest_version
    │   └── .trusted_sha_<module>
    ├── logs/
    │   ├── init.log
    │   └── ShortX_ToolHub_yyyyMMdd.log
    └── toolhub.db

📤 启动返回示例

正常启动：

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

任一关键模块加载失败返回 failed，部分失败返回降级状态 degraded 并给出加载异常列表。

🔐 安全更新链路

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 / th_14_icon_picker	颜色选择器与 ShortX 图标选择器
th_14_button_editor / th_14_button_icon_editor / th_14_button_shortcut	按钮编辑、按钮图标编辑、结构化快捷方式编辑
th_14_schema_editor	Schema 编辑器
th_15_extra / th_15_main_panel	ToolApp Shell、页面栈、响应式布局；主面板网格构建与显隐
th_16_entry	主线程同步与 ToolApp 生命周期
th_17_pointer / th_18_pointer_ocr	指针悬浮球、端点识别、框选 OCR 截图
th_19_position_state	固定位置状态机与重建回滚
th_20_pickword	拾字：屏幕取字、Emoji 字素选区、复制、翻译、钉屏
th_21_result_preview	结果预览浮窗，支持垂直位置百分比设置
th_22_image_viewer	图片服务：缩略图加载、原图查看、公共副本读写
th_23_screenshot_manager	截图管理器：内部截图与已保存双标签管理

🎮 按钮动作类型

type	行为
open_settings	打开设置 / ToolApp
open_screenshot_manager	打开截图管理器
open_viewer	打开日志查看器（启动/运行日志倒序）
toast	显示 Toast
app	启动 App，支持 launchUserId 指定用户
shell	通过 shell 广播桥发送 base64 命令
broadcast	发送自定义广播，兼容 extra / extras
content	执行 Content 按钮，结果进查看面板或 Toast
pointer	启动指针工具链（端点识别 / 框选 OCR）
shortcut	优先结构化快捷方式（LauncherApps），仅显式 legacy_js 才执行旧 JS 启动代码

🔀 更新通道

• Stable（正式版）：跟踪 main 分支，目录为 ToolHub，默认通道。
• Beta（测试版）：跟踪 beta 分支，目录为 ToolHub-Beta，抢先体验新功能。
• 两条通道独立代码、SQLite 数据库、缓存、日志和截图目录，可随时切换互不影响。
• 切换完成后自动检查新通道更新，检查结果同步到更新页、设置首页摘要和红点。
• 更新与版本页提供通道健康自检，核对活动通道、分支、根目录、启动状态、签名清单与 SQLite 存储，诊断报告保存在当前通道 diagnostics/channel-health-last.txt。

💾 配置与持久化

设置、按钮、Schema 与截图记录统一保存到结构化 SQLite 数据库 toolhub.db，写入策略保持临时文件 → flush/sync → rename 原子落盘，去抖合并写入，关闭时强制落盘。

📍 悬浮球位置恢复

保存时同时记录像素、比例、吸边侧等元数据，横竖屏切换后按比例恢复，吸边状态优先回到 left/right 边缘。固定位置由独立状态机管理，重建失败自动回滚到上一个可用状态。

📝 日志路径

• 启动日志：shortx.getShortXDir()/ToolHub/logs/init.log
• 运行日志：shortx.getShortXDir()/ToolHub/logs/ShortX_ToolHub_yyyyMMdd.log
• 悬浮球「日志」入口可直接查看当日日志（倒序）

🛠️ 常见问题

📋 更新日志

1. 2026-08-10
   Beta 已验证更新同步到 Stable：可信清单离线安全回退；统一 IME 避让与键盘收起几何恢复；多项稳定性修复收尾。
2. 2026-07-27
   修复了因 WindowManager 同步移除导致 system_server 重启的问题；主面板与共享遮罩改为异步移除并补齐 generation 保护。
3. 2026-07-21
   新增 Stable 与 Beta 双更新通道（独立代码、数据、缓存与日志）；新增通道健康自检与诊断报告；切换通道后自动检查更新并同步红点提示；隔离两套通道的截图与拾字数据。
4. 2026-07-19 ~ 07-20
   接入截图管理器与内部/已保存双标签；修复截图公共副本存在性误判与重复保存；公共截图操作统一改用 ShortX Shell 桥；修复缩略图缓存无限增长的问题。
5. 2026-07-17 ~ 07-18
   拾字接入截图保存、分享、删除与自动清理；修复了因 Android 14 长按回调缺失导致拾字长按重启系统的问题；新增百度/有道翻译引擎与凭据设置；修复 Emoji 字素绘制与完整选区；修复主面板与结果预览全屏闪烁；新增结果预览垂直位置百分比设置。
6. 2026-07-16
   新增更新与版本页面（待更新列表、事务更新、历史记录分页）；修复了因 ScrollView.LayoutParams 解析失败导致更新页无法打开的问题；修复 ToolApp 输入法跨线程崩溃。
7. 2026-05-23
   新增 STRUCTURE.md；README 同步 18 子模块；ToolApp 返回体验优化；颜色面板固定 footer、支持边缘滑动关闭；新增 UPDATE_SECURITY_MODE 三档安全更新。
8. 2026-05-13 ~ 05-22
   新增 ToolApp 式设置主页与页面栈；内置交互式滑动返回；悬浮球背景色、角标、返回手势设置；颜色选择器与图标选择器完善。
9. 2026-05-07
   引入 manifest.json + manifest.sig 签名清单；子模块按 size/sha256 校验；增加最低可信清单版本与防回滚。

---

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