dsh-wsl-desktop 0.6.0 → 0.7.1

package/README.en.md

@@ -133,6 +133,10 @@ These are real boundaries, not a disclaimer list. Each one tells you where to re
   the whitelisted params, never the host message, stderr or resolved paths; after the user is
   confirmed, the W dialog shows an advisory health check whose failed rows carry the fix. Codes,
   checks and degradation are in [Diagnostics](docs/DIAGNOSTICS.md).
+- **The W dialog is bilingual and keyboard-contained.** Copy follows `navigator.language` between
+  Chinese and English; the dialog traps Tab, closes on Escape and returns focus to the W button,
+  and copy feedback goes through a screen-reader live region. Details in
+  [Diagnostics](docs/DIAGNOSTICS.md#copy-language).
 - **Who it is for.** For now it suits the plugin author or an operator of the same trust level, for
   long-term use. Distribution to third-party users, or unattended high-value environments, are not
   suitable yet — the reasoning is in [SECURITY.md](SECURITY.md).
@@ -151,6 +155,7 @@ These are real boundaries, not a disclaimer list. Each one tells you where to re
 - [Diagnostics](docs/DIAGNOSTICS.md) — error codes, the health check, degradation and the privacy boundary
 - [Engineering notes](docs/ENGINEERING-NOTES.md) — measured constraints, repository layout, release flow, install shape
 - [Distro support matrix](docs/DISTRO-SUPPORT.md) — which distros were verified, and what each one needs
+- [Compatibility and upgrades](docs/COMPATIBILITY.md) — plugin/desktop version relation, upgrade order, rollback steps
 - [Upstream API proposals](docs/UPSTREAM-PROPOSALS.md) — the two proposals to the harness upstream
 - [Architecture and flow diagrams](docs/diagrams.md) — interactive architecture, sequence and lifecycle diagrams
 

package/README.md

@@ -108,6 +108,9 @@ plugin_manager install_bundle dsh-wsl-desktop@<version>
 - **失败现在带 code，可以先自己诊断。** 浏览器侧的错误只回稳定 code 与允许的 params，
   宿主 message、stderr 与解析后的路径不会过线；W 对话框在确认用户后会显示一条建议性的
   「环境检查」，失败项带修复命令。错误码、检查项与降级行为见 [诊断](docs/DIAGNOSTICS.md)。
+- **W 对话框是双语的，键盘也关得住。** 文案按 `navigator.language` 在中英文之间选择；对话框有
+  Tab 焦点陷阱、Escape 关闭并把焦点还给 W 按钮，复制反馈走读屏实时区。细节见
+  [诊断](docs/DIAGNOSTICS.md#文案语言)。
 - **适合谁用。** 目前适合插件作者本人或同信任级别的操作者长期使用。分发给第三方用户、或放进
   无人值守的高价值环境，都还不适合——理由写在 [SECURITY.md](SECURITY.md)。
 
@@ -125,6 +128,7 @@ plugin_manager install_bundle dsh-wsl-desktop@<version>
 - [诊断](docs/DIAGNOSTICS.md) — 错误码、环境检查、宿主能力缺失时的降级与隐私边界
 - [工程笔记](docs/ENGINEERING-NOTES.md) — 实测约束、仓库布局、发版流程、安装形态
 - [发行版支持矩阵](docs/DISTRO-SUPPORT.md) — 哪些发行版验证过，每种缺什么
+- [兼容性与升级](docs/COMPATIBILITY.md) — 插件与桌面的版本关系、升级顺序、回退步骤
 - [上游 API 提案](docs/UPSTREAM-PROPOSALS.md) — 对 harness 上游的两项提案
 - [架构与流程图](docs/diagrams.md) — 可交互的架构、时序与生命周期图
 

package/lib/client.js

@@ -68,15 +68,11 @@ window.__ModuleLoader__.load({
      */
     const FOLDER_SLOT = /(^|_)folder$/
 
-    /** Accessible name and tooltip of the companion button. */
-    const BUTTON_LABEL = '添加 WSL 工作区'
-
     /**
      * The copy language of everything this release adds.
      *
      * The catalog is bilingual, so the dialog can render a host failure in the
-     * operator's language without a translation build step. Older copy in this file
-     * stays Chinese; the protocol surface is localised from the first day.
+     * operator's language without a translation build step.
      */
     const LOCALE = typeof navigator !== 'undefined' && /^zh/i.test(String(navigator.language ?? '')) ? 'zh' : 'en'
 
@@ -90,6 +86,86 @@ window.__ModuleLoader__.load({
       return LOCALE === 'zh' ? zh : en
     }
 
+    /**
+     * The older dialog copy, in one table so the whole W dialog is bilingual.
+     *
+     * The 0.6 surfaces above use `t(zh, en)` inline; these entries are older and
+     * carry `{name}` placeholders, which `copy()` fills. Keeping them here means a
+     * language sweep has one place to audit instead of 1,700 lines of literals.
+     */
+    const COPY = {
+      trigger: { zh: '添加 WSL 工作区', en: 'Add a WSL workspace' },
+      createRefused: { zh: '宿主拒绝创建会话', en: 'The host refused to create the session' },
+      notADirectory: { zh: '{target} 不是一个存在的目录', en: '{target} is not an existing directory' },
+      sessionHint: { zh: '新会话的 bash 与文件工具都会在该发行版里工作；Windows 文件可在 /mnt/<盘符> 下访问。', en: 'The new session runs bash and the file tools inside this distribution; Windows files are under /mnt/<drive>.' },
+      distroLabel: { zh: '发行版', en: 'Distribution' },
+      reading: { zh: '读取中…', en: 'Reading…' },
+      noDistros: { zh: '没有可用的 WSL 发行版', en: 'No usable WSL distribution' },
+      userHint: { zh: '输入要进入该发行版的用户；确认后直接落在其主目录。', en: 'Enter the user to enter this distribution as; the browser lands in their home.' },
+      userPlaceholder: { zh: '留空 = 发行版默认用户', en: 'Leave blank for the distribution default user' },
+      resolving: { zh: '解析中…', en: 'Resolving…' },
+      confirmUser: { zh: '确认进入', en: 'Enter' },
+      cancel: { zh: '取消', en: 'Cancel' },
+      userHome: { zh: '用户 {user} · 主目录 {home}（可直接修改）', en: 'User {user} · home {home} (editable)' },
+      pathPlaceholder: { zh: '/home/用户名/项目', en: '/home/user/project' },
+      go: { zh: '前往', en: 'Go' },
+      readingDir: { zh: '读取目录…', en: 'Reading the directory…' },
+      noSubdirs: { zh: '没有子目录', en: 'No subdirectories' },
+      parentDir: { zh: '.. 上级目录', en: '.. Parent directory' },
+      working: { zh: '处理中…', en: 'Working…' },
+      createOpen: { zh: '创建并打开', en: 'Create and open' },
+      missingPrefix: { zh: '缺少：', en: 'Missing: ' },
+      healthSummary: { zh: '环境检查：{pass} 项通过{warn}{fail}', en: 'Health check: {pass} passed{warn}{fail}' },
+      healthWarn: { zh: '，{count} 项建议处理', en: ', {count} advisory' },
+      healthFail: { zh: '，{count} 项失败', en: ', {count} failed' },
+      dialogDescription: { zh: '从 WSL 发行版目录创建工作区。', en: 'Create a workspace from a WSL distribution directory.' },
+      filterPlaceholder: { zh: '过滤当前目录…', en: 'Filter this directory…' },
+      filterLabel: { zh: '按名称过滤目录', en: 'Filter directories by name' },
+      filterEmpty: { zh: '没有匹配的子目录', en: 'No matching subdirectories' },
+      retryList: { zh: '重试读取', en: 'Try again' },
+    }
+
+    /**
+     * Look up one COPY entry and fill its `{name}` placeholders.
+     * @param {string} key - the COPY key.
+     * @param {Record<string, unknown>} [vars] - placeholder values.
+     * @returns {string} the copy.
+     */
+    function copy(key, vars = {}) {
+      const entry = COPY[key]
+      const text = entry?.[LOCALE] ?? entry?.en ?? key
+      return text.replace(/\{(\w+)\}/g, (_, name) => String(vars[name] ?? ''))
+    }
+
+    /** Accessible name and tooltip of the companion button. */
+    const BUTTON_LABEL = copy('trigger')
+
+    /** Inline style for text that screen readers get but the page does not show. */
+    const VISUALLY_HIDDEN = {
+      position: 'absolute',
+      width: '1px',
+      height: '1px',
+      padding: '0',
+      margin: '-1px',
+      overflow: 'hidden',
+      clip: 'rect(0,0,0,0)',
+      whiteSpace: 'nowrap',
+      border: '0',
+    }
+
+    /** The open dialog's polite live region; null while no dialog is open. */
+    let liveStatus = null
+
+    /**
+     * Announce a short status through the dialog's live region.
+     * @param {string} text - the message.
+     */
+    function announce(text) {
+      if (liveStatus === null) return
+      liveStatus.textContent = ''
+      liveStatus.textContent = text
+    }
+
     /** Copy used only when the catalog itself could not be fetched. */
     const FALLBACK_MESSAGES = {
       transport: { zh: '连不上插件的本地路由。', en: 'The plugin route could not be reached.' },
@@ -135,7 +211,7 @@ window.__ModuleLoader__.load({
      */
     function localizeDetail(detail) {
       if (LOCALE !== 'zh' || typeof detail !== 'string') return detail
-      if (detail.startsWith('missing: ')) return `缺少：${detail.slice('missing: '.length)}`
+      if (detail.startsWith('missing: ')) return `${copy('missingPrefix')}${detail.slice('missing: '.length)}`
       // Version strings carry their own identity (Python x.y, dsh-wsl-confine v1.2).
       if (detail.startsWith('Python ') || detail.startsWith('dsh-wsl-confine ')) return detail
       return DETAIL_ZH[detail] ?? detail
@@ -299,7 +375,7 @@ window.__ModuleLoader__.load({
       const create = ctx.remote?.session?.create
       if (typeof create !== 'function') return ctx.sessions.create({ workspaceId })
       const result = await create({ workspaceId, agentPreset })
-      if (result?.ok !== true) throw new Error(result?.error?.message ?? '宿主拒绝创建会话')
+      if (result?.ok !== true) throw new Error(result?.error?.message ?? copy('createRefused'))
       return result.value.sessionId
     }
 
@@ -428,6 +504,7 @@ window.__ModuleLoader__.load({
         copy.addEventListener('click', () => {
           void navigator.clipboard?.writeText?.(String(remedy.value ?? ''))
           copy.textContent = t('已复制', 'Copied')
+          announce(t('已复制', 'Copied'))
         })
         row.append(copy)
         return row
@@ -451,7 +528,7 @@ window.__ModuleLoader__.load({
      * @param {object|null} bootstrap - the bootstrap result.
      * @returns {HTMLElement|null} the node.
      */
-    function renderFailureNode(failure, bootstrap) {
+    function renderFailureNode(failure, bootstrap, state = null) {
       if (failure === null) return null
       const catalog = bootstrap?.ok === true ? bootstrap.value?.catalog : null
       const entry = catalog?.codes?.[failure.code]
@@ -459,6 +536,7 @@ window.__ModuleLoader__.load({
         ?? t('插件内部错误。', 'The plugin hit an internal error.')
       const box = el('div', { fontSize: '12px', color: T.error, display: 'flex', flexDirection: 'column', gap: '4px' })
       box.setAttribute('role', 'alert')
+      box.setAttribute('aria-live', 'assertive')
       box.setAttribute('data-wsl-error', failure.code)
       box.append(el('div', {}, copy))
       const remedy = entry === undefined ? null : renderRemedy(entry.remedy)
@@ -478,6 +556,7 @@ window.__ModuleLoader__.load({
         copyRef.addEventListener('click', () => {
           void navigator.clipboard?.writeText?.(ref)
           copyRef.textContent = t('已复制', 'Copied')
+          announce(t('已复制', 'Copied'))
         })
         row.append(copyRef)
         box.append(row)
@@ -495,9 +574,64 @@ window.__ModuleLoader__.load({
         box.append(link)
       }
       box.append(el('div', { fontSize: '11px', color: T.dim }, failure.code))
+      if (state !== null) {
+        // A failed browse or commit used to offer no report at all; only the
+        // degraded card did. The same report is now one click away on every
+        // failure, with the same redaction rules.
+        const copyAll = el('button', { ...BUTTON_STYLE, padding: '2px 8px', fontSize: '11px', alignSelf: 'flex-start' },
+          t('复制诊断', 'Copy diagnostics'))
+        copyAll.type = 'button'
+        copyAll.setAttribute('data-wsl-diagnostics', '')
+        copyAll.addEventListener('click', () => {
+          void navigator.clipboard?.writeText?.(buildDiagnostics(state, failure))
+          copyAll.textContent = t('已复制', 'Copied')
+          announce(t('已复制', 'Copied'))
+        })
+        box.append(copyAll)
+      }
       return box
     }
 
+    /**
+     * Build the copyable diagnostic report.
+     *
+     * Deliberately excludes the host message, stderr, resolved paths and the raw
+     * failure text: it carries only what the catalog already exposes plus the
+     * doctor's path-free facts. A failure is described by its code and params.
+     * @param {object} state - the open picker's state.
+     * @param {object|null} [failure] - the failure to include, if any.
+     * @returns {string} pretty JSON.
+     */
+    function buildDiagnostics(state, failure = null) {
+      const bootstrap = state.bootstrap
+      const value = bootstrap?.ok === true ? bootstrap.value : null
+      const health = state.health?.status === 'ready'
+        ? {
+          distro: state.health.distro ?? state.distro,
+          user: state.health.user ?? state.user,
+          family: state.health.family ?? null,
+          runner: state.health.runner ?? null,
+          restricted: state.health.restricted ?? null,
+          checks: (state.health.checks ?? []).map((entry) => ({
+            id: entry.id,
+            status: entry.status,
+            ...(typeof entry.detail === 'string' ? { detail: entry.detail } : {}),
+          })),
+        }
+        : null
+      return JSON.stringify({
+        schema: 1,
+        locale: LOCALE,
+        pluginVersion: value?.pluginVersion ?? 'unknown',
+        catalog: value === null ? 'unavailable' : 'loaded',
+        capabilities: value?.capabilities ?? null,
+        features: state.features,
+        missing: state.missing,
+        health,
+        error: failure === null ? null : { code: failure.code, params: failure.params ?? {} },
+      }, null, 2)
+    }
+
     /**
      * The degraded card: what is missing, what to do, and a copyable report.
      * @param {object[]} body - the card's child list.
@@ -528,11 +662,7 @@ window.__ModuleLoader__.load({
       const entry = catalog?.codes?.['host-capability-missing']
       const remedy = entry === undefined ? null : renderRemedy(entry.remedy)
       if (remedy !== null) panel.append(remedy)
-      const diagnostics = JSON.stringify({
-        pluginVersion: state.bootstrap?.ok === true ? state.bootstrap.value?.pluginVersion ?? 'unknown' : 'unknown',
-        features: state.features,
-        missing: state.missing,
-      }, null, 2)
+      const diagnostics = buildDiagnostics(state)
       panel.append(el('pre', {
         margin: '0',
         padding: '8px',
@@ -548,6 +678,7 @@ window.__ModuleLoader__.load({
       copy.addEventListener('click', () => {
         void navigator.clipboard?.writeText?.(diagnostics)
         copy.textContent = t('已复制', 'Copied')
+        announce(t('已复制', 'Copied'))
       })
       panel.append(copy)
       if (typeof onRetry === 'function') {
@@ -644,6 +775,8 @@ window.__ModuleLoader__.load({
         home: null,
         path: '/',
         draft: '/',
+        /** Case-insensitive substring filter for the current directory. */
+        filter: '',
         listing: null,
         /** `{code, params}` or null; the raw host message is never rendered. */
         error: null,
@@ -656,7 +789,14 @@ window.__ModuleLoader__.load({
       overlay.setAttribute('role', 'dialog')
       overlay.setAttribute('aria-modal', 'true')
       overlay.setAttribute('aria-label', BUTTON_LABEL)
-      overlay.append(card)
+      const description = el('div', VISUALLY_HIDDEN, copy('dialogDescription'))
+      description.id = 'wsl-dialog-description'
+      overlay.setAttribute('aria-describedby', description.id)
+      const status = el('div', VISUALLY_HIDDEN, '')
+      status.setAttribute('role', 'status')
+      status.setAttribute('aria-live', 'polite')
+      liveStatus = status
+      overlay.append(description, card, status)
       overlay.addEventListener('click', () => { close() })
       card.addEventListener('click', (event) => { event.stopPropagation() })
 
@@ -676,6 +816,7 @@ window.__ModuleLoader__.load({
       function forceClose() {
         state.closed = true
         state.token += 1
+        liveStatus = null
         document.removeEventListener('keydown', onKey)
         overlay.remove()
         opener?.setAttribute?.('aria-expanded', 'false')
@@ -685,8 +826,34 @@ window.__ModuleLoader__.load({
         teardown = null
       }
 
+      /** The focusable controls inside the dialog, in document order. */
+      function focusables() {
+        return [...overlay.querySelectorAll('button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])')]
+      }
+
       function onKey(event) {
-        if (event.key === 'Escape') close()
+        if (event.key === 'Escape') {
+          close()
+          return
+        }
+        if (event.key !== 'Tab') return
+        // A modal dialog owns the keyboard: Tab from the last control wraps to the
+        // first and Shift+Tab from the first wraps to the last, so focus cannot
+        // escape into the page behind the overlay.
+        const focusable = focusables()
+        if (focusable.length === 0) return
+        const first = focusable[0]
+        const last = focusable[focusable.length - 1]
+        if (event.shiftKey && document.activeElement === first) {
+          event.preventDefault()
+          last.focus()
+        } else if (!event.shiftKey && document.activeElement === last) {
+          event.preventDefault()
+          first.focus()
+        } else if (!overlay.contains(document.activeElement)) {
+          event.preventDefault()
+          first.focus()
+        }
       }
 
       /** Discover distributions only after the capability gate has cleared. */
@@ -816,13 +983,14 @@ window.__ModuleLoader__.load({
         if (state.health.status === 'loading') {
           strip.setAttribute('data-wsl-health', 'loading')
           strip.setAttribute('role', 'status')
+      strip.setAttribute('aria-live', 'polite')
           strip.append(el('div', { fontSize: '12px', color: T.dim }, t('环境检查：检查中…', 'Health check: running…')))
           body.push(strip)
           return
         }
         if (state.health.status === 'error') {
           strip.setAttribute('data-wsl-health', 'error')
-          const failure = renderFailureNode(state.health.failure, state.bootstrap)
+          const failure = renderFailureNode(state.health.failure, state.bootstrap, state)
           if (failure !== null) strip.append(failure)
           const retry = el('button', {
             ...BUTTON_STYLE,
@@ -846,10 +1014,11 @@ window.__ModuleLoader__.load({
         const measured = checks.some((check) => check.status !== 'unknown')
         const summary = el('div', { display: 'flex', justifyContent: 'space-between', alignItems: 'center', gap: '8px' })
         summary.append(el('span', { fontSize: '12px', color: counts.fail > 0 ? T.error : T.dim },
-          t(
-            `环境检查：${counts.pass} 项通过${counts.warn > 0 ? `，${counts.warn} 项建议处理` : ''}${counts.fail > 0 ? `，${counts.fail} 项失败` : ''}`,
-            `Health: ${counts.pass} passed${counts.warn > 0 ? `, ${counts.warn} advisory` : ''}${counts.fail > 0 ? `, ${counts.fail} failed` : ''}`,
-          )))
+          copy('healthSummary', {
+            pass: counts.pass,
+            warn: counts.warn > 0 ? copy('healthWarn', { count: counts.warn }) : '',
+            fail: counts.fail > 0 ? copy('healthFail', { count: counts.fail }) : '',
+          })))
         const toggle = el('button', { ...BUTTON_STYLE, padding: '2px 8px', fontSize: '11px' },
           state.healthOpen ? t('收起', 'Hide') : t('展开', 'Details'))
         toggle.type = 'button'
@@ -988,7 +1157,7 @@ window.__ModuleLoader__.load({
         try {
           const facts = await call('checkPath', { distro: state.distro, path: target })
           if (facts.isDirectory !== true) {
-            throw Object.assign(new Error(`${target} 不是一个存在的目录`), {
+            throw Object.assign(new Error(copy('notADirectory', { target })), {
               code: 'path-not-directory',
               params: { path: target },
             })
@@ -1054,8 +1223,7 @@ window.__ModuleLoader__.load({
         const body = []
 
         body.push(el('div', { fontSize: '15px', fontWeight: '600' }, BUTTON_LABEL))
-        body.push(el('div', { fontSize: '12px', color: T.dim },
-          '新会话的 bash 与文件工具都会在该发行版里工作；Windows 文件可在 /mnt/<盘符> 下访问。'))
+        body.push(el('div', { fontSize: '12px', color: T.dim }, copy('sessionHint')))
 
         if (state.phase === 'loading') {
           const status = el('div', { fontSize: '12px', color: T.dim }, t('检查插件状态…', 'Checking the plugin…'))
@@ -1065,16 +1233,16 @@ window.__ModuleLoader__.load({
           renderDegraded(body, state, close, retryDegraded)
         } else {
           if (state.bootstrapError !== null) {
-            const failure = renderFailureNode(state.bootstrapError, state.bootstrap)
+            const failure = renderFailureNode(state.bootstrapError, state.bootstrap, state)
             if (failure !== null) body.push(failure)
           }
 
           const distros = el('div', { display: 'flex', flexWrap: 'wrap', gap: '6px', alignItems: 'center' })
-        distros.append(el('span', { fontSize: '12px', color: T.dim }, '发行版'))
+        distros.append(el('span', { fontSize: '12px', color: T.dim }, copy('distroLabel')))
         if (state.distros === null) {
-          distros.append(el('span', { fontSize: '12px', color: T.dim }, '读取中…'))
+          distros.append(el('span', { fontSize: '12px', color: T.dim }, copy('reading')))
         } else if (state.distros.length === 0) {
-          distros.append(el('span', { fontSize: '12px', color: T.error }, '没有可用的 WSL 发行版'))
+          distros.append(el('span', { fontSize: '12px', color: T.error }, copy('noDistros')))
         } else {
           for (const name of state.distros) distros.append(pill(name))
         }
@@ -1084,11 +1252,10 @@ window.__ModuleLoader__.load({
           // The user gate: no browsing until the distribution user is named.
           // An empty field means the distribution's default user; an unknown
           // user fails right here instead of opening the browser on a guess.
-          body.push(el('div', { fontSize: '12px', color: T.dim },
-            '输入要进入该发行版的用户；确认后直接落在其主目录。'))
+          body.push(el('div', { fontSize: '12px', color: T.dim }, copy('userHint')))
           const userField = el('input', FIELD_STYLE)
           userField.value = state.userDraft
-          userField.placeholder = '留空 = 发行版默认用户'
+          userField.placeholder = copy('userPlaceholder')
           userField.addEventListener('input', () => { state.userDraft = userField.value })
           userField.addEventListener('keydown', (event) => {
             if (event.key === 'Enter' && state.distro !== null) void confirmUser()
@@ -1096,7 +1263,7 @@ window.__ModuleLoader__.load({
           const enter = el('button', {
             ...PRIMARY_STYLE,
             opacity: state.pending ? '0.6' : '1',
-          }, state.pending ? '解析中…' : '确认进入')
+          }, state.pending ? copy('resolving') : copy('confirmUser'))
           enter.type = 'button'
           enter.setAttribute('data-wsl-action', 'confirm-user')
           enter.disabled = state.pending || state.distro === null
@@ -1104,30 +1271,30 @@ window.__ModuleLoader__.load({
           body.push(el('div', { display: 'flex', gap: '8px' }, userField, enter))
 
           if (state.error !== null) {
-            const failure = renderFailureNode(state.error, state.bootstrap)
+            const failure = renderFailureNode(state.error, state.bootstrap, state)
             if (failure !== null) body.push(failure)
           }
 
-          const cancel = el('button', BUTTON_STYLE, '取消')
+          const cancel = el('button', BUTTON_STYLE, copy('cancel'))
           cancel.type = 'button'
           cancel.addEventListener('click', () => { close() })
           body.push(el('div', { display: 'flex', justifyContent: 'flex-end' }, cancel))
         } else {
           // The confirmed user and their home: provenance of the prefill.
           if (state.user !== null && state.home !== null) {
-            body.push(el('div', { fontSize: '12px', color: T.dim }, `用户 ${state.user} · 主目录 ${state.home}（可直接修改）`))
+            body.push(el('div', { fontSize: '12px', color: T.dim }, copy('userHome', { user: state.user, home: state.home })))
           }
 
           renderHealthStrip(body)
 
           const input = el('input', FIELD_STYLE)
           input.value = state.draft
-          input.placeholder = '/home/用户名/项目'
+          input.placeholder = copy('pathPlaceholder')
           input.addEventListener('input', () => { state.draft = input.value })
           input.addEventListener('keydown', (event) => {
             if (event.key === 'Enter' && state.distro !== null) go(state.draft)
           })
-          const goButton = el('button', BUTTON_STYLE, '前往')
+          const goButton = el('button', BUTTON_STYLE, copy('go'))
           goButton.type = 'button'
           goButton.disabled = state.distro === null
           goButton.addEventListener('click', () => { go(state.draft) })
@@ -1153,15 +1320,45 @@ window.__ModuleLoader__.load({
             border: `1px solid ${T.border}`,
             background: T.layer,
           })
-          const directories = (state.listing?.entries ?? []).filter((entry) => entry.kind === 'directory')
+          const allDirectories = (state.listing?.entries ?? []).filter((entry) => entry.kind === 'directory')
+          // Filtering updates the rendered rows in place instead of repainting the
+          // card: a paint per keystroke replaces the input and steals focus (and
+          // breaks IME composition). The initial paint applies the stored filter.
+          const matchesFilter = (name) => state.filter === ''
+            || name.toLowerCase().includes(state.filter.toLowerCase())
+          const empty = el('div', { fontSize: '12px', color: T.dim, padding: '6px' }, copy('filterEmpty'))
+          empty.style.display = 'none'
+          const applyFilter = () => {
+            let visible = 0
+            for (const node of list.querySelectorAll('[data-wsl-entry]')) {
+              const shown = matchesFilter(node.getAttribute('data-name') ?? '')
+              node.style.display = shown ? 'block' : 'none'
+              if (shown) visible += 1
+            }
+            empty.style.display = visible === 0 ? 'block' : 'none'
+            if (state.filter !== '') empty.setAttribute('data-wsl-filter-empty', '')
+            else empty.removeAttribute('data-wsl-filter-empty')
+          }
+          if (state.listing !== null) {
+            const filter = el('input', FIELD_STYLE)
+            filter.value = state.filter
+            filter.placeholder = copy('filterPlaceholder')
+            filter.setAttribute('data-wsl-filter', '')
+            filter.setAttribute('aria-label', copy('filterLabel'))
+            filter.addEventListener('input', () => {
+              state.filter = filter.value
+              applyFilter()
+            })
+            body.push(filter)
+          }
           if (state.listing === null) {
-            list.append(el('div', { fontSize: '12px', color: T.dim, padding: '6px' }, '读取目录…'))
-          } else if (directories.length === 0) {
-            list.append(el('div', { fontSize: '12px', color: T.dim, padding: '6px' }, '没有子目录'))
+            list.append(el('div', { fontSize: '12px', color: T.dim, padding: '6px' }, copy('readingDir')))
+          } else if (allDirectories.length === 0) {
+            list.append(el('div', { fontSize: '12px', color: T.dim, padding: '6px' }, copy('noSubdirs')))
           } else {
-            for (const entry of directories) {
+            for (const entry of allDirectories) {
               const item = el('button', {
-                display: 'block',
+                display: matchesFilter(entry.name) ? 'block' : 'none',
                 width: '100%',
                 textAlign: 'left',
                 border: 'none',
@@ -1174,11 +1371,16 @@ window.__ModuleLoader__.load({
                 cursor: 'pointer',
               }, `📁 ${entry.name}`)
               item.type = 'button'
+              item.setAttribute('data-wsl-entry', '')
+              item.setAttribute('data-name', entry.name)
               item.addEventListener('mouseenter', () => { item.style.background = T.hover })
               item.addEventListener('mouseleave', () => { item.style.background = 'transparent' })
               item.addEventListener('click', () => { go(joinLinux(state.path, entry.name)) })
               list.append(item)
             }
+            list.append(empty)
+            if (state.filter !== '') empty.setAttribute('data-wsl-filter-empty', '')
+            applyFilter()
           }
           body.push(list)
           if (typeof state.listing?.hidden === 'number' && state.listing.hidden > 0) {
@@ -1191,24 +1393,35 @@ window.__ModuleLoader__.load({
 
           const parent = parentOf(state.path)
           if (parent !== null) {
-            const up = el('button', { ...BUTTON_STYLE, alignSelf: 'flex-start', padding: '4px 10px' }, '.. 上级目录')
+            const up = el('button', { ...BUTTON_STYLE, alignSelf: 'flex-start', padding: '4px 10px' }, copy('parentDir'))
             up.type = 'button'
             up.addEventListener('click', () => { go(parent) })
             body.push(up)
           }
 
           if (state.error !== null) {
-            const failure = renderFailureNode(state.error, state.bootstrap)
+            const failure = renderFailureNode(state.error, state.bootstrap, state)
             if (failure !== null) body.push(failure)
+            // A failed listing left the operator with an error and no way back to
+            // the directory they were reading. Retrying the same load is safe; a
+            // failed commit is deliberately excluded because it may have created
+            // the workspace before the error.
+            if (state.listing === null && !state.working) {
+              const retryList = el('button', BUTTON_STYLE, copy('retryList'))
+              retryList.type = 'button'
+              retryList.setAttribute('data-wsl-list-retry', '')
+              retryList.addEventListener('click', () => { void load() })
+              body.push(el('div', { display: 'flex', justifyContent: 'flex-start' }, retryList))
+            }
           }
 
-          const cancel = el('button', BUTTON_STYLE, '取消')
+          const cancel = el('button', BUTTON_STYLE, copy('cancel'))
           cancel.type = 'button'
           cancel.addEventListener('click', () => { close() })
           const confirm = el('button', {
             ...PRIMARY_STYLE,
             opacity: state.working ? '0.6' : '1',
-          }, state.working ? '处理中…' : '创建并打开')
+          }, state.working ? copy('working') : copy('createOpen'))
           confirm.type = 'button'
           confirm.setAttribute('data-wsl-action', 'create')
           confirm.disabled = state.working || state.distro === null
@@ -1247,6 +1460,7 @@ window.__ModuleLoader__.load({
       document.addEventListener('keydown', onKey)
       hostElement().append(overlay)
       render()
+      if (!overlay.contains(document.activeElement)) focusables()[0]?.focus()
 
       // The rejection handler only ever sees a refusal of listDistros itself; a
       // throw INSIDE the continuation (a body the route did not expect,

package/lib/index.js

@@ -25,7 +25,7 @@ import {
 } from './http-admission.js'
 import { buildVariantPlugins } from './wsl/preset.js'
 import { setLocalSubprocess } from './wsl/host-refs.js'
-import { checkLinuxPath, defaultDistro, defaultWorkspaceUnc, listDistros, listLinuxDir, resolveDistroHome, runWslShell } from './wsl/world.js'
+import { checkLinuxPath, defaultDistro, defaultWorkspaceUnc, listDistros, listLinuxDir, resolveDistroHome, runWslShell, wslMajorVersion } from './wsl/world.js'
 import { joinWslUnc, parseWslUnc, shellQuote, windowsToMntPath } from './wsl/paths.js'
 import { WslRouteError, browserFailure, routeErrorFor } from './route-errors.js'
 import { CHECK_IDS, CHECK_LABELS, CHECK_REMEDIES, DOCS, ERROR_CODES, FEATURE_IDS, FEATURE_LABELS } from './protocol.js'
@@ -506,7 +506,13 @@ const METHODS = {
   health: async ({ distro, username }) => {
     assertDistro(distro)
     assertUser(username)
-    return healthFor({ distro, username, wslPath: routeWslPath })
+    // Host-side: the distribution cannot report its own WSL generation.
+    return healthFor({
+      distro,
+      username,
+      wslPath: routeWslPath,
+      wslVersionProbe: ({ distro: name }) => wslMajorVersion(name, { wslPath: routeWslPath }),
+    })
   },
 
   /**

package/lib/protocol.js

@@ -141,7 +141,7 @@ export const FEATURE_LABELS = deepFreeze({
 })
 
 /** Health-check ids, in display order. */
-export const CHECK_IDS = deepFreeze(['bash', 'python3', 'util-linux', 'getent', 'runner', 'helper', 'nnp'])
+export const CHECK_IDS = deepFreeze(['bash', 'python3', 'util-linux', 'getent', 'runner', 'helper', 'nnp', 'wsl2'])
 
 /** Human-readable check names. */
 export const CHECK_LABELS = deepFreeze({
@@ -152,6 +152,7 @@ export const CHECK_LABELS = deepFreeze({
   runner: { zh: '受限模式 runner', en: 'Confinement runner' },
   helper: { zh: 'dsh-wsl-confine helper', en: 'dsh-wsl-confine helper' },
   nnp: { zh: 'NO_NEW_PRIVS', en: 'NO_NEW_PRIVS' },
+  wsl2: { zh: 'WSL2', en: 'WSL2' },
 })
 
 /** The fix for one failed check, keyed by check id. */
@@ -209,6 +210,11 @@ export const CHECK_REMEDIES = deepFreeze({
     zh: 'setpriv 不支持 --no-new-privs，受限模式不会运行；升级发行版的 util-linux。',
     en: 'setpriv lacks --no-new-privs, so restricted mode refuses to run; upgrade the distribution util-linux.',
   },
+  wsl2: {
+    kind: 'text',
+    zh: 'WSL1 不支持：在 Windows 侧运行 `wsl.exe --set-version <发行版> 2` 升级到 WSL2 后再试。',
+    en: 'WSL1 is unsupported: run `wsl.exe --set-version <distro> 2` on Windows to upgrade it to WSL2 first.',
+  },
 })
 
 /**

package/lib/release-check.js

@@ -0,0 +1,69 @@
+/**
+ * Pure publish-readiness rules.
+ *
+ * The 0.7.0 release learned two preconditions the hard way: an expired npm token
+ * (checked by the caller, not here) and pnpm's `minimumReleaseAge` refusing a
+ * just-published version during `install_bundle`. These rules are pure so the
+ * release runbook and the offline suite can pin them without a registry.
+ * @module dsh-wsl-desktop/release-check
+ */
+
+/**
+ * Compare two dotted numeric versions.
+ * @param {string} a - the left version.
+ * @param {string} b - the right version.
+ * @returns {number} -1, 0 or 1.
+ */
+export function compareVersions(a, b) {
+  const left = String(a).split('.').map((part) => Number.parseInt(part, 10) || 0)
+  const right = String(b).split('.').map((part) => Number.parseInt(part, 10) || 0)
+  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+    const difference = (left[index] ?? 0) - (right[index] ?? 0)
+    if (difference !== 0) return difference > 0 ? 1 : -1
+  }
+  return 0
+}
+
+/**
+ * Decide whether a version can be published.
+ * @param {{ target: string, latest: string|null, published?: boolean, localTag?: boolean, remoteTag?: boolean, dirty?: boolean }} input -
+ *   the target and the facts gathered by the caller.
+ * @returns {{ ready: boolean, blockers: string[] }} the verdict.
+ */
+export function classifyPublish({ target, latest, published = false, localTag = false, remoteTag = false, dirty = false }) {
+  const blockers = []
+  if (latest === null || latest === undefined) {
+    blockers.push('the registry latest version is unknown (npm view failed)')
+  } else if (compareVersions(target, latest) <= 0) {
+    blockers.push(`target ${target} is not newer than the registry latest ${latest}`)
+  }
+  if (published === true) blockers.push(`target ${target} is already published`)
+  if (localTag === true) blockers.push(`a local tag v${target} already exists`)
+  if (remoteTag === true) blockers.push(`a remote tag v${target} already exists`)
+  if (dirty === true) blockers.push('the working tree carries tracked changes')
+  return { ready: blockers.length === 0, blockers }
+}
+
+/**
+ * When a freshly published version becomes installable under pnpm's minimum age.
+ * @param {{ publishedAt: string|null, minimumReleaseAgeMinutes: number, now: Date }} input -
+ *   the registry publish time, the configured window and the current time.
+ * @returns {{ ready: boolean|null, readyAt: Date|null, detail: string }} the verdict.
+ */
+export function installWindow({ publishedAt, minimumReleaseAgeMinutes, now = new Date() }) {
+  if (publishedAt === null || publishedAt === undefined || publishedAt === '') {
+    return { ready: null, readyAt: null, detail: 'the registry publish time is unreadable; wait one full window before retrying' }
+  }
+  const published = new Date(publishedAt)
+  if (Number.isNaN(published.getTime()) || !Number.isFinite(minimumReleaseAgeMinutes)) {
+    return { ready: null, readyAt: null, detail: 'the publish time or the minimum age is unreadable' }
+  }
+  const readyAt = new Date(published.getTime() + minimumReleaseAgeMinutes * 60_000)
+  return {
+    ready: now.getTime() >= readyAt.getTime(),
+    readyAt,
+    detail: now.getTime() >= readyAt.getTime()
+      ? 'outside the minimumReleaseAge window'
+      : `inside the minimumReleaseAge window until ${readyAt.toISOString()}`,
+  }
+}

package/lib/release-preflight.js

@@ -0,0 +1,105 @@
+/**
+ * Pure decisions behind the live-release preflight.
+ *
+ * The preflight exists because the 0.6.0 release exposed two failure modes that
+ * looked like code reds but were environment states: a production profile installs
+ * the npm package with `developerTools: false` (every dev-token call is a 401), and a
+ * staged generation can lag the tree while the host keeps serving the old bundle.
+ * Both are decided from small, testable inputs — a patch file and a bootstrap
+ * envelope — so this module carries no I/O and no `node:` imports.
+ * @module dsh-wsl-desktop/release-preflight
+ */
+
+/** Markers the current browser half must carry in the served bundle. */
+export const REQUIRED_CLIENT_MARKERS = Object.freeze([
+  'bootstrapOnce',
+  'data-wsl-degraded',
+  'data-wsl-health',
+  'data-wsl-degraded-retry',
+])
+
+/**
+ * Read the developer-surface setting from an installed bundle patch.
+ *
+ * `sync.ps1` stages `config: { developerTools: true }`; the published package ships
+ * no config block at all, so absence means off. An unreadable/missing patch is also
+ * off: the preflight must not crash on the very state it reports.
+ * @param {unknown} patchText - `cordis.patch.yml` contents.
+ * @returns {{ found: boolean, developerTools: boolean }} the setting.
+ */
+export function parseDevSurface(patchText) {
+  if (typeof patchText !== 'string') return { found: false, developerTools: false }
+  const match = /^\s*developerTools:\s*(true|false)\s*$/mu.exec(patchText)
+  if (match === null) return { found: false, developerTools: false }
+  return { found: true, developerTools: match[1] === 'true' }
+}
+
+/**
+ * Classify a bootstrap answer.
+ * @param {{ status: number, json: object|null, expectedVersion: string, expectedCodes?: string[] }} input -
+ *   the HTTP status, parsed body, and the version/codes this checkout requires.
+ * @returns {{ kind: string, detail: string }} the verdict; `kind` is `ready` when the
+ *   host is this tree with a working dev surface.
+ */
+export function classifyBootstrap({ status, json, expectedVersion, expectedCodes = [] }) {
+  if (status === 401) {
+    return { kind: 'dev-surface-disabled', detail: 'the route answered 401: the development token surface is off' }
+  }
+  if (status === 0 || status === undefined) {
+    return { kind: 'unreachable', detail: 'no HTTP response: the desktop is not running or the URL is wrong' }
+  }
+  if (json === null || typeof json !== 'object' || json.ok !== true) {
+    return { kind: 'bad-shape', detail: `HTTP ${status}: the route answered no bootstrap envelope` }
+  }
+  const value = json.value
+  if (value === null || typeof value !== 'object') {
+    return { kind: 'bad-shape', detail: `HTTP ${status}: bootstrap carried no value` }
+  }
+  if (value.pluginVersion !== expectedVersion) {
+    return {
+      kind: 'version-mismatch',
+      detail: `host reports ${String(value.pluginVersion)}, this checkout is ${expectedVersion}`,
+    }
+  }
+  const capability = value.capabilities?.status
+  if (capability !== 'ok' && capability !== 'degraded' && capability !== 'pending') {
+    return { kind: 'missing-capabilities', detail: `bootstrap carries no capability status (${String(capability)})` }
+  }
+  const codes = value.catalog?.codes
+  const missing = codes === null || typeof codes !== 'object'
+    ? expectedCodes
+    : expectedCodes.filter((code) => !Object.hasOwn(codes, code))
+  if (missing.length > 0) {
+    return { kind: 'missing-codes', detail: `catalog is missing: ${missing.join(', ')}` }
+  }
+  return { kind: 'ready', detail: `host ${expectedVersion}, dev surface on` }
+}
+
+/**
+ * Name the required markers a served bundle is missing.
+ * @param {unknown} bundleText - the served client module.
+ * @param {string[]} [markers] - the required markers.
+ * @returns {string[]} the missing markers, in requirement order.
+ */
+export function missingClientMarkers(bundleText, markers = REQUIRED_CLIENT_MARKERS) {
+  const text = String(bundleText ?? '')
+  return markers.filter((marker) => !text.includes(marker))
+}
+
+/**
+ * The operator-facing remedy for a host whose dev surface is off.
+ * @returns {string} a short, copy-pasteable explanation.
+ */
+export function devSurfaceRemedy() {
+  return [
+    'The running host is not exposing its development surface (401).',
+    'The published npm package ships developerTools: false by design; the staged dev',
+    'generation turns it on.',
+    'For a live verification run:',
+    '  1. .\\scripts\\sync.ps1        (stage a dev generation with developerTools: true)',
+    '  2. restart DSH Desktop       (the host half reloads; a page refresh is not enough)',
+    '  3. node scripts/verify-all.mjs --live',
+    'To return to the release shape afterwards, reinstall the registry bundle with',
+    'plugin_manager remove_bundle + install_bundle dsh-wsl-desktop@<version>.',
+  ].join('\n')
+}

package/lib/wsl/doctor.js

@@ -192,7 +192,7 @@ async function probeHelperVersion({ distro, username, run, wslPath }) {
  * @param {object} options - probe inputs.
  * @returns {Promise<object>} the health answer.
  */
-async function computeHealth({ distro, username, run, wslPath, now, runnerProbe, nnpProbe, helperProbe }) {
+async function computeHealth({ distro, username, run, wslPath, now, runnerProbe, nnpProbe, helperProbe, wslVersionProbe }) {
   // The cached probes call `run` themselves and do not know about the plugin's
   // configured wsl.exe path, so the doctor binds it once for every probe it hands
   // them. Without this they silently fall back to the bare `wsl.exe`.
@@ -206,11 +206,16 @@ async function computeHealth({ distro, username, run, wslPath, now, runnerProbe,
     run: probeRun,
     cacheKey: typeof wslPath === 'string' ? wslPath : '',
   }
-  const [values, runnerOutcome, nnpOutcome] = await Promise.all([
+  const [values, runnerOutcome, nnpOutcome, wslVersionOutcome] = await Promise.all([
     runBatch({ distro, username, run, wslPath }),
     bounded(Promise.resolve().then(() => runnerProbe(probeOptions)), PROBE_RACE_MS),
     bounded(Promise.resolve().then(() => nnpProbe(probeOptions)), PROBE_RACE_MS),
+    // Host-side, not in-distro: a WSL1 distribution's mount-namespace semantics
+    // are not visible from inside it. The route passes a real probe; the suite
+    // injects one, so no new spawn leaks into the existing cases.
+    bounded(Promise.resolve().then(() => wslVersionProbe({ distro, wslPath })), PROBE_RACE_MS),
   ])
+  const wslVersion = wslVersionOutcome?.value ?? null
 
   const measured = Object.keys(values).length > 0
   const family = distroFamily(values)
@@ -290,6 +295,13 @@ async function computeHealth({ distro, username, run, wslPath, now, runnerProbe,
     } else {
       add('nnp', 'unknown', 'unmeasured')
     }
+    if (wslVersion === '1') {
+      add('wsl2', 'fail', 'WSL1 distribution; the mount-namespace boundary needs WSL2')
+    } else if (wslVersion === '2') {
+      add('wsl2', 'pass', 'WSL2')
+    } else {
+      add('wsl2', 'unknown', 'not measured')
+    }
   }
 
   const statusOf = (id) => checks.find((entry) => entry.id === id)?.status
@@ -320,6 +332,7 @@ export async function healthFor({
   runnerProbe = detectRunner,
   nnpProbe = detectNoNewPrivs,
   helperProbe = probeHelperVersion,
+  wslVersionProbe = async () => null,
 }) {
   const key = `${distro}\0${username ?? ''}\0${wslPath ?? ''}`
   const cached = healthCache.get(key)
@@ -328,7 +341,7 @@ export async function healthFor({
   }
   const inflight = healthInflight.get(key)
   if (inflight !== undefined) return inflight
-  const pending = computeHealth({ distro, username, run, wslPath, now, runnerProbe, nnpProbe, helperProbe })
+  const pending = computeHealth({ distro, username, run, wslPath, now, runnerProbe, nnpProbe, helperProbe, wslVersionProbe })
     .then((result) => {
       healthCache.set(key, { at: now(), result })
       // The key carries a browser-supplied user; a page could churn spellings to

package/lib/wsl/world.js

@@ -231,6 +231,59 @@ export async function listDistros({ wslPath = 'wsl.exe' } = {}) {
     .filter((line) => line.length > 0)
 }
 
+/**
+ * The WSL major version of one distribution, from `wsl.exe -l -v`.
+ *
+ * WSL1 is explicitly unsupported (its syscall translation layer has no mount
+ * namespace), but until now nothing in the product asked the host which version a
+ * distribution runs. The output is a table:
+ *
+ *   `  NAME      STATE           VERSION`
+ *   `* debian    Running         2`
+ *
+ * The active marker is optional; the version is the last column. A table that
+ * cannot be parsed answers `null` — an unmeasured fact is not a failure.
+ * @param {string} distro - the distribution name.
+ * @param {{ wslPath?: string }} [options] - the configured `wsl.exe` path.
+ * @returns {Promise<'1'|'2'|null>} the major version, or null when unreadable.
+ */
+export async function wslMajorVersion(distro, { wslPath = 'wsl.exe' } = {}) {
+  let stdout
+  try {
+    ({ stdout } = await execFileAsync(wslPath, ['-l', '-v'], {
+      encoding: 'buffer',
+      timeout: DISCOVERY_TIMEOUT_MS,
+      env: { ...process.env, ...WSL_CHILD_ENV },
+    }))
+  } catch {
+    return null
+  }
+  return parseWslVersionTable(decodeWslOutput(stdout), distro)
+}
+
+/**
+ * Pick one distribution's major version out of a `wsl.exe -l -v` table.
+ *
+ * Kept pure and exported so the table's spacing variants are testable without a
+ * real WSL host. The active marker (`*`) is optional; the last column is VERSION.
+ * @param {unknown} text - the decoded table.
+ * @param {string} distro - the distribution name.
+ * @returns {'1'|'2'|null} the major version, or null when the row is absent.
+ */
+export function parseWslVersionTable(text, distro) {
+  const lines = String(text ?? '').split(/\r?\n/)
+  for (const raw of lines) {
+    const line = raw.replace(/\0/g, '').trim()
+    if (line === '') continue
+    const cells = line.replace(/^\*\s*/, '').split(/\s{2,}|\t/).filter((cell) => cell !== '')
+    if (cells.length < 2) continue
+    if (cells[0] !== distro) continue
+    const version = cells[cells.length - 1]
+    return version === '1' || version === '2' ? version : null
+  }
+  return null
+}
+
 /**
  * The Lxss registry values and the two REG_SZ lines the default-distribution read needs.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-wsl-desktop",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "type": "module",
   "main": "lib/index.js",
   "icon": "./lib/icon.svg",