본문으로 건너뛰기
Y

dsh-serial

youhui1/dsh-serial

Serial port debugging plugin for DeepSeek Harness: tools for the agent, a live terminal tab, and searchable logs.

설치

dsh plugin --profile web add github:youhui1/dsh-serial

README

dsh-serial

给 DeepSeek Harness(DSH) 用的串口调试插件:Host 侧八个工具 + 一个「串口」标签页。

  • Agent 能用:列端口、按线路参数打开、发文本或十六进制、增量读回、等某个模式出现、 控制 DTR/RTS/break、检索历史日志、关闭端口
  • 人能用:实时终端面板,时间戳 / 搜索 / 暂停滚动 / HEX 切换,行模式与终端键模式, 写日志开关与日志目录
  • 一套实现:面板、/serial 命令、Agent 工具走同一份代码;面板看到的数据不进模型上下文
  • 没有硬件也能开发:仓库自带 PTY 假串口(AT 应答 / 传感器流 / 回环三种 profile)

环境要求

项说明
DSH针对 0.2.2-rc.2 开发(与 @deepseek-ai/dsh-tools 对齐);DSH 大版本不同时可能加载失败
Node.js跟随 DSH 的要求
平台真串口在 Linux / macOS / Windows 都可用;假串口模拟器依赖 PTY,只在 Unix 可用(Windows 需要 com0com 之类的替代)
原生依赖serialport 13 走预编译二进制;部分 npm 配置会拦截 @serialport/bindings-cpp 的安装脚本,需要显式允许

标签页只在 DSH Web 里出现;工具本身在 TUI / headless 模式下同样可用。

安装

尚未发布到 npm,从源码安装:

git clone https://github.com/YouHui1/dsh-serial.git
cd dsh-serial
npm install

# 在 DSH 的 profile 里登记这个 checkout(路径用绝对路径最稳,profile 名换成你实际用的)
dsh plugin --profile web add "$PWD"

dsh plugin add 会把本包追加进 profile 的 bundle 列表(package.json 里有 dsh.bundle 声明)。 装完重启 DSH:标签栏多出「串口」,Agent 侧多出八个 serial_* 工具。

没有 dsh CLI(例如桌面版)时,手工完成同样的两件事:在 profile 的 package.json 里加一条 "@local/dsh-serial": "link:/path/to/dsh-serial",并把包名加进 dsh.profile.bundles。

卸载:

dsh plugin --profile web remove @local/dsh-serial

改代码后注意:client.js 在每次页面加载时按磁盘现编,刷新页面即可;src/ 是 DSH 进程启动时载入的, 必须重启 DSH。面板遇到宿主还没提供的接口时,会直接提示「重启 DSH 或刷新页面」。

快速开始:没有串口硬件

仓库自带一个假串口:它把 PTY 的 slave 端发布成一个真实 tty 路径,插件的设备层完全不用改。

# 终端 A:起一个模拟设备
python3 spike/vserial.py serve --link run/ttySIM0 --profile at

# 终端 B(或让 Agent 调工具):打开 run/ttySIM0,发 ATI

三种 profile:at(AT 指令应答)、sensor(周期性推送帧)、echo(原样回环)。 面板里手填 run/ttySIM0 打开,或直接让 Agent:

serial_open  path=run/ttySIM0  baudRate=115200
serial_write path=run/ttySIM0  data=ATI  appendNewline=true
serial_read  path=run/ttySIM0  framing=line

原理与实测边界见 spike/NOTES.md。

沙箱注意:DSH 的 bash 工具每次调用有独立的 /dev/pts,在里面创建的伪终端宿主进程看不到。 模拟器要用 full access 启动,或者放到你自己的终端里跑。

工具

工具作用
serial_ports列出系统枚举的串口(带 usb 标记,only: "usb" 可过滤主板 UART),以及本插件已打开的端口
serial_open按路径打开端口:波特率、数据位、停止位、校验位
serial_write发送 UTF-8 文本或精确十六进制字节;行尾可选 crlf / lf / cr / none
serial_read增量读取:每个字节有绝对偏移,默认从上次读到的位置继续;可切帧、可带到达时间
serial_expect等到某个字节序列(或正则)出现再返回;命中前不消费数据
serial_control拉 DTR / RTS、发一段 break(Arduino/ESP32 复位、打断卡住的设备)
serial_logs检索插件写下的日志文件:按设备、时间窗、子串或正则
serial_close关闭端口并释放给其他程序

读取语义是增量的:串口是一条没有消息边界的字节流,serial_read 返回 from / to / pending / missed,用 sinceSeq 可以重读任意起点,落后超过 64 KiB 会明确报告丢了多少。 切帧(line / length)切不完整的尾巴单独返回,不会丢。

同一套操作也有文本命令:/serial list|open|close|send|sendhex|read|state。

面板

