Windows 快捷启动器big0lives/dsh-win-quick-launcher

DSH Win Quick Launcher

DeepSeek Harness 的 Windows 便捷启动器：无终端窗口、自动携带认证令牌、关窗即停服务

支持源码构建与 npm 两种安装方式 · 支持 AI Agent 自动安装 · 零 npm 依赖

中文 · English

使用 DeepSeek Harness（DSH）时，每次启动都要打开终端、执行 pnpm dsh web（或 dsh web）、再从输出里复制带 token 的地址。本启动器把这串动作压缩成一次双击：桌面图标 → 服务后台启动 → 应用窗口自动弹出 → 关窗即停。

功能特性

| 功能 | 说明 |
|---|---|
| 无窗口运行 | 通过 WScript 隐藏宿主启动服务，全程不弹出终端窗口 |
| 自动认证 | 捕获服务输出中 dsh web: ?token=... 一行，直接使用带令牌的地址，跳过 authentication required 页面 |
| 双安装模式 | 同时支持源码构建（pnpm dsh web）与 npm 安装（dsh web，即 npm install -g @deepseek-ai/dsh 或 npx @deepseek-ai/dsh web）的用户 |
| Agent 可安装 | 仓库内置 AGENTS.md 操作手册，把提示词发给你的 AI Agent 即可完成安装与验证 |
| 应用模式窗口 | 以 Edge / Chrome 的 --app 模式打开独立窗口（无地址栏，使用独立浏览器配置目录） |
| 关窗即停 | 监视浏览器进程，窗口关闭后自动结束整个服务进程树 |

⚠️ 与姊妹插件 dsh-web-window-companion 二选一：两者共用同一个浏览器专用配置目录，同时启用会导致窗口互踢闪退、服务被误停。用桌面图标就不需要装那个插件。

快速开始

委托给你的 AI Agent（推荐）

把下面这段提示词原样发给你正在使用的 AI Agent（Codex、Claude Code、Kimi 等）：

请帮我安装 DSH Win Quick Launcher。项目地址为 https://github.com/big0lives/dsh-win-quick-launcher。先阅读仓库的 AGENTS.md 与 README，确认本机环境（Windows、Node.js、DSH 安装方式）满足前置条件，再按 AGENTS.md 的步骤完成安装与验证。执行前向我说明将要改动的位置；遇到杀软排除项、终止进程、凭据或覆盖已有文件时，先停下向我确认。

Agent 只会读写本仓库目录并创建一个桌面快捷方式；它不会改动你的 DSH 源码目录，也不会调整杀毒软件设置。

手动安装

前置条件：Windows 10 / 11、Node.js，以及以下二选一——源码安装（已执行过 pnpm run build 的 DSH 源码目录）或 npm 安装（npm install -g @deepseek-ai/dsh，dsh 命令在 PATH 中可用）。

git clone https://github.com/big0lives/dsh-win-quick-launcher.git
cd dsh-win-quick-launcher

源码安装的 DSH：指定源码目录
powershell -ExecutionPolicy Bypass -File install.ps1 -DshRoot D:\path\to\deepseek-harness

npm 安装的 DSH：
powershell -ExecutionPolicy Bypass -File install.ps1 -Npm

双击桌面上的 DSH Web 图标完成启动。

使用方法

安装完成后日常使用为零操作：双击桌面图标，等待几秒，应用窗口自动弹出并处于已认证状态；关闭窗口，服务随之停止。你能感知到的信号只有两个：应用窗口本身，以及 %TEMP%\dsh-web-launcher.log 里的日志行。

故障排查与维护

| 现象 | 原因与处理 |
|---|---|
| 双击后无反应 | 查看 %TEMP%\dsh-web-launcher.log，每一步都有记录 |
| 页面显示 dsh web authentication required | 访问的地址缺少 ?token= 参数。令牌随每次启动随机生成，只能通过启动器或终端打印的完整地址进入 |
| 启动失败且日志显示 EADDRINUSE | 3080 端口被上次未退出的服务占用，用任务管理器结束对应 node 进程后重试 |
| 启动器脚本被 Windows Defender 删除 | 隐藏进程 + 进程管理的组合可能触发误报，将本目录加入 Defender 排除项后重新安装 |
| DSH 构建报错 git rev-parse HEAD | DSH 构建脚本要求源码目录是 git 仓库；解压的发布包需先 git init && git commit，或设置环境变量 DSH_CLIENT_COMMIT_HASH（7-40 位十六进制） |

