DeepSeek dsh 桌面应用

将 DeepSeek dsh（DeepSeek Agent Harness，本地运行的 AI 智能体工作台）的 Web 版封装为 Windows 原生桌面应用。

你不再需要打开终端敲 npx @deepseek-ai/dsh web，双击桌面图标即可进入 dsh，像使用普通软件一样使用 DeepSeek 的本地 AI 智能体环境。

---

软件介绍

这是什么

• DeepSeek dsh 是 DeepSeek 推出的本地 AI 智能体开发环境：一个运行在 http://127.0.0.1:3080 的 Web 服务，提供与 AI 智能体对话、调用工具（文件读写、终端、代码执行、网页检索等）、多智能体编排、技能（Skills）与工作流（Workflow）等能力。
• 本项目 是一个「封装壳」：用 Electron 创建一个原生 Windows 窗口，在后台自动启动内置的 dsh 服务，把 Web 界面"装进"桌面窗口里。dsh 及其依赖完整内置，用户机器无需安装 Node.js，装完即用。

功能特性

特性	说明
🖥️ 原生桌面窗口	Electron 内置浏览器窗口，非"启动器"，关窗即退出
📦 完全独立	dsh 运行时、依赖、Node.js（真实 node.exe）全部随安装包分发
⚡ 即点即用	安装后双击图标，自动启动 dsh 服务并加载界面，无需命令行
🔁 端口复用	若 3080 端口已有 dsh 服务在运行，直接连接，不重复启动
🛡️ 安全默认	窗口只允许访问 dsh 本机地址，拒绝外部导航与新窗口
🪟 单实例	重复启动只会聚焦已有窗口，不会开第二个实例
🧯 错误可见	dsh 启动失败时窗口内展示错误详情，支持一键重试
📋 日志记录	运行日志写入 %APPDATA%/dsh-desktop/dsh.log，便于排查

系统要求

• 操作系统：Windows 10 / 11（64 位，x64）
• 内存：建议 4 GB 及以上（dsh 服务与 Electron 窗口合计）
• 磁盘：安装包约 160 MB，安装后约 500 MB
• 网络：首次使用需要联网（dsh 需要访问 DeepSeek API 等远端服务）；离线安装不受影响

---

快速开始

方式一：直接安装（推荐）

1. 前往本仓库 Releases 页面，下载最新的 DeepSeek dsh Setup <版本>.exe 安装包；
2. 双击运行安装程序（NSIS 安装器，可选择安装目录、创建桌面/开始菜单快捷方式）；
3. 安装完成后，双击 DeepSeek dsh 图标启动；
4. 首次启动会自动拉起内置服务（约几秒），随后进入 dsh 界面。

如果杀毒软件弹出提示，请选择「允许」。详见文末常见问题。

方式二：从源码构建

需要本机安装 Node.js（≥ 22，Windows x64）与 Git。

# 1. 克隆仓库
git clone https://github.com/<your-username>/dsh-desktop.git
cd dsh-desktop

# 2. 安装依赖（dsh 及全部插件）
npm install

# 3. 准备打包运行时 node.exe（打包必需，已 gitignore）
#    从 Node.js 安装目录（或官方 Windows x64 压缩包）复制 node.exe 到项目根目录：
copy "C:\Program Files\nodejs\node.exe" .\node.exe

# 4. 构建 NSIS 安装包，产物位于 dist/
npm run dist

生成的安装包位于 dist/DeepSeek dsh Setup <版本>.exe。

为什么需要 node.exe？ dsh 的原生模块（koffi 等）按系统 Node.js 的 ABI 编译，与 Electron 内置的 Node 不兼容（会导致目录选择器等原生功能崩溃），因此应用打包了一个真实的 node.exe 来运行 dsh 服务。该文件约 90 MB，属于构建期资源，不纳入版本库。

---

使用说明

启动与退出

• 启动：双击桌面快捷方式「DeepSeek dsh」。窗口打开前会先启动内置 dsh 服务（首次约 3~10 秒），就绪后自动加载界面。
• 退出：关闭窗口即退出——会同时停止后台的 dsh 服务并释放端口。也可以使用系统托盘/任务栏右键退出。
• 重复启动：若程序已在运行，再次双击只会把已有窗口带到前台（单实例）。

日常使用

启动后你面对的就是完整的 dsh Web 界面，常见操作：

• 对话：在输入框与 AI 智能体对话，提出任务（如"分析这个项目"、"写一个脚本"）。
• 工作区：通过界面选择/授权本地目录作为工作区，dsh 可以在其中读写文件。
• 工具调用：dsh 可调用文件、终端、代码执行等工具；敏感操作会请求你的确认。
• 技能 / 工作流：在设置中管理 Skills 与 Workflow，启用需要的插件能力。
• 模型设置：在设置中配置模型与 API 密钥（数据保存在本机）。

详细的 dsh 功能说明请参阅 DeepSeek dsh 官方文档；本仓库只负责「桌面化」，不修改 dsh 的任何功能。

端口与日志

