@morlay/dsh-desktop-host 0.2.5 → 0.2.7

package/dist/preload-source.js

@@ -0,0 +1,80 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { rolldown } from "rolldown";
+//#region src/preload-source.ts
+/**
+* preload 的**源码**由服务现场打包成 CJS 交给壳，装配目录里因此不再有 `dist/`。
+*
+* 为什么需要它：sandboxed preload 有三个硬约束——只能 CJS、不能 ESM、不能 `require` 第三方（因此也挂不了
+* 本仓库那套 TS hooks）。而它的源码是 TS（还跨几个文件：`preload-app.ts` 拉 `./stream-uplink.ts` 那些），
+* 所以只能**打成单文件 CJS**——打包这件事放在这里做，壳就不必在装配时预先产出一份 `dist/`。
+*
+* 谁来取：壳在窗口创建之前（那时宿主已经就绪）取回来落盘，再把路径交给 `BrowserWindow` 的 `preload`。
+*/
+/** 壳取 preload 的路径（`GET` 它得到可执行的 CJS 字节）。 */
+const PRELOAD_SOURCE_PATH = "/@dsh/preload.cjs";
+/**
+* 把 preload 打包成单文件 CJS。
+*
+* @param options - 见 {@link PreloadSourceOptions}。
+* @returns CJS 源码。
+*/
+async function bundlePreload(options) {
+	const bundle = await rolldown({
+		input: join(options.shellRoot, "src", "preload-app.ts"),
+		platform: "node",
+		external: ["electron"]
+	});
+	try {
+		const { output } = await bundle.generate({
+			format: "cjs",
+			inlineDynamicImports: true
+		});
+		const chunk = output.find((item) => item.type === "chunk");
+		if (chunk === void 0) throw new Error("dsh desktop: preload bundling produced no chunk");
+		return chunk.code;
+	} finally {
+		await bundle.close();
+	}
+}
+/** 构建期打好的那份 preload（`prepareShell` 里调 {@link bundlePreload} 产出）。 */
+const PRELOAD_BUNDLE_FILE = join("dist", "preload.cjs");
+/**
+* 在宿主的 webServer 上注册 `/@dsh/preload.cjs`：壳按这条路径取走 preload 的 CJS 字节。
+*
+* **读的是构建期打好的文件**，不在运行时打包：现场打包要读 `src/preload-app.ts`，而打包器（rolldown）
+* 是 native 模块、用自己的文件 IO——**读不了 asar 内的路径**（宿主跑在 Electron 上，`fs` 才被补丁照看着）。
+* 构建期那份读进来是字节，`readFile` 对归档是透明的。
+*
+* @param ctx - 宿主上下文（拿 `webServer`）。
+* @param options - 见 {@link PreloadSourceOptions}。
+*/
+function installPreloadSource(ctx, options) {
+	const file = join(options.shellRoot, PRELOAD_BUNDLE_FILE);
+	const serve = (req, res) => {
+		(async () => {
+			let code;
+			try {
+				code = await readFile(file);
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				ctx.logger.error(`dsh desktop: preload bundle is unreadable at ${file}: ${message}`);
+				res.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
+				res.end(`dsh desktop: preload bundle is unreadable at ${file}: ${message}`);
+				return;
+			}
+			res.writeHead(200, {
+				"content-type": "text/javascript; charset=utf-8",
+				"cache-control": "no-store"
+			});
+			res.end(req.method === "HEAD" ? void 0 : code);
+		})();
+	};
+	ctx.effect(() => ctx.webServer.register({
+		kind: "exact",
+		path: PRELOAD_SOURCE_PATH,
+		handler: serve
+	}), `dsh-desktop-host: ${PRELOAD_SOURCE_PATH}`);
+}
+//#endregion
+export { PRELOAD_BUNDLE_FILE, PRELOAD_SOURCE_PATH, bundlePreload, installPreloadSource };

package/dist/settings-namespace.d.mts

