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

package/README.md

@@ -5,16 +5,17 @@
 不会打架。
 
 对模块作者来说，这里是「不用自己重画」的那一层：卡片壳、行、表单、链接、加载态都在
-`components/`，契约类型都在 `api/`。**dsh 有的原语走 kit，工作台自己的视觉用这里的组件**，
+`components/`，契约类型都在 `contract/`。**dsh 有的原语走 kit，工作台自己的视觉用这里的组件**，
 两者拼出面板，不要从 DOM + CSS 重写一遍。
 
-## 三个入口
+## 四个导出面
 
 | 入口 | 谁用 | 有什么 |
 |---|---|---|
 | `@dsh-workbench/shared` | 浏览器侧 | 契约类型、纯函数、哑组件（样式随组件）、i18n、读通道 `apiGet` / `factOfRoute` |
-| `@dsh-workbench/shared/host` | 宿主侧（Node） | 数据根、opencli 运行时、git、http、面板状态、单元声明、请求配方 composer、公共通道插件计划等，**有 `node:*`** |
+| `@dsh-workbench/shared/host` | 宿主侧（Node） | 数据根、git、http、面板状态、单元声明、请求配方 composer 等，**有 `node:*`** |
 | `@dsh-workbench/shared/testing` | 测试 | 宿主侧假件、从 `package.json` 读模块声明 |
+| `@dsh-workbench/shared/contract/*` | 插件 / 适配器（仅类型） | 契约子路径；`exports` 里的 `./contract/*`，只给类型用 |
 
 两条硬边界：
 
@@ -40,7 +41,8 @@ CSS 处理。
 
 | 落点 | 是什么 |
 |---|---|
-| `src/api/` | 契约：单元清单、卡片面、读通道、写通道、长任务、审批、面板状态 |
+| `src/api/` | 浏览器侧接缝：读 / 写通道、平台客户端 |
+| `src/contract/` | 契约：单元清单、卡片面、读 / 写通道、长任务、审批、面板状态 |
 | `src/components/` | 哑组件：`Card` / `CardHead` / `Rows` / `Form` / `FormRow(s)` / `FormActions` / `Link` / `Stack` / 各态块 |
 | `src/config/` | 常量与存储键 |
 | `src/i18n/` | zh / en 字典、合并与设置 |

package/dist/api/dsh.d.ts

