Merge pull request #522 from wang-kaopu/fix/517-client-ssh-open

fix(editor): open SSH remote editor links on the client

docs/plans/2026-08-22-open-with-menu-design.md

@@ -87,10 +87,12 @@ Cursor             (SSH)
 - 校验：`reveal` 路径必须绝对（`requireAbsolute`）；`url` 必须是 `scheme://` 自定义协议（拒绝 http/https）。
 - **Windows 平台命令为约定实现，需在 Windows 实机验证**（本机为 macOS；CI 覆盖 linux）。
 
+**实施偏差（2026-09，#517 / PR #522）**：SSH 远程编辑器链接**不再经宿主路由执行**。DSH 部署在无头远端服务器时，宿主侧 `xdg-open` 无 DISPLAY/无编辑器，`vscode://` 静默失败。`api.openExternal`（`src/client/api.ts`）现把 `<scheme>://vscode-remote/ssh-remote+…` 形态的 URL 在浏览器客户端同步触发 `window.location.assign`（处于用户点击链内，外部协议交给本机编辑器经 Remote-SSH 打开远端文件）；reveal 与本地编辑器 URL 仍走本节宿主路由。普通浏览器可处理自定义协议；禁止/未处理 `vscode://` 的 WebView 壳客户端需各自适配（见 #517 补充信息）。
+
 ## 已知限制
 
 - 路径含 `#`/`?` 的文件名经 URL 打开可能被浏览器当作 fragment/query（不处理，注释说明）。
-- 编辑器未安装/协议未注册：由 OS 弹提示或静默失败，不做安装检测。
+- 编辑器未安装/协议未注册：由 OS 弹提示或静默失败，不做安装检测。SSH 客户端分支同理——浏览器端 `location.assign` 无法探测协议 handler 是否存在，仍返回 `{started: true}`。
 - 自定义编辑器仅支持 URL 模板式，不支持 CLI 命令式；无 `{dir}` 占位符。
 - Linux reveal 退化为打开所在目录（精确 select 需要各文件管理器私有协议）。
 - SSH 模式为**全局**（非每会话）：DSH 无远程会话概念，文件树路径即宿主路径；该模型对应"DSH 跑在远端开发机上"的场景。
@@ -99,6 +101,7 @@ Cursor             (SSH)
 
 - `tests/open-with.spec.ts`：解析容错、目标解析与 SSH 过滤、URL 构建（本地/SSH/custom/坏模板）、校验器。
 - `tests/open-external.spec.ts`：三平台命令表、URL 校验、spawn 前校验。
+- `tests/open-external-client.spec.ts`（#522）：SSH remote URL 客户端分流（不触 fetch）、本地/reveal/http(s) 留宿主、导航抛错 reject。
 - `tests/file-tree-open-with.spec.tsx`（jsdom）：右键 → 子菜单/图钉；pin 不选中不关闭；选子项回调关闭菜单；SSH 标签后缀；未接线隐藏。
 - `tests/open-with-settings.spec.tsx`：SSH 输入、添加/删除（删除剪枝 pinned）、无效提示、VSCode 系开关。
 - `tests/side-card-section.spec.tsx`：`SettingsBody` 行列表 + render 共存、仅 render 时不变。

src/client/EditorHost.tsx

