dsh-config-manager 0.1.86 → 0.2.1

package/src/client/import/PathPickerDialog.tsx

@@ -0,0 +1,172 @@
+/**
+ * 本机路径选择弹窗（导入 → 路径映射 → 每条「新路径」右侧的文件夹按钮）。
+ *
+ * 为什么需要它
+ * ------------
+ * 路径映射要求用户给一堆**绝对路径**指定本机新位置，而浏览器拿不到真实路径
+ * （File System Access API 只给 handle，`<input type="file">` 只给文件名）。此前用户只能凭记忆
+ * 手打 `D:\\Apps\\nodejs\\node_global\\gitnexus.cmd` 这类字符串 —— 打错一位就等于「导不进」。
+ * 目录列举由宿主 `GET /path-browse` 提供（src/core/path-browse.ts，只读、有界），本组件只画界面。
+ *
+ * 交互约定
+ * --------
+ * - 点目录 = 进入；点文件 = 直接选中（原路径可能指向文件，如 .cmd / .json）；
+ * - 「使用当前目录」回填当前目录；「上一层」「主目录」是导航快捷入口；
+ * - 起点 `startPath` 若是文件或不存在，宿主会同时给出 `parent`，这里上浮一层再列（只自动上浮一次，
+ *   免得用户在空目录里被反复弹走）。
+ *
+ * 边界：组件不发请求做判断，不创建/改名/删除任何东西；错误码由字典翻译（引擎不产文案）。
+ */
+import { useEffect, useRef, useState } from 'react'
+import type { BrowseErrorCode, BrowseResult } from '../../core/path-browse.ts'
+import type { ConfigManagerApi } from '../api.ts'
+import type { TranslateNS } from '../client-types.ts'
+import { Modal } from '../common/Modal.tsx'
+import { Banner, Button, Spinner } from '../common/ui.tsx'
+import { FileIcon, FolderIcon } from '../common/Icon.tsx'
+import css from '../config-manager.module.css'
+
+/** 列举失败原因码 → 字典键（与 core 的 `BrowseErrorCode` 一一对应）。 */
+const BROWSE_ERROR_LABEL: Record<BrowseErrorCode, Parameters<TranslateNS<'config-manager'>>[0]> = {
+  'not-found': 'import.paths.picker.notFound',
+  denied: 'import.paths.picker.denied',
+  failed: 'import.paths.picker.failed',
+  'not-absolute': 'import.paths.picker.notAbsolute',
+}
+
+/** 列举状态机（加载中 / 有结果 / 传输失败）。 */
+type BrowseState =
+  | { kind: 'loading' }
+  | { kind: 'ready'; data: BrowseResult }
+  | { kind: 'failed'; detail: string }
+
+/**
+ * 只需要两个方法：内置浏览器列举 + 原生选择器（两者是**同一条**宿主端点的 GET / POST 形态）。
+ * 这样测试替身只碰这两个方法，其余 API 一概不进入组件视野。
+ * `pickDshPath`（DSH 宿主自带选择器）是可选能力：DSH 客户端总提供它，测试替身不必实现。
+ */
+export type PathBrowsePort = Pick<ConfigManagerApi, 'browsePath' | 'pickNativePath'> & {
+  pickDshPath?: ConfigManagerApi['pickDshPath']
+}
+
+export interface PathPickerDialogProps {
+  open: boolean
+  api: PathBrowsePort
+  t: TranslateNS<'config-manager'>
+  /** 起点：输入框现值（可能是文件、可能是别的机器的路径、可能为空） */
+  startPath: string
+  /** 选中（目录或文件）—— 由调用方回填输入框；本组件不自行关闭弹窗 */
+  onPick: (path: string) => void
+  onClose: () => void
+}
+
+/**
+ * 目录浏览弹窗：列一层目录，点目录进入、点文件选中。
+ */
+export function PathPickerDialog({ open, api, t, startPath, onPick, onClose }: PathPickerDialogProps) {
+  const [current, setCurrent] = useState<string | null>(null)
+  const [state, setState] = useState<BrowseState>({ kind: 'loading' })
+  // 自动上浮只做一次：记录已经为哪个起点上浮过（避免空目录/不存在路径来回弹）
+  const risenFor = useRef<string | null>(null)
+
+  const trimmedStart = startPath.trim()
+
+  // 打开时把起点落到当前目录（关闭状态下不动，避免清掉上次浏览位置造成闪烁）
+  useEffect(() => {
+    if (!open) return
+    risenFor.current = null
+    setCurrent(trimmedStart === '' ? null : trimmedStart)
+  }, [open, trimmedStart])
+
+  useEffect(() => {
+    if (!open) return
+    let alive = true
+    setState({ kind: 'loading' })
+    api.browsePath(current ?? undefined).then(
+      (data) => {
+        if (!alive) return
+        // 起点是文件或不存在：宿主给出的 parent 就是「该去哪」，上浮一层再列（一次性）
+        if (
+          data.error === 'not-found'
+          && data.path === trimmedStart
+          && data.parent !== null
+          && risenFor.current !== data.path
+        ) {
+          risenFor.current = data.path
+          setCurrent(data.parent)
+          return
+        }
+        setState({ kind: 'ready', data })
+      },
+      (error: unknown) => {
+        if (!alive) return
+        setState({ kind: 'failed', detail: error instanceof Error ? error.message : String(error) })
+      },
+    )
+    return () => { alive = false }
+  }, [open, current, trimmedStart, api])
+
+  const data = state.kind === 'ready' ? state.data : null
+  const atRoots = data !== null && data.path === ''
+  const canGoUp = data !== null && data.parent !== null
+  const pathLabel = atRoots ? t('import.paths.picker.thisPc') : (data?.path ?? trimmedStart)
+
+  return (
+    <Modal open={open} onClose={onClose} title={t('import.paths.picker.title')} wide>
+      <Modal.Header title={t('import.paths.picker.title')} onClose={onClose} closeLabel={t('common.close')} />
+      <Modal.Body scroll style={{ maxHeight: '56vh' }}>
+        <div className={css.pickerPath} title={pathLabel}>{pathLabel}</div>
+        {state.kind === 'loading' && <Spinner label={t('common.loading')} />}
+        {state.kind === 'failed' && <Banner kind="error">{state.detail}</Banner>}
+        {state.kind === 'ready' && (
+          <>
+            {state.data.error !== null && <Banner kind="warn">{t(BROWSE_ERROR_LABEL[state.data.error])}</Banner>}
+            {state.data.error === null && state.data.truncated && (
+              <Banner kind="info">{t('import.paths.picker.truncated', { count: String(state.data.entries.length) })}</Banner>
+            )}
+            {state.data.error === null && state.data.entries.length === 0 && (
+              <div className={css.empty}>{t('import.paths.picker.empty')}</div>
+            )}
+            {state.data.entries.length > 0 && (
+              <div className={css.pickerList}>
+                {state.data.entries.map((entry) => (
+                  <button
+                    key={entry.path}
+                    type="button"
+                    className={css.pickerRow}
+                    data-kind={entry.kind}
+                    title={entry.path}
+                    onClick={() => {
+                      if (entry.kind === 'dir') setCurrent(entry.path)
+                      else onPick(entry.path)
+                    }}
+                  >
+                    {entry.kind === 'dir' ? <FolderIcon size={14} /> : <FileIcon size={14} />}
+                    <span className={css.pickerName}>{entry.name}</span>
+                  </button>
+                ))}
+              </div>
+            )}
+          </>
+        )}
+      </Modal.Body>
+      <Modal.Footer>
+        <Button onClick={() => { if (data?.parent != null) setCurrent(data.parent) }} disabled={!canGoUp}>
+          {t('import.paths.picker.up')}
+        </Button>
+        <Button onClick={() => { if (data !== null) setCurrent(data.home) }} disabled={data === null}>
+          {t('import.paths.picker.home')}
+        </Button>
+        <Button onClick={onClose}>{t('common.cancel')}</Button>
+        {/* 根列表（「此电脑」）本身不是可映射目录：没有「当前目录」可回填 */}
+        <Button
+          variant="primary"
+          disabled={data === null || atRoots}
+          onClick={() => { if (data !== null) onPick(data.path) }}
+        >
+          {t('import.paths.picker.useCurrent')}
+        </Button>
+      </Modal.Footer>
+    </Modal>
+  )
+}

