DeepSeek Harness 本地桌面版（Deepseek-Harness-Local-UI）

免命令行 · 一键管理 DeepSeek Harness 本地服务 · 两种方案任选

基于 DeepSeek Harness（MIT 协议）的本地增强发行版：内置服务管家（启动 / 停止 / 重启 / 状态）、一键打开 GUI，并附带修改版 Web GUI 增强（对话大纲导航、回退到这一步、重新生成）。

本项目是 DeepSeek Harness 的二次开发（基于官方提交 f98a57e 修改），全部代码依据 MIT 开源协议发布。上游版权归 DeepSeek 所有；代码构成、占比与改动声明详见 NOTICE.md。

🖼 效果预览

对话大纲导航栏：右侧常驻目录，完整加载全部对话轮次，点击任意轮次即可定位。

📦 选择你的版本（先看这里）

本仓库提供两套独立的桌面方案，按需下载，互不影响：

💡 快速建议：想省事 → 选 Python 版（源码几 MB，自己编译无拦截）；想免安装环境直接跑 → 选 Electron 版（下载 85MB EXE 双击即用，首次运行点「更多信息 → 仍要运行」即可）。

📖 目录

• 📦 选择你的版本（先看这里）
• 为什么做这个
• 功能特性
• 系统要求
• 快速开始（Python 版）
• Electron 版使用指南
• 修改版 Web GUI 增强
• 从源码构建（开发者）
• 项目结构
• 代码构成与占比
• 常见问题 FAQ
• 安全设计
• 开源许可与法律声明
• 致谢

🤔 为什么做这个

DeepSeek Harness 的 Web GUI 在浏览器中使用，对日常使用有几个不便：

• 浏览器没有右键拖拽前进/后退手势，侧边栏开关不够顺手；
• 浏览器自带快捷键（Ctrl+T / Ctrl+W / Ctrl+L 等）会抢走输入焦点；
• 启动 / 停止 / 重启后端服务需要在命令行里敲命令；
• 长对话缺少全局大纲导航，翻历史只能慢慢滚动。

这个发行版把这些痛点一次性解决：

1. 服务管家：点按钮启动 / 停止 / 重启 DSH 服务，实时显示状态，全程不用命令行；
2. 对话大纲：右侧常驻目录，点击任意轮次直接定位，长对话不再迷路；
3. 多种打开方式：Python 启动器（推荐）→ 自动打开系统浏览器；WebView 窗口版 → 原生窗口体验；Electron 桌面壳（可选）→ 手势 / 托盘 / 快捷键屏蔽。

✨ 功能特性

🐍 Python 完整版桌面应用（推荐 ⭐，本仓库原创）

Python 主程序 + 原生窗口加载完整 DSH Web GUI（desktop-py/dsh_app.py）：

• UI 效果 = 完整 Web GUI：三栏布局（工作区 / 聊天 / 对话大纲导航）、Markdown 渲染、代码高亮、工具调用卡片、流式打字机回复——与浏览器体验完全一致；
• 对话大纲导航：完整加载全部轮次（首句摘要），点击定位 + 高亮，可收起；
• 回退到这一步 / 重新生成：用户消息悬浮按钮，一键 fork 分支；
• 服务管家（Python 侧）：自动检测 harness 并启动服务，托盘菜单可 启动 / 停止 / 退出；
• 系统托盘常驻：关窗不退出（隐藏到托盘），服务保持运行；
• 自编译 EXE：build_exe.bat 选 3，在自己电脑上编译为独立 EXE，无 SmartScreen 拦截。

Python 启动器（轻量版）

• 纯 Python 实现：仅用标准库 + tkinter，零第三方依赖，安装 Python 即可运行；
• 一键服务管理：启动 / 停止 / 重启 DSH 服务，实时状态显示（运行中 / 已停止）；
• 一键打开界面：自动打开系统默认浏览器访问 Web GUI；
• 自动检测 DSH 目录：DSH_HOME 环境变量 → 同级 harness/ → 常见位置 → 手动选择（纯 UI）；
• 设置记忆（记住目录与端口），界面中文，简单直观。

WebView 窗口版（可选）

• 基于 pywebview（系统 WebView2），把 DSH 的 Web GUI 装进原生窗口；
• 同样支持自编译 EXE；
• 需要 pip install pywebview。

Electron 桌面壳（可选，源码保留）

