kagurazakayashi/dsh-startup-command

简体中文 · English

在 dsh web 启动成功后运行用户自定义命令的 DeepSeek Harness Web 插件。

当 dsh web 完成启动（Loader 树全部稳定、webServer 开始监听）后，本插件会执行你在 settings.yaml 中配置的自定义命令——例如用特定浏览器、带特定参数打开 Web GUI。

命令完全由设置文件（settings.yaml 的 dsh-startup-command 命名空间）决定，不硬编码在插件源码中。{url} 占位符会被替换为实际 GUI 地址（http://127.0.0.1:<port>/?token=…），因此即使使用 --port 0 由操作系统分配端口也能正确工作。

截图

「设置 → 插件 → 插件配置」页显示的设置卡片：

功能特性

• 启动成功后触发：与内置 web-app 的 openBrowser 走完全相同的生命周期——等整棵 Loader 树 settle、webServer 服务就绪之后才执行，保证拿到的一定是「监听启动后」的实际地址。
• 命令完全可配置：通过 settings 服务注册 dsh-startup-command 命名空间，command 支持单条字符串或多条数组；多条命令按顺序依次执行（前一条退出后才执行下一条）。改配置无需动插件源码。
• {url} / {home} / {browser} 占位符：{url} 执行前替换为 http://127.0.0.1:<实际端口>/?token=…（新版 dsh web 需要 token 换取浏览器登录 cookie；旧版或无 connection 服务时自动退回不带 token 的干净 URL），端口自动分配（--port 0）时同样生效；{home} 替换为用户文件夹；{browser} 自动查找 Chromium 家族浏览器（优先 Chromium > Chrome > Edge，若默认浏览器是其中之一则采用默认浏览器）。
• 不阻塞 dsh 进程：以 detached 方式生成子进程并 unref()，命令独立运行，dsh 退出时不会被拖住。
• 开关与模式：enabled: false 可临时关闭；shell: true 可走系统 shell 执行（默认关闭，直接以参数数组 spawn，路径含空格也安全）。
• 配置缺失即跳过：未设置 command 时打印警告并跳过，不会静默失败或误执行。
• 网页设置卡片：在「设置 → 插件 → 插件配置」页提供一张可展开卡片，就地编辑 enabled / shell / command，并提供「添加示例命令」按钮——弹出说明框介绍示例命令后，一键插入自动查找浏览器的现成命令，无需手改 settings.yaml。

挂载方式

本插件是「双面」插件：host 半侧（index.js，启动时执行命令）+ 浏览器半侧（client.js，在「设置 → 插件 → 插件配置」页注册设置卡片）。

1. 获取包

从 npm 安装（推荐）：

npm install @kagurazakayashi/dsh-startup-command
# pnpm 型 profile 可用：
# pnpm add @kagurazakayashi/dsh-startup-command

或从源码安装（本地开发）——将插件目录放到 profile 下并软链：

C:\Users\<你>\.dsh\profiles\web\plugins\dsh-startup-command\

{
  "dependencies": {
    "@kagurazakayashi/dsh-startup-command": "link:plugins/dsh-startup-command"
  }
}

然后运行 pnpm install 生成软链；或手动创建 node_modules/@kagurazakayashi/dsh-startup-command 指向 ../../plugins/dsh-startup-command 的 junction/symlink。

2. 挂载插件

在 C:\Users\<你>\.dsh\profiles\web\cordis.patch.yml 中添加 insert 条目（只负责挂载，命令配置在 settings.yaml）：

- insert:
    - id: dsh-startup-command
      name: '@kagurazakayashi/dsh-startup-command'
      inject: [webServer]

3. 配置并重启

在 C:\Users\<你>\.dsh\settings.yaml 中添加 dsh-startup-command 命名空间（见下节），然后重启 dsh web 生效。重启后，「设置 → 插件 → 插件配置」页会出现本插件的设置卡片，可就地编辑 enabled / shell / command。

配置详解

配置位于 settings.yaml 的 dsh-startup-command 命名空间。插件启动时通过 settings 服务注册该命名空间，schema 的默认值在未配置时生效：

dsh-startup-command:
  enabled: true
  command: '"C:\Program Files\Google\Chrome\Application\chrome.exe" --app={url}'
  shell: false

支持以下字段：

• command (string | string[]) — 单条命令直接写字符串；多条命令写成数组，按顺序依次执行，前一条退出后才执行下一条；每条按引号分组成 argv，路径含空格必须用双引号包住
• enabled (boolean, 默认 true) — 设为 false 临时关闭
• shell (boolean, 默认 false) — 设为 true 时经系统 shell 执行

command 支持以下占位符，均在执行前替换：