package/src/client/import/dsh-directory-pick.test.ts

@@ -0,0 +1,55 @@
+/**
+ * DSH 目录选择器解析层单测。
+ *
+ * 回归点（真机踩过的）：服务名是 `uiWorkspace`，不是 `workspaces` ——
+ * 只写 `workspaces` 时真机上永远取不到服务，于是「复用 DSH 自带选择器」根本没发生，
+ * 用户看到的一直是插件自己的对话框。这个文件钉住解析顺序与降级。
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { makeDshDirectoryPicker } from './dsh-directory-pick.ts';
+import type { DirectoryPickSources } from './dsh-directory-pick.ts';
+
+test('DSH-01 桌面全局优先：__DSH_DIRECTORY_PICKER__.pick 直接返回路径', async () => {
+  const calls: string[] = [];
+  const sources: DirectoryPickSources = {
+    desktop: { pick: async () => { calls.push('desktop'); return '/desktop/path' } },
+    getService: (name) => ({ pickDirectory: async () => { calls.push(name); return '/service/path' } }),
+  };
+  assert.equal(await makeDshDirectoryPicker(sources)(), '/desktop/path');
+  assert.deepEqual(calls, ['desktop'], '全局有就不该再碰服务');
+});
+
+test('DSH-02 服务名 uiWorkspace（真机口径）：即使 workspaces 不存在也必须成功', async () => {
+  const sources: DirectoryPickSources = {
+    getService: (name) => (name === 'uiWorkspace' ? { pickDirectory: async () => '/ws/path' } : undefined),
+  };
+  assert.equal(await makeDshDirectoryPicker(sources)(), '/ws/path');
+});
+
+test('DSH-03 老版本回退：只有 workspaces 时仍取得到', async () => {
+  const sources: DirectoryPickSources = {
+    getService: (name) => (name === 'workspaces' ? { pickDirectory: async () => '/legacy' } : undefined),
+  };
+  assert.equal(await makeDshDirectoryPicker(sources)(), '/legacy');
+});
+
+test('DSH-04 用户取消：服务返回 null 原样传出去（不是抛错）', async () => {
+  const sources: DirectoryPickSources = { getService: () => ({ pickDirectory: async () => null }) };
+  assert.equal(await makeDshDirectoryPicker(sources)(), null);
+});
+
+test('DSH-05 没有任何入口：抛错交给上层降级，绝不冒充「用户取消」', async () => {
+  await assert.rejects(makeDshDirectoryPicker({})(), /DSH directory picker unavailable/);
+  // 服务在但没有 pickDirectory（形态不符）同样算没有。
+  await assert.rejects(makeDshDirectoryPicker({ getService: () => ({ other: 1 }) })(), /unavailable/);
+});
+
+test('DSH-06 惰取：每次调用重新读服务，宿主重连后能拿到新实例', async () => {
+  let current: unknown = { pickDirectory: async () => '/first' };
+  const sources: DirectoryPickSources = { getService: () => current };
+  const pick = makeDshDirectoryPicker(sources);
+  assert.equal(await pick(), '/first');
+  current = { pickDirectory: async () => '/second' };
+  assert.equal(await pick(), '/second');
+});

package/src/client/import/dsh-directory-pick.ts

@@ -0,0 +1,55 @@
+/**
+ * DSH 自带目录选择器的解析层。
+ *
+ * 真机取证（DSH 0.2.1-rc.3，`resources/app.asar` 内）：
+ * - 桌面壳把原生选择器挂在全局：`globalThis.__DSH_DIRECTORY_PICKER__.pick(): Promise<string | null>`，
+ *   DSH 自己的 `@deepseek-ai/dsh-client-ui-directory-picker-native` 优先用它。
+ * - Web 侧走服务：`new UiWorkspaceService(...)` 里 `super(ctx, "uiWorkspace")`，
+ *   即服务名是 **uiWorkspace**（不是 workspaces），方法 `pickDirectory(): Promise<string | null>`。
+ *
+ * 这里只做「按优先级找一个能用的入口」，找不到就抛错交给上层降级：
+ * 上层顺序是 DSH 原生 → 插件自己的系统对话框 → 内置浏览器。
+ */
+
+/** 桌面壳全局选择器（Electron 侧注入；web 版本没有）。 */
+export interface DesktopDirectoryPicker {
+  pick?: () => Promise<string | null>
+}
+
+/** DSH 客户端服务里只要这个能力。 */
+export interface DirectoryPickService {
+  pickDirectory?: () => Promise<string | null>
+}
+
+/** 解析所需的两个来源（都可缺；测试直接注入替身）。 */
+export interface DirectoryPickSources {
+  /** `globalThis.__DSH_DIRECTORY_PICKER__` */
+  desktop?: DesktopDirectoryPicker | undefined
+  /** `ctx.get(name)`：服务名随 DSH 版本变，两个都试。 */
+  getService?: ((name: string) => unknown) | undefined
+}
+
+/** 服务名按 DSH 版本从新到旧：0.2.x = uiWorkspace，更早 = workspaces。 */
+const SERVICE_NAMES = ['uiWorkspace', 'workspaces'] as const
+
+function asService(value: unknown): DirectoryPickService | undefined {
+  if (typeof value !== 'object' || value === null) return undefined
+  const candidate = value as DirectoryPickService
+  return typeof candidate.pickDirectory === 'function' ? candidate : undefined
+}
+
+/**
+ * 造一个惰取 thunk：每次都重新读服务（宿主重连/服务重建后旧快照会失效）。
+ * 找不到任何入口就抛错 —— 调用方据此归成 `unavailable` 并降级，绝不静默当成「用户取消」。
+ */
+export function makeDshDirectoryPicker(sources: DirectoryPickSources): () => Promise<string | null> {
+  return async () => {
+    const desktop = sources.desktop
+    if (desktop !== undefined && typeof desktop.pick === 'function') return desktop.pick()
+    for (const name of SERVICE_NAMES) {
+      const service = asService(sources.getService?.(name))
+      if (service?.pickDirectory !== undefined) return service.pickDirectory()
+    }
+    throw new Error('config-manager: DSH directory picker unavailable')
+  }
+}