标签栏的「串口」标签页:

  • 端口:下拉(已打开端口带 ● + 系统枚举)+ 手填路径;勾「仅 USB」隐藏 ttyS* 之类的主板串口; 波特率 / 数据位 / 停止位 / 校验位,打开 / 关闭
  • 输出:300ms 轮询,占满整列并自己滚动(和「轨迹」一样没有宽度拖拽手柄)。 开关选中时是高亮底色 + 强调边框:
    • 时间:每行前面加到达时间
    • 搜索:只显示包含该文字的行(按当前显示形式匹配,HEX 模式下搜十六进制)
    • 暂停滚动 / 继续滚动:暂停后数据照常接收,只是不再自动跳到底部
    • HEX:整段历史在十六进制和文本之间切换,亮起表示当前看的是 HEX
  • 发送:行 / 键 两种输入模式,行尾可选 crlf / lf / cr / none
    • 行模式(默认):回车发送,Shift+回车换行;输入框最多 5 行、再多就在框内滚动;↑/↓ 翻本地发送历史
    • 键模式:点一下输出区,之后每个按键直接发给设备(方向键、Ctrl 组合按终端转义序列发出), 设备自己的行编辑和历史(比如 shell 里按 ↑ 调上一条命令)因此可用;Enter 用所选行尾。 「回显」默认关——真实设备一般自己会回显;设备不回显时打开,本机也显示一份
  • 日志:写日志开关(对已打开的端口立即生效)、日志目录(离焦或回车保存)、恢复默认

线路参数(波特率 / 数据位 / 停止位 / 校验位 / 行尾)在点「打开」时记住,刷新页面后恢复。 输出按端口留在内存里,切到别的标签再回来不会丢;刷新整个页面后只能重建缓冲区里最近 64 KiB。

日志

每个端口一个文件,纯文本、每行一个 ISO 时间戳,不区分收发方向:

[2026-11-15T14:49:29.573Z] ATI
[2026-11-15T14:49:29.575Z] SIM-UART 1.0 (vserial spike)
  • 按行写入:终端可能一次只回显一个字符,日志会先攒成一行再落盘;等不到换行的半行 (比如提示符 OK> )静默 DSH_SERIAL_LOG_IDLE_MS(默认 250ms)后落盘
  • 单文件写满 10 MiB 自动换新文件(<名>-<时间戳>-2.log),旧文件不覆盖、不删除
  • 回车符去掉,其余控制字符显示成 .;非 UTF-8 字节不可还原——要看精确字节请用 hex 视图或工具返回的 hex
  • 用 serial_logs 检索历史(补上内存缓冲区看不到的部分)

配置

环境变量默认作用
DSH_SERIAL_LOG_DIR$DSH_HOME/serial-logs日志目录;优先级最高
DSH_SERIAL_LOG_MAX_BYTES10485760(10 MiB)单个日志文件的大小上限
DSH_SERIAL_LOG_IDLE_MS250半行日志在静默多久后落盘

界面保存的设置存在 $DSH_HOME/serial-settings.json(DSH_HOME 默认 ~/.dsh): logDir、logging、line(线路参数)。目录优先级:DSH_SERIAL_LOG_DIR > 界面保存值 > 默认值。

开发与测试

没有测试框架,四个普通 Node 脚本:

npm install
npm test                    # 依次跑下面四个
npm run test:unit           # 缓冲区/游标/溢出、切帧、日志轮转与行装配、日志检索、USB 分类、设置
npm run test:http           # 浏览器通道每个路由的契约(含设置、控制线报错、分段 hex)
npm run test:smoke          # 起假设备跑真插件:收发、切帧、expect、拔线、卸载
npm run test:client         # 视图契约(React 替身 + 脚本化 fetch,不需要浏览器)

test:http 与 test:smoke 需要 python3 来起假串口。

结构

index.js          Host 插件入口:tools / commands / webServer 三条注册
client.js         Web 视图:conversation.view 标签页「串口」
src/http.js       浏览器通道:state / open / close / write / read / control / settings
src/transport.js  唯一 import serialport 的地方:list / open / write / DTR-RTS-break
src/session.js    每端口的收发缓冲、字节偏移、读游标、日志流与轮转
src/logs.js       日志文件命名与检索
src/tools.js      八个工具的 schema、校验与模型可见的 render
src/framing.js    按行/定长切帧
src/settings.js   持久化设置(目录、开关、线路参数)
cordis.patch.yml  bundle 的 loader 插入行
locale/           标签与描述(en / zh)
docs/DETAIL.md    插件详情页
docs/BACKLOG.md   仍然缺失 / 未验证 / 刻意不做的部分
spike/            假串口模拟器(dev 工具,不属于插件运行时)
test/             四个测试脚本

隐私与数据

  • 插件不联网:只在 DSH 自己的 Web 服务上注册 /dsh-serial/* 路由,不向外部发请求
  • 面板轮询不写会话日志,串口数据不会自动进入模型上下文;AI 只有主动调 serial_* 工具时才读端口
  • 串口内容只落到本地日志文件(可关)。日志可能包含设备输出的敏感信息,注意目录权限

已知限制

  • serial_ports 只列操作系统枚举到的端口;伪终端这类虚拟端口要用路径直接打开
  • DTR/RTS/break 只有真串口支持;伪终端返回 Inappropriate ioctl for device,插件如实报错而不是假装成功
  • 端口是插件进程级共享,不按会话隔离
  • 伪终端不校验波特率与校验位,模拟环境里配错不会表现为乱码
  • 拔线不会自动重连:连接中断、会话保留为关闭状态且历史可读,重新插上后手动再打开 (同一个路径可能已经换了设备)
  • 刷新页面后输出区只能重建缓冲区里最近 64 KiB,更早的内容在日志里

其余缺口见 docs/BACKLOG.md。

License

MIT

관련 플러그인