# ShortX ToolHub

ShortX ToolHub 是一个面向 **ShortX / Rhino ES5 JS** 的模块化悬浮工具框架。
入口文件 `ToolHub.js` 负责安全拉取、验签、校验并加载子模块；业务 UI 和功能拆分在 `code/th_*.js` 中维护，避免单个 JS 文件过大。

当前仓库地址：

```text
https://git.xin-blog.com/linshenjianlu/ShortX_ToolHub
```

---

## 核心特性

- **模块化加载**：入口文件只做启动、同步、校验与汇总返回；功能代码拆到 16 个子模块。
- **签名更新机制**：远端 `manifest.json` 必须通过 `manifest.sig` 的 RSA 签名校验后才可信。
- **SHA256 文件校验**：每个子模块按清单中的 `sha256` 和 `size` 校验，通过后才覆盖本地文件。
- **防回滚**：入口内置 `MIN_TRUSTED_MANIFEST_VERSION`，并记录本地已信任清单版本，拒绝旧版本清单。
- **本地可信回退**：网络或远端清单异常时，不盲目覆盖；已验证过的本地模块可继续使用。
- **App 化设置页**：设置主页、按钮管理、按钮编辑等页面使用统一 Shell 与页面栈，支持顶部返回/关闭。
- **系统返回适配**：支持导航键返回；悬浮窗内置左右边缘滑动返回，优先在 ToolHub 页面栈内返回，栈空后关闭面板。
- **ShortX 图标选择器**：支持图标点选、搜索、分页、自适应列数，不再依赖手填图标名。
- **颜色选择器**：使用折叠式完整调色板，支持常用色、最近色、RGB、透明度和实时预览；避免重复内联色板。
- **自适应布局**：ToolApp 根据屏幕尺寸调整宽高，按钮管理页底部操作区保持可见。
- **日志记录**：启动、更新、验签、加载异常写入 `ToolHub/logs/init.log`。

---

## 快速部署

### 1. 安装入口文件

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

> 注意：`ToolHub.js` 是信任根，内置 RSA 公钥和最低可信清单版本。入口文件本身不能安全地自我更新；入口升级时需要手动替换一次。

### 2. 首次运行

入口会自动完成：

1. 创建 `shortx.getShortXDir()/ToolHub/code/`
2. 下载 `manifest.json` 与 `manifest.sig`
3. 使用入口内置公钥验签清单
4. 校验清单版本，防止回滚
5. 按清单下载 16 个子模块到临时文件
6. 校验 `size` 与 `sha256`
7. 校验通过后覆盖本地模块
8. 加载模块并启动悬浮球

---

## 目录结构

### 实机目录

```text
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_07_shortcut.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_15_extra.js
    │   └── th_16_entry.js
    └── logs/
        └── init.log
```

### 仓库目录

```text
ShortX_ToolHub/
├── ToolHub.js
├── ToolHub.js.sha256
├── README.md
├── manifest.json
├── manifest.sig
├── code/
│   └── th_*.js
└── scripts/
    └── generate_signed_manifest.py
```

---

## 启动返回示例

### 正常启动，无模块更新

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

### 正常启动，有模块更新

```json
{
  "ok": true,
  "状态": "ToolHub 启动成功",
  "安全": "✓ 已验签 v20260507155220 / toolhub-targets-2026-rsa3072",
  "同步": "✓ 已更新 2 个模块：th_14_panels.js、th_16_entry.js",
  "布局": "4×4",
  "关闭广播": "shortx.wm.floatball.CLOSE",
  "更新模块": ["th_14_panels.js", "th_16_entry.js"]
}
```

### 启动失败

失败时会返回：

- `ok: false`
- `状态: "ToolHub 启动失败"`
- `安全`: 当前验签/清单状态
- `错误`: 失败原因
- `加载异常`: 非关键模块加载失败列表（如存在）

---

## 安全更新机制

当前更新链路不是旧版 `Last-Modified` 热更新，而是：

1. `ToolHub.js` 内置可信 RSA 公钥。
2. 远端仓库分发：
   - `manifest.json`
   - `manifest.sig`
   - `code/*.js`
3. 入口下载清单和签名。
4. 使用 `SHA256withRSA` 校验 `manifest.sig`。
5. 检查 `manifest.keyId` 是否在入口信任列表内。
6. 检查 `manifest.version` 是否低于最低可信版本或本地已信任版本。
7. 每个模块下载到 `.tmp`。
8. 校验模块 `size` 和 `sha256`。
9. 校验通过才覆盖本地模块。
10. 所有模块加载正常后，保存本地可信清单版本。

当前 keyId：

```text
toolhub-targets-2026-rsa3072
```

---

## 模块职责

| 文件 | 职责 |
|------|------|
| `th_01_base.js` | 基础工具、日志、配置校验、通用辅助 |
| `th_02_core.js` | `FloatBallAppWM` 构造、基础状态与核心工具 |
| `th_03_icon.js` | 图标缓存、Bitmap 管理、悬浮球图标加载 |
| `th_04_theme.js` | 主题、颜色、样式工具 |
| `th_05_persistence.js` | 持久化与设置数据层 |
| `th_06_icon_parser.js` | 图标解析、ShortX 内置图标扫描与回退 |
| `th_07_shortcut.js` | 快捷方式选择器 |
| `th_08_content.js` | ContentProvider 读取与通用 query |
| `th_09_animation.js` | 面板动画、吸边、显示/隐藏管理 |
| `th_10_shell.js` | Shell 执行层 |
| `th_11_action.js` | 按钮动作分发与执行 |
| `th_12_rebuild.js` | 悬浮球重建逻辑 |
| `th_13_panel_ui.js` | 设置面板通用 UI 组件 |
| `th_14_panels.js` | 设置子页面、按钮编辑器、图标选择器、颜色选择器 |
| `th_15_extra.js` | 主面板、ToolApp 页面栈、设置主页、按钮管理页 |
| `th_16_entry.js` | 生命周期、广播注册、系统返回处理、启动与销毁 |

