smolmux-gdb-mcp

smolmux

便携式 C11 设备多路复用器。保持设备连接（串行 UART、GDB stub），并通过 Unix 套接字，使用以换行符分隔的 JSON 在多个客户端之间复用访问权限。

单个静态二进制文件、低延迟、占用空间小——专为在 Linux 上进行日常串行和 GDB bring-up 而构建。

刚接触？ docs/START-HERE.md 是一份一屏式导航指南——找到你的目标（运行程序、借助 AI Agent bring-up 新开发板、了解架构、修改代码），它会为你指向合适的文档。

一个端口，三个客户端

一个代理持有 ESP32-S3 的 UART。监视器（顶部）实时监控它。底部窗格中的脚本发送 temp，并通过同一线路收到回复，重置开发板并等待提示符，随后 esptool 通过 with-port 读取闪存 ID：代理暂停，esptool 运行，代理恢复，而监视器始终不会失去端口。

示例：探测未知开发板

一个代理持有 SWD；smolmux-gdb-mcp 运行 probe_unknown_board。在 SAM C21 Xplained Pro 上，该流程从 CPUID 解码出 Cortex-M0+，通过 SAM DSU DID 识别芯片，排除错误匹配的 STM32，并写入初始版 *.gdb-profile.json。工具、寄存器值和配置文件结构： docs/demo-samc21-probe-transcript.md。

日常串行使用（多客户端、U-Boot 中断、烧录器交接）： docs/daily-driver.md。

功能

• 通过 vtable 多态支持 Serial UART、GDB MI 和 serial-over-TCP（telnet + RFC2217）设备链路
• 通过 Unix 套接字支持多个客户端并发连接，并提供基于角色的访问控制（观察者／控制者／接管者）
• Expect 引擎——对设备字节流进行并发正则表达式匹配，并支持超时
• 异常检测——基于模式检测崩溃／错误，支持冷却时间和事件跟踪
• 输出历史记录——带时间戳的环形缓冲区，供后加入的客户端回放
• 结构化日志——JSONL I/O 日志 + 便于阅读的文本日志，支持轮转 （I/O 日志记录所有发送到设备和从设备接收的内容，包括在登录提示处 输入的任何内容——该日志会以 0600 权限创建在你的私有 状态目录中；smolmux 拒绝通过符号链接写入，也拒绝写入 由其他用户拥有的文件）
• 网络 sink——通过 TCP 和 WebSocket 进行远程访问（默认绑定到环回地址）。 线路协议为明文，任何完成握手的客户端都能完全控制设备——包括控制台写入、引脚、BREAK、SysRq、GDB。 在环回地址上且未指定 --auth-token 时，代理会在 $XDG_RUNTIME_DIR（或 /tmp）中生成一个 0600 权限的文件来保存令牌，其他本地用户和进程因此无法连接；你自己的 smolmux-monitor / smolmux-mcp 会自动读取令牌，且 smolmux-cli token 会将其打印出来。远程使用时，请将 绑定地址保留为环回地址，并通过 SSH 隧道或 WireGuard 访问，而不要 暴露端口；如果 TCP 未绑定到环回地址且未指定 --auth-token，smolmux 会拒绝提供服务。 --insecure-no-auth 会关闭这两项保护。
• MCP 服务——独立的 smolmux-mcp / smolmux-gdb-mcp 可连接到正在运行的代理；也可选用进程内的 --mcp sink，通过单进程 stdio 工作
• 启动跟踪与自动应答器——有序的启动阶段、停滞事件，以及常驻的 expect->send 规则
• 自动启动中断——代理端的按键泛洪（以及可选的 DTR/RTS 复位），用于 bootdelay=0 的 U-Boot
• 设备配置文件／板级清单——用于配置提示符、异常和多线板卡的 JSON 配置
• 自动重连——USB 串口断开后通过指数退避进行恢复
• 构建时功能选择——基于 Kconfig；仅 UART 的构建不包含 GDB/TCP/WebSocket 代码

快速开始

先决条件：Linux、C11 编译器、CMake 3.21+、带有 kconfiglib 的 Python 3（配置步骤会 使用它生成功能头文件）。libpcre2-8 为可选项；未安装时， 正则表达式匹配会回退到 POSIX。

# Debian/Ubuntu
sudo apt install build-essential cmake python3 python3-pip libpcre2-dev
pip install kconfiglib   # or in a venv; Debian's system Python may need
                         # --break-system-packages

cmake -B build && cmake --build build -j$(nproc)
./build/smolmux /dev/ttyUSB0

连接客户端：