回滚：删除桌面快捷方式与 launcher.config.json 即可完全卸载；启动器不写入注册表，不修改 DSH 本体。

架构及原理

各组件的触发时机：start-web.vbs 仅在双击快捷方式时运行，职责是把 launcher.cjs 挂到隐藏宿主上；launcher.cjs 拉起 DSH 服务并持续监视两件事——stdout 里的认证地址、浏览器进程的存活；窗口关闭是唯一的服务停止信号，由启动器同步调用 taskkill /T /F 完成清理。

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px', 'lineColor': '#64748B'}}}%%
flowchart TD
A[桌面快捷方式DSH Web.lnk] --> B[start-web.vbsWScript 隐藏宿主]
B --> C[launcher.cjsNode.js]
C -->|spawn --no-open| D[dsh web 服务进程源码模式 pnpm / npm 模式 dsh]
D --> E{stdout 捕获到dsh web: URL?}
E -->|是| F[应用模式浏览器窗口Edge / Chrome]
E -->|超时 240s| G[taskkill /T /F结束进程树]
F --> H{窗口关闭?}
H -->|是| G

classDef start fill:#3B82F6,stroke:#2563EB,color:#fff,stroke-width:2px
classDef process fill:#10B981,stroke:#059669,color:#fff,stroke-width:2px
classDef decision fill:#F59E0B,stroke:#D97706,color:#fff,stroke-width:2px
classDef stop fill:#8B5CF6,stroke:#7C3AED,color:#fff,stroke-width:2px

class A start
class B,C,D,F process
class E,H decision
class G stop

令牌机制：DSH 服务每次启动时在内存中生成随机令牌，并将 http://127.0.0.1:3080/?token=... 打印到 stdout。启动器用 --no-open 阻止服务自行打开浏览器，改为捕获该地址后自行以应用模式打开，从而获得可监视的浏览器进程句柄——窗口关闭事件即服务停止信号。

Agent 协议（自动化部分，人类无需操作）

安装与排障的机器可读契约收录在 AGENTS.md：环境检查项、两种模式的安装步骤、验证方法（轮询 3080 端口 + 检查日志末行 browser spawned）、操作边界（不修改 DSH 本体、终止进程前列清单、Defender 排除项需用户批准）。这部分由 Agent 自动执行，用户不需要阅读。

配置

launcher.config.json 由 install.ps1 生成，位于 launcher.cjs 旁（已加入 .gitignore）：

| 键 | 说明 | 默认值 |
|---|---|---|
| mode | source（源码安装）或 npm（npm 安装） | 配置了 root 时为 source，否则为 npm |
| root | DSH 源码目录（source 模式必填） | 环境变量 DSH_ROOT |
| pnpm | pnpm 的 JS 入口路径（source 模式） | %APPDATA%\npm\node_modules\pnpm\bin\pnpm.cjs |
| args | 追加的启动参数 | source：["dsh", "web", "--no-open"]；npm：["web", "--no-open"] |

目录结构

dsh-win-quick-launcher/
├── launcher.cjs          # 核心启动器：拉起服务、捕获认证地址、监视窗口、停止服务
├── start-web.vbs         # 无窗口入口，供桌面快捷方式调用
├── install.ps1           # 安装脚本：生成配置、创建桌面快捷方式
├── AGENTS.md             # AI Agent 安装/排障操作手册
├── assets/
│   └── dsh-whale.ico     # 快捷方式图标（DeepSeek 鲸鱼）
├── .gitignore
├── LICENSE               # MIT
├── README.md             # 中文文档
└── README-en.md          # English documentation

技术栈

| 技术 | 用途 |
|---|---|
| Node.js child_process | 服务进程拉起、stdout 捕获、浏览器进程监视、进程树终止 |
| VBScript WScript.Shell | 无窗口宿主，避免弹出控制台 |
| PowerShell + WScript.Shell COM | 安装与桌面快捷方式创建 |

不依赖任何 npm 包。图标为 DeepSeek 品牌资产，取自 deepseek.com 站点图标，仅用于桌面快捷方式标识。

贡献

1. Fork 本仓库
2. 创建功能分支（git checkout -b feature/amazing）
3. 提交改动（git commit -m 'feat: add amazing feature'）
4. 推送分支（git push origin feature/amazing）
5. 提交 Pull Request

许可证

MIT

维护者：@big0lives