@morlay/dsh-desktop-host 0.2.1 → 0.2.2

package/README.md

@@ -1,61 +1,15 @@
 # @morlay/dsh-desktop-host
 
-桌面部署里那个 **host 进程**：按 `desktop` profile 把 Web 应用启起来，然后**在进程内接管 `webServer`**——
-不监听任何端口，Electron 壳把该应用自己的协议（`<app name>://app/*`）的请求经字节管道（FD 3/4）喂进来。
+桌面部署里那个 **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` 入口路径照旧，两处本地差别——Office 组合不再挂
-`@deepseek-ai/dsh-skill-office`（见 [`src/office.ts`](./src/office.ts)），载波从「监听端口 + 壳认证反向代理」
-换成「宿主内 webServer 替身 + 管道」（见 [`src/webserver.ts`](./src/webserver.ts) 与桌面层的
-[设计 桌面无端口传输与窗口对齐](../dsh-desktopify/.agents/designs/20260920-桌面无端口传输与窗口对齐.md)）。
+上游 `apps/desktop-host`（`@deepseek-ai/dsh-desktop-host`）是 `private: true` 的应用，外部装不到，所以这里是它的**变体包**：argv / IPC 契约、`lib/index.js` 入口路径照旧。
 
 ## 用法
 
 被 [`@morlay/dsh-desktopify`](../dsh-desktopify/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`（入口按 `../config/desktop.cordis.patch.yml` 作为 `patchFiles` 读），
-  缺任一样 host 都起不来；
-- 壳按 `<runtime>/node_modules/@morlay/dsh-desktop-host/lib/index.js` 启动它（stdio 五元组：
-  FD 3/4 是管道，FD 5 是 Node IPC），argv 为
-  `[runtimeDir, projectDir, primaryRuntime, pnpmEntry, nodeBin]`（上游 0.1.7 删掉 `runProfile` 的 `resolutionMode` 后少一格）；
-- IPC：`ready { protocolVersion }` / `fatal { message, diagnostic }`（`diagnostic` 是完整 `util.inspect` 的错误，
-  与上游 0.1.7-alpha.2 同形；壳的 dialog 用 `message`，完整诊断走 stderr），另外收 `shutdown`。
+- `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, primaryRuntime, pnpmEntry?, nodeBin?]`；
+- IPC：`ready { protocolVersion }` / `fatal { message, diagnostic }`，另外收 `shutdown`。
 
