@morlay/dsh-desktop-host 0.2.4 → 0.2.6

package/src/__tests__/web-entry.spec.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from "vitest";
+import { DEFAULT_WEB_PORT, webArgs } from "../web.ts";
+
+describe("web 端口契约", () => {
+  it("内层没给 --port 时补上 PORT（缺省 0）", () => {
+    expect(webArgs([], DEFAULT_WEB_PORT)).toEqual(["--port", "0"]);
+    expect(webArgs(["--no-open"], "4000")).toEqual(["--port", "4000", "--no-open"]);
+  });
+
+  it("内层显式给了 --port 就以它为准", () => {
+    expect(webArgs(["--port", "8080"], "4000")).toEqual(["--port", "8080"]);
+  });
+});

package/src/__tests__/wire.spec.ts

@@ -0,0 +1,238 @@
+import { describe, expect, it } from "vitest";
+import {
+  DESKTOP_HOST_PROTOCOL_VERSION,
+  DESKTOP_PIPE_CHUNK_BYTES,
+  DesktopHostRequestDecoder,
+  DesktopHostResponseDecoder,
+  DesktopStreamBodyDecoder,
+  encodeDesktopRequestCancel,
+  encodeDesktopRequestData,
+  encodeDesktopRequestEnd,
+  encodeDesktopRequestStart,
+  encodeDesktopResponseData,
+  encodeDesktopResponseEnd,
+  encodeDesktopResponseError,
+  encodeDesktopResponseStart,
+  encodeDesktopStreamItem,
+  encodeDesktopStreamOpen,
+  isDesktopHostCommand,
+  isDesktopHostEvent,
+} from "../wire.ts";
+
+function decodeRequests(...chunks: Buffer[]) {
+  const decoder = new DesktopHostRequestDecoder();
+  const frames = chunks.flatMap((chunk) => decoder.push(chunk));
+  decoder.finish();
+  return frames;
+}
+
+function decodeResponses(...chunks: Buffer[]) {
+  const decoder = new DesktopHostResponseDecoder();
+  const frames = chunks.flatMap((chunk) => decoder.push(chunk));
+  decoder.finish();
+  return frames;
+}
+
+describe("请求帧", () => {
+  it("按序还原 start / data / end", () => {
+    const frames = decodeRequests(
+      Buffer.concat([
+        encodeDesktopRequestStart(7, {
+          url: "dsh-app://app/api/session",
+          method: "POST",
+          headers: [["content-type", "application/json"]],
+          hasBody: true,
+        }),
+        encodeDesktopRequestData(7, Buffer.from("body")),
+        encodeDesktopRequestEnd(7),
+      ]),
+    );
+    expect(frames).toEqual([
+      {
+        type: "start",
+        streamId: 7,
+        url: "dsh-app://app/api/session",
+        method: "POST",
+        headers: [["content-type", "application/json"]],
+        hasBody: true,
+      },
+      { type: "data", streamId: 7, data: Buffer.from("body") },
+      { type: "end", streamId: 7 },
+    ]);
+  });
+
+  it("跨分片投递时按帧补齐", () => {
+    const bytes = Buffer.concat([
+      encodeDesktopRequestStart(1, {
+        url: "dsh-app://app/",
+        method: "GET",
+        headers: [],
+        hasBody: false,
+      }),
+      encodeDesktopRequestCancel(1),
+    ]);
+    const decoder = new DesktopHostRequestDecoder();
+    const frames = [];
+    for (const byte of bytes) frames.push(...decoder.push(Buffer.from([byte])));
+    decoder.finish();
+    expect(frames.map((frame) => frame.type)).toEqual(["start", "cancel"]);
+  });
+
+  it("载荷长度错误的空帧与未知类型都报错", () => {
+    const start = encodeDesktopRequestStart(1, {
+      url: "dsh-app://app/",
+      method: "GET",
+      headers: [],
+      hasBody: false,
+    });
+    const cancel = encodeDesktopRequestCancel(1);
+    // 载荷长度字段被写成超过控制帧上限，解码要在读取前拒绝。
+    const tampered = Buffer.from(cancel);
+    tampered.writeUInt32BE(2 * 1024 * 1024, 9);
+    expect(() => decodeRequests(Buffer.concat([start, tampered]))).toThrow(/exceeds/);
+
+    const truncated = Buffer.from(cancel);
+    truncated.writeUInt32BE(1, 9);
+    expect(() => decodeRequests(Buffer.concat([start, truncated]))).toThrow(/inside a frame/);
+
+    const unknown = Buffer.from(start);
+    unknown.writeUInt8(9, 4);
+    expect(() => decodeRequests(unknown)).toThrow(/unknown request frame type/);
+  });
+
+  it("EOF 落在帧中间时报错", () => {
+    const decoder = new DesktopHostRequestDecoder();
+    decoder.push(
+      encodeDesktopRequestStart(1, {
+        url: "dsh-app://app/",
+        method: "GET",
+        headers: [],
+        hasBody: false,
+      }).subarray(0, 8),
+    );
+    expect(() => decoder.finish()).toThrow(/inside a frame/);
+  });
+
+  it("data 帧超过单帧上限时编码报错", () => {
+    expect(() => encodeDesktopRequestData(1, Buffer.alloc(DESKTOP_PIPE_CHUNK_BYTES + 1))).toThrow(
+      /exceeds/,
+    );
+  });
+});
+
+describe("响应帧", () => {
+  it("按序还原 start / data / end", () => {
+    const frames = decodeResponses(
+      Buffer.concat([
+        encodeDesktopResponseStart(3, {
+          status: 200,
+          headers: [["content-type", "text/html"]],
+          hasBody: true,
+        }),
+        encodeDesktopResponseData(3, Buffer.from("hi")),
+        encodeDesktopResponseEnd(3),
+      ]),
+    );
+    expect(frames).toEqual([
+      {
+        type: "start",
+        streamId: 3,
+        status: 200,
+        headers: [["content-type", "text/html"]],
+        hasBody: true,
+      },
+      { type: "data", streamId: 3, data: Buffer.from("hi") },
+      { type: "end", streamId: 3 },
+    ]);
+  });
+
+  it("错误帧携带消息", () => {
+    expect(decodeResponses(encodeDesktopResponseError(4, "boom"))).toEqual([
+      { type: "error", streamId: 4, message: "boom" },
+    ]);
+  });
+
+  it("非法帧标记报错", () => {
+    const bad = Buffer.from(encodeDesktopResponseEnd(1));
+    bad.writeUInt32BE(0xdead_beef, 0);
+    expect(() => decodeResponses(bad)).toThrow(/frame marker/);
+  });
+});
+
+describe("桌面流请求体", () => {
+  it("首行定 endpoint 与 payload，后续行是上行项", () => {
+    const decoder = new DesktopStreamBodyDecoder();
+    const text =
+      encodeDesktopStreamOpen("/session.follow", { args: { sessionId: "s1" } }) +
+      encodeDesktopStreamItem({ typed: "hi" }) +
+      encodeDesktopStreamItem(7);
+    expect(decoder.push(Buffer.from(text, "utf8"))).toEqual([
+      { endpoint: "/session.follow", payload: { args: { sessionId: "s1" } } },
+      { typed: "hi" },
+      7,
+    ]);
+    expect(decoder.finish()).toEqual([]);
+  });
+
+  it("行被切进不同字节块、多字节字符被切开也能还原", () => {
+    const decoder = new DesktopStreamBodyDecoder();
+    const bytes = Buffer.from(encodeDesktopStreamItem({ text: "撤回并重试" }), "utf8");
+    // 每 3 字节一块：中文的三字节序列正好被切开。
+    const values: unknown[] = [];
+    for (let offset = 0; offset < bytes.length; offset += 3)
+      values.push(...decoder.push(bytes.subarray(offset, offset + 3)));
+    values.push(...decoder.finish());
+    expect(values).toEqual([{ text: "撤回并重试" }]);
+  });
+
+  it("末行没有换行收尾时在 finish 里交付，空行忽略", () => {
+    const decoder = new DesktopStreamBodyDecoder();
+    expect(decoder.push(Buffer.from('\n{"endpoint":"/x"}', "utf8"))).toEqual([]);
+    expect(decoder.finish()).toEqual([{ endpoint: "/x" }]);
+  });
+
+  it("非法 JSON 报错（宿主据此回 400）", () => {
+    const decoder = new DesktopStreamBodyDecoder();
+    expect(() => decoder.push(Buffer.from("not json\n", "utf8"))).toThrow();
+  });
+});
+
+describe("IPC 契约", () => {
+  it("只接受当前协议版本的 ready 与文本 fatal", () => {
+    expect(
+      isDesktopHostEvent({ type: "ready", protocolVersion: DESKTOP_HOST_PROTOCOL_VERSION }),
+    ).toBe(true);
+    expect(isDesktopHostEvent({ type: "ready", protocolVersion: 99 })).toBe(false);
+    expect(isDesktopHostEvent({ type: "fatal", message: "x" })).toBe(true);
+    expect(
+      isDesktopHostEvent({ type: "fatal", message: "x", diagnostic: "Error: x\n    at a" }),
+    ).toBe(true);
+    expect(isDesktopHostEvent({ type: "fatal", message: "x", diagnostic: 7 })).toBe(false);
+    expect(isDesktopHostEvent({ type: "fatal" })).toBe(false);
+    expect(isDesktopHostEvent("ready")).toBe(false);
+  });
+
+  it("调试端点事件带可选 url 与原因", () => {
+    expect(isDesktopHostEvent({ type: "inspected", url: "ws://127.0.0.1:9229/uuid" })).toBe(true);
+    expect(isDesktopHostEvent({ type: "inspected", url: null })).toBe(true);
+    expect(isDesktopHostEvent({ type: "inspected", url: null, message: "listen failed" })).toBe(
+      true,
+    );
+    expect(isDesktopHostEvent({ type: "inspected" })).toBe(false);
+    expect(isDesktopHostEvent({ type: "inspected", url: 9229 })).toBe(false);
+    expect(isDesktopHostEvent({ type: "inspected", url: null, message: 7 })).toBe(false);
+  });
+
+  it("只接受 shutdown 与调试端点命令", () => {
+    expect(isDesktopHostCommand({ type: "shutdown" })).toBe(true);
+    expect(isDesktopHostCommand({ type: "inspect", port: 0 })).toBe(true);
+    expect(isDesktopHostCommand({ type: "inspect", port: 65_535 })).toBe(true);
+    expect(isDesktopHostCommand({ type: "inspect-off" })).toBe(true);
+    expect(isDesktopHostCommand({ type: "update-tasks" })).toBe(false);
+    expect(isDesktopHostCommand({ type: "inspect" })).toBe(false);
+    expect(isDesktopHostCommand({ type: "inspect", port: -1 })).toBe(false);
+    expect(isDesktopHostCommand({ type: "inspect", port: 65_536 })).toBe(false);
+    expect(isDesktopHostCommand({ type: "inspect", port: 9229.5 })).toBe(false);
+    expect(isDesktopHostCommand(null)).toBe(false);
+  });
+});

