@dsh-workbench/core 1.1.12 → 1.1.14-beta.0

package/dist/host/index.js

@@ -1,7 +1,7 @@
-import path, { basename, dirname, join, relative, resolve, sep } from "node:path";
+import path, { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import dayjs from "dayjs";
 import fs, { accessSync, constants, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
-import "node:os";
+import { homedir } from "node:os";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import utc from "dayjs/plugin/utc.js";
 import { createHash, randomUUID } from "node:crypto";
@@ -406,16 +406,22 @@ var DAY = 864e5;
 365 * DAY;
 //#endregion
 //#region ../shared/dist/lib/board-fact.js
+function normalizePath(value) {
+	const forward = value.replace(/\\/g, "/").replace(/\/+$/g, "");
+	return /^[A-Za-z]:\//.test(forward) || forward.startsWith("//") ? forward.toLowerCase() : forward;
+}
 /**
 * 判一个路径落不落在这个工作区里（按路径前缀比，不是字符串包含）。
 * @param root - 工作区根路径。
 * @param target - 要判的路径。
-* @returns 同一个路径或在其下给 `true`；`root` 末尾带不带斜杠都认（`/a` 不匹配 `/ab`）。
+* @returns 同一个路径或在其下给 `true`；分隔符先归一（Windows 的 `\` 与 `/` 都认），
+*   盘符路径按大小写不敏感比；`root` 末尾带不带斜杠都认（`/a` 不匹配 `/ab`）。
 */
 function insideWorkshop(root, target) {
-	if (target === root) return true;
-	const base = root.endsWith("/") ? root : `${root}/`;
-	return target.startsWith(base);
+	const base = normalizePath(root);
+	const real = normalizePath(target);
+	if (real === base) return true;
+	return real.startsWith(base === "" ? "/" : `${base}/`);
 }
 /**
 * 把探针读数归成左栏那句人话的档位。
@@ -596,9 +602,9 @@ function stringArrayProblems(at, value) {
 function declarationProblemsOf(subject, raw) {
 	if (!isRecord(raw)) return [`${subject}: dsh.workbench 不是一个对象 —— ${JSON.stringify(raw)}`];
 	const version = raw.apiVersion;
-	if (version === void 0) return [`${subject}: dsh.workbench 没有 apiVersion —— 协议从 v3 起，写 \`"apiVersion": 3\`。缺它 = 外壳不认这个模块`];
+	if (version === void 0) return [`${subject}: dsh.workbench 没有 apiVersion —— 协议从 v3 起，写 \`"apiVersion": 3\`。缺它 = 外壳不认这个模块（\`dsh-wb-module migrate\` 能自动补这一项）`];
 	if (!Number.isInteger(version) || !SUPPORTED_API_VERSIONS.includes(version)) {
-		const hint = version === 2 ? " —— v3 把卡片标题挪成了顶层 `title`（`{ \"zh\": \"…\", \"en\": \"…\" }` 字面量）：把 `card.titleKey` 删掉、在顶层写 title，再把 apiVersion 改成 3" : "";
+		const hint = version === 2 ? " —— v3 把卡片标题挪成了顶层 `title`（`{ \"zh\": \"…\", \"en\": \"…\" }` 字面量）：把 `card.titleKey` 删掉、在顶层写 title，再把 apiVersion 改成 3" : " —— 先跑 `dsh-wb-module migrate` 把版本号改到 3，再按 check 的提示改源码";
 		return [`${subject}: dsh.workbench.apiVersion 是 ${JSON.stringify(version)}，这里只认 ${SUPPORTED_API_VERSIONS.join(" / ")}（要整数）${hint}`];
 	}
 	const problems = [];
@@ -843,37 +849,72 @@ function refusalReason() {
 //#endregion
 //#region ../shared/dist/host/shell.js
 var DEFAULT_MAX_BYTES$3 = 8388608;
+var GUARD_SLACK_MS = 1e3;
+function stalledResult() {
+	return {
+		exitCode: null,
+		timedOut: true,
+		aborted: false,
+		stdout: "",
+		stderr: "",
+		truncated: false,
+		stalled: true
+	};
+}
+async function settleWithin(work, limitMs) {
+	let timer;
+	const guard = new Promise((resolve) => {
+		timer = setTimeout(() => resolve(null), limitMs);
+	});
+	try {
+		return await Promise.race([work, guard]);
+	} finally {
+		if (timer !== void 0) clearTimeout(timer);
+	}
+}
 async function runShell(shell, command, options = {}) {
-	const { workdir, timeoutMs = GIT_TIMEOUT_MS, signal } = options;
+	const { workdir, timeoutMs = GIT_TIMEOUT_MS, signal, env } = options;
 	const spec = shell.resolve({
 		command,
 		...workdir === void 0 ? {} : { workdir },
 		timeoutMs,
 		onExpiry: "kill",
 		stdoutMaxBytes: DEFAULT_MAX_BYTES$3,
-		...signal === void 0 ? {} : { signal }
+		...signal === void 0 ? {} : { signal },
+		...env === void 0 ? {} : { env }
 	});
-	const result = await (await shell.execute(spec)).result();
-	return {
-		exitCode: result.exitCode,
-		timedOut: result.timedOut === true,
-		aborted: result.aborted === true,
-		stdout: result.stdout.text,
-		stderr: result.stderr.text,
-		truncated: result.stdout.truncated || result.stderr.truncated
-	};
+	return await settleWithin((async () => {
+		const result = await (await shell.execute(spec)).result();
+		return {
+			exitCode: result.exitCode,
+			timedOut: result.timedOut === true,
+			aborted: result.aborted === true,
+			stdout: result.stdout.text,
+			stderr: result.stderr.text,
+			truncated: result.stdout.truncated || result.stderr.truncated,
+			stalled: false
+		};
+	})(), timeoutMs + GUARD_SLACK_MS) ?? stalledResult();
 }
 //#endregion
 //#region ../shared/dist/host/shell-text.js
 /**
-* 按目标平台把一个值裹成 shell 字面量：POSIX 用单引号，win32 用双引号（cmd 与 PowerShell 都认）。
+* 按目标平台判 shell 种类：win32 是 pwsh（dsh 的 Windows 执行器就是 PowerShell），其余是 POSIX。
+* @param platform - 目标平台，默认当前 `process.platform`。
+* @returns `'pwsh'` 或 `'posix'`。
+*/
+function shellKindOf(platform = process.platform) {
+	return platform === "win32" ? "pwsh" : "posix";
+}
+/**
+* 按目标平台把一个值裹成 shell 字面量：POSIX 用单引号并按 `'\''` 逃逸，pwsh 也用单引号但按 `''` 逃逸。
 * @param value - 任意值；不是字符串的先 `String()`。
 * @param platform - 目标平台，默认当前 `process.platform`。
 * @returns 可安全拼进该平台 shell 命令的一段文本；含空格 / 元字符的值不会被当成语法。
 */
 function quoteShellArgFor(value, platform = process.platform) {
 	const text = String(value);
-	if (platform === "win32") return `"${text.replace(/"/g, "\\\"")}"`;
+	if (shellKindOf(platform) === "pwsh") return `'${text.replace(/'/g, "''")}'`;
 	return `'${text.replace(/'/g, `'\\''`)}'`;
 }
 /**
@@ -4330,14 +4371,17 @@ function sessionIdOf(exec) {
 //#region ../shared/dist/host/host-kit.js
 /**
 * 建一份宿主 kit；每个挂载点一份，没有模块级状态。
-* @returns flow / sessionIdOf / sessionWorkspace / libInstallCommand。
+* @param parts.libInstallCommand 拼「装这个共用依赖」的那条命令。
+* @param parts.surface 宿主平台事实；由组合根按 profile 与宿主进程算好再交进来。
+* @returns flow / sessionIdOf / sessionWorkspace / libInstallCommand / surface。
 */
 function createHostKit(parts) {
 	return {
 		flow: createFlowHost(),
 		sessionIdOf,
 		sessionWorkspace,
-		libInstallCommand: parts.libInstallCommand
+		libInstallCommand: parts.libInstallCommand,
+		surface: parts.surface
 	};
 }
 //#endregion
@@ -4727,15 +4771,15 @@ function createValueHandoff(options = {}) {
 function dshHome() {
 	const configured = process.env.DSH_HOME?.trim();
 	if (configured !== void 0 && configured !== "") return configured;
-	return `${process.env.HOME ?? ""}/.dsh`;
+	return join(homedir(), ".dsh");
 }
 function workbenchRoot() {
 	const configured = process.env.DSH_WORKBENCH_HOME?.trim();
 	if (configured !== void 0 && configured !== "") return configured;
-	return `${dshHome()}/workbench`;
+	return join(dshHome(), "workbench");
 }
 function workspacesRoot() {
-	return `${workbenchRoot()}/workspaces`;
+	return join(workbenchRoot(), "workspaces");
 }
 //#endregion
 //#region ../shared/dist/host/workspace-store.js
@@ -4747,11 +4791,15 @@ function workspaceKey(workspace) {
 	const abs = path.resolve(workspace);
 	return `${slug(path.basename(abs))}-${createHash("sha1").update(abs).digest("hex").slice(0, 8)}`;
 }
-function inside(dir, name) {
+function safeName(name) {
 	const trimmed = name.trim();
 	if (trimmed === "" || trimmed === "." || trimmed === "..") throw new Error(`模块文件夹里只接受相对文件名，收到的是「${name}」`);
-	if (trimmed.includes("\0") || path.isAbsolute(trimmed)) throw new Error(`模块只能写自己的文件夹：不接受绝对路径「${name}」`);
-	const full = path.resolve(dir, trimmed);
+	if (trimmed.includes("\0") || path.isAbsolute(trimmed) || /^[A-Za-z]:[\\/]/.test(trimmed)) throw new Error(`模块只能写自己的文件夹：不接受绝对路径「${name}」`);
+	if (trimmed.replace(/\\/g, "/").split("/").includes("..")) throw new Error(`模块只能写自己的文件夹：路径越界「${name}」`);
+	return trimmed;
+}
+function inside(dir, name) {
+	const full = path.resolve(dir, safeName(name));
 	if (full !== dir && !full.startsWith(dir + path.sep)) throw new Error(`模块只能写自己的文件夹：路径越界「${name}」`);
 	return full;
 }
@@ -4760,15 +4808,15 @@ function memoryStore(dir) {
 	return {
 		dir,
 		read: (name) => {
-			inside(dir, name);
+			safeName(name);
 			return files.get(name) ?? null;
 		},
 		write: (name, value) => {
-			inside(dir, name);
+			safeName(name);
 			files.set(name, value);
 		},
 		remove: (name) => {
-			inside(dir, name);
+			safeName(name);
 			files.delete(name);
 		},
 		list: () => [...files.keys()].sort()
@@ -4849,7 +4897,7 @@ var TARGET_FLAGS = [
 	"--dir",
 	"--store-dir"
 ];
-var INSTALL_VERBS = /^\s*npm\s+(i|install|add)\b/;
+var INSTALL_VERBS = /^\s*(?:npm\s+(?:i|install|add)|pnpm\s+(?:add|install))\b/;
 var NPM_PATH = /^npm (?:error|ERR!) path (.+)$/m;
 function commandTokens(command) {
 	const tokens = [];
@@ -6779,14 +6827,31 @@ function bundleInspectHandler(ctx) {
 }
 //#endregion
 //#region src/shared/api/host/git-exec.ts
-var GIT_NO_PROMPT_ENV = {
-	GIT_TERMINAL_PROMPT: "0",
-	GIT_ASKPASS: "/usr/bin/false",
-	SSH_ASKPASS: "/usr/bin/false",
-	SSH_ASKPASS_REQUIRE: "never",
-	GCM_INTERACTIVE: "never",
-	GIT_SSH_COMMAND: "ssh -o BatchMode=yes -o StrictHostKeyChecking=accept-new"
-};
+function gitNoPromptEnv(platform = process.platform) {
+	const shared = {
+		GIT_TERMINAL_PROMPT: "0",
+		SSH_ASKPASS_REQUIRE: "never",
+		GCM_INTERACTIVE: "never",
+		GIT_SSH_COMMAND: "ssh -o BatchMode=yes -o StrictHostKeyChecking=accept-new"
+	};
+	if (platform === "win32") return shared;
+	return {
+		...shared,
+		GIT_ASKPASS: "/usr/bin/false",
+		SSH_ASKPASS: "/usr/bin/false"
+	};
+}
+function gitNoPromptProcessEnv(parent = process.env, platform = process.platform) {
+	const env = {
+		...parent,
+		...gitNoPromptEnv(platform)
+	};
+	if (platform === "win32") {
+		delete env.GIT_ASKPASS;
+		delete env.SSH_ASKPASS;
+	}
+	return env;
+}
 function withoutAskpassNoise(text) {
 	return text.split("\n").filter((line) => !/unable to read askpass response/i.test(line)).join("\n").trim();
 }
@@ -6796,10 +6861,7 @@ var DEFAULT_MAX_BYTES$2 = 8388608;
 var runGitProcess = async (args, options = {}) => {
 	const result = await execa("git", [...args], {
 		...options.cwd === void 0 ? {} : { cwd: options.cwd },
-		env: {
-			...process.env,
-			...GIT_NO_PROMPT_ENV
-		},
+		env: gitNoPromptProcessEnv(),
 		stdin: "ignore",
 		reject: false,
 		...options.timeoutMs === void 0 ? {} : { timeout: options.timeoutMs },
@@ -8363,7 +8425,10 @@ function asText$1(value) {
 	return typeof value === "string" ? value.trim() : "";
 }
 function insideRoot(root, target) {
-	return insideWorkshop(existsSync(root) ? realpathSync(root) : resolve(root), existsSync(target) ? realpathSync(target) : resolve(target));
+	const base = existsSync(root) ? realpathSync(root) : resolve(root);
+	const real = existsSync(target) ? realpathSync(target) : resolve(target);
+	const rel = relative(base, real);
+	return rel === "" || rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
 }
 function manifestAt(dir) {
 	try {
@@ -13115,7 +13180,7 @@ function sourceProblemText(problem, env) {
 //#region src/modules/panels/model/plugin-name.ts
 function pluginDirOf(entry, files) {
 	if (entry.local === true || files?.dir === void 0) return entry.package;
-	return `${files.dir}/${entry.package}`;
+	return join(files.dir, entry.package);
 }
 function pluginOnDisk(entry, files) {
 	return pluginAt(pluginDirOf(entry, files), files?.manifest ?? "") !== void 0;
@@ -17337,7 +17402,10 @@ function mountUnits(units, deps) {
 			message: "没有注入 DataReader：模块只能走 deps.data 读数据"
 		}
 	});
-	const hostKit = createHostKit({ libInstallCommand: (options) => adaptersOf(deps.ctx).supply.libInstallCommand(options) });
+	const hostKit = createHostKit({
+		libInstallCommand: (options) => adaptersOf(deps.ctx).supply.libInstallCommand(options),
+		surface: deps.surface ?? hostSurface()
+	});
 	const data = deps.data ?? {
 		read: missingData,
 		request: missingData,
@@ -18269,10 +18337,13 @@ async function apply(ctx, config) {
 	const capabilities = adapters.runtime.capabilities(ctx);
 	const runtimeProfile = adapters.runtime.profile?.(ctx) ?? null;
 	const runtimeCheck = adapters.runtime.check;
+	const profileDir = adapters.profile.dirOf(ctx);
+	const surface = hostSurface({ profile: profileDir ?? void 0 });
 	routes.health = async (search) => ({
 		...await baseHealth?.(search),
 		capabilities,
 		runtimeProfile,
+		surface,
 		adapterSet: {
 			configured: adapterSpec,
 			active: adapters.id,
@@ -18286,7 +18357,6 @@ async function apply(ctx, config) {
 		}
 	});
 	const renderers = /* @__PURE__ */ new Map();
-	const profileDir = adapters.profile.dirOf(ctx);
 	const packageRoot = adapters.runtime.packageRoot(import.meta.url);
 	const reconcileProfile = async () => {
 		const hmr = ctx.get("hmr");
@@ -18439,6 +18509,7 @@ async function apply(ctx, config) {
 				commands: adapters.commands,
 				probe: (unit, options) => probeOne(unit, options?.force ?? false),
 				values,
+				surface,
 				longTasks: {
 					scope: process.env["DSH_HOME"] ?? "",
 					bump: (names) => facts.bump([...names, LONG_TASKS_ROUTE]),

package/dist/types/app/client.d.ts

@@ -9,10 +9,12 @@ import * as longTaskModule from '../shared/hooks/use-long-task';
 import * as capabilityGateModule from '../shared/hooks/use-capability-gate';
 import * as unitBoardModule from '../shared/hooks/use-unit-board';
 import * as visibleBusyModule from '../shared/hooks/use-visible-busy';
+import { usePlatform } from '../shared/hooks/use-platform';
 import * as blockerStateModule from '../shared/components/BlockerState';
-import { ActivityAction, ActivityBlock, ActivityLine, ApprovalDetail, ApprovalPlan, Card, CardAnchor, CardBoundary, CardHead, CenteredState, ChoiceGroup, ConfirmBar, EmptyState, Field, Form, FormActions, FormRow, FormRows, IconBrandMark, IconConversation, IconModuleMark, IconNpm, IconOpencli, IconPanelScreen, Link, LongTaskRow, longTaskIsLive, Note, Row, Rows, SaveBar, SelectField, SettingsSection, SkeletonRows, Spinner, Stack, StateBlock, TextField, apiGet, apiPost, blockerOfCapability, blockerOfError, cardIdOf, cx, defaultSelectFilter, duplicateKeysOf, errorReasonOf, excerpt, factOfRoute, filterSelectOptions, firstProblemOf, formFirstProblemOf, formValuesOf, holdBusy, parseJsonLoose, parseLocalTimestamp, readText, relativeTime, relativeTimeAgo, relativeTimeBucket, relativeTimeCompact, revealFirstProblem, searchTextOf, selectCursorValue, selectEntries, shortenPath, stepSelectCursor, writeText } from '@dsh-workbench/shared';
+import { ActivityAction, ActivityBlock, ActivityLine, ApprovalDetail, ApprovalPlan, Card, CardAnchor, CardBoundary, CardHead, CenteredState, ChoiceGroup, ConfirmBar, EmptyState, Field, Form, FormActions, FormRow, FormRows, IconBrandMark, IconConversation, IconModuleMark, IconNpm, IconOpencli, IconPanelScreen, Link, LongTaskRow, longTaskIsLive, Note, Row, Rows, SaveBar, SelectField, SettingsSection, SkeletonRows, Spinner, Stack, StateBlock, TextField, apiGet, apiPost, blockerOfCapability, blockerOfError, cardIdOf, cx, defaultSelectFilter, duplicateKeysOf, errorReasonOf, excerpt, factOfRoute, filterSelectOptions, firstProblemOf, formFirstProblemOf, formValuesOf, holdBusy, parseJsonLoose, parseLocalTimestamp, pathBase, readText, relativeTime, relativeTimeAgo, relativeTimeBucket, relativeTimeCompact, revealFirstProblem, searchTextOf, selectCursorValue, selectEntries, shortenPath, stepSelectCursor, writeText } from '@dsh-workbench/shared';
 export declare const kit: {
     hooks: {
+        usePlatform: typeof usePlatform;
         heldPhase(phase: visibleBusyModule.HeldPhase, refreshing: boolean): visibleBusyModule.HeldPhase;
         busyView(active: boolean, visible: boolean): visibleBusyModule.BusyView;
         useVisibleBusy(active: boolean, floorMs: number): visibleBusyModule.BusyView;
@@ -121,6 +123,7 @@ export declare const kit: {
         holdBusy: typeof holdBusy;
         parseJsonLoose: typeof parseJsonLoose;
         parseLocalTimestamp: typeof parseLocalTimestamp;
+        pathBase: typeof pathBase;
         readText: typeof readText;
         relativeTime: typeof relativeTime;
         relativeTimeAgo: typeof relativeTimeAgo;

package/dist/types/app/layouts/env-gate/gate-text.d.ts

@@ -2,6 +2,11 @@ import type { Translate } from '@dsh-workbench/shared';
 import type { PreflightBridgeIssue, PreflightGuidance, PreflightSnapshot, PreflightStep } from '@dsh-workbench/shared/host';
 import type { RuntimeProfile } from '@dsh-workbench/shared';
 export declare function failedStepText(guidance: PreflightGuidance | undefined, t: Translate): string;
+export interface GuidanceText {
+    readonly why: string;
+    readonly step: string;
+}
+export declare function guidanceTextOf(guidance: PreflightGuidance | undefined, t: Translate): GuidanceText;
 export declare function stepDetailText(step: PreflightStep, snapshot: PreflightSnapshot, t: Translate): string;
 export declare function gateHintOf(snapshot: PreflightSnapshot, t: Translate): string;
 export declare function showsRawDetails(snapshot: PreflightSnapshot): boolean;

package/dist/types/kernel/contract/index.d.ts

@@ -1,6 +1,7 @@
 export type { UnitModuleFace, UnitMountDeps, UnitMountResult } from '@dsh-workbench/shared/host';
 export type { FlowAction, FlowActionContext, FlowActionRegistry, FlowActionStep, FlowCheck, FlowDefinition, FlowForEach, FlowHost, FlowPoll, FlowPredicate, FlowProblem, FlowResult, FlowRetry, FlowRunOptions, FlowScope, FlowStep, FlowStepEvent, FlowSubFlowStep, FlowValue, HostKit, } from '@dsh-workbench/shared/host';
 export type { ExtensionCaller, ExtensionCallOptions, ExtensionNeed, ExtensionSession, CommandReader, ExtensionValue, GitReader, LibReader } from '@dsh-workbench/shared';
-export type { BoardModuleProps as BoardProps, CallOverrides, DataError, DataReader, DataRequest, DataResult, RequestRecipe, UnitClientApi, UnitClientFace, } from '@dsh-workbench/shared';
+export type { BoardModuleProps as BoardProps, CallOverrides, DataError, DataReader, DataRequest, DataResult, DshToolDefinition, DshToolRegistry, DshToolRunContext, RequestRecipe, UnitClientApi, UnitClientFace, } from '@dsh-workbench/shared';
 export type { DshClientContext as ClientContext, DshHostContext as HostContext } from '@dsh-workbench/shared';
+export type { ClientCapabilities, ClientShell, ClientSurface, Deployment, HostCapabilities, HostOs, HostRuntime, HostSurface, ProfileName, SelfUpdateCli, ToolchainPlan, } from '@dsh-workbench/shared';
 export type { UnitRegistry } from '../host/unit-registry.js';

package/dist/types/kernel/host/mount-units.d.ts

@@ -1,4 +1,4 @@
-import type { DshHostContext } from '@dsh-workbench/shared';
+import type { DshHostContext, HostSurface } from '@dsh-workbench/shared';
 import type { UnitManifest } from '@dsh-workbench/shared/host';
 import { type RouteTable } from '@dsh-workbench/shared/host';
 import type { ContextRenderer, LongTaskBase, LongTaskChange, LongTaskRegistry, UnitMountDeps, UnitMountResult, UnitCall } from '@dsh-workbench/shared/host';
@@ -68,6 +68,7 @@ export declare function mountUnits(units: readonly HostUnit[], deps: {
     probe?: UnitMountDeps['probe'];
     store?: UnitMountDeps['store'];
     values?: UnitMountDeps['values'];
+    surface?: HostSurface | undefined;
     longTasks?: {
         readonly scope: string;
         readonly bump: (facts: readonly string[]) => void;

package/dist/types/shared/api/host/git-exec.d.ts

@@ -1,3 +1,3 @@
-export declare const GIT_NO_PROMPT_ENV: Readonly<Record<string, string>>;
-export declare function gitNoPromptPrefix(): string;
+export declare function gitNoPromptEnv(platform?: NodeJS.Platform): Readonly<Record<string, string>>;
+export declare function gitNoPromptProcessEnv(parent?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): NodeJS.ProcessEnv;
 export declare function withoutAskpassNoise(text: string): string;

package/dist/types/shared/hooks/runtime-queries.d.ts

@@ -1,6 +1,7 @@
-import type { ApiResponse, RuntimeCapabilities, RuntimeProfile } from '@dsh-workbench/shared';
+import type { ApiResponse, HostSurface, RuntimeCapabilities, RuntimeProfile } from '@dsh-workbench/shared';
 export type RuntimeCapabilitiesPayload = {
     readonly capabilities: RuntimeCapabilities;
     readonly runtimeProfile?: RuntimeProfile | null;
+    readonly surface?: HostSurface | null;
 };
 export declare function readRuntimeCapabilities(): Promise<ApiResponse<RuntimeCapabilitiesPayload>>;

package/dist/types/shared/hooks/use-platform.d.ts

@@ -0,0 +1,13 @@
+import type { ClientSurface, HostSurface } from '@dsh-workbench/shared';
+/**
+ * 卡片看到的平台事实：客户端侧现算，宿主侧从 health 读；没读到之前宿主侧是 `undefined`。
+ */
+export interface PlatformView {
+    readonly client: ClientSurface;
+    readonly host: HostSurface | undefined;
+}
+/**
+ * 卡片里拿平台事实的唯一入口：部署形态 / 能力 / 操作系统的差异按这里的值分叉，别自己读 `window` 或 `process`。
+ * @returns `client` 是浏览器侧事实（deployment / shell / 宿主机 OS / capabilities），`host` 是宿主侧 surface（可能还没读到）。
+ */
+export declare function usePlatform(): PlatformView;

package/dist/types/shared/hooks/use-runtime-capabilities.d.ts

@@ -1,6 +1,8 @@
-import type { RuntimeCapabilities, RuntimeProfile } from '@dsh-workbench/shared';
+import type { HostSurface, RuntimeCapabilities, RuntimeProfile } from '@dsh-workbench/shared';
 export declare function pluginMarketOf(capabilities: RuntimeCapabilities | undefined): boolean;
 export declare function runtimeCapabilitiesValue(): RuntimeCapabilities | undefined;
 export declare function runtimeProfileValue(): RuntimeProfile | undefined;
+export declare function hostSurfaceValue(): HostSurface | undefined;
 export declare function resetRuntimeCapabilities(): void;
 export declare function useRuntimeCapabilities(): RuntimeCapabilities | undefined;
+export declare function useHostSurface(): HostSurface | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-workbench/core",
-  "version": "1.1.12",
+  "version": "1.1.14-beta.0",
   "description": "个人工作台：Agent 工作台（左栏 + 常驻对话 + 自研右侧数据面板）。",
   "type": "module",
   "icon": "./icon.svg",
@@ -76,7 +76,7 @@
     }
   },
   "devDependencies": {
-    "@arch-guard/core": "^0.11.2",
+    "@arch-guard/core": "^0.11.3",
     "@deepseek-ai/dsh-client-ui-primitives": "0.2.1-rc.2",
     "@types/node": "^24.19.0",
     "@types/proper-lockfile": "^4.1.4",
@@ -100,8 +100,8 @@
     "proper-lockfile": "^4.1.2",
     "which": "^7.0.0",
     "write-file-atomic": "^8.0.0",
-    "@dsh-workbench/adapters-default": "1.1.12",
-    "@dsh-workbench/shared": "1.1.12"
+    "@dsh-workbench/shared": "1.1.14-beta.0",
+    "@dsh-workbench/adapters-default": "1.1.14-beta.0"
   },
   "license": "MIT",
   "repository": {

package/scripts/create-workbench.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { spawnSync } from 'node:child_process';
+import { execaSync } from 'execa';
 import { existsSync, readdirSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
@@ -56,9 +56,12 @@ function nameProblem(value, source, profiles) {
 }
 
 function runSetup(args) {
-  const child = spawnSync('bash', [join(PKG_ROOT, 'bin', 'dsh-workbench'), ...args], { stdio: 'inherit' });
-  if (child.error !== undefined) fail(child.error.message);
-  process.exit(child.status ?? 1);
+  const child = execaSync('bash', [join(PKG_ROOT, 'bin', 'dsh-workbench'), ...args], {
+    stdio: 'inherit',
+    reject: false,
+  });
+  if (child.failed) fail(child.shortMessage ?? `bash 起不来（退出码 ${child.exitCode ?? '未知'}）`);
+  process.exit(child.exitCode ?? 1);
 }
 
 if (!process.stdin.isTTY || !process.stdout.isTTY) {

package/scripts/seed-workshop.sh

@@ -648,10 +648,32 @@ EOF
 - 造一个新模块：`dsh-wb-module init <名字> --dir packages/module-<名字>`
   （`dsh-wb-module` 挂在 PATH 上、与 cwd 无关；写成 `pnpm exec dsh-wb-module …` 也对）
 - 每个模块自己的四件事：`pnpm build` / `pnpm typecheck` / `pnpm test` / `pnpm selfcheck`，
-  外加 `dsh-wb-module check` 的十条判据。
+  外加 `dsh-wb-module check` 的十三条判据。
 
 不要手改这个目录下的 `package.json` / `pnpm-workspace.yaml` / `.npmrc`：
 它们是 `dsh-workbench setup` 生成的，模块要加依赖就加在**模块自己**的 `package.json` 里。
+EOF
+  cat >"$DIY_DIR/AGENTS.md" <<'EOF'
+# DIY 工坊 · agent 说明
+
+模块住在 `packages/`，一个模块一个目录。开新模块：
+
+    dsh-wb-module init <名字> --dir packages/module-<名字>
+
+## 依赖
+
+依赖装在这个工坊根（`packages/` 的上一层），已经装好；模块包里不要再 `pnpm install`：
+
+- 缺依赖 / 工具链换代：在**宿主终端**到工坊根跑 `pnpm install`；`dsh-workbench setup` 也做这件事。
+- 会话沙箱里直接跑 `pnpm install` 会 EPERM：link 目标在可写根之外。
+- 模块自己加依赖，写进**模块自己**的 `package.json`，再在工坊根装一次。
+
+## 每个模块
+
+`pnpm build` / `pnpm typecheck` / `pnpm test` / `pnpm selfcheck`，外加 `dsh-wb-module check`
+（十三条判据）；单跑一条：`dsh-wb-module check --only <判据>`。
+
+这个目录的 `package.json` / `pnpm-workspace.yaml` / `.npmrc` 由 setup 生成，手改会被覆盖。
 EOF
 fi
 
@@ -665,17 +687,24 @@ fi
 # 用 pnpm 的 overrides 而不是改模块模板：模板里写死 link 路径会把"装到别人机器上"这条弄坏，
 # overrides 活在**这个工坊**里，模块的 package.json 仍旧是干净的 `^0.1.x`。
 # 放在第一次 `pnpm install` **之前**，这样一次装就是对的；已存在的工坊再跑一次 setup 也会被修好。
+#
+# devDependencies 与 overrides **必须同一套值、一起重写**：只刷 overrides 的话，老清单里的
+# devDependencies 会永远停在旧路径（实测：dev 指向早已不存在的 `packages/workbench`、overrides
+# 指向 `packages/core`），`init` 读外壳 manifest 时还会踩到悬空链接。
 if [ "$IN_REPO" = "1" ] && [ -f "$DIY_DIR/package.json" ]; then
   node - "$DIY_DIR/package.json" "$CORE_SPEC" "$TOOLS_SPEC" "$SHARED_SPEC" <<'NODE'
 const [file, core, tools, shared] = process.argv.slice(2);
 const fs = require('node:fs');
 const manifest = JSON.parse(fs.readFileSync(file, 'utf8'));
+const want = {
+  '@dsh-workbench/core': core,
+  '@dsh-workbench/module-tools': tools,
+  '@dsh-workbench/shared': shared,
+};
+manifest.devDependencies = { ...(manifest.devDependencies ?? {}), ...want };
 manifest.pnpm = {
-  overrides: {
-    '@dsh-workbench/core': core,
-    '@dsh-workbench/module-tools': tools,
-    '@dsh-workbench/shared': shared,
-  },
+  ...(manifest.pnpm ?? {}),
+  overrides: { ...(manifest.pnpm?.overrides ?? {}), ...want },
 };
 fs.writeFileSync(file, `${JSON.stringify(manifest, null, 2)}\n`);
 NODE
@@ -688,7 +717,16 @@ elif ! command -v pnpm >/dev/null 2>&1; then
   echo "     cd $DIY_DIR && pnpm install" >&2
 else
   echo "→ 装工坊依赖（第一次会下载 react / typescript / vitest，几百 MB，之后不再下）"
-  (cd "$DIY_DIR" && pnpm install 2>&1 | tail -6)
+  install_log="${TMPDIR:-/tmp}/dsh-wb-install.$$.log"
+  if (cd "$DIY_DIR" && pnpm install >"$install_log" 2>&1); then
+    tail -6 "$install_log"
+    rm -f "$install_log"
+  else
+    tail -20 "$install_log" >&2
+    rm -f "$install_log"
+    echo "→ ⚠️ 装工坊依赖失败。若上面报 EPERM：link 目标在可写根之外 —— 到宿主终端重跑 setup（它由人跑、不受会话沙箱）。" >&2
+    echo "   装好前工坊里的模块跑不了 pnpm build / check；恢复后在工坊根重跑 pnpm install 即可。" >&2
+  fi
 fi
 
 # 完整的这一趟跑完：先挂指引（不管有没有基准 —— setup 那趟也要建起来），再看要不要自愈。