diff --git a/README.md b/README.md index 1ba2ec3..19769d2 100644 --- a/README.md +++ b/README.md @@ -1,46 +1,61 @@ # ShortX ToolHub -一个模块化的 ShortX JS 浮窗工具框架，支持广播关闭、子线程模型、日志记录和可扩展面板。 +一个模块化的 ShortX JS 浮窗工具框架，支持广播关闭、子线程模型、日志记录、自动下载与热更新。 --- ## 目录结构 +### 实机（ShortX 数据目录） ``` -ToolHub.js # 入口文件（粘贴到 ShortX 任务） -code/ -├── th_1_base.js # 基础工具函数、Logger、崩溃处理、进程信息 -├── th_2_core.js # 核心逻辑、浮窗管理、Shell 桥接、ContentProvider -├── th_3_panels.js # 面板配置、按钮定义、对话框、文本查看器 -├── th_4_extra.js # 额外面板（设备信息、快捷操作等） -└── th_5_entry.js # 入口面板定义、广播接收器注册 +shortx.getShortXDir()/ +├── ToolHub/ +│ └── code/ +│ ├── th_1_base.js +│ ├── th_2_core.js +│ ├── th_3_panels.js +│ ├── th_4_extra.js +│ └── th_5_entry.js +└── ToolHub/logs/ + └── init.log +``` + +### 服务器（项目维护目录） +``` +ToolHub/ +├── ToolHub.js # 入口文件（粘贴到 ShortX 任务） +└── code/ + ├── th_1_base.js + ├── th_2_core.js + ├── th_3_panels.js + ├── th_4_extra.js + └── th_5_entry.js ``` --- ## 部署步骤 -### 1. 创建目录 +### 1. 创建目录（可省略） -在 ShortX 数据根目录下创建： +入口文件会自动检测并创建 `ToolHub/code/` 目录，无需手动操作。 -``` -ShortX数据根目录/ -└── ToolHub/ - └── code/ +若需手动创建，在 ShortX 数据根目录下执行： +```bash +mkdir -p ToolHub/code +chmod 700 ToolHub/code +chown 1000:1000 ToolHub/code ``` -> ShortX 数据根目录路径通过 `shortx.getShortXDir()` 获取，通常为 `/data/system/shortx_XXXXXXXX/` +### 2. 放置入口文件 -### 2. 放置文件 +将 `ToolHub.js` 的内容粘贴到 ShortX 任务中。 -- 将 `ToolHub.js` 的内容粘贴到 ShortX 任务中 -- 将 `code/` 目录下的 5 个 `th_*.js` 文件放入 `ToolHub/code/` +子模块会自动从 git 仓库下载到 `ToolHub/code/`，无需手动复制。 ### 3. 运行 执行 ShortX 任务，正常返回示例： - ```json { "ok": true, @@ -53,35 +68,86 @@ ShortX数据根目录/ --- +## 自动下载与权限管理 + +入口文件启动时会自动完成以下操作： + +1. **缺失自检**：检查 `ToolHub/code/` 下的 5 个模块文件，缺失则从 git raw URL 自动下载 +2. **权限保障**：目录不存在时自动创建并设置 `chmod 700` + `chown 1000:1000` +3. **权限判断**：通过 `stat` 命令精确检查 uid/gid/mode，不正确才修复 +4. **单次检查**：一次启动中只检查一次目录权限，避免重复 shell 开销 + +--- + +## 版本管理与热更新 + +每个模块文件第一行必须包含版本注释： +```javascript +// @version 1.0.0 +``` + +入口文件中的 `MODULE_MANIFEST` 定义各模块的期望版本。启动时若本地版本与期望版本不匹配，自动重新下载。 + +升级模块时只需： +1. 更新模块文件中的 `@version` 版本号 +2. 同步更新 `ToolHub.js` 中 `MODULE_MANIFEST` 的对应版本号 +3. 推送到 git 仓库 +4. 实机下次启动时自动检测并更新 + +--- + +## 下载校验 + +- **大小校验**：对比 HTTP `Content-Length` 与实际写入字节数，不匹配则抛异常 +- **内容校验**：读取下载文件前 200 字节，检测 `200KB） + +### 运行日志 +路径：`shortx.getShortXDir() + "/ToolHub/logs/"` + +日志文件按天分割，默认保留 3 天。 + +--- + ## 关闭浮窗 通过 adb 或 ShortX Shell 执行： - ```bash am broadcast -a shortx.wm.floatball.CLOSE ``` --- -## 日志位置 +## 模块说明 -``` -ShortX数据根目录/ToolHub/logs/ -``` - -日志文件按天分割，默认保留 3 天。 +| 文件 | 职责 | 线数参考 | +|------|------|---------| +| `th_1_base.js` | 基础工具函数、Logger、崩溃处理、进程信息获取 | ~1300 | +| `th_2_core.js` | 浮窗管理器、Shell 执行器、ContentProvider 读取器、图标缓存 | ~4700 | +| `th_3_panels.js` | 面板配置工厂、按钮构建器、对话框、文本查看器 | ~2900 | +| `th_4_extra.js` | 额外面板：设备信息、网络状态、快捷操作 | ~1600 | +| `th_5_entry.js` | 入口面板定义、广播接收器注册、启动流程 | ~300 | --- -## 模块说明 +## 模块加载容错 -| 文件 | 职责 | -|------|------| -| `th_1_base.js` | 工具函数、Logger、崩溃处理、进程信息获取 | -| `th_2_core.js` | 浮窗管理器、Shell 执行器、ContentProvider 读取器 | -| `th_3_panels.js` | 面板配置工厂、按钮构建器、对话框、文本查看器 | -| `th_4_extra.js` | 额外面板：设备信息、网络状态、快捷操作 | -| `th_5_entry.js` | 入口面板定义、广播接收器注册、启动流程 | +- `for` 循环加载 5 个模块，单模块失败记录日志但不阻断后续加载 +- `th_5_entry.js` 失败时直接抛异常（启动必备） +- 错误信息落盘到 `ToolHub/logs/init.log`，便于实机排查 --- @@ -90,3 +156,4 @@ ShortX数据根目录/ToolHub/logs/ - 入口文件通过 `loadScript()` 动态加载子模块，`var` 声明通过间接 `eval` 挂到全局作用域 - 子模块加载顺序不可更改：base → core → panels → extra → entry - 调试请查看日志文件，不通过返回 JSON 暴露内部细节 +- 单个模块建议不超过 200KB，超过时启动日志会记录 WARN 提示拆分