npm package: @neosamon/serial-gateway-cli
Description: 命令行工具，用于通过 Serial Gateway 与串口设备通信
Latest version: 0.2.1

# Serial Gateway CLI

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

## 功能特性

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

## 安装

```bash
npm install -g serial-gateway-cli
```

或者本地开发：

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

## 使用

### 启动 REPL

```bash
# 离线模式启动（默认）
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

```bash
# 离线模式启动（默认），使用 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`

```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                     显示帮助信息
```

## 开发

```bash
# 安装依赖
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`，现在可以移除它以使用离线模式：

```json
// 旧配置（仍然兼容）
{
  "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