SPLoong — 参赛项目文档

项目名:SPLoong 串口调试软件
版本:v0.8 · 开源协议:GPL v3.0 · 作者 GitHub:helloworldpxy

一、源码仓库链接

源码仓库:

https://github.com/helloworldpxy/SPLoong
https://gitee.com/helloworldpxy/SPLoong
Release(v0.8,含 Windows exe 与 deepin deb):https://github.com/helloworldpxy/SPLoong/releases/tag/v0.8

二、项目文档

2.1 功能介绍

SPLoong 是一款跨平台串口调试软件,对标 PuTTY / MobaXterm,用于调试交换机、路由器、嵌入式开发板等串口设备;重点适配 deepin 25 及更新版本(LoongArch 新世界 / Wayland),同时支持 Windows、macOS 与其他 Linux。

核心能力:

串口通信:自动识别系统串口设备(Windows COMx、Linux /dev/tty*),支持 RS-232/422/485/423/449 及 USB 虚拟串口(CH340/CP2102/FT232RL 等),提供波特率、数据位、停止位、校验位、流控与解码编码(UTF-8/GBK/GB2312/GB18030/Big5 等)配置;支持 ASCII/HEX 收发。
SSH 远程调试:通过 SSH 连接远程主机(demo 目标:deepin 25 / LoongArch),提供交互式 Shell;支持远程串口调试(自动探测 socat/screen/minicom,sudo 密码自动提权)与远程串口扫描;支持断线自动重连。
终端体验:
- ANSI 16/256/真彩色渲染与控制序列过滤,兼容 oh-my-zsh、powerlevel10k 等 zsh 主题;
- pyte 终端仿真模式(vim/htop/备用屏/光标寻址);
- 键盘直通输入(PuTTY 风格,回车/方向键/Ctrl 组合直接转发);
- 字体/字号可调(系统字体框 + Ctrl+=/-),右键菜单支持"复制带颜色";
- 界面主题(跟随系统 / 深色 / 浅色)。
多会话页签:串口会话与 SSH 会话双页并行,数据各进各页,互不打断。
工程能力:会话保存/加载/最近会话(不落明文密码)、通信日志记录与导出、串口热插拔自动刷新、HEX 视图(合并刷新,高性能)、文件关联(.sploong-session 双击打开)与开机自启。
跨架构:x86(AMD64)、ARM64、LoongArch(新世界);LoongArch 上自动以系统 PyQt6 运行(详见开发过程)。

2.2 安装方式

Windows

方式 A(推荐):直接运行桌面版 SPLoong.exe(PyInstaller 打包,免安装 Python)。

方式 B(源码):

cd SPLoong
pip install -r requirements.txt      :: PySide6 / pyserial / paramiko / pyte
python run.py

deepin 25 / 其他 Linux

方式 A:安装 deb 包(LoongArch 亦可,依赖由系统 apt 提供):

sudo apt install -y python3-pyqt6 python3-paramiko python3-serial python3-pyte
sudo dpkg -i sploong_0.8.0-3_all.deb
# 桌面/应用菜单中搜索 SPLoong 启动;卸载 sudo dpkg -r sploong

方式 B:一键脚本(源码):

cd SPLoong
./scripts/install_deepin.sh --install        # 建 .venv 并安装依赖
./scripts/install_deepin.sh --create-desktop # 桌面快捷方式
./scripts/install_deepin.sh                  # 运行

方式 C:纯源码运行(依赖已由 apt 提供时):
```
cd SPLoong && python3 run.py
```

说明:LoongArch(新世界)暂无 PySide6 pip 预编译包,软件内置 PySide6→PyQt6 兼容垫片,配合 deepin apt 的 python3-pyqt6 即可运行,详见开发过程。

2.3 使用说明

串口调试:工具栏选择串口 →「配置」设置参数(含编码)→「连接」;接收显示在终端,底部输入框(ASCII/HEX + 行结束符)发送;设备热插拔后端口列表自动刷新。
SSH 连接:工具 > SSH 连接 手动填写主机/端口/用户名/密码(可选 sudo 密码)→ 连接后进入远程 Shell;工具 > 远程串口调试/扫描远程串口 可对远程主机上的串口设备进行操作。
终端仿真 / 键盘直通:连接后勾选发送区旁「仿真」可流畅使用 vim/htop 等全屏程序;勾选「键盘输入」后点击终端即可直接打字(回车、方向键、Ctrl+C 等均转发)。
会话与日志:文件 > 保存/打开/最近会话;工具 > 开始/停止日志 并导出。
外观:视图 > 终端字体…、增大/减小字号(Ctrl+=/-)、界面主题;终端内右键可复制(带颜色)/全选/清空。
deepin 权限:访问 /dev/tty* 需 dialout 组权限,可在远程执行 sudo usermod -a -G dialout $USER;软件在权限不足时给出提示,SSH 远程串口可通过 sudo 密码自动提权。

