托盘启动器 kissnnx/dsh-launcher

DeepSeek Harness 桌面启动器

双击就启动，不再需要开 cmd 窗口。一个约 430 KB 的 .exe，托盘常驻（官方小鲸鱼图标），右键即可停止。

当前版本 1.1.0 —— "DeepSeek Harness.exe" --version 可查，--diagnose 里也会显示。

- 成品下载：Releases（exe + ico 作为发布附件）
- 源码：src/DshLauncher.cs + src/WhalePath.cs（官方鲸鱼矢量路径）
- 构建脚本：build.ps1
- 卸载脚本：uninstall.ps1
- 通知图标缓存修复：refresh-toast-icon.ps1
- 许可证：LICENSE（MIT）+ NOTICE（鲸鱼矢量素材的 MIT 署名）

dist/ 是构建输出，不放进版本库；要 exe 请下 Release，或按「重新构建」自己编一个。

快速开始

1. 到 Releases 下载最新版 DeepSeek Harness.exe，和 dsh.ico 放在同一个文件夹（快捷方式与托盘图标要用到它）。
2. 确认 DSH 已经装好并能跑：dsh --version（本机是 npm 全局安装的 @deepseek-ai/dsh）。
3. 双击 exe。托盘出现蓝色小鲸鱼图标；浏览器没自动打开就右键托盘 →「打开 DeepSeek Harness」。
4. 开机自启：把 exe 的快捷方式放进 shell:startup（或构建时加 -InstallStartup）。卸载见下面「卸载」。

从 DSH 沙箱里编译/复制出来的 exe 会带上低完整性标记，双击后会报权限错误——见下面那节，一条 icacls 就能修。

它做了什么

1. 双击时先探测 3080 端口：
- 已经在运行 → 只打开页面，不会启动第二个实例；
- 没在运行 → 隐藏窗口启动 node ...\dsh\lib\bin.js --profile web，Harness 自己会把带 token 的地址交给默认浏览器。
2. 托盘出现一个蓝色圆角方块 + 白色小鲸鱼图标（所有尺寸同一个图案），右键菜单：

| 菜单项 | 行为 |
| 打开 DeepSeek Harness | 用启动时捕获的带 token 地址打开页面（浏览器没弹出时的兜底） |
| 复制访问地址 | 把带 token 的地址写进剪贴板 |
| 打开日志文件夹 | 打开 %LOCALAPPDATA%\dsh-launcher\logs |
| 重新启动 | 结束当前服务后重新拉起 |
| 停止并退出 | 结束 Harness 进程树，托盘图标消失 |

双击托盘图标等同于「打开 DeepSeek Harness」。

3. 启动失败时（例如端口被占、配置报错）会弹窗显示退出码和最后 15 行输出，而不是静默死掉。
4. 如果端口已经在服务、却始终没在读到的输出里发现带 token 的地址（说明上游输出格式可能变了），会弹一条告警通知并写进日志，而不是默默降级成不带凭据的地址。

命令行开关

DeepSeek Harness.exe 也接受参数，适合做快捷方式或脚本：

| 开关 | 说明 |
| （无参数） | 已在运行则打开页面，否则后台启动并常驻托盘 |
| --open | 只打开页面 |
| --status | 显示端口 / PID / 地址（弹窗） |
| --stop | 停止该端口上的服务（先杀托盘守护进程树，再按端口兜底） |
| --profile <名称> | 要启动的 profile，默认 web |
| --port <端口> | 端口，默认 3080 |
| --foreground | 显示控制台窗口，排错用 |
| --command "<命令>" | 覆盖启动命令（调试/其他表层） |
| --dry-run | 只检测并记录，不启动、不打开 |
| --diagnose | 显示版本与进程上下文（身份等级、能否写状态目录、沙箱判定 / 文件标记判定） |
| --version | 显示版本与 exe 路径 |
| --out <路径> | 把 --diagnose / --version 的结果同时写成文件（便于脚本读取，GUI 程序没有可捕获的 stdout） |
| --quiet | 不弹窗，配合 --status / --dry-run / --diagnose / --version 做脚本检查 |
| --help | 弹窗显示帮助 |

⚠️ 低完整性标记（本机踩过的坑，务必看）

Windows 启动进程时，进程的身份等级 = 父进程与被启动文件两者中较低的那个。而在 DSH 沙箱里编译/复制出来的文件会被打上 Low（低完整性） 标记，于是：