@@ -192,10 +192,11 @@ export function EditorHost(props: {
   }
 
   /** The context menu's "open with" action: reveal the path in the OS file
-   *  manager, or hand the target's URL (a local `file` URL, or the SSH-remote
-   *  form for VSCode-family editors in remote mode) to the host's external
-   *  opener. Failures are logged only — a missing handler is the OS's
-   *  dialog, not a sidebar error. */
+   *  manager, or hand the target's URL to its opener — local `file` URLs go
+   *  to the host's external opener, while the SSH-remote form for
+   *  VSCode-family editors launches on the browser/client machine (see
+   *  api.openExternal). Failures are logged only — a missing handler is the
+   *  OS's/browser's dialog, not a sidebar error. */
   const openWith = (targetId: string, absolute: string): void => {
     const target = openWithTargets.find(item => item.id === targetId)
     if (target === undefined) return

src/client/api.ts

@@ -216,6 +216,51 @@ function gitPayload(scope: SessionScope, worktree: string | undefined, extra: Re
   return scopePayload(scope, { ...(worktree !== undefined && worktree !== '' ? { worktree } : {}), ...extra })
 }
 
+/** One external-open request from the file tree. */
+type OpenExternalPayload =
+  | { action: 'reveal'; path: string }
+  | { action: 'url'; url: string }
+
+/** The host route's success shape. */
+type OpenExternalResult = { started: boolean }
+
+/**
+ * Remote VSCode-family URLs must be consumed on the browser/client machine:
+ * the DSH host can be a headless remote server with no editor or DISPLAY.
+ * Local editor URLs and reveal actions still belong to the host opener.
+ */
+function shouldOpenExternalOnClient(payload: OpenExternalPayload): payload is { action: 'url'; url: string } {
+  if (payload.action !== 'url') return false
+  let parsed: URL
+  try {
+    parsed = new URL(payload.url)
+  } catch {
+    return false
+  }
+  return parsed.protocol !== 'http:'
+    && parsed.protocol !== 'https:'
+    && parsed.hostname === 'vscode-remote'
+    && parsed.pathname.startsWith('/ssh-remote+')
+}
+
+/**
+ * Dispatch an external-open request to the correct machine. SSH remote-editor
+ * URLs stay in the synchronous user-click chain and navigate the client so
+ * its registered vscode:// / cursor:// handler can launch. Everything else
+ * keeps using the DSH host route.
+ */
+function openExternal(payload: OpenExternalPayload): Promise<OpenExternalResult> {
+  if (!shouldOpenExternalOnClient(payload)) {
+    return call<OpenExternalResult>('open.external', payload)
+  }
+  try {
+    window.location.assign(payload.url)
+    return Promise.resolve({ started: true })
+  } catch (error) {
+    return Promise.reject(error)
+  }
+}
+
 /** The sidebar API surface (session scope threaded through every call). */
 export const api = {
   sessionCwd: (scope: SessionScope, signal?: AbortSignal) =>
@@ -350,12 +395,10 @@ export const api = {
    *  check; see the host's browser.probe route). */
   browserProbe: (url: string, signal?: AbortSignal) =>
     call<BrowserProbeResult>('browser.probe', { url }, signal),
-  /** External open for the file tree's "open with" menu: reveal a path in
-   *  the OS file manager, or hand a custom-scheme URL (vscode://, cursor://,
-   *  zed://, custom editors) to its registered handler. The host launches
-   *  the platform opener (argv, no shell). */
-  openExternal: (payload: { action: 'reveal'; path: string } | { action: 'url'; url: string }) =>
-    call<{ started: boolean }>('open.external', payload),
+  /** External open for the file tree's "open with" menu. Remote SSH editor
+   *  URLs are launched on the browser/client machine; reveal and local URLs
+   *  keep using the host's platform opener. */
+  openExternal,
 }
 
 /** Absolute URL of the media route for one path (images only). */

tests/open-external-client.spec.ts

@@ -0,0 +1,98 @@
+/**
+ * Client/host routing for the file tree's external-open action. Remote
+ * VSCode-family SSH URLs must launch on the browser machine, while local
+ * editor URLs and reveal actions keep using the DSH host opener.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { api } from '../src/client/api.ts'
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+function hostOk(): ReturnType<typeof vi.fn> {
+  return vi.fn(async () => ({
+    ok: true,
+    status: 200,
+    json: async () => ({ ok: true, value: { started: true } }),
+  }))
+}
+
+describe('api.openExternal', () => {
+  it('launches an SSH remote-editor URL on the client without calling the host', async () => {
+    const assign = vi.fn()
+    const fetchMock = hostOk()
+    vi.stubGlobal('window', { location: { assign } })
+    vi.stubGlobal('fetch', fetchMock)
+    const url = 'vscode://vscode-remote/ssh-remote+dev/home/u/f.ts'
+
+    await expect(api.openExternal({ action: 'url', url })).resolves.toEqual({ started: true })
+    expect(assign).toHaveBeenCalledOnce()
+    expect(assign).toHaveBeenCalledWith(url)
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+
+  it('launches Cursor/custom VSCode-family SSH URLs on the client too', async () => {
+    const assign = vi.fn()
+    const fetchMock = hostOk()
+    vi.stubGlobal('window', { location: { assign } })
+    vi.stubGlobal('fetch', fetchMock)
+
+    await api.openExternal({
+      action: 'url',
+      url: 'cursor://vscode-remote/ssh-remote+dev/home/u/f.ts',
+    })
+    await api.openExternal({
+      action: 'url',
+      url: 'myfork://vscode-remote/ssh-remote+dev/home/u/f.ts',
+    })
+
+    expect(assign).toHaveBeenCalledTimes(2)
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+
+  it('keeps local editor URLs on the host opener', async () => {
+    const assign = vi.fn()
+    const fetchMock = hostOk()
+    vi.stubGlobal('window', { location: { assign } })
+    vi.stubGlobal('fetch', fetchMock)
+
+    await expect(api.openExternal({
+      action: 'url',
+      url: 'vscode://file//tmp/a.ts',
+    })).resolves.toEqual({ started: true })
+
+    expect(assign).not.toHaveBeenCalled()
+    expect(fetchMock).toHaveBeenCalledOnce()
+    expect(fetchMock.mock.calls[0]?.[0]).toBe('/sidebar/api/open.external')
+  })
+
+  it('keeps reveal actions and http(s) lookalikes on the host opener', async () => {
+    const assign = vi.fn()
+    const fetchMock = hostOk()
+    vi.stubGlobal('window', { location: { assign } })
+    vi.stubGlobal('fetch', fetchMock)
+
+    await api.openExternal({ action: 'reveal', path: '/tmp/a.ts' })
+    await api.openExternal({
+      action: 'url',
+      url: 'https://vscode-remote/ssh-remote+dev/home/u/f.ts',
+    })
+
+    expect(assign).not.toHaveBeenCalled()
+    expect(fetchMock).toHaveBeenCalledTimes(2)
+  })
+
+  it('returns a rejected promise when client navigation throws', async () => {
+    const error = new Error('navigation failed')
+    const fetchMock = hostOk()
+    vi.stubGlobal('window', { location: { assign: vi.fn(() => { throw error }) } })
+    vi.stubGlobal('fetch', fetchMock)
+
+    await expect(api.openExternal({
+      action: 'url',
+      url: 'vscode://vscode-remote/ssh-remote+dev/home/u/f.ts',
+    })).rejects.toBe(error)
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+})