@morlay/dsh-desktop-host 0.2.5 → 0.2.6

package/README.md

@@ -2,14 +2,28 @@
 
 桌面部署里那个 **host 进程**：按 `desktop` profile 把 Web 应用启起来，然后**在进程内接管 `webServer`**——不监听任何端口，Electron 壳把该应用自己的协议（`<app name>://app/*`）的请求经字节管道（FD 3/4）喂进来。
 
-上游 `apps/desktop-host`（`@deepseek-ai/dsh-desktop-host`）是 `private: true` 的应用，外部装不到，所以这里是它的**变体包**：argv / IPC 契约、`lib/index.js` 入口路径照旧。
+上游 `apps/desktop-host`（`@deepseek-ai/dsh-desktop-host`）是 `private: true` 的应用，外部装不到，所以这里是它的**变体包**：IPC 契约照旧，argv 与本仓库的 web 入口统一成一套 flag（见下）。
 
 ## 用法
 
-被 [`@morlay/dsh-desktopify`](../dsh-desktopify/README.md) 使用，不单独跑：
+被 [`@local/dshdev`](../../../devpackages/dshdev/README.md) 使用，不单独跑：
 
-- `dev` / `bundle` 把本包落位到部署的 `<runtime>/node_modules/@morlay/dsh-desktop-host`（`dev` 整份复制源码树，`bundle` 按 manifest `files` 复制），四样必须都在——`lib/index.js`（启动入口）、`lib/webserver.js`（桌面 patch 行按 `../lib/webserver.js` 加载）、`lib/wire.js`、`config/desktop.cordis.patch.yml`（入口按它作 `patchFiles` 读）；
-- 壳按 `lib/index.js` 启动它（stdio 五元组：FD 3/4 是管道，FD 5 是 Node IPC），argv 为 `[entry, runtimeDir, projectDir, pnpmEntry?, nodeBin?]`；
-- IPC：`ready { protocolVersion }` / `fatal { message, diagnostic }`，另外收 `shutdown`。
+- `dev` / `bundle` 把本包落位到部署的 `<runtime>/node_modules/@morlay/dsh-desktop-host`（`dev` 从工作区解析同一份包，`bundle` 按 manifest `files` 复制），三样必须都在——`src/index.ts`（启动入口，壳按 node 解析取**源码**，由 TS loader 转译）、当时那个无端口替身（已删）（桌面 patch 行按 当时那个无端口替身（已删） 加载）、`config/desktop.cordis.patch.yml`（入口按它作 `patchFiles` 读）；
+- 壳启动它（stdio：stdout/stderr 落盘 + FD 5 是 Node IPC），argv 与 web 入口**同一套**
+  （解析只有一处，见 [`src/invocation.ts`](./src/invocation.ts)）：
 
-运行时做的事（profile 装配、`webServer` 替身、认证接管、客户端 transport 与账号面）、出口面与依赖边界见[设计 桌面host的运行时面与依赖边界](./.agents/designs/20260929-桌面host的运行时面与依赖边界.md)；载波形态的取舍见[设计 桌面无端口传输与窗口对齐](../dsh-desktopify/.agents/designs/20260920-桌面无端口传输与窗口对齐.md)。
+  ```
+  <entry> --profile-dir <dir> --runtime-dir <dir> [--patch <file>]… [--pnpm <path> --node-bin <dir>] [-- <内层参数>]
+  ```
+
+  `--profile-dir` 是 profile root（打包形态是种子种出的 `$DSH_HOME/profiles/<name>`，dev 形态是 app 目录本身）；
+
+- **入口只做三件事**：[`src/index.ts`](./src/index.ts) 解析参数 → 装配 → 接线；装配在
+  [`@morlay/dsh-app-boot`](../../boot/dsh-app-boot/README.md)（desktop 与 web 共用，层完全由 profile 的
+  `dsh.profile.bundles` 决定），管道与请求分发在 [`src/desktop-ipc.ts`](./src/desktop-ipc.ts)，传输接管在
+  [`src/transport.ts`](./src/transport.ts)；
+- `--web`（dev 的 web 形态）走 [`src/web.ts`](./src/web.ts)：同一个 `bootAppProfile`，只是 profile 名换成
+  `web` 并多一个端口契约，见[设计 dev 形态的 profile root 就是 app 目录](../../../devpackages/dshdev/.agents/designs/20261014-数据与工作目录的-layout.md)；
+- IPC：`ready { protocolVersion, wsPort }` / `fatal { message, diagnostic }`，另外收 `shutdown`。
+
+运行时做的事（profile 装配、`webServer` 替身、认证接管、客户端 transport 与账号面）、出口面与依赖边界见[设计 桌面host的运行时面与依赖边界](./.agents/designs/20260929-桌面host的运行时面与依赖边界.md)；载波形态的取舍见[设计 桌面运行形态与窗口对齐](.agents/designs/20260920-桌面运行形态与窗口对齐.md)。

