DSH Win Quick Launcher

DeepSeek Harness 的 Windows 便捷启动器：无终端窗口、自动携带认证令牌、关窗即停服务
支持源码构建与 npm 两种安装方式 · 支持 AI Agent 自动安装 · 零 npm 依赖

中文 · English

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

功能特性

功能	说明
无窗口运行	通过 WScript 隐藏宿主启动服务，全程不弹出终端窗口
自动认证	捕获服务输出中 dsh web: <url>?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[桌面快捷方式<br/>DSH Web.lnk] --> B[start-web.vbs<br/>WScript 隐藏宿主]
    B --> C[launcher.cjs<br/>Node.js]
    C -->|spawn --no-open| D[dsh web 服务进程<br/>源码模式 pnpm / npm 模式 dsh]
    D --> E{stdout 捕获到<br/>dsh web: URL?}
    E -->|是| F[应用模式浏览器窗口<br/>Edge / Chrome]
    E -->|超时 240s| G[taskkill /T /F<br/>结束进程树]
    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