Qt 原生桌面客户端 RayJinStudio/Deepseek_Harness_QTDesktop

dsh-qt

DeepSeek Harness（dsh）的 Qt6 / QML 原生桌面客户端。界面与交互 1:1 复刻 Web 原版，通信协议与原版完全一致——同一个 harness 宿主，Web 与 Qt 客户端可互换使用。

同会话同负载实测——内存省约 45%，CPU 占用约为三分之一。

功能

- 会话界面 1:1 复刻 Web 原版
- 流式 Markdown 渲染（增量分块、代码块独立刷新）、Think 思考折叠行
- 工具卡全型别：终端 / diff / 搜索 / 读写 / 网页，错误行首行摘要、运行态扫光
- 审批接管面板、提问卡片、消息队列坞（排队 / 插话，贴输入框叠放）
- 图片附件：拖拽 / Ctrl+V 粘贴 / 文件选择，气泡外缩略图（单图 240px 自适应、多图 64px 方格），点击全屏 lightbox 预览；历史图片经 session.attachment 惰性解析
- 产物 chips、复制 / 分支 chrome（仅轮次结束后出现在轮尾，与原版 TurnTailNodeView 一致）
- 轮次统计条（轮数 / 步数 / 耗时 / token 速率 / 缓存命中）
- 轨迹页：全事件时间线 + 标签化详情（Summary / Payload / Result / Schema / Timing）
- 会话管理：工作区树、会话搜索、重命名 / 归档 / 分支、历史向上分页
- 侧边栏：56px 收缩 rail、拖拽调宽、窗口宽度自适应收展（迟滞区间）
- 设置面板：内置各节 + 插件注入节，主题跟随系统（可 --theme 覆盖）

软件运行截图

会话界面

dsh-qt 会话界面

新会话首页

dsh-qt 新会话首页

设置面板（插件设置UI部分兼容）

dsh-qt 设置面板

插件兼容（React 设置页 → QML 原生组件）

官方 WebUI 插件常带 client 端 React 页面（settings.section 等 slot 注入）。本客户端不嵌入浏览器内核，而是用 Node 子进程运行插件前端逻辑，再把 React 元素树实时翻译成原生 QML 组件：

tools/plugin-runtime-core.mjs mini-React（createElement + hooks + 渲染）+ slots/ctx/fetch shim tools/plugin-runtime.mjs stdio 桥接（QProcess ↔ Node，JSON lines 协议） src/plugins/ClientPluginHost.* 插件发现（~/.dsh/profiles//node_modules）、spawn、sections 模型 src/ui/plugins/PluginTree.js 元素树 → QML 宿主组件（样式 / flex 布局 / 事件翻译） src/ui/plugins/R.qml 宿主组件（RBox/RColumn/RRow/RFlow/RText/RButton/RLink/RInput…）

- 插件前端代码在原版 bundle 中原样运行（VNode 树结构化diff），不嵌入 Chromium/WebView
- 已注册的 settings.section 出现在设置面板导航栏（按 order 排在内置节之后）
- 运行时状态 / 错误显示在导航栏底部；诊断日志带 [pluginHost] 前缀输出到 stderr

兼容性说明：已实测部分插件的设置页可用。mini-React 实现了常用 hooks 子集，宿主组件覆盖常见 HTML 元素与样式属性——部分插件可能存在兼容性问题（如依赖复杂第三方组件库、浏览器专有 API、canvas 等），欢迎反馈具体插件。

技术优势

- 纯 Qt 原生：Qt6 QML 渲染，无 Chromium / WebView 内核，启动快、体积小
- 深度内存优化：相比 Web 类原版（Electron / Tauri / WebView2 壳）内存与 CPU 占用显著更低
- C++ 侧 QAbstractListModel 增量模型，行级 dataChanged 精确失效（绝不整表重建）
- 流式 token 节流 flush + 块级前缀保持（已落定块不重绑，快速 token 流不重建整棵代理树）
- 图片按显示尺寸 2x 密度解码，历史附件惰性解析；轨迹页惰性装载（切走即卸载）
- 协议完全一致：HTTP POST 一元调用 + POST /api/respond + 两条只下行 WebSocket （/api/events.mux、/api/events.host），Typert remote 走 POST /api//
（payload {args: {...}}）——行为对照上游 packages/host/apiproxy/src/api/

构建

Windows（Qt 6.6.1 msvc2019_64 / msvc2022 均可） cmake -B build -DCMAKE_PREFIX_PATH=D:/software/Qt/6.6.1/msvc2019_64 -DCMAKE_BUILD_TYPE=Release cmake --build build -j

Linux
cmake -B build -DCMAKE_PREFIX_PATH=~/software/QT/6.5.3/gcc_64 -DCMAKE_BUILD_TYPE=Release
cmake --build build -j

运行

先启动 harness（需要 node 22+）
pnpm dsh --profile web # 默认监听 127.0.0.1:3080

再启动客户端 ./build/dsh-qt # 连默认 3080 ./build/dsh-qt -u http://127.0.0.1: Linux：本机 Wayland 组件过旧时必须 xcb
QT_QPA_PLATFORM=xcb ./build/dsh-qt

开发参数

- --dump：无头冒烟——连接后打印 workspace/session/conversation 行数并退出
- --demo：注入合成事件（全部工具卡型 + 审批 + 提问 + 队列），不连 host
- --shot ：启动后截图并退出（配 QT_QPA_PLATFORM=offscreen QT_QUICK_BACKEND=software）
- --theme light|dark：覆盖系统主题（默认跟随系统，与 WebUI 的 preference: 'system' 一致）
- --settings ：启动即打开设置面板并定位到指定节（插件节 id 也可，如 --settings subscription-auth）

结构（镜像 packages/client）

src/connection/ ≈ client/connection：ApiClient / WsDownlink / ConnectionController src/runtime/ ≈ client/runtime：Session/Workspace/Projection/Queue/Jobs/Interaction/ Settings/Subagent/Conversation Store + Runtime 路由 src/ui/ QML 模块，目录与 webui 的 ui-* 一一对应（layout/sidebar/conversation/ tool/questions/approvals/settings/subagent/theme） tools/_harness/ QML 几何探测 harness（qml.exe 直跑，布局回归用）

协议对照文档（上游单一事实源）：deepseek-harness-master/packages/host/apiproxy/src/api/。

未来展望

- Harness 启动器（Launcher）
- 在客户端内置 harness 启动与托管能力，支持按 profile 管理本地 harness 环境
- 提供环境检测与配置（Node/pnpm 版本、端口占用、工作目录与启动参数）
- 客户端启动时可自动拉起 harness，退出时按策略托管或回收进程，降低手工维护成本
- 增加启动健康检查与重连机制，确保会话可用性与恢复速度