DeepSeek Harness Desktop

中文 | English

DeepSeek Harness 的桌面客户端(Electron + TypeScript)。

许可证与使用条款

本项目遵循自定义许可协议(见 LICENSE),核心条款:

• 不得商用:任何衍生项目不得用于商业用途(DeepSeek 官方、本项目作者本人、有关项目贡献者及作者书面授权的个人/组织除外)。
• 必须开源:任何衍生项目必须公开源代码,并同样遵守本协议。
• 更宽松授权:作者保留对特定个人或组织授予更宽松协议条款的权利(包括商业使用许可),须经作者明确书面授权;未获书面授权者一律适用本协议默认条款。
• 第三方依赖组件(DeepSeek Harness、@tencent-connect/qqbot-nodejs、Electron 等)遵循各自许可证,详见下文「参考与致谢」。

隐私说明

• 发布包(安装包 exe / zip)只包含应用代码与运行库,不包含任何本地配置、壁纸、访问令牌、API 密钥、会话数据或日志。
• 用户的壁纸、令牌与配置保存在系统用户目录(%APPDATA%/DeepSeek Harness Desktop),永远不会进入安装包或提交到仓库。
• 安装程序不会删除用户数据:卸载时保留 %APPDATA% 下的配置与壁纸(deleteAppDataOnUninstall = false)。
• 若从源码自行构建,构建产物同样不涉及上述用户数据。

下载与安装

从 GitHub Releases 下载,三种形态任选: | 形态 | 文件 | 说明 | |---|---|---| | 安装版(推荐) | DeepSeek-Harness-Desktop-Setup-*.exe | NSIS 安装程序,双击安装,自动创建开始菜单与桌面快捷方式,可选安装目录 | | 便携版 | DeepSeek.Harness.Desktop-*.win.zip | 解压即用,免安装,适合 U 盘携带 | | 源码版 | 克隆仓库 npm install && npm start | 自行构建 |

安装版卸载时保留用户配置与壁纸(不会删除 %APPDATA% 数据);如需彻底清理请手动删除 %APPDATA%/DeepSeek Harness Desktop。

系统要求:Windows x64、Node.js 18+(仅在桌面端需要托管拉起 harness 时使用)。 提示:先运行 npx @deepseek-ai/dsh web 并配置好模型密钥,再打开桌面端,体验最佳。

📖 完整安装、配置、手机端与 QQ 机器人使用步骤见 实操指南(汉英双语)。

参考与致谢

本项目在设计与实现中参考、依赖并致谢以下开源项目的贡献:

同时感谢 DeepSeek Harness 社区与本项目测试过程中提供反馈的各位使用者。

• 内嵌 Web UI:原生控制条 + 内嵌完整 harness Web UI(会话、工具、插件全功能)。
• AI 屏保(替换系统屏保):空闲 N 分钟自动全屏显示 agent 实时工作画面(思考过程、文本流、工具调用),移动鼠标或按键立即退出;也可注册为 Windows 系统屏保。
• 各种模型选择:快捷切换默认模型(DeepSeek 官方、OpenAI、Anthropic 及 37+ 目录 Provider),添加自定义 OpenAI 兼容网关(公司网关、Ollama 本地等),密钥安全写入 credentials 存储。
• harness 托管:自动探测已运行的 dsh web,没有则自动拉起(默认 npx @deepseek-ai/dsh web),崩溃自动重启。
• 系统托盘常驻:开机自启、一键启动屏保、快速打开 Web UI。

快速开始

npm install
npm start        # 构建并启动桌面端

首次启动会自动探测 http://127.0.0.1:3080:已有 harness 则直接接入;没有则自动执行 npx --yes @deepseek-ai/dsh web --port 3080 拉起(需要 Node.js 18+)。

提示:先运行 npx @deepseek-ai/dsh web 并配置好模型密钥,再打开桌面端,体验最佳。

功能说明

模型切换

顶栏的「默认模型」下拉框列出当前已配置的全部 Provider 与模型:

• 选择后通过 session.selectModel 写入,harness 会同时持久化为新会话的默认模型,热生效、无需重启。
• 「设置 → 添加自定义 Provider」可添加 OpenAI 兼容网关(预设:DeepSeek 官方 / OpenAI / Ollama 本地 / 自定义),支持「从网关拉取模型」自动发现模型列表;API Key 通过 credentials.set 安全写入,不会明文落盘到配置。
• 更完整的模型管理(密钥配置、目录 Provider、推理参数)在嵌入式 Web UI 的「设置 → Models」页面。

AI 屏保

「设置 → AI 屏保」:

屏保画面实时渲染 agent 的思考、输出文本与工具调用卡片(流式渲染为增量追加,不因长输出卡顿)。退出方式:点击、按键、滚轮、触摸均可立即退出;鼠标移动不触发退出(避免鼠标抖动导致屏保闪退)。退出后任务默认保留在后台继续运行,下次进入屏保会「继续上次任务」;关闭「保留任务」则在每次进入时重启新任务。任务会话自动命名「AI 屏保任务 HH:MM」,便于在 Web UI 中识别。

防循环弹出:系统屏保拉起(/s)与空闲检测自动激活都受 5 分钟退出冷却约束——用户点击退出后,5 分钟内不会被系统/空闲检测再次拉起,避免"关了又弹"。用户主动点击「AI 屏保」按钮不受此限制。

注册为 Windows 系统屏保:点击「注册为系统屏保」后,Windows 的锁屏/超时机制会用 /s 参数拉起本应用直接进入全屏模式(注册表 HKCU\Control Panel\Desktop\SCRNSAVE.EXE,无需管理员权限;注册前自动备份原设置,取消时恢复)。