package/src/client/import/import-wizard-steps.tsx

@@ -12,6 +12,7 @@ import type { ImportAnalysis, PathMapping } from '../../core/types.ts'
 import type { ConsultReport } from '../../core/migration-consult.ts'
 import type { TranslateNS } from '../client-types.ts'
 import type { UiT } from '../../ui/i18n.ts'
+import type { PathBrowsePort } from './PathPickerDialog.tsx'
 import {
   Badge, Banner, Button, Card, Checkbox, Empty, SectionTitle,
 } from '../common/ui.tsx'
@@ -276,12 +277,14 @@ export function PathMappingStage(props: {
   onBack: () => void
   onNext: () => void
   t: TranslateNS<'config-manager'>
+  /** 「选择本机路径」弹窗的数据源（宿主只读列举端点） */
+  api: PathBrowsePort
 }) {
-  const { issues, mappings, onMappingsChange, onBack, onNext, t } = props
+  const { issues, mappings, onMappingsChange, onBack, onNext, t, api } = props
   return (
     <div className={css.viewBody}>
       <SectionTitle title={t('import.paths.title')} info={<InfoHint text={t('import.paths.hint')} label={t('common.infoHint')} />} />
-      <PathMappingForm issues={issues} initial={mappings} t={t} onChange={onMappingsChange} />
+      <PathMappingForm issues={issues} initial={mappings} t={t} onChange={onMappingsChange} api={api} />
       <div className={css.actionRow}>
         <Button variant="ghost" onClick={onBack}>{t('common.back')}</Button>
         <Button variant="primary" onClick={onNext}>{t('common.next')}</Button>

package/src/client/index.ts

@@ -21,6 +21,8 @@ import type {} from '@deepseek-ai/dsh-client-locale/client'
 import type {} from '@deepseek-ai/dsh-client-ui-settings/client'
 // Type-only：拉入 SlotMap / LocaleNamespaceMap 合并表（dsh-client-ui-slots）。
 import type {} from '@deepseek-ai/dsh-client-ui-slots'
+import { makeDshDirectoryPicker } from './import/dsh-directory-pick.ts'
+import type { DesktopDirectoryPicker } from './import/dsh-directory-pick.ts'
 import { ConfigManagerApi } from './api.ts'
 import { ConfigManagerSection } from './ConfigManagerSection.tsx'
 import { en, zh, type ConfigManagerKey } from './locales.ts'
@@ -136,7 +138,16 @@ export function apply(ctx: ClientContext): void {
   // 模块级单例（runStore 等）用同一个活源：它们没有调用方可以传 UiT。
   setUiLanguageSource(readLanguage)
   const uiT: UiT = makeLiveUiT(readLanguage)
-  const api = new ConfigManagerApi(uiT)
+  // DSH 自带的目录选择器（「选择工作区目录」那个原生窗口）：**点击那一刻**才读全局/服务，
+  // 装载期快照会在宿主重连/服务重建后失效。解析顺序与降级见 import/dsh-directory-pick.ts
+  // （真机取证：服务名是 uiWorkspace，不是 workspaces；桌面壳还会挂全局 __DSH_DIRECTORY_PICKER__）。
+  const pickDshDirectory = makeDshDirectoryPicker({
+    get desktop() {
+      return (globalThis as { __DSH_DIRECTORY_PICKER__?: DesktopDirectoryPicker }).__DSH_DIRECTORY_PICKER__
+    },
+    getService: (name) => ctx.get(name),
+  })
+  const api = new ConfigManagerApi(uiT, pickDshDirectory)
   const syncT = ctx.locale.bind(SYNC_NS)
   const syncApi = new SyncApi(uiT)
   const marketT = ctx.locale.bind(MARKET_NS)

package/src/client/locales.ts

@@ -289,6 +289,19 @@ export const zh = {
   'import.paths.kind.homeMismatch': '基础路径不同',
   'import.paths.unresolved': '还有 {count} 条路径未映射（留空将跳过该路径，可以继续）',
   'import.paths.empty': '无需映射路径',
+  // 「选择本机路径」弹窗（第③项）：浏览器拿不到本机真实路径，目录列举走宿主只读端点
+  'import.paths.browse': '选择本机路径',
+  'import.paths.picker.title': '选择本机路径',
+  'import.paths.picker.up': '上一层',
+  'import.paths.picker.home': '主目录',
+  'import.paths.picker.thisPc': '此电脑',
+  'import.paths.picker.useCurrent': '使用当前目录',
+  'import.paths.picker.empty': '这个目录里没有可进入的项',
+  'import.paths.picker.truncated': '只显示前 {count} 项',
+  'import.paths.picker.notFound': '这个路径不存在（已为你打开上一级）',
+  'import.paths.picker.denied': '没有读取这个目录的权限',
+  'import.paths.picker.notAbsolute': '请填绝对路径（如 D:\\ 或 /）',
+  'import.paths.picker.failed': '读取这个目录失败',
   // —— 快照恢复 ——
   'home.schedule.title': '定时备份',
   'snapshots.selectHint': '选择快照以预览恢复计划（只读预览，不会改动任何设置）：',
@@ -1160,6 +1173,18 @@ export const en: Record<keyof typeof zh, string> = {
   'import.paths.kind.homeMismatch': 'Different base path',
   'import.paths.unresolved': '{count} path(s) unmapped (blank = skip that path, you can continue)',
   'import.paths.empty': 'No paths to map',
+  'import.paths.browse': 'Choose a local path',
+  'import.paths.picker.title': 'Choose a local path',
+  'import.paths.picker.up': 'Up one level',
+  'import.paths.picker.home': 'Home folder',
+  'import.paths.picker.thisPc': 'This PC',
+  'import.paths.picker.useCurrent': 'Use this folder',
+  'import.paths.picker.empty': 'Nothing to open in this folder',
+  'import.paths.picker.truncated': 'Showing the first {count} entries',
+  'import.paths.picker.notFound': 'That path does not exist (opened its parent instead)',
+  'import.paths.picker.denied': 'No permission to read this folder',
+  'import.paths.picker.notAbsolute': 'Enter an absolute path (e.g. D:\\ or /)',
+  'import.paths.picker.failed': 'Could not read this folder',
   'home.schedule.title': 'Schedule',
   'snapshots.selectHint': 'Select a snapshot to preview its restore plan (read-only preview, changes nothing):',
   'snapshots.status': 'Status',

package/src/client/lucide-icons.d.ts

@@ -29,6 +29,8 @@ declare module 'lucide-react/dist/esm/icons/download.mjs' { const i: LucideIconC
 declare module 'lucide-react/dist/esm/icons/eye.mjs' { const i: LucideIconComponent; export default i }
 declare module 'lucide-react/dist/esm/icons/file.mjs' { const i: LucideIconComponent; export default i }
 declare module 'lucide-react/dist/esm/icons/folder-input.mjs' { const i: LucideIconComponent; export default i }
+declare module 'lucide-react/dist/esm/icons/folder.mjs' { const i: LucideIconComponent; export default i }
+declare module 'lucide-react/dist/esm/icons/folder-open.mjs' { const i: LucideIconComponent; export default i }
 declare module 'lucide-react/dist/esm/icons/hard-drive-download.mjs' { const i: LucideIconComponent; export default i }
 declare module 'lucide-react/dist/esm/icons/history.mjs' { const i: LucideIconComponent; export default i }
 declare module 'lucide-react/dist/esm/icons/info.mjs' { const i: LucideIconComponent; export default i }

package/src/client/sync/SyncPanel.tsx

@@ -74,7 +74,7 @@ import type {
 import {
   buildSelectionRequest, buildSyncChannelBody, buildSyncConfigBody, buildSyncPushBody,
   channelBackfillFromStatus, channelRemoteReady, cloudFormFromStatus, computeEncryptInvalid, encryptToggle,
-  githubPollDecision, hasSelectedSections, includeSecretsToggle, isGithubFlowInFlight, resolveInitialChannel,
+  githubPollDecision, hasSelectedSections, includeSecretsToggle, isGithubFlowInFlight, pickSyncPrimary, resolveInitialChannel,
   needsSessionInventory, saveQueueOnFlush, saveQueueOnRequest, saveQueueOnSettled, toggleSectionSelection,
   validateCloudForm, DEFAULT_S3_PROVIDER,
   SYNC_CONFIG_SAVE_DEBOUNCE_MS,
@@ -1261,10 +1261,10 @@ export function SyncPanel({ api, t, cmT }: SyncPanelProps) {
         {ready && (
           <Card>
             {/* 动作行（方案 A 定案）：用户只面对两个方向 —— 下行「一键同步」/ 上行「推送到远端」。
-                合并裁决并入一键同步（有基线走三方裁决视图、无基线走老导入确认），不再单独占按钮。 */}
+                合并裁决并入一键同步（有基线走三方裁决视图、无基线走老导入确认）；并排两个按钮看不出该按哪个（issue 115）⇒ 按已确证远端事实只让一个落在 primary。 */}
             <div className={css.actionRow}>
               <Button
-                variant="primary"
+                variant={pickSyncPrimary(state.statusInfo, channel) === 'sync' ? 'primary' : 'ghost'}
                 disabled={busy}
                 loading={state.busy === 'sync'}
                 onClick={() => { void runSyncSmart(channel) }}
@@ -1273,7 +1273,7 @@ export function SyncPanel({ api, t, cmT }: SyncPanelProps) {
                   ? (syncPhase === 'preview' ? t('syncflow.checkingRemote') : t('syncflow.syncing'))
                   : t('syncflow.button')}
               </Button>
-              <Button disabled={!computeSyncButtons(state.busy, ready, uiT).canPush || githubBusy || !hasSelectedSections(cs) || computeEncryptInvalid(cs)} onClick={() => { switchChannel(channel); void runPushPreview() }}>
+              <Button variant={pickSyncPrimary(state.statusInfo, channel) === 'push' ? 'primary' : 'ghost'} disabled={!computeSyncButtons(state.busy, ready, uiT).canPush || githubBusy || !hasSelectedSections(cs) || computeEncryptInvalid(cs)} onClick={() => { switchChannel(channel); void runPushPreview() }}>
                 {computeSyncButtons(state.busy, ready, uiT).pushLabel}
               </Button>
               {/* 测试连接（只读自检）：与两个主操作同一行、排在最后；结果走 toast（不再占页面高度） */}

package/src/client/sync/sync-view.ts

@@ -294,7 +294,7 @@ export function cloudIssueKey(code: string): SyncKey | null {
 /* ------------------------------------------------ G-34：gist 通道不适合大分区 */
 
 /**
- * G-34（docs/spec/known-gaps.md）：gist 通道**刻意不做内容寻址外置** —— 一次 GET 把全部
+ * G-34（docs/maintenance/known-gaps.md）：gist 通道**刻意不做内容寻址外置** —— 一次 GET 把全部
  * 文件内容取回、单文件内容超限会被截断、文件数还有上限，因此会话这类大分区不适合走 gist。
  *
  * 本常量 = 「gist 表单」常驻提示的字典键（组件按它取 sync 字典文案渲染 hint）。

package/src/core/native-path-picker.test.ts

@@ -0,0 +1,118 @@
+/**
+ * 原生目录选择器的调度逻辑单测（不弹窗、不 spawn 真进程：全部走注入的 spawner）。
+ *
+ * 真机那半（PowerShell 的 IFileOpenDialog 到底能不能弹出来）无法在无头测试里断言，
+ * 由方案的 `Probe` 自检 + 人工目测覆盖；本文件只钉住**我们自己的**判断逻辑：
+ * 三态区分（ok / canceled / unsupported·failed）、取消不当错误、能力缺失必须回落、
+ * 起始路径与标题经环境变量传递、以及路径归一化不毁掉盘符根。
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  PICK_ENV_START,
+  PICK_ENV_TITLE,
+  defaultSpawner,
+  pickNativeDirectory,
+} from './native-path-picker.ts';
+import type { NativePickExec, NativePickRun } from './native-path-picker.ts';
+
+/** 造一个 spawner：按调用顺序吐出预设结果，并记录每次 run（便于断言 argv/env）。 */
+function scripted(results: Partial<NativePickExec>[]): { spawner: (run: NativePickRun) => Promise<NativePickExec>; runs: NativePickRun[] } {
+  const runs: NativePickRun[] = [];
+  let index = 0;
+  return {
+    runs,
+    spawner: async (run) => {
+      runs.push(run);
+      const preset = results[index] ?? {};
+      index += 1;
+      return { code: 0, stdout: '', stderr: '', missing: false, ...preset };
+    },
+  };
+}
+
+test('win32：选中路径 → ok，且起始路径/标题走环境变量而不是命令行', async () => {
+  const { spawner, runs } = scripted([{ code: 0, stdout: 'D:\\Projects\\picked\\\r\n' }]);
+  const result = await pickNativeDirectory({ platform: 'win32', startPath: 'D:\\Projects', title: '选择本机路径', spawner });
+  assert.deepEqual(result, { ok: true, path: 'D:\\Projects\\picked' });
+  const run = runs[0];
+  assert.ok(run !== undefined);
+  assert.equal(run.file, 'powershell');
+  // -STA 必须在：PowerShell 7 默认 MTA，COM 模态窗口会直接失败。
+  assert.ok(run.args.includes('-STA'));
+  assert.equal(run.env[PICK_ENV_START], 'D:\\Projects');
+  assert.equal(run.env[PICK_ENV_TITLE], '选择本机路径');
+  // 用户给的字符串绝不进 argv（否则就等于拼进脚本了）。
+  assert.ok(!run.args.some((arg) => arg.includes('picked') || arg.includes('选择本机路径')));
+});
+
+test('win32：退出码 2（用户取消）→ canceled，不是失败', async () => {
+  const { spawner } = scripted([{ code: 2 }]);
+  assert.deepEqual(await pickNativeDirectory({ platform: 'win32', spawner }), { ok: false, reason: 'canceled' });
+});
+
+test('win32：HRESULT 错误 → failed 并带回 detail', async () => {
+  const { spawner } = scripted([{ code: 3, stderr: 'ERR:-2147024809\r\n' }]);
+  const result = await pickNativeDirectory({ platform: 'win32', spawner });
+  assert.deepEqual(result, { ok: false, reason: 'failed', detail: 'ERR:-2147024809' });
+});
+
+test('win32：powershell 不存在 → unsupported（客户端回落内置浏览器）', async () => {
+  const { spawner } = scripted([{ missing: true, code: null }]);
+  const result = await pickNativeDirectory({ platform: 'win32', spawner });
+  assert.equal(result.ok, false);
+  assert.equal(result.ok === false ? result.reason : '', 'unsupported');
+});
+
+test('win32：空 stdout 当作取消处理（窗口关了但没给路径）', async () => {
+  const { spawner } = scripted([{ code: 0, stdout: '  \r\n' }]);
+  assert.deepEqual(await pickNativeDirectory({ platform: 'win32', spawner }), { ok: false, reason: 'canceled' });
+});
+
+test('win32：盘符根与 POSIX 根的原样保留 / 常规尾部反斜杠剥离', async () => {
+  for (const [stdout, expected] of [
+    ['D:\\\r\n', 'D:\\'],
+    ['D:\\Apps\\nodejs\\\r\n', 'D:\\Apps\\nodejs'],
+    ['/home/me/docs/\r\n', '/home/me/docs'],
+    ['/\r\n', '/'],
+  ] as const) {
+    const { spawner } = scripted([{ code: 0, stdout }]);
+    const result = await pickNativeDirectory({ platform: 'win32', spawner });
+    assert.deepEqual(result, { ok: true, path: expected }, `归一化 ${JSON.stringify(stdout)} 期望 ${expected}`);
+  }
+});
+
+test('darwin：osascript 选中 → ok；取消（-128 / 退出码 1）→ canceled', async () => {
+  const ok = scripted([{ code: 0, stdout: '/Users/me/Documents\n' }]);
+  assert.deepEqual(await pickNativeDirectory({ platform: 'darwin', spawner: ok.spawner }), { ok: true, path: '/Users/me/Documents' });
+  assert.equal(ok.runs[0]?.file, 'osascript');
+
+  const canceled = scripted([{ code: 0, stderr: 'execution error: User canceled. (-128)\n' }]);
+  assert.deepEqual(await pickNativeDirectory({ platform: 'darwin', spawner: canceled.spawner }), { ok: false, reason: 'canceled' });
+});
+
+test('linux：zenity 缺失时自动换 kdialog；两个都没有 → unsupported', async () => {
+  const fallback = scripted([{ missing: true, code: null }, { code: 0, stdout: '/home/me\n' }]);
+  assert.deepEqual(await pickNativeDirectory({ platform: 'linux', startPath: '/home', spawner: fallback.spawner }), { ok: true, path: '/home/me' });
+  assert.equal(fallback.runs[0]?.file, 'zenity');
+  assert.equal(fallback.runs[1]?.file, 'kdialog');
+
+  const none = scripted([{ missing: true, code: null }, { missing: true, code: null }]);
+  const result = await pickNativeDirectory({ platform: 'linux', spawner: none.spawner });
+  assert.equal(result.ok === false ? result.reason : '', 'unsupported');
+});
+
+test('其他平台：直接 unsupported，且根本不 spawn', async () => {
+  const { spawner, runs } = scripted([]);
+  const result = await pickNativeDirectory({ platform: 'freebsd', spawner });
+  assert.equal(result.ok === false ? result.reason : '', 'unsupported');
+  assert.equal(runs.length, 0);
+});
+
+test('defaultSpawner：超时也保留子进程已经吐出的 stderr（排障线索不能丢）', async () => {
+  const script = 'process.stderr.write("boom\\n"); setTimeout(() => {}, 10000)';
+  const exec = await defaultSpawner({ file: process.execPath, args: ['-e', script], env: {}, timeoutMs: 400 });
+  assert.equal(exec.code, null);
+  assert.match(exec.stderr, /timed out/);
+  assert.match(exec.stderr, /boom/);
+});