dsh-native-launcher

dsh-native-launcher

以"零额外安装"为设计原则：本插件基于 DSH 官方插件生态及其官方基础依赖构建，不重复引入其他开源框架或重型运行时，仅凭一个官方插件与 Windows 原生机制，让 DeepSeek Harness Web UI 获得桌面 App 式的一键启动体验。

设计理念

把 dsh 的 WebUI 变成桌面应用，并补上 Web 形态天生缺的原生能力：托盘、原生通知、关窗即退。

• 桌面化已完成：快捷方式、托盘、独立窗口、任务通知、关窗即退——启动器该有的都有了。它小而稳定，没有报告的问题就不再折腾；后续以缺陷修复与官方版本适配为主。
• "零额外安装"：不引入 Electron / Python / WebView2 等任何重型桌面端或运行时；插件依赖 DSH 官方插件生态及其官方基础依赖，复用官方能力而不重复实现。装进 profile 即用，卸载即干净。
• 以官方为中心：不魔改、不替换官方 Web UI，一切围绕官方版本做加法；插件本身也只是标准 dsh 插件，官方升级后依然兼容。
• 维护为主：功能范围已收敛——不再扩展新的大功能，把已有的做实做稳，跟随官方版本做适配与修复。用户的反馈和新需求依然欢迎，会按实际价值评估是否实现。
• 个人喜好驱动：功能取舍以本人实际使用为准，也欢迎大家反馈使用中的问题。

一句话：让 dsh 在 Windows 上像桌面软件一样工作——启动、驻留、提醒、退出，都在系统里完成。

安装

平台：仅支持 Windows（Windows 10/11，x64）。macOS / Linux 请勿安装本插件。

版本要求：需要 dsh >= 0.1.5-rc.2（已适配 dsh 0.1.7 并以其为真机验证基准；--no-open 参数自 rc.8 起、任务通知所依赖的官方能力自 0.1.5 起）。本插件以该区间为基线持续适配，不再针对更低版本做适配与验证——使用更低版本 dsh 请安装对应的历史插件版本（见下方「版本状态」）。dsh 版本过低时，插件启动会在日志中给出升级提示。

前置要求：dsh plugin 命令依赖 pnpm。若提示 pnpm is not recognized，先安装：

npm install -g pnpm

（或启用 Node 自带的 corepack：corepack enable pnpm）

设置页表单使用 DSH 官方维护的 @deepseek-ai/schemastery，随插件安装声明；它属于 DSH 官方基础依赖，不是额外的社区功能框架。

推荐方式（普通用户）：从 npm 安装，再用 DSH 官方的插件添加命令接入——拿到的是已发布的正式版本，不需要 clone 源码。

源码方式（开发者）：需要修改代码、或跟进尚未发布的改动时使用。下载源码即视为以开发者身份使用本插件。

# 推荐：npm 安装 + 官方插件添加
npm install -g dsh-native-launcher
dsh plugin --profile web add dsh-native-launcher

# 开发：源码安装（指向本仓库目录）
git clone https://github.com/ingleav626-art/dsh-native-launcher
dsh plugin --profile web add <path-to-repo>
# 重启 dsh web 后生效

安装后重启：桌面出现快捷方式，右下角托盘出现图标。双击快捷方式即用。

安装为应用（推荐，一次性）：普通标签页打开 http://127.0.0.1:3080 → 视觉中心出现安装提示框 → 点「安装」→ 弹出浏览器安装提示 → 确认。装完后：

• 快捷方式自动打开已安装的应用（独立窗口、任务栏独立图标、可固定）
• 若点安装无反应（浏览器安装抑制期），用 Edge 菜单 ⋯ → 更多工具 → 应用 → 将此站点安装为应用

特性