• {url} — 实际 GUI 地址（新版 dsh web 为带 ?token= 的认证 URL）
• {home} — 当前用户文件夹（os.homedir()）
• {browser} — 自动查找的 Chromium 家族浏览器可执行文件路径。查找规则：系统默认浏览器若是 Chromium / Chrome / Edge 之一，则采用默认浏览器；否则按 Chromium > Chrome > Edge 的优先级返回第一个已安装者

网页设置卡片上的「添加示例命令」按钮会先弹出说明框介绍示例命令，确认后再追加一条使用 {browser}、{home}、{url} 的现成命令；若 dsh 启动时未找到 Chromium / Chrome / Edge，则会提示「无法生成示例命令」并说明原因。

使用示例

用 Chrome 以独立配置目录、缓存目录、仿 APP 窗口打开 GUI，不显示欢迎画面、不加载任何扩展：

dsh-startup-command:
  command: '"C:\Program Files\Google\Chrome\Application\chrome.exe" --user-data-dir="D:\dsh-chrome-profile" --disk-cache-dir="D:\dsh-chrome-cache" --app={url} --no-first-run --disable-extensions'

各参数含义：

• --app={url} — 仿 APP 窗口（应用模式，无地址栏/工具栏）
• --no-first-run — 不显示首次运行欢迎画面
• --disable-extensions — 不加载任何扩展
• --user-data-dir=<路径> — 指定配置（profile）目录
• --disk-cache-dir=<路径> — 指定缓存目录

注：使用独立 --user-data-dir 可避免与已运行的 Chrome 实例冲突（否则 --app 会被已有实例接管、开关不生效）。

自动查找 Chromium / Chrome / Edge 并带上上述参数（等效于网页卡片上的「添加示例命令」按钮）：

dsh-startup-command:
  command: '"{browser}" --user-data-dir="{home}/.dsh/dsh-browser-data" --disk-cache-dir="{home}/.dsh/dsh-browser-cache" --app={url} --no-first-run --disable-extensions'

多条命令按顺序依次执行（前一条退出后才执行下一条）：

dsh-startup-command:
  command:
    - 'cmd /c ping -n 3 127.0.0.1' # 先做点准备工作（此例约 2 秒后退出）
    - '"C:\Program Files\Google\Chrome\Application\chrome.exe" --app={url}'

打开任意程序（例如记事本）：

dsh-startup-command:
  command: 'C:\Windows\System32\notepad.exe'

与内置「打开默认浏览器」的关系

dsh web 内置会在启动成功后用 open 包打开系统默认浏览器（web-runtime 行的 openBrowser）。如果你用本插件指定浏览器打开，通常会希望关掉内置行为，避免双重打开。在 cordis.patch.yml 中覆盖该行（patch 会整行替换 config，必须重述所有键）：

- id: web-runtime
  config:
    openBrowser: false
    printUrl: true
    surfaceContext: true
    trustedHosts: !!js ctx.webStartup.trustedHosts

如果不需要禁用内置行为（例如想让默认浏览器与自定义命令共存），去掉这段即可。

触发时序

dsh web 启动
    │
    ▼
Loader 树全部 settle（webServer 开始监听）
    │
    ▼
dsh-startup-command 执行：{url} 替换 → spawn(命令)
    │
    ▼
子进程 detached 运行，dsh 继续服务

卸载

从 cordis.patch.yml 中删除 dsh-startup-command 的 insert 条目（以及不再需要的 web-runtime 覆盖），从 settings.yaml 中删除 dsh-startup-command 命名空间，删除插件目录，重启 dsh web。插件不产生任何持久状态，无需其他清理。

注意事项

• 需重启生效：运行中的进程不会加载新的 patch 行，修改配置后必须重启 dsh web。
• ESM 目录导入限制：name 必须指向 index.js 文件而非目录，否则 Node 报 ERR_UNSUPPORTED_DIR_IMPORT。
• 命令解析：每条命令字符串按「双引号分组」拆成 argv；路径含空格但未加引号时会被错误拆分。
• 多命令串行：多条命令按顺序执行，前一条退出后才启动下一条；如果某条是长驻进程（如浏览器），排在它后面的命令会一直等待——请把长驻命令放在最后。
• 未配置即跳过：command 未设置时打印警告并跳过，不会执行任何东西。
• 不会等待整个序列完成：插件以 detached + unref 启动每条命令，dsh 退出时未启动的后续命令不再执行，已启动的独立进程继续运行；如需确认命令已执行，请查看 dsh 启动日志中的 dsh-startup-command: 行。

License

MIT — 见 LICENSE，版权归 KagurazakaYashi(KagurazakaMiyabi) 所有。

语言

• English