package/config/desktop.cordis.patch.yml

@@ -1,20 +1,11 @@
-# 桌面形态的传输接管：上游 `webserver` 行在激活时 listen，桌面没有网络入口，
-# 这里禁用它并插入宿主内的无端口替身（同服务名 `webServer`、同一份路由面，
-# 请求由字节管道经 dispatch 喂进来）。其余行沿用 web-app bundle。
+# 桌面形态**不再替换** `webserver`：以前这里禁用它、插一个"无端口替身"，让请求走字节管道喂进来——
+# 那样没有 origin（不是真的 `http://host:port`），而基于 URL/WS 的东西（settings 的 `describe` 流、
+# 账号的 stream mux、vite 的 HMR）拿不到答复，表现为"设置页永远不可用、连请求都看不到"。
+# 现在回到上游的做法：**照常 listen（随机端口）**，壳用它的 origin 载入窗口。
 #
 # `web-runtime` 的四项一并写全：patch 整块替换 config，没有端口可打印、也没有
 # 浏览器可交接；`surfaceContext` 关掉，免得提示段带一个并不存在的 URL。
 
-- id: webserver
-  disabled: true
-
-- insert:
-    - id: portless-webserver
-      name: "../lib/webserver.js"
-      config:
-        host: "127.0.0.1"
-        port: 0
-
 - id: web-runtime
   config:
     openBrowser: false
@@ -22,32 +13,43 @@
     surfaceContext: false
     trustedHosts: []
 
-# 桌面档不含登录，账号面整条停掉。DeepSeek 账号登录是「系统浏览器授权 + 回环地址回调」：
-# 上游 `dsh-deepseek-account-platform` 在 webServer 上注册 `/oauth/callback`，授权页要回到
-# `http://localhost:<端口>/oauth/callback`——而本部署的 webServer 没有端口（上面的
-# portless-webserver），回调没有入口；client 半算出的回调来源是页面的自定义协议来源，
-# 连协议校验都过不了。装着的那几个面点进去只会撞死路，于是按 id 停掉：
-#
-# - `deepseek-account`：登录实现（凭据记录、事务面与浏览器流程的宿主一半）；
-# - `account-controller`：账号事务的 Remote 名册，硬注入 `deepseekAccount`，登录实现停了
-#   它只会等一个不会出现的服务；
-# - `llm-deepseek-account`：账号 token 独占的模型路由，token 只可能来自上面那条登录，
-#   留着则是一条永远 `ACCOUNT_SIGN_IN_REQUIRED` 的死路由；
-# - `ui-settings-account`：账号的 client 面（设置页的账号页、侧栏账号菜单、桌面首次引导
-#   覆盖层、充值页宿主），并且是 `ui-settings-account` 这个 settings namespace 的 owner。
-#
-# 留下的仍是本部署的模型路径：`credentials`（通用凭据服务）与 `llm-deepseek`（官方 API key
-# 路由，不是登录）都不动——模型走 ollama provider，key 由 `credentials` 解析
-# `apiKeyEnv: OLLAMA_API_KEY`（profile 层给的）。
-
-- id: deepseek-account
+# **端口要随机**：`web-app` bundle 给 `webserver` 的默认是 `webStartup.port ?? 3080`，而桌面形态没有
+# `--port` 参数，于是落到 3080——同时开两个实例、或本机上别的工具占了它，第二次就起不来。桌面没有
+# "可预期的地址"要对外（窗口从 origin 载入，地址由宿主自己报），所以向系统要一个：`0`（上游的
+# `webserver` 明确支持："zero requests an OS-assigned port"）。
+- id: webserver
+  config:
+    # `host` 与 `port` 是必填（patch 整块替换 config，写一半就是 `$.host missing required value`）。
+    # 只绑回环：桌面不需要对外服务。
+    host: "127.0.0.1"
+    port: 0
+
+# 桌面档的产品遥测面：上游那两行只在 profile 名为 `desktop` 时激活，靠构建期环境变量 `DSH_CLIENT_VERSION`
+# 填 `serviceVersion`（必填）。自研壳不传那个变量，于是遥测行配置校验失败、`product-analytics` 行 pending，
+# 页面启动时 `productAnalytics/watchPolicy` 那条流拿 502，前端又在非 JSON 响应上抛未捕获错误。
+# 本地桌面部署没有上报对象（endpoint 是官方 collector），两行一起停。
+# 决策见 [ADR 桌面档无产品遥测](../.agents/adrs/20261008-桌面档无产品遥测.md)。
+
+- id: desktop-product-telemetry
   disabled: true
 