• 桌面快捷方式：安装后自动生成桌面快捷方式，双击即可启动或返回 WebUI；支持自定义名称与强制重建。
• 独立应用窗口：可将 WebUI 安装为桌面应用——拥有独立任务栏图标、无浏览器地址栏；未安装应用时按设置的打开方式回退（独立窗口 / 默认浏览器）。
• 窗口自动聚焦：WebUI 已在运行时，再次点击快捷方式或托盘仅将现有窗口切换至前台，不会重复开启实例。
• 系统托盘：常驻托盘图标，提供"打开 WebUI"与"退出"入口，并可发送 Windows 原生通知；可在设置中选择 dsh 停止后托盘是否保留。
• 任务通知：任务完成、出错、中止、被阻塞、达到上限，以及等待审批 / 回答 / 计划审阅时，通过 Windows 原生通知提醒并进入通知中心；关闭全部页面后由后台补发，确保消息不遗漏。设置页有「发送测试通知」按钮，一键验证「模块 → 通知通道 → 托盘 → 系统」整条链路（排错第一站）。提示音三档可选：系统默认、静音，或自定义音效——在设置页选择本地音频文件（wav / mp3 / wma），改动即时生效，配完紧接着点「发送测试通知」就能试听。
• 关窗即退：关闭全部窗口且无运行中任务时自动停止服务；存在运行中任务则等待其完成后再停止。防抖时长与二次确认窗口均可调整。
• 完整设置界面：启动命令、端口、快捷方式名称、打开方式、托盘开关、通知开关、关闭行为参数及各功能模块开关，均在设置页可视化配置并持久化保存。
• 模块化设计：附加功能以独立模块形式提供，可在设置页单独启用或停用；已使用其他同类插件的用户可关闭对应模块，避免功能冲突。
• 一键卸载：在设置页完成卸载——自动停止服务、移除桌面快捷方式、清理生成文件与注册表项、从 profile 移除插件条目；可选同时清除全部个人配置。卸载过程记录于独立日志文件。
• 日志与诊断：启动、运行、卸载全过程均有结构化日志记录，全部集中在 %USERPROFILE%\.dsh-webui-launcher\logs\ 这一个文件夹里（含网页端事件——统一汇入主日志，浏览器控制台不留任何东西）。出问题时把整个 logs 文件夹发过来即可，不用挑也不用筛选：主日志 native-launcher.log 内容最全，其余是各组件的时间线补充（启动分支、开页面、托盘、通知、应用扫描、卸载）。设置页有「打开日志目录（排错用）」按钮，一键定位。

维护策略

本插件已进入维护阶段：以跟随官方版本适配与缺陷修复为主，不再扩展新的大功能。

为什么不再做整合包

DSH 官方正把常用能力逐步做进 WebUI 本身（终端、会话归档、外部资源接入等）。当初规划整合包，是为了补齐 Web 形态在桌面体验与生态组织上的缺口；如今官方自己把大部分缺口填上了，再重复建设意义不大。与其追着官方做加法，不如把已有的做实、做稳。

后续的功能

自定义通知音效已随 v1.0.0 交付（设置页选择本地音频文件，wav / mp3 / wma）——这是计划中的最后一项新增功能。此后以维护为主，用户反馈的问题会按实际需要评估处理。

关于退役

如果官方后续提供了同类能力（桌面客户端、原生通知或启动器功能），本插件的历史使命就完成了，届时会停止维护并在本 README 顶部说明。

常见问题

Q：任务完成了但没收到通知？ A：通知由托盘直接发送（不依赖浏览器权限）。若托盘也没弹：先确认托盘图标在（重启 dsh 会自动拉起/换新托盘），再看 ~/.dsh-webui-launcher/logs/tray-notify.log 是否有失败原因。另注意 Windows 会静默屏蔽短时间内的连续通知（同一条通知几秒内重复时尤其明显）——设置页"发送测试通知"请间隔几秒再点。

Q：关掉窗口后服务退出了，但我不想让它退？ A：在设置页关闭「关窗自动退出」——关窗后服务常驻（手动用托盘"退出 WebUI"才退出）。

Q：卸载 / 改名后，桌面上还留着旧的快捷方式图标？ A：文件其实已经删除了，是桌面显示没有刷新——按 F5 或右键桌面选"刷新"即可；图标显示异常同理（Windows 图标缓存）。刷新后如果仍有残留，再反馈并附上 logs 文件夹。

Q：任务还在跑，我关了窗口，任务会丢吗？ A：不会。有任务在跑时服务会驻留，任务跑完（且仍无窗口）才自动退出；任务完成还会弹托盘通知。

Q：改了端口，启动打开的还是旧页面？ A：改 port 后已安装的旧应用仍指向旧端口，启动会自动回退到普通窗口模式（功能可用）；清理旧应用请到 edge://apps 手动卸载。

Q：卸载重装了浏览器应用，通知没了？ A：托盘通知不依赖浏览器，不受影响；重装应用后如页面异常，重启 dsh 即可。

