feat: 更新入口文件与模块 — 自动下载、版本校验、权限管理、日志落盘

README.md

@@ -1,46 +1,61 @@
 # ShortX ToolHub
 
-一个模块化的 ShortX JS 浮窗工具框架，支持广播关闭、子线程模型、日志记录和可扩展面板。
+一个模块化的 ShortX JS 浮窗工具框架，支持广播关闭、子线程模型、日志记录、自动下载与热更新。
 
 ---
 
 ## 目录结构
 
+### 实机（ShortX 数据目录）
 ```
-ToolHub.js          # 入口文件（粘贴到 ShortX 任务）
+shortx.getShortXDir()/
-code/
+├── ToolHub/
-├── th_1_base.js    # 基础工具函数、Logger、崩溃处理、进程信息
+│   └── code/
-├── th_2_core.js    # 核心逻辑、浮窗管理、Shell 桥接、ContentProvider
+│       ├── th_1_base.js
-├── th_3_panels.js  # 面板配置、按钮定义、对话框、文本查看器
+│       ├── th_2_core.js
-├── th_4_extra.js   # 额外面板（设备信息、快捷操作等）
+│       ├── th_3_panels.js
-└── th_5_entry.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 数据根目录下执行：
-ShortX数据根目录/
+```bash
-└── ToolHub/
+mkdir -p ToolHub/code
-    └── 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 任务中
+子模块会自动从 git 仓库下载到 `ToolHub/code/`，无需手动复制。
-- 将 `code/` 目录下的 5 个 `th_*.js` 文件放入 `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 字节，检测 `<!DOCTYPE` 或 `<html`，防止下到 404/502 错误页面
+
+---
+
+## 日志系统
+
+### 启动日志
+路径：`shortx.getShortXDir() + "/ToolHub/logs/init.log"`
+
+记录内容：
+- 目录创建/权限修复
+- 模块下载开始/结束/异常
+- 版本不匹配
+- 模块加载失败
+- 模块体积超阈警告（>200KB）
+
+### 运行日志
+路径：`shortx.getShortXDir() + "/ToolHub/logs/"`
+
+日志文件按天分割，默认保留 3 天。
+
+---
+
 ## 关闭浮窗
 
 通过 adb 或 ShortX Shell 执行：
-
 ```bash
 am broadcast -a shortx.wm.floatball.CLOSE
 ```
 
 ---
 
-## 日志位置
+## 模块说明
 
-```
+| 文件 | 职责 | 线数参考 |
-ShortX数据根目录/ToolHub/logs/
+|------|------|---------|
-```
+| `th_1_base.js` | 基础工具函数、Logger、崩溃处理、进程信息获取 | ~1300 |
-
+| `th_2_core.js` | 浮窗管理器、Shell 执行器、ContentProvider 读取器、图标缓存 | ~4700 |
-日志文件按天分割，默认保留 3 天。
+| `th_3_panels.js` | 面板配置工厂、按钮构建器、对话框、文本查看器 | ~2900 |
+| `th_4_extra.js` | 额外面板：设备信息、网络状态、快捷操作 | ~1600 |
+| `th_5_entry.js` | 入口面板定义、广播接收器注册、启动流程 | ~300 |
 
 ---
 
-## 模块说明
+## 模块加载容错
 
-| 文件 | 职责 |
+- `for` 循环加载 5 个模块，单模块失败记录日志但不阻断后续加载
-|------|------|
+- `th_5_entry.js` 失败时直接抛异常（启动必备）
-| `th_1_base.js` | 工具函数、Logger、崩溃处理、进程信息获取 |
+- 错误信息落盘到 `ToolHub/logs/init.log`，便于实机排查
-| `th_2_core.js` | 浮窗管理器、Shell 执行器、ContentProvider 读取器 |
-| `th_3_panels.js` | 面板配置工厂、按钮构建器、对话框、文本查看器 |
-| `th_4_extra.js` | 额外面板：设备信息、网络状态、快捷操作 |
-| `th_5_entry.js` | 入口面板定义、广播接收器注册、启动流程 |
 
 ---
 
@@ -90,3 +156,4 @@ ShortX数据根目录/ToolHub/logs/
 - 入口文件通过 `loadScript()` 动态加载子模块，`var` 声明通过间接 `eval` 挂到全局作用域
 - 子模块加载顺序不可更改：base → core → panels → extra → entry
 - 调试请查看日志文件，不通过返回 JSON 暴露内部细节
+- 单个模块建议不超过 200KB，超过时启动日志会记录 WARN 提示拆分

ToolHub.js

@@ -1,13 +1,177 @@
 // ToolHub - 入口文件 (加载子模块并执行)
 // 将本文件放入 ShortX 任务，th_*.js 放入 ShortX 数据根目录/ToolHub/code/ 文件夹
 
+var MODULE_MANIFEST = {
+    "th_1_base.js": "1.0.0",
+    "th_2_core.js": "1.0.0",
+    "th_3_panels.js": "1.0.0",
+    "th_4_extra.js": "1.0.0",
+    "th_5_entry.js": "1.0.0"
+};
+
+var GIT_BASE = "https://git.xin-blog.com/chenziran/ShortX_ToolHub/raw/branch/main/code/";
+var __dirChecked = false;
+
+function getLogPath() {
+    return shortx.getShortXDir() + "/ToolHub/logs/init.log";
+}
+
+function writeLog(msg) {
+    try {
+        var f = new java.io.File(getLogPath());
+        var dir = f.getParentFile();
+        if (dir && !dir.exists()) {
+            dir.mkdirs();
+        }
+        var sdf = new java.text.SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
+        var ts = sdf.format(new java.util.Date());
+        var writer = new java.io.FileWriter(f, true);
+        writer.write("[" + ts + "] " + String(msg) + "\n");
+        writer.close();
+    } catch (e) {}
+}
+
+function runShell(cmdArr) {
+    try {
+        var proc = java.lang.Runtime.getRuntime().exec(cmdArr);
+        proc.waitFor();
+        return proc.exitValue() === 0;
+    } catch (e) {
+        return false;
+    }
+}
+
+function checkDirPerms(path) {
+    try {
+        var proc = java.lang.Runtime.getRuntime().exec(["stat", "-c", "%u %g %a", path]);
+        proc.waitFor();
+        var reader = new java.io.BufferedReader(new java.io.InputStreamReader(proc.getInputStream()));
+        var line = reader.readLine();
+        reader.close();
+        if (line) {
+            var parts = String(line).trim().split(/\s+/);
+            if (parts.length >= 3) {
+                var uid = String(parts[0]);
+                var gid = String(parts[1]);
+                var mode = String(parts[2]);
+                return uid === "1000" && gid === "1000" && mode === "700";
+            }
+        }
+    } catch (e) {}
+    return false;
+}
+
+function setDirPerms(path) {
+    runShell(["chmod", "700", path]);
+    runShell(["chown", "1000:1000", path]);
+}
+
+function downloadFile(urlStr, destFile) {
+    var url = new java.net.URL(urlStr);
+    var conn = url.openConnection();
+    conn.setConnectTimeout(10000);
+    conn.setReadTimeout(30000);
+    conn.setRequestProperty("User-Agent", "ShortX-ToolHub/1.0");
+    var code = conn.getResponseCode();
+    if (code !== 200) {
+        throw "HTTP " + code;
+    }
+    var expectedLen = conn.getContentLength();
+    var inStream = conn.getInputStream();
+    var outStream = new java.io.FileOutputStream(destFile);
+    var buf = java.lang.reflect.Array.newInstance(java.lang.Byte.TYPE, 8192);
+    var n;
+    var total = 0;
+    while ((n = inStream.read(buf)) !== -1) {
+        outStream.write(buf, 0, n);
+        total += n;
+    }
+    outStream.close();
+    inStream.close();
+    if (expectedLen > 0 && total !== expectedLen) {
+        throw "Size mismatch: expected=" + expectedLen + ", got=" + total;
+    }
+    var checkStream = new java.io.FileInputStream(destFile);
+    var checkBuf = java.lang.reflect.Array.newInstance(java.lang.Byte.TYPE, 200);
+    var checkRead = checkStream.read(checkBuf);
+    checkStream.close();
+    if (checkRead > 0) {
+        var prefix = new java.lang.String(checkBuf, 0, checkRead, "UTF-8");
+        if (prefix.indexOf("<!DOCTYPE") >= 0 || prefix.indexOf("<html") >= 0) {
+            throw "Downloaded content is HTML, not JS";
+        }
+    }
+    return total;
+}
+
+function getFileVersion(filePath) {
+    try {
+        var f = new java.io.File(filePath);
+        if (!f.exists()) return null;
+        var r = new java.io.BufferedReader(new java.io.InputStreamReader(new java.io.FileInputStream(f), "UTF-8"));
+        var line = r.readLine();
+        r.close();
+        if (line) {
+            var lineStr = String(line);
+            var idx = lineStr.indexOf("@version");
+            if (idx >= 0) {
+                var rest = lineStr.substring(idx + 8).trim();
+                var spaceIdx = rest.indexOf(" ");
+                var ver = spaceIdx >= 0 ? rest.substring(0, spaceIdx) : rest;
+                return ver;
+            }
+        }
+    } catch (e) {}
+    return null;
+}
+
 function loadScript(relPath) {
     try {
         var base = shortx.getShortXDir();
-        var f = new java.io.File(base + "/ToolHub/code/" + relPath);
+        var dir = new java.io.File(base + "/ToolHub/code/");
-        if (!f.exists()) {
+
-            throw "Not found: " + f.getAbsolutePath();
+        if (!__dirChecked) {
+            if (!dir.exists()) {
+                dir.mkdirs();
+                setDirPerms(dir.getAbsolutePath());
+                writeLog("Created dir: " + dir.getAbsolutePath());
+            } else if (!checkDirPerms(dir.getAbsolutePath())) {
+                setDirPerms(dir.getAbsolutePath());
+                writeLog("Fixed dir perms: " + dir.getAbsolutePath());
+            }
+            __dirChecked = true;
         }
+
+        if (!dir.canWrite()) {
+            throw "Dir not writable: " + dir.getAbsolutePath();
+        }
+
+        var f = new java.io.File(dir, relPath);
+        var expectedVer = MODULE_MANIFEST[relPath];
+        var localVer = getFileVersion(f.getAbsolutePath());
+        var needsDownload = !f.exists();
+
+        if (!needsDownload && expectedVer && localVer !== null && localVer !== expectedVer) {
+            needsDownload = true;
+            writeLog("Version mismatch for " + relPath + ": local=" + localVer + ", expected=" + expectedVer);
+        }
+
+        if (needsDownload) {
+            try {
+                var urlStr = GIT_BASE + relPath;
+                writeLog("Downloading " + relPath + " from " + urlStr);
+                var size = downloadFile(urlStr, f);
+                writeLog("Downloaded " + relPath + " (" + size + " bytes)");
+            } catch (dlErr) {
+                throw "Not found: " + f.getAbsolutePath() + ", download failed: " + dlErr;
+            }
+        }
+
+        var fileSize = f.length();
+        if (fileSize > 200 * 1024) {
+            writeLog("WARN: " + relPath + " is " + (fileSize / 1024) + "KB, consider splitting");
+        }
+
         var r = new java.io.BufferedReader(new java.io.InputStreamReader(
             new java.io.FileInputStream(f), "UTF-8"));
         var sb = new java.lang.StringBuilder();
@@ -23,11 +187,19 @@ function loadScript(relPath) {
     }
 }
 
-loadScript("th_1_base.js");
+var modules = ["th_1_base.js", "th_2_core.js", "th_3_panels.js", "th_4_extra.js", "th_5_entry.js"];
-loadScript("th_2_core.js");
+var loadErrors = [];
-loadScript("th_3_panels.js");
+for (var i = 0; i < modules.length; i++) {
-loadScript("th_4_extra.js");
+    try {
-loadScript("th_5_entry.js");
+        loadScript(modules[i]);
+    } catch (e) {
+        writeLog("Module load failed: " + modules[i] + " -> " + String(e));
+        loadErrors.push({ module: modules[i], err: String(e) });
+        if (modules[i] === "th_5_entry.js") {
+            throw "Critical module failed: " + modules[i];
+        }
+    }
+}
 
 var __out = (function() {
   var entryInfo = getProcessInfo("entry");

code/th_1_base.js

@@ -1,3 +1,4 @@
+// @version 1.0.0
 // ToolHub - Android 悬浮球工具 (ShortX / Rhino ES5)
 // 来源: 阿然 (xin-blog.com)
 //

code/th_2_core.js

@@ -1,3 +1,4 @@
+// @version 1.0.0
 function FloatBallAppWM(logger) {
   this.L = logger || null;
 

code/th_3_panels.js

@@ -1,3 +1,4 @@
+// @version 1.0.0
 FloatBallAppWM.prototype.buildSettingsPanelView = function() {
   this.beginEditConfig();
 

code/th_4_extra.js

@@ -1,3 +1,4 @@
+// @version 1.0.0
 FloatBallAppWM.prototype.buildViewerPanelView = function(titleText, bodyText) {
   var self = this;
   var isDark = this.isDarkTheme();

code/th_5_entry.js

@@ -1,3 +1,4 @@
+// @version 1.0.0
 function runOnMainSync(fn, timeoutMs) {
   if (!fn) return { ok: false, error: "empty-fn" };
   try {