dsh-builtin-browser 0.3.1 → 0.4.1

package/desktop-bridge/install.mjs

@@ -8,31 +8,92 @@
  * expressed as something replayable rather than as a one-off edit — re-run this
  * after every desktop upgrade.
  *
+ * TWO LAYOUTS
+ * DSH Desktop ships in two shapes, and they need different work:
+ *
+ *   unpacked  `<install>/resources/app/lib/main.js` is a real file. The
+ *             long-standing path: copy the module next to main.js and append a
+ *             guarded import to it.
+ *
+ *   packed    `<install>/resources/app.asar` holds the whole app (main.js is
+ *             inside the archive) and `resources/app.asar.unpacked` holds the
+ *             entries marked `unpacked`, i.e. the native modules. The official
+ *             Windows build is packed — where this script used to fail with
+ *             "not a DSH Desktop install" on a perfectly good installation,
+ *             because it only ever looked for the unpacked main.js.
+ *
+ * HOW THE PACKED LAYOUT IS HANDLED
+ * Electron loads `app.asar` in preference to `app/`, and a directory only wins
+ * once the archive is not there. Rewriting the archive in place is not an
+ * option either: the official build enables the
+ * `EnableEmbeddedAsarIntegrityValidation` fuse (measured: enabled), so a
+ * modified app.asar is a broken app. The archive is therefore never touched:
+ *
+ *   1. extract `app.asar` into `resources/app`, taking the real bytes of
+ *      `unpacked` entries from `resources/app.asar.unpacked` (a straight
+ *      archive walk would leave the native modules as empty stubs);
+ *   2. install the bridge into that tree exactly as in the unpacked layout;
+ *   3. rename `app.asar` to `app.asar.before-bridge`, so Electron falls back to
+ *      the directory that was just built.
+ *
+ * The trigger is the ARCHIVE's presence, not the directory's absence. A desktop
+ * update writes a new `app.asar` and leaves any earlier extraction lying around
+ * (the updater does not know about that directory), so keying off "the tree is
+ * missing" would patch the stale tree while Electron keeps loading the archive —
+ * a run that reports success with the bridge dead. Whenever the archive is
+ * there it is the app, so the tree is rebuilt from it.
+ *
+ * `--revert` moves the archive back and restores the pristine main.js. The
+ * extracted tree then becomes inert (the archive wins again) and can be deleted.
+ *
  * WHAT IT DOES (idempotent)
  *   1. copies `plugin-browser-bridge.js` next to the app's main bundle;
  *   2. appends a guarded import to `lib/main.js` that starts it after `whenReady`,
  *      keeping a pristine `main.js.before-bridge` backup the first time;
- *   3. does nothing if the import is already present.
+ *   3. does nothing if the import is already present;
+ *   4. keeps `dsh <args>` working: the Desktop CLI launcher and the CLI's own
+ *      runtime lookup both spell `app.asar` out loud and both break once the
+ *      archive is moved aside, so both are patched (each with its own
+ *      `.before-bridge` backup) and `--revert` restores them.
  *
  * USAGE
- *   node apps/desktop/bridge/install.mjs [path-to-DeepSeek-Harness-install]
+ *   node desktop-bridge/install.mjs [path-to-DeepSeek-Harness-install]
  * Default path: %LOCALAPPDATA%\Programs\DeepSeek Harness
- * Pass --revert to restore the pre-bridge main.js instead.
+ * Pass --revert to restore the pre-bridge state instead.
  */
