SerialHub

English | 简体中文

串口（MCU）与网络连接（Web 终端 / AI）之间的双向桥接器：把 MCU 串口同时桥接给人和 AI，单个 Go 二进制（前端内嵌），支持 Windows（系统托盘）/ Linux / macOS。

📚 文档：快速开始 | MCP 使用指南 | 配置与架构 | 发布流程 | 集成测试

项目简介

• 人：浏览器里的 xterm.js Web 终端，实时查看与输入（启动后自动打开浏览器，WSL 下也能弹出 Windows 宿主浏览器）
• AI：原生 MCP 服务器（Streamable HTTP + stdio），提供 8 个工具（serial_list / serial_connect / serial_write / serial_read / serial_clear / serial_disconnect / serial_status / serial_script）
• 双通道共享同一串口连接与数据缓冲，人和 AI 看到的是同一串字节
• 所有参数均可通过 TOML 或命令行配置，数据流可按需记录（--log-data）

系统架构

flowchart TB
    MCU["MCU"] <-->|"串口 (COM9, 115200, 8N1)"| Serial["串口管理器<br/>Serial Manager"]

    subgraph SerialHub["SerialHub（单二进制）"]
        Serial <-->|"事件总线"| Bridge["数据桥接<br/>DataBridge"]
        Bridge <-->|"读写"| Buffer["DataBuffer<br/>共享缓冲"]
        Bridge <-->|"WebSocket (端口 5050)"| Web["Web 终端<br/>xterm.js"]
        Bridge <-->|"JSON-RPC (HTTP)"| MCP["MCP 服务<br/>8 个工具"]
    end

    Web <-->|"WebSocket"| Browser["浏览器<br/>人工操作"]
    MCP <-->|"MCP 协议"| AI["AI 工具<br/>OpenCode / VS Code 等"]

安装

一键安装（自动查最新版、下载并校验；可用 SERIALHUB_GITHUB_API 指定加速基址）：

# Linux（装到 ~/.local/bin）
curl -fsSL https://raw.githubusercontent.com/dongly/serialhub/main/install.sh | bash

# Windows：在 PowerShell 中运行（装到 %LOCALAPPDATA%\Programs\serialhub 并加入用户 PATH）
irm https://raw.githubusercontent.com/dongly/serialhub/main/install.ps1 | iex

• 手动下载、PATH 配置、安装验证、WSL USB 串口挂载等详细步骤见 QUICKSTART.md。
• 源码构建（macOS 唯一方式；需 Go 1.26+）：git clone https://github.com/dongly/serialhub && cd serialhub && go build -o serialhub ./cmd/serialhub
• 自升级与卸载：serialhub upgrade（下载校验并原子替换自身）/ serialhub uninstall（dry-run 列清单确认后清理 MCP 条目 / 配置 / 日志 / 二进制）；代理遵从 HTTPS_PROXY。

快速开始

场景：人工 + AI 同时调试

1. 启动 SerialHub：

serialhub -p COM9 --host 0.0.0.0 -D

Windows 推荐用安装目录下的启动脚本

.\sr.ps1 [参数]
# 如: 
.\sr.ps1 -p COM9 -D

• 启动前强制结束仍在运行的旧 serialhub 进程（重启免手工关旧实例）；
• 以最小化窗口启动（自动附加 --minimized），并打印 PID、日志路径（exe 同目录 logs\serialhub.log）与停止命令；
• 参数 -p / -b / -c / -D / -m 与直接运行 serialhub.exe 的同名参数一致（脚本 -listen 对应 exe 的 --host）；也可双击 sr.bat（转调 sr.ps1）。脚本命名为 sr 是为了不遮蔽 PATH 上的 serialhub.exe。

2. 人工通过 Web 终端监视：浏览器打开 http://localhost:5050/terminal。页面「退出」按钮可远程关闭 SerialHub（优雅停机；--host 0.0.0.0 暴露到局域网时，任何能打开该页的人均可关闭）。
3. AI 接入：运行 serialhub setup 一键写入 MCP 客户端配置（默认 stdio 本地模式，支持 OpenCode / Claude Code / Cursor / Windsurf / VS Code / Codex）；手动配置见 MCP.md。
4. 串口数据同时转发到 Web 终端和 AI 接口，两者可独立向串口发送命令。

命令与配置

全部选项见 serialhub --help 与 AGENTS.md 的 CLI 参数表。配置优先级 CLI 参数 > 配置文件 > 默认值；查找顺序、回写时机与日志目录见 AGENTS.md，完整示例见 config.example.toml。Windows 上默认启动系统托盘（右键菜单连接 / 断开 / 退出），详见 QUICKSTART.md。

开发

开发流程与常用命令见 AGENTS.md；在 WSL 中测试 Windows 版本（托盘、单实例锁、PowerShell 脚本）的方法与坑见 docs/wsl-windows-testing.md。

许可证 / License

本项目采用 Apache License 2.0（Copyright 2026 dongly）发布。