-出口：`.`（启动入口）、`./webserver`（无端口 `webServer` 服务，供 patch 行加载）、`./wire`
-（管道分帧，壳构建时内联，部署里不需要单独解析它）。
-
-## 运行时做的事
-
-1. `runProfile` 装配 `desktop` profile（保住 profileContext / proxy / fail-loud / appReady / shutdown 语义）；
-2. 桌面 patch 禁用上游 `webserver` 行，插入本包的 `webServer` 替身——同一份路由面
-   （`register` / `registerFallback` / `registerUpgrade` / `tapIndex` / `renderIndex` / `collectIndexInjections` /
-   `port` / `host`），请求由 `dispatch(Request)` 从管道喂进来；
-3. 接管浏览器认证：页面由壳独占、没有网络入口，`connection` 的 `requestRejection` 与 `authorizeIndex`
-   被改写为放行（理由与代价见[债务 桌面宿主覆写 connection 认证方法](../dsh-desktopify/.agents/debts/20260920-桌面宿主覆写connection认证方法.md)）；
-4. 注入客户端 transport（`__DSH_TRANSPORT__ = { ownsHost, openStream }`）并注册 `/.dsh/remote-stream`
-   （双向 NDJSON：请求体首行定 endpoint/payload、后续行是上行项，响应体是下行帧 →
-   `typertGateway.wireStream.open`）；
-5. 桌面 patch 还按 id 停掉整条**账号/登录面**（`deepseek-account`、`account-controller`、
-   `llm-deepseek-account`、`ui-settings-account`）：登录要的回环地址回调在无端口下没有入口，
-   装着只会撞死路——理由与代价见 [ADR 桌面档不含登录与账号面](./.agents/adrs/20260928-桌面档不含登录与账号面.md)。
-   模型路径不受影响（`credentials` + `llm-pi-ai` 的 `ollama` 路由），探针
-   [`tool/verify-desktop-account-plane.mts`](./tool/verify-desktop-account-plane.mts) 判这两件事。
-
-## 依赖边界
-
-`@deepseek-ai/*` 全部由**部署自己的** `node_modules` 提供（与上游同边界）：
-
-- `dependencies`：本包入口与替身真正 import 的 `@deepseek-ai/dsh`（含 `./profile-boot` 子路径）、
-  `@deepseek-ai/dsh-app-boot`、`@deepseek-ai/dsh-home-paths`、`@deepseek-ai/dsh-host-webserver`
-  （`renderIndexInjections`）、`@deepseek-ai/schemastery`（替身的 Config schema）；
-- `peerDependencies`：`@deepseek-ai/cordis`；
-- 类型面 `@deepseek-ai/dsh-client-connection` / `@deepseek-ai/dsh-api-gateway` 只在 devDependencies
-  （空 import 带 Context merge，构建后即被擦除）；
-- vendor 里的 `workspace-dependencies` 模块在构建期内联，运行期不依赖 vendor 路径。
-
-清单只声明**这份代码真正用到**的包：上游那份 app manifest 里的组合依赖
-（`@deepseek-ai/dsh-skill-office`、`dsh-agent`、`dsh-jobs`、`dsh-tools` …）属于部署的官方闭包，
-由 `@morlay/dsh-desktopify` 的部署步骤按 profile 提供，不该由本包声明。
+运行时做的事（profile 装配、`webServer` 替身、认证接管、客户端 transport 与账号面）、出口面与依赖边界见[设计 桌面host的运行时面与依赖边界](./.agents/designs/20260929-桌面host的运行时面与依赖边界.md)；载波形态的取舍见[设计 桌面无端口传输与窗口对齐](../dsh-desktopify/.agents/designs/20260920-桌面无端口传输与窗口对齐.md)。

package/lib/index.js

@@ -25,19 +25,12 @@ var office_exports = /* @__PURE__ */ __exportAll({
 	apply: () => apply,
 	name: () => name
 });
-/** Loader identity for the application-owned workspace dependency composition. */
 const name = "desktop-office";
-/**
-* Enable the bundled authoring dependencies in the Desktop profile.
-* @param ctx - Profile scope; child plugins declare their own service requirements.
-* @param config - Bundled payload source and Harness-home installation root.
-*/
 async function apply(ctx, config) {
 	await ctx.plugin(workspaceDependencies, config);
 }
 //#endregion
 //#region src/transport.ts
-/** 注入 index 的 transport 行：声明页面拥有 Host，并给出 Gateway 流载体（下行流 + 上行项）。 */
 const DESKTOP_TRANSPORT_SCRIPT = `globalThis.__DSH_TRANSPORT__={
   _desktop:true,
   ownsHost:true,
@@ -73,9 +66,8 @@ const DESKTOP_TRANSPORT_SCRIPT = `globalThis.__DSH_TRANSPORT__={
       },
       fail(message){failure=new Error(message);ended=true;notify()},
     })
-    // 取消必须结束迭代：abort 只解除 IPC 监听，挂在这一句等待上的消费方再也收不到
-    // end 帧；不叫醒它就等于 dispose（RemoteStream 会 await iterator.return）永不落定——
-    // 撤回 / 重试后的窗口重建正是卡在这里，页面既收不到新窗口也没有报错。
+    // 取消必须结束迭代：不叫醒它，等在这一句上的消费方收不到 end 帧，dispose（await iterator.return）
+    // 也永不落定——窗口重建会卡在这里。
     const onAbort=()=>{stream.cancel();ended=true;notify()}
     signal.addEventListener('abort',onAbort,{once:true})
     if(signal.aborted)onAbort()
@@ -108,12 +100,6 @@ const DESKTOP_TRANSPORT_SCRIPT = `globalThis.__DSH_TRANSPORT__={
   }
 }
 console.info('[dsh-desktop] transport installed',Object.keys(globalThis.__DSH_TRANSPORT__))`;
-/**
-* 桌面形态下放行 `connection` 的两处浏览器认证：`requestRejection`（`/api` 路由与
-* 各插件 handler 的自查）与 `authorizeIndex`（`frontend-static` 的 index 渲染）。
-*
-* 页面由壳独占、没有网络入口，认证没有对象；这里直接改写服务实例的方法。
-*/
 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");