@@ -144,6 +144,7 @@ export interface DshShellExecution {
 }
 /**
  * dsh 的 shell 服务：先 resolve 出执行规格，再把它原样喂给 execute。
+ * `env` 是**叠加**在宿主环境上的变量覆盖（不是替换），所以设一个变量不必自己拼 shell 语法。
  */
 export interface DshShell {
     resolve(request: {
@@ -153,6 +154,7 @@ export interface DshShell {
         onExpiry?: 'kill' | 'none';
         stdoutMaxBytes?: number;
         signal?: AbortSignal;
+        env?: Readonly<Record<string, string>>;
     }): unknown;
     execute(spec: unknown): Promise<DshShellExecution>;
 }

package/dist/config/constants.d.ts

@@ -50,6 +50,8 @@ export declare const WARM_TIMEOUT_MS = 20000;
 export declare const PREFLIGHT_FRESH_MS = 30000;
 /** 装 / 卸模块包的超时（毫秒）：pnpm 与取包内容都按它算。 */
 export declare const INSTALL_TIMEOUT_MS = 300000;
+/** 启动体检里查版本号那一条的超时（毫秒）：只印个版本号，留够 opencli 每次调用约 5 秒的开销；`doctor` 要起浏览器会话，另按 `OPENCLI_TIMEOUT_MS`。 */
+export declare const PREFLIGHT_VERSION_TIMEOUT_MS = 30000;
 /** 查 registry 版本那一次请求的超时（毫秒）。 */
 export declare const VERSION_CHECK_TIMEOUT_MS = 10000;
 /** 版本查询结果的缓存有效期（毫秒）：期内不发第二次请求。 */

package/dist/config/constants.js

@@ -50,6 +50,8 @@ export const WARM_TIMEOUT_MS = 20_000;
 export const PREFLIGHT_FRESH_MS = 30_000;
 /** 装 / 卸模块包的超时（毫秒）：pnpm 与取包内容都按它算。 */
 export const INSTALL_TIMEOUT_MS = 300_000;
+/** 启动体检里查版本号那一条的超时（毫秒）：只印个版本号，留够 opencli 每次调用约 5 秒的开销；`doctor` 要起浏览器会话，另按 `OPENCLI_TIMEOUT_MS`。 */
+export const PREFLIGHT_VERSION_TIMEOUT_MS = 30_000;
 /** 查 registry 版本那一次请求的超时（毫秒）。 */
 export const VERSION_CHECK_TIMEOUT_MS = 10_000;
 /** 版本查询结果的缓存有效期（毫秒）：期内不发第二次请求。 */

package/dist/contract/command.d.ts

@@ -6,6 +6,7 @@ export interface CommandRequest {
     readonly argv: readonly string[];
     readonly timeoutMs?: number | undefined;
     readonly cwd?: string | undefined;
+    readonly env?: Readonly<Record<string, string>> | undefined;
     readonly files?: readonly CommandFile[] | undefined;
     readonly appendFileArgs?: string | undefined;
 }
@@ -14,6 +15,7 @@ export interface CommandResult {
     readonly stderr: string;
     readonly exitCode: number;
     readonly timedOut: boolean;
+    readonly truncated: boolean;
     readonly filePaths: readonly string[];
     readonly error?: string | undefined;
 }

package/dist/contract/unit-declaration.js

@@ -77,14 +77,15 @@ export function declarationProblemsOf(subject, raw) {
     if (version === undefined) {
         return [
             `${subject}: dsh.workbench 没有 apiVersion —— 协议从 v${WORKBENCH_API_VERSION} 起，` +
-                `写 \`"apiVersion": ${WORKBENCH_API_VERSION}\`。缺它 = 外壳不认这个模块`,
+                `写 \`"apiVersion": ${WORKBENCH_API_VERSION}\`。缺它 = 外壳不认这个模块` +
+                '（`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'
-            : '';
+            : ' —— 先跑 `dsh-wb-module migrate` 把版本号改到 3，再按 check 的提示改源码';
         return [
             `${subject}: dsh.workbench.apiVersion 是 ${JSON.stringify(version)}，这里只认 ` +
                 `${SUPPORTED_API_VERSIONS.join(' / ')}（要整数）${hint}`,

package/dist/host/data-root.js

@@ -1,15 +1,17 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
 export function dshHome() {
     const configured = process.env.DSH_HOME?.trim();
     if (configured !== undefined && configured !== '')
         return configured;
-    return `${process.env.HOME ?? ''}/.dsh`;
+    return join(homedir(), '.dsh');
 }
 export function workbenchRoot() {
     const configured = process.env.DSH_WORKBENCH_HOME?.trim();
     if (configured !== undefined && configured !== '')
         return configured;
-    return `${dshHome()}/workbench`;
+    return join(dshHome(), 'workbench');
 }
 export function workspacesRoot() {
-    return `${workbenchRoot()}/workspaces`;
+    return join(workbenchRoot(), 'workspaces');
 }

package/dist/host/flow/step.d.ts

@@ -0,0 +1,11 @@
+import type { LongTaskStep } from '../../contract/long-task.js';
+import type { FlowStepEvent } from './types.js';
+/**
+ * 把流程的一步事件翻成长任务步骤流的默认一行。
+ * `running` → `start`、`ok` → `succeed`、`skipped` → `info`、`failed` → `fail`、
+ * `needs-login` → `info`（带 `loginUrl`）；文字取 `message ?? title`。
+ * 要改文案或过滤步骤，就在模块里自己映射 —— 这只是默认值。
+ * @param event `flow.run({ onStep })` 收到的那条事件。
+ * @returns 能直接交给长任务 `run({ onStep })` 的一行。
+ */
+export declare function longTaskStepOf(event: FlowStepEvent): LongTaskStep;

package/dist/host/flow/step.js

@@ -0,0 +1,21 @@
+/**
+ * 把流程的一步事件翻成长任务步骤流的默认一行。
+ * `running` → `start`、`ok` → `succeed`、`skipped` → `info`、`failed` → `fail`、
+ * `needs-login` → `info`（带 `loginUrl`）；文字取 `message ?? title`。
+ * 要改文案或过滤步骤，就在模块里自己映射 —— 这只是默认值。
+ * @param event `flow.run({ onStep })` 收到的那条事件。
+ * @returns 能直接交给长任务 `run({ onStep })` 的一行。
+ */
+export function longTaskStepOf(event) {
+    const text = event.message ?? event.title;
+    if (event.status === 'failed')
+        return { kind: 'fail', text };
+    if (event.status === 'needs-login') {
+        return { kind: 'info', text, ...(event.loginUrl === undefined ? {} : { loginUrl: event.loginUrl }) };
+    }
+    if (event.status === 'ok')
+        return { kind: 'succeed', text };
+    if (event.status === 'skipped')
+        return { kind: 'info', text };
+    return { kind: 'start', text };
+}

package/dist/host/host-kit.d.ts

@@ -1,19 +1,24 @@
+import type { HostSurface } from '../contract/protocol/platform.js';
 import type { EnvSupplyPort } from './port-types.js';
 import { type FlowHost } from './flow/kit.js';
 import { sessionIdOf, sessionWorkspace } from './tool-kit.js';
 /**
- * 宿主 kit 的公共部分：flow、工具侧 session 读法、外部供给装法。
+ * 宿主 kit 的公共部分：flow、工具侧 session 读法、外部供给装法、宿主平台事实。
  */
 export interface HostKit {
     readonly flow: FlowHost;
     readonly sessionIdOf: typeof sessionIdOf;
     readonly sessionWorkspace: typeof sessionWorkspace;
     readonly libInstallCommand: EnvSupplyPort['libInstallCommand'];
+    readonly surface: HostSurface;
 }
 /**
  * 建一份宿主 kit；每个挂载点一份，没有模块级状态。
- * @returns flow / sessionIdOf / sessionWorkspace / libInstallCommand。
+ * @param parts.libInstallCommand 拼「装这个共用依赖」的那条命令。
+ * @param parts.surface 宿主平台事实；由组合根按 profile 与宿主进程算好再交进来。
+ * @returns flow / sessionIdOf / sessionWorkspace / libInstallCommand / surface。
  */
 export declare function createHostKit(parts: {
     readonly libInstallCommand: EnvSupplyPort['libInstallCommand'];
+    readonly surface: HostSurface;
 }): HostKit;

package/dist/host/host-kit.js

@@ -2,7 +2,9 @@ import { createFlowHost } from './flow/kit.js';
 import { sessionIdOf, sessionWorkspace } from './tool-kit.js';
 /**
  * 建一份宿主 kit；每个挂载点一份，没有模块级状态。
- * @returns flow / sessionIdOf / sessionWorkspace / libInstallCommand。
+ * @param parts.libInstallCommand 拼「装这个共用依赖」的那条命令。
+ * @param parts.surface 宿主平台事实；由组合根按 profile 与宿主进程算好再交进来。
+ * @returns flow / sessionIdOf / sessionWorkspace / libInstallCommand / surface。
  */
 export function createHostKit(parts) {
     return {
@@ -10,5 +12,6 @@ export function createHostKit(parts) {
         sessionIdOf,
         sessionWorkspace,
         libInstallCommand: parts.libInstallCommand,
+        surface: parts.surface,
     };
 }

package/dist/host/install-failure.js

@@ -1,7 +1,7 @@
 import { accessSync, constants, statSync } from 'node:fs';
 import { dirname } from 'node:path';
 const TARGET_FLAGS = ['--prefix', '--cache', '--dir', '--store-dir'];
-const INSTALL_VERBS = /^\s*npm\s+(i|install|add)\b/;
+const INSTALL_VERBS = /^\s*(?:npm\s+(?:i|install|add)|pnpm\s+(?:add|install))\b/;
 const NPM_PATH = /^npm (?:error|ERR!) path (.+)$/m;
 export function commandTokens(command) {
     const tokens = [];

package/dist/host/lib-install.d.ts

@@ -10,6 +10,7 @@ export declare function libInstallCommand(options: {
     readonly env?: NodeJS.ProcessEnv | undefined;
     readonly prefix: string;
     readonly cacheDir?: string | undefined;
+    readonly pnpm?: string | undefined;
 }): string;
 export declare function binInstallCommand(need: BinNeed, os: HostOs, env: NodeJS.ProcessEnv, prefix: string, cacheDir?: string): string | undefined;
 export declare function libUninstallCommand(options: {

package/dist/host/lib-install.js

@@ -2,11 +2,12 @@ import { npmRegistryOf } from './npm-registry.js';
 import { quoteShellArg } from './shell-text.js';
 export function libInstallCommand(options) {
     const { need, source, version } = options;
+    const pnpm = options.pnpm ?? process.env.DSH_WB_PNPM?.trim() ?? 'pnpm';
     const registry = npmRegistryOf(source, options.env ?? process.env);
     const spec = version ?? need.version ?? 'latest';
     const registryFlag = registry.ok ? ` --registry ${quoteShellArg(registry.value)}` : '';
-    const cacheFlag = options.cacheDir === undefined ? '' : ` --cache ${quoteShellArg(options.cacheDir)}`;
-    return `npm i --prefix ${quoteShellArg(options.prefix)} ${quoteShellArg(`${need.name}@${spec}`)}${registryFlag}${cacheFlag}`;
+    const storeFlag = options.cacheDir === undefined ? '' : ` --store-dir ${quoteShellArg(options.cacheDir)}`;
+    return `${pnpm} add --dir ${quoteShellArg(options.prefix)} ${quoteShellArg(`${need.name}@${spec}`)}${registryFlag}${storeFlag} --allow-build=${quoteShellArg(need.name)}`;
 }
 export function binInstallCommand(need, os, env, prefix, cacheDir) {
     const install = need.install;
@@ -35,5 +36,5 @@ export function binInstallCommand(need, os, env, prefix, cacheDir) {
     });
 }
 export function libUninstallCommand(options) {
-    return `npm uninstall --prefix ${quoteShellArg(options.prefix)} ${quoteShellArg(options.need.name)}`;
+    return `pnpm remove --dir ${quoteShellArg(options.prefix)} ${quoteShellArg(options.need.name)}`;
 }

package/dist/host/paths.js

@@ -1,18 +1,19 @@
+import { join } from 'node:path';
 import { workbenchRoot } from './data-root.js';
 export function runtimeRootOf(id) {
-    return `${workbenchRoot()}/${id}`;
+    return join(workbenchRoot(), id);
 }
 export function runtimeLayoutOf(id) {
     const root = runtimeRootOf(id);
-    const vendorPrefix = `${root}/plugins-npm`;
-    const libsPrefix = `${root}/libs`;
+    const vendorPrefix = join(root, 'plugins-npm');
+    const libsPrefix = join(root, 'libs');
     return {
         root,
-        home: `${root}/home`,
+        home: join(root, 'home'),
         vendorPrefix,
-        vendorPluginsDir: `${vendorPrefix}/node_modules`,
+        vendorPluginsDir: join(vendorPrefix, 'node_modules'),
         libsPrefix,
-        libsBinDir: `${libsPrefix}/node_modules/.bin`,
-        npmCacheDir: `${root}/npm-cache`,
+        libsBinDir: join(libsPrefix, 'node_modules', '.bin'),
+        npmCacheDir: join(root, 'npm-cache'),
     };
 }

package/dist/host/payload.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 把任意 payload 当对象看；不是对象就回空对象。
+ * @param value 任意入参。
+ * @returns 可按下标取值的安全对象。
+ */
+export declare function recordOf(value: unknown): Record<string, unknown>;
+/**
+ * 把任意 payload 当一段文字看：字符串就 trim，别的都算空串。
+ * @param value 任意入参。
+ * @returns 去掉首尾空白的字符串；不是字符串时是空串。
+ */
+export declare function textOf(value: unknown): string;

package/dist/host/payload.js

@@ -0,0 +1,16 @@
+/**
+ * 把任意 payload 当对象看；不是对象就回空对象。
+ * @param value 任意入参。
+ * @returns 可按下标取值的安全对象。
+ */
+export function recordOf(value) {
+    return typeof value === 'object' && value !== null ? value : {};
+}
+/**
+ * 把任意 payload 当一段文字看：字符串就 trim，别的都算空串。
+ * @param value 任意入参。
+ * @returns 去掉首尾空白的字符串；不是字符串时是空串。
+ */
+export function textOf(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}

package/dist/host/preflight.d.ts

@@ -1,7 +1,7 @@
 export type PreflightStepId = 'toolchain' | 'cli' | 'bridge' | 'runtime' | 'diy' | 'warm';
 export type PreflightStepStatus = 'pending' | 'running' | 'ok' | 'warn' | 'failed';
-export type PreflightFailure = 'permission' | 'network' | 'missing' | 'unknown';
-export type PreflightGuidance = 'install' | 'path' | 'shell';
+export type PreflightFailure = 'permission' | 'network' | 'missing' | 'host' | 'unknown';
+export type PreflightGuidance = 'install' | 'path' | 'shell' | 'host';
 export type PreflightBridgeIssue = string;
 export interface PreflightStep {
     readonly id: PreflightStepId;
@@ -10,6 +10,7 @@ export interface PreflightStep {
     readonly detail?: string;
     readonly action?: string;
     readonly command?: string;
+    readonly log?: readonly string[];
 }
 export interface PreflightDiyGap {
     readonly rows: readonly string[];
@@ -26,4 +27,5 @@ export interface PreflightSnapshot {
     readonly bridgeIssues?: readonly PreflightBridgeIssue[];
     readonly diyGap?: PreflightDiyGap;
     readonly canWakeBrowser?: boolean;
+    readonly log?: readonly string[];
 }

package/dist/host/shell-text.d.ts

@@ -1,5 +1,15 @@
 /**
- * 按目标平台把一个值裹成 shell 字面量：POSIX 用单引号，win32 用双引号（cmd 与 PowerShell 都认）。
+ * 一台机器上跑命令的那种 shell：POSIX 系（sh / bash / zsh），或 dsh 在 Windows 上用的 pwsh。
+ */
+export type ShellKind = 'posix' | 'pwsh';
+/**
+ * 按目标平台判 shell 种类：win32 是 pwsh（dsh 的 Windows 执行器就是 PowerShell），其余是 POSIX。
+ * @param platform - 目标平台，默认当前 `process.platform`。
+ * @returns `'pwsh'` 或 `'posix'`。
+ */
+export declare function shellKindOf(platform?: NodeJS.Platform): ShellKind;
+/**
+ * 按目标平台把一个值裹成 shell 字面量：POSIX 用单引号并按 `'\''` 逃逸，pwsh 也用单引号但按 `''` 逃逸。
  * @param value - 任意值；不是字符串的先 `String()`。
  * @param platform - 目标平台，默认当前 `process.platform`。
  * @returns 可安全拼进该平台 shell 命令的一段文本；含空格 / 元字符的值不会被当成语法。

package/dist/host/shell-text.js

@@ -1,13 +1,21 @@
 /**
- * 按目标平台把一个值裹成 shell 字面量：POSIX 用单引号，win32 用双引号（cmd 与 PowerShell 都认）。
+ * 按目标平台判 shell 种类：win32 是 pwsh（dsh 的 Windows 执行器就是 PowerShell），其余是 POSIX。
+ * @param platform - 目标平台，默认当前 `process.platform`。
+ * @returns `'pwsh'` 或 `'posix'`。
+ */
+export function shellKindOf(platform = process.platform) {
+    return platform === 'win32' ? 'pwsh' : 'posix';
+}
+/**
+ * 按目标平台把一个值裹成 shell 字面量：POSIX 用单引号并按 `'\''` 逃逸，pwsh 也用单引号但按 `''` 逃逸。
  * @param value - 任意值；不是字符串的先 `String()`。
  * @param platform - 目标平台，默认当前 `process.platform`。
  * @returns 可安全拼进该平台 shell 命令的一段文本；含空格 / 元字符的值不会被当成语法。
  */
 export 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, `'\\''`)}'`;
 }
 /**

package/dist/host/shell.d.ts

@@ -6,9 +6,11 @@ export interface ShellResult {
     readonly stdout: string;
     readonly stderr: string;
     readonly truncated: boolean;
+    readonly stalled: boolean;
 }
 export declare function runShell(shell: DshShell, command: string, options?: {
     workdir?: string;
     timeoutMs?: number;
     signal?: AbortSignal;
+    env?: Readonly<Record<string, string>>;
 }): Promise<ShellResult>;

package/dist/host/shell.js

@@ -1,7 +1,32 @@
 import { GIT_TIMEOUT_MS } from '../config/constants.js';
 const DEFAULT_MAX_BYTES = 8 * 1024 * 1024;
+const GUARD_SLACK_MS = 1_000;
+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 !== undefined)
+            clearTimeout(timer);
+    }
+}
 export 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 === undefined ? {} : { workdir }),
@@ -9,15 +34,20 @@ export async function runShell(shell, command, options = {}) {
         onExpiry: 'kill',
         stdoutMaxBytes: DEFAULT_MAX_BYTES,
         ...(signal === undefined ? {} : { signal }),
+        ...(env === undefined ? {} : { env }),
     });
-    const execution = await shell.execute(spec);
-    const result = await execution.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,
-    };
+    const settled = await settleWithin((async () => {
+        const execution = await shell.execute(spec);
+        const result = await execution.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);
+    return settled ?? stalledResult();
 }

package/dist/host/tool-approval.d.ts

@@ -63,3 +63,23 @@ export interface ApprovalContext {
     readonly detailOf?: ((call: ApprovalCall) => ApprovalFacts | undefined | Promise<ApprovalFacts | undefined>) | undefined;
 }
 export declare function approvalFor(call: ApprovalCall, context?: ApprovalContext): Promise<AskDecision | undefined>;
+/**
+ * 「写工具要点头」那一对的默认口径：点名的工具一律 `ask` + 同一份明细，其余一律 `read`。
+ * 把它直接摊在 `mount()` 的返回值里：`...writeApprovalOf({ … })`。
+ * @param options.tools 需要点头的工具名。
+ * @param options.reason 为什么问（给 agent 看的理由）。
+ * @param options.question 问句（zh / en，≤40 字）。
+ * @param options.fallback 没有明细时的整句（zh / en，≤40 字）。
+ * @param options.detail 审批屏头行那句明细（zh / en，≤20 字）。
+ * @returns `{ needsApproval, approvalDetail }`。
+ */
+export declare function writeApprovalOf(options: {
+    readonly tools: readonly string[];
+    readonly reason: string;
+    readonly question: ApprovalDetail;
+    readonly fallback: ApprovalDetail;
+    readonly detail: ApprovalDetail;
+}): {
+    needsApproval(call: ApprovalCall): ApprovalVerdict;
+    approvalDetail(call: ApprovalCall): ApprovalFacts | undefined;
+};

package/dist/host/tool-approval.js

@@ -93,3 +93,23 @@ export async function approvalFor(call, context = {}) {
         displayReason: compose(facts, verdict, note),
     };
 }
+/**
+ * 「写工具要点头」那一对的默认口径：点名的工具一律 `ask` + 同一份明细，其余一律 `read`。
+ * 把它直接摊在 `mount()` 的返回值里：`...writeApprovalOf({ … })`。
+ * @param options.tools 需要点头的工具名。
+ * @param options.reason 为什么问（给 agent 看的理由）。
+ * @param options.question 问句（zh / en，≤40 字）。
+ * @param options.fallback 没有明细时的整句（zh / en，≤40 字）。
+ * @param options.detail 审批屏头行那句明细（zh / en，≤20 字）。
+ * @returns `{ needsApproval, approvalDetail }`。
+ */
+export function writeApprovalOf(options) {
+    const tools = new Set(options.tools);
+    const named = (call) => call.name !== undefined && tools.has(call.name);
+    return {
+        needsApproval: (call) => named(call)
+            ? { kind: 'ask', reason: options.reason, question: options.question, fallback: options.fallback }
+            : { kind: 'read' },
+        approvalDetail: (call) => (named(call) ? options.detail : undefined),
+    };
+}

package/dist/host/unit-face.d.ts

@@ -49,6 +49,11 @@ export interface UnitCall {
     readonly args: Readonly<Record<string, unknown>>;
     readonly result: unknown;
 }
+/**
+ * 挂载结果：路由表 + 工具注册。
+ * `registerTools()` 是**调用时才注册**，返回一组清理函数（卸载 / 热换时外壳逐个调）；
+ * 工具名必须与清单 `dsh.workbench.tools` 一字不差，没有工具就 `() => []`。
+ */
 export interface UnitMountResult {
     readonly routes: RouteTable;
     registerTools(): Array<() => void>;

package/dist/host/unit-plugin.d.ts

@@ -0,0 +1,33 @@
+import type { UnitModuleFace } from './unit-face.js';
+/**
+ * 宿主面注册只需要的那点上下文：`get` / `effect` / 可选的 `logger`。
+ */
+export interface UnitHostContextLike {
+    get<T = unknown>(name: string): T | undefined;
+    effect(effect: () => void | (() => void), label?: string): () => void;
+    readonly logger?: {
+        warn?(message: string): void;
+    } | undefined;
+}
+/**
+ * 一个宿主插件导出的三件：`name` / `inject` / `apply`。
+ */
+export interface UnitHostPlugin {
+    readonly name: string;
+    readonly inject: readonly string[];
+    apply(ctx: UnitHostContextLike): void;
+}
+/**
+ * 把「宿主面注册进外壳」这段在每个模块里都一样的接线收成一份。
+ * 用法：先 `const plugin = defineUnitHostPlugin({ … })`，再逐个导出 `name` / `inject` / `apply`
+ * （逐名 `export const` 才过 arch 的导出对账；解构导出它认不出）。
+ * @param options.name 插件名（包名）。
+ * @param options.unit 单元 id。
+ * @param options.face 这个单元的宿主面。
+ * @returns `{ name, inject, apply }`；`apply` 里取 `workbenchUnits`、缺了就 warn 一声。
+ */
+export declare function defineUnitHostPlugin(options: {
+    readonly name: string;
+    readonly unit: string;
+    readonly face: UnitModuleFace;
+}): UnitHostPlugin;

package/dist/host/unit-plugin.js

@@ -0,0 +1,25 @@
+import { UNITS_SERVICE } from '../config/constants.js';
+/**
+ * 把「宿主面注册进外壳」这段在每个模块里都一样的接线收成一份。
+ * 用法：先 `const plugin = defineUnitHostPlugin({ … })`，再逐个导出 `name` / `inject` / `apply`
+ * （逐名 `export const` 才过 arch 的导出对账；解构导出它认不出）。
+ * @param options.name 插件名（包名）。
+ * @param options.unit 单元 id。
+ * @param options.face 这个单元的宿主面。
+ * @returns `{ name, inject, apply }`；`apply` 里取 `workbenchUnits`、缺了就 warn 一声。
+ */
+export function defineUnitHostPlugin(options) {
+    const { name, unit, face } = options;
+    return {
+        name,
+        inject: [UNITS_SERVICE],
+        apply(ctx) {
+            const units = ctx.get(UNITS_SERVICE);
+            if (units === undefined) {
+                ctx.logger?.warn?.(`[${unit}] 外壳没有提供 workbenchUnits 服务：这个模块装不进来`);
+                return;
+            }
+            ctx.effect(() => units.register(face), `${name}: 注册 ${unit}`);
+        },
+    };
+}

package/dist/host/workspace-store.js

@@ -13,15 +13,21 @@ export 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)) {
+    if (trimmed.includes('\0') || path.isAbsolute(trimmed) || /^[A-Za-z]:[\\/]/.test(trimmed)) {
         throw new Error(`模块只能写自己的文件夹：不接受绝对路径「${name}」`);
     }
-    const full = path.resolve(dir, trimmed);
+    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}」`);
     }
@@ -32,15 +38,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(),

package/dist/host.d.ts

@@ -47,13 +47,16 @@ export * from './host/flow/expr.js';
 export * from './host/flow/check.js';
 export * from './host/flow/run.js';
 export * from './host/flow/kit.js';
+export * from './host/flow/step.js';
 export * from './host/host-kit.js';
 export * from './host/panel-state.js';
+export * from './host/payload.js';
 export * from './host/plugin-ledger.js';
 export * from './host/time.js';
 export * from './host/tokens.js';
 export * from './host/tool-approval.js';
 export * from './host/tool-kit.js';
+export * from './host/unit-plugin.js';
 export * from './host/unit-face.js';
 export * from './host/lib-runners.js';
 export * from './host/value-handoff.js';