dsh-launcher

# dsh-launcher

中文 | English

Windows 下 DeepSeek Harness Web 的启动与管理工具： 在 cmd / PowerShell 中输入 deepseek 即可一键启动（前台 / 后台双模式）、自动打开浏览器、 查询状态、停止服务，支持一键注册 deepseek 命令。

功能特性

• 命令行启动：在 cmd / PowerShell 中输入 deepseek 即可启动
• 前台 / 后台双模式：前台显示运行日志（关窗即停）；deepseek -b 提交后台启动后立即返回
• 自动打开浏览器：服务就绪后自动打开带认证的本地 Web 界面，无需手动输入地址
• 跨浏览器重开：deepseek --open [default|edge|chrome|firefox|brave] 使用当前认证 URL 在指定浏览器中打开
• 快捷方式启动反馈：显示启动进度，成功打开浏览器后自动关窗；失败时保留窗口与日志提示
• 状态查询与停止：deepseek --status 查看运行状态，deepseek --stop 一键停止并提示重启命令
• 跨系统通用：Win10 / Win11 均可使用

安装

前置条件：安装 Node.js

dsh-launcher 是 DeepSeek Harness 的启动器， 只需先安装 Node.js；首次运行 deepseek 时，启动器会通过 npm 在 %USERPROFILE%\dsh-launch\runtime 准备并启动 DSH 本体。

1. 安装 Node.js LTS（要求 ^22.19.0 || >=24.0.0，与上游 DSH 一致；22 LTS 或 24+ 均可；启动器在安装、启动和升级前会统一检查并提示当前版本与升级方式）

首次启动需要联网。Node.js 通常自带 npm；若环境自检提示未检测到 npm，请重新安装 Node.js LTS。

方式一：PowerShell 一行命令（推荐）

irm https://raw.githubusercontent.com/RYun601/dsh-launcher/main/install.ps1 | iex

自动完成：下载最新 Release → 校验发行包 SHA-256 与包清单 → 解压到 %USERPROFILE%\dsh-launcher → 注册 deepseek 命令。

安装器在解压前会核对发行包的 SHA-256（优先使用 GitHub 发行资产摘要，其次为随包发布的 .sha256 校验文件）与包内 release-files.txt 清单；摘要缺失或不匹配、或包内文件与清单不一致时，安装会拒绝执行，不会写入任何文件。

默认不创建桌面快捷方式。需要快捷方式时，请在同一个 PowerShell 窗口依次执行以下两步：

1. 下载安装脚本到当前目录：

   irm https://raw.githubusercontent.com/RYun601/dsh-launcher/main/install.ps1 -OutFile .\install.ps1

2. 执行该脚本，并传入 -Shortcut 参数：

   .\install.ps1 -Shortcut

-Shortcut：在桌面创建「DeepSeek Harness」快捷方式，点击后以后台模式启动并显示启动进度；启动成功后窗口自动关闭。再次使用该参数会更新同名快捷方式；不带该参数时，安装器不会新建快捷方式。

方式二：手动安装

1. 从 Releases 下载 dsh-launcher.zip 并解压
2. 双击运行 install-command.cmd（注册 deepseek 命令）
3. 新开终端，输入 deepseek

方式三：从源码运行

git clone https://github.com/RYun601/dsh-launcher.git
cd dsh-launcher

快速开始

完成上方「安装」（任选一种方式）并新开一个终端窗口（使新 PATH 生效）后：

1. 输入 deepseek -b 提交后台启动并立即返回（或输入 deepseek 前台启动）
2. 首次运行会自动通过 npm 准备 DeepSeek Harness 运行时和必需依赖（需联网，约 1-2 分钟）
3. 服务就绪后浏览器自动打开本地 Web 界面
4. 首次使用需要在 DeepSeek Harness 界面登录 / 填入 API Key

全部子命令与参数见下方「命令行用法」。

命令行用法

每次调用只允许一个动作，出现未知参数或冲突组合时直接报错退出，不会静默回落到前台启动；PowerShell 层的失败退出码会原样传播到 deepseek 命令的返回值。--full 只能与 --uninstall 组合使用；数字只允许紧跟在 --logs 后作为行数、或紧跟在 --rollback 后作为版本列表的显示数量，--json 只允许跟随 --status，--follow 只允许跟随 --logs，版本号（形如 0.1.1-rc.2）只允许跟随 --rollback，浏览器别名只允许跟随 --open。

启动与停止

状态与日志

认证与浏览器

--open 只连接已经处于 READY 的实例；服务正在启动时请稍后重试。命令会复用 DSH 当前进程的认证入口，不会关闭认证或打印含 token 的 URL。显式浏览器使用其默认配置文件，不支持无痕窗口或指定 profile。

版本与升级

