DSH Serial Console

用户与 AI 模型共享同一个可审计的嵌入式串口会话。（D指导，我不想再复制粘贴了，你直接干活吧）

DSH Serial Console 是一个面向 DeepSeek Harness 的社区串口控制台项目。它把人工终端操作、模型工具调用、板卡输出和会话记录汇集在同一个控制台中，适用于 Linux 开发板、U-Boot、MCU Shell、AT 指令设备和其他串口调试场景。

本项目由社区独立维护，不代表 DeepSeek 官方产品或官方背书。

可以用它做什么

• 在浏览器中查看板卡启动日志和实时串口输出。
• 使用键盘直接操作设备，包括 Tab 补全、方向键、退格、粘贴、输入法和常用终端控制键。
• 选择串口、波特率和 CR、LF、CRLF 等行尾模式。
• 让 DeepSeek 模型与用户操作同一个串口，而不是分别占用设备。
• 让模型发现端口、建立连接、发送命令、读取输出、等待特定内容和添加审计标记。
• 在串口页右侧直接查看模型思考、工具进度和最终回复，无需来回切换会话标签。
• 在 Text 终端中使用 Ctrl+F 查找历史输出，并在匹配项之间前后跳转。
• 在 Text 与 HEX 视图之间切换，兼顾命令行操作和原始字节排查。
• 导出会话事件，并保留独立的串口审计记录。

终端体验

Text 模式提供真实的 VT 终端交互。板卡返回的提示符、ANSI 颜色、光标移动和同行刷新会直接呈现在当前终端画面中。

点击工具栏中的 Find 或在终端聚焦时按 Ctrl+F 可以查找当前 xterm 缓冲区。输入时会高亮匹配项；Enter 跳到下一个，Shift+Enter 跳到上一个，Esc 关闭查找。打开查找会暂停 Follow，避免实时输出把当前结果拉出视口。

在对话页与串口页之间切换时，控制台会从内存中的 xterm 检查点恢复终端画面、光标和来源标记，只增量处理离开后收到的事件；检查点不连续或事件窗口已截断时会自动回退到完整重建。

终端左侧提供独立来源标记：

这些标记只属于界面展示，不会写入串口数据或改变板卡收到的命令。

串口页内置可折叠的 AI 浏览窗。桌面端默认显示在右侧，可拖动分隔线调整宽度；窄屏下自动改为覆盖式抽屉。浏览窗只读呈现当前 DSH 会话的实时思考、工具状态、最终回复和错误，并使用 DSH 原生 Markdown 渲染标题、列表、链接、代码块和公式；底部仍使用 DSH 原生输入栏。折叠浏览窗不会卸载 xterm，终端内容、光标和滚动位置保持不变；开关和宽度仅保存在本机浏览器中。

用户与模型协作

用户和模型看到的是同一个串口会话：

• 用户可以随时观察模型命令及板卡响应。
• 模型可以读取受限范围内的串口事件。
• 每次发送都会记录来源，便于区分人工操作和模型调用。
• 所有写入按顺序发送，避免单次请求之间相互越过。

项目提供以下模型能力：

可追溯性

• RX 与 TX 都保留原始字节，文本仅用于友好显示。
• 事件包含会话、顺序、时间和来源信息。
• 浏览器清空视图不会删除 Host 侧记录。
• 内存事件过期时会明确报告缺口。
• 审计记录可用于复查模型操作、人工命令和板卡响应的先后关系。

适用场景

• 嵌入式!
• Linux 开发板启动与登录控制台
• U-Boot 环境变量、启动流程和镜像调试
• MCU 命令行与固件诊断接口
• Modem、GNSS 和其他 AT 指令设备
• 自动化烧录后的启动检查
• 长时间串口日志采集与故障复盘
• AI 辅助硬件调试和远程协作

快速开始

环境要求

