Serial Bridge

Serial Bridge 是一个 Hub，可在本地操作员与 MCP 代理之间共享两个串行控制台。它不依赖特定操作系统：安装 requirements.txt 中的 Python 包，即可在任意装有 Python 3.10+ 的主机上运行。Hub 位于 serial_bridge/ 包中；通过 python -m serial_bridge 或根目录下的 app.py 启动。

安装与启动

建议使用 Python 3.10 或更高版本。

python -m pip install -r requirements.txt
python -m serial_bridge

下面的 Shell 片段使用 PowerShell（$env:NAME = "..."）。在 bash 或 zsh 中，使用 export NAME=... 设置相同的名称。

Hub 在开始监听后，会在浏览器中打开控制台页面 http://127.0.0.1:8765/。根目录下的 app.py 启动方式与之等效。若不想打开浏览器标签页，可这样启动：

$env:SERIAL_BRIDGE_OPEN_UI = "off"
python -m serial_bridge

或传入 --no-open-ui。当环境变量禁用自动打开时，可使用 --open-ui 强制打开。未设置 SERIAL_BRIDGE_OPEN_UI 时默认打开；只有 0、false、no 和 off（不区分大小写）会禁用它。

首次启动时，Hub 会在端口绑定配置文件旁边自动生成一个访问令牌，写入 serial_bridge.token 文件（可通过 SERIAL_BRIDGE_TOKEN_FILE 覆盖路径）。请勿将密钥文件提交到版本控制。

在 Hub 主机上打开 Setup（http://127.0.0.1:8765/setup）可复制 Hub URL、查看访问令牌、轮换令牌，并粘贴 Cursor 的 mcpServers 片段。Setup 中的密钥（令牌明文、Rotate 以及包含密钥的片段）仅在回环地址（127.0.0.1 / ::1）上可见。

或者，在启动 Hub 前设置 SERIAL_BRIDGE_TOKEN，并将相同的密钥提供给 MCP 客户端。环境变量在该进程生命周期内会覆盖密钥文件；Rotate 仍会重写文件，但会发出警告，直到环境变量被取消设置或 Hub 在未设置该变量的情况下重启。

即使从回环地址连接，MCP 也需要身份验证。请勿将令牌放入源代码、静态前端文件、URL 或日志中。

Hub 监听在 0.0.0.0:8765 上，因此可从本地网络访问。请使用适当的主机防火墙和强令牌。远程代理无法更改模式或 Port Binding。

MCP

在 Hub 主机上使用 Setup（/setup）可获取可直接复制粘贴的 Cursor 配置。手动配置方式如下：

配置 Agent 的 Streamable HTTP MCP 连接：

URL: http://<hub-host>:8765/mcp
Authorization: Bearer <SERIAL_BRIDGE_TOKEN>

请精确使用 /mcp；Web UI 位于 /。MCP 服务器提供以下功能：

• serial_status：读取当前模式以及每个 Target 的 Port Binding、打开状态和忙碌提示。

• serial_exec：发送一条文本命令，并捕获输出，直到出现空闲间隔、可选的提示匹配或 60 秒超时。

• serial_send：发送一行文本或原始负载，不等待输出。

要测试状态和 Exec：

1. 在本地打开 Web UI，切换到 Bridge Mode。

2. 使用上述 URL 和 Bearer 头连接 MCP 客户端。

3. 调用不带参数的 serial_status，确认 mode 为 bridge，且目标 Target 已打开。

4. 调用 serial_exec，参数为 {"target":"linux","cmd":"uname -a"} 或 {"target":"rtos","cmd":"help"}。

5. 如果设备有稳定的提示符，可选择性传入 prompt；仅当提示值本身是正则表达式时，才将 prompt_is_regex 设为 true。

Exec 接受 Target 名称 linux 和 rtos，而不是串口设备名称。它返回捕获的 output，以及 timed_out、truncated 和 aborted 标志。

Exec 输出和 live/*.log 记录均为纯文本，已去除 ANSI 转义序列。Web UI 则会解释这些转义序列并显示设备颜色。

Port Binding

Port Binding 将 Target 分配给一个串口设备路径和波特率。内置默认值为 Windows 风格（linux 对应 COM3，rtos 对应 COM6，均为 115200）；在 Linux 或 macOS 上，请改为设置 /dev/ttyUSB0 等路径。

在启动前通过环境变量覆盖默认值：

$env:SERIAL_BRIDGE_LINUX_PORT = "COM8"
$env:SERIAL_BRIDGE_LINUX_BAUD = "57600"
$env:SERIAL_BRIDGE_RTOS_PORT = "COM9"
$env:SERIAL_BRIDGE_RTOS_BAUD = "115200"
python -m serial_bridge

等效的 CLI 标志为 --linux-port、--linux-baud、--rtos-port 和 --rtos-baud。SERIAL_BRIDGE_CONFIG 或 --config 选择持久化的 JSON 文件。加载顺序为：内置默认值，然后是环境变量/CLI 值，最后是持久化文件；Web UI 中保存的值优先。

只有操作员可以编辑 Port Binding，且只能在 CRT Mode 下、Hub 已释放端口时进行。Web UI 会为每个 Target 在下拉列表中列出检测到的串口；插入适配器后，使用 Scan 重新枚举。在 Web UI 中进行的更改会在重启后保留。

Live Directory

Live Directory 是 Hub 写入每个 Target 的 Bridge 会话日志和 bridge_status.json 的目录。默认位置是项目根目录旁的 <app-dir>/live/（与 serial_bridge.json 和根目录下的 app.py 位于同一目录）。

在启动前覆盖：

$env:SERIAL_BRIDGE_LIVE_DIR = "D:\logs\serial-bridge"
python -m serial_bridge

或传入 --live-dir。加载顺序与 Port Binding 相同：内置默认值，然后是环境变量/CLI，最后是持久化配置文件；Web UI 保存的值优先。

每次操作员进入 Bridge Mode 时，Hub 都会创建新的日志文件，命名为 <TargetName>-YYYY-MM-DD-HHMMSS.log（本地时间，24 小时制）。第二次 Bridge 会话会创建新文件；旧日志保留在原处，更改 Live 目录或重命名 Target 时不会迁移旧日志。

只能在 CRT Mode 下通过 Web UI 的 Bindings 面板编辑 Live 目录（与 Port Binding 相同的仅回环写入路径）。页脚会显示配置的目录，以及分配后的当前会话日志文件名。

Bridge Mode 与 CRT Mode

• Bridge Mode： Hub 拥有配置的串口。操作员和 Agent 可以发送命令并观察相同的实时日志。

• CRT Mode： Hub 释放串口，供 SecureCRT 或其他独占式串口客户端使用。在操作员返回 Bridge Mode 之前，MCP Exec 和 Send 将失败。

进入 Bridge Mode 前请断开 SecureCRT。切换到 CRT Mode 会中止正在进行的 Exec，并可能返回部分输出。

Raw Send 警告

serial_send 配合 raw_hex 会写入任意字节，不添加文本行分隔或自动换行。这是完整的控制台能力：控制字节可能中断启动、终止进程、改变设备状态或使会话无响应。命令请优先使用 serial_exec，仅在完全理解精确字节序列及其对设备的影响时，才使用 Raw Payload。