# lua-debug-electron

**Repository Path**: michaelhyg/lua-debug-electron

## Basic Information

- **Project Name**: lua-debug-electron
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-29
- **Last Updated**: 2026-06-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Lua 调试助手

基于 Electron + React + Monaco 的 ESP32 Lua 调试工作台，用来连接设备串口、管理设备脚本、编辑 Lua 代码、保存到 Flash、执行/停止脚本，并查看串口日志和设备状态。

## 当前能力

- Electron 桌面工作台，Renderer 保持 `contextIsolation: true`、`nodeIntegration: false`
- Monaco Lua 多标签编辑器，支持新建、打开本地文件、保存、dirty 标记、关闭标签
- 真实串口接入，支持串口枚举、连接、断开、状态同步、发送数据
- 设备协议层，支持文件列表、读取脚本、写入 Flash、执行脚本、停止脚本、内存信息、模块列表、OTA 固件升级
- 左侧活动栏，支持资源管理器和搜索面板切换
- 设备资源树，显示设备 Lua 文件和设备模块
- 模块函数浏览，函数目录来自 `src/data/luaModuleFunctions.json`
- 右侧设备摘要，显示连接状态、当前脚本、LittleFS、Lua 内存、模块数量和 OTA 状态
- 底部日志栏，包含串口日志、操作日志、问题、调试输出，支持过滤、清空、自动滚动
- 工作台布局记忆，左侧、右侧、底部显示状态和尺寸会在下次启动恢复
- 串口设置记忆，启动后会尝试使用上次保存的串口配置自动连接并刷新资源
- Mock Device 模式，方便没有 ESP32 设备时验证 UI 和基础流程

## 最近更新

- 工作台 UI 从单体 `App.tsx` 拆分为 `components/`、`hooks/`、`utils/` 和 `settings/`，主入口只负责组装页面
- 新增工作台控制层 Hook，串口、设备资源、脚本动作、布局拖拽等逻辑开始从 UI 组件中拆出
- 新增 `eslint.config.mjs`，为后续 TypeScript/React 代码整理提供统一检查入口
- 资源管理器底部动作补齐：支持新建 Lua、刷新设备资源、批量上传 Lua、删除当前脚本
- 资源管理器脚本树支持右键菜单：打开、重命名、删除
- 资源管理器脚本树支持 `Cmd/Ctrl` 多选、`Shift` 范围选择，并可批量删除选中的 Lua 脚本
- 设备脚本重命名流程打通：读取旧脚本、写入新文件名、删除旧文件、刷新资源树
- 编辑器标签支持右键菜单：关闭右侧、关闭其他、关闭所有
- 编辑器标签栏右侧 `+` 按钮可直接新建空白 Lua 标签
- 日志栏支持独立字体设置，工具栏和菜单栏都可打开日志字体配置
- 日志栏工具区样式收紧：自动滚动和追加 `CRLF` 保持单行显示，复选框和控件尺寸更协调
- 新增右侧“升级”页：选择 `.bin` 固件、查看 OTA 状态、上传固件、上传进度和重启到新固件
- 新增 macOS `.app` 本地打包脚本，生产包使用相对资源路径并优先加载内置 `dist/index.html`

## 运行

安装依赖：

```bash
npm install
```

连接真实设备运行：

```bash
npm run dev
```

无设备 Mock 模式运行：

```bash
npm run dev:mock
```

构建前端：

```bash
npm run build
```

构建并安装 macOS 应用到当前用户 Applications 目录：

```bash
npm run build
scripts/package-macos-app.zsh /Users/michael/Applications/Lua调试助手.app
```

打包脚本会基于 `node_modules/electron/dist/Electron.app` 生成应用包，并拷贝 `dist/`、`electron/`、`package.json` 和 `node_modules/` 到 `Contents/Resources/app`。如果目标路径已有同名 app，脚本会先生成临时包，再替换目标包。

## 界面入口

顶部主工具栏保留高频设备动作：

- 执行
- 停止
- 保存到 Flash
- 串口设置
- 连接 / 断开

菜单栏按功能分组：

- 文件：新建、打开、保存、保存到 Flash、执行、停止、退出
- 设备：刷新资源、串口设置、连接 / 断开
- 视图：显示/隐藏资源管理器、显示/隐藏右侧摘要、显示/隐藏底部日志、恢复默认布局、编辑器字体、日志字体
- 帮助：关于

## 典型流程

