Serial Hub — AI skill for Claude Code

serial-hub

让 **任何 AI**（workbuddy、VS Code 里的 Cline、Claude Desktop、Cursor、DSH……）都能和人类工程师**共用同一条串口**，自主地看输出、发命令、交互式调试嵌入式开发板上的 Linux。

                 ┌──────────────────────────────────┐
  人(浏览器)────▶│   serial-hub 守护进程（常驻）       │◀── MCP ──▶ VS Code 的 AI (Cline)
  Web 控制台      │   唯一持有并独占串口的那一个对象      │
                 │   hub: 环形缓冲 + seq + 游标        │◀── MCP ──▶ workbuddy 的 AI
  MobaXterm ────▶│   控制 IPC（本地 TCP，换行 JSON）     │
  (TCP 桥,可选)   └──────────────────────────────────┘
                        ▲
                        └── CLI (serialctl) ── 任何"只能跑 shell"的 AI

它解决什么

嵌入式工程师调板子时，人盯串口终端、AI 想帮忙却"看不见也摸不着"。serial-hub 把串口提升成一个**常驻服务**：人用 Web 控制台（xterm 终端），AI 通过 MCP 或 CLI 工具接入，**双方共享同一个 SerialHub、同一条物理连接**——AI 看到的 == 人看到的，AI 发的 == 人看到的，`serial_expect_send` 还能让 AI 在正确的毫秒发出命令（抢 U-Boot 倒计时、登录密码）。

核心设计

• 单一真源：所有数据（设备输出、AI 发的、人敲的）进同一个按 seq 严格递增的环形缓冲。任何客户端读到的都是同一份真相。
• 独占而不互斥：串口只被守护进程打开一次；人和多个 AI 都是它的客户端，彼此不抢端口。
• 读取游标：每个会话/每个 CLI consumer 有独立游标，read 默认是"给我还没看过的部分"。
• 原子 expect→send：serial_expect_send 在命中正则的同一 tick 内发字节，解决交互式提示的秒级竞态。
• 上下文卫生：read/wait 有硬上限并显式报截断，绝不把整段 dmesg 灌进模型上下文。

安装

cd serial-hub
npm install        # serialport(N-API 预编译) + ws + @xterm/xterm + MCP SDK + zod

`serialport` 有原生依赖；若在非 Electron 的普通 Node 下加载失败，先用内置 `VIRTUAL` 虚拟端口验证整条链路（见下）。

快速开始（无硬件自测）

# 1) 前台起守护进程（会打印 Web 控制台地址）
node bin/serial-hub.js
#    → 人类 Web 控制台：http://127.0.0.1:48080/serial/
#    → 控制 IPC：127.0.0.1:48555

# 2) 用 CLI 走一遍（虚拟板）
serialctl ports                 # 应看到 VIRTUAL 虚拟演示板
serialctl open VIRTUAL
serialctl wait "U-Boot" --timeout 5000
serialctl read
serialctl close

人类打开 `http://127.0.0.1:48080/serial/` 就能看到 xterm 终端，和 CLI/AI 共用同一个口。

三种接入方式

方式	适合谁	说明
MCP Server（推荐）	workbuddy、Cline 等支持 MCP 的 AI	一次配置，工具即插即用
CLI (serialctl)	只能执行 shell 命令的 AI	零集成，直接跑命令
人类 Web 控制台	你	xterm 终端，随时看/敲

---

接入 A：MCP Server（workbuddy / Cline / Claude Desktop