package/src/desktop-ipc.ts

@@ -0,0 +1,71 @@
+// 桌面形态的 **IPC 面**：只剩两条——"向壳发事件"（`ready` / `fatal`）与"收尾"。
+//
+// 以前这里还有一条请求/响应字节管道（FD 3/4）：页面的请求经它喂给宿主内的 `webServer`。那条路已退休——
+// 窗口现在从宿主真 webServer 的 origin（`http://127.0.0.1:<port>`）载入，请求直连它本身；管道留下的
+// 唯一后果是"没有 origin"，而基于 URL/WS 的东西（settings 的 describe 流、账号的 stream mux、vite 的
+// HMR）拿不到答复。判据与取舍见 `../config/desktop.cordis.patch.yml` 的注释。
+
+import type { AppProfileBoot } from "@morlay/dsh-app-boot";
+import { applyInspectorCommand, closeInspectorEndpoint } from "./inspector.ts";
+import { isDesktopHostCommand, type DesktopHostEvent } from "./wire.ts";
+
+/** 接上壳那条 IPC 通道要什么。 */
+export interface DesktopIpcOptions {
+  /** 装配结果：收尾时取它的 `shutdown`（尚未 settle 也照等，装配失败只当作没有树可停）。 */
+  readonly application: Promise<AppProfileBoot>;
+}
+
+/** 接好之后的信道两头。 */
+export interface DesktopIpc {
+  /** 向壳发事件（`ready` / `fatal`）。 */
+  readonly send: (event: DesktopHostEvent) => void;
+  /** 收尾：停树、断开 IPC 通道；幂等。 */
+  readonly stop: (exitCode?: number) => Promise<void>;
+}
+
+/**
+ * 接上 IPC 面：挂好生命周期（`shutdown` 命令 / 通道断开）。
+ * @param options - 装配结果。
+ * @returns 发事件与收尾两个入口。
+ */
+export function connectDesktopIpc(options: DesktopIpcOptions): DesktopIpc {
+  const { application } = options;
+  let stopping: Promise<void> | undefined;
+
+  const send = (event: DesktopHostEvent): void => {
+    if (process.send === undefined || !process.connected) return;
+    try {
+      process.send(event);
+    } catch (error) {
+      // 父进程并发断开时只吞掉通道已关闭这一种；其余照常抛出。
+      if ((error as NodeJS.ErrnoException).code !== "ERR_IPC_CHANNEL_CLOSED") throw error;
+    }
+  };
+
+  const stop = (exitCode = 0): Promise<void> => {
+    stopping ??= (async () => {
+      closeInspectorEndpoint();
+      const running = await application.catch(() => undefined);
+      await running?.shutdown.shutdown(exitCode);
+      if (process.connected) process.disconnect?.();
+      process.exitCode = exitCode;
+    })();
+    return stopping;
+  };
+
+  process.on("message", (message: unknown) => {
+    if (!isDesktopHostCommand(message)) return;
+    // 调试端点命令先于 shutdown 分派：它们只影响回环上的 Node inspector。
+    const inspected = applyInspectorCommand(message);
+    if (inspected !== undefined) {
+      send(inspected);
+      return;
+    }
+    if (message.type === "shutdown") void stop();
+  });
+  process.once("disconnect", () => {
+    void stop();
+  });
+
+  return { send, stop };
+}

