docs: update README for signed ToolHub updates

2026-05-09 22:57:53 +08:00
parent 7ce5ebeda8
commit 523d6e2044
1 changed files with 255 additions and 194 deletions
--- a/README.md
+++ b/README.md
@@ -1,181 +1,161 @@
 # ShortX ToolHub

-一个模块化的 ShortX JS 浮窗工具框架，支持子模块自动下载、按 `Last-Modified` 热更新、启动日志记录，以及面向大图标库的分页式 ShortX 图标选择器。
+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`，并记录本地已信任清单版本，拒绝旧版本清单。
+- **本地可信回退**：网络或远端清单异常时，不盲目覆盖；已验证过的本地模块可继续使用。
+- **ShortX 图标选择器**：支持图标点选、搜索、分页、自适应列数，不再依赖手填图标名。
+- **颜色选择器**：支持常用色、最近色、RGB、透明度和实时预览。
+- **日志记录**：启动、更新、验签、加载异常写入 `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. 加载模块并启动悬浮球

 ---

 ## 目录结构

-### 实机（ShortX 数据目录）
-```
-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
-```
+### 实机目录

-### 服务器（项目维护目录）
-```
-ToolHub/
-├── ToolHub.js
-├── README.md
-└── 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
-```
-
---
-
-## 部署步骤
-
-### 1. 放置入口文件
-将 `ToolHub.js` 内容粘贴到 ShortX 任务中。
-
-### 2. 直接运行
-入口文件会自动：
-1. 检查并创建 `ToolHub/code/`
-2. 修复目录权限（`chmod 700` + `chown 1000:1000`）
-3. 对 16 个子模块做 HEAD 检测
-4. 缺失或有更新时自动下载覆盖
-5. 记录启动日志到 `ToolHub/logs/init.log`
-
---
-
-## 返回信息格式
-
-成功启动示例：
-```json
-{
-  "ok": true,
-  "started": true,
-  "msg": "ToolHub 启动成功：已按 WM 专属 HandlerThread 模型启动",
-  "syncMsg": "本次已覆盖更新 2 个子模块（新增 0 / 覆盖 2）：th_14_panels.js、th_16_entry.js",
-  "updatedCount": 2,
-  "updatedModules": ["th_14_panels.js", "th_16_entry.js"],
-  "closeAction": "shortx.wm.floatball.CLOSE",
-  "layout": {"cols": 2, "rows": 2}
-}
-```
-
-无子模块更新时：
-```json
-{
-  "ok": true,
-  "started": true,
-  "msg": "ToolHub 启动成功：已按 WM 专属 HandlerThread 模型启动",
-  "syncMsg": "子模块已是最新，本次未覆盖更新。",
-  "updatedCount": 0,
-  "updatedModules": [],
-  "closeAction": "shortx.wm.floatball.CLOSE",
-  "layout": {"cols": 2, "rows": 2}
-}
-```
-
-如果有非关键模块加载失败，会额外返回：
- `loadMsg`
- `loadErrors`
-
-如果启动失败，会额外返回：
- `err`
-
---
-
-## 子模块热更新机制
-
-当前机制不是版本号比对，而是：
- 对每个子模块发送 HTTP HEAD 请求
- 读取远端 `Last-Modified`
- 与本地 `.lm_模块名` 缓存比较
- 不一致则重新下载覆盖
- 网络检查失败时优先回退到本地已有文件
-
-因此：
- **入口文件无需维护 `MODULE_MANIFEST`**
- 模块里的 `@version` 仅可作为人工注释，不参与程序判断
-
---
-
-## ShortX 图标选择器优化
-
-按钮编辑页里的 ShortX 图标选择器已改为：
- **ShortX 图标名称编辑框已取消**，改为预览卡片 + 图标库点选
- **分页模式**，不再一次性塞入大批图标
- **图标列表按当前可用宽度自动排列列数，并结合可见高度计算每页容量**
- **自适应布局**：弹窗宽度、单元格尺寸、卡片高度均按屏幕比例自动计算，最大化利用可见空间
- 保留 **搜索 / 上一页 / 下一页**
- 选中图标后自动填回并收起
- 收起后再次点击 **展开图标库** 可正常重新打开
-
-当前交互要点：
-1. 图标库默认收起，点击 **展开图标库** 后打开
-2. 列数按当前可用宽度自动计算，屏幕更宽时一页可显示更多图标
-3. 每页容量按自动列数 × 当前可见行数实时计算，页面底部无空白
-4. 搜索、翻页时都会回到顶部，减少卡顿感和误触
-5. 选中图标后自动填回并收起图标库
-
-## 弹出式颜色选择器
-
-点击 **选择颜色** 按钮弹出独立颜色选择器弹窗：
- **图标预览区**：实时显示当前图标着色效果
- **最近使用**：最多 8 个，点击直接复用，自动去重并置顶
- **常用颜色**：21 色固定网格（7 列），点击直接选中
- **RGB 三色调色器**：红/绿/蓝各 0-255 拖动进度条，实时同步预览
- **透明度滑块**：A 通道 0-255，支持半透明图标着色
- **清空按钮**：一键恢复跟随主题
- **确定按钮**：确认选择并将颜色加入最近使用列表
-
-交互要点：
-1. 拖动 RGB 滑块时，预览图标实时变色，当前颜色值文本实时更新
-2. 点击常用色或最近色后，RGB 滑块自动同步到对应值
-3. 清空后滑块重置为 255/255/255/255（白/不透明）
-4. 最近颜色持久化存储，跨会话保留
-
---
-
-## 日志系统
-
-启动日志路径：
 ```text
-shortx.getShortXDir() + "/ToolHub/logs/init.log"
+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
 ```