Q：托盘图标不见了？ A：重启 dsh 会自动重新拉起（含旧托盘自动换新）；仍不行就任务管理器结束残留的 PowerShell 托盘进程（含 pwsh）再重启。

Q：一个任务会收到两条通知？ A：不会。通知只有系统托盘一个通道（v0.3.6 起浏览器通知已移除），不存在双弹。

Q：双击快捷方式只有命令行窗口，WebUI 没打开？ A：快捷方式通过 dsh --profile web 启动服务，依赖 PATH 中的全局 dsh 命令。若你平时用 npx @deepseek-ai/dsh web 运行（dsh 未全局安装），dsh 命令不存在会导致启动失败。v0.2.1 起会自动回退 npx 启动并在窗口显示提示；

卸载

范围说明：一键卸载仅移除本插件提供的桌面化增强组件（快捷方式 / 托盘 / 自动打开等）；dsh 服务本身与其数据不受影响。

推荐：设置页一键卸载——打开 WebUI 设置 → "WebUI 启动器" → 一键卸载启动器：

• 停止系统托盘与 dsh 后端服务（确认后约 6 秒自动停止，无需手动 taskkill）
• 删除桌面快捷方式、清理全部生成文件与通知注册表项
• 从 profile 移除插件条目（自动备份 package.json.before-uninstall）
• 可勾选「同时清除全部个性化配置」——不清除则重装后会恢复你的偏好（与主流软件一致）
• 全程记录于 %USERPROFILE%\.dsh-webui-launcher\logs\uninstall.log（该日志不会被清理，失败可溯源）

手动清理（备用方案，点开）

dsh plugin --profile web remove dsh-native-launcher   # 1. 移除插件（profile 依赖 + 插件条目）

Remove-Item "$env:USERPROFILE\.dsh-webui-launcher" -Recurse -Force   # 2. 启动脚本/托盘/图标/日志
Remove-Item "$env:USERPROFILE\Desktop\DSH WebUI.lnk"                 # 3. 桌面快捷方式（按实际名字）
reg delete "HKCU\Software\Classes\AppUserModelId\DshNativeLauncher" /f   # 4. 通知标识注册表项

• 已安装的应用（若装过）：Edge 打开 edge://apps → DSH WebUI → 卸载

最后重启 dsh。

想连 dsh 本体一起移除？（与本插件无关，谨慎操作）

本插件不代管 dsh 本体的卸载（会话记录、全局设置等其他数据也在其中）。如确定不再使用：

npm uninstall -g @deepseek-ai/dsh    # 移除 dsh 服务端

并按需备份后清理 DSH_HOME 目录（默认 %USERPROFILE%\.dsh 或自定义路径，含 sessions / settings 等个人数据）。

版本状态

当前版本 v1.0.0。各版本详情见 GitHub Releases；里程碑之外的迭代见提交记录。

