dsh-vscode-mode 0.5.3 → 0.7.0

package/src/dap/protocol.ts

@@ -0,0 +1,80 @@
+/**
+ * dsh-vscode-mode host — DAP（Debug Adapter Protocol）消息纯类型与守卫。
+ * 帧格式与 LSP 相同（Content-Length 头），编解码直接复用 lsp/jsonrpc.ts。
+ * 消息形状只覆盖本插件消费的子集（DAP 3.x 常用面 + emmylua 适配器扩展）。
+ * 作者 ddj 2026年09月29号 / 2026年09月21号
+ */
+/** DAP 消息基型（请求/响应/事件的公共头）。 */
+export interface DapMessage {
+  seq?: number
+  type: 'request' | 'response' | 'event'
+}
+
+/** DAP 响应（按 request_seq 关联）。 */
+export interface DapResponse extends DapMessage {
+  type: 'response'
+  request_seq: number
+  success: boolean
+  command: string
+  message?: string
+  body?: unknown
+}
+
+/** DAP 事件。 */
+export interface DapEvent extends DapMessage {
+  type: 'event'
+  event: string
+  body?: unknown
+}
+
+/** DAP 请求（客户端 → 适配器）。 */
+export interface DapRequest extends DapMessage {
+  type: 'request'
+  command: string
+  arguments?: unknown
+}
+
+/** 客户端 → 适配器请求帧构造。 */
+export function dapRequest(seq: number, command: string, args?: unknown): DapRequest {
+  return args === undefined
+    ? { seq, type: 'request', command }
+    : { seq, type: 'request', command, arguments: args }
+}
+
+/** 响应守卫。 */
+export function isDapResponse(msg: DapMessage): msg is DapResponse {
+  return msg.type === 'response' && typeof (msg as Partial<DapResponse>).request_seq === 'number'
+}
+
+/** 事件守卫。 */
+export function isDapEvent(msg: DapMessage): msg is DapEvent {
+  return msg.type === 'event' && typeof (msg as Partial<DapEvent>).event === 'string'
+}
+
+/** 事件体安全取值。 */
+export function eventBody(event: DapEvent): Record<string, unknown> {
+  return event.body && typeof event.body === 'object' ? event.body as Record<string, unknown> : {}
+}
+
+/** 响应体安全取值。 */
+export function responseBody(response: DapResponse): Record<string, unknown> {
+  return response.body && typeof response.body === 'object' ? response.body as Record<string, unknown> : {}
+}
+
+/**
+ * initialize 请求参数（适配器协商口径：path 格式、行列 1 基）。
+ * @author ddj 2026年09月29号
+ * @param adapterId 适配器 id
+ */
+export function initializeArgs(adapterId: string): Record<string, unknown> {
+  return {
+    adapterID: adapterId,
+    locale: 'zh-cn',
+    linesStartAt1: true,
+    columnsStartAt1: true,
+    pathFormat: 'path',
+    supportsVariableType: true,
+    supportsVariablePaging: false,
+    supportsRunInTerminalRequest: false,
+  }
+}

package/src/dap/provider.ts