• Node.js ^22.19.0 或 >=24.0.0
• DeepSeek Harness 0.2.0-rc.2（与插件 0.1.0-rc.5 配套验证）
• pnpm 11.22.0
• Windows 或 Linux 串口环境

已有 DSH：一行安装并启用

项目发布在 @infinitepersistence/dsh-serial-console。当前候选版为 0.1.0-rc.5，对应 DSH 0.2.0-rc.2。已经安装该版本 DSH 的用户，可以用一条命令将插件安装到 web profile，并同时启用 Host、网页串口页和模型工具：

dsh.cmd plugin --profile web add '@infinitepersistence/dsh-serial-console@0.1.0-rc.5' --save-exact

停止仍在运行的旧 Host 后，启动同一个 profile：

dsh.cmd --profile web

dsh.cmd web 与 dsh.cmd --profile web 等价。安装和启动必须使用同一个 profile；升级后请重启 Host，并在浏览器中使用 Ctrl+F5 刷新页面。

从旧 DSH 升级时，先完全退出 Host，再执行 npm.cmd install --global '@deepseek-ai/dsh@0.2.0-rc.2'，之后安装插件。仍使用 DSH 0.1.0-rc.7 的用户请保留插件 0.1.0-rc.4，不要混装 rc.5，也不要使用 allow-version 绕过兼容性检查。后续 DSH 版本需要重新验证，不能仅凭版本号较新认定兼容。

已安装插件：更新到本候选版

确认 DSH 已为 0.2.0-rc.2，停止旧 Host 后执行：

dsh.cmd plugin --profile web add '@infinitepersistence/dsh-serial-console@0.1.0-rc.5' --save-exact
if ($LASTEXITCODE -ne 0) { throw '插件更新失败，请不要继续启动' }
dsh.cmd --profile web

安装失败时不要继续启动。网页打开后用 Ctrl+F5 刷新。候选版发布到 npm 的 next 通道；对外安装指令固定具体版本，不依赖 latest，也不使用本地源码目录链接。

全新 Windows：安装环境、DSH 与插件

在 PowerShell 中依次执行：

# 基础环境
winget install --id Git.Git --exact --source winget --accept-package-agreements --accept-source-agreements
winget install --id OpenJS.NodeJS.LTS --exact --source winget --accept-package-agreements --accept-source-agreements
winget install --id Microsoft.VCRedist.2015+.x64 --exact --source winget --accept-package-agreements --accept-source-agreements

# 让当前 PowerShell 识别新安装的软件
$machinePath = [Environment]::GetEnvironmentVariable('Path', 'Machine')
$userPath = [Environment]::GetEnvironmentVariable('Path', 'User')
$env:Path = "$machinePath;$userPath"

# 安装固定的 pnpm 与 DSH 版本
& npm.cmd install --global pnpm@11.22.0 '@deepseek-ai/dsh@0.2.0-rc.2'

# 定位全局 dsh 命令
$npmGlobal = (& npm.cmd prefix --global).Trim()
$dsh = Join-Path $npmGlobal 'dsh.cmd'
$env:Path = "$npmGlobal;$env:Path"

# 安装并启用串口插件
& $dsh plugin --profile web add '@infinitepersistence/dsh-serial-console@0.1.0-rc.5' --save-exact

# 启动 DSH Web
& $dsh --profile web

启动后访问终端打印的本机地址（默认端口 3080），进入已有内容的对话并选择“串口”标签。DSH 0.2.0-rc.2 的空白会话首页会隐藏会话视图，不显示串口标签；这不等于插件安装失败。dsh plugin add 与普通 npm install/pnpm add 不同：它会读取包内的 bundle 清单，将插件 patch 加入指定 profile，并在下次启动时自动挂载。插件携带 serialport 的官方多平台预编译二进制，无需从源码构建。

Linux 与 macOS

确认 Node.js 与 DSH 版本满足上面的要求后执行：

dsh plugin --profile web add '@infinitepersistence/dsh-serial-console@0.1.0-rc.5' --save-exact
dsh --profile web

