NoMindSama/dsh-launcher

DSH Launcher

为 DSH Web 自动创建 Windows 桌面快捷方式：双击直达工作页面，未启动时自动拉起 dsh web。

目录

- 简介
- 演示
- 功能特性
- 安装方法
- 配置说明
- 工作原理
- 目录结构
- 常见问题
- 卸载
- 许可证

简介

dsh-launcher 是一个 DSH Web 辅助插件，用于在 Windows 桌面上自动创建名为 「DSH 工作台」 的快捷方式。

它解决的核心问题是：每次使用 DSH Web 都要手动打开终端、进入工作目录、输入 dsh web。安装本插件后，DSH 会在启动时自动创建/更新桌面快捷方式，你只需要：

双击桌面上的 「DSH 工作台」 -> 直接进入 DSH Web 工作页面。

本插件不会修改 DSH Web 的聊天、侧栏、设置等任何原生功能，只负责桌面快捷方式的创建与启动编排。

演示

DSH Launcher 演示示意图

上图为演示示意图：左侧是安装后自动生成的桌面快捷方式，右侧是双击后打开的 DSH Web 页面。实际桌面样式、图标和 DSH 界面以你的系统与主题为准。

图标预览

该图标会随快捷方式一起安装到：

%USERPROFILE%\.dsh\launcher\icon.ico

你可以随时替换它，详见 配置说明。

功能特性

- 一键直达：双击桌面快捷方式即可打开 DSH Web 工作页面。
- 智能判断运行状态：
- DSH Web 已运行：直接打开当前页面，不重复启动服务；
- DSH Web 未运行：自动在工作目录中最小化启动 dsh web，并由 DSH 打开带认证 token 的页面。
- 自动识别端口：优先读取 DSH 实际监听端口，默认回退到 3080。
- 可配置工作目录：快捷方式启动 DSH 时使用你指定的 workspace。
- 可配置快捷方式名称与图标。
- DSH 原生插件安装：通过 dsh plugin --profile web add ... 安装，无需手动复制文件。
- Windows 原生实现：只依赖系统自带的 Windows PowerShell，不需要额外运行时。
- 幂等安装：每次 DSH 启动会检查并更新快捷方式，不会产生重复图标。
- 非 Windows 平台安全跳过：当前版本仅支持 Windows，其他平台不会产生副作用。

安装方法

环境要求

| 项目 | 要求 |
|---|---|
| 操作系统 | Windows 10 / Windows 11 |
| Node.js | >= 20 |
| pnpm | 已安装并在 PATH 中 |
| DSH | 已安装 dsh 命令，且 dsh web 可正常运行 |
| 浏览器 | 系统默认浏览器（推荐 Edge / Chrome） |

dsh plugin 本质上是把参数转发给 pnpm，因此请确保 pnpm 可用：pnpm -v。

方式 A：从 GitHub 安装（推荐）

在任意目录执行：

dsh plugin --profile web add github:NoMindSama/dsh-launcher

安装完成后，重启 DSH Web：

先停止当前 dsh web 进程，然后重新启动
dsh web

DSH 加载 dsh-launcher 插件后，会自动在你的桌面创建/更新：

DSH 工作台.lnk

以后直接双击这个快捷方式即可。

方式 B：本地开发安装

git clone https://github.com/NoMindSama/dsh-launcher.git
cd dsh-launcher
dsh plugin --profile web add link:.

注意：必须在 package.json 所在的仓库根目录执行 dsh plugin --profile web add link:.，不要写成 link:.\dsh-launcher 这种子目录路径，否则 pnpm 会把它当成普通依赖，而不是 DSH bundle 插件。

然后重启 dsh web。

方式 C：不使用 DSH 插件，手动创建快捷方式

如果你只想使用启动器脚本，也可以手动运行安装脚本：

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-shortcut.ps1
-LauncherScript .\scripts\launch-web.ps1
-IconPath .\assets\icon.ico
-ShortcutName "DSH 工作台"
-WorkingDirectory "E:\your-workspace"

其中 -WorkingDirectory 改成你希望 dsh web 启动时使用的工作目录。

配置说明

插件配置优先级为：

DSH 插件配置  >  环境变量  >  默认值

1. DSH 插件配置

在你的 profile patch 层（例如 $DSH_HOME/profiles/web/cordis.patch.yml 或 $DSH_HOME/cordis.patch.yml）中加入：

- id: dsh-launcher
config:
workspace: "E:\\projects\\my-dsh-workspace"
port: 3080
shortcutName: "DSH 工作台"
dshCommand: "C:\\Users\\you\\AppData\\Roaming\\npm\\dsh.cmd"
desktop: "C:\\Users\\you\\Desktop"

字段说明：

| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| workspace | string | DSH 启动时的工作目录 | 双击快捷方式后启动 dsh web 的工作目录 |
| port | number | 3080 | DSH Web 默认端口；实际运行时优先使用真实监听端口 |
| shortcutName | string | DSH 工作台 | 桌面快捷方式名称，不需要带 .lnk |
| dshCommand | string | 自动查找 dsh.cmd | dsh 可执行文件路径，适用于非全局 npm 安装 |
| desktop | string | 系统桌面目录 | 自定义桌面目录，支持 OneDrive 重定向 |

2. 环境变量配置

如果不想修改 DSH patch，也可以设置环境变量：

| 环境变量 | 对应配置 | 示例 |
|---|---|---|
| DSH_LAUNCHER_WORKSPACE | workspace | E:\projects\my-app |
| DSH_LAUNCHER_PORT | port | 3080 |
| DSH_LAUNCHER_SHORTCUT_NAME | shortcutName | DSH 工作台 |
| DSH_LAUNCHER_DSH_CMD | dshCommand | C:\Users\you\AppData\Roaming\npm\dsh.cmd |
| DSH_LAUNCHER_DESKTOP | desktop | C:\Users\you\Desktop |

PowerShell 中临时设置示例：

$env:DSH_LAUNCHER_WORKSPACE = "E:\projects\my-app"
$env:DSH_LAUNCHER_PORT = "3080"
dsh web

3. 更换快捷方式图标

方式一：替换包内图标后重启 DSH：

assets/icon.ico

方式二：直接替换运行时图标：

%USERPROFILE%\.dsh\launcher\icon.ico

然后重新双击快捷方式；如果 Windows 仍显示旧图标，在桌面按 F5 刷新即可。

4. 运行时生成的文件

插件会在 DSH Home 下生成：

%USERPROFILE%\.dsh\launcher\
├── icon.ico
├── launch-web.ps1
├── install-shortcut.ps1
└── config.json

其中 config.json 由插件根据配置自动生成，一般不需要手动修改。

工作原理

dsh web 启动
|
v
DSH 加载 dsh-launcher 插件
|
v
插件把脚本与图标复制到 %USERPROFILE%\.dsh\launcher
|
v
调用 install-shortcut.ps1 创建/更新桌面快捷方式
|
v
用户双击 DSH 工作台
|
+-- DSH Web 已运行 -> 直接打开 http://127.0.0.1:/
|
+-- DSH Web 未运行 -> 在配置的 workspace 中启动 dsh web

目录结构

dsh-launcher/
├── assets/
│   ├── demo.png              # README 演示示意图
│   ├── icon.ico              # 快捷方式图标（多尺寸）
│   └── icon.png              # 图标原图
├── lib/
│   └── index.js              # DSH host 插件入口
├── scripts/
│   ├── install-shortcut.ps1  # 创建/更新桌面快捷方式
│   └── launch-web.ps1        # 快捷方式实际执行的启动脚本
├── .github/
│   └── workflows/
│       └── ci.yml            # 基础校验工作流
├── cordis.patch.yml          # DSH bundle patch
├── package.json
├── LICENSE
└── README.md

常见问题

Q1：安装后桌面没有出现快捷方式？

请依次检查：

1. 是否执行了 dsh plugin --profile web add ... 或 dsh plugin --profile web add link:.；
2. 是否 重启了 dsh web；
3. 当前系统是否为 Windows；
4. 查看 DSH 启动日志中是否出现：

[dsh-launcher] desktop shortcut is ready: DSH 工作台
5. 检查 %USERPROFILE%\.dsh\launcher\ 目录是否生成。

Q2：双击快捷方式后浏览器显示 401 / 无法访问？

DSH Web 使用临时启动 token 和浏览器 Cookie 认证：

- 如果 DSH Web 已经在运行，快捷方式会打开 http://127.0.0.1:/，正常情况下浏览器已有 Cookie；
- 如果浏览器清除了站点数据，请先关闭当前 DSH Web，再双击快捷方式重新拉起，DSH 会打开带认证 token 的完整 URL。

Q3：快捷方式打开后没有进入我指定的工作目录？

请检查配置中的 workspace 是否存在。不存在时脚本会回退到用户主目录。也可以通过 config.json 确认实际值：

%USERPROFILE%\.dsh\launcher\config.json

Q4：可以用于 macOS / Linux 吗？

当前版本只支持 Windows 桌面快捷方式。非 Windows 平台插件会直接安全跳过。

Q5：会不会修改 DSH 原生界面？

不会。本插件是 host 侧辅助插件，只创建桌面快捷方式，不注入任何前端样式或 UI 组件。

卸载

从 DSH 移除插件：

dsh plugin --profile web remove dsh-launcher

然后手动删除桌面快捷方式 DSH 工作台.lnk。

如果需要彻底清理运行时文件：

Remove-Item -Recurse -Force "$env:USERPROFILE\.dsh\launcher"

许可证

本项目使用 MIT License。

Made with love for DSH Web.