dsh-vscode-mode 0.7.0 → 0.9.0

package/src/rpc.ts

@@ -34,7 +34,7 @@ import { rulesList, rulesRead, rulesRemove, rulesSave, rulesToggle } from './rul
 import { isSnippetFilePath, snippetsEntries, snippetsList, snippetsRead, snippetsRemove, snippetsSave } from './snippets.js'
 import { listMcp, refreshMcp, removeMcp, saveMcp, toggleMcp } from './mcp.js'
 import { listProjects, projectRefresh, projectRemove, projectSave, projectToggle } from './mcpProject.js'
-import { normalizeFileOpenTool, FILE_OPEN_DEFAULT, FILE_OPEN_SETTINGS_NS } from './fileOpenSettings.js'
+import { normalizeFileOpenTool, FILE_OPEN_DEFAULT, FILE_OPEN_SETTINGS_NS, sectionOf, updateSection } from './fileOpenSettings.js'
 import { INTEGRATION_BASE_DEFAULT } from './shared/integration.js'
 import { shellMenuRegister, shellMenuRemove, shellMenuStatus } from './integrate.js'
 import { unityAdd, unityInstall, unityList, unityRemove } from './unityBridge.js'
@@ -44,10 +44,11 @@ import { findProfileDir, readDevForm, setDevForm } from './devForm.js'
 import { normalizeRel } from './tree.js'
 import { baseNameOf, checkNewName, checkRenameName, isSubPath, joinRelPath, parentRelOf } from './shared/fsNames.js'
 import { invalidateIndex, listDirCached } from './treeIndex.js'
+import { findRemoteWs, remoteDisplayOf, type RemoteWs } from './remoteWorkspace.js'
 import { revealInExplorer } from './reveal.js'
 import { dshHome, debugLogFile, pluginLogRoot } from './paths.js'
 import { clearDebugLog, debugRecord, isDebugLogName, listDebugLogs, readDebugLog } from './debugLog.js'
-import { markActiveSessions, moveOutSessions, planMoveOut, purgeArchive, restoreSession, scanSessionInventory, sessionsArchiveRoot, sessionSizeOf, sidecarSummaryOf } from './perf.js'
+import { markActiveSessions, markOfficialFlags, moveOutSessions, planMoveOut, purgeArchive, restoreSession, scanSessionInventory, sessionsArchiveRoot, sessionSizeOf, sidecarSummaryOf, unarchiveOfficial } from './perf.js'
 import { patchHasPerfConfig, patchInsertPerfConfig, patchRemovePerfConfig, perfConfigBlock } from './perfPatch.js'
 import type { FileVersions } from './fileVersions.js'
 
@@ -56,8 +57,8 @@ const staleCheckedAt = new Map<string, number>()
 /** stale 自动清理最小间隔。 */
 const STALE_CHECK_MIN_MS = 10_000
 