-- id: llm-deepseek-account
+- id: product-analytics
   disabled: true
 
-- id: account-controller
-  disabled: true
+# **本部署不要账号 UI**：上游 `ui-settings-account` 那一行渲染设置页的账号页、侧栏账号菜单与首次引导层。
+# 它同时还是那个 **settings namespace 的 owner**——光停它，前端镜面就拿不到名册（`describeFace.view
+# === undefined`）→ 直接 failLoad，整个设置页判 "settings are unavailable in this browser"，连
+# `/api/settings` 都不请求。所以停它的同时，由下面那行**顶上同一个注册**（不渲染任何界面）。
+#
+# **为什么停用必须写在这里**：实测，写在 bundle 层的停用会被后来应用的层盖回去；这份 overlay 由宿主追加在
+# `patchFiles` 末尾（`src/index.ts:80`），是最后应用的一层。
 
 - id: ui-settings-account
   disabled: true
+
+# 顶替上面那行不可省的那件事：注册 settings namespace（同样的 `settings.configure({ auto: false })`，
+# 不渲染账号页/侧栏菜单/引导层）。实现见 [`../src/settings-namespace.ts`](../src/settings-namespace.ts)。
+
+- insert:
+    - id: settings-namespace
+      name: "../src/settings-namespace.ts"

package/dist/index.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/index.js