# Needs a running broker (above). Auto-discovers the socket from the port name.
./build/smolmux-monitor /dev/ttyUSB0

日常工作流（配置文件、日志、U-Boot 中断、多线板卡）： docs/daily-driver.md。意图路由器：docs/START-HERE.md。

构建

cmake -B build && cmake --build build -j$(nproc)   # Default (all features)
ctest --test-dir build                               # Run tests

功能配置方案

cp configs/defconfig.minimal .config && cmake -B build    # UART only, no sinks/watcher
cp configs/defconfig.uart .config && cmake -B build       # UART + MCP sink + watcher
cp configs/defconfig.embedded .config && cmake -B build   # Embedded target profile
cp configs/defconfig.full .config && cmake -B build       # Everything (GDB, TCP, WS, MCP, watcher)

也可以直接切换功能：

cmake -B build -DSM_ENABLE_GDB=OFF -DSM_ENABLE_SINK_WS=OFF

开发者基准测试（例如输出合并器测试工具）默认关闭：

cmake -B build -DSM_BUILD_BENCH=ON && cmake --build build --target bench_coalesce

交互式配置：

cmake --build build --target menuconfig

静态构建

cmake -B build -DSM_MUSL_STATIC=ON    # Fully static musl binary (zero runtime deps)
cmake -B build -DSM_STATIC=ON         # Static linking (except glibc)

用法

smolmux <port> [options]

Options:
  -b, --baud <rate>           Baud rate (default: 115200)
  -s, --socket <path>         Unix socket path
  -l, --log-dir <dir>         I/O log directory
                              (default: $XDG_STATE_HOME/smolmux or
                               ~/.local/state/smolmux)
  -t, --text-log-dir <dir>    Text log directory
  -p, --profile <path>        Device profile JSON file
  --board <name>              Group this wire under a board (for discovery)
  --role <label>              This wire's role on the board (console, swd, ...)
  --gdb                       Use GDB MI link instead of UART
  --gdb-path <path>           Path to gdb binary (default: gdb)
  --gdb-target <spec>         GDB target (e.g., localhost:3333)
  --serial-tcp <host:port>    Connect to a serial-over-TCP device server
                              (ser2net, socat, terminal server; telnet +
                              RFC2217 baud/DTR/RTS/break control)
  --mcp                       Enable in-process MCP stdio sink (prefer standalone
                              smolmux-mcp against a daemon broker for daily use)
  --tcp-port <port>           Enable TCP sink (default: 5555)
  --tcp-bind <addr>           TCP bind address (default: 127.0.0.1)
  --auth-token <token>        Require token in hello from TCP clients
                              (prefer env SMOLMUX_AUTH_TOKEN - hidden from ps)
  --auth-token-file <path>    Read the token from a file
  --insecure-no-auth          Serve TCP/WS with no token. Without it, a
                              loopback listener gets a generated token
                              (0600 file; smolmux-cli token prints it) and
                              a non-loopback --tcp-bind is refused.
  --ws-port <port>            Enable WebSocket sink (default: 5556)
  --no-text-log               Disable text log
  --no-io-log                 Disable JSONL I/O log
  --no-reconnect              Don't auto-reconnect on disconnect
  --wait-device <seconds>     Wait for the device path before open
  --gdb-allow-shell           Permit GDB shell/python/eval (off by default)
  --list-ports                List available serial ports and exit
  --list-profiles             List available device profiles and exit
  --help-protocol             Show wire protocol documentation
  -v, --verbose               Enable debug logging
  -V, --version               Show version
  -h, --help                  Show this help

线路协议

基于 Unix 套接字（以及 TCP/WS sink）的换行符分隔 JSON。二进制数据 采用 base64 编码。消息集涵盖会话控制、expect、历史记录、异常、 启动阶段、自动启动按键泛洪和自动应答器。

完整参考文档：./build/smolmux --help-protocol（始终与此二进制文件匹配）。

客户端 -> 代理： hello、send、send_expect、takeover、release、status、pin_control、set_baud、suspend、resume、history_request、incidents_request、configure_anomaly、interrupt_autoboot、configure_autoresponder、autoresponders_request

代理 -> 客户端： welcome、output、input_echo、expect_result、status_response、error、history_response、incidents_response、anomaly、autoboot_result、boot_stage、boot_stall、autoresponders_response、autoresponder_fired、suspended、resumed、link_down、link_up

会话示例：

-> {"type":"hello","name":"my-tool","role":"controller","protocol_version":1}
<- {"type":"welcome","broker_version":"x.y.z","protocol_version":1,"port":"/dev/ttyUSB0","baud":115200,"your_role":"controller"}
-> {"type":"send","id":"1","data":"dW5hbWUgLWEK"}
<- {"type":"output","data":"TGludXggNC4xOS4w...","timestamp":1709654321.123}

