BeConsole

BeConsole 是运行在 PC 上的 Node.js 桥接工具，通过串口连接 ESP32 设备，提供交互式终端和 WebSocket 服务。

下文中的「设备」均指搭载 beshell 固件的 ESP32 系列芯片设备（如 ESP32-C3、ESP32-S3 等）。beshell 是 ESP32 的 JS 开发框架，它让开发者用 JavaScript 编写固件逻辑，通过文件系统、GPIO、网络等模块控制硬件。BeConsole 正是 beshell 开发流程中的 PC 端调试工具。

你可以：

• 在终端里手动调试：连接设备、执行本地命令、设备端 shell 命令、设备端 JS 代码
• 配合编辑器高效开发：编写 JS 源文件 → sync 自动同步到设备 → 即时测试
• 对接 AI 工具智能协作：通过 WebSocket 让 Claude/MCP 参与调试和迭代

你 (终端 / AI / 编辑器) ──┬── CLI REPL ────> BeConsole ──serial──> ESP32 (beshell)
                          │                      
                          └── WebSocket ────> ws://localhost:14518

使用场景

场景一：终端手动调试（核心用法）

在终端里交互式地连接设备、执行命令和 JS 代码，适合日常调试和探索：

> open                        # 扫描串口
可用串口:
  #0: COM31 — USB-SERIAL CH340

> open COM31                   # 打开设备
正在打开 COM31... 已打开 COM31!

> ls                          # 设备端命令
main.js  xxx.txt  lib/

> cat /main.js                # 查看设备上的文件
console.log("boot ok")
...

> 1+2                         # 设备端 JS 表达式
3

> fs.readdirSync("/")         # 返回数组（自动序列化）
["main.js", "xxx.txt", "lib"]

> console.log("hello")        # OUTPUT 通道异步输出
hello

> fs.statSync("/main.js").size
1234

所有不是本地命令的输入都会转发到设备引擎执行。复合类型（数组、对象）自动序列化/反序列化，无需手动 JSON.stringify。

场景二：写代码 + 自动同步

在编辑器中写 JS 源文件，sync 命令监视本地目录，文件保存后自动同步到设备：

# 启动 BeConsole，连接设备，监视 ./src 目录
beconsole --open COM31 --sync ./src

开始监视目录: d:\project\my-esp32\src
File src\led.js has been changed
sync led.js [====================] 100% | 2048/2048 | 1.2 KB/s
sync file /led.js  done!

你在编辑器中保存文件，设备上即时生效。可以用 console.log 打出启动日志确认模块加载正常。

场景三：对接 AI（MCP/Claude Code）

AI 通过 WebSocket 连接 BeConsole，自动完成"写代码 → 上传 → 测试 → 迭代"的开发循环。先运行 beconsole install-skill 安装 skill，之后在 Claude Code 中使用 beconsole-local-js skill，AI 即可自主操作设备。详见 ai-skill/beconsole-local-js/skill.md。

安装

环境要求

• Node.js >= 14
• Windows / macOS / Linux
• ESP32 设备（beshell 固件）

安装 BeConsole

# npm（推荐）
npm install -g beconsole.js

# 或者用 pnpm
pnpm add -g beconsole.js

安装后在任意目录都可以使用 beconsole 命令。

安装 AI Skill

将内置的 AI 开发 skill 安装到 Claude Code 全局 skills 目录，安装后 AI 即可自主操作设备：

beconsole install-skill

安装后，在任意项目的 Claude Code 中都可以使用 beconsole-local-js skill。详见 ai-skill/beconsole-local-js/skill.md。

从源码安装（本地开发）

git clone <repo-url>
cd beconsole.js
npm install
node beconsole.js install        # 注册全局命令
node beconsole.js install-skill   # 安装 AI skill

命令参考

本地命令

在 BeConsole 端执行，不发送到设备：

| 命令 | 别名 | 说明 | |------|------|------| | open | o, connect | 扫描并列出可用串口；open COM31 打开指定串口；open 0 / open #0 按序号打开 | | close | c, disconnect | 断开设备连接 | | upload <本地> [远端] | up | 上传本地文件到设备 | | download <远端> [本地] | down, dl | 从设备下载文件 | | edit <设备文件> | e | 下载→本地编辑器编辑→保存自动上传 | | sync [目录] | — | 监视目录变化，自动同步到设备 | | clear | clean, cls | 清空终端屏幕 | | help | h, ? | 显示本地命令 + 设备端命令 | | quit | q, exit | 退出 BeConsole |

