Serial Gateway CLI

命令行工具，用于通过 Serial Gateway 与串口设备通信。

功能特性

• 交互式 REPL - 提供类似 telnet/ssh 的交互式终端体验
• 离线模式启动 - 支持离线启动 REPL，运行时连接 Gateway
• MCP Server 模式 - 支持 Model Context Protocol，可被 Claude Desktop 等 AI Agent 调用
• 灵活的 Gateway 连接 - 支持多种地址格式，运行时切换 Gateway
• 数据收发 - 支持向串口设备发送命令并接收响应，支持转义序列
• 会话日志 - 自动记录所有交互数据
• 彩色输出 - 使用 chalk 提供清晰的彩色输出

安装

npm install -g serial-gateway-cli

或者本地开发：

cd serial-gateway-cli
npm install
npm run build
npm link

使用

启动 REPL

# 离线模式启动（默认）
sgc repl

# 启动时连接到指定 Gateway
sgc repl --host 192.168.1.100:8080

# 支持多种地址格式
sgc repl --host ws://192.168.1.100:8080   # 完整 URL
sgc repl --host 192.168.1.100:8080        # IP:PORT
sgc repl --host 192.168.1.100             # 仅 IP（使用默认端口 8080）

# 启动时自动打开串口（需要同时指定 --host）
sgc repl --host localhost --open COM3 --baud 115200

# 指定日志目录
sgc repl --log-dir ./my-logs

本地命令

在 REPL 中，以下命令可用：

| 命令 | 描述 | |------|------| | :help | 显示帮助信息 | | :status | 显示当前连接状态 | | :list | 列出可用串口 | | :connect <host> | 连接到 Gateway（支持 IP:PORT、ws://URL、或仅 IP） | | :disconnect | 断开 Gateway 连接 | | :open <port> [@baud] | 打开串口 | | :close | 关闭当前串口 | | :send <data> | 发送原始数据（支持 \n, \r, \t, \xNN, \\ 转义） | | :log [file] | 显示日志或保存到文件 | | :exit | 退出 REPL |

使用示例

离线模式启动后连接

$ sgc repl

Serial Gateway CLI v0.1.0
输入 :help 查看帮助

[10:30:00] 离线模式 - 使用 :connect <host> 连接到 Gateway
sgc> :connect 192.168.1.100
[10:30:01] 正在连接到 Gateway: ws://192.168.1.100:8080...
[10:30:02] 已连接到 Gateway: ws://192.168.1.100:8080

sgc> :open COM3 @115200
[10:30:03] 正在打开串口 COM3 @ 115200 baud...
[10:30:04] 已打开串口 COM3 @ 115200 baud（已自动订阅）

sgc> show version
Cisco IOS Software, C2960 Software...

发送原始数据（含控制字符）

sgc> :send \x03         # 发送 Ctrl+C
sgc> :send AT\r\n       # 发送 AT 命令（带 CRLF）
sgc> :send Hello\nWorld # 发送多行数据

MCP Server 模式

MCP (Model Context Protocol) Server 模式允许 AI Agent（如 Claude Desktop）直接通过 MCP 协议访问串口设备。

启动 MCP Server

# 离线模式启动（默认），使用 gateway_connect 工具连接
sgc mcp

# 启动时自动连接到 Gateway
sgc mcp --host 192.168.1.100:8080

# 支持多种地址格式
sgc mcp --host ws://192.168.1.100:8080   # 完整 URL
sgc mcp --host 192.168.1.100:8080        # IP:PORT
sgc mcp --host 192.168.1.100             # 仅 IP（使用默认端口 8080）

配置 Claude Desktop

在 Claude Desktop 的配置文件中添加：

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "serial-gateway": {
      "command": "sgc",
      "args": ["mcp"]
    }
  }
}

注意: 默认使用离线模式启动，在 Claude Desktop 中通过 gateway_connect 工具连接到 Gateway。

可用的 MCP Tools

| Tool 名称 | 描述 | 参数 | |-----------|------|------| | gateway_connect | 连接到 Gateway | host | | gateway_disconnect | 断开 Gateway 连接 | 无 | | serial_list_ports | 列出可用串口 | 无 | | serial_open | 打开串口 | port, baudRate? | | serial_close | 关闭串口 | port | | serial_write | 写入数据 | port, data, encoding?, timeout? | | serial_subscribe | 订阅数据推送 | port |