• v1.0.0 — 首个正式版。新增自定义通知音效：设置页选择本地音频文件（wav / mp3 / wma），弹出通知即播放，改动即时生效；适配 dsh 0.1.7 的设置机制（0.1.5-rc.2 以上均兼容）；修复通知设置偶发失效与自动打开探测超时的两个真机问题。升级注意：从旧版本（插件 v0.4.2 + dsh 0.1.6 及以下）升级后，通知开关与关键词规则需重新配置一次（设置存储位置随 dsh 新机制调整，一次性成本）；重启 dsh 后托盘自动换新，无需手动处理
• v0.4.2 — 修复版本。修复通知卡片点击后可能打开浏览器而不是应用窗口的问题（浏览器页面标题里的关键词会干扰窗口识别）；启动日志补充了逐步耗时记录，启动慢时可以直接看到卡在哪一步；生成物目录的状态文件改为标准格式并清理了历史遗留文件；启动入口统一切换到 PowerShell 脚本（此前的批处理形态保留为回退备份）
• v0.4.1 — 启动耗时的根因修复版本。修复隐藏窗口启动被系统按后台任务限制性能、导致快捷方式启动被拖到 20~40 秒的问题（实测服务加载 32.4 秒 → 6.0 秒，且运行期同样受益）；修复「仅在任务不在眼前时通知」在页面持续处于前台时静默失效；启动前的服务存活检测由约 2 秒降至毫秒级；启动入口由批处理脚本（.cmd）迁移至 PowerShell 脚本（.ps1），行为逻辑不变
• v0.4.0 — 架构重写版本。功能增量很少，重心是完整重写：全部代码迁移到 TypeScript 严格模式工程（esbuild 构建，产物按职责拆分），插件功能改为模块容器接入（可单独禁用/替换，为分包独立迭代打底），启动脚本/托盘/快捷方式链路建立自动化守卫。功能面：新增任务通知卡片点击唤起已有窗口（不重复开页，需网页已安装为应用）与开机自启动（默认关，设置页开启，即时生效）；修复双击快捷方式无法唤起、自动打开静默失效；设置页精简重复开关
• v0.3.6 — 通知 v2：0.1.5 上任务通知全面恢复（判断与发送移到插件后台，网页全关照样弹）；关窗等待任务完成真正生效；通知设置卡片（规则编辑 / 测试通知 / 即时生效）；日志统一 logs\ 子目录 + 一键打开；模块重构，包体积显著缩减
• v0.3.5 — dsh 0.1.5-rc.2 适配：设置页通道兜底（规避官方连接层回归）；冷启动自动开页面修复（带 token 探测，一次点击即开）
• v0.3.3 — 设置页完整表单 + 一键卸载 + 模块化框架 + 托盘可靠性白箱化
• v0.2.3 — 托盘拉起重构（WScript 隐藏启动，彻底无黑窗）
• v0.2.2 — rc.8 适配（--no-open 防双开）+ 关闭行为修复（任务在跑立即挂起等待）
• v0.2.1 — 启动可靠性修复（启动脚本分支 / HTTP 探测 / npx 回退 / 托盘重试 / 环境自诊断）
• v0.2 — 托盘原生通知主通道 + 等待确认通知 + 关闭行为（桌面应用行为）+ 托盘自更新
• v0.1 — 桌面化基础：快捷方式、静默启动、端口探测、托盘、应用优先、安装引导、任务通知集成

工作原理

桌面快捷方式(DSH WebUI.lnk)
    │ wscript.exe launcher.vbs（隐藏窗口，无黑窗）
    ▼
launch.ps1 就绪探测 (127.0.0.1:<port>)
    ├─ 已运行 → 拉起托盘 → open-webui.ps1（打开已装应用/浏览器，不重复启动）
    └─ 未运行 → 拉起托盘 → set DSH_LAUNCHER=1 && dsh --profile web --no-open（静默启动；dsh 不在 PATH 时自动回退 npx --yes @deepseek-ai/dsh）
                                │
                                ▼
                         插件加载（任意启动方式都会执行）
                                ├─ 拉起系统托盘（单实例保护 + 版本自更新）
                                ├─ 注册应用清单（manifest + 官方图标）
                                ├─ 注册设置页 "WebUI 启动器" 分组
                                ├─ 注册通知 / 关窗行为（见下）
                                └─ 检测 DSH_LAUNCHER=1 → 等待服务就绪
                                   → 端口可用 → 打开 WebUI

open-webui.ps1 打开链路（多路探测，命中一个即启动）：

优先级	方式	说明
0	已运行检测 → 聚焦现有窗口	按应用标识 / 端口 URL（任意 host）匹配浏览器进程；已在运行则聚焦，绝不新开
0	--app-id=<app_id>	启动时扫描 Edge 已安装应用（按站点 URL 匹配），部署自适应；冷启动后验证进程是否真的出现
0b	应用列表（explorer shell:AppsFolder\<应用标识>）	Windows 已注册应用列表，按站点前缀 + 名称匹配
1-2	应用快捷方式扫描	开始菜单 / 任务栏 / 桌面（浏览器 exe + --app-id 特征），避免自我递归
3	Chromium Web Applications 目录	旧结构 manifest 匹配
4	--app / --new-window / 默认	未安装应用时的浏览器回退

通知链路（可靠主通道，v0.3.6 起全部在插件后台完成，不依赖网页）：

会话事件（插件后台监听）
   → 状态判定 → 按通知设置与规则过滤 → 写入通知队列
等待批准 / 回答 / 计划审阅：页面端上报 → 同一判定与投递
      → 托盘每 1.5 秒轮询 → Windows 原生通知（应用标识已注册）
         ├─ 成功 → 删除队列文件
         └─ 失败 → 记 tray-notify.log + 气泡提示 + 提示音

关窗行为（桌面 App 行为）：

页面加载 → 在线登记（每个标签页独立标识）
页面关闭/刷新 → 离线上报
   → 全部页面离线 → 20s 防抖（刷新/重连可取消）
   → 任务空闲 → 2s 二次确认 → 优雅退出服务（数据已保存）
   → 任务在跑 → 驻留；任务完成且仍无页面 → 自动退出