- 即使你从资源管理器双击，进程也会被降到 Low；
- Low 进程写不了 %LOCALAPPDATA% 和 %USERPROFILE%\.dsh，于是启动器建不出日志目录、Harness 写不了 profiles\web\cordis.yml，报 EPERM；
- 用 .bat 包一层、换快捷方式、换目录都没用 —— 标记在被启动的 exe 文件本身上。

修复（不需要管理员）：

$exe = '<启动器目录>\dist\DeepSeek Harness.exe' # 换成你的实际路径 icacls "$exe" /setintegritylevel Medium

在本机执行后已验证：进程等级变成 Medium、状态目录可写、沙箱判定：否。

两点注意：

1. 校验方式：icacls "<exe>" 的最后一行会显示强制标签，例如正确状态是 Mandatory Label\Medium Mandatory Level:(NW)；是 Low Mandatory Level 就说明还要跑上面那条命令。
想看实效等级（进程真正拿到什么身份）则用 exe 自报： powershell & '<启动器目录>\dist\DeepSeek Harness.exe' --diagnose 看弹窗里的「完整性级别」和「沙箱判定」两行。
2. 重新编译不会再带上标记：build.ps1 会在编译之前把输出目录 dist\ 标成 Medium（新建文件随之继承），编译后再对 exe / ico 各校准一次。所以现在重建必须在普通（非沙箱）PowerShell 里跑 —— 低完整性进程写不进标准完整性的 dist\，脚本会直接报错而不是悄悄产出坏文件。若某天产物又变成了 Low，在普通 PowerShell 里跑一次上面的 icacls 即可。

配置文件

需要改默认值时，把 launcher.config.example.json 复制成 launcher.config.json，放在 exe 旁边（dist\ 目录）。命令行开关优先于文件。

| 键 | 默认 | 含义 |
| profile | web | 启动的配置档 |
| port | 3080 | 端口 |
| extraArgs | 空 | 追加给 dsh 的参数，例如 --no-open |
| nodePath | 自动探测 | node.exe 路径 |
| dshBin | 自动探测 | ...\@deepseek-ai\dsh\lib\bin.js 路径 |
| workspace | $DSH_HOME\storages\workspace.json 里最近的工作区 | Harness 进程的工作目录（无 cwd 会话的沙箱回退根） |
| openWhenReady | false | true = 启动后由启动器再打开一次页面（会多一个标签页） |

自动探测：先找 PATH 里的 dsh.cmd，从它的位置推出 node_modules\@deepseek-ai\dsh\lib\bin.js 和同目录的 node.exe；找不到再试 %APPDATA%\npm\...（npm 的默认全局前缀）。用自定义前缀、装在别的盘、或版本管理器装的 dsh，探测不到时在配置里写死 dshBin 即可。

状态与日志

| 路径 | 内容 |
| %LOCALAPPDATA%\dsh-launcher\logs\launcher.log | 启动器的决策记录（探测、拉起、停止、taskkill 结果、告警） |
| %LOCALAPPDATA%\dsh-launcher\logs\host-<时间>.log | 每次启动的 Harness stdout/stderr 全文 |
| %LOCALAPPDATA%\dsh-launcher\last-url-<端口>.txt | 该端口最近一次捕获的带 token 地址 |
| %LOCALAPPDATA%\dsh-launcher\supervisor-<端口>.pid | 该端口的托盘守护进程 PID（--stop 用它） |

按端口分文件，所以多个启动器（不同端口、不同 DSH 版本并存）共用一个状态目录也不会互相覆盖。1.0.x 时代的单份 last-url.txt / supervisor.pid 只作迁移回退：地址会先校验端口是否匹配才采用，pid 则完全不采用（避免 --stop 误杀别的端口的守护进程）。这两个旧文件可以直接删。

设置环境变量 DSH_LAUNCHER_HOME 可以整体搬到别处（便携用法）。

重新构建 powershell powershell -NoProfile -ExecutionPolicy Bypass -File .\build.ps1 powershell -NoProfile -ExecutionPolicy Bypass -File .\build.ps1 -InstallDesktop # 顺便建桌面快捷方式 powershell -NoProfile -ExecutionPolicy Bypass -File .\build.ps1 -InstallStartup # 顺便加到开机启动