• 原生窗口 + 右键手势 + 快捷键屏蔽 + 文件拖放 + 托盘常驻；
• 源码在 src/，需要 Node.js 环境自行构建；
• 注意：对外分发 EXE 需要代码签名证书，否则 SmartScreen 会提示（见 FAQ）。

修改版 Web GUI 增强

• 对话大纲导航栏：右侧常驻目录，完整加载全部对话轮次（每轮显示首句摘要），点击定位 + 高亮，支持收起；
• 回退到这一步：用户消息悬浮按钮，在该轮之前创建分支（fork）并打开子会话；
• 重新生成：用户消息悬浮按钮，在该轮之前创建分支并自动重发原消息；
• 大纲服务端接口：新增 session.outline RPC，返回整份会话日志的逐轮摘要。

完整保留上游能力

全部 DeepSeek Harness 插件体系原样保留：工具（bash / 文件 / 网页搜索 / 工作流 / 子代理等）、会话持久化（JSONL / SQLite）、技能系统、计划模式、审批与交互、Python SDK 等。

💻 系统要求

🐍 Python 版

🖥 Electron 版（Release v0.1.3）

注：两种方案共用同一个 DSH 后端（harness/），区别只在桌面壳实现（Python 小 / Electron 大）。

🚀 快速开始（🐍 Python 版）

Python 版有三种用法任选：A. 完整版桌面应用（推荐 ⭐，原生窗口加载完整 Web GUI + 托盘）→ B. 轻量启动器（浏览器打开）→ C. 自编译 EXE（不装 Python 环境时用）。 需要 Electron 版？直接下载 Release v0.1.3 的现成 EXE，见 Electron 版使用指南。

第 0 步：准备环境（Python 版需要，只需做一次）

0.1 安装 Node.js

1. 打开 https://nodejs.org 下载 LTS 版本（≥ 22.19）的 Windows 安装包；
2. 双击安装，一路下一步（务必勾选 “Add to PATH”）；
3. 安装完成后打开 PowerShell / CMD 验证：

node --version   # 应输出 v22.x 或更高

0.2 安装 pnpm

npm install -g pnpm
pnpm --version   # 应输出 9.x 或更高

0.3 安装依赖并构建（只需一次，约 5-20 分钟）必须完整执行，否则服务无法启动

# 进入 harness 目录（DeepSeek Harness 官方源码修改版）
cd harness

# 1) 安装依赖
pnpm install

# 2) 构建前端与各包（官方标准流程，生成 Web GUI 所需资源）
pnpm run build

cd ..

⚠️ 这两步决定成败（官方流程为 pnpm install → pnpm run build → pnpm dsh web）：

• pnpm install：安装 node_modules（含 tsx 等运行时依赖）；
• pnpm run build：生成前端 bundle 与各包产物（lib/client.js、apps/web/dist），缺了它 GUI 无法渲染；
• 国内网络慢可先执行：pnpm config set registry https://registry.npmmirror.com 再重试。

验证依赖与构建产物就绪（三项都应看到 True / 目录存在）：

Test-Path harness\node_modules\tsx    # 依赖：返回 True
Test-Path harness\apps\web\dist      # 构建：返回 True
Get-ChildItem harness\packages\client\ui-conversation\lib\client.js  # 前端 bundle 存在

0.4 配置 DeepSeek API 密钥

在 harness/ 目录下创建 .env 文件，内容：

DEEPSEEK_API_KEY=sk-你的密钥

密钥仅保存在本机，不会上传。

方式 A：Python 完整版桌面应用（推荐 ⭐）

原生窗口加载完整版 DSH Web GUI（含我们修改版的全部功能：对话大纲导航、回退到这一步、重新生成、工具卡片、流式回复等），Python 负责服务管理与系统托盘。UI 效果与原版 Web GUI 完全一致。

前置：Python ≥ 3.10（下载 https://www.python.org/downloads/ ，安装时勾选 “Add to PATH”）。

# 安装依赖（只需一次）
pip install pywebview pystray pillow

# 运行完整版桌面应用
python desktop-py/dsh_app.py

启动后自动检测 harness/ 并启动服务，然后打开原生窗口：

1. 窗口内：完整 DSH Web GUI（三栏布局：工作区 / 聊天 / 对话大纲导航，全部功能可用）；
2. 系统托盘：小图标常驻，右键菜单可「显示窗口 / 启动服务 / 停止服务 / 退出」；
3. 关窗不退出：点关闭按钮只是隐藏到托盘，服务保持运行；托盘「退出」才真正结束。