-/** 记录 → 客户端视图（不含 before 全文，仅长度）。 */
-function recView(record: DiffRecord): RecordView {
+/** 记录 → 客户端视图（不含 before 全文，仅长度）；远程工作区附远端展示路径（issue #7）。 */
+function recView(record: DiffRecord, ws: RemoteWs | null = null): RecordView {
   return {
     callId: record.callId,
     toolName: record.toolName,
@@ -75,6 +76,7 @@ function recView(record: DiffRecord): RecordView {
     conflict: record.conflict === true,
     legacy: record.legacy === true,
     at: record.at,
+    ...(ws ? { displayPath: remoteDisplayOf(record.path, ws) ?? undefined } : {}),
   }
 }
 
@@ -107,6 +109,57 @@ function snippetTargetOf(path: string): string | null {
   return isSnippetFilePath(path) ? path.replace(/\\/g, '/') : null
 }
 
+/** readTargetOf 成功形态：解析后的目标路径、stat 信息与 fs 服务句柄。 */
+interface ReadTargetOk {
+  target: string
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  fs: any
+  info: { version?: unknown; size?: number }
+}
+
+/**
+ * 二进制/文本读取共用前置（edrv.read 与 edrv.readBinary）：解析路径 + debugRecord +
+ * stat + 文件类型校验 + 32MB 二进制上限，保证两条读通道的错误口径完全一致。
+ * @author ddj 2026年09月22号
+ * @param ctx DSH 上下文
+ * @param sc requireSession 成功结果（session + cwd）
+ * @param path 客户端请求路径
+ * @returns 成功返回解析目标与 stat；失败返回错误文案（文件不存在时附 resolvedPath）
+ */
+async function readTargetOf(
+  ctx: Ctx,
+  sc: { session: Session; cwd: string },
+  path: string,
+): Promise<ReadTargetOk | { err: string; resolvedPath?: string }> {
+  const fs = ctx.get('fs')
+  if (!fs) return { err: '缺少 fs' }
+  try {
+    const target = await resolveTarget(ctx, sc.session, path)
+    debugRecord(ctx, sc.cwd, '[DEBUG path.resolve] input=' + String(path ?? '') + ' resolved=' + fs.processPath(target), 'debug')
+    const info = await fs.stat(target)
+    if (!info || info.type !== 'file') {
+      // 带上解析后的真实路径：跳转失败时可直接看出是路径解析错还是目标本身不存在
+      return { err: '文件不存在', resolvedPath: fs.processPath(target) }
+    }
+    if ((info.size ?? 0) > BINARY_READ_CAP) return { err: '文件过大（>32MB），不支持整文件预览' }
+    return { target, fs, info }
+  } catch (error) {
+    return { err: '读取失败：' + String(error) }
+  }
+}
+
+/**
+ * readTargetOf 失败结果 → RPC 错误载荷（文件不存在时保留 resolvedPath 供诊断）。
+ * @author ddj 2026年09月22号
+ * @param prep readTargetOf 的失败分支
+ * @returns { ok:false } 形态载荷
+ */
+function targetErrOf(prep: { err: string; resolvedPath?: string }): { ok: false; error: string; resolvedPath?: string } {
+  return prep.resolvedPath !== undefined
+    ? { ok: false, error: prep.err, resolvedPath: prep.resolvedPath }
+    : { ok: false, error: prep.err }
+}
+
 /**
  * 本地文件系统版本令牌（mtime+size）：与 ctx.fs 的不透明版本串用途相同，
  * 仅供全局片段文件（走 node:fs 直读、不经 ctx.fs）在 edrv.read 时回带。
@@ -181,6 +234,7 @@ async function applyDecisions(
 ): Promise<DecideResult[]> {
   const results: DecideResult[] = []
   const resolved: DiffRecord[] = []
+  const ws = findRemoteWs(cwd)
   let changed = false
   for (const item of items) {
     const record = bucket.get(item.callId)
@@ -204,7 +258,7 @@ async function applyDecisions(
     markDecision(record, item.scope ?? 'call', item.hunkIndex, item.decision)
     changed = true
     if (!wasResolved && recordResolved(record)) resolved.push(record)
-    const result: DecideResult = { callId: item.callId, ok: true, record: recView(record) }
+    const result: DecideResult = { callId: item.callId, ok: true, record: recView(record, ws) }
     if (revertedStale) result.stale = true
     results.push(result)
   }
@@ -241,8 +295,7 @@ async function latestPatchBackup(patchPath: string): Promise<string | undefined>
 /** 读取设置中的深链基址（缺省/非法回退默认 3080）。 */
 async function integrationBaseUrlOf(ctx: Ctx): Promise<string> {
   const settings = ctx.get('settings')
-  const descriptor = settings?.describe?.({ redactSecrets: true })?.find((item: { ns?: string }) => item.ns === FILE_OPEN_SETTINGS_NS)
-  const value = descriptor?.value as { integrationBaseUrl?: unknown } | undefined
+  const value = sectionOf(settings, FILE_OPEN_SETTINGS_NS)?.value as { integrationBaseUrl?: unknown } | undefined
   const raw = typeof value?.integrationBaseUrl === 'string' ? value.integrationBaseUrl.trim() : ''
   return raw || INTEGRATION_BASE_DEFAULT
 }
@@ -384,11 +437,12 @@ export function buildHandlers(
         }
       }
       const out: RecordView[] = []
+      const ws = findRemoteWs(sc.cwd)
       for (const rec of bucket.values()) {
         // 面板全量查询过滤已归档；聊天条按 callId 查询保留（状态徽章仍需正确显示）
         if (!want && rec.archived) continue
         if (want && !want.has(rec.callId)) continue
-        out.push(recView(rec))
+        out.push(recView(rec, ws))
       }
       out.sort((a, b) => (a.at < b.at ? -1 : 1))
       return { ok: true, records: out }
@@ -433,26 +487,36 @@ export function buildHandlers(
       }
       const sc = await requireSession(ctx, args.sessionId)
       if ('err' in sc) return { ok: false, error: sc.err }
-      const fs = ctx.get('fs')
-      if (!fs) return { ok: false, error: '缺少 fs' }
+      const prep = await readTargetOf(ctx, sc, args.path)
+      if ('err' in prep) return targetErrOf(prep)
       try {
-        const target = await resolveTarget(ctx, sc.session, args.path)
-         debugRecord(ctx, sc.cwd, '[DEBUG path.resolve] input=' + String(args.path ?? '') + ' resolved=' + fs.processPath(target), 'debug')
-        const info = await fs.stat(target)
-        if (!info || info.type !== 'file') {
-          // 带上解析后的真实路径：跳转失败时可直接看出是路径解析错还是目标本身不存在
-          return { ok: false, error: '文件不存在', resolvedPath: fs.processPath(target) }
-        }
-        if ((info.size ?? 0) > BINARY_READ_CAP) return { ok: false, error: '文件过大（>32MB），不支持整文件预览' }
         if (args.encoding === 'base64') {
-          // 图片/PDF 等二进制预览：readBytes 无解码、无二进制拒绝；超上限已由上方 stat 拦截
-          const bytes = await fs.readBytes(target, undefined, BINARY_READ_CAP)
+          // 图片/PDF 等二进制预览：readBytes 无解码、无二进制拒绝；超上限已由 readTargetOf 拦截
+          const bytes = await prep.fs.readBytes(prep.target, undefined, BINARY_READ_CAP)
           const content = Buffer.from(bytes).toString('base64')
-          return { ok: true, content, size: bytes.byteLength, encoding: 'base64', mime: binaryMimeOf(args.path), version: String(info.version ?? '') }
+          return { ok: true, content, size: bytes.byteLength, encoding: 'base64', mime: binaryMimeOf(args.path), version: String(prep.info.version ?? '') }
+        }
+        if ((prep.info.size ?? 0) > READ_CAP) return { ok: false, error: '文件过大（>8MB），不支持整文件预览' }
+        const content = await prep.fs.readText(prep.target)
+        return { ok: true, content, size: content.length, version: String(prep.info.version ?? '') }
+      } catch (error) {
+        return { ok: false, error: '读取失败：' + String(error) }
+      }
+    },
+    'edrv.readBinary': async (args) => {
+      // 二进制直读通道（图片/PDF 预览）：与 edrv.read base64 分支共用 readTargetOf 前置，
+      // 返回 Uint8Array 信封；routes 接线后以 octet-stream + x-edrv-* 头直出，
+      // 未接线时信封被 JSON 化，由 client 探测到后自动回退 base64 路径（见 shared/rpc readBinaryPreview）。
+      const sc = await requireSession(ctx, args.sessionId)
+      if ('err' in sc) return { ok: false, error: sc.err }
+      const prep = await readTargetOf(ctx, sc, args.path)
+      if ('err' in prep) return targetErrOf(prep)
+      try {
+        const bytes = await prep.fs.readBytes(prep.target, undefined, BINARY_READ_CAP)
+        return {
+          ok: true,
+          binary: { bytes, mime: binaryMimeOf(args.path), size: bytes.byteLength, version: String(prep.info.version ?? '') },
         }
-        if ((info.size ?? 0) > READ_CAP) return { ok: false, error: '文件过大（>8MB），不支持整文件预览' }
-        const content = await fs.readText(target)
-        return { ok: true, content, size: content.length, version: String(info.version ?? '') }
       } catch (error) {
         return { ok: false, error: '读取失败：' + String(error) }
       }
@@ -550,6 +614,7 @@ export function buildHandlers(
       const sc = await requireSession(ctx, args.sessionId)
       if ('err' in sc) return { ok: false, error: sc.err }
       const batches = parseArchive(await readArchiveText(ctx, sc.cwd)).filter((b) => b.cwd === sc.cwd)
+      const ws = findRemoteWs(sc.cwd)
       const entries = batches.map((b) => {
         const recs = Array.isArray(b.records) ? b.records : []
         const sum = recs.reduce((s, r) => {
@@ -560,7 +625,16 @@ export function buildHandlers(
           if (sm.superseded) s.superseded++
           return s
         }, { accepted: 0, rejected: 0, pending: 0, superseded: 0 })
-        return { at: b.at, lastAt: b.lastAt || b.at, path: b.path, batch: b.batch ?? null, reason: b.reason ?? null, nRecords: recs.length, summary: sum }
+        return {
+          at: b.at,
+          lastAt: b.lastAt || b.at,
+          path: b.path,
+          ...(ws ? { displayPath: remoteDisplayOf(b.path, ws) ?? undefined } : {}),
+          batch: b.batch ?? null,
+          reason: b.reason ?? null,
+          nRecords: recs.length,
+          summary: sum,
+        }
       })
       entries.sort((a, b) => (Number(b.batch ?? -1) - Number(a.batch ?? -1)) || (a.at < b.at ? 1 : -1))
       return { ok: true, entries }
@@ -847,22 +921,20 @@ export function buildHandlers(
     },
     'vscode.fileOpenSettingsGet': async () => {
       const settings = ctx.get('settings')
-      const descriptor = settings?.describe?.({ redactSecrets: true })?.find((item: { ns?: string }) => item.ns === FILE_OPEN_SETTINGS_NS)
-      const value = descriptor?.value as { fileOpenTool?: unknown } | undefined
-      return { ok: true, fileOpenTool: normalizeFileOpenTool(value?.fileOpenTool ?? FILE_OPEN_DEFAULT), integrationBaseUrl: await integrationBaseUrlOf(ctx), revision: descriptor?.revision }
+      const section = sectionOf(settings, FILE_OPEN_SETTINGS_NS)
+      const value = section?.value as { fileOpenTool?: unknown } | undefined
+      return { ok: true, fileOpenTool: normalizeFileOpenTool(value?.fileOpenTool ?? FILE_OPEN_DEFAULT), integrationBaseUrl: await integrationBaseUrlOf(ctx), revision: section?.revision }
     },
     'vscode.fileOpenSettingsUpdate': async (args) => {
       const settings = ctx.get('settings')
-      if (!settings?.update) return { ok: false, error: '设置服务不可用' }
-      try {
-        const patch: Record<string, unknown> = { fileOpenTool: normalizeFileOpenTool(args.fileOpenTool) }
-        if (typeof args.integrationBaseUrl === 'string' && args.integrationBaseUrl.trim()) patch.integrationBaseUrl = args.integrationBaseUrl.trim()
-        await settings.update(FILE_OPEN_SETTINGS_NS, patch, args.expectedRevision)
-        const descriptor = settings.describe?.({ redactSecrets: true })?.find((item: { ns?: string }) => item.ns === FILE_OPEN_SETTINGS_NS)
-        const value = descriptor?.value as { fileOpenTool?: unknown } | undefined
-        return { ok: true, fileOpenTool: normalizeFileOpenTool(value?.fileOpenTool), integrationBaseUrl: await integrationBaseUrlOf(ctx), revision: descriptor?.revision }
-      } catch (error) { return { ok: false, error: String(error) }
-      }
+      const patch: Record<string, unknown> = { fileOpenTool: normalizeFileOpenTool(args.fileOpenTool) }
+      if (typeof args.integrationBaseUrl === 'string' && args.integrationBaseUrl.trim()) patch.integrationBaseUrl = args.integrationBaseUrl.trim()
+      // 冲突自愈（0.1.7 SettingsConflictError 重读重试一次）与形状校验读取统一走 fileOpenSettings 工具
+      const result = await updateSection(settings, FILE_OPEN_SETTINGS_NS, patch, args.expectedRevision)
+      if (!result.ok) return { ok: false, error: result.error ?? '设置服务不可用' }
+      const section = sectionOf(settings, FILE_OPEN_SETTINGS_NS)
+      const value = section?.value as { fileOpenTool?: unknown } | undefined
+      return { ok: true, fileOpenTool: normalizeFileOpenTool(value?.fileOpenTool), integrationBaseUrl: await integrationBaseUrlOf(ctx), revision: section?.revision }
     },
     'compat': async () => ({ ok: true, report: await buildReport(ctx) }),
     'vscode.devFormGet': async () => ({ ok: true, devForm: readDevForm() }),
@@ -953,6 +1025,7 @@ export function buildHandlers(
         const inventory = await scanSessionInventory(home, sessionsArchiveRoot(home))
         const active = activeSessionIds(ctx)
         markActiveSessions(inventory.sessions, active)
+        markOfficialFlags(inventory.sessions, ctx)
         return { ok: true, ...inventory, activeIds: [...active] }
       } catch (error) {
         return { ok: false, error: '盘点失败：' + String(error) }
@@ -990,7 +1063,10 @@ export function buildHandlers(
     'edrv.perf.restore': async (args) => {
       try {
         const result = await restoreSession(dshHome(), sessionsArchiveRoot(dshHome()), args.workspaceKey, args.sessionId)
-        return result.ok ? { ok: true, restored: true } : { ok: false, error: result.error ?? '恢复失败' }
+        if (!result.ok) return { ok: false, error: result.error ?? '恢复失败' }
+        // 目录搬回后对齐官方归档标志（best-effort：服务缺失/调用失败不影响恢复结果，见 perf.unarchiveOfficial）
+        await unarchiveOfficial(ctx, args.sessionId)
+        return { ok: true, restored: true }
       } catch (error) {
         return { ok: false, error: '恢复失败：' + String(error) }
       }

package/src/shared/ai.ts

@@ -66,6 +66,12 @@ export interface AiConfigView {
   model: string
   /** 空 = 跟随模型默认（请求不携带 reasoningEffort）。 */
   effort: string
+  /** AI 任务模型（非补全场景）：空/缺省 = 跟随补全配置。 */
+  taskProvider?: string
+  /** AI 任务模型 id（与 taskProvider 成对；空/缺省 = 跟随补全配置）。 */
+  taskModel?: string
+  /** AI 任务模型思考档位（空/缺省 = 跟随补全配置的 effort）。 */
+  taskEffort?: string
 }
 
 /** AI 补全配置更新载荷（edrv.ai.configUpdate）。 */
@@ -75,6 +81,12 @@ export interface AiConfigPatch {
   model?: string
   /** 空 = 清除（跟随默认）。 */
   effort?: string
+  /** AI 任务模型（非补全场景）：空 = 清除（跟随补全配置）。 */
+  taskProvider?: string
+  /** AI 任务模型 id（与 taskProvider 成对更新）。 */
+  taskModel?: string
+  /** AI 任务模型思考档位：空 = 清除（跟随补全配置的 effort）。 */
+  taskEffort?: string
 }
 
 /**

package/src/shared/lsp.ts

@@ -125,6 +125,82 @@ export function decodeSemanticTokens(
   return out
 }
 
+/**
+ * LSP CompletionItemKind（协议 1-based）→ Monaco CompletionItemKind 枚举名（0-based）。
+ *
+ * 为什么按**名称**而不是编号直传：两侧枚举编号并不一致 —— LSP 2=Method，而 Monaco
+ * 0=Method。若把协议编号当 Monaco 编号塞回去，草稿纸上的「只差一位」会变成全表错位
+ * （属性显示成方法图标等）。用名称映射让两侧各自的编号在各自类型系统里解析，杜绝硬编码。
+ * 索引 i 对应 LSP kind i（索引 0 占位，协议从 1 起）。
+ * @author ddj 2026年09月22号
+ */
+export const LSP_COMPLETION_KIND_NAMES = [
+  '', 'Text', 'Method', 'Function', 'Constructor', 'Field', 'Variable', 'Class',
+  'Interface', 'Module', 'Property', 'Unit', 'Value', 'Enum', 'Keyword', 'Snippet',
+  'Color', 'File', 'Reference', 'Folder', 'EnumMember', 'Constant', 'Struct',
+  'Event', 'Operator', 'TypeParameter',
+] as const
+
+/** LSP InsertTextFormat：1=PlainText，2=Snippet。 */
+export const LSP_INSERT_TEXT_FORMAT_SNIPPET = 2
+
+/**
+ * LSP 补全项文本编辑范围（单 range 或 insert/replace 双 range 形态）。
+ * 两种形态由服务器任选，必须都能解析：只认一种会让另一家服务器的补全落点错位。
+ */
+export interface LspCompletionTextEdit {
+  range?: LspRange
+  insert?: LspRange
+  replace?: LspRange
+  newText: string
+}
+
+/** 归一化后的补全项（host 归一化；client 映射为 Monaco suggestion）。 */
+export interface LspCompletionItem {
+  label: string
+  kind?: number            // LSP CompletionItemKind 原始编号（client 经名称表转 Monaco）
+  detail?: string
+  documentation?: string
+  insertText?: string
+  insertTextFormat?: number
+  textEdit?: LspCompletionTextEdit
+  additionalTextEdits?: Array<{ range: LspRange; newText: string }>
+  sortText?: string
+  filterText?: string
+  preselect?: boolean
+  commitCharacters?: string[]
+  deprecated?: boolean
+  data?: unknown           // 原样透传，completionItem/resolve 需回传
+}
+
+/** 归一化后的补全列表（incomplete：服务器要求按已输入内容重查）。 */
+export interface LspCompletionList {
+  items: LspCompletionItem[]
+  incomplete: boolean
+  truncated?: boolean
+}
+
+/** 签名帮助中的单个参数（label 可为字符串或 [start, end] 元组，原样透传）。 */
+export interface LspParameterInformation {
+  label: string | [number, number]
+  documentation?: string
+}
+
+/** 归一化后的单个签名。 */
+export interface LspSignatureInformation {
+  label: string
+  documentation?: string
+  parameters: LspParameterInformation[]
+  activeParameter?: number
+}
+
+/** 归一化后的签名帮助结果。 */
+export interface LspSignatureHelp {
+  signatures: LspSignatureInformation[]
+  activeSignature: number
+  activeParameter: number
+}
+
 /** LSP 服务器能力子集：本插件会用到的方法。 */
 export interface LspServerCapabilities {
   definition: boolean
@@ -134,6 +210,9 @@ export interface LspServerCapabilities {
   workspaceSymbol: boolean
   hover: boolean
   semanticTokens: boolean
+  completion: boolean
+  completionResolve: boolean
+  signatureHelp: boolean
   semanticTokenTypes?: string[]
   semanticTokenModifiers?: string[]
 }

package/src/shared/nativeOpen.ts

@@ -0,0 +1,91 @@
+/**
+ * dsh-vscode-mode shared — 原生打开范围判定（host/client 双面契约）。
+ * 背景：DSH 文件预览双形态——本插件认领 `dsh-resource://file/**` 进 Monaco 编辑，
+ * 官方渲染器（Office 预览/不可预览提示/表格预览）看认领让位。本模块承载「原生打开」
+ * 范围的单一事实源：默认集 = 让位清单（插件本来就不认领的后缀），用户可经设置
+ * `nativeOpenExts`（逗号分隔）增删；host 的 Config schema 默认值与 client 的
+ * 文件树点击判定 / claim 认领判定共用，保证三处永不同源漂移。
+ * 决策沿袭（不因本模块迁移而变）：CSV/TSV **不在**默认集——官方 0.1.7 有表格预览，
+ * 但编辑器可编辑性优先，仅用户显式加入 nativeOpenExts 才让位（同 avif 例外先例）。
+ * 作者 ddj 2026年09月22号
+ */
+
+/**
+ * Office 文档后缀：官方 `dsh-client-ui-sidebar-documentpreview` 的 Office 渲染器
+ * 声明 `doc/docx/xls/xlsx/ppt/pptx`（0.1.6 起侧栏 Office 预览；0.1.7 扩展表格 CSV/TSV
+ * 只读预览——本清单刻意不含 csv/tsv，见文件头决策）。本插件让位官方（不认领），
+ * 否则会把这些文件路由进 Monaco 而丢掉官方预览。
+ */
+export const OFFICE_EXT: readonly string[] = ['doc', 'docx', 'xls', 'xlsx', 'ppt', 'pptx', 'odt', 'ods', 'odp', 'pages', 'numbers']
+
+/**
+ * 官方「不可预览二进制容器」清单（`UNVIEWABLE_BINARY_EXTENSIONS`，逐项取自
+ * `dsh-client-ui-sidebar-documentpreview/lib/client.js`）。这些后缀官方会给出
+ * 「无法预览」提示；本插件让位官方，避免把二进制当文本读成乱码。
+ *
+ * ⚠️ 刻意例外：官方清单含 `avif`，但本插件图片预览支持 avif（浏览器原生解码），
+ * 故从本表**移除** `avif` —— 保留本插件的图片预览优于官方的「不可预览」。
+ * @author ddj 2026年09月18号
+ */
+export const BLIND_EXT: readonly string[] = [
+  // 媒体
+  'mp4', 'mov', 'avi', 'mkv', 'webm', 'flv', 'wmv', 'm4v', 'mp3', 'wav', 'flac', 'ogg', 'm4a', 'aac', 'wma', 'opus',
+  // 归档
+  'zip', 'gz', 'tgz', 'bz2', 'xz', 'zst', '7z', 'rar', 'tar', 'jar',
+  // 可执行与库
+  'exe', 'dll', 'so', 'dylib', 'bin', 'o', 'class', 'pyc', 'wasm',
+  // 字体
+  'ttf', 'otf', 'woff', 'woff2', 'eot',
+  // 磁盘映像
+  'dmg', 'iso', 'img',
+  // 数据库与设计文件
+  'sqlite', 'db', 'psd', 'ai', 'sketch', 'tiff', 'tif', 'heic', 'heif',
+]
+
+/** 原生打开默认后缀集 = 让位清单并集（两清单元素天然互斥，直接拼接）。 */
+export const DEFAULT_NATIVE_EXT: readonly string[] = [...OFFICE_EXT, ...BLIND_EXT]
+
+/** 默认范围的设置序列（逗号分隔；Config schema 默认值与设置页回显同源）。 */
+export const DEFAULT_NATIVE_CSV: string = DEFAULT_NATIVE_EXT.join(',')
+
+/**
+ * 取 path 的 basename 后缀（小写、无点）；无后缀/隐藏文件返回 ''。
+ * @author ddj 2026年09月22号
+ * @param path 文件路径（`/` 或 `\` 分隔均可）
+ * @returns 小写后缀或 ''
+ */
+export function suffixOf(path: unknown): string {
+  const base = String(path ?? '').replace(/\\/g, '/').split('/').pop() ?? ''
+  const dot = base.lastIndexOf('.')
+  return dot > 0 ? base.slice(dot + 1).toLowerCase() : ''
+}
+
+/**
+ * 解析设置串为后缀集合：逗号分隔、去空白、去前导点、小写；空段丢弃。
+ * 解析失败/空串 → 空集合（= 不追加任何原生打开范围，让位仍走 deferToOfficial）。
+ * @author ddj 2026年09月22号
+ * @param csv 逗号分隔后缀串
+ * @returns 后缀集合
+ */
+export function parseExtCsv(csv: unknown): Set<string> {
+  const out = new Set<string>()
+  if (typeof csv !== 'string') return out
+  for (const raw of csv.split(',')) {
+    const item = raw.trim().replace(/^\./, '').toLowerCase()
+    if (item) out.add(item)
+  }
+  return out
+}
+
+/**
+ * 该路径是否命中「原生打开」范围（仅看用户配置集合；默认集语义由调用方
+ * 与 deferToOfficial 取并，保持两判定各司其职）。
+ * @author ddj 2026年09月22号
+ * @param path 文件路径
+ * @param exts 已解析的后缀集合（parseExtCsv 产物）
+ * @returns 是否命中
+ */
+export function inNativeOpen(path: unknown, exts: ReadonlySet<string>): boolean {
+  const ext = suffixOf(path)
+  return ext !== '' && exts.has(ext)
+}