• 服务地址：http://127.0.0.1:3080（固定端口；若已被其他 dsh 实例占用，应用会直接复用）。
• 日志文件：%APPDATA%\dsh-desktop\dsh.log，包含 dsh 子进程的 stdout/stderr，排查问题时可查看。

---

项目结构

dsh-desktop/
├── main.js                     # Electron 主进程：窗口创建、生命周期、启动/停止 dsh
├── preload.js                  # 预加载脚本：暴露 dshRetry（错误页重试）
├── lib/
│   └── server-manager.js       # 纯 Node 逻辑：端口探测、dsh 子进程启动/停止、就绪等待
├── docs/
│   ├── README.md               # 文档索引
│   └── design.md               # 设计文档（架构与关键决策） 
├── .github/workflows/
│   └── build.yml               # GitHub Actions：测试 + 构建安装包 + 自动发布
├── package.json                # 项目配置与 electron-builder 打包配置
└── node.exe                    # 打包用 Node 运行时（gitignore，构建前自备）

技术架构

┌───────────────────────────────────────────────┐
│ Electron 主进程 (main.js)                      │
│                                               │
│  启动时 ──spawn──▶ 内置 node.exe 运行 dsh        │
│                  (node_modules/@deepseek-ai/   │
│                   dsh/lib/bin.js web)          │
│                    │ 轮询 http://127.0.0.1:3080│
│                    ▼ 就绪（超时 60s）           │
│  BrowserWindow ──加载──▶ dsh Web 界面           │
│                                               │
│  关闭窗口 ──▶ 杀掉 dsh 子进程 ──▶ 退出          │
└───────────────────────────────────────────────┘

关键设计决策（详见 docs/design.md）：

1. dsh 内置：@deepseek-ai/dsh 作为正式依赖随包分发，用户无需安装 Node.js。
2. 真实 node.exe 运行 dsh：避免 Electron 内置 Node 与 koffi 等原生模块的 ABI 不兼容问题。
3. 端口复用：启动前探测 3080，已有服务直接连接。
4. 模块划分：核心逻辑抽到 lib/server-manager.js（纯 Node，无 Electron 依赖），便于维护与复用。

---

开发指南

环境要求

• Node.js ≥ 22（Windows x64）——仅用于开发/构建/测试，运行时不依赖
• npm ≥ 10

常用命令

npm start    # 开发模式：以 Electron 启动应用（本地需已安装 dsh 依赖）
npm run pack # 构建解包目录（快速验证），产物在 dist/win-unpacked/
npm run dist # 构建 NSIS 安装包，产物在 dist/

修改代码

• 改窗口行为 / 生命周期 → main.js
• 改 dsh 启动逻辑 → lib/server-manager.js
• 改打包配置 → package.json 的 build 字段

---

常见问题

Q1：启动后窗口显示「dsh 服务启动失败」？

点击窗口内的「重试」按钮；仍失败则查看日志 %APPDATA%\dsh-desktop\dsh.log。常见原因：

• 3080 端口被其他程序占用且不是 dsh 服务（日志会显示端口已占用，但页面无法就绪）；
• 杀毒软件拦截了内置 node.exe 启动子进程；
• 安装目录权限不足（尝试以管理员身份安装）。

Q2：杀毒软件/Windows Defender 报毒？

本应用是开源项目，代码可审查。报毒通常是误报，原因多为「Electron 打包 + 内置 node.exe + 无数字签名」的组合特征。处理方式：

• 点击「更多信息 → 仍要运行」放行；
• 有条件可为安装包购买/申请代码签名证书（EV 或 OV），可大幅降低误报率。

Q3：目录选择器崩溃（directory picker failed）？

这是 dsh 原生目录选择器（koffi 驱动 Win32 对话框）与运行 Node ABI 不匹配导致的。本应用已内置真实 node.exe 运行 dsh，正常情况下不会出现。若仍出现，请确认安装包是最新版本。

Q4：端口 3080 已被占用？

应用会自动复用已有 dsh 服务（直接连接）。如果你想强制使用全新实例，请先结束占用 3080 的进程再启动应用。

Q5：如何卸载？

在「设置 → 应用 → 已安装的应用」中找到 DeepSeek dsh 卸载，或在开始菜单中找到卸载入口。卸载会一并移除后台服务与程序文件（用户数据目录 %APPDATA%\dsh-desktop 如需彻底删除请手动清理）。

---

发布与维护

• 🏷️ 发布新版本：更新 package.json 版本号与 CHANGELOG.md → 打标签 git tag v1.0.1 && git push origin main --tags → GitHub Actions 自动构建安装包并生成 Release。
• 🚀 首次发布：创建 GitHub 仓库 → git push -u origin main 推送代码 → 按上述方式打 v1.0.0 标签触发自动构建与 Release。
• 🐛 欢迎提 Issue / PR 反馈问题与改进。

开源协议

本项目基于 MIT License 开源。内含的 DeepSeek dsh 及相关 @deepseek-ai/* 包版权归其各自作者所有，请遵守其相应许可条款。