💡 找不到 harness/？设置环境变量 DSH_HOME 指向源码目录，或把仓库解压后保持 harness/ 与 desktop-py/ 同级。

方式 B：Python 轻量启动器

只想在浏览器里用 DSH？用零依赖的轻量启动器：

python desktop-py/dsh_launcher.py
# 点「🚀 启动服务」→「🌐 打开界面」，浏览器自动打开

方式 C：自编译 EXE（不想装 Python 环境时）

在自己电脑上把启动器编译成独立 EXE，自己编译的 EXE 不会被 Windows SmartScreen 拦截：

cd desktop-py
build_exe.bat
# 按提示输入：
#   1 - 纯 Python 启动器（tkinter，最小）
#   2 - WebView 窗口版
#   3 - 全量 UI 桌面版（推荐，约 48MB）
# 编译产物：desktop-py/dist/ 目录下

编译完成后，双击 dist/DSH-Desktop.exe（模式 3）即可使用（首次编译约 1-2 分钟）。

📦 若您不想自己编译、想直接下载现成 EXE，请前往仓库 Releases 页面（注意：下载的未签名 EXE 可能触发 SmartScreen，见 FAQ）。

方式 D：Electron 桌面壳（体验最完整，需要 Node.js）

Electron 版提供原生窗口体验：右键手势、快捷键屏蔽、文件拖放、托盘常驻、模型/密钥管理窗口。

# 安装依赖（只需一次）
npm install

# 编译 TypeScript + 复制静态资源
npm run build

# 启动桌面壳
npm run start
# 或直接：npx electron .

启动后：欢迎页点「🚀 启动服务」→ 自动进入聊天界面。

打包 Electron EXE（可选）

npx electron-builder --win --publish never
# 产物：release/DSH-Desktop-<版本>-portable.exe（便携版）和 -setup.exe（安装版）

🔐 重要说明：Electron EXE 若对外分发（下载给别人），需要代码签名证书（商业 CA 如 DigiCert / Sectigo，个人可申请 OV 证书）才能消除 SmartScreen「无法验证发布者」提示；仅自己电脑使用则不受影响。个人自用建议直接采用方式 A 或 B。

🐍 Python 启动器使用指南

cd desktop-py
python dsh_launcher.py

服务状态实时显示（● 运行中 / ○ 已停止），日志区记录每一步操作结果。

🔨 自编译 EXE（可选）

不想装 Python？可以在自己电脑上把启动器编译成独立 EXE：

cd desktop-py
build_exe.bat          # 按提示选择版本（1=纯 Python，2=WebView）
# 产物：desktop-py/dist/DSH-Desktop-Python.exe

为什么自己编译不会被拦截？ SmartScreen 拦截的是“从网络下载 + 未签名”的组合。自己编译的 EXE 没有“来自网络”标记（Mark-of-the-Web），因此不会出现“无法验证发布者”的警告，双击即用。

🌐 WebView 窗口版（可选）

用 pywebview（基于系统 WebView2）把 Web GUI 装进原生窗口，比纯 Python 启动器多一层桌面壳体验：

# 1. 安装依赖（只需一次）
pip install pywebview

# 2. 运行窗口版
cd desktop-py
python dsh_webview.py

启动后会自动检测 DSH 目录并尝试启动服务，然后打开原生窗口加载 Web GUI。

也可以随 build_exe.bat 选 2 编译为 EXE（已包含 pywebview 打包配置）。

🖥 Electron 桌面壳（可选 · 完整保留）

📥 直接下载（免环境，双击即用）： Release v0.1.3 → DSH-Desktop-0.1.3-portable.exe（便携版，约 85MB） 首次运行若提示「无法验证发布者」，点「更多信息 → 仍要运行」即可（未签名 EXE 的正常提示，不影响使用）。

为什么有 Electron 版？ 它提供比 Python 版更完整的桌面交互：右键手势（按住右键左右拖动收起/展开侧边栏）、快捷键屏蔽（Ctrl+T/W 等不干扰输入）、文件拖放获得真实路径、托盘常驻、内置模型/API 密钥管理窗口。代价是体积大（约 85MB）且分发需处理签名问题。