package/src/fatal.ts

@@ -0,0 +1,30 @@
+// 出错时给壳的那条事件的形状：`message` 给壳的 dialog 用；`diagnostic` 是完整 `inspect`——stderr
+// 字节与这条 IPC 谁先到不确定，所以诊断跟着 IPC 一起走。两处用到（IPC 面与入口的顶层兜底），
+// 放这里而不是任何一边。
+
+import { inspect } from "node:util";
+import type { DesktopHostEvent } from "./wire.ts";
+
+/** 诊断上限：壳把它写进日志，再长也没有额外价值。 */
+const MAX_FATAL_DIAGNOSTIC_CHARS = 64 * 1024;
+
+/** 任何抛出来的东西 → 一行消息。 */
+export function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * 造一条 `fatal` 事件。
+ * @param error - 触发退出的错误（未必是 `Error`）。
+ * @returns 带完整诊断的 fatal 事件。
+ */
+export function fatalEvent(error: unknown): DesktopHostEvent {
+  return {
+    type: "fatal",
+    message: errorMessage(error),
+    diagnostic: inspect(error, { depth: 4, maxArrayLength: 50 }).slice(
+      0,
+      MAX_FATAL_DIAGNOSTIC_CHARS,
+    ),
+  };
+}

package/src/index.ts