体验提示:AI 屏保是「观看模式」——它全屏展示 agent 正在做什么,而不是接管你的鼠标键盘。空闲时让 agent 干活前,先想清楚任务是否真的需要跑(模型调用消耗 token、工具调用消耗 CPU)。

Harness 服务

• auto(默认):先探测已运行实例(接入 3080 或自定义端口),没有则托管启动。
• external:仅连接外部地址(如局域网内的另一台机器)。
• managed:始终由桌面端托管启动,可自定义启动命令(如指向本地仓库的 pnpm dsh web --port {port})。

外观 · 壁纸

「设置 → 外观」可分别自定义:

• 主窗口壁纸:顶栏与设置抽屉呈现毛玻璃透出效果(不影响内嵌 Web UI 的显示区域)。
• 屏保壁纸:全屏背景图,带可调遮罩(0.1~0.9)保证文字可读。
• 图片会复制到应用数据目录(%APPDATA%/DeepSeek Harness Desktop/wallpapers),原图移动/删除不影响;支持 png/jpg/jpeg/gif/webp/bmp。

手机远程控制(PWA)

「设置 → 远程访问」启用后,桌面端开一个局域网网关(默认端口 3082,Bearer token 认证):

1. 手机与电脑连同一 WiFi,用手机扫设置面板中的二维码(或浏览器访问 http://<电脑IP>:3082)
2. PWA 自动填入地址与令牌并连接,可添加到主屏幕当作 App 使用

手机端功能:

• 会话:列表、历史、实时流式收发消息、停止任务
• 任务:输入描述 + 选择工作区 + 选择模型,一键运行并实时查看
• 工作区:列表、新建、按工作区执行任务
• 安全:Bearer token 认证 + RPC 白名单(手机端不能改配置/读密钥/操作文件系统),仅局域网可达

QQ 机器人远程控制(可选)

「设置 → QQ 机器人」填入在 QQ 开放平台 注册机器人得到的 AppID/AppSecret 即启用(留空自动禁用),也可设置默认工作区/目录(任务命令未指定时自动使用)。在 QQ 私聊机器人发送指令(发送任意无法识别的消息,机器人会自动回复完整指令集与示例):

典型流程:工作区 查看列表 → 进入 qqbot → 连续对话 → 退出。

基于 @tencent-connect/qqbot-nodejs(WebSocket 长连接),协议参考 QQ 开放平台 API v2 文档(消息收发/消息类型/事件订阅)与 Agent QQBot 接入指南。QQ 官方机器人为被动回复模式:只能在你发消息后回复,不能主动推送;长回复自动分段。

开发

npm run build    # tsc 编译 main/preload/renderer 到 dist/
npm start        # 构建 + electron .
npm run smoke    # 冒烟测试:验证 RPC 客户端与模型目录(需 harness 运行中)
npm run pack     # 打包 Windows portable 单文件 exe(electron-builder)

调试开关:

• --remote-debugging-port=9222 启动时启用 CDP,可用 node scripts/cdp-eval.mjs '<表达式>' 检查页面状态。
• --ss-debug 启动时,屏保窗口保持打开(禁用空闲退出),便于调试屏保画面。
• node scripts/mux-test.mjs <baseUrl> 端到端管线测试:设置默认模型 → 建会话 → 发提示 → 订阅事件流(会消耗少量模型调用)。

结构

src/main/          主进程
  index.ts         入口(单实例锁、/s 屏保参数、mux 事件桥)
  harness.ts       harness 进程托管(探测/拉起/健康检查/崩溃重启)
  client.ts        HTTP RPC 客户端(POST /api/<method> + SSE events.mux)
  models.ts        模型目录、默认模型切换、自定义 Provider 向导
  screensaver.ts   AI 屏保(空闲检测、全屏窗口、任务编排、系统屏保注册)
  tray.ts          系统托盘
src/renderer/      渲染进程(经典脚本,无打包器)
  index.html       主窗口(控制条 + webview)
  screensaver.html 全屏屏保(实时 agent 画面)
scripts/           冒烟与端到端测试脚本

与 harness 的通信协议

桌面端直接实现 deepseek-harness 的 HTTP RPC 协议(dsh-host-apiproxy):

• 一元调用:POST /api/<method>,body 为 {type:'client-request', rpcId, method, payload},响应 {type:'server-response', rpcId, result};回环地址免令牌。
• 事件流:GET /api/events.mux(SSE),推送 session/event 等帧,屏保页面据此实时渲染。
• 关键方法:session.list/create/prompt/cancel/selectModel、host.describe、llm.providers/models/discoverModels、settings.update/mutate、credentials.set。

协议细节随 harness 演进可能变化;桌面端使用的方法均来自当前 0.1.0-rc.x 的 packages/host/apiproxy。

已知限制

• 屏保实时画面为「观看视图」:交互(输入、审批)请回到主窗口的 Web UI 完成;agent 遇到需要确认的问题会等待,会话在 Web UI 中可见。
• 系统屏保注册仅支持 Windows(注册表方案,注册前自动备份原设置,取消时恢复);macOS/Linux 可用内置空闲检测模式。
• 事件流传输自动协商:旧版 harness 只接受 WebSocket(HTTP 返回 426),新版额外支持 SSE;两者都兼容。
• 屏保窗口内禁用了系统休眠时的自动唤醒逻辑(跟随系统屏保行为)。