使用示例

在 Claude Desktop 中：

用户：连接到本地的 Serial Gateway
Claude：[调用 gateway_connect 工具，host="localhost"]
已连接到 Gateway: ws://localhost:8080

用户：列出所有可用的串口
Claude：[调用 serial_list_ports 工具]
找到了以下串口：COM1, COM3

用户：打开 COM3，波特率 115200
Claude：[调用 serial_open 工具]
已成功打开串口 COM3 @ 115200 baud（已自动订阅）

用户：发送 AT 命令
Claude：[调用 serial_write 工具]
AT 命令已发送

命令行参数

REPL 模式

用法: sgc repl [选项]

选项:
  -V, --version              输出版本号
  -c, --open <port>          启动时自动打开指定串口（需配合 --host）
  -b, --baud <rate>          波特率 (默认: 115200)
  -h, --host <url>           Gateway 地址（默认: 离线模式）
  -l, --log-dir <path>       日志目录 (默认: ./logs)
  --help                     显示帮助信息

注意: --open 参数需要同时指定 --host，因为必须先连接到 Gateway 才能打开串口。

MCP 模式

用法: sgc mcp [选项]

选项:
  -V, --version              输出版本号
  -h, --host <url>           Gateway 地址（默认: 离线模式）
  -l, --log-dir <path>       日志目录 (默认: ./logs)
  --help                     显示帮助信息

开发

# 安装依赖
npm install

# 构建
npm run build

# 开发模式（监听文件变化）
npm run dev

# 运行测试
npm test

# 代码检查
npm run lint

# 类型检查
npm run typecheck

迁移指南

从 v0.1.0 升级

REPL 命令变更

| 旧命令 | 新命令 | 说明 | |--------|--------|------| | :connect COM3 | :open COM3 | 连接串口改用 :open | | :disconnect | :close | 断开串口改用 :close | | 无 | :connect <host> | 新增 Gateway 连接命令 |

CLI 参数变更

| 旧参数 | 新参数 | 说明 | |--------|--------|------| | --connect COM3 | --open COM3 | 参数名变更，语义更清晰 |

默认行为变更：

• 之前: REPL 启动时自动连接到 ws://localhost:8080
• 之后: REPL 默认离线模式启动，需要使用 :connect <host> 或 --host 参数连接 Gateway

MCP 工具重命名

| 旧工具名 | 新工具名 | 说明 | |----------|----------|------| | serial_connect | serial_open | 统一术语为 "打开/关闭" | | serial_disconnect | serial_close | 统一术语为 "打开/关闭" |

新增工具：

• gateway_connect(host) - 连接到 Gateway
• gateway_disconnect() - 断开 Gateway 连接

Claude Desktop 配置更新

如果你之前在配置中指定了 --host，现在可以移除它以使用离线模式：

// 旧配置（仍然兼容）
{
  "mcpServers": {
    "serial-gateway": {
      "command": "sgc",
      "args": ["mcp", "--host", "ws://localhost:8080"]
    }
  }
}

// 新配置（推荐，使用离线模式）
{
  "mcpServers": {
    "serial-gateway": {
      "command": "sgc",
      "args": ["mcp"]
    }
  }
}

在 Claude Desktop 中，先调用 gateway_connect 工具连接到 Gateway，再进行串口操作。

故障排查

REPL 启动后显示"离线模式"

这是正常行为。REPL 默认以离线模式启动，使用 :connect <host> 命令连接到 Gateway：

sgc> :connect 192.168.1.100

无法连接到 Gateway

1. 确认 Serial Gateway 服务正在运行
2. 检查 Gateway 地址是否正确（支持多种格式）
3. 检查防火墙设置

串口操作提示"未连接到 Gateway"

需要先连接到 Gateway，再操作串口：

sgc> :connect localhost    # 先连接 Gateway
sgc> :open COM3            # 再打开串口

串口打开失败

1. 确认串口名称正确（Windows: COMx, Linux: /dev/ttyUSBx, macOS: /dev/cu.usbserial-*）
2. 确认串口未被其他程序占用
3. 检查波特率设置

日志文件位置

默认情况下，日志文件保存在 ./logs/ 目录下，文件名格式为 sgc-YYYY-MM-DD-HHMMSS.log。

许可证

MIT