架构

┌───────────┐  ┌───────────┐
│ uart link │  │  gdb link │   <- device-facing, compiled in/out via Kconfig
└─────┬─────┘  └─────┬─────┘
      │              │
      ▼              ▼
┌──────────────────────────────┐
│         smolmux core         │  <- epoll event loop, message bus,
│  history · logging · anomaly │    role enforcement, expect engine
└──┬───────┬───────┬───────┬───┘
   │       │       │       │
   ▼       ▼       ▼       ▼
┌──────┐┌─────┐┌─────┐┌──────┐
│ unix ││ tcp ││ ws  ││ mcp  │  <- sinks, also compiled in/out
│socket││sink ││sink ││ sink │
└──────┘└─────┘└─────┘└──────┘

完整架构文档请参阅 DESIGN.md。

依赖项

必需： cJSON（随项目提供的单文件版本）

自动检测： PCRE2（libpcre2-8）。存在时用作正则表达式引擎，因为它能在内部限制回溯；缺少时，构建会自动回退到 POSIX ERE，因此它并非必需。可通过 -DSM_ENABLE_PCRE2=ON（缺少时会报错）或 -DSM_ENABLE_PCRE2=OFF 强制启用或禁用。

除 POSIX 和 cJSON 外，核心部分没有任何必需的外部依赖。

配套工具

• smolmux-cli - 命令行客户端（发送命令、读取输出；with-port <cmd> 会暂停端口、运行外部工具（如烧录器），然后始终恢复端口）
• smolmux-monitor - 交互式终端客户端，支持转义序列（先按前缀键，再输入命令；前缀默认为 Ctrl-]，可用 -e 更改，例如 -e esc 或 -e ^A）
• smolmux-mcp - 独立的 MCP 服务：连接到正在运行的代理，并提供串口工具（serial_send_command、serial_read、serial_boot_status、serial_add_autoresponder 等）。另一种方式是使用代理的 --mcp 接收端，在进程内嵌入 MCP。
• smolmux-gdb-mcp - 用于 GDB 调试的独立 MCP 服务：通过持有 --gdb 链路的代理提供 21 种工具，包括断点、单步执行、回溯、带名称标签的寄存器、内存、表达式求值、故障寄存器解码（核心支持时）、外设读取、gdb_interrupt，以及目前针对 ARM Cortex-M 的未知开发板探测（gdb_identify_target / gdb_generate_profile；计划支持其他架构）。资源和提示词包括 smolmux-gdb://board-probing 和 probe_unknown_board。启用 SM_ENABLE_GDB 后构建；已在 SAM C21 Xplained Pro 上验证芯片 ID。
• smolmux-watcher - 监控异常并将事件报告保存到磁盘的守护进程

相关文档

• 从这里开始 - 一屏式意图导航（每日使用、新开发板、架构、开发）。
• MCP 设置 - 在 Claude Code、Claude Desktop 或 Cursor 中注册 smolmux-mcp / smolmux-gdb-mcp。
• 日常使用指南 - 推荐的构建方式、运行时标志、U-Boot 闯入、启动阶段、开发板以及与烧录器的共存。
• 开发板探索工作流 - 新开发板操作手册（手动操作或使用 AI Agent）：接线、SWD 识别、控制台、外设。
• 开发板 Bring-up 模板 - 可按开发板复制使用的事实记录模板。
• 持久化串口设备名称 - 为 UART 转接器设置稳定名称（如 /dev/serial/rpi-console）。
• 硬件验证矩阵 - 已在真实硬件上验证的内容与尚未验证的内容。
• DESIGN.md / CLAUDE.md - 架构与贡献者指南。

免费版与 Pro 版

此仓库中的所有内容均采用 MIT 许可，包括完整源代码、线协议、通用设备配置文件和构建系统。自行构建即可获得完整产品。

smolmux Pro 提供便利，而非功能限制：预构建的静态二进制文件（x86_64 + aarch64、musl、零运行时依赖）、经过筛选的配置文件包（含各配置文件的说明），以及 6 个月电子邮件支持。一次性购买（$79）。zip 路径的 MCP 设置说明见 docs/MCP-SETUP-FULL.md（也包含在此公共代码树中）。

购买 smolmux Pro - 一次性支付 $79 - 下载内容包括当前的静态二进制文件和配置文件包。

许可证

MIT。cJSON 随项目提供，遵循其自身的 MIT 许可证 （deps/cJSON/LICENSE）。