# ShortX ToolHub

一个模块化的 ShortX JS 浮窗工具框架，支持广播关闭、子线程模型、日志记录、自动下载与热更新。

---

## 目录结构

### 实机（ShortX 数据目录）
```
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. 创建目录（可省略）

入口文件会自动检测并创建 `ToolHub/code/` 目录，无需手动操作。

若需手动创建，在 ShortX 数据根目录下执行：
```bash
mkdir -p ToolHub/code
chmod 700 ToolHub/code
chown 1000:1000 ToolHub/code
```

### 2. 放置入口文件

将 `ToolHub.js` 的内容粘贴到 ShortX 任务中。

子模块会自动从 git 仓库下载到 `ToolHub/code/`，无需手动复制。

### 3. 运行

执行 ShortX 任务，正常返回示例：
```json
{
  "ok": true,
  "started": true,
  "msg": "已按 WM 专属 HandlerThread 模型启动",
  "closeAction": "shortx.wm.floatball.CLOSE",
  "layout": {"cols": 2, "rows": 2}
}
```

---

## 自动下载与权限管理

入口文件启动时会自动完成以下操作：

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
```

---

## 模块说明

| 文件 | 职责 | 线数参考 |
|------|------|---------|
| `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 |

---

## 模块加载容错

- `for` 循环加载 5 个模块，单模块失败记录日志但不阻断后续加载
- `th_5_entry.js` 失败时直接抛异常（启动必备）
- 错误信息落盘到 `ToolHub/logs/init.log`，便于实机排查

---

## 注意事项

- 入口文件通过 `loadScript()` 动态加载子模块，`var` 声明通过间接 `eval` 挂到全局作用域
- 子模块加载顺序不可更改：base → core → panels → extra → entry
- 调试请查看日志文件，不通过返回 JSON 暴露内部细节
- 单个模块建议不超过 200KB，超过时启动日志会记录 WARN 提示拆分