@@ -0,0 +1,126 @@
+// 桌面宿主进程的**入口**：解析参数 → 装配 profile → 接线。就这三步——协议在
+// [`./desktop-ipc.ts`](./desktop-ipc.ts)、装配在 [`@morlay/dsh-app-boot`](../../boot/dsh-app-boot/README.md)、传输接管在
+// [`./transport.ts`](./transport.ts)；`webServer` 服务来自上游 `@deepseek-ai/dsh-host-webserver`。
+//
+// argv 与 web 入口**同一套**（见 [`./invocation.ts`](./invocation.ts)）：
+// `--profile-dir <dir> --runtime-dir <dir> [--patch <file>]... [--pnpm <path> --node-bin <dir>] [-- <内层参数>]`；
+// 另加两条通道：请求/响应字节管道（FD 3/4）与 Node IPC（`ready` / `fatal` / `shutdown`）。
+// 装配层完全由 profile 的 `dsh.profile.bundles` 决定：打包形态的 profile 由工具按官方形态种出
+// （见 `../.agents/designs/20260929-桌面host的运行时面与依赖边界.md`）；dev 形态由启动器把 app 目录当
+// profile root 传进来（同一份清单，见 `../../dshdev/.agents/designs/20261010-app目录即profile-root.md`）。
+
+import { fileURLToPath } from "node:url";
+import type { Context } from "@deepseek-ai/cordis";
+import { bootAppProfile } from "@morlay/dsh-app-boot";
+import { connectDesktopIpc } from "./desktop-ipc.ts";
+import { fatalEvent } from "./fatal.ts";
+import { parseHostInvocation } from "./invocation.ts";
+import { installPreloadSource } from "./preload-source.ts";
+import {
+  DESKTOP_STREAM_PATH,
+  desktopStreamStats,
+  installDesktopTransport,
+  takeOverDesktopAuthentication,
+} from "./transport.ts";
+import { DESKTOP_HOST_PROTOCOL_VERSION, type DesktopHostEvent } from "./wire.ts";
+import type {} from "@deepseek-ai/dsh-api-gateway";
+import type {} from "@deepseek-ai/dsh-client-connection";
+import type {} from "@deepseek-ai/dsh-host-webserver";
+
+// 桌面形态自己的 overlay：产品遥测、账号 UI，以及 web-runtime 的桌面配置。
+const DESKTOP_PATCH = fileURLToPath(new URL("../config/desktop.cordis.patch.yml", import.meta.url));
+
+// 按需的内存/流上报：默认关，`DSH_MEMORY_REPORT=1` 时每 5 秒一行。用来把「宿主内存一直在涨」
+// 落到具体哪条流、多少字节上（heapUsed 涨 = 转译/业务对象，external 涨 = 缓冲或原生件）。
+function reportMemoryWhenAsked(ctx: Context): void {
+  if (process.env.DSH_MEMORY_REPORT !== "1") return;
+  const megabytes = (value: number): string => (value / 1024 / 1024).toFixed(1);
+  const timer = 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`,
+    );
+  }, 5000);
+  timer.unref();
+}
+
+// 插件页的包操作通道：随包 node 跑随包 pnpm；`ELECTRON_RUN_AS_NODE` 让 Electron 把自己当 node 用。
+function packageManagerOf(pnpmEntry: string, nodeBin: string | undefined) {
+  return {
+    command: process.execPath,
+    args: ["--expose-internals", pnpmEntry],
+    env: {
+      ELECTRON_RUN_AS_NODE: "1",
+      DSH_DESKTOP_NODE_EXECUTABLE: process.execPath,
+      PATH: `${nodeBin ?? ""}${nodeBin === undefined ? "" : ":"}${process.env.PATH ?? ""}`,
+    },
+  };
+}
+
+async function main(): Promise<void> {
+  const invocation = parseHostInvocation("dsh desktop", process.argv.slice(2));
+  if (process.send === undefined)
+    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;
+
+  // 装配走 [`./app-boot.ts`](./app-boot.ts) 那条路（与 web 形态同一份实现）：层由 profile 的
+  // `dsh.profile.bundles` 决定（各 bundle 自己的 patch 由 loader 按 `dsh.bundle.patch` 读），
+  // 这里只按顺序补两层 overlay：调用方给的（壳）+ 桌面形态自己的。
+  const application = bootAppProfile({
+    profileDir,
+    profile: "desktop",
+    patchFiles: [...patches, DESKTOP_PATCH],
+    // 桌面壳自己管窗口：不让 app 行去开浏览器；`--` 之后的内层参数排在其后。
+    args: ["--no-open", ...inner],
+    ...(pnpmEntry === undefined ? {} : { packageManager: packageManagerOf(pnpmEntry, nodeBin) }),
+  });
+
+  const { ctx } = await application;
+  takeOverDesktopAuthentication(ctx);
+  installDesktopTransport(ctx);
+  reportMemoryWhenAsked(ctx);
+  // 调试窗口的前端产物：桌面档自己托管，不从上游 inspector 行取（那条路由与它的 Worker 绑在一起）。
+  // preload 的源码由这里现场打成 CJS（sandboxed preload 只能 CJS），壳在窗口创建前取走——装配目录里
+  // 因此不再需要一份预产的 `dist/`。
+  const shellRoot = process.env["DSH_DESKTOP_SHELL_ROOT"];
+  if (shellRoot !== undefined && shellRoot !== "") {
+    installPreloadSource(ctx, { shellRoot });
+  }
+  // 真 webServer（上游 `@deepseek-ai/dsh-host-webserver`）：只用它的 `port` 报 origin 给壳。
+  const webServer = ctx.get("webServer") as unknown as { readonly port: number };
+  const ipc = connectDesktopIpc({ application });
+
+  const gateway = ctx.get("typertGateway");
+  ctx.logger.info("transport ready %o", {
+    // 结构化字段：键名 `.` 分层、不带空格；值作为参数传（不走 `key=value` 文本）。
+    webServer: webServer.constructor.name,
+    gateway: gateway === undefined ? "missing" : "present",
+    streamRoute: DESKTOP_STREAM_PATH,
+  });
+  ipc.send({
+    type: "ready",
+    protocolVersion: DESKTOP_HOST_PROTOCOL_VERSION,
+    // 真 webServer 的 origin：壳用它载入窗口。基于 URL/WS 的东西（settings 的 describe 流、账号的
+    // stream mux、vite 的 HMR）都要求窗口的来源是它——以前没有 origin（请求走字节管道喂进来），那些
+    // 长连接拿不到答复，表现为"设置页永远不可用、连请求都看不到"。
+    origin: `http://127.0.0.1:${String(webServer.port)}`,
+  });
+}
+
+if (import.meta.main) {
+  // 顶层兜底**只能用 console**：走到这里时树可能还没起（`ctx.logger` 不存在）或已经拆了。
+  main().catch((error: unknown) => {
+    if (process.send !== undefined && process.connected)
+      process.send(fatalEvent(error) satisfies DesktopHostEvent, (sendError) => {
+        if (sendError !== null) console.error(sendError);
+      });
+    console.error(error);
+    process.exitCode = 1;
+    if (process.connected) process.disconnect?.();
+  });
+}

