@dsh-workbench/core 1.1.13 → 1.1.14-beta.1

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 = [];
@@ -867,14 +873,15 @@ async function settleWithin(work, limitMs) {
 	}
 }
 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 }
 	});
 	return await settleWithin((async () => {
 		const result = await (await shell.execute(spec)).result();
@@ -892,14 +899,22 @@ async function runShell(shell, command, options = {}) {
 //#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, `'\\''`)}'`;
 }
 /**
@@ -4356,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
@@ -4753,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
@@ -4773,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;
 }
@@ -4786,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()
@@ -4875,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 = [];
@@ -6805,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();
 }
@@ -6822,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 },
@@ -8389,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 {
@@ -13141,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;
@@ -17363,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,
@@ -18295,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,
@@ -18312,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");
@@ -18465,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/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.13",
+  "version": "1.1.14-beta.1",
   "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/shared": "1.1.13",
-    "@dsh-workbench/adapters-default": "1.1.13"
+    "@dsh-workbench/adapters-default": "1.1.14-beta.1",
+    "@dsh-workbench/shared": "1.1.14-beta.1"
   },
   "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 那趟也要建起来），再看要不要自愈。

package/skills/workbench-module-diy/BUILD.md

@@ -33,27 +33,30 @@
 ## 2 从模板开始
 
 ```bash
-pnpm exec dsh-wb-module init <unit> --dir <工作区>/packages/module-<unit> --template diy --description "<一句话>"
+pnpm exec dsh-wb-module init <unit> --dir <目录> --template diy --description "<一句话>"
 ```
 
 `<unit>`：小写短横线，同时是单元 id、包名后缀、样式前缀；全局唯一（与已装模块、外壳单元冲突时装配抛错）。
-骨架开箱即绿（十三条判据 + 六脚本）。
-
-| 模板 | 内容 | 适用 |
-|---|---|---|
-| `minimal`（默认） | 空壳：卡壳、文案、测试；无数据源 | 已明确读什么 |
-| `diy` | 样板卡：宿主一条只读路由 + 五态 | 需要可运行的数据样板（推荐） |
+`<目录>` 是模块落地处：在某个工作区里就选它 glob 覆盖的目录（`packages/`、`apps/`、`modules/`…都行）；
+独立目录也行，那时这个包自己就是根。
+骨架开箱 `check` 绿；`selfcheck` 里还含 `design check`，底稿填完才绿（脚本 8 个）。**只有一个模板**：`--template diy`（默认）——
+真数据源 + 五态卡片 + 可跑的长任务 / 工具 / 动作通道样板；维护两份模板的成本没人付。
 
 骨架分层：`src/model/**`（纯逻辑）、`src/components/**`（视图 + 同目录 `*.module.css`）、
-`src/messages.ts`、`src/host.ts`、`src/client.tsx`、`scripts/smoke.mjs`、`design.json`。
-模板原文可直接读。非显然项：
+`src/messages.ts`、`src/host.ts`（宿主面）+ `src/host/**`（宿主侧内部实现，
+`moduleArch()` 默认认这一层）、`src/client.tsx`、`scripts/smoke.mjs` +
+`scripts/smoke.assert.mjs`、`design.json`。模板原文可直接读。非显然项：
+
+宿主面注册那段（`name` / `inject` / `apply`）用 `@dsh-workbench/shared/host` 的
+`defineUnitHostPlugin`；写工具的审批口径用 `writeApprovalOf`；`recordOf` / `textOf` 也从那里取，
+别每个宿主文件抄一份。浏览器侧注册仍是十几行样板（kit 还没有对应的收口）。
 
 | 文件 | 要点 |
 |---|---|
-| `arch.config.mjs` | 一行 `moduleArch()`（`@dsh-workbench/module-tools/arch`）；层序、运行时、阈值随工具链 |
+| `arch.config.mjs` | `moduleArch()`（`@dsh-workbench/module-tools/arch`）；层序、运行时、阈值随工具链 |
 | `eslint.config.mjs` | 两行 `moduleLint({ rootDir: import.meta.dirname })`；`rootDir` 钉 tsconfig 根 |
 | `types/styles.d.ts` | 用 `X.module.css` 必须有；`globals.d.ts` 是模块，其 `declare module` 不算环境声明 |
-| `design.json` | 三张表 / 矩阵 / 数据源 / 验收；README 段由它生成（`minimal` 无此文件，按 [DESIGN.md](DESIGN.md) §5 建） |
+| `design.json` | 三张表 / 矩阵 / 数据源 / 验收；README 段由它生成 |
 
 修改位置：视图改 `src/components/*.tsx` + 同目录 `*.module.css`；逻辑改 `src/model/**`；文案改 `src/messages.ts`；
 `src/client.tsx` 只留注册。宿主侧不 import `src/components/**`（跨运行时，`arch` 判红）。
@@ -61,8 +64,8 @@ pnpm exec dsh-wb-module init <unit> --dir <工作区>/packages/module-<unit> --t
 ## 3 命令
 
 用 `pnpm exec dsh-wb-module …`；命令、`--only` 判据名与模板参数看 `--help` / `check --list`，不在指引里抄。
-`package.json` 六个脚本（`build` / `typecheck` / `test` / `selfcheck` / `check` / `lint`）必须保留，
-`contracts` 点名缺失。
+`package.json` 至少保留 `build` / `typecheck` / `test` / `selfcheck` 四个脚本，`contracts` 点名缺失；
+模板自带 8 个（另含 `check` / `lint` / `design` / `prepack`）。
 
 - `check` 不跑 `pnpm test`；状态、换算、边界测试自己跑。
 - "不适用"不是"通过"：`standalone` 需外壳源码在场，`markers` 只扫公开包（DIY 模块 `private`）。
@@ -73,25 +76,31 @@ pnpm exec dsh-wb-module init <unit> --dir <工作区>/packages/module-<unit> --t
 
 ## 4 两个面
 
-宿主面：
+宿主面（`defineUnitHostPlugin` 把 `name` / `inject` / `apply` 一起给）：
 
 ```ts
-export const name = '<包名>';
-export const inject = ['workbenchUnits'];
-
-export function apply(ctx) {
-  const units = ctx.get('workbenchUnits');
-  if (units === undefined) return;
-  ctx.effect(() => units.register({ manifest, mount }), '<unit>: 注册');
-}
+import { defineUnitHostPlugin } from '@dsh-workbench/shared/host';
+
+const plugin = defineUnitHostPlugin({
+  name: '<包名>',
+  unit: '<unit>',
+  face: { unit: '<unit>', mount },
+});
+
+export const name = plugin.name;
+export const inject = plugin.inject;
+export const apply = plugin.apply;
 ```
 
+展开写就是：`inject = ['workbenchUnits']`，`apply(ctx)` 里从 `ctx.get('workbenchUnits')` 拿注册表，
+再 `ctx.effect(() => units.register(face), '<unit>: 注册')`。
+
 `mount({ data })` 的 `data` 是统一数据端口（`DataReader`）；读数据用 `data.read(...)`，不要自己 import adapter。
-`mount()` 返回 `{ routes, registerTools, prefs? }`。`routes` 挂 `/workbench/api/<路由>`，只许 GET，
+`mount()` 返回 `UnitMountResult`：`routes`、`registerTools()`，以及可选的 `factsOf` / `gate` / `context` / `warmReads` / `prefs` / `actions` / `provision` / `longTasks` / `approvalDetail` / `needsApproval`。`routes` 挂 `/workbench/api/<路由>`，只许 GET，
 键必须在 `<unit>` 或 `<unit>/…` 之下（否则装配抛错）。错误返回
 `{ ok: false, error: { code, message, hint? } }`（HTTP 200，外壳转发）。`registerTools` 提供模块工具。
 
-浏览器面：`units.registerUnit({ manifest, messages, card })`。`card` 收到
+浏览器面：`units.registerUnit({ unit, messages, card })`；清单由外壳从已装清单读，不在面里重复。`card` 收到
 `{ t, world, refreshToken, onRefresh, onSummary }`（`world.current.workspace` 为当前项目），返回元素。
 三态用 kit：加载 `kit.components.SkeletonRows`；空 `kit.components.EmptyState`（无按钮）；
 错误 `kit.components.BlockerState` + `kit.lib.blockerOfError(error, t)`。

package/skills/workbench-module-diy/DATASOURCE.md

@@ -49,8 +49,9 @@
    - 脚本约定：不在站点 → `{ ok: false, code: "not-on-site" }`；登录过期 → `{ ok: false, code: "not-logged-in" }`
      （工具归一为 `auth-required`）；成功 → `{ ok: true, ...数据 }`。
    - 新 session 的 `eval` 会静默开 `about:blank`（后台容器窗，不抢焦点）。脚本第一行判断
-     `location.origin`；不在站点则 `open` 该页，等约 1 秒再 eval。两拍都用 shared 的 `backgroundLine`
-     拼（前缀 `env OPENCLI_WINDOW=background`），不要直接拼 `opencli browser …`。
+     `location.origin`；不在站点则 `open` 该页，等约 1 秒再 eval。在 shell 里跑 opencli 时不要自己
+     拼命令前缀：`OPENCLI_WINDOW` 这类环境变量走宿主 shell 的 env 覆盖（`env` 是叠加，POSIX / pwsh 通用），
+     手写 `env NAME=value` / `$env:NAME` 在另一个平台就是坏的。
    - 读与屏用不同会话：`data.read({ kind: 'browser' })` 默认读会话 `workbench-read`；`workbench` 是看 / 动族的屏会话。同名会把用户的页导航走。需要独立标签就传 `session: "<unit>"`。
    - DOM 读不要在宿主脚本里 `querySelectorAll`：宿主产物禁止 `document.`，且无法单测。探时用
      `workbench_diy_find`（`read=…, args=["--css", "<选择器>"]`）；固化用

package/skills/workbench-module-diy/FAMILY.md

@@ -21,7 +21,7 @@
 
 - 只在 DIY 模式的会话出现；面板得画在屏上。
 - 看 / 动 / 网络 / 日志族先 `_debug_start`（审批一次），否则整族拒、零命令；收工 `_debug_stop`。
-  `_pause` 只暂停看屏。不碰屏的：`_status` / `_panel` / `_components` / `_recon` / `_spec` /
+  `_debug_pause` 只暂停看屏。不碰屏的：`_status` / `_panel` / `_components` / `_recon` / `_spec` /
   `_install` / `_show` / `_publish`；`_find` / `_eval` 带 `read=` 时也不碰。
 - 录制独立：`_record_prepare` 审批一次，其余不问；同时只有一场，要重来先 `_record_stop`。