前提是 Windows + .NET Framework 4.x（Win10 1809 起自带 4.8），csc.exe 在 %WINDIR%\Microsoft.NET\Framework64\v4.0.30319\。用它编译，不需要 SDK、NuGet 或联网。两步编译：先编出不带图标的 exe，用它的 --make-icon 生成多尺寸 .ico，再带 /win32icon 编一次。

注意三点：

1. 请在普通（非沙箱）PowerShell 里跑：dist\ 现在是标准完整性，低完整性沙箱进程写不进去（这正是为了让产物双击时不被降级）。
2. exe 正在运行时会被占用：脚本会先把旧 exe 改名成 ...exe.old 让路，然后再编译；旧的 .old 会在下一次构建时自动删除（DeepSeek Harness.exe.old 就是当前托盘进程正在用的那个旧版本）。
3. 刚编译出的文件首次执行可能被实时防护拦一下：图标生成那一步有 3 次重试，日志里会看到 retrying icon generation。

已验证 / 未验证

已实测（1.1.0）：

- --status / --dry-run 对正在运行的端口判断正确（识别出真正的 PID，判定「已在运行」）；
- 用 tests/fake-host.js 跑完整周期：隐藏启动 → 捕获带 token 的 URL → 写 last-url-<端口>.txt → 托盘守护进程存活 → --stop 后端口释放、守护进程退出、pid 文件清理；
- 用 tests/fake-host-nourl.js（只监听、绝不打印 URL）验证新告警：启动后约 3 秒日志出现 warning: the host is serving port ... but no URL line appeared，托盘弹出告警通知；同一状态下有 URL 的 host 不告警、正常抓取地址；
- 多实例并存：同时跑 3096 / 3097 / 3098 三个启动器，各写各的 supervisor-<端口>.pid 与 last-url-<端口>.txt，互不干扰；没有本端口记录时也不会误用别端口的地址（--dry-run --port 3090 返回 http://127.0.0.1:3090/）；
- 用真实 dsh 走了一遍默认启动路径（node ...\bin.js --profile web），确认 node/bin.js 解析、隐藏启动、stdout/stderr 捕获、退出码上报都正常；
- 工作目录解析出了 $DSH_HOME\storages\workspace.json 里最近的工作区；
- .ico 9 个尺寸（16/20/24/32/40/48/64/128/256）由官方鲸鱼矢量路径按尺寸独立光栅化，所有尺寸都是同一个"蓝底白鲸"图案（16px 也会单独渲染，不是缩放）；托盘图标同样按 16/20/24/32 独立渲染。
（曾试过 16–24px 用「> + 小鲸鱼」的紧凑版，好在托盘里更好认，已回滚；参数扫描与对比可用 tools/iconlab.cs 重新生成到任意输出目录。）
- 低完整性标记这条链路被完整复现和证实：D:\dsh_workspace 本身带 Low 强制标签并向下继承，所以工作区里编译出的 exe 一定是 Low；非沙箱（Medium）令牌启动这种 exe，进程仍是 Low、写不了 %LOCALAPPDATA%；icacls ... /setintegritylevel Medium 之后同一上下文变成 Medium、状态目录可写；反过来，沙箱进程复制出来的副本必然是 Low，且沙箱进程执行 icacls /setintegritylevel 会被拒绝 —— 所以启动器自身无法自愈，只能提示确切命令。现在 build.ps1 会先把输出目录标成 Medium，产物继承为标准级别。
- 发布前做过干净副本构建：把仓库里实际会提交的 14 个文件复制到一个全新目录（不含 dist\），直接按 build.ps1 的两遍流程编译 —— 两遍都通过，产物 438784 字节（与现役 exe 同尺寸），生成的 .ico 与现役 dsh.ico 逐字节一致；这也验证了 src/WhalePath.cs 里的矢量路径与现役产物同源。

未在沙箱内验证：

- 双击 exe 后 Harness 真正起来、浏览器自动打开这一整条链路。依据是随包源码：dsh-web-app 在 openBrowser（默认 true）且环境里没有 SSH_CONNECTION/SSH_TTY 时调用 openBrowser(authenticatedUrl)，从资源管理器启动不满足 SSH 条件；
- 从桌面快捷方式双击的那一次点击本身（快捷方式的目标、起始目录、图标已用 COM 读回校验，但没有真的点它，以免无端给你多开一个页面）。

升级与卸载