@@ -0,0 +1,49 @@
+/**
+ * dsh-vscode-mode host — 调试适配器规格解析：按调试类型从扩展清单声明（discovery）
+ * 解析 spawn 规格，通用不限定语言：
+ * - runtime='node' → node 跑 js 入口（emmylua 形态，等价旧 process.execPath 硬编码）；
+ * - 无 runtime → program 即原生可执行（clrdbg/monodbg 形态，args 为清单声明如 --interpreter=vscode）；
+ * - 其它 runtime 明确不支持（decl.available=false 带原因，不做假启动）。
+ * 旧版仅探测 tangzx.emmylua 两型（attach/new），由清单驱动后自然覆盖并扩展到任意适配器。
+ * 作者 ddj 2026年09月29号 / 2026年09月21号
+ */
+import { debuggerDecls } from './discovery.js'
+
+/** 适配器启动规格（spawn 参数）。 */
+export interface DapAdapterSpec {
+  /** 调试类型（= initialize.adapterID）。 */
+  type: string
+  /** 可执行文件（node 型 = node 本体；直启型 = 适配器本体）。 */
+  command: string
+  /** 启动参数（node 型 = [program]；直启型 = 清单声明 args）。 */
+  args: string[]
+  /** 扩展根目录（emmylua 兼容 shim 注入 extensionPath 用）。 */
+  extensionPath: string
+  /** 来源扩展 id（publisher.name；emmylua 兼容 shim 判定）。 */
+  extensionId: string
+  /** 可下断点扩展名（断点下发语言过滤；空 = 不限）。 */
+  exts: string[]
+  /** 探测描述（错误提示用）。 */
+  detail: string
+}
+
+/**
+ * 解析某调试类型的适配器启动规格。
+ * @author ddj 2026年09月29号 / 2026年09月21号
+ * @param type 调试类型（launch.json type = 清单 contributes.debuggers.type）
+ * @param force 强制重扫扩展清单（测试隔离用）
+ * @param home DSH home（缺省真实；测试可注入）
+ * @returns 启动规格；类型未发现 / 不可用 / runtime 不支持返回 null（原因见 discovery 声明）
+ */
+export function resolveAdapterSpec(type: string, force = false, home?: string): DapAdapterSpec | null {
+  const decl = debuggerDecls(force, home).find((d) => d.type === type)
+  if (!decl || !decl.available) return null
+  const base = { type, extensionPath: decl.extensionPath, extensionId: decl.extensionId, exts: decl.exts, detail: decl.extensionPath }
+  if (decl.runtime === 'node') {
+    return { ...base, command: process.execPath, args: [decl.program, ...decl.args] }
+  }
+  if (!decl.runtime) {
+    return { ...base, command: decl.program, args: [...decl.args] }
+  }
+  return null
+}

package/src/dap/rpc.ts