@@ -0,0 +1,9 @@
+import { Context } from "@deepseek-ai/cordis";
+//#region src/settings-namespace.d.ts
+export declare const name = "@morlay/dsh-desktop-host-settings-namespace";
+/**
+ * 注册 settings namespace（`auto: false` 表示这个 namespace 的界面由宿主自己安排，不走自动渲染）。
+ * @param ctx - 宿主的上下文。
+ */
+export declare function apply(ctx: Context): void;
+//#endregion

package/dist/settings-namespace.js

@@ -0,0 +1,13 @@
+//#region src/settings-namespace.ts
+const name = "@morlay/dsh-desktop-host-settings-namespace";
+/**
+* 注册 settings namespace（`auto: false` 表示这个 namespace 的界面由宿主自己安排，不走自动渲染）。
+* @param ctx - 宿主的上下文。
+*/
+function apply(ctx) {
+	ctx.inject(["settings"], (scope) => {
+		scope.effect(() => scope.settings.configure({ auto: false }, ctx.fiber));
+	});
+}
+//#endregion
+export { apply, name };

package/dist/wire.d.mts

@@ -0,0 +1,109 @@
+//#region src/wire.d.ts
+export declare const DESKTOP_HOST_PROTOCOL_VERSION: 1;
+export declare const DESKTOP_STREAM_PATH = "/.dsh/remote-stream";
+export declare function encodeDesktopStreamOpen(endpoint: string, payload: unknown): string;
+export declare function encodeDesktopStreamItem(item: unknown): string;
+export declare const DESKTOP_REQUEST_PIPE_FD = 3;
+export declare const DESKTOP_RESPONSE_PIPE_FD = 4;
+export declare const DESKTOP_CONTROL_IPC_FD = 5;
+export declare const DESKTOP_PIPE_CHUNK_BYTES: number;
+export interface DesktopHostRequestStart {
+  readonly url: string;
+  readonly method: string;
+  readonly headers: readonly [string, string][];
+  readonly hasBody: boolean;
+}
+export type DesktopHostRequestFrame = ({
+  readonly type: "start";
+  readonly streamId: number;
+} & DesktopHostRequestStart) | {
+  readonly type: "data";
+  readonly streamId: number;
+  readonly data: Buffer;
+} | {
+  readonly type: "end";
+  readonly streamId: number;
+} | {
+  readonly type: "cancel";
+  readonly streamId: number;
+};
+export type DesktopHostResponseFrame = {
+  readonly type: "start";
+  readonly streamId: number;
+  readonly status: number;
+  readonly headers: readonly [string, string][];
+  readonly hasBody: boolean;
+} | {
+  readonly type: "data";
+  readonly streamId: number;
+  readonly data: Buffer;
+} | {
+  readonly type: "end";
+  readonly streamId: number;
+} | {
+  readonly type: "error";
+  readonly streamId: number;
+  readonly message: string;
+};
+export type DesktopHostCommand = {
+  readonly type: "shutdown";
+} | {
+  readonly type: "inspect";
+  readonly port: number;
+} | {
+  readonly type: "inspect-off";
+};
+export type DesktopHostEvent = {
+  readonly type: "ready";
+  readonly protocolVersion: typeof DESKTOP_HOST_PROTOCOL_VERSION;
+  /**
+   * webServer 的 origin（`http://127.0.0.1:<port>`）：壳用它载入窗口。基于 URL/WS 的东西（settings 的
+   * describe 流、账号的 stream mux、vite 的 HMR）要求窗口来源就是它。
+   */
+  readonly origin: string;
+} | {
+  readonly type: "fatal";
+  readonly message: string;
+  readonly diagnostic?: string;
+} | {
+  readonly type: "inspected";
+  readonly url: string | null;
+  readonly message?: string;
+};
+export declare function encodeDesktopRequestStart(streamId: number, request: DesktopHostRequestStart): Buffer;
+export declare function encodeDesktopRequestData(streamId: number, data: Uint8Array): Buffer;
+export declare function encodeDesktopRequestEnd(streamId: number): Buffer;
+export declare function encodeDesktopRequestCancel(streamId: number): Buffer;
+export declare function encodeDesktopResponseStart(streamId: number, response: {
+  readonly status: number;
+  readonly headers: readonly [string, string][];
+  readonly hasBody: boolean;
+}): Buffer;
+export declare function encodeDesktopResponseData(streamId: number, data: Uint8Array): Buffer;
+export declare function encodeDesktopResponseEnd(streamId: number): Buffer;
+export declare function encodeDesktopResponseError(streamId: number, message: string): Buffer;
+export declare class DesktopStreamBodyDecoder {
+  private readonly text;
+  private buffer;
+  push(chunk: Uint8Array): unknown[];
+  finish(): unknown[];
+  private take;
+}
+export declare class DesktopHostRequestDecoder {
+  private buffer;
+  push(chunk: Buffer): DesktopHostRequestFrame[];
+  finish(): void;
+  private next;
+  private parseStart;
+}
+export declare class DesktopHostResponseDecoder {
+  private buffer;
+  push(chunk: Buffer): DesktopHostResponseFrame[];
+  finish(): void;
+  private next;
+  private parseStart;
+  private parseError;
+}
+export declare function isDesktopHostEvent(value: unknown): value is DesktopHostEvent;
+export declare function isDesktopHostCommand(value: unknown): value is DesktopHostCommand;
+//#endregion