配置

cordis.patch.yml（或 profile 的 patch 层覆盖）：

- id: native-launcher
  config:
    # 快捷方式双击后执行的启动命令（由启动脚本执行，依赖 PATH 里的 dsh；dsh 缺失时自动回退 npx --yes @deepseek-ai/dsh）
    # --no-open：让官方 dsh web（rc.8 起默认自动开浏览器）让位，避免双开——浏览器由插件负责打开（已装应用优先）
    launchCommand: dsh --profile web --no-open
    # 是否自动打开浏览器（仅快捷方式启动且带 DSH_LAUNCHER=1 时）
    autoOpen: true
    # 快捷方式名称（不含扩展名）
    shortcutName: DSH WebUI
    # 快捷方式已存在时是否强制覆盖
    force: false
    # 端口探测端口（需与 webserver 端口一致）
    port: 3080
    # 是否启用系统托盘
    tray: true
    # 打开方式：app（独立窗口，默认）| new-window（新窗口）| default（浏览器默认行为）
    openMode: app
    # 关窗行为（桌面应用行为）：所有页面窗口关闭后，无任务则优雅退出服务；有任务则驻留到完成
    closeToExit: true

生成物（用户目录 ~/.dsh-webui-launcher/，日志统一在 logs/ 子目录）：

排错时的一步操作：把 logs 文件夹整个发过来即可（不必判断该看哪个文件）。 所有日志都在那一个文件夹里，没有第二处——主日志 native-launcher.log 最全，其余按组件分文件。 设置页「打开日志目录（排错用）」按钮可直接弹出该文件夹。

文件	作用
launcher.vbs	启动入口：隐藏窗口调起启动脚本（快捷方式默认指向它）
launcher-visible.vbs	同上但显示窗口——排错用，可以看到启动全过程与逐行耗时
launch.ps1	就绪探测 + 启动/直连 + 拉起托盘（逐行耗时写入日志）
launch.cmd	同上的历史形态（v0.4.1 起默认不用，保留作回退备份）
launch-ready.ps1	就绪等待辅助：后台等待服务可访问并记录时间
open-webui.ps1	多路探测打开已安装应用 / 浏览器（已运行→聚焦，未运行→启动）
tray.ps1	托盘（单实例保护；打开 / 退出 WebUI；通知轮询）
tray-state.json	托盘运行状态（进程 / 脚本版本 / 启动时刻；用于托盘自动更新）
tray-notify.json	通知队列文件（插件写 → 托盘轮询发送 → 消费删除）
webui-url.json	带 token 的 WebUI 地址（打开页面时优先使用）
shortcut-registry.json	桌面快捷方式登记（卸载时定点清除）
dsh-webui.ico	快捷方式 / 托盘图标（官方 DSH 图标）
logs/native-launcher.log	主日志：启动/快捷方式/托盘/通知/关窗行为/设置/模块，含环境快照与网页端事件
logs/native-launcher.prev.log	主日志的上一代（超过 1MB 自动轮转归档）
logs/launch.log	启动入口日志（每次双击的探测结果、逐步耗时与走向）
logs/open-webui.log	打开页面链日志（应用优先/聚焦/新开窗口的判定过程）
logs/tray-exit.log	托盘启动与退出原因记录（单实例冲突 / 正常退出）
logs/tray-notify.log	通知发送与失败原因 / 轮询错误
logs/pwa-scan.log	应用扫描诊断日志（每次启动重写）
logs/uninstall.log	一键卸载的审计日志（刻意不随卸载清理，失败可溯源）

致谢

• 构建于 DeepSeek Harness 插件生态之上（MIT License, Copyright (c) 2026 DeepSeek）——"以最小破坏性利用原生插件生态实现桌面级体验"的设计理念，依赖其插件机制与官方 API
• 任务通知设计源自：dsh-notification（MIT License, Copyright (c) 2026 DeepSeek）——上游已停止维护（失效于 dsh 0.1.5 的架构变更）；v0.3.6 起按其决策链设计重写为本项目自维护的通知模块（判定收归插件后台、托盘为唯一通道），上游的贡献与设计归属致谢于此
• 图标使用官方 DeepSeek Harness 品牌图标（源自 dsh web 的 favicon.svg），仅用于非商业开源插件场景

许可证

MIT