@@ -0,0 +1,192 @@
+/**
+ * dsh-vscode-mode host — 调试 RPC（edrv.dap.*）装配。
+ * 单例 DapSession + 适配器发现（扩展清单驱动，通用不限定语言）+ 进程枚举 +
+ * launch.json 读取（全量透传）+ findFile 反向匹配（chunkname → ripgrep 定向查找源文件）。
+ * 作者 ddj 2026年09月29号 / 2026年09月21号
+ */
+import { join } from 'node:path'
+import { mkdir, writeFile } from 'node:fs/promises'
+import type { Ctx } from '../store.js'
+import type { RpcHandlerMap } from '../shared/rpc.js'
+import { DAP_ACTIONS, DAP_LAUNCH_REL, DAP_LEGACY_LAUNCH_REL, requestOfConfig, type DapAction, type DapDebugConfig } from '../shared/dap.js'
+import { normalizeSourcePath, rankSourceCandidates } from './sourcePath.js'
+import { findFilesByChunk } from '../search/ripgrep.js'
+import { hasCmdPlaceholder, parseLaunchConfigs } from './launchConfig.js'
+import { dapConfigSnippets, annotateSnippets } from './configSnippets.js'
+import { filterProcesses, listProcesses } from './processList.js'
+import { resolveAdapterSpec } from './provider.js'
+import { debuggerDecls } from './discovery.js'
+import { DapSession } from './manager.js'
+import { debugRecord } from '../debugLog.js'
+import { log } from '../log.js'
+
+/**
+ * 解析工作区根为 subprocess 执行世界可见的真实路径。
+ * DAP 会话无 DSH Session 对象，不能让 fs.resolve('.') 落回 host 进程目录，
+ * 因此显式以 cwd 为基准解析 `.`（= cwd 本身）。
+ * @author ddj 2026年09月21号
+ * @param ctx DSH 上下文
+ * @param workspacePath 工作区绝对路径
+ * @returns 可交给 rg 的根路径；fs 不可用或解析失败返回空串
+ */
+async function rootPathOf(ctx: Ctx, workspacePath: string): Promise<string> {
+  const fs = ctx.get('fs')
+  if (!fs || !workspacePath) return ''
+  try {
+    const target = await fs.resolve('.', { cwd: workspacePath })
+    return fs.processPath(target) || ''
+  } catch (error) {
+    return ''
+  }
+}
+
+/**
+ * 创建调试 RPC（单例会话随插件装配创建，ctx.effect 里调 disposeDap 清理）。
+ * @author ddj 2026年09月29号
+ * @param ctx DSH 上下文
+ */
+export function createDapRpc(ctx: Ctx): { handlers: Partial<RpcHandlerMap>; dispose: () => void } {
+  const session = new DapSession({
+    findFiles: async (workspacePath, chunk) => {
+      const clean = normalizeSourcePath(chunk)
+      if (!clean) return []
+      // 工作区根需转换成 subprocess 执行世界可见的真实路径，再交给 rg 定向查找
+      const root = await rootPathOf(ctx, workspacePath)
+      if (!root) {
+        debugRecord(ctx, workspacePath, '[DEBUG findFiles] chunk=' + clean + ' root=(无法解析) candidates=0', 'debug')
+        return []
+      }
+      const candidates = await findFilesByChunk(ctx, root, clean)
+      const ranked = rankSourceCandidates(clean, candidates, workspacePath)
+      log.debug('[dap-trace] findFiles chunk=' + clean + ' cwd=' + workspacePath + ' root=' + root + ' candidates=' + ranked.length + ' first=' + (ranked[0] ?? ''))
+      debugRecord(ctx, workspacePath, '[DEBUG findFiles] chunk=' + clean + ' root=' + root + ' candidates=' + ranked.length + ' first=' + (ranked[0] ?? ''), 'debug')
+      return ranked
+    },
+    trace: (workspacePath, message) => debugRecord(ctx, workspacePath, message, 'debug'),
+  })
+
+  const handlers: Partial<RpcHandlerMap> = {
+    'edrv.dap.configs': async (args) => {
+      const configs = await readLaunchConfigs(ctx, args.workspacePath)
+      const adapters = debuggerDecls().map((d) => ({ type: d.type, label: d.label, available: d.available, reason: d.reason }))
+      return { ok: true, configs, adapters, source: configs.length ? 'launchjson' : 'none' }
+    },
+    'edrv.dap.snippets': async () => ({
+      ok: true,
+      // 与工具条同源裁决：不可用适配器的模板带 reason，client 下拉过滤
+      snippets: annotateSnippets(dapConfigSnippets(), debuggerDecls()),
+    }),
+    'edrv.dap.processes': async (args) => {
+      const items = filterProcesses(await listProcesses(), args.processName)
+      return { ok: true, items }
+    },
+    'edrv.dap.start': async (args) => {
+      const config = args.config
+      if (hasCmdPlaceholder(config)) {
+        return { ok: false, error: '配置含 ${command:...} 占位（VS Code 命令），本插件无法解析，请在 launch.json 中改为具体值' }
+      }
+      const spec = resolveAdapterSpec(config.type)
+      if (!spec) return { ok: false, error: unknownTypeMessage(config.type) }
+      let pid = args.pid && args.pid > 0 ? args.pid : undefined
+      if (requestOfConfig(config) === 'attach' && !pid && !config.processId) {
+        const resolved = await resolvePid(config.processName)
+        if (typeof resolved === 'string') return { ok: false, error: resolved }
+        pid = resolved
+      }
+      session.start(spec, config, args.workspacePath, pid)
+      return { ok: true, phase: 'starting' }
+    },
+    'edrv.dap.stop': async () => {
+      session.stop()
+      return { ok: true }
+    },
+    'edrv.dap.poll': async (args) => ({ ok: true, ...session.poll(args.since) }),
+    'edrv.dap.setBreakpoints': async (args) => {
+      const abs = join(args.workspacePath, args.file.replace(/\\/g, '/'))
+      return { ok: true, breakpoints: await session.setBreakpoints(abs, args.points) }
+    },
+    'edrv.dap.stackTrace': async () => ({ ok: true, frames: await session.stackTrace() }),
+    'edrv.dap.scopes': async (args) => ({ ok: true, scopes: await session.scopes(args.frameId) }),
+    'edrv.dap.variables': async (args) => ({ ok: true, variables: await session.variables(args.ref) }),
+    'edrv.dap.evaluate': async (args) => ({ ok: true, ...(await session.evaluate(args.expression, args.frameId)) }),
+    'edrv.dap.command': async (args) => {
+      if (!DAP_ACTIONS.includes(args.action as DapAction)) return { ok: false, error: '未知动作：' + args.action }
+      if (args.action === 'disconnect') session.stop()
+      else session.action(args.action as DapAction)
+      return { ok: true }
+    },
+  }
+
+  return { handlers, dispose: () => session.dispose() }
+}
+
+/**
+ * processName → pid：唯一命中直用；0 命中或多命中返回错误文案（客户端引导用 processes 列表选择）。
+ * @author ddj 2026年09月29号
+ * @param processName 进程名（标题/文件名包含匹配）
+ */
+async function resolvePid(processName?: string): Promise<number | string> {
+  const items = filterProcesses(await listProcesses(), processName)
+  if (items.length === 1) return items[0].pid
+  if (items.length === 0) return '未找到匹配进程：' + (processName || '(空)')
+  return '匹配到 ' + items.length + ' 个进程，请先在进程列表中选择（edrv.dap.processes）'
+}
+
+/**
+ * 读工作区调试配置：优先 `.dsh/launch.json`（插件专属）；缺失时从旧共用
+ * `.vscode/launch.json` 一次性迁移（只读 legacy 源、永不回写；复制失败当次
+ * 仍用 legacy 内容响应不丢配置，下次读重试）；都缺失 → 空表。
+ * @author ddj 2026年09月22号
+ * @param ctx DSH 上下文
+ * @param workspacePath 工作区绝对路径
+ * @returns 解析后的配置列表
+ */
+async function readLaunchConfigs(ctx: Ctx, workspacePath: string): Promise<DapDebugConfig[]> {
+  const fs = ctx.get('fs')
+  if (!fs || !workspacePath) return []
+  try {
+    const target = await fs.resolve(DAP_LAUNCH_REL, { cwd: workspacePath })
+    let text = ''
+    let exists = true
+    try {
+      text = String(await fs.readText(target) ?? '')
+    } catch {
+      exists = false
+    }
+    if (exists) return parseLaunchConfigs(text, workspacePath)
+    // 新文件缺失 → 读旧共用源：命中则本次以内存内容响应（写入失败不丢配置，下次读重试）
+    let legacy = ''
+    let legacyExists = true
+    try {
+      const source = await fs.resolve(DAP_LEGACY_LAUNCH_REL, { cwd: workspacePath })
+      legacy = String(await fs.readText(source) ?? '')
+    } catch {
+      legacyExists = false
+    }
+    if (!legacyExists) return []
+    try {
+      const realPath = fs.processPath(target)
+      await mkdir(join(realPath, '..'), { recursive: true })
+      await writeFile(realPath, legacy, 'utf8')
+      log.debug('[dap] 已迁移 ' + DAP_LEGACY_LAUNCH_REL + ' → ' + DAP_LAUNCH_REL + '（' + workspacePath + '）')
+    } catch (error) {
+      log.debug('[dap] launch.json 迁移失败（下次读重试，本次以旧源响应）：' + String(error))
+    }
+    return parseLaunchConfigs(legacy, workspacePath)
+  } catch (error) {
+    log.debug('[dap] launch.json 读取失败（视为无配置）：' + String(error))
+    return []
+  }
+}
+
+/**
+ * 未知调试类型的错误文案：列出已识别类型（含不可用原因），引导用户安装/排查。
+ * @author ddj 2026年09月21号
+ * @param type launch.json 中的调试类型
+ */
+function unknownTypeMessage(type: string): string {
+  const known = debuggerDecls()
+    .map((d) => d.type + (d.available ? '' : '（' + (d.reason ?? '不可用') + '）'))
+    .join(' / ')
+  return '未发现调试类型「' + type + '」的适配器（已识别：' + (known || '无，请安装带调试器的扩展') + '）'
+}