@@ -0,0 +1,430 @@
+import { installPreloadSource } from "./preload-source.js";
+import { DESKTOP_STREAM_PATH, DesktopStreamBodyDecoder, isDesktopHostCommand } from "./wire.js";
+import { fileURLToPath } from "node:url";
+import { bootAppProfile } from "@morlay/dsh-app-boot";
+import inspector from "node:inspector";
+import { inspect } from "node:util";
+import { once } from "node:events";
+//#region src/inspector.ts
+function errorText$1(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/** 打开回环上的 Node inspector，返回它的 WebSocket 端点（`port` 为 0 时用随机端口）。 */
+function openInspectorEndpoint(port) {
+	if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error(`dsh desktop: inspector port ${String(port)} is out of range`);
+	const existing = inspector.url();
+	if (existing !== void 0) return existing;
+	inspector.open(port, "127.0.0.1");
+	const url = inspector.url();
+	if (url === void 0) throw new Error("dsh desktop: the inspector endpoint did not open");
+	return url;
+}
+/** 关掉调试端点；没开时什么都不做。 */
+function closeInspectorEndpoint() {
+	inspector.close();
+}
+/** 处理一条调试端点命令，返回要回报给壳的事件；不是调试命令时返回 undefined。 */
+function applyInspectorCommand(command) {
+	if (command.type === "inspect-off") {
+		closeInspectorEndpoint();
+		return {
+			type: "inspected",
+			url: null
+		};
+	}
+	if (command.type !== "inspect") return void 0;
+	try {
+		return {
+			type: "inspected",
+			url: openInspectorEndpoint(command.port)
+		};
+	} catch (error) {
+		return {
+			type: "inspected",
+			url: null,
+			message: errorText$1(error)
+		};
+	}
+}
+//#endregion
+//#region src/desktop-ipc.ts
+/**
+* 接上 IPC 面：挂好生命周期（`shutdown` 命令 / 通道断开）。
+* @param options - 装配结果。
+* @returns 发事件与收尾两个入口。
+*/
+function connectDesktopIpc(options) {
+	const { application } = options;
+	let stopping;
+	const send = (event) => {
+		if (process.send === void 0 || !process.connected) return;
+		try {
+			process.send(event);
+		} catch (error) {
+			if (error.code !== "ERR_IPC_CHANNEL_CLOSED") throw error;
+		}
+	};
+	const stop = (exitCode = 0) => {
+		stopping ??= (async () => {
+			closeInspectorEndpoint();
+			await (await application.catch(() => void 0))?.shutdown.shutdown(exitCode);
+			if (process.connected) process.disconnect?.();
+			process.exitCode = exitCode;
+		})();
+		return stopping;
+	};
+	process.on("message", (message) => {
+		if (!isDesktopHostCommand(message)) return;
+		const inspected = applyInspectorCommand(message);
+		if (inspected !== void 0) {
+			send(inspected);
+			return;
+		}
+		if (message.type === "shutdown") stop();
+	});
+	process.once("disconnect", () => {
+		stop();
+	});
+	return {
+		send,
+		stop
+	};
+}
+//#endregion
+//#region src/fatal.ts
+/** 诊断上限：壳把它写进日志，再长也没有额外价值。 */
+const MAX_FATAL_DIAGNOSTIC_CHARS = 65536;
+/** 任何抛出来的东西 → 一行消息。 */
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* 造一条 `fatal` 事件。
+* @param error - 触发退出的错误（未必是 `Error`）。
+* @returns 带完整诊断的 fatal 事件。
+*/
+function fatalEvent(error) {
+	return {
+		type: "fatal",
+		message: errorMessage(error),
+		diagnostic: inspect(error, {
+			depth: 4,
+			maxArrayLength: 50
+		}).slice(0, MAX_FATAL_DIAGNOSTIC_CHARS)
+	};
+}
+//#endregion
+//#region src/invocation.ts
+/**
+* 解析宿主入口的参数。
+* @param binName - 报错时前缀用的入口名（`dsh desktop` / `dsh web`）。
+* @param argv - `process.argv.slice(2)`。
+* @returns 两形态同形的启动参数。
+* @throws 缺两格锚点、该带值的参数缺值、或参数名不认识时。
+*/
+function parseHostInvocation(binName, argv) {
+	let profileDir;
+	let runtimeDir;
+	let pnpmEntry;
+	let nodeBin;
+	const patches = [];
+	const inner = [];
+	for (let index = 0; index < argv.length; index += 1) {
+		const argument = argv[index];
+		if (argument === "--") {
+			inner.push(...argv.slice(index + 1));
+			break;
+		}
+		const value = () => {
+			const next = argv[index + 1];
+			if (next === void 0) throw new Error(`${binName}: ${String(argument)} needs a value`);
+			index += 1;
+			return next;
+		};
+		if (argument === "--profile-dir") profileDir = value();
+		else if (argument === "--runtime-dir") runtimeDir = value();
+		else if (argument === "--patch") patches.push(value());
+		else if (argument === "--pnpm") pnpmEntry = value();
+		else if (argument === "--node-bin") nodeBin = value();
+		else throw new Error(`${binName}: unknown argument ${JSON.stringify(String(argument))}`);
+	}
+	if (profileDir === void 0 || runtimeDir === void 0) throw new Error(`${binName}: expected --profile-dir <dir> and --runtime-dir <dir>`);
+	return {
+		profileDir,
+		runtimeDir,
+		patches,
+		...pnpmEntry === void 0 ? {} : { pnpmEntry },
+		...nodeBin === void 0 ? {} : { nodeBin },
+		inner
+	};
+}
+//#endregion
+//#region src/transport.ts
+const desktopStreamStats = {
+	active: 0,
+	opened: 0,
+	failed: 0,
+	items: 0,
+	bytes: 0
+};
+const DESKTOP_TRANSPORT_SCRIPT = `globalThis.__DSH_TRANSPORT__={
+  _desktop:true,
+  ownsHost:true,
+  async *openStream(endpoint,payload,signal,uplink){
+    console.info('[dsh-desktop] openStream',endpoint)
+    const carrier=globalThis.__DSH_DESKTOP_STREAM__
+    if(carrier===undefined){
+      console.error('[dsh-desktop] stream carrier missing for',endpoint)
+      throw new Error('desktop stream carrier is unavailable')
+    }
+    const queue=[]
+    let buffer=''
+    let ended=false
+    let failure
+    let wake
+    const notify=()=>{const pending=wake;wake=undefined;if(pending)pending()}
+    const append=(text)=>{
+      buffer+=text
+      let at
+      while((at=buffer.indexOf('\\n'))!==-1){
+        const line=buffer.slice(0,at)
+        buffer=buffer.slice(at+1)
+        if(line!=='')queue.push(JSON.parse(line))
+      }
+      notify()
+    }
+    const stream=carrier.open(endpoint,payload,{
+      chunk(text){append(text)},
+      end(){
+        if(buffer!==''){queue.push(JSON.parse(buffer));buffer=''}
+        ended=true
+        notify()
+      },
+      fail(message){failure=new Error(message);ended=true;notify()},
+    })
+    // 收尾只有一处：取消必须结束迭代（不叫醒它，等在这一句上的消费方收不到 end 帧，
+    // dispose（await iterator.return）也永不落定——窗口重建会卡在这里），同时取消载体流本身。
+    // abort（窗口重建）与消费方提前退出（切会话时上游只 return 迭代器，不发 abort）都走它；
+    // 幂等，两条路径都发生也只 cancel 一次。
+    let closed=false
+    const close=()=>{
+      if(closed)return
+      closed=true
+      stream.cancel()
+      ended=true
+      notify()
+    }
+    const onAbort=close
+    signal.addEventListener('abort',onAbort,{once:true})
+    if(signal.aborted)onAbort()
+    // 上行（客户端 → 宿主）是逻辑流的输入项：逐条交给主进程，收尾时结束请求体；
+    // 没有 uplink 的流（如 $events）立刻结束请求体，宿主侧不用等一个永不来的 end。
+    if(uplink===undefined)stream.end()
+    else void (async()=>{
+      try{
+        for await(const item of uplink){
+          // 取消后不再上行：宿主那边这条逻辑流已经作废。
+          if(signal.aborted)break
+          stream.send(item)
+        }
+      }catch(error){
+        console.error('[dsh-desktop] stream uplink failed for',endpoint,error)
+      }finally{
+        stream.end()
+      }
+    })()
+    try{
+      for(;;){
+        while(queue.length>0)yield queue.shift()
+        if(failure!==undefined)throw failure
+        if(ended)return
+        await new Promise(resolve=>{wake=resolve})
+      }
+    }finally{
+      signal.removeEventListener('abort',onAbort)
+      close()
+    }
+  }
+}
+console.info('[dsh-desktop] transport installed',Object.keys(globalThis.__DSH_TRANSPORT__))`;
+function takeOverDesktopAuthentication(ctx) {
+	const connection = ctx.get("connection");
+	if (connection === void 0) throw new Error("dsh desktop: the composition did not provide the connection service");
+	if (typeof connection.requestRejection !== "function" || typeof connection.authorizeIndex !== "function") throw new Error("dsh desktop: the connection service no longer exposes requestRejection / authorizeIndex; desktop authentication takeover needs an update");
+	connection.requestRejection = () => void 0;
+	connection.authorizeIndex = () => true;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function* readStreamFrames(request) {
+	const decoder = new DesktopStreamBodyDecoder();
+	for await (const chunk of request) for (const frame of decoder.push(chunk)) yield frame;
+	for (const frame of decoder.finish()) yield frame;
+}
+function parseStreamOpening(value, subject) {
+	if (!isRecord(value) || typeof value.endpoint !== "string") throw new Error(`dsh desktop: invalid stream request ${subject}`);
+	return {
+		endpoint: value.endpoint,
+		payload: value.payload ?? { args: {} }
+	};
+}
+function reportStreamFailure(subject, detail, log) {
+	log.error(`[dsh-desktop] ${subject}: ${errorText(detail)}`);
+}
+function errorText(value) {
+	return value instanceof Error ? value.stack ?? value.message : String(value);
+}
+function streamHandler(ctx) {
+	return async (request, response) => {
+		if (request.method !== "POST") {
+			response.writeHead(405);
+			response.end();
+			return;
+		}
+		const gateway = ctx.get("typertGateway");
+		if (gateway === void 0) {
+			reportStreamFailure("stream failed", "typertGateway service is missing", ctx.logger);
+			response.writeHead(503);
+			response.end("gateway unavailable");
+			return;
+		}
+		const peer = ctx.get("connection")?.browserPeer;
+		if (peer === void 0) {
+			reportStreamFailure("stream failed", "connection service is missing", ctx.logger);
+			response.writeHead(503);
+			response.end("connection unavailable");
+			return;
+		}
+		const endpointFromQuery = new URL(request.url ?? "/", "http://127.0.0.1").searchParams.get("endpoint");
+		const frames = readStreamFrames(request);
+		let opening;
+		try {
+			const first = await frames.next();
+			opening = first.done ? parseStreamOpening(endpointFromQuery === null ? void 0 : { endpoint: endpointFromQuery }, String(request.url)) : parseStreamOpening(first.value, String(request.url));
+		} catch (error) {
+			reportStreamFailure("stream body is not a valid opener", error, ctx.logger);
+			response.writeHead(400);
+			response.end("invalid stream request");
+			return;
+		}
+		const endpoint = opening.endpoint;
+		const abort = new AbortController();
+		const cancel = () => {
+			abort.abort();
+		};
+		request.once("aborted", cancel);
+		response.once("close", cancel);
+		try {
+			ctx.logger.debug(`[dsh-desktop] stream opening ${endpoint}`);
+			const values = await gateway.wireStream.open(endpoint, opening.payload, frames, peer, abort.signal);
+			ctx.logger.debug(`[dsh-desktop] stream opened ${endpoint}`);
+			response.writeHead(200, {
+				"content-type": "application/x-ndjson",
+				"cache-control": "no-store"
+			});
+			desktopStreamStats.opened += 1;
+			desktopStreamStats.active += 1;
+			try {
+				for await (const value of values) {
+					const line = `${JSON.stringify(value)}\n`;
+					desktopStreamStats.items += 1;
+					desktopStreamStats.bytes += Buffer.byteLength(line);
+					if (!response.write(line)) {
+						await Promise.race([once(response, "drain"), once(response, "close")]).catch(() => void 0);
+						if (response.destroyed) return;
+					}
+				}
+				response.end();
+			} finally {
+				desktopStreamStats.active -= 1;
+			}
+		} catch (error) {
+			desktopStreamStats.failed += 1;
+			reportStreamFailure(`stream ${endpoint} failed`, error, ctx.logger);
+			if (response.headersSent) {
+				response.destroy(error instanceof Error ? error : new Error(String(error)));
+				return;
+			}
+			response.writeHead(502);
+			response.end(error instanceof Error ? error.message : String(error));
+		}
+	};
+}
+function installDesktopTransport(ctx) {
+	ctx.on("webserver/index-inject", (table) => {
+		table.push({
+			kind: "script",
+			placement: "head",
+			text: DESKTOP_TRANSPORT_SCRIPT
+		});
+	});
+	ctx.effect(() => ctx.webServer.register({
+		kind: "exact",
+		path: DESKTOP_STREAM_PATH,
+		handler: streamHandler(ctx)
+	}), "dsh-desktop: remote stream route");
+}
+//#endregion
+//#region src/index.ts
+const DESKTOP_PATCH = fileURLToPath(new URL("../config/desktop.cordis.patch.yml", import.meta.url));
+function reportMemoryWhenAsked(ctx) {
+	if (process.env.DSH_MEMORY_REPORT !== "1") return;
+	const megabytes = (value) => (value / 1024 / 1024).toFixed(1);
+	setInterval(() => {
+		const memory = process.memoryUsage();
+		ctx.logger.info(`[dsh-desktop] memory rss=${megabytes(memory.rss)}MB heapUsed=${megabytes(memory.heapUsed)}MB external=${megabytes(memory.external)}MB | streams active=${String(desktopStreamStats.active)} opened=${String(desktopStreamStats.opened)} failed=${String(desktopStreamStats.failed)} items=${String(desktopStreamStats.items)} bytes=${megabytes(desktopStreamStats.bytes)}MB`);
+	}, 5e3).unref();
+}
+function packageManagerOf(pnpmEntry, nodeBin) {
+	return {
+		command: process.execPath,
+		args: ["--expose-internals", pnpmEntry],
+		env: {
+			ELECTRON_RUN_AS_NODE: "1",
+			DSH_DESKTOP_NODE_EXECUTABLE: process.execPath,
+			PATH: `${nodeBin ?? ""}${nodeBin === void 0 ? "" : ":"}${process.env.PATH ?? ""}`
+		}
+	};
+}
+async function main() {
+	const invocation = parseHostInvocation("dsh desktop", process.argv.slice(2));
+	if (process.send === void 0) throw new Error("dsh desktop: expected a Node IPC channel and the byte pipes on fd 3/4 (the shell owns them)");
+	const { profileDir, patches, pnpmEntry, nodeBin, inner } = invocation;
+	const application = bootAppProfile({
+		profileDir,
+		profile: "desktop",
+		patchFiles: [...patches, DESKTOP_PATCH],
+		args: ["--no-open", ...inner],
+		...pnpmEntry === void 0 ? {} : { packageManager: packageManagerOf(pnpmEntry, nodeBin) }
+	});
+	const { ctx } = await application;
+	takeOverDesktopAuthentication(ctx);
+	installDesktopTransport(ctx);
+	reportMemoryWhenAsked(ctx);
+	const shellRoot = process.env["DSH_DESKTOP_SHELL_ROOT"];
+	if (shellRoot !== void 0 && shellRoot !== "") installPreloadSource(ctx, { shellRoot });
+	const webServer = ctx.get("webServer");
+	const ipc = connectDesktopIpc({ application });
+	const gateway = ctx.get("typertGateway");
+	ctx.logger.info("transport ready %o", {
+		webServer: webServer.constructor.name,
+		gateway: gateway === void 0 ? "missing" : "present",
+		streamRoute: DESKTOP_STREAM_PATH
+	});
+	ipc.send({
+		type: "ready",
+		protocolVersion: 1,
+		origin: `http://127.0.0.1:${String(webServer.port)}`
+	});
+}
+if (import.meta.main) main().catch((error) => {
+	if (process.send !== void 0 && process.connected) process.send(fatalEvent(error), (sendError) => {
+		if (sendError !== null) console.error(sendError);
+	});
+	console.error(error);
+	process.exitCode = 1;
+	if (process.connected) process.disconnect?.();
+});
+//#endregion
+export {};

package/dist/paths.d.mts

@@ -0,0 +1,4 @@
+//#region src/paths.d.ts
+/** 应用 origin 下托管调试窗口前端产物的前缀。 */
+export declare const DEVTOOLS_ASSETS_PREFIX = "/node-devtools";
+//#endregion

package/dist/paths.js

@@ -0,0 +1,5 @@
+//#region src/paths.ts
+/** 应用 origin 下托管调试窗口前端产物的前缀。 */
+const DEVTOOLS_ASSETS_PREFIX = "/node-devtools";
+//#endregion
+export { DEVTOOLS_ASSETS_PREFIX };

package/dist/preload-source.d.mts

@@ -0,0 +1,29 @@
+import { Context } from "@deepseek-ai/cordis";
+//#region src/preload-source.d.ts
+/** 壳取 preload 的路径（`GET` 它得到可执行的 CJS 字节）。 */
+export declare const PRELOAD_SOURCE_PATH = "/@dsh/preload.cjs";
+export interface PreloadSourceOptions {
+  /** 壳包所在的目录（app 目录）：preload 的源码在它的 `src/` 下。 */
+  readonly shellRoot: string;
+}
+/**
+ * 把 preload 打包成单文件 CJS。
+ *
+ * @param options - 见 {@link PreloadSourceOptions}。
+ * @returns CJS 源码。
+ */
+export declare function bundlePreload(options: PreloadSourceOptions): Promise<string>;
+/** 构建期打好的那份 preload（`prepareShell` 里调 {@link bundlePreload} 产出）。 */
+export declare const PRELOAD_BUNDLE_FILE: string;
+/**
+ * 在宿主的 webServer 上注册 `/@dsh/preload.cjs`：壳按这条路径取走 preload 的 CJS 字节。
+ *
+ * **读的是构建期打好的文件**，不在运行时打包：现场打包要读 `src/preload-app.ts`，而打包器（rolldown）
+ * 是 native 模块、用自己的文件 IO——**读不了 asar 内的路径**（宿主跑在 Electron 上，`fs` 才被补丁照看着）。
+ * 构建期那份读进来是字节，`readFile` 对归档是透明的。
+ *
+ * @param ctx - 宿主上下文（拿 `webServer`）。
+ * @param options - 见 {@link PreloadSourceOptions}。
+ */
+export declare function installPreloadSource(ctx: Context, options: PreloadSourceOptions): void;
+//#endregion