package/{lib → dist}/wire.js

@@ -254,10 +254,13 @@ function isDesktopHostEvent(value) {
 	if (!isRecord(value)) return false;
 	if (value.type === "ready") return value.protocolVersion === 1;
 	if (value.type === "fatal") return typeof value.message === "string" && (value.diagnostic === void 0 || typeof value.diagnostic === "string");
+	if (value.type === "inspected") return (value.url === null || typeof value.url === "string") && (value.message === void 0 || typeof value.message === "string");
 	return false;
 }
 function isDesktopHostCommand(value) {
-	return isRecord(value) && value.type === "shutdown";
+	if (!isRecord(value)) return false;
+	if (value.type === "shutdown" || value.type === "inspect-off") return true;
+	return value.type === "inspect" && Number.isInteger(value.port) && value.port >= 0 && value.port <= 65535;
 }
 //#endregion
 export { DESKTOP_CONTROL_IPC_FD, DESKTOP_HOST_PROTOCOL_VERSION, DESKTOP_PIPE_CHUNK_BYTES, DESKTOP_REQUEST_PIPE_FD, DESKTOP_RESPONSE_PIPE_FD, DESKTOP_STREAM_PATH, DesktopHostRequestDecoder, DesktopHostResponseDecoder, DesktopStreamBodyDecoder, encodeDesktopRequestCancel, encodeDesktopRequestData, encodeDesktopRequestEnd, encodeDesktopRequestStart, encodeDesktopResponseData, encodeDesktopResponseEnd, encodeDesktopResponseError, encodeDesktopResponseStart, encodeDesktopStreamItem, encodeDesktopStreamOpen, isDesktopHostCommand, isDesktopHostEvent };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@morlay/dsh-desktop-host",
-  "version": "0.2.5",
-  "description": "Desktop host process for dsh-desktopify: boots the desktop profile and serves it through an in-process, portless webServer over byte pipes — upstream apps/desktop-host with the web carrier taken over and the Office composition dropped.",
+  "version": "0.2.7",
+  "description": "Desktop host process for dshdev: boots the desktop profile and serves it through an in-process, portless webServer over byte pipes — upstream apps/desktop-host with the web carrier taken over and the Office composition dropped.",
   "keywords": [
     "desktop",
     "dsh",
@@ -16,37 +16,61 @@
     "url": "https://github.com/morlay/dsh-plugin.git"
   },
   "files": [
+    "src",
     "locale/*.json",
-    "lib",
+    "dist",
     "config/desktop.cordis.patch.yml"
   ],
   "type": "module",