package/src/dap/sourcePath.ts

@@ -0,0 +1,82 @@
+/**
+ * dsh-vscode-mode host — DAP source 路径归一化与候选排序。
+ * 适配器可能上报绝对路径、工作区相对路径、file:// URI 或 Lua chunkname；
+ * 这里统一转换，避免调用栈只显示 rawFile 但无法跳转。
+ * 作者 ddj 2026年09月29号
+ */
+
+/** 统一路径分隔符并去掉 chunkname 的 @ 前缀。 */
+export function normalizeSourcePath(value: unknown): string {
+  let text = String(value ?? '').trim()
+  if (!text) return ''
+  if (/^file:\/\//i.test(text)) text = fileUriPath(text)
+  return text.replace(/^@/, '').replace(/\\/g, '/')
+}
+
+/** 将 file:// URI 转成本地路径（兼容 Windows 盘符与 UNC）。 */
+function fileUriPath(value: string): string {
+  try {
+    const url = new URL(value)
+    let path = decodeURIComponent(url.pathname)
+    if (url.hostname && url.hostname !== 'localhost') path = '//' + url.hostname + path
+    if (/^\/[A-Za-z]:/.test(path)) path = path.slice(1)
+    return path
+  } catch {
+    return value.replace(/^file:\/\//i, '')
+  }
+}
+
+/** 取路径 basename（大小写保持原样）。 */
+export function sourceBaseOf(value: unknown): string {
+  const path = normalizeSourcePath(value)
+  return path.split('/').pop() ?? ''
+}
+
+/** 规范化路径键（大小写不敏感，供候选缓存使用）。 */
+export function sourceKeyOf(value: unknown): string {
+  return normalizeSourcePath(value).toLowerCase()
+}
+
+/**
+ * 把 source 路径转换为工作区相对路径；工作区外路径保留规范化绝对路径，
+ * 不再返回空串，调用方仍可交给现有 tabPathOf/absoluteOf 继续处理。
+ */
+export function sourcePathOf(value: unknown, workspacePath: string): string {
+  const source = normalizeSourcePath(value)
+  if (!source) return ''
+  const root = normalizeSourcePath(workspacePath).replace(/\/+$/, '')
+  if (root && source.toLowerCase().startsWith((root + '/').toLowerCase())) {
+    return source.slice(root.length + 1)
+  }
+  return source
+}
+
+/**
+ * 对 findFile 候选按 chunkname 相关度排序：完整路径后缀 > 路径片段 > basename/stem，
+ * 同分时保持确定性字典序，避免同名 Lua 文件随机取第一项。
+ */
+export function rankSourceCandidates(chunk: string, files: string[], workspacePath: string): string[] {
+  const needle = normalizeSourcePath(chunk).toLowerCase()
+  const needleParts = needle.split('/').filter(Boolean)
+  const needleBase = sourceBaseOf(needle).toLowerCase()
+  const needleStem = needleBase.replace(/\.[^.]+$/, '')
+  return [...files].sort((a, b) => scoreSource(b, needle, needleParts, needleBase, needleStem, workspacePath) - scoreSource(a, needle, needleParts, needleBase, needleStem, workspacePath) || a.localeCompare(b))
+}
+
+/** 计算单个候选相关度。 */
+function scoreSource(file: string, needle: string, parts: string[], base: string, stem: string, workspacePath: string): number {
+  const rel = sourcePathOf(file, workspacePath).toLowerCase()
+  const fileBase = sourceBaseOf(rel).toLowerCase()
+  const fileStem = fileBase.replace(/\.[^.]+$/, '')
+  let score = 0
+  if (needle && (rel === needle || rel.endsWith('/' + needle) || needle.endsWith('/' + rel))) score += 100000
+  if (base && fileBase === base) score += 10000
+  if (stem && fileStem === stem) score += 5000
+  const relParts = rel.split('/').filter(Boolean)
+  let suffix = 0
+  for (let i = 1; i <= Math.min(parts.length, relParts.length); i++) {
+    if (parts[parts.length - i] !== relParts[relParts.length - i]) break
+    suffix += 1
+  }
+  return score + suffix * 100
+}

package/src/index.ts

@@ -13,7 +13,6 @@ import { handleRpc } from './rpc.js'
 import { newSearcher } from './search/orchestrator.js'
 import { newContentSearcher } from './search/content.js'
 import { installIsolation } from './mcpIsolation.js'
-import { dropFileIndex } from './workspace.js'
 import { cwdOf } from './registry.js'
 import { setupOpenSettings } from './fileOpenSettings.js'
 import { shellMenuLifecycle } from './integrate.js'
@@ -27,6 +26,7 @@ import { disposeAllServers, hookExitReclaim } from './lsp/transport.js'
 import { createAiRpc } from './ai/rpc.js'
 import { createFileVersions } from './fileVersions.js'
 import { createSvnRpc } from './svn.js'
+import { createDapRpc } from './dap/rpc.js'
 import { installRulesSection } from './rules.js'
 import { installSkillGroup } from './skills.js'
 import type { RpcHandlerMap } from './shared/rpc.js'
@@ -70,6 +70,9 @@ export function apply(ctx: Ctx, config?: unknown): void {
   /** SVN RPC（检测/更新/Tortoise 发射；settings 提供 svnPath/tortoisePath）。 */
   const svnRpc = createSvnRpc({ ctx, settings: openSettings })
   const svnHandlers: Partial<RpcHandlerMap> = svnRpc.handlers as Partial<RpcHandlerMap>
+  /** 调试 RPC（DAP 桥单例：spawn 扩展适配器 + 事件缓冲 + findFile 反向匹配）。 */
+  const dapRpc = createDapRpc(ctx)
+  const dapHandlers: Partial<RpcHandlerMap> = dapRpc.handlers
   /** 文件磁盘新鲜度观察器（客户端轮询 edrv.versions；变化时顺带失效目录树缓存）。 */
   const fileVersions = createFileVersions(ctx)
 
@@ -81,7 +84,6 @@ export function apply(ctx: Ctx, config?: unknown): void {
     const cwd = cwdOf(session as never)
     if (cwd) {
       registry.delete(cwd)
-      dropFileIndex(cwd)
       searcher.dispose(cwd)
       contentSearcher.dispose(cwd)
       disposeIndex(cwd)
@@ -90,7 +92,7 @@ export function apply(ctx: Ctx, config?: unknown): void {
     if (typeof sid === 'string') lspRpc.disposeSession(sid)
   })
 
-  registerRoutes(ctx, config, (method, args) => handleRpc(ctx, registry, method, args, searcher, contentSearcher, lspHandlers, aiHandlers, fileVersions, svnHandlers), (warning) => warnings.push(warning))
+  registerRoutes(ctx, config, (method, args) => handleRpc(ctx, registry, method, args, searcher, contentSearcher, lspHandlers, aiHandlers, fileVersions, svnHandlers, dapHandlers), (warning) => warnings.push(warning))
   installIsolation(ctx)
   // 系统集成生命周期：启动自动恢复右键菜单注册（marker 存在时）；插件卸载/reload 清理注册痕迹
   ctx.effect(() => shellMenuLifecycle(ctx))
@@ -104,6 +106,8 @@ export function apply(ctx: Ctx, config?: unknown): void {
   })
   // 卸载时清空文件版本基准表（观察器为模块内单例，不清会跨装配残留陈旧版本）
   ctx.effect(() => () => fileVersions.dispose())
+  // 卸载/重启时结束调试会话并强杀适配器子进程（防残留注入器/适配器孤儿）
+  ctx.effect(() => () => dapRpc.dispose())
   // 宿主进程退出回收：ctx.effect 清理不覆盖进程退出，缺此注册会留下跨重启的孤儿服务器
   hookExitReclaim()
 

package/src/lsp/providers.ts

@@ -214,8 +214,9 @@ export function sdkEnvOf(sdkRoot: string): Record<string, string> {
   return env
 }
 
-/** 读扩展目录 package.json 的 version（读取失败不影响入口使用，返回 undefined）。 */
-function manifestVersionOf(extDir: string): string | undefined {
+/** 读扩展目录 package.json 的 version（读取失败不影响入口使用，返回 undefined）。
+ * 导出供 dap/discovery 复用（扩展清单版本排序同口径，避免第二份实现）。 */
+export function manifestVersionOf(extDir: string): string | undefined {
   try {
     const manifest = JSON.parse(readFileSync(join(extDir, 'package.json'), 'utf8')) as { version?: unknown }
     return typeof manifest.version === 'string' ? manifest.version : undefined

package/src/reveal.ts

@@ -1,12 +1,16 @@
 /**
  * dsh-vscode-mode host — 在 OS 文件浏览器中打开/定位路径（reveal 能力）。
- * 纯函数 revealCommand 平台分发 + revealInExplorer 经 ctx.subprocess.spawn 发射
- * （argv 数组、无 shell 插值，沿 workspace/revert 的 subprocess 契约）。
+ * 纯函数 revealCommand 平台分发 + revealSpawnOpts 启动选项 + revealInExplorer 发射。
  * 文件 → 资源管理器选中定位；目录 → 打开目录；Linux 无通用定位协议 → 打开所在目录。
- * 作者 ddj 2026-08-27
+ *
+ * 刻意**不经** ctx.subprocess.spawn：DSH 的 Windows Job runner 硬编码
+ * `windowsHide: true`（dsh-subprocess-local 的 launchWindowsJob 与 runner 内部 spawn），
+ * 连 explorer.exe 的 GUI 窗口一并隐藏——RPC 回 ok:true 但窗口根本不出现。
+ * GUI 拉起属 fire-and-forget，用 node child_process + detached + unref 才贴合语义。
+ * 作者 ddj 2026年08月27号 / 2026年09月20号
  */
+import { spawn } from 'node:child_process'
 import { dirname } from 'node:path'
-import type { Ctx } from './store.js'
 
 /** reveal 结果（沿 revert.ts 的 Result 风格）。 */
 export type RevealResult = { ok: true } | { ok: false; error: string }
@@ -35,28 +39,35 @@ export function revealCommand(absPath: string, isDir: boolean, platform: NodeJS.
 }
 
 /**
- * 经 host subprocess 服务发射 opener（fire-and-forget 语义）。
- * Explorer 为 GUI 分离进程，非零退出码不视为失败；仅 spawn 级错误回失败。
- * @author ddj 2026年08月27号
- * @param ctx DSH host 上下文
+ * 构造 opener 子进程启动选项。
+ * `windowsHide` 必须为 **false**：置 true 会把 Explorer 等 GUI 窗口一起隐藏，
+ * 症状即「RPC 回 ok:true 但窗口不出现」（本文件头注释记录的回归）。
+ * @author ddj 2026年09月20号
+ * @param cwd 子进程工作目录（打开文件时用其父目录）
+ * @returns child_process.spawn 选项
+ */
+export function revealSpawnOpts(cwd: string): { cwd: string; stdio: 'ignore'; windowsHide: false; detached: true } {
+  return { cwd, stdio: 'ignore', windowsHide: false, detached: true }
+}
+
+/**
+ * 发射 opener 拉起 OS 文件浏览器（fire-and-forget 语义）。
+ * Explorer 为 GUI 分离进程，非零退出码不视为失败，故只等 spawn 事件即返回；
+ * 子进程脱离父进程组并 unref，避免阻塞宿主退出。
+ * @author ddj 2026年08月27号 / 2026年09月20号
  * @param absPath 绝对路径
  * @param isDir 是否为目录
  * @returns 成功或失败原因
  */
-export async function revealInExplorer(ctx: Ctx, absPath: string, isDir: boolean): Promise<RevealResult> {
-  const sub = ctx.get('subprocess')
-  if (!sub || typeof sub.spawn !== 'function') {
-    return { ok: false, error: '打开文件浏览器不可用：缺少 subprocess 服务' }
-  }
-  const { argv } = revealCommand(absPath, isDir)
+export async function revealInExplorer(absPath: string, isDir: boolean): Promise<RevealResult> {
+  const [program, ...args] = revealCommand(absPath, isDir).argv
+  if (!program) return { ok: false, error: '打开失败：opener 命令为空' }
   try {
-    const handle = sub.spawn({
-      argv,
-      cwd: dirname(absPath),
-      stdio: { stdout: { maxBytes: 1 << 16 }, stderr: { maxBytes: 1 << 16 }, stdin: 'ignore' },
-      graceMs: 10000,
+    await new Promise<void>((resolve, reject) => {
+      const child = spawn(program, args, revealSpawnOpts(dirname(absPath)))
+      child.once('spawn', () => { child.unref(); resolve() })
+      child.once('error', (error) => { reject(error) })
     })
-    await handle.done
     return { ok: true }
   } catch (error) {
     return { ok: false, error: '打开失败：' + String(error) }