package/src/inspector.ts

@@ -0,0 +1,44 @@
+// 桌面档的后端调试端点：host 运行时开关 Node 自己的 inspector，只监听回环。
+// 与 `DSH_DESKTOP_HOST_INSPECT_PORT` 那条启动参数用的是同一套机制，区别是这条不需要重启进程。
+
+import inspector from "node:inspector";
+import type { DesktopHostCommand, DesktopHostEvent } from "./wire.ts";
+
+type InspectorEvent = Extract<DesktopHostEvent, { type: "inspected" }>;
+
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** 打开回环上的 Node inspector，返回它的 WebSocket 端点（`port` 为 0 时用随机端口）。 */
+export function openInspectorEndpoint(port: number): string {
+  if (!Number.isInteger(port) || port < 0 || port > 65_535)
+    throw new Error(`dsh desktop: inspector port ${String(port)} is out of range`);
+  // 已经有端点就复用它：dev 形态的 `--inspect=127.0.0.1:<port>` 启动参数已经占着一个，
+  // 关掉再开只会把那个端口换成新的。
+  const existing = inspector.url();
+  if (existing !== undefined) return existing;
+  inspector.open(port, "127.0.0.1");
+  const url = inspector.url();
+  if (url === undefined) throw new Error("dsh desktop: the inspector endpoint did not open");
+  return url;
+}
+
+/** 关掉调试端点；没开时什么都不做。 */
+export function closeInspectorEndpoint(): void {
+  inspector.close();
+}
+
+/** 处理一条调试端点命令，返回要回报给壳的事件；不是调试命令时返回 undefined。 */
+export function applyInspectorCommand(command: DesktopHostCommand): InspectorEvent | undefined {
+  if (command.type === "inspect-off") {
+    closeInspectorEndpoint();
+    return { type: "inspected", url: null };
+  }
+  if (command.type !== "inspect") return undefined;
+  try {
+    return { type: "inspected", url: openInspectorEndpoint(command.port) };
+  } catch (error) {
+    return { type: "inspected", url: null, message: errorText(error) };
+  }
+}