-记录内容包括：
- 目录创建 / 权限修复
- 更新检测
- 下载开始 / 结束 / 异常
- 模块加载失败
- 模块体积告警（>200KB）
+### 仓库目录
+
+```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
+```

 ---

@@ -196,55 +176,136 @@ shortx.getShortXDir() + "/ToolHub/logs/init.log"
 | `th_11_action.js` | 按钮动作分发与执行 |
 | `th_12_rebuild.js` | 悬浮球重建逻辑 |
 | `th_13_panel_ui.js` | 设置面板通用 UI 组件 |
-| `th_14_panels.js` | 设置面板、按钮编辑器、ShortX 图标分页选择器 |
+| `th_14_panels.js` | 设置面板、按钮编辑器、图标选择器、颜色选择器 |
 | `th_15_extra.js` | 主面板与附加展示层 |
 | `th_16_entry.js` | 生命周期、广播注册、启动与销毁 |

 ---

-## 注意事项
+## 图标与颜色交互

- 入口文件只负责加载与汇总返回信息，不承载业务 UI
- `th_16_entry.js` 属于关键模块，加载失败会直接中止启动
- 不建议把调试细节直接塞进返回 JSON，优先写日志；返回信息只保留用户判断启动/更新所需的关键信息
- 若修改了模块结构、返回字段、图标选择器交互，记得同步更新 README 与相关技能说明
+### 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-09
+
+**文档更新**
+
+- README 改为匹配当前签名更新机制。
+- 移除旧版 `Last-Modified` 热更新描述。
+- 补充 manifest 验签、SHA256 校验、防回滚、本地可信回退说明。
+- 更新启动返回示例为当前中文精简字段。
+
+### 2026-05-07
+
+**安全升级**
+
+- 引入 `manifest.json` + `manifest.sig` 签名清单。
+- 入口内置 RSA 公钥，使用 `SHA256withRSA` 验签。
+- 子模块下载后按 `size` 与 `sha256` 校验。
+- 增加最低可信清单版本与本地可信版本，防止回滚。
+- 启动返回信息精简为 `状态 / 安全 / 同步 / 布局 / 关闭广播`。

 ### 2026-04-21

 **功能改进**