DSH 大版本升级，对启动器有多大影响

启动器和 DSH 几乎不耦合：它不打包 DSH、不是 DSH 插件、不 import 任何 DSH 包，只做"找 node + dsh\lib\bin.js → 启动 → 读 stdout 里的 URL"。所以升级后大概率零影响；下面这些是全部耦合点，最坏情况改一行配置即可，不需要重新编译。

| 耦合点 | 大版本若变了 | 影响 | 修法 |
| PATH 里的 dsh.cmd/dsh.ps1 → node_modules\@deepseek-ai\dsh\lib\bin.js + 同目录 node.exe | 安装布局变（例如改成自包含二进制） | 唯一会硬失败：弹窗「找不到 dsh 的 lib\bin.js」 | 配置 dshBin 或 command |
| node bin.js --profile web | CLI 契约变 | 启动失败 | extraArgs / command |
| stdout 的 dsh web: ...?token=... | 文案格式变 | 报新告警并退回 plain URL（见上） | 把 host-.log 发我适配 |
| 端口 3080 是否在监听 | 默认端口变 | 探测/停止会看错端口 | 配置 port |
| $DSH_HOME\storages\workspace.json（只读） | schema 变 | 子进程工作目录退回 %USERPROFILE%，无实质影响 | 配置 workspace |
| profile 名 web | profile 改名 | 启动失败 | 配置 profile |

升级 DSH 的正确顺序：① 托盘「停止并退出」（upgrade-dsh.ps1 要求 dsh 不在运行，Windows 不能替换被映射的 .node）→ ② 跑升级脚本 → ③ 直接双击桌面快捷方式，启动器每次启动都重新解析路径，不缓存版本。

反过来，升级/重建启动器也不影响 DSH；dshBin/profile/port/command 都可配，所以新旧大版本可以并存：两份配置目录 + 两个快捷方式，各指一个 dshBin 和端口。

卸载 powershell powershell -ExecutionPolicy Bypass -File .\uninstall.ps1 # 体检：列出将要删除的东西 powershell -ExecutionPolicy Bypass -File .\uninstall.ps1 -Yes # 真正卸载 powershell -ExecutionPolicy Bypass -File .\uninstall.ps1 -Yes -KeepState # 保留日志

它只结束 supervisor-<端口>.pid 记录的启动器进程（刻意不用 --stop，免得按端口误杀你自己用命令行起的服务），并且只在快捷方式确实指向本启动器时才删。全部痕迹只有三处：状态目录 %LOCALAPPDATA%\dsh-launcher、桌面/启动文件夹的 .lnk、以及启动器自己所在的文件夹（最后一行会打印清空命令，删不删由你决定）。
不写注册表（一个键都没有）、不注册服务或计划任务、不改 PATH、不写 DSH 安装目录、不写 $DSH_HOME（profiles / sessions / storages / 凭据）。（refresh-toast-icon.ps1 会删的那个通知身份键是 Windows 自己创建的，不是启动器写入的。）也正因为从不安装，它不会出现在「设置 → 应用」列表里 —— 要那个条目就得写注册表 Uninstall 键，那才是残留。

平台支持与已知限制

只支持 Windows。 这不是打包方式的问题，而是核心功能本身依赖 Windows 机制：

| 能力 | 用到的 Windows 机制 | 换到别的平台要改成 |
| 托盘图标与菜单 | System.Windows.Forms.NotifyIcon | macOS 的 NSStatusItem、Linux 的 AppIndicator |
| 结束进程树 | taskkill /T /F | POSIX 进程组（kill -TERM -<pgid>） |
| 端口 → PID | netstat.exe -ano | ss -ltnp / lsof -iTCP:<port> |
| 低完整性检测 | whoami /groups + icacls 完整性标签 | 无对应概念（Linux 是 AppArmor/SELinux） |
| 打开浏览器 / 文件夹 | UseShellExecute / explorer.exe | open（macOS）、xdg-open（Linux） |
| 状态目录 | %LOCALAPPDATA% | ~/Library/Application Support、$XDG_STATE_HOME |
| 编译 | .NET Framework 4.x 的 csc.exe | 需换 .NET / Mono，或重写 |

所以 Linux / macOS / WSL 上用不了，得另写一个等价启动器；而它在本机的主要价值（不弹控制台、托盘常驻、失败弹窗）在 macOS/Linux 上通常一行 shell 加 systemd/launchd 就能覆盖。Windows ARM64 可以跑（AnyCPU，走 x64 模拟），但仍需 .NET Framework 4.x。