作为程序库安装

如果只是把控制台作为 React/Node.js 库嵌入自己的程序，可以使用：

pnpm add '@infinitepersistence/dsh-serial-console@0.1.0-rc.5' --save-exact

包提供以下公开入口：

• @infinitepersistence/dsh-serial-console/protocol：共享串口协议类型与编解码。
• @infinitepersistence/dsh-serial-console/serial：Node.js Host 串口管理与审计能力。
• @infinitepersistence/dsh-serial-console：DSH Host 串口服务。
• @infinitepersistence/dsh-serial-console/tool：模型串口工具插件。
• @infinitepersistence/dsh-serial-console/client：DSH Web 预构建客户端。
• @infinitepersistence/dsh-serial-console/react：可嵌入其他 React 应用的 xterm.js 控制台。

从源码构建

git clone https://github.com/InfinitePersistence/dsh-serial-console.git
cd dsh-serial-console
corepack enable
pnpm install --frozen-lockfile
pnpm typecheck
pnpm test
pnpm test:compat

test:compat 会先构建，再使用官方 Cordis/Typert/工具运行时验证 Host 挂载、工具注册和卸载清理，不打开物理串口。测试依赖中包含官方 Markdown 组件在独立测试环境所需的库；它们不随插件发布，DSH Web 中仍复用宿主组件。发布前还需用 npm pack 产物在独立 Web profile 完成界面与真实串口验收；构建成功不等于真机验证通过。

若安装时报 ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION，说明插件或依赖尚未满足 pnpm 的最短发布时间要求，请按错误中给出的时间等待后重试，不必删除 lockfile 或关闭供应链检查。新发布的插件版本也可能需要等待，发布成功不代表能立即通过这一检查。

本项目是 DeepSeek Harness 的可安装组合插件，同时也提供可复用的协议、Node.js 串口核心和 React 控制台；它不是一个双击即可运行的独立桌面应用。

当前状态

当前版本为 0.1.0-rc.5，仍属候选版，尚不是 0.1.0 稳定版。适配 DSH 0.2.0-rc.2 的 Typert 校验器工厂、Session/Chat 拆分和 Markdown 标签接口，保留已有终端查找、检查点和 AI 侧窗功能，不改串口收发算法。

本候选版已通过维护者 Windows 环境的依赖安装、类型检查、71 项测试、构建、Host/7 个工具兼容性检查和实际使用验收。修复了 autoInstallPeers 与锁文件不一致的问题，明确声明开发测试依赖，保持冻结安装可复现。该验证不代表已覆盖所有板卡、操作系统或后续 DSH 版本。

当前限制：

• 一次只管理一个活动物理串口。
• 暂不自动重连，也不会在重连后自动重放命令。
• 当前 Text 模式依赖板卡回显；关闭 Shell echo 时不会显示用户正在键入的字符。
• 用户与模型共享发送队列，但尚未提供整条命令级别的输入租约。
• 实时画面会在新的串口事件到达后及时刷新；连接旧版 Host 时会自动切换到兼容模式，无新事件且连接元数据未变化时不会重复刷新界面。
• 终端检查点仅保存在当前浏览器内存中；刷新页面、重载插件或事件出现缺口后会重新构建画面。
• 来源 gutter 的历史行归属属于辅助展示，原始审计事件才是权威记录。
• 多板卡管理、稳定 USB 身份绑定和审计完整性增强仍在规划中。

项目文档

• 架构与设计边界
• 上游 Harness monorepo 拆包参考
• 第三方许可证

参与贡献

欢迎通过 Issue 报告设备兼容性、终端行为和 Harness 接入问题，也欢迎提交 Pull Request。涉及真实设备的反馈，请提供必要的复现条件，但不要上传串口凭据、访问令牌、私有固件、设备序列号或包含敏感信息的完整日志。

许可证

本项目采用 MIT License。第三方组件的许可证信息见 THIRD_PARTY_NOTICES.md。