与 Python 版的区别：Python 版（方案 A）体积小、可自编译无拦截；Electron 版（本方案）体积大但交互最完整。两者共用同一个修改版 Web GUI（大纲导航、回退/重新生成等功能都有），按需选择即可。

功能对照

安装与运行

# 1. 安装依赖（只需一次）
npm install

# 2. 编译 TypeScript + 复制静态资源
npm run build

# 3. 运行单元测试（可选）
npm test

# 4. 启动桌面壳
npm run start
# 或直接：npx electron .

打包分发 EXE

npx electron-builder --win --publish never
# 产物：
#   release/DSH-Desktop-<版本>-portable.exe  便携版（免安装，双击即用）
#   release/DSH-Desktop-<版本>-setup.exe     安装版（开始菜单快捷方式 + 卸载器）

国内网络打包建议先设置镜像环境变量： ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ ELECTRON_BUILDER_BINARIES_MIRROR=https://npmmirror.com/mirrors/electron-builder-binaries/

Electron 版使用指南

• 欢迎页与服务管理：🚀 启动服务 / ⏹ 停止服务 / 🔄 重启服务 / 更改 DSH 安装位置，状态实时显示；
• 手势：按住鼠标右键左右拖动 = 收起/展开侧边栏；Alt+← / Alt+→ 同效；
• 快捷键：Ctrl+T / W / N / H / L / Tab / 数字键 已被屏蔽，不会干扰输入；
• 关闭窗口：可选「同时停止服务并退出」「保持服务后台运行并退出（托盘驻留）」「取消」；
• 模型/API 密钥：菜单 → 模型/API 密钥管理（读取环境变量，应用不存储）。

⚠️ 分发注意事项

Electron EXE 若仅自己电脑使用（或通过 npm run start 运行），不会遇到拦截。若要把 EXE 下载分发给他人，Windows SmartScreen 会提示「无法验证发布者」，需要：

1. 商业代码签名证书（推荐，个人可申请 OV 证书：DigiCert / Sectigo / Certum，年费约 ¥800–2000）；
2. 或让用户右键 EXE → 属性 → 勾选「解除锁定」；
3. 或提示用户点击「更多信息」→「仍要运行」。

💡 个人自用建议：直接使用 Python 启动器（方式 A）或自编译 EXE（方式 B），无需处理签名问题。

🔍 修改版 Web GUI 增强

对话大纲导航栏

• 位于聊天区右侧，与左侧工作区 / 中间聊天区构成三栏布局，各自独立滚动；
• 完整加载全部对话轮次（不依赖窗口分页），每轮显示首句摘要；
• 点击任意轮次 → 自动滚动定位到对应消息，并高亮闪烁提示；
• 正在进行的轮次显示「生成中…」，仅有工具调用的轮次显示「工具调用」，无回复的轮次显示「无回复」；
• 窗口过窄（< 760px）时自动收起为窄条；也可以点「收起目录栏」手动收起。

回退到这一步 / 重新生成

• 鼠标悬浮到任意用户消息上，出现两个按钮：
  • 「回退到这一步」：在该轮之前创建分支（fork），打开子会话，保留此前的全部上下文；
  • 「重新生成」：创建分支后自动重发该条消息，直接得到新回复；
• 子会话标题自动递增（如「计划（2）」），方便区分。

🛠 从源码构建（开发者）

DSH 源码（harness/）

完整保留官方开发流程：pnpm install → pnpm run test / typecheck / build 等，详见 harness/README.md。

Python 客户端

cd desktop-py
pip install pywebview        # 全量 UI 版需要（仅一次）
python dsh_app.py           # 全量 UI 桌面版（推荐）
python dsh_launcher.py      # 轻量启动器（零依赖）
python -m py_compile dsh_app.py dsh_api.py dsh_launcher.py   # 语法检查
build_exe.bat              # 编译为 EXE（1=轻量 / 2=WebView / 3=全量 UI）

📁 项目结构

