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 覆盖）

软件运行截图

会话界面

新会话首页

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

插件兼容（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/<namespace>/<method> （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:<port>
# Linux：本机 Wayland 组件过旧时必须 xcb
QT_QPA_PLATFORM=xcb ./build/dsh-qt

开发参数

• --dump：无头冒烟——连接后打印 workspace/session/conversation 行数并退出
• --demo：注入合成事件（全部工具卡型 + 审批 + 提问 + 队列），不连 host
• --shot <file.png>：启动后截图并退出（配 QT_QPA_PLATFORM=offscreen QT_QUICK_BACKEND=software）
• --theme light|dark：覆盖系统主题（默认跟随系统，与 WebUI 的 preference: 'system' 一致）
• --settings <section>：启动即打开设置面板并定位到指定节（插件节 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，退出时按策略托管或回收进程，降低手工维护成本
  • 增加启动健康检查与重连机制，确保会话可用性与恢复速度