三、演示视频或截图(3–5 张)

四、开发过程说明(重点:如何用 deepin Skills 辅助开发)

4.1 总体过程

项目按需求分析 → 技术选型 → 核心串口模块 → GUI → SSH/远程串口 → deepin 适配 → 跨平台验证 → 打包发布的流程推进:

技术选型:Python 3.10+ + PySide6(Qt6)+ pyserial + paramiko + pyte;GUI 方案与语言依据需求文档 §3 自主决定,兼顾 deepin 25 兼容与跨平台效率。
功能开发:串口参数/收发、会话、日志、ASCII/HEX、SSH 交互与远程串口注入式会话、ANSI 渲染与终端仿真、多会话页签、主题/字体、编码扩展、热插拔、自动重连等。
验证:全程单元测试(pytest 46 项)+ 离屏 GUI 冒烟(9 项)+ 真机 SSH 集成验证(deepin 25 / loongarch64),并保留 Windows / deepin 双端实测记录。

4.2 使用 deepin Skills 辅助开发的说明(重点)

本项目在 deepin 适配阶段,系统调研并参考了 deepin-skills 技能库(本地路径 C:\Users\HelloWorld\Downloads\deepin-skills-master),通过在 AI 编程工具中调用子代理对技能库进行检索、按其规范实施,并对结果做了"可用 / 不适用"的甄别。具体如下:

调研方式:以只读子代理对技能库进行结构化调查(技能清单 → 定位与本次需求相关的主题文档 → 提取规范 → 输出借鉴结论),之后再落地代码与文档。
实际借鉴并落地的内容(来自 dtk-development 技能):
- 字体规范(references/utilities/font-manager.md 等):不硬编码字号、随系统可用字体回退 → 落地为 terminal_widget.py 的 default_terminal_font(),deepin/Linux 按 Noto Sans Mono CJK SC → Noto Sans Mono → DejaVu Sans Mono 回退,中文与等宽兼顾;字体/字号通过系统字体框选择,随 DDE 主题。
- Wayland 适配(references/platform-abstraction.md 等):QT_QPA_PLATFORM 需在 QApplication 创建前设置,且 X11/Wayland 双后端都要验证 → 落地为 __main__.py(先于 QApplication、且仅当会话为 Wayland 才设置,避免 X11 黑屏)。
- 主题与控件:界面不把 QSS 硬编码成唯一风格,对话框/菜单/字体框交给系统(Qt 平台主题自动贴合 DDE 风格)→ 落地为 视图 > 界面主题(跟随系统/深/浅)。
- 打包规范(references/app-dev-with-dtk.md、examples/dtk-codeviewer 的 debian 结构):debian/control 字段、desktop 安装于 /usr/share/applications、图标目录、Name[zh_CN] 等 → 落地为 packaging/ 与 scripts/install_deepin.py,最终产出 sploong_0.8.0-3_all.deb。
- 运行环境适配判断:结合技能库对 deepin Qt 生态的说明与实际验证(LoongArch 无 PySide6 wheel、cryptography/bcrypt 源码编译需 Rust),决定 LoongArch 采用 apt 的 python3-pyqt6 + 自研 PySide6→PyQt6 兼容垫片(src/sploong/__init__.py),上层代码零改动。
甄别与取舍:技能库主体为 C++/DTK 内容,DPalette/DGuiApplicationHelper/DFontManager/DConfig/DStyle/DMenu 及 dde-shell / dde-control-center / dde-tray 插件协议均属 DTK 专属,本项目为 PySide6 非 DTK 应用,未使用(仅作后续深度集成方向记录在文档中)。
可提供的佐证材料:
- 源码内 docs/deepin-adaptation.md(深度适配说明,含深 skill 借鉴点)、docs/development.md(技术选型与架构);
- README(中英双语)deepin 适配章节;
- 真机验证记录:SSH 连接 deepin 25 / loongarch64(内核 6.6.143-loong64-desktop-hwe)执行命令、扫描 /dev/ttyS*、运行 GUI 均正常。