Deepseek-Harness-Local-UI/
├── desktop-py/             # Python 客户端（推荐）
│   ├── dsh_app.py          # ⭐ 全量 UI 桌面版（自绘聊天 + 大纲 + 服务管家）
│   ├── dsh_api.py          # DSH 后端 HTTP/SSE API 客户端
│   ├── dsh_ui/             # 自绘界面（index.html / style.css / app.js）
│   ├── dsh_launcher.py     # 轻量启动器（tkinter，零依赖）
│   ├── dsh_webview.py      # WebView 窗口版（pywebview，可选）
│   ├── build_exe.bat       # 自编译 EXE 脚本（PyInstaller，三种模式）
│   └── requirements.txt    # pywebview 等依赖
├── src/                    # Electron 桌面壳源码（可选方案）
├── scripts/                # Electron 构建辅助脚本
├── tests/                  # Electron 单元测试
├── harness/                # DeepSeek Harness 官方源码（修改版，MIT）
│   ├── packages/           # 全部上游插件包
│   ├── apps/               # CLI / Web 应用
│   └── LICENSE             # 上游 MIT 许可证（原样保留）
├── LICENSE                 # 本仓库 MIT 许可证（DeepSeek + 修改者）
├── NOTICE.md               # 代码占比 / 改动声明 / 法律说明
└── README.md               # 本文件

📊 代码构成与占比

详细的改动清单与声明见 NOTICE.md。

❓ 常见问题 FAQ

Q：双击 Electron EXE 时 Windows 提示「无法验证发布者 / 已保护你的电脑」？ A：这是 SmartScreen 对“从网络下载的未签名 EXE”的标准拦截。建议改用 Python 启动器 + 自编译（desktop-py/build_exe.bat）——自己编译的 EXE 不会触发该提示。若必须分发 Electron EXE，请申请商业代码签名证书（个人可申请 OV 证书，如 DigiCert / Sectigo / Certum）。

Q：点「启动服务」提示「harness 依赖未安装（缺少 tsx）」？ A：说明 harness/ 目录的依赖没装成功。请打开命令行执行：

cd harness
pnpm install

国内网络慢可先 pnpm config set registry https://registry.npmmirror.com 再执行。完成后用 Test-Path harness\node_modules\tsx 验证（返回 True 即可）。

Q：Python 启动器需要装什么依赖？ A：纯 Python 版零依赖（标准库 + tkinter，Python 自带）。只有 WebView 窗口版需要 pip install pywebview。

Q：找不到 DSH 安装目录？ A：点「更改 DSH 目录…」选择包含 apps/cli/src/bin.ts 的 harness/ 目录；也可以设置环境变量 DSH_HOME。

Q：启动服务失败 / 端口被占用？ A：启动器会检测端口占用；点「重启服务」会终止占用端口的进程并重新启动。

Q：服务停了之后，我的对话数据会丢吗？ A：不会。对话数据持久化在 DSH 的会话存储中，服务重启后历史完整保留。

Q：需要联网才能用吗？ A：需要。聊天依赖 DeepSeek API（需要 API Key），但所有服务都在本机运行，您的对话内容不会上传到除 DeepSeek API 以外的任何地方。

Q：启动器会存我的 API 密钥吗？ A：不存。密钥只读取系统环境变量 / .env，启动器自身不存储、不上传。

Q：这个项目和 DeepSeek 官方是什么关系？ A：没有任何隶属 / 背书关系。这是基于官方开源代码（MIT）的个人二次开发发行版。

🔒 安全设计

• 服务仅绑定本机：--host 127.0.0.1，不对外网开放；
• 不存储凭证：API 密钥只读环境变量 / .env；
• 停止即杀进程树：停止服务时整棵进程树终止，不留孤儿进程；
• Electron 壳额外防护：URL 白名单、渲染进程沙箱、权限拒绝（见 src/ 源码）。

📜 开源许可与法律声明

• 本项目遵循 MIT License，完整文本见 LICENSE；
• 上游版权：Copyright (c) 2026 DeepSeek —— 见 harness/LICENSE（原样保留，未修改）；
• 修改者：Astra-Ursae-Majoris（版权声明见根 LICENSE）；
• 代码占比与改动声明：见 NOTICE.md；
• 本项目与 DeepSeek 公司及其关联方无任何隶属、背书或合作关系；「DeepSeek」等商标归各自权利人所有，此处仅为指明上游来源；
• 按 MIT 协议，本软件按「AS IS」提供，不附带任何明示或默示担保；作者与版权持有人不对任何索赔、损害或其他责任负责；
• 再分发时请保留本仓库 LICENSE、NOTICE.md 与 harness/LICENSE。

🙏 致谢

• DeepSeek Harness —— 上游项目（MIT License）；
• Electron —— 可选桌面壳的运行时；
• pywebview —— 可选 WebView 窗口库；
• Cordis —— 上游所用的插件框架。