与平台无关的限制：

- 没有代码签名：从网上拿到这个 exe，Windows SmartScreen 会提示"未知发布者"，实时防护也可能拦一下。自用无所谓；要给别人用，得买代码签名证书（或走 Microsoft Store）才能消除。
- 不自带 DSH：不打包 node、不打包 dsh，必须先用 npm 装好 @deepseek-ai/dsh。开发与验证针对的是 0.2.0-rc.2。
- 靠解析 stdout 取地址：上游 dsh web: ...?token=... 那行格式一变，就退化成不带 token 的地址并弹告警。
- 带 token 的地址是明文落盘的：%LOCALAPPDATA%\dsh-launcher\last-url-<端口>.txt 与 logs\launcher.log 里都有。它是本机 DSH 的访问凭据，同机其他进程/用户读得到；目前没有开关能关掉，不想留就删掉状态目录。
- --stop 按端口杀进程：端口上若是你自己用命令行起的服务，也会被结束（uninstall.ps1 刻意不走这条路）。
- 没有自动化测试与 CI：只有 tests/fake-host.js / tests/fake-host-nourl.js 两个假 host 手工验证。

许可证与致谢

- 本项目代码：MIT，Copyright (c) 2026 kissnnx。
- 鲸鱼矢量路径（src/WhalePath.cs）取自 DeepSeek Harness 的 dsh-web-frontend/dist/favicon.svg，同为 MIT，Copyright (c) 2026 DeepSeek；完整署名见 NOTICE。
- 本项目不打包、不链接、不重新分发 @deepseek-ai/dsh，只在运行时启动你已安装的 dsh。
- 非官方声明：这是独立第三方工具，与 DeepSeek 没有隶属、赞助或背书关系。"DeepSeek"、"DeepSeek Harness" 及鲸鱼标志归 DeepSeek 所有；MIT 只授予版权许可，不授予商标许可。

排错

| 现象 | 处理 |
| 双击后没有反应 | 看 launcher.log；若报「找不到 dsh 的 lib\bin.js」，在 launcher.config.json 写 dshBin |
| 托盘弹出告警「端口已在服务，但读到的输出里没有带 token 的地址」 | 上游 dsh web: 那行的格式可能变了。此刻托盘「打开页面」退回 http://127.0.0.1:<端口>/（浏览器 cookie 通常仍有效）；把 logs\host-.log 发我就能适配 |
| 换了图标，但 toast（通知）里还是旧图标 | 这是 Windows 的通知图标缓存，不是 exe 的问题：它按 exe 路径生成固定 AUMID，并在第一次弹通知时把当时的图标转存成 %TEMP%\NotifyIconGeneratedAumid_<hash>.png，之后不再刷新。跑一次 refresh-toast-icon.ps1（-Report 只看不删）即可，下次弹通知会按当前 exe 重新提取 |
| 想知道跑的是哪一版启动器 | "DeepSeek Harness.exe" --version，或看 --diagnose 的第一行 |
| 弹窗说「exe 文件本身带着低完整性标记」 | 按弹窗里给的命令执行一次 icacls "<exe>" /setintegritylevel Medium（见上面那节） |
| 弹窗说「这个进程是由 DSH 拉起来的」 | 从资源管理器 / 桌面快捷方式 / 开始菜单启动，别用页面里的文件卡片或 DSH 终端 |
| 服务起来了但浏览器没开 | 右键托盘 → 打开 DeepSeek Harness；或把 openWhenReady 设为 true |
| 提示端口被占 | 说明已有实例在跑，直接打开页面即可；要换端口用 --port |
| 打开后页面报未认证 / 401 | 你现在的服务是从 cmd 启动的，启动器没有它带 token 的地址。浏览器里的会话 cookie 有效期 30 天（绑定 127.0.0.1:3080，签名密钥存在 $DSH_HOME\.credentials.yaml），通常仍然有效；cookie 已失效时，先 --stop 再用启动器启动一次，它就能拿到带 token 的地址 |
| 想看黑窗口输出 | --foreground |
| 沙箱/受控环境下停止失败 | 启动器会先 taskkill /T /F，被拒绝时改用直接 Kill()，再按端口兜底；结果写进 launcher.log |