-  "main": "./lib/index.js",
   "exports": {
-    ".": "./lib/index.js",
-    "./webserver": "./lib/webserver.js",
-    "./wire": "./lib/wire.js",
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.js"
+    },
+    "./preload-source": {
+      "types": "./dist/preload-source.d.mts",
+      "default": "./dist/preload-source.js"
+    },
+    "./wire": {
+      "types": "./dist/wire.d.mts",
+      "default": "./dist/wire.js"
+    },
+    "./paths": {
+      "types": "./dist/paths.d.mts",
+      "default": "./dist/paths.js"
+    },
+    "./settings-namespace": {
+      "types": "./dist/settings-namespace.d.mts",
+      "default": "./dist/settings-namespace.js"
+    },
     "./package.json": "./package.json",
     "./locale/*.json": "./locale/*.json"
   },
   "dependencies": {
-    "@deepseek-ai/dsh": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-app-boot": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-host-webserver": "^0.2.0-rc.2",
-    "@deepseek-ai/schemastery": "^3.18.4"
+    "@deepseek-ai/dsh-host-webserver": "^0.2.1-rc.1",
+    "@deepseek-ai/schemastery": "^3.18.5",
+    "@morlay/dsh-app-boot": "0.2.7",
+    "@morlay/dsh-client-modules": "0.2.8",
+    "@morlay/web-custom-profile": "0.0.2",
+    "lightningcss": "^1.32.0",
+    "rolldown": "1.x",
+    "ws": "^8.21.3"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "4.0.4",
-    "@deepseek-ai/dsh-api-gateway": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-connection": "0.2.0-rc.2",
+    "@deepseek-ai/cordis": "^4.0.5",
     "@local/devkit": "0.1.0",
-    "@types/node": "^26.5.0"
+    "@types/node": "^26.5.0",
+    "@types/ws": "^8.18.2",
+    "playwright": "^1.64.0"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.4"
+    "@deepseek-ai/cordis": "^4.0.5",
+    "@deepseek-ai/dsh-api-gateway": "^0.2.1-rc.1",
+    "@deepseek-ai/dsh-client-connection": "^0.2.1-rc.1"
   },
   "engines": {
-    "node": ">=24.11.0"
+    "node": ">=24.11.0",
+    "dsh": ">= 0.2.1-rc.1 < 0.2.2"
   },
   "scripts": {
     "build": "pnpm exec tsdown"

package/src/__tests__/desktop-patch.spec.ts

@@ -0,0 +1,171 @@
+import { readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+const repoRoot = process.cwd();
+const PATCH_PATH = join(
+  repoRoot,
+  "packages/desktop/dsh-desktop-host/config/desktop.cordis.patch.yml",
+);
+const BUNDLE_ROOT = join(repoRoot, "vendor/deepseek-harness/packages/bundle");
+// 前端服务（`@morlay/dsh-client-modules`）那一行：单独一层，web 形态也要挂（用 `--patch`）。
+const DEV_CLIENT_PATCH_PATH = join(
+  repoRoot,
+  "packages/bundles/web-custom-profile/cordis.patch.yml",
+);
+const devClientPatch = await readFile(DEV_CLIENT_PATCH_PATH, "utf8");
+const UPSTREAM_PATCHES = ["base/cordis.patch.yml", "web-app/cordis.patch.yml"];
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const patch = await readFile(PATCH_PATH, "utf8");
+
+// 停用/配置的目标行 id（顶层 `- id:`，不含 insert 出来的行）。
+function disabledIds(text: string): string[] {
+  return [...text.matchAll(/^- id: (\S+)\n {2}disabled: true$/gm)].map((match) => match[1]!);
+}
+
+function configuredIds(text: string): string[] {
+  return [...text.matchAll(/^- id: (\S+)\n {2}config:$/gm)].map((match) => match[1]!);
+}
+
+function insertedNames(text: string): string[] {
+  const names: string[] = [];
+  for (const block of text.split(/^- insert:\s*$/m).slice(1)) {
+    names.push(
+      ...[...block.matchAll(/^ {4}- id: (\S+)\n {6}name: "([^"]+)"$/gm)].map((m) => m[2]!),
+    );
+  }
+  return names;
+}
+
+// 上游 patch 里的 `行 id → 模块名`（本 overlay 只按 id 瞄准，名字留在上游那一份）。
+async function upstreamModules(): Promise<Map<string, string>> {
+  const modules = new Map<string, string>();
+  for (const file of UPSTREAM_PATCHES) {
+    const text = await readFile(join(BUNDLE_ROOT, file), "utf8");
+    for (const match of text.matchAll(/^\s*- id: (\S+)\n\s+name: ['"]([^'"]+)['"]/gm))
+      modules.set(match[1]!, match[2]!);
+  }
+  return modules;
+}
+
+const upstream = await upstreamModules();
+
+// 账号面的取舍**不在桌面档**：本部署不含登录，那几条由 profile 档
+// [`@morlay/mydsh-profile`](../../../bundles/mydsh-profile/tsdown.config.ts) 停（web 形态也同样受益）。
+// 桌面档这里只停"桌面形态"自己的两件事：传输接管（`webserver` → `portless-webserver`）与产品遥测。
+//
+// 为什么非要分家：应用顺序是 `bundle 层 → overlay`，而桌面 overlay 由宿主追加在 `patchFiles` 末尾
+// （`src/index.ts:80`）——排最后、覆盖前面所有层。取舍写在 overlay 里，profile 档的同 id 设置就"改不动"。
+// 本部署不要账号 UI：停上游那一行，由 profile 档的空壳行补上它的 settings namespace 注册。
+const ACCOUNT_ROWS: Readonly<Record<string, string>> = {
+  "ui-settings-account": "@deepseek-ai/dsh-client-ui-settings-account",
+};
+
+// 桌面档**必须**停的产品遥测面：两行只在 profile 名为 `desktop` 时激活，靠构建期环境变量
+// `DSH_CLIENT_VERSION` 填 `serviceVersion`（必填）；自研壳不传那个变量 → 遥测行配置校验失败、
+// 产品分析行 pending，页面启动时那条 watchPolicy 流拿 502。本地桌面部署没有上报对象。
+const TELEMETRY_ROWS = {
+  "desktop-product-telemetry": "@deepseek-ai/dsh-host-product-telemetry-otel",
+  "product-analytics": "@deepseek-ai/dsh-client-product-analytics",
+} as const;
+
+// 桌面档**故意不动**的行：它们不是登录面，模型路径靠它们。
+const KEPT_ROWS = {
+  credentials: "@deepseek-ai/dsh-credentials-local",
+  authorization: "@deepseek-ai/dsh-authorization",
+  "llm-deepseek": "@deepseek-ai/dsh-llm-deepseek-api-key",
+} as const;
+
+describe("桌面 overlay 的停用清单", () => {
+  it("瞄准的上游行都存在，且行 id 现在确实指向那个模块", () => {
+    for (const [id, module] of [
+      ...Object.entries(ACCOUNT_ROWS),
+      ...Object.entries(TELEMETRY_ROWS),
+      ...Object.entries(KEPT_ROWS),
+      ["webserver", "@deepseek-ai/dsh-host-webserver"] as const,
+    ]) {
+      expect(upstream.get(id), `upstream row ${id} moved or was renamed`).toBe(module);
+    }
+  });
+
+  it("停用清单是产品遥测 + 账号 UI（后者由 profile 档的空壳行接替）", () => {
+    // 停用必须在 overlay：写在 bundle 层会被后来应用的层盖回去（实测），而 overlay 排最后。
+    // 停的是"账号 UI"那一行——它同时是 settings namespace 的 owner，所以由 profile 档补一个空壳注册。
+    expect(disabledIds(patch).sort()).toEqual(
+      ["ui-settings-account", ...Object.keys(TELEMETRY_ROWS)].sort(),
+    );
+  });
+
+  it("桌面档停的浏览器模块是产品分析与账号 UI", () => {
+    const clientModules = [...Object.values(ACCOUNT_ROWS), ...Object.values(TELEMETRY_ROWS)].filter(
+      (module) => module.startsWith("@deepseek-ai/dsh-client-"),
+    );
+    expect(clientModules.sort()).toEqual([
+      "@deepseek-ai/dsh-client-product-analytics",
+      "@deepseek-ai/dsh-client-ui-settings-account",
+    ]);
+  });
+
+  it("前端服务那一行单独一层，按包名指到 @morlay/dsh-client-modules", async () => {
+    expect(insertedNames(devClientPatch)).toEqual(["@morlay/dsh-client-modules"]);
+    const built = join(repoRoot, "packages/client/dsh-client-modules/dist/index.js");
+    if (await pathExists(built)) expect((await stat(built)).isFile()).toBe(true);
+  });
+
+  it("模型路径那几行没有一起被停", () => {
+    for (const id of Object.keys(KEPT_ROWS)) expect(disabledIds(patch)).not.toContain(id);
+  });
+
+  it("不再替换 webServer；配 web-runtime 与它的随机端口", () => {
+    // 以前这里禁掉 `webserver` 并插一个"无端口替身"（请求走字节管道喂进来）。那条路没有 origin，
+    // 基于 URL/WS 的东西（settings 的 describe 流、账号的 stream mux、vite 的 HMR）拿不到答复——
+    // 现在照常 listen，壳用它的 origin 载入窗口。
+    expect(insertedNames(patch)).toEqual(["../src/settings-namespace.ts"]);
+    expect(disabledIds(patch)).not.toContain("webserver");
+    expect(configuredIds(patch).sort()).toEqual(["web-runtime", "webserver"]);
+    // 插入的那一行是"账号面空壳"：顶替被停掉的 `ui-settings-account` 那个 settings namespace 注册。
+    // 端口必须随机：上游 `web-app` 给的是 `webStartup.port ?? 3080`，桌面没有 `--port`，于是落到 3080
+    // ——两个实例或本机别的工具占了它，第二次就起不来。
+    expect(portOfWebServer(patch)).toBe(0);
+  });
+
+  it("停用各归其位：遥测与官方账号实现都在桌面 overlay（写在 bundle 层会被盖回去）", async () => {
+    const overlay = await readFile(
+      join(repoRoot, "packages/desktop/dsh-desktop-host/config/desktop.cordis.patch.yml"),
+      "utf8",
+    );
+    // 桌面 overlay 只管桌面形态自己那两件：传输接管与产品遥测。
+    for (const id of Object.keys(TELEMETRY_ROWS)) {
+      expect(overlay, `overlay 该停 ${id}`).toContain(id);
+    }
+    // 账号实现必须在本 overlay 里（它是最后应用的一层）；写在 profile 档里会被后来应用的层盖回去。
+    for (const id of Object.keys(ACCOUNT_ROWS)) {
+      expect(overlay, `overlay 该停在 ${id}`).toContain(id);
+    }
+    const profile = await readFile(
+      join(repoRoot, "packages/bundles/mydsh-profile/cordis.patch.yml"),
+      "utf8",
+    );
+    // profile 档不承担停用（写那儿不生效）；它负责的是"空壳注册"。
+    expect(profile, "profile 档不该出现停用").not.toContain("disabled: true");
+  });
+});
+
+/** 桌面 overlay 给 `webserver` 定的端口。 */
+function portOfWebServer(source: string): number | undefined {
+  const row = source.split("\n- id: ").find((chunk) => chunk.startsWith("webserver"));
+  return row === undefined
+    ? undefined
+    : /port: (\d+)/.exec(row)?.[1] === undefined
+      ? undefined
+      : Number(/port: (\d+)/.exec(row)?.[1]);
+}

package/src/__tests__/inspector.spec.ts

@@ -0,0 +1,50 @@
+import inspector from "node:inspector";
+import { afterEach, describe, expect, it } from "vitest";
+import { applyInspectorCommand, closeInspectorEndpoint } from "../inspector.ts";
+
+afterEach(() => {
+  closeInspectorEndpoint();
+});
+
+describe("调试端点开关", () => {
+  it("开在回环的随机端口上并回报端点，关掉后端点消失", () => {
+    const event = applyInspectorCommand({ type: "inspect", port: 0 });
+    expect(event?.type).toBe("inspected");
+    const url = event?.url ?? "";
+    expect(url).toMatch(/^ws:\/\/127\.0\.0\.1:\d+\/[0-9a-f-]+$/u);
+    expect(url).not.toContain(":0/");
+    expect(inspector.url()).toBe(url);
+
+    expect(applyInspectorCommand({ type: "inspect-off" })).toEqual({
+      type: "inspected",
+      url: null,
+    });
+    expect(inspector.url()).toBeUndefined();
+  });
+
+  it("已有端点时复用而不是换端口（dev 的 --inspect 启动参数占着的那个）", () => {
+    const first = applyInspectorCommand({ type: "inspect", port: 0 });
+    const second = applyInspectorCommand({ type: "inspect", port: 0 });
+    expect(second).toEqual(first);
+    expect(inspector.url()).toBe(first?.url);
+  });
+
+  it("端口非法时报原因而不是抛出", () => {
+    const event = applyInspectorCommand({ type: "inspect", port: 65_536 });
+    expect(event?.type).toBe("inspected");
+    expect(event?.url).toBeNull();
+    expect(event?.message).toBeTruthy();
+  });
+
+  it("重复关闭是幂等的，非调试命令不回应", () => {
+    expect(applyInspectorCommand({ type: "inspect-off" })).toEqual({
+      type: "inspected",
+      url: null,
+    });
+    expect(applyInspectorCommand({ type: "inspect-off" })).toEqual({
+      type: "inspected",
+      url: null,
+    });
+    expect(applyInspectorCommand({ type: "shutdown" })).toBeUndefined();
+  });
+});

package/src/__tests__/invocation.spec.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import { parseHostInvocation } from "../invocation.ts";
+
+// 两个入口（desktop 的 `index.ts`、web 的 `web.ts`）共用这一套参数：这是"形态之间唯一该不同的地方"
+// 之外的全部输入——两形态从这里拿到的东西必须同形，否则"哪一层生效"又会两边不一致。
+describe("宿主入口的参数（desktop / web 共用）", () => {
+  it("取两格锚点、overlay、包通道与 `--` 之后的内层参数", () => {
+    expect(
+      parseHostInvocation("dsh desktop", [
+        "--profile-dir",
+        "/profiles/desktop",
+        "--runtime-dir",
+        "/runtime",
+        "--patch",
+        "/host/desktop.cordis.patch.yml",
+        "--patch",
+        "/extra.yml",
+        "--pnpm",
+        "/runtime/pnpm",
+        "--node-bin",
+        "/runtime/node/bin",
+        "--",
+        "--no-open",
+      ]),
+    ).toEqual({
+      profileDir: "/profiles/desktop",
+      runtimeDir: "/runtime",
+      patches: ["/host/desktop.cordis.patch.yml", "/extra.yml"],
+      pnpmEntry: "/runtime/pnpm",
+      nodeBin: "/runtime/node/bin",
+      inner: ["--no-open"],
+    });
+  });
+
+  it("包通道与 overlay 都可省（dev 形态不传 pnpm 载荷）", () => {
+    const invocation = parseHostInvocation("dsh desktop", [
+      "--profile-dir",
+      "/app",
+      "--runtime-dir",
+      "/store",
+    ]);
+    expect(invocation.pnpmEntry).toBeUndefined();
+    expect(invocation.nodeBin).toBeUndefined();
+    expect(invocation.patches).toEqual([]);
+    expect(invocation.inner).toEqual([]);
+  });
+
+  it("缺锚点、缺值、参数不认识时都失败，且报出是哪个入口", () => {
+    expect(() => parseHostInvocation("dsh desktop", [])).toThrow(/dsh desktop: .*--profile-dir/u);
+    expect(() => parseHostInvocation("dsh desktop", ["--profile-dir", "/app"])).toThrow(
+      /--runtime-dir/u,
+    );
+    expect(() =>
+      parseHostInvocation("dsh desktop", ["--profile-dir", "/app", "--runtime-dir"]),
+    ).toThrow(/needs a value/u);
+    expect(() => parseHostInvocation("dsh web", ["--nope"])).toThrow(
+      /dsh web: unknown argument "--nope"/u,
+    );
+  });
+});

package/src/__tests__/manifest.spec.ts

@@ -0,0 +1,70 @@
+import { access, readdir, readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const PACKAGE_ROOT = dirname(
+  fileURLToPath(import.meta.resolve("@morlay/dsh-desktop-host/package.json")),
+);
+const BUILD_DIR = join(PACKAGE_ROOT, "lib");
+const BUILT = await access(join(BUILD_DIR, "index.js")).then(
+  () => true,
+  () => false,
+);
+
+interface Manifest {
+  readonly dependencies?: Record<string, string>;
+  readonly peerDependencies?: Record<string, string>;
+}
+
+// 产物里的裸 import 说明运行期依赖；相对路径与 node: 内建除外。
+async function builtImports(): Promise<Set<string>> {
+  const names = new Set<string>();
+  for (const entry of await readdir(BUILD_DIR)) {
+    if (!entry.endsWith(".js")) continue;
+    const source = await readFile(join(BUILD_DIR, entry), "utf8");
+    // 只认行首的 ESM import 语句：产物里的字符串字面量也含 "import"。
+    for (const match of source.matchAll(/^import\s+(?:[^"'`]*?\sfrom\s+)?"([^"]+)"/gmu)) {
+      const specifier = match[1] as string;
+      if (specifier.startsWith(".") || specifier.startsWith("node:")) continue;
+      const segments = specifier.split("/");
+      names.add(
+        segments[0]?.startsWith("@") === true ? `${segments[0]}/${segments[1]}` : segments[0]!,
+      );
+    }
+  }
+  return names;
+}
+
+describe("desktop host 发布清单", () => {
+  it("不声明上游 app 的组合依赖（office 组合整个不挂）", async () => {
+    const manifest = JSON.parse(
+      await readFile(join(PACKAGE_ROOT, "package.json"), "utf8"),
+    ) as Manifest;
+
+    // 变体不挂 Office 组合：docx / pptx / xlsx 技能与它那份载荷工具都由上游 app manifest 声明，抄来会让部署照装。
+    for (const name of [
+      "@deepseek-ai/dsh-skill-office",
+      "@deepseek-ai/dsh-tool-workspace-dependencies",
+      "@deepseek-ai/dsh-agent",
+      "@deepseek-ai/dsh-jobs",
+      "@deepseek-ai/dsh-tools",
+    ]) {
+      expect(manifest.dependencies?.[name]).toBeUndefined();
+    }
+  });
+
+  it.skipIf(!BUILT)("清单与产物互相覆盖：声明即用到，用到即声明", async () => {
+    const manifest = JSON.parse(
+      await readFile(join(PACKAGE_ROOT, "package.json"), "utf8"),
+    ) as Manifest;
+    const declared = new Set([
+      ...Object.keys(manifest.dependencies ?? {}),
+      ...Object.keys(manifest.peerDependencies ?? {}),
+    ]);
+    const used = await builtImports();
+
+    expect([...used].filter((name) => !declared.has(name))).toEqual([]);
+    expect([...declared].filter((name) => !used.has(name))).toEqual([]);
+  });
+});