---

## 图标、颜色与设置交互

### ToolApp 设置页

- 设置、按钮管理、按钮编辑统一运行在 ToolApp Shell 内。
- 顶部栏提供返回与关闭，子页面优先通过页面栈返回。
- 系统返回键会优先回到上一页；没有上一页时关闭 ToolApp。
- 悬浮窗无法稳定接入系统级预测性返回动画，因此 ToolHub 内置左右边缘滑动返回作为可用替代。
- 面板尺寸按屏幕自适应，减少小屏溢出与大屏空白。
- 按钮管理页底部操作区保持可见，避免被列表内容挤出屏幕。

### ShortX 图标选择器

- 图标库默认收起，点击后展开。
- 支持搜索、上一页、下一页。
- 按当前可用宽度自动计算列数。
- 按可见高度计算每页容量，减少空白和滚动浪费。
- 选中图标后自动回填并收起。
- 优先运行时扫描 ShortX 可用图标，避免维护超大静态图标表。

### 弹出式颜色选择器

- 图标预览实时显示着色效果。
- 最近使用颜色最多保留 8 个。
- 常用颜色使用自适应网格。
- RGB 与透明度滑块实时同步。
- 支持一键清空，恢复跟随主题。

---

## 日志

启动日志路径：

```text
shortx.getShortXDir() + "/ToolHub/logs/init.log"
```

常见记录内容：

- 目录创建与权限处理
- manifest 下载与验签结果
- 模块下载、哈希校验与覆盖更新
- 模块加载失败
- 启动异常
- 模块体积告警（超过 200KB）

---

## 维护与发布

### 修改子模块后

如果修改了 `code/*.js` 或 `ToolHub.js`，需要重新生成签名清单：

```bash
scripts/generate_signed_manifest.py
```

会更新：

```text
manifest.json
manifest.sig
ToolHub.js.sha256
```

然后再提交并推送。

### 修改 README

只改 `README.md` 不需要重新签名，因为 README 不参与手机端模块校验。

### 注意事项

- Rhino / ShortX JS 中统一使用 `var`，避免 `let` / `const`。
- 顶层不要使用 `return`。
- 入口文件是信任根，改动后需要用户手动替换 ShortX 任务中的入口。
- 不要把私钥提交到仓库。
- 不建议把调试细节塞进启动返回 JSON，优先写日志。

---

## 更新记录

### 2026-05-13

**功能改进**

- 新增 ToolApp 式设置主页与页面栈，设置、按钮管理、按钮编辑改为更接近 App 的层级导航。
- 支持系统导航返回；因 ToolHub 是悬浮窗 Overlay，系统级预测性返回动画不稳定，改为内置左右边缘滑动返回。
- ToolApp 尺寸按屏幕自适应，按钮管理页底部操作区保持可见。
- 按钮管理与按钮编辑布局继续轻量化，减少说明文字和视觉负担。
- ShortX 图标选择器风格与设置 UI 对齐。
- 移除重复内联颜色调色板，统一使用折叠式颜色选择器。

**稳定性修复**

- 改进 ToolHub 启动与清理流程。
- 修复设置页返回按钮状态、编辑器返回后页面栈状态、系统手势返回提示等细节问题。

### 2026-05-09

**文档更新**

- README 改为匹配当前签名更新机制。
- 移除旧版 `Last-Modified` 热更新描述。
- 补充 manifest 验签、SHA256 校验、防回滚、本地可信回退说明。
- 更新启动返回示例为当前中文精简字段。

### 2026-05-07

**安全升级**

- 引入 `manifest.json` + `manifest.sig` 签名清单。
- 入口内置 RSA 公钥，使用 `SHA256withRSA` 验签。
- 子模块下载后按 `size` 与 `sha256` 校验。
- 增加最低可信清单版本与本地可信版本，防止回滚。
- 启动返回信息精简为 `状态 / 安全 / 同步 / 布局 / 关闭广播`。

### 2026-04-21

**功能改进**

- 移除 ShortX 图标选择器分类标签，保留搜索和分页。
- 调整图标弹窗自适应布局参数，提高单页容量。
- 清理旧版分类过滤逻辑。

**Bug 修复**

- 修复删除 tabs 代码后遗留重复 `addView(searchEt)` 导致的面板显示崩溃。

### 2026-04-20

**Bug 修复**

- 修复 ShortX 图标调色板确认后未应用颜色。
- 修复颜色弹窗确认时 `recentGrid` 引用异常。
- 图标颜色与悬浮球颜色改为独立维护，避免互相覆盖。

**功能改进**

- 图标库与调色板默认收起。
- 常用颜色改为自适应布局。
- ShortX 图标浮窗选择器改为分页模式。
- 设置面板移除悬浮球文字相关设置项。
- 新增独立颜色选择器，支持最近色、常用色、RGB、透明度和实时预览。

**代码清理**

- 按钮编辑与悬浮球设置复用图标选择器和颜色选择器。
- 清理悬浮球文字相关死代码。