- **移除 ShortX 图标选择器分类标签**：顶部水平滚动分类标签已删除，简化 UI，图标列表仅保留搜索和分页
- **自适应布局参数调整**：弹窗宽度上限提升至 520dp，单元格最小宽度降至 52dp，卡片高度固定为屏幕高度 88%，滚动区域自动填充剩余空间
- **提升每页容量**：去掉 12–40 的人为限制，行数按实际可见高度计算，屏幕更大时每页可显示更多图标
- **去除分类过滤逻辑**：旧版内嵌选择器的分类相关代码、函数、状态已彻底清理
+
+- 移除 ShortX 图标选择器分类标签，保留搜索和分页。
+- 调整图标弹窗自适应布局参数，提高单页容量。
+- 清理旧版分类过滤逻辑。

 **Bug 修复**
- **修复面板显示崩溃**：删除 tabs 代码时遗留了一行重复的 `addView(searchEt)`，导致旧版图标选择器构建时抛出 `IllegalStateException: already has a parent`
+
+- 修复删除 tabs 代码后遗留重复 `addView(searchEt)` 导致的面板显示崩溃。

 ### 2026-04-20

 **Bug 修复**
- **修复 ShortX 图标调色板确认后未应用颜色**：颜色弹窗确认回调未同步触发 ShortX 图标预览链路，新增统一入口 `applyTintSelectionFromPopup()` 规范化处理
- **修复颜色弹窗确认时 `recentGrid` 引用异常**：`showColorPickerPopup()` 中最近颜色网格重建后未更新局部引用，改为延迟初始化并缓存 `recentGrid` 引用
- **改为独立维护 ShortX 图标颜色状态**：图标颜色与悬浮球颜色分离存储，避免互相覆盖
- **强制应用弹窗选中的图标颜色**：确保弹窗选色结果立即写入按钮编辑状态并刷新预览
+
+- 修复 ShortX 图标调色板确认后未应用颜色。
+- 修复颜色弹窗确认时 `recentGrid` 引用异常。
+- 图标颜色与悬浮球颜色改为独立维护，避免互相覆盖。

 **功能改进**
- **图标库与调色板** 默认收起，打开编辑面板时不再自动展开
- **常用颜色** 改为自适应布局，根据当前可用宽度自动计算列数（与 ShortX 图标列表一致）
- **ShortX 图标浮窗选择器** 改为分页模式，按当前可见容量动态计算每页图标数量
- 修复图标选择器关闭后无法再次打开的问题
- 入口返回信息增加中文 `msg` / `syncMsg` 及 `updatedModules` 字段
- 优化入口返回信息格式
- **设置面板改造**：取消“执行与查看器”、“悬浮球文字/大小/颜色”设置项
- **悬浮球图标配置** 支持 ShortX 图标选择器（弹窗列表+搜索）和调色板拖拽选色
- **弹出式颜色选择器**：新增独立弹窗，支持最近使用颜色（8 个）、RGB 实时调色、常用色网格、透明度滑块，最近颜色持久化存储
+
+- 图标库与调色板默认收起。
+- 常用颜色改为自适应布局。
+- ShortX 图标浮窗选择器改为分页模式。
+- 设置面板移除悬浮球文字相关设置项。
+- 新增独立颜色选择器，支持最近色、常用色、RGB、透明度和实时预览。

 **代码清理**
- **统一图标弹窗**：按钮编辑与悬浮球设置复用同一套 `showShortXIconPickerPopup` 和 `showColorPickerPopup`
- **清理悬浮球文字相关死代码**：删除悬浮球文字开关、文字大小、文字颜色等 UI 渲染与持久化残留
+
+- 按钮编辑与悬浮球设置复用图标选择器和颜色选择器。
+- 清理悬浮球文字相关死代码。