package/src/invocation.ts

@@ -0,0 +1,68 @@
+// 两个宿主入口（桌面 [`./index.ts`](./index.ts) 与 web [`./web.ts`](./web.ts)）**共用**的启动参数。
+//
+// 为什么非要把这套 flag 抽出来：这两个入口拿到的输入完全同形——profile root、工具链根、形态自己的
+// overlay、应用包通道、内层参数。以前桌面用位置参数（`argv[2]`/`argv[3]`）、web 用 `--profile-dir`
+// 风格 flag，各自解析、各自组选项，"挂哪一层、锚点指哪"很容易只在一边改对，于是出现"dev 正常、打包
+// 不对"这种只能靠猜的差异。现在只有这一处解析，两个入口的输入同形。
+
+/** One host process invocation: what the process was asked to boot. */
+export interface HostInvocation {
+  /** profile root：dev 是 app 目录本身，打包是 `$DSH_HOME/profiles/<name>`。 */
+  readonly profileDir: string;
+  /** 工具链根（`node` / `pnpm` / loader）：不是依赖面。 */
+  readonly runtimeDir: string;
+  /** 形态自己的 overlay patch 文件，按 argv 顺序排在 bundle 层与 profile 自己的 patch 之后。 */
+  readonly patches: string[];
+  /** 应用包操作通道：随包 pnpm 的入口（缺省时插件页回退到进程 PATH）。 */
+  readonly pnpmEntry?: string;
+  /** 包通道要用的 node 可执行文件（打包形态的随包 node，与 `pnpm` 同属工具链）。 */
+  readonly nodeBin?: string;
+  /** `--` 之后的内层参数，原样交给树里 app 插件的 flag family。 */
+  readonly inner: string[];
+}
+
+/**
+ * 解析宿主入口的参数。
+ * @param binName - 报错时前缀用的入口名（`dsh desktop` / `dsh web`）。
+ * @param argv - `process.argv.slice(2)`。
+ * @returns 两形态同形的启动参数。
+ * @throws 缺两格锚点、该带值的参数缺值、或参数名不认识时。
+ */
+export function parseHostInvocation(binName: string, argv: readonly string[]): HostInvocation {
+  let profileDir: string | undefined;
+  let runtimeDir: string | undefined;
+  let pnpmEntry: string | undefined;
+  let nodeBin: string | undefined;
+  const patches: string[] = [];
+  const inner: string[] = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--") {
+      inner.push(...argv.slice(index + 1));
+      break;
+    }
+    const value = (): string => {
+      const next = argv[index + 1];
+      if (next === undefined) 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 === undefined || runtimeDir === undefined) {
+    throw new Error(`${binName}: expected --profile-dir <dir> and --runtime-dir <dir>`);
+  }
+  return {
+    profileDir,
+    runtimeDir,
+    patches,
+    ...(pnpmEntry === undefined ? {} : { pnpmEntry }),
+    ...(nodeBin === undefined ? {} : { nodeBin }),
+    inner,
+  };
+}

package/src/paths.ts

@@ -0,0 +1,4 @@
+// 壳与 host 共享的路径事实（两侧都要用它拼调试窗口的地址，只有一份）。
+
+/** 应用 origin 下托管调试窗口前端产物的前缀。 */
+export const DEVTOOLS_ASSETS_PREFIX = "/node-devtools";