dsh-auto-open-web 0.1.4 → 0.1.9

package/README.en.md

@@ -31,7 +31,12 @@ selected by `windowKind`:
    kills the dedicated instance process tree (matching only our own user-data-dir, never the normal
    browser); instances left behind by a force-kill are cleaned up before the next launch.
 3. If the selected type is unavailable (host missing / browser not found / non-Windows, etc.) →
-   **nothing is opened** (a log entry is written), with no automatic cross-fallback.
+   **falls back to the official default-browser handoff** — the URL is given to the OS default
+   browser (plain tab), so the user can always reach the GUI. The implementation mirrors exactly
+   how the DSH core (web-app bundle) opens the page at startup: it prefers the `open` package
+   shipped with the DSH deployment (win32 = PowerShell Start, darwin = `open`, linux = `xdg-open`);
+   when the package is unavailable it falls back to a native platform launch
+   (win32 = `cmd /c start`, darwin = `open`, linux = `xdg-open`).
    `appWindow: false` opens nothing automatically.
 
 The port comes from the real listening value of the webServer service (`--port` overrides and
@@ -42,6 +47,13 @@ Both modes close with DSH: the webview2 host watches the parent process; the
 browser dedicated instance is ended by the Job Object (also effective on force-kill) plus exit
 cleanup.
 
+> **Relationship with DSH's core browser handoff**: the DSH core (web-app bundle) opens the GUI
+> in the system default browser at startup by default (`openBrowser: true` — a plain tab/window,
+> not an app window). Installing this plugin flips `web-runtime.openBrowser` to `false` via the
+> plugin's bundle patch, so only the plugin's app-style window opens and no ordinary browser page
+> pops up; uninstalling the plugin restores the default behavior (or use `dsh web --no-open`
+> to disable it temporarily).
+
 ### WebView2 host requirements (webview2 mode only)
 
 - Windows 10 1803+ / Windows 11 / Windows Server 2016+
@@ -59,15 +71,17 @@ Two equivalent ways:
    `browserPath` (browser executable, with a native "Browse" file dialog; located below the
    window-type field and enabled only when "Browser app window" is selected),
    `exitOnWindowClose` (exit DSH when the window closes, off by default).
-   After saving, values persist to the settings document (namespace `auto-open-web`); once saved,
-   settings take precedence over row configuration.
+   After saving, values persist through the **official settings domain** (client `settingsScope`)
+   to the settings document (namespace `auto-open-web`); once saved,
+   settings take precedence over row configuration. The host keeps only the "Browse" / "Test"
+   helper routes (capabilities the official channel cannot cover).
 2. **Row configuration** (`cordis.patch.yml`): acts as the startup seed, effective until the
    settings card is saved.
 
 | Field | Default | Description |
 | --- | --- | --- |
 | `appWindow` | `true` | Automatically open the independent app window on start; `false` opens nothing |
-| `windowKind` | `webview2` | `webview2` = WebView2 host (own process, DSH taskbar icon, exits with DSH); `browser` = dedicated `--app` browser instance. If the selected type is unavailable, only a log entry is written and nothing opens |
+| `windowKind` | `webview2` | `webview2` = WebView2 host (own process, DSH taskbar icon, exits with DSH); `browser` = dedicated `--app` browser instance. If the selected type is unavailable, it falls back to the default-browser handoff (official open method, plain tab) |
 | `exitOnWindowClose` | `false` | **（Experimental）** Exit DSH when the auto-opened window closes (off by default; only effective while `appWindow` is on). Triggered only when the window process exits **normally** (user closes the window) → `process.exit(0)`; startup failures/crashes/force-kills (non-zero exit code) do not trigger, preventing accidental exits. **Takes effect immediately in the current session after saving** (the exit listener is always registered; behavior is driven by a live flag), no restart needed |
 | `browserPath` | `''` | Manual browser executable path (single entry, e.g. `C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe`; used only in browser mode), preferred over the built-in candidates Edge → Chrome; a non-existent path is skipped with a warning. The "Browse" button on the card opens a **native file dialog**: same mechanism as the official workspace directory picker (child process + koffi-driven `IFileOpenDialog`; the dialog is the child's first window and is automatically brought to front; no PowerShell). The "Test" button **actually launches** a dedicated `--app` test instance (separate user-data-dir `~/.dsh/<browser>-test-profile`, never pollutes the real instance): after confirming the browser main process stays alive it reports success, then automatically ends that test process tree after a few seconds of display (exact pid, never touches the real instance; the test instance is also placed in the Job Object when available as an exit safety net); the test uses the currently typed path (works even when unsaved), and failures show the reason |
 
@@ -86,14 +100,14 @@ whole config; fields not listed fall back to defaults):
 
 This package is a **bundle**: an npm package carrying a configuration layer — `dsh.bundle` in
 `package.json` declares the patch file (`cordis.patch.yml`), and a profile activates the plugin row
-by package name when installed. Published to the **npm registry** (`dsh-auto-open-web@0.1.4`) and
+by package name when installed. Published to the **npm registry** (`dsh-auto-open-web@0.1.5`) and
 **GitHub** (https://github.com/jinsiyu/dsh-auto-open-web, `main` branch).
 
 ### Packaging
 
 ```bash
 cd dsh-auto-open-web
-pnpm pack          # the prepack hook compiles the WebView2 host first (dotnet publish), producing dsh-auto-open-web-0.1.4.tgz
+pnpm pack          # the prepack hook compiles the WebView2 host first (dotnet publish), producing dsh-auto-open-web-0.1.5.tgz
 ```
 
 ### Installation (pick one)
@@ -108,7 +122,7 @@ dsh plugin --profile web add C:\path\to\dsh-auto-open-web
 **Option 2: tarball (published artifact, recommended for delivery; no build permission needed)**
 
 ```bash
-dsh plugin --profile web add ./dsh-auto-open-web-0.1.4.tgz
+dsh plugin --profile web add ./dsh-auto-open-web-0.1.5.tgz
 ```
 
 **Option 3: npm registry (after publishing)**
@@ -145,34 +159,30 @@ without touching the package.
 
 ### Notes
 
-- **DSH version requirement**: this plugin supports **dsh `>=0.1.0-rc.7 <0.2.0`** (declared as an
-  optional peer, provided by the DSH deployment, no install warnings). `settings.plugin.item`
-  became a keyed slot in that release; the card registers with both `id` and `key` so it mounts on
-  both old and new dsh generations. Below the supported range the host logs a clear error at
-  startup (pointing to a dsh upgrade) and the card may not mount.
+- **Zero dependencies**: every runtime dependency is provided by the **DSH deployment** and
+  declared as an optional peer (no install warnings):
+  - `@deepseek-ai/dsh` (the host; declares the compatibility range `>=0.1.0-rc.7 <0.2.0` —
+    `settings.plugin.item` became a keyed slot in that release, registration requires
+    `options.key`; no runtime version check is performed)
+  - `@deepseek-ai/schemastery` (config schema validator; resolved at runtime: normal import
+    first, then the DSH deployment copy under the Windows global npm layout)
+  - `koffi` (Windows only: Job Object / process verification / native file dialog; same runtime
+    deployment-copy resolution, failure only degrades)
+  So no platform ever hits build-script blocking — HarmonyOS and other environments without
+  koffi prebuilds install out of the box; posix platforms use the posix fallback adapter (browser
+  mode works; webview2 / native dialog unavailable), and the platform adapter is loaded
+  conditionally so win32.js is never evaluated on posix.
+- This package does not depend on `@deepseek-ai/cordis` (zero code references; the plugin identity
+  comes from the `dsh.bundle` / `dsh.client` fields, and Cordis is provided by the DSH deployment
+  at runtime), so installation produces no peer warnings.
 - **The npm package already contains the compiled WebView2 host** (built by the prepack hook before
   publishing); the **GitHub `main` branch and source-checkout installs do not** include
   `host-publish/` (build artifacts are .gitignore'd): for webview2 mode, run
   `pnpm run build:host` inside `node_modules/dsh-auto-open-web` first (requires the .NET SDK);
   browser mode needs no build.
-- This package does not depend on `@deepseek-ai/cordis` (zero code references; the plugin identity
-  comes from the `dsh.bundle` / `dsh.client` fields, and Cordis is provided by the DSH deployment
-  at runtime), so installation produces no peer warnings.
-- **Zero koffi dependency declared**: koffi (driving Windows Job Object / process verification /
-  native file dialog) ships with the **DSH deployment itself** (the official native picker
-  `@deepseek-ai/dsh-host-directory-picker-native` depends on koffi, so the deployment always has
-  it). The plugin resolves it at runtime: normal resolution (profile-installed or manual
-  `pnpm add koffi`) first, then the DSH deployment copy under the Windows global npm layout; if
-  resolution fails, capabilities only degrade (Job Object unavailable → exit / pre-launch cleanup
-  still apply; process verification skipped; native dialog unavailable) with a log entry.
-  **Therefore no platform ever hits koffi build-script blocking** — HarmonyOS and other
-  environments without koffi prebuilds install out of the box, with no `pnpm-workspace.yaml` or
-  other configuration needed; posix platforms use the posix fallback adapter (browser mode works;
-  webview2 / native dialog unavailable), and the platform adapter is loaded conditionally so
-  win32.js is never evaluated on posix.
 - If installing by editing `package.json` manually (not via the `dsh plugin` command), you must add
   both the `dependencies` entry and `dsh.profile.bundles`; when using a local `file:` dependency,
-  `dsh web` normalizes `file:` to `^0.1.4` at startup, which does not affect runtime.
+  `dsh web` normalizes `file:` to `^0.1.5` at startup, which does not affect runtime.
 
 ## Icons
 
@@ -187,8 +197,8 @@ without touching the package.
 ## Platform support
 
 - Windows: `windowKind: webview2` (default, DSH taskbar icon) or `windowKind: browser` (dedicated
-  `--app` instance); nothing opens if the selected type is unavailable
-- macOS/Linux: `webview2` mode is unavailable (logs and opens nothing); `browser` mode is untested
+  `--app` instance); falls back to the default-browser handoff (official open method, plain tab) if the selected type is unavailable
+- macOS/Linux: `webview2` mode is unavailable (falls back to the default-browser handoff); `browser` mode is untested
   (dedicated `--app` instance)
 
 ## Edge cases

package/README.md

@@ -27,8 +27,13 @@ dsh web profile 启动后自动打开独立应用窗口（或网页标签页）
    依赖任何退出事件。另有两层兜底：DSH 正常退出时 `process 'exit'` 结束该
    专用实例的整个进程树（仅匹配我们自己的 user-data-dir，不影响正常浏览器）；
    DSH 被强杀后的残留实例由下次启动前预清理。
-3. 所选类型不可用时（宿主缺失/浏览器找不到/非 Windows 等）→ **不打开任何东西**
-   （记录日志），不自动交叉兜底。
+3. **默认浏览器打开（最后兜底）**：所选类型不可用时（宿主缺失/浏览器找不到/
+   非 Windows 等）→ **降级为官方同款的默认浏览器交接**——把 URL 交给操作系统
+   默认浏览器（普通标签页），保证用户至少能打开 GUI。实现与 DSH 核心
+   （web-app bundle）启动时打开网页的方式一致：优先用 DSH 部署自带的
+   `open` 包（win32 = PowerShell Start，darwin = `open`，linux = `xdg-open`），
+   `open` 包不可用时退回平台原生拉起（win32 = `cmd /c start`，darwin = `open`，
+   linux = `xdg-open`）。
    `appWindow: false` 时不自动打开任何窗口。
 
 端口取自 webServer 服务的真实监听值（`--port` 自定义、`--port 0` 均正确）。
@@ -38,6 +43,12 @@ webServer 插件 `Service.init()` 完成（HTTP socket 已绑定、端口已写
 两种模式都随 DSH 退出而关闭：webview2 宿主监视父进程；browser 专用实例由
 Job Object（强杀也生效）+ 退出清理结束进程树。
 
+> **与 DSH 核心浏览器交接的关系**：DSH 核心（web-app bundle）默认会在启动后
+> 用系统默认浏览器打开 GUI（`openBrowser: true`，普通标签页/窗口，非独立窗口）。
+> 安装本插件后，插件的 bundle 补丁会把 `web-runtime.openBrowser` 置为 `false`，
+> 只保留插件的独立应用窗口，不再弹出普通浏览器页面；卸载插件后恢复默认行为
+> （临时关闭也可用 `dsh web --no-open`）。
+
 ### WebView2 宿主要求（仅 webview2 模式）
 
 - Windows 10 1803+ / Windows 11 / Windows Server 2016+
@@ -54,8 +65,9 @@ Job Object（强杀也生效）+ 退出清理结束进程树。
    `browserPath`（浏览器可执行文件，支持「浏览」原生对话框选择；位于窗口类型
    下方，仅选择「浏览器应用窗口」时使能）、
    `exitOnWindowClose`（窗口关闭时退出 DSH，默认关闭）。
-   保存后持久化到
-   settings 文档（命名空间 `auto-open-web`），首次保存后设置值优先于行配置。
+   保存后经**官方 settings 域**（客户端 settingsScope）持久化到
+   settings 文档（命名空间 `auto-open-web`），首次保存后设置值优先于行配置；
+   宿主仅保留「浏览」「测试」辅助路由（官方通道无法覆盖的能力）。
 2. **行配置**（cordis.patch.yml）：作为启动种子，设置卡片保存前生效。
 
 | 字段 | 默认 | 说明 |
@@ -79,14 +91,14 @@ Job Object（强杀也生效）+ 退出清理结束进程树。
 
 本包是**组合包(bundle)**:一个附带配置层的 npm 包——`package.json` 的
 `dsh.bundle` 声明配置层文件(`cordis.patch.yml`),profile 安装它时按包名激活
-插件行。已发布到 **npm registry**(`dsh-auto-open-web@0.1.4`)与 **GitHub**
+插件行。已发布到 **npm registry**(`dsh-auto-open-web@0.1.5`)与 **GitHub**
 （https://github.com/jinsiyu/dsh-auto-open-web，main 分支）。
 
 ### 打包
 
 ```bash
 cd dsh-auto-open-web
-pnpm pack          # prepack 钩子自动先编译 WebView2 宿主(dotnet publish),产出 dsh-auto-open-web-0.1.4.tgz
+pnpm pack          # prepack 钩子自动先编译 WebView2 宿主(dotnet publish),产出 dsh-auto-open-web-0.1.5.tgz
 ```
 
 ### 安装方式(任选其一)
@@ -101,7 +113,7 @@ dsh plugin --profile web add C:\path\to\dsh-auto-open-web
 **方式二:tarball(发布产物,推荐交付;无需构建授权)**
 
 ```bash
-dsh plugin --profile web add ./dsh-auto-open-web-0.1.4.tgz
+dsh plugin --profile web add ./dsh-auto-open-web-0.1.5.tgz
 ```
 
 **方式三:npm 注册表(发布后)**
@@ -137,27 +149,25 @@ dsh plugin --profile web remove dsh-auto-open-web   # 同时移除依赖与对
 
 ### 注意事项
 
-- **dsh 版本要求**:本插件支持 **dsh `>=0.1.0-rc.7 <0.2.0`**(peer 声明,由 DSH 部署
-  提供,安装无警告)。`settings.plugin.item` 自该版本起为 keyed 插槽,卡片注册
-  同时提供 `id` 与 `key` 以兼容新旧两代 dsh;低于支持范围时宿主启动会记录
-  明确错误日志(提示升级 dsh),卡片可能无法挂载。
+- **本包零 dependencies**:所有运行时依赖均由 **DSH 部署提供**,以 optional
+  peer 声明(安装无警告):
+  - `@deepseek-ai/dsh`(宿主,声明兼容范围 `>=0.1.0-rc.7 <0.2.0`,
+    `settings.plugin.item` 自该版本起为 keyed 插槽,注册需 `options.key`;
+    不做运行时版本检测)
+  - `@deepseek-ai/schemastery`(配置 schema 校验器;运行时解析:常规 import
+    优先,其次 Windows 全局 npm 布局下的 DSH 部署副本)
+  - `koffi`(仅 Windows 的 Job Object / 进程校验 / 原生对话框;同样运行时
+    解析部署副本,失败仅降级)
+  因此任何平台安装都无构建拦截——鸿蒙等无 koffi 预编译的环境开箱即装;
+  posix 平台走 posix 降级适配器(browser 模式可用;webview2 / 原生对话框
+  不可用),且平台适配器按平台条件加载,posix 上完全不求值 win32.js。
 - **npm 包已含 WebView2 宿主编译产物**(prepack 编译后发布);**GitHub
   main 分支与源码 checkout 方式不含** `host-publish/`(构建产物被
   .gitignore 忽略):webview2 模式需先在 `node_modules/dsh-auto-open-web`
   下执行 `pnpm run build:host` 生成(需 .NET SDK);browser 模式无需构建。
-- **本包零 koffi 依赖声明**:koffi(驱动 Windows 的 Job Object / 进程校验 /
-  原生对话框)由 **DSH 部署自带**(官方原生选择器
-  `@deepseek-ai/dsh-host-directory-picker-native` 依赖 koffi,部署必带),
-  插件运行时解析:常规解析(profile 已装/手动 `pnpm add koffi`)优先,
-  其次 Windows 全局 npm 布局下的 DSH 部署副本;解析失败仅降级(Job
-  Object 不可用 → 退出/预清理兜底;进程校验跳过;对话框不可用)并记录
-  日志。**因此任何平台安装都无 koffi 构建拦截**——鸿蒙等无 koffi
-  预编译的环境开箱即装,无需 `pnpm-workspace.yaml` 等额外配置;posix
-  平台走 posix 降级适配器(browser 模式可用;webview2 / 原生对话框
-  不可用),且平台适配器按平台条件加载,posix 上完全不求值 win32.js。
 - 若手动编辑 `package.json` 安装(不经 dsh plugin 命令),需同时追加
   `dependencies` 与 `dsh.profile.bundles` 两项;使用本地 `file:` 依赖时
-  `dsh web` 启动会把 `file:` 规范化成 `^0.1.4`,运行时不受影响。
+  `dsh web` 启动会把 `file:` 规范化成 `^0.1.5`,运行时不受影响。
 
 ## 图标
 
@@ -170,8 +180,8 @@ dsh plugin --profile web remove dsh-auto-open-web   # 同时移除依赖与对
 
 ## 平台支持
 
-- Windows：`windowKind: webview2`（默认，任务栏图标 DSH）或 `windowKind: browser`（--app 专用实例）；所选类型不可用则不打开
-- macOS/Linux：`webview2` 模式不可用（会记录日志不打开）；`browser` 模式未测试（--app 专用实例）
+- Windows：`windowKind: webview2`（默认，任务栏图标 DSH）或 `windowKind: browser`（--app 专用实例）；所选类型不可用时降级为默认浏览器打开（官方同款，普通标签页）
+- macOS/Linux：`webview2` 模式不可用（降级为默认浏览器打开）；`browser` 模式未测试（--app 专用实例）
 
 ## 边界情况
 

package/cordis.patch.yml

@@ -3,3 +3,15 @@
 - insert:
     - id: auto-open-web
       name: dsh-auto-open-web
+
+# 本插件用独立应用窗口打开 GUI,替代 DSH 核心(web-app bundle)启动后的
+# 默认浏览器交接,避免同时弹出普通浏览器页面(核心的 openBrowser 默认 true,
+# 会以普通标签页/窗口打开 GUI;插件窗口才是"独立应用窗口")。
+# 补丁按 id 整体替换 config,故逐键重述 web-runtime 原配置,仅把
+# openBrowser 置为 false(trustedHosts 保留 webStartup 提供的原表达式)。
+- id: web-runtime
+  config:
+    openBrowser: false
+    printUrl: true
+    surfaceContext: true
+    trustedHosts: !!js ctx.webStartup.trustedHosts

package/host-publish/DshAppWindow.deps.json

@@ -6,7 +6,7 @@
   "compilationOptions": {},
   "targets": {
     ".NETCoreApp,Version=v10.0": {
-      "DshAppWindow/0.1.4": {
+      "DshAppWindow/0.1.5": {
         "dependencies": {
           "Microsoft.Web.WebView2": "1.0.3124.44",
           "Microsoft.Web.WebView2.Core": "1.0.3124.44",
@@ -63,7 +63,7 @@
     }
   },
   "libraries": {
-    "DshAppWindow/0.1.4": {
+    "DshAppWindow/0.1.5": {
       "type": "project",
       "serviceable": false,
       "sha512": ""