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

package/src/host/__tests__/shell-text.test.ts

@@ -1,6 +1,6 @@
 import { execFileSync } from 'node:child_process';
 import { describe, expect, it } from 'vitest';
-import { quoteShellArg, quoteShellArgFor, tailLines } from '../shell-text.js';
+import { quoteShellArg, quoteShellArgFor, shellKindOf, tailLines } from '../shell-text.js';
 
 function shellSees(value: string): string {
   return execFileSync('/bin/sh', ['-c', `printf '%s' ${quoteShellArg(value)}`], {
@@ -8,7 +8,7 @@ function shellSees(value: string): string {
   });
 }
 
-describe('quoteShellArg', () => {
+describe.skipIf(process.platform === 'win32')('quoteShellArg（POSIX /bin/sh）', () => {
   it('普通值原样往返', () => {
     expect(shellSees('example-monorepo')).toBe('example-monorepo');
   });
@@ -45,15 +45,40 @@ describe('tailLines', () => {
 
 
 describe('quoteShellArgFor', () => {
-  it('win32 用双引号，路径里的空格原样保留', () => {
-    expect(quoteShellArgFor('C:\\Program Files\\dsh\\x.cjs', 'win32')).toBe('"C:\\Program Files\\dsh\\x.cjs"');
+  it('★ win32 按 pwsh 的字面量走：单引号，路径里的空格与反斜杠都原样', () => {
+    expect(quoteShellArgFor('C:\\Program Files\\dsh\\x.cjs', 'win32')).toBe("'C:\\Program Files\\dsh\\x.cjs'");
   });
 
-  it('win32 里值自身的双引号被转义', () => {
-    expect(quoteShellArgFor('a"b', 'win32')).toBe('"a\\"b"');
+  it('★ pwsh 里值自身的单引号按双写逃逸（不是 POSIX 那套反斜杠）', () => {
+    expect(quoteShellArgFor("it's", 'win32')).toBe("'it''s'");
   });
 
-  it('POSIX 仍用单引号', () => {
+  it('★ pwsh 里 $ 与双引号不再被当成语法（单引号内是字面量）', () => {
+    expect(quoteShellArgFor('a$b"c', 'win32')).toBe(`'a$b"c'`);
+  });
+
+  it('POSIX 仍用单引号加反斜杠逃逸', () => {
     expect(quoteShellArgFor("it's", 'darwin')).toBe("'it'\\''s'");
   });
 });
+
+describe.skipIf(process.platform !== 'win32')('quoteShellArg（Windows pwsh）', () => {
+  it('经真 pwsh 解析后原样往返', { timeout: 30000 }, () => {
+    for (const raw of ["it's", '$HOME', 'a;b', 'a && b']) {
+      const out = execFileSync(
+        'pwsh',
+        ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', `[Console]::Out.Write(${quoteShellArg(raw)})`],
+        { encoding: 'utf8' },
+      );
+      expect(out, raw).toBe(raw);
+    }
+  });
+});
+
+describe('shellKindOf', () => {
+  it('win32 是 pwsh，其余是 POSIX', () => {
+    expect(shellKindOf('win32')).toBe('pwsh');
+    expect(shellKindOf('darwin')).toBe('posix');
+    expect(shellKindOf('linux')).toBe('posix');
+  });
+});

package/src/host/__tests__/shell.test.ts

@@ -57,6 +57,30 @@ describe('runShell', () => {
     expect(result.stalled).toBe(false);
   });
 
+  it('★ env 走 resolve 的覆盖字段，不拼进命令行的 shell 语法', async () => {
+    const seen: Array<Record<string, unknown>> = [];
+    const shell: DshShell = {
+      resolve: (request) => {
+        seen.push(request as unknown as Record<string, unknown>);
+        return request;
+      },
+      execute: async () => ({
+        result: async () => ({
+          exitCode: 0,
+          timedOut: false,
+          aborted: false,
+          stdout: { text: '', truncated: false },
+          stderr: { text: '', truncated: false },
+        }),
+      }),
+    };
+
+    await runShell(shell, 'node --version', { env: { OPENCLI_WINDOW: 'background' } });
+
+    expect(seen[0]?.command).toBe('node --version');
+    expect(seen[0]?.env).toEqual({ OPENCLI_WINDOW: 'background' });
+  });
+
   it('★ 宿主自己抛错 → 照旧抛出去，不吞成 stalled', async () => {
     const shell: DshShell = {
       resolve: (request) => request,

package/src/host/data-root.ts

@@ -1,15 +1,18 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
 export function dshHome(): string {
   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(): string {
   const configured = process.env.DSH_WORKBENCH_HOME?.trim();
   if (configured !== undefined && configured !== '') return configured;
-  return `${dshHome()}/workbench`;
+  return join(dshHome(), 'workbench');
 }
 
 export function workspacesRoot(): string {
-  return `${workbenchRoot()}/workspaces`;
+  return join(workbenchRoot(), 'workspaces');
 }

package/src/host/flow/__tests__/step.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+
+import type { FlowStepEvent } from '../types.js';
+import { longTaskStepOf } from '../step.js';
+
+const eventOf = (status: FlowStepEvent['status'], extra: Partial<FlowStepEvent> = {}): FlowStepEvent => ({
+  stepId: 'read',
+  title: '读目录',
+  status,
+  ...extra,
+});
+
+describe('longTaskStepOf：流程事件 → 长任务步骤的默认映射', () => {
+  it('running 记成 start，文字用 title', () => {
+    expect(longTaskStepOf(eventOf('running'))).toEqual({ kind: 'start', text: '读目录' });
+  });
+
+  it('ok 记成 succeed', () => {
+    expect(longTaskStepOf(eventOf('ok'))).toEqual({ kind: 'succeed', text: '读目录' });
+  });
+
+  it('skipped 记成 info', () => {
+    expect(longTaskStepOf(eventOf('skipped'))).toEqual({ kind: 'info', text: '读目录' });
+  });
+
+  it('failed 记成 fail', () => {
+    expect(longTaskStepOf(eventOf('failed'))).toEqual({ kind: 'fail', text: '读目录' });
+  });
+
+  it('needs-login 带 loginUrl', () => {
+    expect(longTaskStepOf(eventOf('needs-login', { loginUrl: 'https://example.com/login' }))).toEqual({
+      kind: 'info',
+      text: '读目录',
+      loginUrl: 'https://example.com/login',
+    });
+  });
+
+  it('message 盖过 title；没有 loginUrl 就不带那个键', () => {
+    const step = longTaskStepOf(eventOf('running', { message: '正在读' }));
+    expect(step).toEqual({ kind: 'start', text: '正在读' });
+    expect('loginUrl' in step).toBe(false);
+  });
+});

package/src/host/flow/step.ts

@@ -0,0 +1,21 @@
+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 function longTaskStepOf(event: FlowStepEvent): LongTaskStep {
+  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/src/host/host-kit.ts

@@ -1,26 +1,34 @@
+import type { HostSurface } from '../contract/protocol/platform.js';
 import type { EnvSupplyPort } from './port-types.js';
 import { createFlowHost, 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 function createHostKit(parts: { readonly libInstallCommand: EnvSupplyPort['libInstallCommand'] }): HostKit {
+export function createHostKit(parts: {
+  readonly libInstallCommand: EnvSupplyPort['libInstallCommand'];
+  readonly surface: HostSurface;
+}): HostKit {
   return {
     flow: createFlowHost(),
     sessionIdOf,
     sessionWorkspace,
     libInstallCommand: parts.libInstallCommand,
+    surface: parts.surface,
   };
 }

package/src/host/install-failure.ts

@@ -4,7 +4,7 @@ import type { InstallFailure, InstallFailureKind } from '../contract/command.js'
 
 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;
 

package/src/host/lib-install.ts

@@ -12,13 +12,15 @@ export function libInstallCommand(options: {
   readonly env?: NodeJS.ProcessEnv | undefined;
   readonly prefix: string;
   readonly cacheDir?: string | undefined;
+  readonly pnpm?: string | undefined;
 }): string {
   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(
@@ -52,5 +54,5 @@ export function binInstallCommand(
 }
 
 export function libUninstallCommand(options: { readonly need: LibNeed; readonly prefix: string }): string {
-  return `npm uninstall --prefix ${quoteShellArg(options.prefix)} ${quoteShellArg(options.need.name)}`;
+  return `pnpm remove --dir ${quoteShellArg(options.prefix)} ${quoteShellArg(options.need.name)}`;
 }

package/src/host/paths.ts

@@ -1,3 +1,4 @@
+import { join } from 'node:path';
 import { workbenchRoot } from './data-root.js';
 
 export interface RuntimeLayout {
@@ -11,20 +12,20 @@ export interface RuntimeLayout {
 }
 
 export function runtimeRootOf(id: string): string {
-  return `${workbenchRoot()}/${id}`;
+  return join(workbenchRoot(), id);
 }
 
 export function runtimeLayoutOf(id: string): RuntimeLayout {
   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/src/host/payload.ts

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

package/src/host/preflight.ts

@@ -11,6 +11,7 @@ export interface PreflightStep {
   readonly detail?: string;
   readonly action?: string;
   readonly command?: string;
+  readonly log?: readonly string[];
 }
 
 export interface PreflightDiyGap {
@@ -29,4 +30,5 @@ export interface PreflightSnapshot {
   readonly bridgeIssues?: readonly PreflightBridgeIssue[];
   readonly diyGap?: PreflightDiyGap;
   readonly canWakeBrowser?: boolean;
+  readonly log?: readonly string[];
 }

package/src/host/shell-text.ts

@@ -1,12 +1,26 @@
 /**
- * 按目标平台把一个值裹成 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 function shellKindOf(platform: NodeJS.Platform = process.platform): ShellKind {
+  return platform === 'win32' ? 'pwsh' : 'posix';
+}
+
+/**
+ * 按目标平台把一个值裹成 shell 字面量：POSIX 用单引号并按 `'\''` 逃逸，pwsh 也用单引号但按 `''` 逃逸。
  * @param value - 任意值；不是字符串的先 `String()`。
  * @param platform - 目标平台，默认当前 `process.platform`。
  * @returns 可安全拼进该平台 shell 命令的一段文本；含空格 / 元字符的值不会被当成语法。
  */
 export function quoteShellArgFor(value: unknown, platform: NodeJS.Platform = process.platform): string {
   const text = String(value);
-  if (platform === 'win32') return `"${text.replace(/"/g, '\\"')}"`;
+  if (shellKindOf(platform) === 'pwsh') return `'${text.replace(/'/g, "''")}'`;
   return `'${text.replace(/'/g, `'\\''`)}'`;
 }
 

package/src/host/shell.ts

@@ -42,9 +42,14 @@ async function settleWithin<T>(work: Promise<T>, limitMs: number): Promise<T | n
 export async function runShell(
   shell: DshShell,
   command: string,
-  options: { workdir?: string; timeoutMs?: number; signal?: AbortSignal } = {},
+  options: {
+    workdir?: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    env?: Readonly<Record<string, string>>;
+  } = {},
 ): Promise<ShellResult> {
-  const { workdir, timeoutMs = GIT_TIMEOUT_MS, signal } = options;
+  const { workdir, timeoutMs = GIT_TIMEOUT_MS, signal, env } = options;
 
   const spec = shell.resolve({
     command,
@@ -53,6 +58,7 @@ export async function runShell(
     onExpiry: 'kill',
     stdoutMaxBytes: DEFAULT_MAX_BYTES,
     ...(signal === undefined ? {} : { signal }),
+    ...(env === undefined ? {} : { env }),
   });
 
   const settled = await settleWithin(

package/src/host/tool-approval.ts

@@ -181,3 +181,34 @@ export async function approvalFor(
     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: {
+  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;
+} {
+  const tools = new Set(options.tools);
+  const named = (call: ApprovalCall): boolean => 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/src/host/unit-face.ts

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

package/src/host/unit-plugin.ts

@@ -0,0 +1,49 @@
+import { UNITS_SERVICE } from '../config/constants.js';
+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 function defineUnitHostPlugin(options: {
+  readonly name: string;
+  readonly unit: string;
+  readonly face: UnitModuleFace;
+}): UnitHostPlugin {
+  const { name, unit, face } = options;
+  return {
+    name,
+    inject: [UNITS_SERVICE],
+    apply(ctx: UnitHostContextLike): void {
+      const units = ctx.get<{ register(face: UnitModuleFace): () => void }>(UNITS_SERVICE);
+      if (units === undefined) {
+        ctx.logger?.warn?.(`[${unit}] 外壳没有提供 workbenchUnits 服务：这个模块装不进来`);
+        return;
+      }
+      ctx.effect(() => units.register(face), `${name}: 注册 ${unit}`);
+    },
+  };
+}

package/src/host/workspace-store.ts

@@ -30,15 +30,22 @@ export function workspaceKey(workspace: string): string {
   return `${slug(path.basename(abs))}-${createHash('sha1').update(abs).digest('hex').slice(0, 8)}`;
 }
 
-function inside(dir: string, name: string): string {
+function safeName(name: string): string {
   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: string, name: string): string {
+  const full = path.resolve(dir, safeName(name));
   if (full !== dir && !full.startsWith(dir + path.sep)) {
     throw new Error(`模块只能写自己的文件夹：路径越界「${name}」`);
   }
@@ -50,15 +57,15 @@ function memoryStore(dir: string): ModuleStore {
   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/src/host.ts

@@ -57,13 +57,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';

package/src/i18n/en.ts

@@ -621,6 +621,7 @@ export const en: Record<keyof WorkbenchMessages, string> = {
   'env.fix.permission': 'Permission denied: rerun with sudo, or point npm\u2019s global directory at your home.',
   'env.fix.network': 'Network unreachable: check your network or proxy, then retry.',
   'env.fix.details': 'Details (for troubleshooting)',
+  'env.log': 'Detailed output',
   'env.retry': 'Retry',
   'env.wake': 'Open browser',
   'env.wake.opening': 'Opening the browser…',

package/src/i18n/zh.ts

@@ -617,6 +617,7 @@ export const zh = {
   'env.fix.permission': '权限不够：在命令前加 sudo 重跑，或先把 npm 的全局目录配到你的用户目录。',
   'env.fix.network': '网络不通：检查网络或代理设置后重试。',
   'env.fix.details': '详细输出（排障用）',
+  'env.log': '详细输出',
   'env.retry': '重试',
   'env.wake': '打开浏览器',
   'env.wake.opening': '正在打开浏览器…',

package/src/lib/__tests__/board-fact.test.ts

@@ -51,4 +51,12 @@ describe('干不了活是为什么：先看人在不在工坊，再看板画没
     expect(insideWorkshop('/a/b', '/a/bc')).toBe(false);
     expect(insideWorkshop('/a/b/', '/a/b/c')).toBe(true);
   });
+
+  it('★ Windows 路径：反斜杠、混合分隔符与盘符大小写都认', () => {
+    expect(insideWorkshop('C:\\w\\ws', 'C:\\w\\ws\\packages\\module-demo')).toBe(true);
+    expect(insideWorkshop('C:\\w\\ws', 'C:/w/ws/packages/module-demo')).toBe(true);
+    expect(insideWorkshop('c:\\w\\ws', 'C:\\W\\WS\\packages')).toBe(true);
+    expect(insideWorkshop('C:\\w\\ws', 'C:\\w\\ws2')).toBe(false);
+    expect(insideWorkshop('C:\\w\\ws', 'D:\\w\\ws\\packages')).toBe(false);
+  });
 });

package/src/lib/__tests__/ui.test.ts

@@ -3,6 +3,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import {
   cx,
   parseLocalTimestamp,
+  pathBase,
   relativeTime,
   relativeTimeAgo,
   relativeTimeBucket,
@@ -112,8 +113,14 @@ describe('shortenPath', () => {
     expect(shortenPath('/Users/you/dev/app')).toBe('~/dev/app');
   });
 
+  it('Linux 与 Windows 的用户主目录也缩', () => {
+    expect(shortenPath('/home/you/dev/app')).toBe('~/dev/app');
+    expect(shortenPath('C:\\Users\\you\\dev\\app')).toBe('~\\dev\\app');
+  });
+
   it('非用户目录原样返回', () => {
     expect(shortenPath('/Volumes/dev/app')).toBe('/Volumes/dev/app');
+    expect(shortenPath('D:\\work\\app')).toBe('D:\\work\\app');
   });
 
   it('非字符串给空串', () => {
@@ -122,6 +129,25 @@ describe('shortenPath', () => {
   });
 });
 
+describe('pathBase', () => {
+  it('取最后一段，POSIX 与 Windows 都认', () => {
+    expect(pathBase('/Users/you/dev/app')).toBe('app');
+    expect(pathBase('C:\\Users\\you\\dev\\app')).toBe('app');
+    expect(pathBase('C:/Users/you/dev/app')).toBe('app');
+  });
+
+  it('尾部有分隔符先去掉', () => {
+    expect(pathBase('/Users/you/dev/app/')).toBe('app');
+    expect(pathBase('C:\\Users\\you\\dev\\app\\')).toBe('app');
+  });
+
+  it('没有分隔符就整串，非字符串给空串', () => {
+    expect(pathBase('app')).toBe('app');
+    expect(pathBase(undefined)).toBe('');
+    expect(pathBase(42)).toBe('');
+  });
+});
+
 describe('parseLocalTimestamp', () => {
   it('按本地时区解析 Coding 的时间戳形态', () => {
     const parsed = parseLocalTimestamp('2026-09-27 08:18:36');

package/src/lib/board-fact.ts

@@ -29,16 +29,23 @@ export interface BoardProbe {
   readonly drawn: boolean;
 }
 
+function normalizePath(value: string): string {
+  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`）。
  */
 export function insideWorkshop(root: string, target: string): boolean {
-  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}/`);
 }
 
 /**