-import { copyFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { copyFileSync, existsSync, mkdirSync, openSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
 
 const DEFAULT_INSTALL = join(process.env.LOCALAPPDATA ?? '', 'Programs', 'DeepSeek Harness')
 const args = process.argv.slice(2)
 const revert = args.includes('--revert')
 const installRoot = args.find(arg => !arg.startsWith('--')) ?? DEFAULT_INSTALL
 
-const appDir = join(installRoot, 'resources', 'app')
+const resourcesDir = join(installRoot, 'resources')
+const appDir = join(resourcesDir, 'app')
+const asarPath = join(resourcesDir, 'app.asar')
+const asarMoved = `${asarPath}.before-bridge`
 const mainPath = join(appDir, 'lib', 'main.js')
 const bridgeTarget = join(appDir, 'lib', 'plugin-browser-bridge.js')
 const bridgeSource = join(import.meta.dirname, 'plugin-browser-bridge.js')
 const backupPath = `${mainPath}.before-bridge`
 
+// Moving the archive aside breaks two more places that spell `app.asar` out
+// loud, and both are used by `dsh <args>` (the Desktop CLI launcher and the
+// plugin manager behind it), so they are patched here and restored by --revert:
+//
+//   runtime/cli/bin/dsh.cmd                    launches the CLI by that path
+//   dsh/.../dsh-desktop-host/lib/cli.js        locates `runtime` by that name
+//
+// Without them the CLI dies with MODULE_NOT_FOUND even though the app itself
+// runs fine (the shell resolves everything through app.getAppPath()).
+const cliShimPath = join(resourcesDir, 'runtime', 'cli', 'bin', 'dsh.cmd')
+const cliShimBackup = `${cliShimPath}.before-bridge`
+const hostCliPath = join(appDir, 'dsh', 'node_modules', '@deepseek-ai', 'dsh-desktop-host', 'lib', 'cli.js')
+const hostCliBackup = `${hostCliPath}.before-bridge`
+const CLI_SHIM_MARKER = 'dsh-builtin-browser: resolve the app directory'
+const HOST_CLI_MARKER = 'dsh-builtin-browser: recognize an unpacked `app` directory'
+
 /** The exact block appended to main.js. Keep it recognisable: idempotence and
  *  reverting both key off this marker. */
 const MARKER = '// dsh-builtin-browser: hand the plugin a way to drive the sidebar'
@@ -54,25 +115,225 @@ app.whenReady().then(async () => {
 });
 `
 
-if (!existsSync(mainPath)) {
-  console.error(`not a DSH Desktop install (no ${mainPath})`)
+/**
+ * Parse an asar header — a Chromium pickle holding
+ * `[payloadSize][jsonLength][json…]`, preceded by an 8-byte outer pickle.
+ * @param file - the archive path.
+ * @returns the parsed header tree plus the offset where file content starts.
+ */
+function readAsarHeader(file) {
+  const fd = openSync(file, 'r')
+  const sizeBuf = Buffer.alloc(8)
+  readSync(fd, sizeBuf, 0, 8, 0)
+  const headerSize = sizeBuf.readUInt32LE(4)
+  const headerBuf = Buffer.alloc(headerSize)
+  readSync(fd, headerBuf, 0, headerSize, 8)
+  const jsonLength = headerBuf.readUInt32LE(4)
+  const header = JSON.parse(headerBuf.toString('utf8', 8, 8 + jsonLength))
+  return { fd, header, contentBase: 8 + headerSize }
+}
+
+/**
+ * Write one asar tree to disk, taking `unpacked` entries from the sibling
+ * `.unpacked` directory — their bytes are not in the archive.
+ * @param asar - the archive path.
+ * @param outDir - directory to extract into.
+ * @returns file and byte counts, and how many entries came from `.unpacked`.
+ */
+function extractAsar(asar, outDir) {
+  const { fd, header, contentBase } = readAsarHeader(asar)
+  const unpackedRoot = `${asar}.unpacked`
+  let files = 0
+  let bytes = 0
+  let unpackedFiles = 0
+  const walk = (node, prefix) => {
+    for (const [name, entry] of Object.entries(node.files ?? {})) {
+      const relativePath = prefix === '' ? name : `${prefix}/${name}`
+      const target = join(outDir, ...relativePath.split('/'))
+      if (entry.files) {
+        mkdirSync(target, { recursive: true })
+        walk(entry, relativePath)
+        continue
+      }
+      mkdirSync(dirname(target), { recursive: true })
+      if (entry.unpacked) {
+        const source = join(unpackedRoot, ...relativePath.split('/'))
+        if (!existsSync(source)) throw new Error(`unpacked entry is missing: ${source}`)
+        copyFileSync(source, target)
+        unpackedFiles += 1
+      } else {
+        const buffer = Buffer.alloc(entry.size)
+        readSync(fd, buffer, 0, entry.size, contentBase + Number(entry.offset))
+        writeFileSync(target, buffer)
+      }
+      const actual = statSync(target).size
+      if (actual !== entry.size) throw new Error(`size mismatch for ${relativePath}: header ${entry.size}, wrote ${actual}`)
+      files += 1
+      bytes += actual
+    }
+  }
+  mkdirSync(outDir, { recursive: true })
+  walk(header, '')
+  return { files, bytes, unpackedFiles }
+}
+
+/**
+ * Make the Desktop CLI launcher resolve the app directory instead of spelling
+ * `app.asar` out loud.
+ *
+ * `resources/runtime/cli/bin/dsh.cmd` is what the `dsh` command on PATH calls,
+ * and it launches the CLI through an `app.asar\…` path. Once the archive is
+ * moved aside that path is gone, so `dsh <args>` dies with MODULE_NOT_FOUND
+ * while the app itself keeps working (the shell resolves everything through
+ * `app.getAppPath()`). The patch touches only the app-directory fragment: the
+ * launcher keeps its own spelling of everything else, including the executable
+ * name, so a build whose binary is named differently still works.
+ *
+ * @returns what happened, for the install log.
+ */
+function patchCliShim() {
+  if (!existsSync(cliShimPath)) return 'launcher not present (skipped)'
+  const text = readFileSync(cliShimPath, 'utf8')
+  if (text.includes(CLI_SHIM_MARKER)) return 'already patched'
+  if (!/%~dp0(?:\.\.\\)+app\.asar\\dsh\\/.test(text)) return 'unexpected launcher shape (skipped)'
+  if (!existsSync(cliShimBackup)) copyFileSync(cliShimPath, cliShimBackup)
+  const eol = text.includes('\r\n') ? '\r\n' : '\n'
+  const setLocal = /^.*setlocal.*$/m.exec(text)
+  const injection = [
+    `rem ${CLI_SHIM_MARKER} (resources\\app when the bridge is installed,`,
+    'rem resources\\app.asar on a stock installation).',
+    'set "DSH_APP=%~dp0..\\..\\..\\app"',
+    'if not exist "%DSH_APP%\\dsh\\node_modules\\@deepseek-ai\\dsh-desktop-host\\lib\\cli.js" set "DSH_APP=%~dp0..\\..\\..\\app.asar"',
+  ].join(eol)
+  const withVariables = setLocal === null
+    ? `${injection}${eol}${text}`
+    : text.replace(setLocal[0], `${setLocal[0]}${eol}${injection}`)
+  writeFileSync(cliShimPath, withVariables.replace(/%~dp0(?:\.\.\\)+app\.asar\\dsh\\/, '%DSH_APP%\\dsh\\'))
+  return 'patched'
+}
+
+/**
+ * Teach the Desktop CLI where its `runtime` directory is when the app is an
+ * unpacked `app` directory rather than `app.asar`.
+ *
+ * `dsh-desktop-host/lib/cli.js` derives the directory that holds pnpm as
+ * `dirname(runtimeArchivePath(runtimeDir) ?? runtimeDir)`, and
+ * `runtimeArchivePath` only recognises a parent literally named `app.asar`.
+ * With the app at `resources/app` that falls back to one level too few and
+ * resolves `resources/app/runtime`, which does not exist — so the plugin
+ * manager behind `dsh plugin …` cannot start.
+ *
+ * @returns what happened, for the install log.
+ */
+function patchHostCli() {
+  if (!existsSync(hostCliPath)) return 'cli.js not present (skipped)'
+  const text = readFileSync(hostCliPath, 'utf8')
+  if (text.includes(HOST_CLI_MARKER)) return 'already patched'
+  const before = '\tawait runDesktopCli(runtimeDir, join(dirname(runtimeArchivePath(runtimeDir) ?? runtimeDir), "runtime"));'
+  if (!text.includes(before)) return 'unexpected cli.js shape (skipped)'
+  if (!existsSync(hostCliBackup)) copyFileSync(hostCliPath, hostCliBackup)
+  const eol = text.includes('\r\n') ? '\r\n' : '\n'
+  const after = [
+    `\t// ${HOST_CLI_MARKER} as the app root,`,
+    '\t// so an installation whose app.asar was moved aside still finds its runtime.',
+    '\tconst cliOwnerDir = dirname(runtimeDir);',
+    '\tconst cliSupportRoot = basename(cliOwnerDir) === "app" || basename(cliOwnerDir) === "app.asar" ? dirname(cliOwnerDir) : cliOwnerDir;',
+    '\tawait runDesktopCli(runtimeDir, join(cliSupportRoot, "runtime"));',
+  ].join(eol)
+  writeFileSync(hostCliPath, text.replace(before, after))
+  return 'patched'
+}
+
+/** Apply both CLI compatibility patches and report them. */
+function installCliCompatibility() {
+  console.log(`  cli launcher:           ${patchCliShim()}`)
+  console.log(`  cli runtime resolution: ${patchHostCli()}`)
+}
+
+// The archive wins whenever it exists, so ITS presence — not the absence of the
+// directory — decides the layout. After a desktop update the archive is back
+// (a new build) while an older extraction is still lying around, and keying off
+// the directory would patch a tree that Electron never loads.
+const packedLayout = existsSync(asarPath)
+if (!existsSync(mainPath) && !existsSync(asarPath)) {
+  console.error('not a DSH Desktop install: neither')
+  console.error(`  ${mainPath}`)
+  console.error('nor')
+  console.error(`  ${asarPath}`)
+  console.error('exists. Pass the installation directory as the first argument.')
   process.exit(1)
 }
 
 if (revert) {
-  if (!existsSync(backupPath)) {
-    console.error(`nothing to revert: ${backupPath} does not exist`)
+  let reverted = false
+  if (existsSync(asarMoved)) {
+    if (existsSync(asarPath)) rmSync(asarPath, { force: true })
+    renameSync(asarMoved, asarPath)
+    console.log(`restored the app archive: app.asar.before-bridge -> app.asar`)
+    reverted = true
+  }
+  if (existsSync(backupPath)) {
+    copyFileSync(backupPath, mainPath)
+    console.log(`restored ${mainPath} from ${backupPath}`)
+    reverted = true
+  }
+  if (existsSync(cliShimBackup)) {
+    copyFileSync(cliShimBackup, cliShimPath)
+    console.log(`restored the CLI launcher: ${cliShimPath}`)
+    reverted = true
+  }
+  if (existsSync(hostCliBackup) && existsSync(dirname(hostCliPath))) {
+    copyFileSync(hostCliBackup, hostCliPath)
+    console.log(`restored the CLI runtime resolution: ${hostCliPath}`)
+    reverted = true
+  }
+  if (!reverted) {
+    console.error(`nothing to revert in ${installRoot}`)
     process.exit(1)
   }
-  copyFileSync(backupPath, mainPath)
-  console.log(`reverted ${mainPath} from ${backupPath}`)
+  console.log(`note: ${appDir} is inert while app.asar exists; delete it to reclaim ~350 MB`)
   process.exit(0)
 }
 
+if (packedLayout) {
+  const stale = existsSync(appDir)
+  const started = Date.now()
+  console.log(stale
+    ? `packed layout detected (${asarPath}); an earlier extraction is present and will be rebuilt`
+    : `packed layout detected (${asarPath})`)
+  if (stale) {
+    // Rebuild rather than merge: the tree has to describe THIS archive, and a
+    // merge would keep files the new build no longer ships. Removing it is safe
+    // here — the archive is present, so the app is not running from this
+    // directory, and a failure below leaves the archive in place and the
+    // installation working.
+    rmSync(appDir, { recursive: true, force: true })
+  }
+  console.log(`extracting into ${appDir} — this writes ~355 MB and can take a minute (measured: 8-55s)...`)
+  const result = extractAsar(asarPath, appDir)
+  const megabytes = (result.bytes / 1024 / 1024).toFixed(1)
+  const seconds = ((Date.now() - started) / 1000).toFixed(1)
+  console.log(`  extracted ${result.files} files / ${megabytes} MB` +
+    ` (${result.unpackedFiles} from app.asar.unpacked) in ${seconds}s`)
+  // A fresh extraction invalidates any earlier pristine copy: --revert has to be
+  // able to restore the main.js that belongs to THIS build.
+  copyFileSync(mainPath, backupPath)
+  try {
+    renameSync(asarPath, asarMoved)
+    console.log('moved the archive aside: app.asar -> app.asar.before-bridge')
+    console.log(`  Electron now loads ${appDir}; the archive is untouched, so the asar integrity fuse cannot trip`)
+  } catch (error) {
+    console.error(`could not move app.asar aside: ${String(error)}`)
+    console.error('close DSH Desktop completely and run this again.')
+    process.exit(1)
+  }
+}
+
 const current = readFileSync(mainPath, 'utf8')
 if (current.includes(MARKER)) {
   console.log('bridge already installed (main.js carries the marker); refreshing the module copy')
   copyFileSync(bridgeSource, bridgeTarget)
+  installCliCompatibility()
   process.exit(0)
 }
 
@@ -95,4 +356,5 @@ copyFileSync(bridgeSource, bridgeTarget)
 console.log(`installed bridge into ${appDir}`)
 console.log(`  module: ${bridgeTarget}`)
 console.log(`  patch:  ${mainPath} (+${SNIPPET.split('\n').length} lines)`)
+installCliCompatibility()
 console.log('restart DSH Desktop to activate it.')

package/desktop-bridge/plugin-browser-bridge.js

@@ -24,12 +24,24 @@
 import { createServer } from 'node:net'
 import { randomBytes } from 'node:crypto'
 import { writeFileSync, mkdirSync } from 'node:fs'
+import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { app, webContents } from 'electron'
 
-/** Absolute path of the endpoint file the plugin reads. */
+/**
+ * Absolute path of the endpoint file the plugin reads.
+ *
+ * The fallback has to match the plugin's own (`process.env.DSH_HOME ??
+ * homedir()/.dsh`, see src/browser-electron/desktop-bridge-host.ts). With a
+ * bare `?? ''` an unset DSH_HOME resolves to the process CWD, so the endpoint
+ * landed beside the app — while the plugin looked in ~/.dsh and never found it.
+ * The failure is silent in both directions: discovery returns undefined and the
+ * plugin quietly falls back to a self-hosted window, with no error anywhere.
+ * Measured on DSH Desktop 0.2.0-rc.2, launched from a shortcut (no DSH_HOME in
+ * its environment).
+ */
 function endpointFile() {
-  const home = process.env.DSH_HOME ?? ''
+  const home = process.env.DSH_HOME ?? join(homedir(), '.dsh')
   return join(home, 'dsh-builtin-browser-bridge.json')
 }
 
@@ -128,10 +140,21 @@ async function handle(request) {
     //    b. otherwise type into the address field and submit with REAL key input
     //       (synthetic events do not move React's controlled input, and the field
     //       also loses focus to re-renders, so both halves are needed).
+    let submitVerdict = 'n/a'
     const restored = await sendCdp(shell.id, 'Runtime.evaluate', {
+      // Only real controls count, and only their OWN text does. Matching any
+      // node's `textContent` made a container that merely mentioned restoring a
+      // page report RESTORED — which skipped the address route below entirely
+      // and left the guest unmaterialized (measured on DSH 0.2.0-rc.2, where the
+      // sidebar shows no restore control at all).
       expression: `(() => {
         const nodes = Array.from(document.querySelectorAll('button,a,[role=button],div[role=link]'));
-        const hit = nodes.find(n => /恢复页面|恢复上次|上次打开/.test((n.textContent || '').trim()));
+        const hit = nodes.find(n => {
+          const own = (n.textContent || '').trim();
+          if (own.length > 24) return false;
+          return /^(恢复页面|恢复上次|恢复上次页面|上次打开)$/.test(own)
+            || /恢复|restore/i.test(n.getAttribute('aria-label') || n.getAttribute('title') || '');
+        });
         if (hit === undefined) return 'NO_RESTORE';
         hit.click();
         return 'RESTORED';
@@ -140,8 +163,15 @@ async function handle(request) {
     })
     if (restored?.result?.value !== 'RESTORED') {
       if (url !== '') {
-        // Set the value the way React accepts it, then submit with real input.
-        await sendCdp(shell.id, 'Runtime.evaluate', {
+        // Set the value the way React accepts it, then SUBMIT THE FORM.
+        //
+        // A dispatched Enter is not enough: the sidebar browser's toolbar is a
+        // `<form>` whose submission is wired to an explicit control (aria-label
+        // "前往" / "Go"), and implicit submission does not fire there — measured
+        // on DSH 0.2.0-rc.2, where Enter left the field filled and the guest
+        // uncreated. `requestSubmit()` goes through the same path the button
+        // does, so it works with React's onSubmit and needs no localized label.
+        const typed = await sendCdp(shell.id, 'Runtime.evaluate', {
           expression: `(() => {
             const inputs = Array.from(document.querySelectorAll('input')).filter(i => /HTTP|地址|url/i.test((i.placeholder || '') + (i.getAttribute('aria-label') || '')));
             if (inputs.length === 0) return 'NO_ADDRESS_BAR';
@@ -150,18 +180,28 @@ async function handle(request) {
             setter.call(input, ${JSON.stringify(String(request.url ?? ''))});
             input.dispatchEvent(new Event('input', { bubbles: true }));
             input.focus();
-            return 'TYPED';
+            const form = input.form ?? input.closest('form');
+            if (form) { form.requestSubmit(); return 'SUBMITTED_FORM'; }
+            const button = input.parentElement
+              ? input.parentElement.querySelector('button[type=submit],button')
+              : null;
+            if (button) { button.click(); return 'CLICKED_SUBMIT'; }
+            return 'TYPED_ONLY';
           })()`,
           returnByValue: true,
         })
-        for (const type of ['keyDown', 'keyUp']) {
-          await sendCdp(shell.id, 'Input.dispatchKeyEvent', {
-            type,
-            key: 'Enter',
-            code: 'Enter',
-            windowsVirtualKeyCode: 13,
-            nativeVirtualKeyCode: 13,
-          })
+        submitVerdict = String(typed?.result?.value ?? 'n/a')
+        // Enter stays as the last resort for sidebars without a form.
+        if (submitVerdict === 'TYPED_ONLY') {
+          for (const type of ['keyDown', 'keyUp']) {
+            await sendCdp(shell.id, 'Input.dispatchKeyEvent', {
+              type,
+              key: 'Enter',
+              code: 'Enter',
+              windowsVirtualKeyCode: 13,
+              nativeVirtualKeyCode: 13,
+            })
+          }
         }
       }
     }
@@ -177,7 +217,7 @@ async function handle(request) {
         return { ok: true, created: true, id: created[0].id, via: restored?.result?.value === 'RESTORED' ? 'restore' : 'address' }
       }
     }
-    throw new Error(`the sidebar did not create a browser guest (prepare=${String(verdict)}, restore=${String(restored?.result?.value)})`)
+    throw new Error(`the sidebar did not create a browser guest (prepare=${String(verdict)}, restore=${String(restored?.result?.value)}, submit=${submitVerdict})`)
   }
   if (op === 'ensureTabs') {
     // Grow the sidebar's browser tab strip to `count` tabs and report every guest.

package/docs/architecture.md

@@ -61,7 +61,7 @@ RemoteElectronViewHost  ──TCP JSON-RPC──▶  host-main.js
 - **协议**:本机 loopback TCP,每行一个 JSON(`{ id, op, ... }` ↔ `{ id, ok, result|err }`);
 - **认证**:每次 spawn 生成随机 token,经 **stdin 首行 + `DSH_BROWSER_RPC_TOKEN` 环境变量双通道**传给子进程(绝不进 argv,避免进程列表泄露;Windows GUI 进程收不到 piped stdin,环境变量兜底),子进程首条消息必须回传该 token(`hello`);服务端只接受**一个**连接,其余连接直接断开——本机其他进程无法伪冒子进程或注入回复;
 - **Electron 定位**:① `ELECTRON_PATH`(显式覆盖,优先于一切自动发现)→ ② 随插件安装的 electron 包(纯文件系统探测,含 pnpm store 布局,不触发 44+ 懒下载)→ ③ 锚点与 pnpm store 中**版本最新**者(33.x 有合成器缺陷,建议 ≥ 40)→ ④ 当前进程是**裸** Electron(dev 模式)时复用宿主二进制(`process.execPath`)→ ⑤ 进程祖先树中的裸 Electron 二进制(Windows 用 PowerShell CIM 查询,仅在其它路径全部落空时才执行)。**打包应用不参与复用**:旁有 `resources/app.asar` 的可执行文件(如 DSH Desktop.exe)不能按脚本参数拉起——spawn 会启动应用本体并秒退(单实例锁,即 "browser host exited (code=0)"),一律跳过;
-- **稳健性**:子进程/套接字都有 `error` 监听(否则未捕获事件会炸掉整个 DSH 进程);子进程退出自动重启,已物化的视图句柄在下次调用时**自动重建并重试一次**(会话跨崩溃存活,仅页面状态丢失,不再出现 "browser host is not running" 僵尸态);物化失败可重试;下载仅限 HTTP(S)、`savePath` 必须绝对路径(默认限定 `~/Downloads`,可配置 `downloadDir` 覆盖)、流式限流 + Content-Length 提前拒绝、256MB 上限与 60s 超时,文件由**子进程直接落盘**(临时文件 + rename,不再经 RPC 传 base64);cookie 导出/恢复有 30s 超时;
+- **稳健性**:子进程/套接字都有 `error` 监听(否则未捕获事件会炸掉整个 DSH 进程);子进程退出自动重启,已物化的视图句柄在下次调用时**自动重建并重试一次**(会话跨崩溃存活,仅页面状态丢失,不再出现 "browser host is not running" 僵尸态);物化失败可重试;下载仅限 HTTP(S)、`savePath` 必须绝对路径(`downloadDir` 已配置时用它;未配置时按序探测 —— 存在的 `XDG_DOWNLOAD_DIR` → home 下第一个存在的 `Downloads`/`下载`/`下載` → 回退 `~/Downloads`,首次使用时创建)、流式限流 + Content-Length 提前拒绝、256MB 上限与 60s 超时,文件由**子进程直接落盘**(临时文件 + rename,不再经 RPC 传 base64);cookie 导出/恢复有 30s 超时,且两者都受设置里 `credentials.allowRead` 门控 —— 关闭时抛 `BROWSER_AUTH_DISABLED`(导出**与恢复**都拒绝),有原生方法时优先用它,否则走 CDP 的 `Storage.getCookies` / `Storage.setCookies`(三种载体都可用);
 - **视图可见性**:多标签/多会话时,`showView` 隐藏其他视图并把目标视图置顶(remove+re-add),确保用户看到的是活动标签;目标是当前可见视图时**跳过** remove/re-add(否则每次操作都闪烁);窗口标题实时显示当前可见会话的任务标识 + 页面标题/URL(`showView` 携带会话 label,子进程读 `getTitle`/`getURL`);窗口 resize 时视图 bounds 自动跟随;
 - **孤儿防护**:父进程断开时子进程自动退出,不留僵尸窗口;
 - **cookie 落盘**:子进程使用独立 userData 目录(`<DSH_HOME>/dsh-builtin-browser-host`),登录态跨重启保留(另有 `browser_auth` 手动导出/恢复)。

package/docs/tool-reference.md

@@ -1,6 +1,6 @@
 # 工具参考
 
-全部 34 个 `browser_*` 工具。守卫列:✅ 表示该动作受 `browser_restrict` 白名单约束;只读工具永不拦截。
+全部 34 个 `browser_*` 工具。守卫列:✅ 表示该动作受 `browser_restrict` 白名单约束;**「– 豁免」表示无论白名单怎么写都不拦截**(豁免集合为 `READ_ONLY_TOOLS`,`src/tool-browser/index.ts` 导出:**只观察的工具** —— `snapshot`/`a11y`/`content`/`scrape`/`screenshot`/`get_value`/`wait`/`challenge`/`list_tabs`/`session`/`history`/`visited`/`auth` —— 加上 **解除限制 / 从坏状态恢复的工具** `restrict`/`reset_session`/`reset`;`restrict` 在其中,否则限制到空的任务再也解不开);**「–」表示该工具只观察、不做动作**,故没有可拦的东西。两者之外的工具都受白名单约束 —— 例如 `browser_close_tab` 不属于豁免集合。
 
 ## 页面与导航
 
@@ -30,16 +30,16 @@
 | `browser_check` | `target`(必填), `checked?` | `{ checked }` | ✅ | 勾选/取消勾选 checkbox 或 radio(按 target 定位) |
 | `browser_select` | `target`(必填), `optionValue?`/`optionText?`/`optionIndex?`(三选一) | `{ value, text }` | ✅ | 选中 `<select>` 的某个选项(按 target 定位) |
 | `browser_clear` | `target`(必填) | `{ cleared }` | ✅ | 清空输入/文本域/contenteditable,或取消勾选 checkbox/radio |
-| `browser_get_value` | `target`(必填) | `{ value?, checked?, selectedText? }` | – | 读取元素当前值,用于操作后验证 |
-| `browser_scrape` | `item`(必填), `fields`(必填,映射), `timeoutMs?` | `{ count, items[] }` | – | 结构化提取:容器选择器 + 字段映射(如 `{"title": "h3", "url": "a@href"}`);静态 CSS 查询、不执行任意代码、CSP 安全;等待 item 出现(默认 5s) |
+| `browser_get_value` | `target`(必填) | `{ value?, checked?, selectedText? }` | – 豁免 | 读取元素当前值,用于操作后验证 |
+| `browser_scrape` | `item`(必填), `fields`(必填,映射), `timeoutMs?` | `{ count, items[] }` | – 豁免 | 结构化提取:容器选择器 + 字段映射(如 `{"title": "h3", "url": "a@href"}`);静态 CSS 查询、不执行任意代码、CSP 安全;等待 item 出现(默认 5s) |
 
 ## 标签与会话
 
 | 工具 | 参数 | 输出 | 守卫 | 说明 |
 | --- | --- | --- | --- | --- |
-| `browser_list_tabs` | – | `{ session, tabs[] }` | – | 当前会话的标签列表 |
+| `browser_list_tabs` | – | `{ tabs: [{ id, url, active }] }` | – | 当前会话的标签列表(输出 schema 只有 `tabs`,**没有 `session` 字段**;会话标识请用 `browser_session`) |
 | `browser_switch_tab` | `tabId`(必填) | `{ switched }` | ✅ | 按 id 切换标签;自托管下同步切换可见视图 |
-| `browser_close_tab` | `tabId`(必填) | `{ closed }` | – | 关闭标签;关闭活动标签后激活下一个 |
+| `browser_close_tab` | `tabId`(必填) | `{ closed }` | ✅ | 关闭标签;关闭活动标签后激活下一个。**不属于只读豁免集合,受白名单约束**;`tabId` 只在本会话内查找(接受 `tab:<uuid>` 或裸 uuid),陈旧 id 不会关掉别的任务的标签页 |
 | `browser_reset` | – | `{ reset }` | ✅ | 关闭本任务所有标签,回到一个空白标签 |
 | `browser_session` | – | `{ session, tabs[] }` | – | 查看本任务的浏览器会话与标签 |
 | `browser_reset_session` | – | `{ reset }` | ✅ | 关闭并重建本任务的浏览器会话(崩溃/卡死后恢复) |
@@ -57,14 +57,14 @@
 
 | 工具 | 参数 | 输出 | 守卫 | 说明 |
 | --- | --- | --- | --- | --- |
-| `browser_auth` | `action`(flush/restore,必填), `cookies?` | `{ cookies[]? / restored? }` | ✅ | 导出/恢复 cookie(自托管可用);flush 返回 cookie 列表,restore 带列表写回 |
-| `browser_restrict` | `allowed?` | `{ restrictedTo[] }` | – | 设置动作白名单;空列表解除;未知工具名报错。**软护栏**——模型可自行解除,非安全边界 |
+| `browser_auth` | `action`(flush/restore,必填), `cookies?` | `{ cookies[]? / restored? }` | ✅ | 导出/恢复 cookie —— **三种载体都可用**:自托管走原生会话,桌面侧栏与本机 Chrome/Edge 走 CDP 的 `Storage.getCookies` / `Storage.setCookies`;flush 返回 cookie 列表,restore 带列表写回。设置里「允许读取 cookies / 导出登录状态」关闭时,flush 与 restore **都**抛 `BROWSER_AUTH_DISABLED` |
+| `browser_restrict` | `allowed?` | `{ restrictedTo[] }` | – | 设置动作白名单;空列表解除;**只校验名字是否以 `browser_` 开头**(写错的前缀会报错,`browser_typo` 这种拼错但前缀合法的名字会被接受、等同于拦掉该名字,不额外报错);守卫按名字匹配,因此白名单里列什么名字就只放行什么名字。**软护栏**——模型可自行解除,非安全边界 |
 
 ## 截图
 
 | 工具 | 参数 | 输出 | 守卫 | 说明 |
 | --- | --- | --- | --- | --- |
-| `browser_screenshot` | `fullPage?`, `savePath?`, `format?`(png/jpeg), `quality?`, `maxWidth?`, `maxHeight?` | `{ dataUrl, path? }` | – | 截图;PNG 默认,JPEG 仅自托管原生路径;`maxWidth`/`maxHeight` 等比缩放降低视觉模型开销;`savePath` 落盘供视觉模型读取(与 `browser_download` 同一准入门:必须位于 `downloadDir` 内且不覆盖已有文件) |
+| `browser_screenshot` | `fullPage?`, `savePath?`, `format?`(png/jpeg), `quality?`, `maxWidth?`, `maxHeight?` | `{ dataUrl, path? }` | – | 截图;PNG 默认,**JPEG 在自托管与本机 Chrome/Edge 上都可用**(自托管在原生 `capturePage` 路径编码,本机浏览器经 CDP 声明 `supportsCdpJpeg`;**桌面侧栏**的 Electron CDP JPEG 编码器会挂起,该载体下 JPEG 请求返回 PNG);`maxWidth`/`maxHeight` 等比缩放**三种载体都支持**;`fullPage` 会跳过原生 `capturePage`、三种载体统一走 CDP `captureBeyondViewport`;`savePath` 落盘供视觉模型读取(与 `browser_download` 同一准入门:必须位于 `downloadDir` 内且不覆盖已有文件) |
 
 ## 常用组合
 

package/docs/user-guide.md

@@ -17,10 +17,12 @@ dsh plugin --profile web add dsh-builtin-browser
 dsh plugin --profile web add <本仓库路径>
 ```
 
-安装会链接插件、把 `dsh-builtin-browser` 加入 profile 的 bundle 层,并挂载三行:
+安装会链接插件、把 `dsh-builtin-browser` 加入 profile 的 bundle 层,并挂载四行(一个惰性的根行 + 三个功能行):
 
 | 行 | 子路径 | 角色 |
 | --- | --- | --- |
+| `dsh-builtin-browser` | 包名本身 | **惰性根行**:不注册任何东西(空 `apply()`),只用来声明包名 —— 宿主的客户端插件扫描靠精确包名读到 `dsh.client`,少了这行设置栏不会出现 |
+| --- | --- | --- |
 | `browser` | `dsh-builtin-browser/browser` | `ctx.browser` 能力 seam(始终挂载) |
 | `browser-electron` | `dsh-builtin-browser/browser-electron` | Electron CDP provider |
 | `tool-browser` | `dsh-builtin-browser/tool-browser` | `browser_*` 模型侧工具 |
@@ -31,7 +33,7 @@ dsh plugin --profile web add <本仓库路径>
 
 | 行 | 配置项 | 类型 | 默认 | 说明 |
 | --- | --- | --- | --- | --- |
-| `browser-electron` | `viewHost` | 对象 | 必填 | 宿主提供的 `ElectronBrowserViewHost`(通常 `!!js ctx.get('electronViewHost')`) |
+| `browser-electron` | `viewHost` | 对象 | 可选 | 宿主提供的 `ElectronBrowserViewHost`(通常 `!!js ctx.get('electronViewHost')`)。**不传时插件自己选载体**:桌面端驱动官方侧栏、否则自托管;设置里显式选择的 Chrome/Edge 优先于两者 |
 | `browser-electron` | `httpOnly` | 布尔 | `true` | 仅允许 HTTP(S) 导航;`file:`/`data:` 等拒绝 |
 | `browser-electron` | `snapshotMaxElements` | 数字 | `60` | 快照最多收录的交互元素数 |
 | `browser-electron` | `contentMaxChars` | 数字 | `100000` | 内容抓取默认字符上限 |

package/docs/why-browser.md

@@ -33,7 +33,7 @@ LLM agent 需要"上网"。传统做法是给 agent 一个**无头浏览器**(Pl
 ## 设计取舍
 
 - **登录态共享**:所有任务共享同一份 cookie(符合"用户登录一次,agent 到处可用");需要隔离时用 `browser_auth` 手动导出/恢复。
-- **任务级会话隔离**:每个 DSH 会话(任务)拥有独立的浏览器会话(标签页与历史),并发任务互不抢页面;但窗口只有一个,当前活动的任务视图可见。
+- **任务级会话隔离**:每个 DSH 会话(任务)拥有独立的浏览器会话(标签页与历史),并发任务互不抢页面;自托管载体下**每个会话连窗口都各自一份**(窗口按会话 id 分组,窗口标题带任务标识),侧栏与本机浏览器载体则是同一个宿主里切换当前可见视图。
 - **装好即用**:不依赖桌面外壳。有外壳时嵌入外壳视图;纯 `dsh web` 时插件自托管——自己拉起 Electron 窗口,通过本机 TCP JSON-RPC 驱动。
 - **边界清晰**:可见视图、浏览器列布局属于宿主外壳;插件只负责 seam、provider 与工具,不含任何 UI。
 - **人机验证不硬刚**:检测到 Cloudflare/reCAPTCHA/hCaptcha/Turnstile 时停下,请用户在共享窗口人工完成,而不是盲目重试。

package/lib/browser-electron/desktop-bridge-host.d.ts

@@ -35,7 +35,6 @@ export declare function bridgeEndpointPath(): string;
  * point is a single page both parties can see.
  */
 export declare class DesktopBridgeViewHost implements ElectronBrowserViewHost {
-    private readonly endpoint;
     private readonly connection;
     private readonly views;
     /**
@@ -47,6 +46,16 @@ export declare class DesktopBridgeViewHost implements ElectronBrowserViewHost {
      * session gets its own page).
      */
     private readonly orphaned;
+    /**
+     * Registered by the provider, and deliberately never invoked on this carrier.
+     *
+     * The sidebar is the shell's own interface: a human clicking inside that page is an
+     * event the shell owns, and the bridge exposes no operation that reports it. The
+     * handler is stored anyway so the interface contract holds (a caller may register
+     * one and must not be surprised) and so a future bridge operation can deliver it
+     * without changing the provider. Consequently no user-action event is emitted while
+     * the desktop sidebar is the carrier — by design, not by omission.
+     */
     private userActionHandler;
     /**
      * @param endpoint - the shell's published bridge endpoint.

package/lib/browser-electron/desktop-bridge-host.js

@@ -50,7 +50,6 @@ function isGuestGone(error) {
  * point is a single page both parties can see.
  */
 export class DesktopBridgeViewHost {
-    endpoint;
     connection;
     views = new Map();
     /**
@@ -62,12 +61,21 @@ export class DesktopBridgeViewHost {
      * session gets its own page).
      */
     orphaned = new Set();
+    /**
+     * Registered by the provider, and deliberately never invoked on this carrier.
+     *
+     * The sidebar is the shell's own interface: a human clicking inside that page is an
+     * event the shell owns, and the bridge exposes no operation that reports it. The
+     * handler is stored anyway so the interface contract holds (a caller may register
+     * one and must not be surprised) and so a future bridge operation can deliver it
+     * without changing the provider. Consequently no user-action event is emitted while
+     * the desktop sidebar is the carrier — by design, not by omission.
+     */
     userActionHandler;
     /**
      * @param endpoint - the shell's published bridge endpoint.
      */
     constructor(endpoint) {
-        this.endpoint = endpoint;
         this.connection = new BridgeConnection(endpoint);
     }
     /**