@@ -124,13 +110,11 @@ function takeOverDesktopAuthentication(ctx) {
 function isRecord(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-/** 桌面流请求体：首行是 open（endpoint / payload），后续每行是一道上行项。 */
 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;
 }
-/** 校验首行：它决定这条流开在哪个 endpoint 上。 */
 function parseStreamOpening(value, subject) {
 	if (!isRecord(value) || typeof value.endpoint !== "string") throw new Error(`dsh desktop: invalid stream request ${subject}`);
 	return {
@@ -198,7 +182,6 @@ function streamHandler(ctx) {
 		}
 	};
 }
-/** 注入 transport 行并注册 Gateway 流路由；随插件 fiber 一起撤销。 */
 function installDesktopTransport(ctx) {
 	ctx.on("webserver/index-inject", (table) => {
 		table.push({
@@ -215,24 +198,11 @@ function installDesktopTransport(ctx) {
 }
 //#endregion
 //#region src/index.ts
-/**
-* 桌面部署里的 host 进程入口：按 `desktop` profile 装配 Web 应用，并把请求经字节管道
-* （FD 3/4）交给宿主内的无端口 `webServer`。
-*
-* argv：`[runtimeDir, projectDir, primaryRuntime, pnpmEntry?, nodeBin?]`；
-* IPC：`ready` / `fatal`，另收 `shutdown`。
-*/
 const DESKTOP_PATCH = fileURLToPath(new URL("../config/desktop.cordis.patch.yml", import.meta.url));
 function errorMessage(error) {
 	return error instanceof Error ? error.message : String(error);
 }
-/** 诊断上限：壳把它写进日志，再长也没有额外价值。 */
 const MAX_FATAL_DIAGNOSTIC_CHARS = 65536;
-/**
-* fatal 事件：`message` 给壳的 dialog 用，`diagnostic` 是完整 `inspect`（`code` / `syscall` /
-* `path` / `cause` 链，stack 行里没有）——stderr 字节与这条 IPC 谁先到不确定，壳报告的是它
-* 先看到的那一条，所以诊断得跟 IPC 一起走。
-*/
 function fatalEvent(error) {
 	return {
 		type: "fatal",

package/lib/webserver.js

@@ -4,14 +4,6 @@ import { Service } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
 import { renderIndexInjections } from "@deepseek-ai/dsh-host-webserver";
 //#region src/webserver.ts
-/**
-* 桌面形态的 `webServer` 服务：与上游同名的路由载体，但不监听任何端口。
-*
-* 上游 `@deepseek-ai/dsh-host-webserver` 在激活时 `listen`。桌面宿主自己拥有页面，
-* 没有网络入口，于是这里保留同一份服务面（register / registerFallback / registerUpgrade /
-* tapIndex / renderIndex / collectIndexInjections / port / host），把请求由 `dispatch`
-* 从字节管道直接喂进来。
-*/
 function deferred() {
 	let resolve;
 	return {
@@ -21,14 +13,12 @@ function deferred() {
 		resolve
 	};
 }
-/** 由 handler 写出的 node 风格响应：写出头部即对外可见，`end` 收尾响应体流。 */
 var SyntheticResponse = class extends EventEmitter {
 	statusCode = 200;
 	statusMessage = "";
 	headersSent = false;
 	writableEnded = false;
 	destroyed = false;
-	/** 上游中间件按 `res.socket === undefined` 识别「没有真实连接」。 */
 	socket = void 0;
 	body;
 	started;
@@ -102,7 +92,6 @@ var SyntheticResponse = class extends EventEmitter {
 		this.emit("close");
 		return this;
 	}
-	/** handler 抛错：未写头时以 500 收场，已写头则中断响应体。 */
 	fail(error) {
 		if (this.destroyed) return;
 		if (!this.headersSent) {
@@ -133,7 +122,6 @@ function toBytes(chunk) {
 function errorMessage(error) {
 	return error instanceof Error ? error.message : String(error);
 }
-/** 把一条 Fetch 请求合成 node 风格的 req/res，供注册在这些表上的 handler 使用。 */
 function createRequest(request, url) {
 	const stream = Readable.from(request.body === null ? [] : consume(request.body));
 	const headers = {};
@@ -176,7 +164,6 @@ var PortlessWebServer = class extends Service {
 		super(ctx, "webServer");
 		this.config = config;
 	}
-	/** 没有真实监听：报配置值（缺省 0），只用于拼展示用 URL。 */
 	get port() {
 		return this.config.port ?? 0;
 	}
@@ -225,7 +212,6 @@ var PortlessWebServer = class extends Service {
 	renderIndex(html) {
 		return this.applyIndexTaps(renderIndexInjections(html, this.collectIndexInjections()));
 	}
-	/** 把一条管道请求分派给注册表；没有匹配也没有 fallback 时回 404。 */
 	async dispatch(request) {
 		const url = new URL(request.url);
 		let pathname;

package/lib/wire.js

@@ -1,35 +1,19 @@
 import { StringDecoder } from "node:string_decoder";
 //#region src/wire.ts
-/**
-* 桌面 host 与 Electron 壳之间的字节管道协议：请求帧（壳 → host，FD 3）与响应帧（host → 壳，FD 4）。
-*
-* 帧头 13 字节：magic(4) | type(1) | streamId(4) | payloadLength(4)。data 帧是原始字节，
-* 其余帧是 JSON 或空载荷。两侧共用这一份实现，避免编解码各写一遍。
-*/
 const DESKTOP_HOST_PROTOCOL_VERSION = 1;
-/** 桌面流的宿主路径：页面/主进程都用它（两侧共享一份，避免路径写两处）。 */
 const DESKTOP_STREAM_PATH = "/.dsh/remote-stream";
-/**
-* 桌面流请求体的首行：定下这条逻辑流的 endpoint 与 payload，后续行都是上行项
-* （客户端 → 宿主；`$events` 这类宿主自己的流被上游释放，不会读到它们）。
-*/
 function encodeDesktopStreamOpen(endpoint, payload) {
 	return `${JSON.stringify({
 		endpoint,
 		payload
 	})}\n`;
 }
-/** 桌面流请求体里的一道上行项。 */
 function encodeDesktopStreamItem(item) {
 	return `${JSON.stringify(item)}\n`;
 }
-/** 壳写请求帧的管道描述符。 */
 const DESKTOP_REQUEST_PIPE_FD = 3;
-/** host 写响应帧的管道描述符。 */
 const DESKTOP_RESPONSE_PIPE_FD = 4;
-/** Node 生命周期 IPC 通道的描述符（ready / fatal / shutdown）。 */
 const DESKTOP_CONTROL_IPC_FD = 5;
-/** 单个 data 帧携带的最大原始字节数。 */
 const DESKTOP_PIPE_CHUNK_BYTES = 65536;
 const FRAME_MAGIC = 1146308659;
 const FRAME_HEADER_BYTES = 13;
@@ -66,35 +50,27 @@ function encodeFrame(type, streamId, payload, dataType, direction) {
 function jsonPayload(type, streamId, value, dataType, direction) {
 	return encodeFrame(type, streamId, Buffer.from(JSON.stringify(value), "utf8"), dataType, direction);
 }
-/** 编码开启一个请求流的元数据帧（壳侧）。 */
 function encodeDesktopRequestStart(streamId, request) {
 	return jsonPayload(REQUEST_FRAME_START, streamId, request, REQUEST_FRAME_DATA, "request");
 }
-/** 编码一个受限的请求体原始分片（壳侧）。 */
 function encodeDesktopRequestData(streamId, data) {
 	return encodeFrame(REQUEST_FRAME_DATA, streamId, Buffer.from(data), REQUEST_FRAME_DATA, "request");
 }
-/** 编码请求体正常结束（壳侧）。 */
 function encodeDesktopRequestEnd(streamId) {
 	return encodeFrame(REQUEST_FRAME_END, streamId, Buffer.alloc(0), REQUEST_FRAME_DATA, "request");
 }
-/** 编码取消一个请求及其响应（壳侧）。 */
 function encodeDesktopRequestCancel(streamId) {
 	return encodeFrame(REQUEST_FRAME_CANCEL, streamId, Buffer.alloc(0), REQUEST_FRAME_DATA, "request");
 }
-/** 编码响应元数据帧（host 侧）。 */
 function encodeDesktopResponseStart(streamId, response) {
 	return jsonPayload(RESPONSE_FRAME_START, streamId, response, RESPONSE_FRAME_DATA, "response");
 }
-/** 编码一个受限的响应体原始分片（host 侧）。 */
 function encodeDesktopResponseData(streamId, data) {
 	return encodeFrame(RESPONSE_FRAME_DATA, streamId, Buffer.from(data), RESPONSE_FRAME_DATA, "response");
 }
-/** 编码响应正常结束（host 侧）。 */
 function encodeDesktopResponseEnd(streamId) {
 	return encodeFrame(RESPONSE_FRAME_END, streamId, Buffer.alloc(0), RESPONSE_FRAME_DATA, "response");
 }
-/** 编码一次响应失败，不把 Error 对象跨进程传递（host 侧）。 */
 function encodeDesktopResponseError(streamId, message) {
 	return jsonPayload(RESPONSE_FRAME_ERROR, streamId, { message }, RESPONSE_FRAME_DATA, "response");
 }
@@ -120,19 +96,13 @@ function parseJson(payload, subject) {
 function assertEmpty(payload, subject) {
 	if (payload.byteLength !== 0) throw new Error(`dsh desktop: ${subject} frame carried a payload`);
 }
-/**
-* 增量解码桌面流请求体：按行取 JSON，首行是 `open`（endpoint / payload），后续每行是一道上行项。
-* 字节边界可能切开多字节字符，所以先过 `StringDecoder` 再切行。
-*/
 var DesktopStreamBodyDecoder = class {
 	text = new StringDecoder("utf8");
 	buffer = "";
-	/** 追加字节并返回所有已完整的行的解析值（空行忽略）。 */
 	push(chunk) {
 		this.buffer += this.text.write(Buffer.from(chunk));
 		return this.take(false);
 	}
-	/** 请求体结束：交付末行（没有换行收尾时也存在）。 */
 	finish() {
 		this.buffer += this.text.end();
 		return this.take(true);
@@ -161,10 +131,8 @@ function parseStreamLine(line) {
 		throw new Error(`dsh desktop: stream body line is not JSON: ${error instanceof Error ? error.message : String(error)}`);
 	}
 }
-/** 增量解码 host 侧从请求管道收到的请求帧。 */
 var DesktopHostRequestDecoder = class {
 	buffer = Buffer.alloc(0);
-	/** 追加字节并返回所有已完整的请求帧。 */
 	push(chunk) {
 		this.buffer = this.buffer.byteLength === 0 ? chunk : Buffer.concat([this.buffer, chunk]);
 		const frames = [];
@@ -174,7 +142,6 @@ var DesktopHostRequestDecoder = class {
 			frames.push(frame);
 		}
 	}
-	/** EOF 落在帧中间时报错。 */
 	finish() {
 		if (this.buffer.byteLength !== 0) throw new Error("dsh desktop: request pipe ended inside a frame");
 	}
@@ -222,10 +189,8 @@ var DesktopHostRequestDecoder = class {
 		};
 	}
 };
-/** 增量解码壳侧从响应管道收到的响应帧。 */
 var DesktopHostResponseDecoder = class {
 	buffer = Buffer.alloc(0);
-	/** 追加字节并返回所有已完整的响应帧。 */
 	push(chunk) {
 		this.buffer = this.buffer.byteLength === 0 ? chunk : Buffer.concat([this.buffer, chunk]);
 		const frames = [];
@@ -235,7 +200,6 @@ var DesktopHostResponseDecoder = class {
 			frames.push(frame);
 		}
 	}
-	/** EOF 落在帧中间时报错。 */
 	finish() {
 		if (this.buffer.byteLength !== 0) throw new Error("dsh desktop: response pipe ended inside a frame");
 	}
@@ -286,14 +250,12 @@ var DesktopHostResponseDecoder = class {
 		return { message: value.message };
 	}
 };
-/** IPC 事件校验（壳侧）。 */
 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");
 	return false;
 }
-/** IPC 命令校验（host 侧）。 */
 function isDesktopHostCommand(value) {
 	return isRecord(value) && value.type === "shutdown";
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morlay/dsh-desktop-host",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "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 skill mount removed.",
   "keywords": [
     "desktop",