设备端命令（取决于BeShell固件版本）

注意：设备端命令由 beshell 固件提供，实际可用命令取决于设备固件的版本和定制情况。以下列表仅作为常见参考，请以设备实际 help 输出为准。

| 命令 | 说明 | |------|------| | ls | 列出当前目录文件 | | cat <path> | 查看文件内容 | | cp <src> <dst> | 复制文件 | | mv <src> <dst> | 移动 / 重命名 | | rm <path> | 删除文件 | | mkdir <path> | 创建目录 | | pwd | 显示当前目录 | | reboot / run | 重启设备 |

设备端 JS

所有非本地命令的输入都会作为 JS 表达式在设备引擎上执行并返回结果。例如 1+2、fs.readdirSync("/")、typeof someFunc 等。

注意：设备端 JS API（如 fs.*）同样取决于固件版本。如果某个 API 返回 undefined，可能是该固件版本未实现。

启动参数

| 参数 | 说明 | |------|------| | --open [端口] | 启动后自动打开设备。例如 --open COM31。不带参数时打开第一个串口 | | --sync [目录] | 启动后监视目录，文件变化时自动同步到设备 | | --port <端口> | WebSocket 服务端口（默认 14518） |

常用组合：

# 纯手动：启动后自行 open
beconsole

# 立即开始调试：打开设备 + 监视 src 目录
beconsole --open COM31 --sync ./src

# 换个端口（同时给多个设备用）
beconsole --port 14519 --open COM32

特殊参数（执行后退出）：

| 参数 | 说明 | |------|------| | install | 安装为全局命令，创建 beconsole.cmd 到 npm bin 目录 | | install-skill | 安装 AI skill 到 Claude Code 全局 skills 目录 |

文件传输

所有文件传输操作（edit、upload、download、sync）共用统一的进度条，实时显示百分比、字节数和传输速率。

edit — 设备文件即时编辑

edit 是最快捷的设备文件编辑方式，将"下载→本地编辑→上传"三步合并为一条命令（默认使用 VSCode 编辑） ：

> edit /main.js
下载 [====================] 100% | 1234/1234 | 12.1 KB/s
编辑器: code C:\Users\...\Temp\beconsole\main.js

VS Code 随即打开该文件的临时副本。此后：

• Ctrl+S 保存 → 自动上传到设备，显示同步进度条
• 关闭标签页 → 停止监视，删除临时文件

同步 [====================] 100% | 1300/1300 | 1.5 KB/s
已同步: /main.js (1300 bytes)
编辑器已关闭，临时文件已删除。

工作流程：

edit /main.js
  │
  ├─ ① 下载设备文件 → OS 临时目录（系统重启时自动清理）
  ├─ ② 启动编辑器（默认 VS Code，可通过 EDITOR 环境变量定制）
  ├─ ③ 你编辑文件，每次 Ctrl+S 自动上传
  └─ ④ 关闭标签页 → 清理临时文件

提示：编辑器使用 --wait 模式打开，BeConsole 会等待你关闭标签页后才恢复提示符。如需后台编辑，可以另开一个终端窗口。

upload / download — 文件上传下载

# 上传本地文件到设备
> upload ./lib/led.js /lib/led.js
上传 [====================] 100% | 2048/2048 | 1.5 KB/s
上传完成: d:\project\lib\led.js → /lib/led.js

# 省略目标路径则使用源文件名
> upload ./config.json /
上传 [====================] 100% | 512/512 | 2.0 KB/s
上传完成: d:\project\config.json → /config.json

# 下载设备文件到本地
> download /main.js ./backup-main.js
下载 [====================] 100% | 1234/1234 | 12.1 KB/s
下载完成: d:\project\backup-main.js

sync — 目录自动同步

监视本地目录，文件保存后自动同步到设备：

> sync ./src
开始监视目录: d:\project\my-esp32\src
File src\led.js has been changed
sync led.js [====================] 100% | 2048/2048 | 1.2 KB/s
sync file /led.js  done!

WebSocket API

BeConsole 启动后在 ws://localhost:14518 开启 WebSocket 服务。主要用于 AI/MCP 对接。