1. 从命令行到悬浮球我为什么要把 DeepSeek Harness 藏进一个球里DeepSeek Harness 这套东西圈内人应该不陌生。它本质上是一个把大模型能力封装成可调用工具链的运行时框架你可以把它理解成一个“AI 的手和脚”——模型负责思考Harness 负责真正去碰你的文件系统、执行命令、读写代码、跑工作流。但问题也恰恰出在这里它太“重”了。每次要用你得开终端、激活环境、敲一长串命令、等它加载完 skill 和插件然后才能开始干活。对于我这种一天要唤起它十几次的人来说这套流程本身就是一种消耗。我试过把它挂在 IDE 里试过做成命令行别名甚至试过用快捷键绑定脚本。但这些方案都有同一个毛病它们都要求我“先切换到某个界面”然后才能操作。而我真正想要的是它像输入法一样随时待命——我按一下它出来我说一句它去干干完它缩回去不占地方、不抢焦点、不打断我手头的事。这就是 DeepSeek Orb 这个项目的起点把 DeepSeek Harness 改成一个桌面悬浮球。悬浮球这个交互形态最早是手机上的辅助触控后来被各种桌面工具借用。它最大的价值在于“常驻但不打扰”。一个半透明的小球贴在屏幕边缘你不需要它的时候它几乎不存在你需要它的时候一键唤起。我把它和 Harness 结合之后整个使用体验发生了质变以前是“我去找工具”现在是“工具在我手边”。它能替你操作电脑——读写文件、执行脚本、整理目录、跑批处理它能在后台干活——你交代完任务就可以去干别的它自己跑完再通知你。这套东西我开源了名字就叫 DeepSeek Orb。这篇文章适合两类人看一类是已经在用 DeepSeek Harness、但觉得每次调用太麻烦的开发者另一类是对 Qt 桌面悬浮球开发感兴趣、想拿一个真实项目练手的人。我会把整个项目的设计思路、核心实现、踩过的坑、以及怎么把它部署到你自己的机器上全部拆开讲清楚。不管你是刚接触 Harness 的新手还是已经写过插件的老手应该都能从里面捞到点能直接用的东西。2. 整体架构设计悬浮球和 Harness 到底怎么接2.1 为什么选 Qt 而不是 Electron做桌面悬浮球第一个要决策的就是技术栈。市面上主流方案有三类Electron、Qt、以及各平台原生。我最后选了 Qt原因很实在。Electron 做悬浮球不是不行但它有个致命问题内存占用和启动开销。一个空白的 Electron 窗口光运行时就要吃掉 80 到 150MB 内存启动冷加载动辄一两秒。悬浮球这种东西是要常驻的你不可能让它一直占着这么多资源。而且 Electron 的透明窗口和置顶行为在不同系统上表现不一致Windows 上还好Linux 下各种合成器的兼容性会让你怀疑人生。Qt 的优势在于它是真正的原生框架。一个 Qt Widgets 或 QML 写的悬浮球内存占用可以压到 20MB 以内启动基本是毫秒级。透明背景、无边框、置顶、鼠标穿透这些悬浮球必需的特性Qt 都有成熟的支持。更重要的是Qt 的跨平台能力足够强我一套代码在 Windows 和 Linux 上都能跑macOS 稍微改改也能用。原生方案Win32 API 或 GTK性能最好但开发成本太高而且完全没有跨平台性。对于一个开源项目来说让更多人能跑起来比极致性能更重要。所以 Qt 是那个平衡点。2.2 悬浮球与 Harness 的通信模型架构上我把整个系统拆成两个独立进程Orb 前端悬浮球 UI和Harness 后端任务执行引擎。为什么不放在一个进程里因为 Harness 执行任务时可能会跑很久甚至卡住如果和 UI 同进程界面就假死了。分离之后UI 永远流畅后端该跑多久跑多久。两者之间用本地 socket 通信具体是 Unix Domain SocketLinux/macOS和 Named PipeWindows。选本地 socket 而不是 HTTP是因为它更轻、更快、没有端口占用问题也不需要处理跨域。消息格式用 JSON简单直接调试的时候肉眼就能看懂。通信协议我设计得很简单就几种消息类型消息类型方向作用submit_taskOrb → Harness提交一个自然语言任务task_statusHarness → Orb回报任务进度排队/执行中/完成/失败task_resultHarness → Orb返回最终结果或错误信息cancel_taskOrb → Harness取消正在执行的任务ping/pong双向心跳检测确认对方还活着这个设计的好处是Orb 完全不需要知道 Harness 内部怎么执行任务它只负责“提交”和“展示结果”。Harness 也完全不需要知道 UI 长什么样它只管“收任务”和“报状态”。两边可以独立开发、独立升级。2.3 一键唤起的交互设计“一键唤起”这四个字说起来简单做起来要考虑的细节一大堆。首先是全局快捷键怎么注册。Qt 本身没有提供全局热键 API得用平台相关的方案Windows 上用RegisterHotKeyLinux 上用 X11 的XGrabKey或者 Wayland 下的 portal 接口。我封装了一层抽象让上层代码不用关心平台差异。快捷键我默认设的是CtrlShiftSpace这个组合在大多数系统上都不会和常用软件冲突。但我也留了配置文件用户可以自己改。这里有个坑有些桌面环境会抢占某些快捷键注册失败的时候要给出明确提示而不是默默失效。唤起之后的行为也值得说道。我的设计是按一下快捷键悬浮球从屏幕边缘滑出并展开成输入框再按一下收回成小球。如果输入框里已经有内容按 Esc 清空并收回。这个“展开-收回”的动画我用 QPropertyAnimation 做的200 毫秒的缓动手感很顺。别小看这个动画没有它的话界面切换会显得很生硬用久了会觉得烦躁。2.4 后台干活的实现思路“后台干活”是这个项目区别于普通悬浮球的核心。普通悬浮球点一下就是执行一个固定动作而 DeepSeek Orb 点一下是提交一个任务给 HarnessHarness 在后台异步执行执行完了再通知 Orb。这里的关键是任务队列和状态机。Harness 后端维护一个任务队列同一时间只执行一个任务避免多个任务同时操作文件系统导致冲突。每个任务有明确的状态pending、running、done、failed、cancelled。Orb 前端根据状态变化更新悬浮球的视觉反馈——执行中球会缓慢旋转完成了球会闪一下绿色失败了闪红色。任务执行过程中Harness 会定期把进度通过 socket 推给 Orb。比如“正在读取文件 3/10”、“正在执行命令”、“正在生成结果”。这些进度信息会显示在悬浮球展开后的面板里让用户知道它没卡死。这个反馈机制非常重要我一开始没做结果用户提交任务后不知道它在干嘛以为程序挂了反复点反而把队列塞满了。3. 核心细节拆解悬浮球 UI 与 Harness 调用的关键实现3.1 悬浮球的窗口属性配置悬浮球要“浮”在桌面上窗口属性必须配对。Qt 里核心是这几个 flagsetWindowFlags(Qt::FramelessWindowHint | // 无边框 Qt::WindowStaysOnTopHint | // 始终置顶 Qt::Tool | // 不在任务栏显示 Qt::NoDropShadowWindowHint); // 不要系统阴影 setAttribute(Qt::WA_TranslucentBackground); // 背景透明Qt::Tool这个 flag 很关键它让窗口不出现在任务栏和 AltTab 列表里。悬浮球是辅助工具不应该占用任务栏位置。WA_TranslucentBackground配合 QPainter 自己画圆形背景才能做出真正的圆形悬浮球而不是一个方形窗口里画个圆。置顶这块有个细节WindowStaysOnTopHint在某些全屏应用比如游戏、视频播放器下会失效这是系统层面的限制没法绕过。我的处理是检测到全屏应用时自动隐藏悬浮球退出全屏再显示。这个逻辑通过监听窗口焦点变化来实现。3.2 拖拽与边缘吸附悬浮球要能拖动但拖完之后要自动吸附到屏幕边缘这是用户预期。实现上重写mousePressEvent、mouseMoveEvent、mouseReleaseEvent三个事件。拖动过程中记录鼠标按下时的偏移量移动时用move()更新位置。释放时计算当前球心到屏幕左右边缘的距离哪个近就吸附到哪边。吸附动画同样用 QPropertyAnimation让球“滑”过去而不是“跳”过去。这里有个容易忽略的点多显示器。用户可能有两个甚至三个屏幕悬浮球要能跨屏拖动吸附时要判断当前在哪个屏幕内吸附到那个屏幕的边缘。我用QGuiApplication::screenAt()获取鼠标所在屏幕然后取那个屏幕的availableGeometry()来计算吸附位置。这个细节不做的话多屏用户会觉得很别扭。3.3 Harness 任务提交的封装Orb 前端提交任务时不是直接把用户输入的原话丢给 Harness而是要先做一层封装。因为用户输入的是自然语言比如“帮我把下载目录里的图片按日期整理一下”Harness 需要知道这是一个文件操作任务涉及哪个目录、什么类型的文件、按什么规则整理。我的做法是在 Orb 侧做一个轻量的意图预处理提取关键信息路径、文件类型、操作类型组装成一个结构化的任务描述再发给 Harness。Harness 侧收到结构化描述后再结合 skill 和插件的能力去执行。{ task_id: orb-20250101-001, intent: organize_files, params: { target_dir: ~/Downloads, file_type: image, rule: by_date }, raw_input: 帮我把下载目录里的图片按日期整理一下, timestamp: 1735689600 }为什么要保留raw_input因为有些复杂任务没法完全结构化Harness 侧可能需要原始文本来做更精细的理解。结构化字段是“快速通道”原始文本是“兜底方案”两者结合成功率最高。3.4 Skill 与插件的加载机制DeepSeek Harness 的能力扩展靠 skill 和插件。skill 可以理解成“技能包”一个 skill 就是一组相关的操作能力比如文件操作 skill、代码执行 skill、网络请求 skill。插件则是更底层的扩展可以 hook Harness 的执行流程。Orb 启动时会先检查 Harness 后端是否已经加载了必要的 skill。如果没有它会尝试自动加载。这里有个顺序问题必须先启动 Harness 后端并完成 skill 加载Orb 才能提交任务。所以我的启动脚本是先拉起 Harness等它发ready信号再拉起 Orb。skill 的加载路径我做成可配置的。默认从~/.deepseek-harness/skills/读取用户也可以指定其他目录。每个 skill 是一个独立的文件夹里面有manifest.json描述元信息有入口脚本定义具体能力。这种设计让 skill 可以独立分发、独立更新不用动 Harness 核心代码。注意skill 加载失败时Harness 不应该直接崩溃而应该记录错误、跳过这个 skill、继续加载其他的。我一开始没做容错结果一个 skill 的 manifest 写错了格式整个 Harness 起不来排查了半天。4. 实操过程从零把 DeepSeek Orb 跑起来4.1 环境准备与依赖安装先说环境。我主要在 LinuxUbuntu 22.04和 Windows 11 上测试macOS 也跑通了但没深度测试。基础依赖如下Qt 6.5 或以上Qt 5.15 也能用但 QML 部分要改CMake 3.20一个 C17 编译器GCC 11 / MSVC 2022 / Clang 14Python 3.10Harness 后端是 Python 写的DeepSeek Harness 本体从官方仓库拉取Linux 下装 Qt 最省事的方式是用系统包管理器sudo apt install qt6-base-dev qt6-declarative-dev qt6-tools-dev \ libqt6websockets6-dev cmake build-essentialWindows 下建议用 Qt 官方在线安装器勾选 MSVC 2022 64-bit 套件。装完之后把 Qt 的 bin 目录加到 PATH 里不然 CMake 找不到。Harness 本体我假设你已经装好了。如果还没装去官方仓库按 README 走一遍。装完之后确认harness --version能正常输出版本号。4.2 编译 Orb 前端克隆仓库之后编译流程很标准git clone https://github.com/yourname/deepseek-orb.git cd deepseek-orb mkdir build cd build cmake .. -DCMAKE_BUILD_TYPERelease cmake --build . -j$(nproc)编译产物是一个可执行文件deepseek-orb。第一次运行之前先检查配置文件config/orb.json{ hotkey: CtrlShiftSpace, harness_socket: /tmp/deepseek-harness.sock, ball_size: 56, edge_snap: true, auto_hide_fullscreen: true, theme: dark }harness_socket这个路径要和 Harness 后端配置的一致不然连不上。ball_size是悬浮球直径单位像素56 是我觉得比较舒服的大小你可以按自己屏幕分辨率调。4.3 启动 Harness 后端并加载 SkillHarness 后端的启动命令取决于你的安装方式。如果是 pip 装的deepseek-harness serve --socket /tmp/deepseek-harness.sock --skills ~/.deepseek-harness/skills/--socket指定 socket 路径要和 Orb 配置一致。--skills指定 skill 目录。启动之后你会看到日志输出确认它加载了哪些 skill、监听了哪个 socket。如果 skill 加载报权限错误比如 Windows 上常见的SetNamedSecurityInfoW failed那通常是 skill 目录的 ACL 有问题。解决办法是给当前用户对该目录的完全控制权限。Linux 下则是检查目录的 owner 和 mode确保当前用户有读写执行权限。4.4 联调提交第一个任务两边都起来之后按CtrlShiftSpace唤起悬浮球输入一个简单任务测试比如“列出当前目录下的所有文件”。正常情况下悬浮球会旋转几秒然后弹出结果面板显示文件列表。如果没反应按这个顺序排查确认 Harness 后端进程还活着ps aux | grep harness确认 socket 文件存在ls -l /tmp/deepseek-harness.sock看 Orb 的日志输出启动时加--verbose看 Harness 的日志输出我踩过最坑的一次是 socket 路径写错了Orb 一直连不上但没有任何提示就静静地待在那里。后来加了连接失败的重试和提示体验才好起来。4.5 打包与开机自启开发调试跑通之后就该考虑日常使用了。Linux 下做个 systemd user serviceWindows 下做个计划任务或者启动项。这样开机之后 Harness 和 Orb 自动起来你随时按快捷键就能用。Linux 的 service 文件大概长这样[Unit] DescriptionDeepSeek Harness Backend Afternetwork.target [Service] ExecStart/usr/local/bin/deepseek-harness serve --socket /tmp/deepseek-harness.sock Restarton-failure [Install] WantedBydefault.targetOrb 前端也可以做成 service但因为它有 UI更推荐放到桌面环境的自启动里。GNOME 下就是往~/.config/autostart/放一个.desktop文件。5. 常见问题与排查技巧实录5.1 悬浮球不显示或显示异常最常见的原因是透明背景没生效。检查两点一是WA_TranslucentBackground属性有没有设二是窗口管理器是否支持合成compositing。有些轻量级桌面环境默认关闭合成透明就会变成黑色。解决办法是开启合成或者退而求其次给悬浮球一个纯色背景。另一个原因是窗口被其他置顶窗口盖住了。WindowStaysOnTopHint不是绝对的两个都置顶的窗口之间还是有层级关系。如果发现悬浮球被盖住可以尝试周期性调用raise()但这会带来性能开销不建议频繁做。5.2 快捷键注册失败快捷键注册失败通常有两个原因一是组合键被系统或其他软件占用了二是权限不足。Windows 下RegisterHotKey失败会返回错误码可以查一下具体原因。Linux 下 X11 的XGrabKey如果被占用会收到BadAccess错误。我的建议是准备几个备选快捷键注册失败时自动尝试下一个并在日志里明确记录。用户也可以在配置文件里手动指定一个没被占用的组合。5.3 Harness 任务执行超时或卡死任务卡死的原因很多常见的有skill 内部死循环、外部命令等待输入、网络请求没有超时设置。我的处理是在 Harness 侧给每个任务加一个可配置的超时时间默认 300 秒。超时之后强制终止任务返回失败状态并记录日志。但强制终止有个风险如果任务正在写文件中途被杀可能导致文件损坏。所以对于文件写操作我建议 skill 内部实现原子写入——先写临时文件写完再重命名。这样即使中途被杀原文件也不会损坏。5.4 多屏环境下悬浮球位置错乱多屏环境下屏幕坐标是相对于整个虚拟桌面的不是相对于单个屏幕。如果你直接用绝对坐标悬浮球可能会跑到屏幕外面去。正确做法是用QScreen::availableGeometry()获取当前屏幕的可用区域所有位置计算都基于这个区域。还有一个坑不同屏幕的 DPI 可能不一样。Qt 6 默认开启了高 DPI 缩放但如果你手动设置了固定像素值在不同 DPI 的屏幕上大小会不一致。解决办法是用逻辑像素而不是物理像素或者监听screenChanged信号动态调整。5.5 常见问题速查表现象可能原因排查方向悬浮球不显示透明背景未生效 / 被置顶窗口盖住检查窗口 flag 和合成设置快捷键无响应组合键被占用 / 注册失败换组合键看日志错误码任务一直转圈Harness 未启动 / socket 连不上检查后端进程和 socket 文件任务执行报权限错误skill 目录 ACL 问题检查目录权限和 owner多屏位置错乱用了绝对坐标 / DPI 不一致改用 availableGeometry 和逻辑像素后台任务卡死skill 死循环 / 命令等待输入加超时检查 skill 实现5.6 几个我踩过的坑和对应技巧第一个坑是动画和拖拽冲突。我一开始在拖拽释放时启动吸附动画但如果用户快速连续拖拽上一个动画还没结束新的拖拽就开始了位置会乱。解决办法是在拖拽开始时先stop()掉正在运行的动画。第二个坑是socket 消息粘包。本地 socket 是流式的不保证一次read就能读到一条完整消息。我一开始没处理这个结果偶尔会解析 JSON 失败。后来加了一个简单的分帧协议每条消息前面加 4 字节的长度头读的时候先读长度再读内容。第三个坑是Harness 重启后 Orb 连不上。Harness 崩溃重启后socket 文件可能还在但连接已经断了。Orb 需要检测到连接断开后自动重连而不是一直用旧的连接。我加了一个心跳机制每隔 5 秒发一次 ping连续三次没收到 pong 就重连。第四个坑是中文输入法冲突。悬浮球展开成输入框后如果用户用中文输入法某些桌面环境下输入法候选框会跑到屏幕角落。这是因为输入框窗口的定位和输入法框架的交互有问题。解决办法是确保输入框窗口有正确的Qt::WA_InputMethodEnabled属性并且位置更新时通知输入法框架。6. 还能怎么扩展几个我打算继续做的方向这个项目目前已经能稳定日常使用了但我觉得还有不少可以打磨的地方。第一个方向是多任务并行。现在 Harness 后端是单任务队列一次只能跑一个任务。如果能让多个不冲突的任务并行执行效率会高很多。难点在于冲突检测——两个任务都要写同一个文件怎么办我打算做一个简单的资源锁机制任务提交时声明它需要哪些资源调度器根据资源占用情况决定是否并行。第二个方向是任务历史与回放。现在任务执行完结果看完就没了。如果能保存历史记录支持搜索和回放会很有用。特别是那些复杂的、多步骤的任务回放能帮用户理解 Harness 到底做了什么。这个功能对调试 skill 也很有帮助。第三个方向是更丰富的视觉反馈。现在悬浮球只有旋转、闪绿、闪红三种状态。我想加上进度环让用户一眼就能看出任务执行到哪一步了。还想加上音效提示任务完成时“叮”一声不用一直盯着屏幕看。第四个方向是移动端 companion。有时候我不在电脑前但想让 Harness 帮我跑个任务。如果能在手机上提交任务、查看结果会很方便。技术上就是做一个移动端 app通过局域网连接到桌面端的 Harness。这个涉及网络通信和安全认证得仔细设计。第五个方向是skill 市场。现在 skill 要手动安装、手动配置对普通用户门槛太高。如果能做一个 skill 市场用户点一下就能安装会自动处理依赖和配置那 Harness 的生态就能真正跑起来。这个工程量比较大但我觉得是值得做的。我个人在实际使用中最大的体会是工具的价值不在于功能多强而在于用起来有多顺手。DeepSeek Harness 本身能力很强但之前每次调用都要折腾一番导致我反而不太愿意用它。改成悬浮球之后调用成本降到几乎为零我用它的频率翻了不止一倍。这也让我重新思考了一个问题很多 AI 工具之所以没被用起来不是因为模型不够聪明而是因为交互摩擦太大。把摩擦降下去价值自然就出来了。最后分享一个小技巧如果你也在做类似的桌面常驻工具一定要把日志做好。悬浮球这种东西出问题的时候往往没有明显的报错界面用户只看到“没反应”。这时候日志就是唯一的线索。我的做法是 Orb 和 Harness 都输出结构化日志到文件出问题时让用户把日志发过来基本一眼就能定位。这个习惯帮我省了无数排查时间。 
长河君 · 2026/10/31 3:33:44 · 阅读 1.2k DeepSeek Harness 桌面悬浮球：Qt 实现一键唤起与后台任务执行
1. 从命令行到悬浮球我为什么要把 DeepSeek Harness 藏进一个球里DeepSeek Harness 这套东西圈内人应该不陌生。它本质上是一个把大模型能力封装成可调用工具链的运行时框架你可以把它理解成一个“AI 的手和脚”——模型负责思考Harness 负责真正去碰你的文件系统、执行命令、读写代码、跑工作流。但问题也恰恰出在这里它太“重”了。每次要用你得开终端、激活环境、敲一长串命令、等它加载完 skill 和插件然后才能开始干活。对于我这种一天要唤起它十几次的人来说这套流程本身就是一种消耗。我试过把它挂在 IDE 里试过做成命令行别名甚至试过用快捷键绑定脚本。但这些方案都有同一个毛病它们都要求我“先切换到某个界面”然后才能操作。而我真正想要的是它像输入法一样随时待命——我按一下它出来我说一句它去干干完它缩回去不占地方、不抢焦点、不打断我手头的事。这就是 DeepSeek Orb 这个项目的起点把 DeepSeek Harness 改成一个桌面悬浮球。悬浮球这个交互形态最早是手机上的辅助触控后来被各种桌面工具借用。它最大的价值在于“常驻但不打扰”。一个半透明的小球贴在屏幕边缘你不需要它的时候它几乎不存在你需要它的时候一键唤起。我把它和 Harness 结合之后整个使用体验发生了质变以前是“我去找工具”现在是“工具在我手边”。它能替你操作电脑——读写文件、执行脚本、整理目录、跑批处理它能在后台干活——你交代完任务就可以去干别的它自己跑完再通知你。这套东西我开源了名字就叫 DeepSeek Orb。这篇文章适合两类人看一类是已经在用 DeepSeek Harness、但觉得每次调用太麻烦的开发者另一类是对 Qt 桌面悬浮球开发感兴趣、想拿一个真实项目练手的人。我会把整个项目的设计思路、核心实现、踩过的坑、以及怎么把它部署到你自己的机器上全部拆开讲清楚。不管你是刚接触 Harness 的新手还是已经写过插件的老手应该都能从里面捞到点能直接用的东西。2. 整体架构设计悬浮球和 Harness 到底怎么接2.1 为什么选 Qt 而不是 Electron做桌面悬浮球第一个要决策的就是技术栈。市面上主流方案有三类Electron、Qt、以及各平台原生。我最后选了 Qt原因很实在。Electron 做悬浮球不是不行但它有个致命问题内存占用和启动开销。一个空白的 Electron 窗口光运行时就要吃掉 80 到 150MB 内存启动冷加载动辄一两秒。悬浮球这种东西是要常驻的你不可能让它一直占着这么多资源。而且 Electron 的透明窗口和置顶行为在不同系统上表现不一致Windows 上还好Linux 下各种合成器的兼容性会让你怀疑人生。Qt 的优势在于它是真正的原生框架。一个 Qt Widgets 或 QML 写的悬浮球内存占用可以压到 20MB 以内启动基本是毫秒级。透明背景、无边框、置顶、鼠标穿透这些悬浮球必需的特性Qt 都有成熟的支持。更重要的是Qt 的跨平台能力足够强我一套代码在 Windows 和 Linux 上都能跑macOS 稍微改改也能用。原生方案Win32 API 或 GTK性能最好但开发成本太高而且完全没有跨平台性。对于一个开源项目来说让更多人能跑起来比极致性能更重要。所以 Qt 是那个平衡点。2.2 悬浮球与 Harness 的通信模型架构上我把整个系统拆成两个独立进程Orb 前端悬浮球 UI和Harness 后端任务执行引擎。为什么不放在一个进程里因为 Harness 执行任务时可能会跑很久甚至卡住如果和 UI 同进程界面就假死了。分离之后UI 永远流畅后端该跑多久跑多久。两者之间用本地 socket 通信具体是 Unix Domain SocketLinux/macOS和 Named PipeWindows。选本地 socket 而不是 HTTP是因为它更轻、更快、没有端口占用问题也不需要处理跨域。消息格式用 JSON简单直接调试的时候肉眼就能看懂。通信协议我设计得很简单就几种消息类型消息类型方向作用submit_taskOrb → Harness提交一个自然语言任务task_statusHarness → Orb回报任务进度排队/执行中/完成/失败task_resultHarness → Orb返回最终结果或错误信息cancel_taskOrb → Harness取消正在执行的任务ping/pong双向心跳检测确认对方还活着这个设计的好处是Orb 完全不需要知道 Harness 内部怎么执行任务它只负责“提交”和“展示结果”。Harness 也完全不需要知道 UI 长什么样它只管“收任务”和“报状态”。两边可以独立开发、独立升级。2.3 一键唤起的交互设计“一键唤起”这四个字说起来简单做起来要考虑的细节一大堆。首先是全局快捷键怎么注册。Qt 本身没有提供全局热键 API得用平台相关的方案Windows 上用RegisterHotKeyLinux 上用 X11 的XGrabKey或者 Wayland 下的 portal 接口。我封装了一层抽象让上层代码不用关心平台差异。快捷键我默认设的是CtrlShiftSpace这个组合在大多数系统上都不会和常用软件冲突。但我也留了配置文件用户可以自己改。这里有个坑有些桌面环境会抢占某些快捷键注册失败的时候要给出明确提示而不是默默失效。唤起之后的行为也值得说道。我的设计是按一下快捷键悬浮球从屏幕边缘滑出并展开成输入框再按一下收回成小球。如果输入框里已经有内容按 Esc 清空并收回。这个“展开-收回”的动画我用 QPropertyAnimation 做的200 毫秒的缓动手感很顺。别小看这个动画没有它的话界面切换会显得很生硬用久了会觉得烦躁。2.4 后台干活的实现思路“后台干活”是这个项目区别于普通悬浮球的核心。普通悬浮球点一下就是执行一个固定动作而 DeepSeek Orb 点一下是提交一个任务给 HarnessHarness 在后台异步执行执行完了再通知 Orb。这里的关键是任务队列和状态机。Harness 后端维护一个任务队列同一时间只执行一个任务避免多个任务同时操作文件系统导致冲突。每个任务有明确的状态pending、running、done、failed、cancelled。Orb 前端根据状态变化更新悬浮球的视觉反馈——执行中球会缓慢旋转完成了球会闪一下绿色失败了闪红色。任务执行过程中Harness 会定期把进度通过 socket 推给 Orb。比如“正在读取文件 3/10”、“正在执行命令”、“正在生成结果”。这些进度信息会显示在悬浮球展开后的面板里让用户知道它没卡死。这个反馈机制非常重要我一开始没做结果用户提交任务后不知道它在干嘛以为程序挂了反复点反而把队列塞满了。3. 核心细节拆解悬浮球 UI 与 Harness 调用的关键实现3.1 悬浮球的窗口属性配置悬浮球要“浮”在桌面上窗口属性必须配对。Qt 里核心是这几个 flagsetWindowFlags(Qt::FramelessWindowHint | // 无边框 Qt::WindowStaysOnTopHint | // 始终置顶 Qt::Tool | // 不在任务栏显示 Qt::NoDropShadowWindowHint); // 不要系统阴影 setAttribute(Qt::WA_TranslucentBackground); // 背景透明Qt::Tool这个 flag 很关键它让窗口不出现在任务栏和 AltTab 列表里。悬浮球是辅助工具不应该占用任务栏位置。WA_TranslucentBackground配合 QPainter 自己画圆形背景才能做出真正的圆形悬浮球而不是一个方形窗口里画个圆。置顶这块有个细节WindowStaysOnTopHint在某些全屏应用比如游戏、视频播放器下会失效这是系统层面的限制没法绕过。我的处理是检测到全屏应用时自动隐藏悬浮球退出全屏再显示。这个逻辑通过监听窗口焦点变化来实现。3.2 拖拽与边缘吸附悬浮球要能拖动但拖完之后要自动吸附到屏幕边缘这是用户预期。实现上重写mousePressEvent、mouseMoveEvent、mouseReleaseEvent三个事件。拖动过程中记录鼠标按下时的偏移量移动时用move()更新位置。释放时计算当前球心到屏幕左右边缘的距离哪个近就吸附到哪边。吸附动画同样用 QPropertyAnimation让球“滑”过去而不是“跳”过去。这里有个容易忽略的点多显示器。用户可能有两个甚至三个屏幕悬浮球要能跨屏拖动吸附时要判断当前在哪个屏幕内吸附到那个屏幕的边缘。我用QGuiApplication::screenAt()获取鼠标所在屏幕然后取那个屏幕的availableGeometry()来计算吸附位置。这个细节不做的话多屏用户会觉得很别扭。3.3 Harness 任务提交的封装Orb 前端提交任务时不是直接把用户输入的原话丢给 Harness而是要先做一层封装。因为用户输入的是自然语言比如“帮我把下载目录里的图片按日期整理一下”Harness 需要知道这是一个文件操作任务涉及哪个目录、什么类型的文件、按什么规则整理。我的做法是在 Orb 侧做一个轻量的意图预处理提取关键信息路径、文件类型、操作类型组装成一个结构化的任务描述再发给 Harness。Harness 侧收到结构化描述后再结合 skill 和插件的能力去执行。{ task_id: orb-20250101-001, intent: organize_files, params: { target_dir: ~/Downloads, file_type: image, rule: by_date }, raw_input: 帮我把下载目录里的图片按日期整理一下, timestamp: 1735689600 }为什么要保留raw_input因为有些复杂任务没法完全结构化Harness 侧可能需要原始文本来做更精细的理解。结构化字段是“快速通道”原始文本是“兜底方案”两者结合成功率最高。3.4 Skill 与插件的加载机制DeepSeek Harness 的能力扩展靠 skill 和插件。skill 可以理解成“技能包”一个 skill 就是一组相关的操作能力比如文件操作 skill、代码执行 skill、网络请求 skill。插件则是更底层的扩展可以 hook Harness 的执行流程。Orb 启动时会先检查 Harness 后端是否已经加载了必要的 skill。如果没有它会尝试自动加载。这里有个顺序问题必须先启动 Harness 后端并完成 skill 加载Orb 才能提交任务。所以我的启动脚本是先拉起 Harness等它发ready信号再拉起 Orb。skill 的加载路径我做成可配置的。默认从~/.deepseek-harness/skills/读取用户也可以指定其他目录。每个 skill 是一个独立的文件夹里面有manifest.json描述元信息有入口脚本定义具体能力。这种设计让 skill 可以独立分发、独立更新不用动 Harness 核心代码。注意skill 加载失败时Harness 不应该直接崩溃而应该记录错误、跳过这个 skill、继续加载其他的。我一开始没做容错结果一个 skill 的 manifest 写错了格式整个 Harness 起不来排查了半天。4. 实操过程从零把 DeepSeek Orb 跑起来4.1 环境准备与依赖安装先说环境。我主要在 LinuxUbuntu 22.04和 Windows 11 上测试macOS 也跑通了但没深度测试。基础依赖如下Qt 6.5 或以上Qt 5.15 也能用但 QML 部分要改CMake 3.20一个 C17 编译器GCC 11 / MSVC 2022 / Clang 14Python 3.10Harness 后端是 Python 写的DeepSeek Harness 本体从官方仓库拉取Linux 下装 Qt 最省事的方式是用系统包管理器sudo apt install qt6-base-dev qt6-declarative-dev qt6-tools-dev \ libqt6websockets6-dev cmake build-essentialWindows 下建议用 Qt 官方在线安装器勾选 MSVC 2022 64-bit 套件。装完之后把 Qt 的 bin 目录加到 PATH 里不然 CMake 找不到。Harness 本体我假设你已经装好了。如果还没装去官方仓库按 README 走一遍。装完之后确认harness --version能正常输出版本号。4.2 编译 Orb 前端克隆仓库之后编译流程很标准git clone https://github.com/yourname/deepseek-orb.git cd deepseek-orb mkdir build cd build cmake .. -DCMAKE_BUILD_TYPERelease cmake --build . -j$(nproc)编译产物是一个可执行文件deepseek-orb。第一次运行之前先检查配置文件config/orb.json{ hotkey: CtrlShiftSpace, harness_socket: /tmp/deepseek-harness.sock, ball_size: 56, edge_snap: true, auto_hide_fullscreen: true, theme: dark }harness_socket这个路径要和 Harness 后端配置的一致不然连不上。ball_size是悬浮球直径单位像素56 是我觉得比较舒服的大小你可以按自己屏幕分辨率调。4.3 启动 Harness 后端并加载 SkillHarness 后端的启动命令取决于你的安装方式。如果是 pip 装的deepseek-harness serve --socket /tmp/deepseek-harness.sock --skills ~/.deepseek-harness/skills/--socket指定 socket 路径要和 Orb 配置一致。--skills指定 skill 目录。启动之后你会看到日志输出确认它加载了哪些 skill、监听了哪个 socket。如果 skill 加载报权限错误比如 Windows 上常见的SetNamedSecurityInfoW failed那通常是 skill 目录的 ACL 有问题。解决办法是给当前用户对该目录的完全控制权限。Linux 下则是检查目录的 owner 和 mode确保当前用户有读写执行权限。4.4 联调提交第一个任务两边都起来之后按CtrlShiftSpace唤起悬浮球输入一个简单任务测试比如“列出当前目录下的所有文件”。正常情况下悬浮球会旋转几秒然后弹出结果面板显示文件列表。如果没反应按这个顺序排查确认 Harness 后端进程还活着ps aux | grep harness确认 socket 文件存在ls -l /tmp/deepseek-harness.sock看 Orb 的日志输出启动时加--verbose看 Harness 的日志输出我踩过最坑的一次是 socket 路径写错了Orb 一直连不上但没有任何提示就静静地待在那里。后来加了连接失败的重试和提示体验才好起来。4.5 打包与开机自启开发调试跑通之后就该考虑日常使用了。Linux 下做个 systemd user serviceWindows 下做个计划任务或者启动项。这样开机之后 Harness 和 Orb 自动起来你随时按快捷键就能用。Linux 的 service 文件大概长这样[Unit] DescriptionDeepSeek Harness Backend Afternetwork.target [Service] ExecStart/usr/local/bin/deepseek-harness serve --socket /tmp/deepseek-harness.sock Restarton-failure [Install] WantedBydefault.targetOrb 前端也可以做成 service但因为它有 UI更推荐放到桌面环境的自启动里。GNOME 下就是往~/.config/autostart/放一个.desktop文件。5. 常见问题与排查技巧实录5.1 悬浮球不显示或显示异常最常见的原因是透明背景没生效。检查两点一是WA_TranslucentBackground属性有没有设二是窗口管理器是否支持合成compositing。有些轻量级桌面环境默认关闭合成透明就会变成黑色。解决办法是开启合成或者退而求其次给悬浮球一个纯色背景。另一个原因是窗口被其他置顶窗口盖住了。WindowStaysOnTopHint不是绝对的两个都置顶的窗口之间还是有层级关系。如果发现悬浮球被盖住可以尝试周期性调用raise()但这会带来性能开销不建议频繁做。5.2 快捷键注册失败快捷键注册失败通常有两个原因一是组合键被系统或其他软件占用了二是权限不足。Windows 下RegisterHotKey失败会返回错误码可以查一下具体原因。Linux 下 X11 的XGrabKey如果被占用会收到BadAccess错误。我的建议是准备几个备选快捷键注册失败时自动尝试下一个并在日志里明确记录。用户也可以在配置文件里手动指定一个没被占用的组合。5.3 Harness 任务执行超时或卡死任务卡死的原因很多常见的有skill 内部死循环、外部命令等待输入、网络请求没有超时设置。我的处理是在 Harness 侧给每个任务加一个可配置的超时时间默认 300 秒。超时之后强制终止任务返回失败状态并记录日志。但强制终止有个风险如果任务正在写文件中途被杀可能导致文件损坏。所以对于文件写操作我建议 skill 内部实现原子写入——先写临时文件写完再重命名。这样即使中途被杀原文件也不会损坏。5.4 多屏环境下悬浮球位置错乱多屏环境下屏幕坐标是相对于整个虚拟桌面的不是相对于单个屏幕。如果你直接用绝对坐标悬浮球可能会跑到屏幕外面去。正确做法是用QScreen::availableGeometry()获取当前屏幕的可用区域所有位置计算都基于这个区域。还有一个坑不同屏幕的 DPI 可能不一样。Qt 6 默认开启了高 DPI 缩放但如果你手动设置了固定像素值在不同 DPI 的屏幕上大小会不一致。解决办法是用逻辑像素而不是物理像素或者监听screenChanged信号动态调整。5.5 常见问题速查表现象可能原因排查方向悬浮球不显示透明背景未生效 / 被置顶窗口盖住检查窗口 flag 和合成设置快捷键无响应组合键被占用 / 注册失败换组合键看日志错误码任务一直转圈Harness 未启动 / socket 连不上检查后端进程和 socket 文件任务执行报权限错误skill 目录 ACL 问题检查目录权限和 owner多屏位置错乱用了绝对坐标 / DPI 不一致改用 availableGeometry 和逻辑像素后台任务卡死skill 死循环 / 命令等待输入加超时检查 skill 实现5.6 几个我踩过的坑和对应技巧第一个坑是动画和拖拽冲突。我一开始在拖拽释放时启动吸附动画但如果用户快速连续拖拽上一个动画还没结束新的拖拽就开始了位置会乱。解决办法是在拖拽开始时先stop()掉正在运行的动画。第二个坑是socket 消息粘包。本地 socket 是流式的不保证一次read就能读到一条完整消息。我一开始没处理这个结果偶尔会解析 JSON 失败。后来加了一个简单的分帧协议每条消息前面加 4 字节的长度头读的时候先读长度再读内容。第三个坑是Harness 重启后 Orb 连不上。Harness 崩溃重启后socket 文件可能还在但连接已经断了。Orb 需要检测到连接断开后自动重连而不是一直用旧的连接。我加了一个心跳机制每隔 5 秒发一次 ping连续三次没收到 pong 就重连。第四个坑是中文输入法冲突。悬浮球展开成输入框后如果用户用中文输入法某些桌面环境下输入法候选框会跑到屏幕角落。这是因为输入框窗口的定位和输入法框架的交互有问题。解决办法是确保输入框窗口有正确的Qt::WA_InputMethodEnabled属性并且位置更新时通知输入法框架。6. 还能怎么扩展几个我打算继续做的方向这个项目目前已经能稳定日常使用了但我觉得还有不少可以打磨的地方。第一个方向是多任务并行。现在 Harness 后端是单任务队列一次只能跑一个任务。如果能让多个不冲突的任务并行执行效率会高很多。难点在于冲突检测——两个任务都要写同一个文件怎么办我打算做一个简单的资源锁机制任务提交时声明它需要哪些资源调度器根据资源占用情况决定是否并行。第二个方向是任务历史与回放。现在任务执行完结果看完就没了。如果能保存历史记录支持搜索和回放会很有用。特别是那些复杂的、多步骤的任务回放能帮用户理解 Harness 到底做了什么。这个功能对调试 skill 也很有帮助。第三个方向是更丰富的视觉反馈。现在悬浮球只有旋转、闪绿、闪红三种状态。我想加上进度环让用户一眼就能看出任务执行到哪一步了。还想加上音效提示任务完成时“叮”一声不用一直盯着屏幕看。第四个方向是移动端 companion。有时候我不在电脑前但想让 Harness 帮我跑个任务。如果能在手机上提交任务、查看结果会很方便。技术上就是做一个移动端 app通过局域网连接到桌面端的 Harness。这个涉及网络通信和安全认证得仔细设计。第五个方向是skill 市场。现在 skill 要手动安装、手动配置对普通用户门槛太高。如果能做一个 skill 市场用户点一下就能安装会自动处理依赖和配置那 Harness 的生态就能真正跑起来。这个工程量比较大但我觉得是值得做的。我个人在实际使用中最大的体会是工具的价值不在于功能多强而在于用起来有多顺手。DeepSeek Harness 本身能力很强但之前每次调用都要折腾一番导致我反而不太愿意用它。改成悬浮球之后调用成本降到几乎为零我用它的频率翻了不止一倍。这也让我重新思考了一个问题很多 AI 工具之所以没被用起来不是因为模型不够聪明而是因为交互摩擦太大。把摩擦降下去价值自然就出来了。最后分享一个小技巧如果你也在做类似的桌面常驻工具一定要把日志做好。悬浮球这种东西出问题的时候往往没有明显的报错界面用户只看到“没反应”。这时候日志就是唯一的线索。我的做法是 Orb 和 Harness 都输出结构化日志到文件出问题时让用户把日志发过来基本一眼就能定位。这个习惯帮我省了无数排查时间。