1. 启动软件后自动尝试连接上次保存的串口。
2. 连接成功后自动刷新设备资源。
3. 左侧资源管理器点击 `/lua/*.lua` 文件，读取设备脚本并打开到 Monaco。
4. 修改脚本后标签会显示 `*`。
5. 点击“保存到 Flash”写入设备。
6. 点击“执行”运行当前脚本，点击“停止”停止设备脚本。
7. 底部“串口日志”查看设备 `print` 输出，也可以直接发送串口文本。

## OTA 固件升级

右侧摘要面板新增“升级”页，用于通过设备协议上传固件：

1. 连接设备后点击“选择固件”，选择 `.bin` 文件。
2. 点击“刷新状态”读取当前 OTA 状态、运行分区、启动分区、目标分区和 CRC32。
3. 点击“开始 OTA”后，主进程读取固件、计算 CRC32，并按分片发送 `OTA_BEGIN`、`OTA_WRITE`、`OTA_END`。
4. 上传过程中 Renderer 会接收 `device:ota-progress` 事件并显示进度。
5. 设备进入 `ready_to_reboot` 且 `pendingReboot` 为 true 后，可以点击“重启到新固件”发送 `OTA_REBOOT`。

Mock Device 模式下也会返回模拟 OTA 状态，方便验证 UI 流程。

## 串口与设备协议

串口由 Electron Main Process 中的 `electron/serial-manager.cjs` 统一管理，Renderer 不直接访问 `serialport`。

设备控制协议由 `electron/device-protocol.cjs` 负责。当前协议跟随 Qt 上位机使用二进制帧：

- 帧头：`0xAA 0x55`
- Header：`payload length + command + sequence`
- Payload：命令数据
- CRC：CRC16-CCITT
- 命令：`LIST`、`LOAD_SCRIPT`、`STORE`、`EXEC`、`RESET`、`FS_INFO`、`MODULE_LIST`、`OTA_BEGIN`、`OTA_WRITE`、`OTA_END`、`OTA_ABORT`、`OTA_STATUS`、`OTA_REBOOT` 等

协议帧和普通串口文本分流：

- 协议响应用于完成 `device.*` 命令 Promise
- 普通串口文本进入底部“串口日志”
- 协议错误进入“问题”日志

## Renderer 安全 API

`electron/preload.cjs` 通过 `contextBridge` 暴露安全 API：

```ts
window.localFile.open()
window.localFile.openMany()
window.localFile.save(path, content)
window.localFile.saveAs(suggestedName, content)
window.localFile.openFirmware()

window.device.listPorts()
window.device.connect(options)
window.device.disconnect()
window.device.getStatus()
window.device.listFiles(path)
window.device.listModules()
window.device.readFile(path)
window.device.writeFile(path, content)
window.device.deleteFile(path)
window.device.runScript(path, content)
window.device.stopScript()
window.device.getMemInfo()
window.device.otaStatus()
window.device.otaUpload({ filePath, version, chunkSize })
window.device.otaAbort()
window.device.otaReboot()
window.device.onOtaProgress(callback)
window.device.onEvent(callback)
window.device.onError(callback)

window.serial.write(data)
window.serial.onData(callback)
window.serial.onStatus(callback)
window.serial.onError(callback)
```

不要在 Renderer 中直接 `require("fs")`、`require("serialport")` 或暴露完整 `ipcRenderer`。

## 目录结构

```text
electron/
  main.cjs              Electron 主进程、菜单、IPC、窗口管理
  preload.cjs           安全桥接 API
  serial-manager.cjs    串口枚举、连接、读写、状态事件
  device-protocol.cjs   ESP32 Lua 设备协议层和 OTA 上传

src/
  App.tsx               工作台 UI 和业务动作编排
  hooks/                工作台控制 Hook，包括 OTA 控制器
  store/                useReducer 状态管理
  types/                设备、文件、日志、编辑器、Electron API 类型
  mock/                 初始空状态和 Mock 数据
  data/                 Lua 模块函数索引 JSON
  styles.css            工作台布局和组件样式

docs/
  qt-plan-short.md      Qt 上位机规划精简版
  qt-todo-short.md      后续 Todo 精简版
```

## Mock Device

`npm run dev:mock` 会设置 `MOCK_DEVICE=1`，设备相关接口返回本地 mock 数据：

- `device.listFiles`
- `device.listModules`
- `device.readFile`
- `device.writeFile`
- `device.runScript`
- `device.stopScript`
- `device.getMemInfo`
- `device.otaStatus`
- `device.otaUpload`
- `device.otaAbort`
- `device.otaReboot`

这个模式适合没有硬件时验证编辑器、资源树、保存、执行、日志和布局逻辑。

## 后续计划

精简版路线图见 [docs/qt-plan-short.md](docs/qt-plan-short.md)。
执行清单见 [docs/qt-todo-short.md](docs/qt-todo-short.md)。