• 普通启动优先复用已经准备并校验过的本地 DSH 版本，存在可用本地运行时时不访问 npm；仅在没有可用运行时的首次启动或修复场景中准备依赖。使用 deepseek --update 从 npm 检查新版本，使用 deepseek --upgrade 安装并切换到新版本。
• deepseek --update / deepseek --upgrade / deepseek --rollback 默认直接查询 npm 公共 registry（dist-tags 或已发布版本列表，均比 npm view 更快）。如需使用镜像或私有 registry，可设置环境变量 DSH_REGISTRY（例如 https://registry.npmmirror.com）；该设置仅在查询远端发布版本时生效，不影响本地运行时启动。
• deepseek --upgrade 的详细流程：先解析并校验目标版本，当前运行时健康且版本不低于目标版本时直接提示已是最新并退出（不停止服务、不执行 npm 操作）；否则停止服务 → 清理旧 DSH npx 工作区 → 同步全局 dsh 命令 → 重新后台启动。候选版本因插件依赖 DSH 已移除的导出，或插件清单与目标 DSH 契约不兼容（插件树加载失败）而启动失败时，会列出不兼容插件并询问是否从 web profile 移除；确认后使用目标版本的 dsh plugin --profile web remove 清理插件并重试候选运行时，拒绝或处理失败时依次尝试恢复当前、上一版或旧版可用运行时（只有通过就绪校验的运行时才会被用于回退）。
• deepseek --upgrade 会同步 npm 全局的 dsh 命令：已安装则同步到目标版本，缺失则自动安装，保证直接使用 dsh 命令的版本与启动器一致；该步骤失败仅提示警告，不影响启动器运行时的升级。目标版本无法解析或格式非法时，升级会在停止服务之前直接中止，不会影响当前安装。
• deepseek --rollback <版本> 的约束与流程：目标必须是 npm 上已发布的精确版本号，且低于当前活动版本；当前活动版本未知、目标版本未发布、格式非法或高于当前版本时，都会在停止服务之前直接中止，不会影响当前安装。回退复用 --upgrade 的事务（停止服务 → 清理旧 DSH npx 工作区 → 同步全局 dsh 命令 → 重新后台启动验证），并把全局 dsh 命令一并降级到目标版本；候选启动失败时的插件处理与运行时回退链与 --upgrade 一致。版本列表默认只显示最近 20 个，超出时末尾提示完整列表的查看方式；回退目标的校验始终使用完整版本列表，显示数量只影响打印。
• deepseek --upgrade-launcher 的详细流程：校验发行包 SHA-256 与包清单 → 获取维护互斥锁 → 旧安装整目录备份 → 新版就位 → 离线烟雾验证 → 提交；服务运行中、DSH 升级进行中、源码工作树或非受管安装时拒绝执行；失败自动恢复旧版本（恢复未完成时保留备份与恢复脚本并以退出码 2 结束）。

诊断与卸载

• deepseek --uninstall --full 的事务细节：带确认，取消不做任何更改；先停止服务，目录先备份后删除；PATH 在目录全部备份成功后才移除；安装目录会校验所有权标记，删除失败时保留备份并提示位置。

其他启动方式

以下方式不经过 deepseek 命令，按需选用。

双击内置脚本

• start-deepseek-harness.bat：前台启动（启动服务 + 自动打开浏览器）
• start-background.cmd：后台启动进度窗（启动成功后窗口自动关闭，失败时保留窗口与日志提示）

可选：官方 DSH CLI

只有需要在任意终端直接使用官方 dsh 命令时，才需要全局安装 DSH CLI（dsh-launcher 使用自己的版本化运行时，此步骤并非必需）：

npm install -g @deepseek-ai/dsh

新开一个终端后，可运行：

dsh web

使用启动输出中的认证 URL打开界面即表示启动成功（Ctrl+C 退出）。

npm install -g @deepseek-ai/dsh 会在 npm 的全局可执行目录注册 dsh（Windows 中为 dsh.cmd）。正常安装的 Node.js 会把该目录加入 PATH；若新开终端后仍提示找不到 dsh，请检查 npm 全局目录是否在 PATH 中。

npx @deepseek-ai/dsh web 能直接启动 DSH，但不会注册可在任意终端使用的 dsh 命令。

常见问题

• 输入 deepseek 提示"不是内部或外部命令"：先运行 install-command.cmd，然后新开终端窗口
• 启动时卡在下载 / 报网络错误：换国内镜像后重试 npm config set registry https://registry.npmmirror.com
• deepseek --status 显示 STARTING：表示 DSH 正在下载或启动，使用 deepseek --logs 50 查看实时错误；再次运行 deepseek -b 不会重复提交启动任务
• deepseek --status 显示 FAILED：DSH 在监听端口前退出，运行 deepseek --logs 50 查看具体错误后重试 deepseek -b
• deepseek --status 显示 UNHEALTHY：端口 3080 有 DSH 进程在监听但 HTTP 无响应（可能已卡死）；运行 deepseek --stop 后重新启动
• deepseek --status 显示 FOREIGN_PORT：端口 3080 被其他非 DeepSeek Harness 进程占用；启动前请先排查并释放该端口（启动器和停止逻辑都不会误杀陌生进程）
• 提示端口 3080 被占用（EADDRINUSE）：说明已有一个实例在运行，用 deepseek --status 确认，或先 deepseek --stop 再启动
• 在其他浏览器访问提示 dsh web authentication required：不要直接输入裸地址；在新终端运行 deepseek --open edge（也可替换为 chrome、firefox 或 brave）
• 关闭前台窗口后服务就停了：设计行为（进程寄宿在控制台窗口）；需要常驻请用 deepseek -b
• 想迁移已配置好的 DSH 设置（含 API Key）：复制 %USERPROFILE%\.dsh 整个文件夹到新电脑的 C:\Users\<用户名>\.dsh（含敏感凭据，请勿公开）

附录：文件说明

面向想了解脚本职责或参与贡献的读者；日常使用只需关注上文命令。

许可证

MIT