dsh-vscode-mode 0.5.3 → 0.7.0

package/src/rpc.ts

@@ -20,8 +20,8 @@ import {
   resolveTarget,
   saveBucket,
 } from './store.js'
-import { mkdir, readFile, rm, stat, writeFile, readdir } from 'node:fs/promises'
-import { basename, join } from 'node:path'
+import { cp, mkdir, readFile, rename, rm, stat, writeFile, readdir } from 'node:fs/promises'
+import { basename, dirname, join } from 'node:path'
 import { archiveEntryFor, markDecision, recordResolved, reconstructOriginal } from './model.js'
 import type { Registry } from './registry.js'
 import { bucketOf, cwdOf, sessionOf } from './registry.js'
@@ -42,6 +42,7 @@ import { handoffOpen, pendingState, pollPending } from './externalHandoff.js'
 import { buildReport } from './compat.js'
 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 { revealInExplorer } from './reveal.js'
 import { dshHome, debugLogFile, pluginLogRoot } from './paths.js'
@@ -246,6 +247,106 @@ async function integrationBaseUrlOf(ctx: Ctx): Promise<string> {
   return raw || INTEGRATION_BASE_DEFAULT
 }
 
+// --region 文件操作（edrv.fs.*：资源管理器右键的新建/重命名/删除/复制/移动）
+
+/**
+ * 文件操作目标解析：工作区相对路径 → 绝对路径，并做工作区边界检查。
+ * edrv.fs.* 各方法共用（对齐 edrv.saveBinary 的 contains 护栏口径）。
+ * @author ddj 2026年09月22号
+ * @param ctx DSH 上下文
+ * @param session 当前会话
+ * @param rel 工作区相对路径
+ * @returns 绝对路径；缺 fs/越界/解析失败返回错误文案
+ */
+async function fsOpsTarget(ctx: Ctx, session: Session, rel: string): Promise<{ abs: string } | { err: string }> {
+  const fs = ctx.get('fs')
+  if (!fs) return { err: '缺少 fs' }
+  try {
+    const target = await resolveTarget(ctx, session, rel)
+    const rootTarget = await fs.resolve(policyOf(ctx, session)?.workspaceRoot ?? '.', {})
+    if (!fs.contains(rootTarget, target)) return { err: '拒绝操作：目标不在会话工作区内' }
+    return { abs: fs.processPath(target) }
+  } catch (error) {
+    return { err: '路径解析失败：' + String(error) }
+  }
+}
+
+/**
+ * 取异常的系统错误码（EEXIST/EXDEV 等分支判定用）。
+ * @author ddj 2026年09月22号
+ * @param error 捕获到的异常
+ * @returns 错误码；取不到返回空串
+ */
+function fsErrCode(error: unknown): string {
+  const code = (error as { code?: unknown } | null)?.code
+  return typeof code === 'string' ? code : ''
+}
+
+/**
+ * 复制/移动共用核心（edrv.fsCopy / edrv.fsMove）：目标目录存在 + 同名拒绝覆盖 +
+ * 「不能以自身或其子目录为目标」护栏；move 跨设备（EXDEV）回退「递归复制 + 删除源」。
+ * @author ddj 2026年09月22号
+ * @param ctx DSH 上下文
+ * @param sc requireSession 成功结果（session + cwd）
+ * @param args 请求载荷（from / toDir 均为工作区相对路径）
+ * @param mode copy = 复制；move = 移动
+ * @returns 成功返回 from/to 相对路径；失败返回错误文案
+ */
+async function fsTransfer(
+  ctx: Ctx,
+  sc: { session: Session; cwd: string },
+  args: { from: string; toDir: string },
+  mode: 'copy' | 'move',
+): Promise<{ from: string; to: string } | { err: string }> {
+  const fromRel = normalizeRel(args.from)
+  const toDirRel = normalizeRel(args.toDir)
+  if (fromRel === null || fromRel === '' || toDirRel === null) return { err: '路径不合法' }
+  if (isSubPath(fromRel, toDirRel)) return { err: '不能以自身或其子目录为目标' }
+  const src = await fsOpsTarget(ctx, sc.session, fromRel)
+  if ('err' in src) return src
+  const dir = await fsOpsTarget(ctx, sc.session, toDirRel)
+  if ('err' in dir) return dir
+  const dirInfo = await stat(dir.abs).catch(() => null)
+  if (!dirInfo || !dirInfo.isDirectory()) return { err: '目标目录不存在' }
+  const toRel = joinRelPath(toDirRel, baseNameOf(fromRel))
+  const dst = await fsOpsTarget(ctx, sc.session, toRel)
+  if ('err' in dst) return dst
+  const srcInfo = await stat(src.abs).catch(() => null)
+  if (!srcInfo) return { err: '源不存在' }
+  if (await stat(dst.abs).catch(() => null)) return { err: '目标目录已存在同名文件或目录' }
+  try {
+    await transferEntry(src.abs, dst.abs, mode)
+  } catch (error) {
+    return { err: (mode === 'copy' ? '复制失败：' : '移动失败：') + String(error) }
+  }
+  invalidateIndex(ctx, sc.cwd, fromRel)
+  invalidateIndex(ctx, sc.cwd, toRel)
+  return { from: fromRel, to: toRel }
+}
+
+/**
+ * 单条目复制/移动落盘（文件/目录通用；move 跨设备回退复制+删除源）。
+ * @author ddj 2026年09月22号
+ * @param absFrom 源绝对路径
+ * @param absTo 目标绝对路径
+ * @param mode copy = 复制；move = 移动
+ */
+async function transferEntry(absFrom: string, absTo: string, mode: 'copy' | 'move'): Promise<void> {
+  if (mode === 'copy') {
+    await cp(absFrom, absTo, { recursive: true, force: false, errorOnExist: true })
+    return
+  }
+  try {
+    await rename(absFrom, absTo)
+  } catch (error) {
+    if (fsErrCode(error) !== 'EXDEV') throw error
+    await cp(absFrom, absTo, { recursive: true, force: false, errorOnExist: true })
+    await rm(absFrom, { recursive: true })
+  }
+}
+
+// --endregion
+
 /** 各方法 handler 表（类型由 shared/rpc 的 RpcHandlerMap 约束）。 */
 export function buildHandlers(
   ctx: Ctx,
@@ -256,6 +357,7 @@ export function buildHandlers(
   aiHandlers?: Partial<RpcHandlerMap>,
   fileVersions?: FileVersions,
   svnHandlers?: Partial<RpcHandlerMap>,
+  dapHandlers?: Partial<RpcHandlerMap>,
 ): RpcHandlerMap {
   return {
     // edrv.lsp.* 由 createLspRpc 一次性提供（tracker 跨请求保留），这里并入。
@@ -264,6 +366,8 @@ export function buildHandlers(
     ...((aiHandlers ?? {}) as RpcHandlerMap),
     // svn.* 由 createSvnRpc 提供（SVN 检测/更新/Tortoise 发射），这里并入。
     ...((svnHandlers ?? {}) as RpcHandlerMap),
+    // edrv.dap.* 由 createDapRpc 提供（调试会话单例），这里并入。
+    ...((dapHandlers ?? {}) as RpcHandlerMap),
     'edrv.list': async (args) => {
       const sc = await requireSession(ctx, args.sessionId)
       if ('err' in sc) return { ok: false, error: sc.err }
@@ -333,6 +437,7 @@ export function buildHandlers(
       if (!fs) return { ok: false, error: '缺少 fs' }
       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') {
           // 带上解析后的真实路径：跳转失败时可直接看出是路径解析错还是目标本身不存在
@@ -366,6 +471,7 @@ export function buildHandlers(
       if (!fs) return { ok: false, error: '缺少 fs' }
       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: '文件不存在' }
         if ((info.size ?? 0) > READ_CAP) return { ok: false, error: '文件过大（>8MB），不支持差异重建' }
@@ -399,6 +505,7 @@ export function buildHandlers(
       if (!fs) return { ok: false, error: '缺少 fs' }
       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')
         // 版本守卫（客户端带回上次读取的版本）：文件在读取后被外部改过则拒绝写入，
         // 避免用陈旧缓冲静默覆盖外部改动；客户端未带 rev（旧版/无版本后端）时行为不变。
         const rev = typeof args.rev === 'string' && args.rev ? args.rev : null
@@ -421,6 +528,7 @@ export function buildHandlers(
       if (!fs) return { ok: false, error: '缺少 fs' }
       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: '文件不存在' }
         // fs 服务仅提供文本写（writeText/editText），二进制回写经 node:fs 直写解析后的
@@ -540,7 +648,7 @@ export function buildHandlers(
     },
     'edrv.dlog.reveal': async () => {
       // 打开日志根目录（OS 文件管理器；目录形态 → 直接打开）
-      const revealed = await revealInExplorer(ctx, pluginLogRoot(), true)
+      const revealed = await revealInExplorer(pluginLogRoot(), true)
       if (!revealed.ok) return { ok: false, error: revealed.error }
       return { ok: true, opened: true }
     },
@@ -598,13 +706,108 @@ export function buildHandlers(
         const info = await fs.stat(target)
         if (!info) return { ok: false, error: '路径不存在' }
         const abs = fs.processPath(target)
-        const outcome = await revealInExplorer(ctx, abs, info.type === 'directory')
+        const outcome = await revealInExplorer(abs, info.type === 'directory')
         if (!outcome.ok) return { ok: false, error: outcome.error }
         return { ok: true, revealed: abs }
       } catch (error) {
         return { ok: false, error: '打开失败：' + String(error) }
       }
     },
+    'edrv.fsCreateFile': async (args) => {
+      // 新建文件（资源管理器右键「新建文件…」）：空内容独占创建（同名拒绝），
+      // 名称可含 a/b.c 嵌套段（父目录按需创建）；名称校验与客户端弹窗共用 shared/fsNames。
+      const sc = await requireSession(ctx, args.sessionId)
+      if ('err' in sc) return { ok: false, error: sc.err }
+      const bad = checkNewName(args.path)
+      if (bad) return { ok: false, error: bad }
+      const r = await fsOpsTarget(ctx, sc.session, args.path)
+      if ('err' in r) return { ok: false, error: r.err }
+      try {
+        await mkdir(dirname(r.abs), { recursive: true })
+        await writeFile(r.abs, '', { flag: 'wx' })
+      } catch (error) {
+        const code = fsErrCode(error)
+        return { ok: false, error: code === 'EEXIST' ? '已存在同名文件或目录' : '新建文件失败：' + String(error) }
+      }
+      invalidateIndex(ctx, sc.cwd, args.path)
+      return { ok: true, path: args.path }
+    },
+    'edrv.fsCreateDir': async (args) => {
+      // 新建文件夹（资源管理器右键「新建文件夹」）：名称可含嵌套段（父目录按需创建），已存在拒绝。
+      const sc = await requireSession(ctx, args.sessionId)
+      if ('err' in sc) return { ok: false, error: sc.err }
+      const bad = checkNewName(args.path)
+      if (bad) return { ok: false, error: bad }
+      const r = await fsOpsTarget(ctx, sc.session, args.path)
+      if ('err' in r) return { ok: false, error: r.err }
+      try {
+        await mkdir(dirname(r.abs), { recursive: true })
+        await mkdir(r.abs)
+      } catch (error) {
+        const code = fsErrCode(error)
+        return { ok: false, error: code === 'EEXIST' ? '已存在同名文件或目录' : '新建文件夹失败：' + String(error) }
+      }
+      invalidateIndex(ctx, sc.cwd, args.path)
+      return { ok: true, path: args.path }
+    },
+    'edrv.fsRename': async (args) => {
+      // 重命名（仅名称段、同父目录内）：目标已存在拒绝；名称未变化按幂等成功返回。
+      const sc = await requireSession(ctx, args.sessionId)
+      if ('err' in sc) return { ok: false, error: sc.err }
+      const bad = checkRenameName(args.newName)
+      if (bad) return { ok: false, error: bad }
+      const fromRel = normalizeRel(args.path)
+      if (fromRel === null || fromRel === '') return { ok: false, error: '路径不合法' }
+      const toRel = joinRelPath(parentRelOf(fromRel), args.newName)
+      if (toRel === fromRel) return { ok: true, from: fromRel, to: fromRel }
+      const src = await fsOpsTarget(ctx, sc.session, fromRel)
+      if ('err' in src) return { ok: false, error: src.err }
+      const dst = await fsOpsTarget(ctx, sc.session, toRel)
+      if ('err' in dst) return { ok: false, error: dst.err }
+      if (!(await stat(src.abs).catch(() => null))) return { ok: false, error: '源不存在' }
+      try {
+        await rename(src.abs, dst.abs)
+      } catch (error) {
+        const code = fsErrCode(error)
+        const exists = code === 'EEXIST' || code === 'ENOTEMPTY' || code === 'EPERM'
+        return { ok: false, error: exists ? '已存在同名文件或目录' : '重命名失败：' + String(error) }
+      }
+      invalidateIndex(ctx, sc.cwd, fromRel)
+      invalidateIndex(ctx, sc.cwd, toRel)
+      return { ok: true, from: fromRel, to: toRel }
+    },
+    'edrv.fsDelete': async (args) => {
+      // 删除（文件/文件夹递归；「删除/永久删除」共用）：根拒绝；破坏性由客户端确认框把关。
+      const sc = await requireSession(ctx, args.sessionId)
+      if ('err' in sc) return { ok: false, error: sc.err }
+      const rel = normalizeRel(args.path)
+      if (rel === null || rel === '') return { ok: false, error: '路径不合法' }
+      const r = await fsOpsTarget(ctx, sc.session, rel)
+      if ('err' in r) return { ok: false, error: r.err }
+      try {
+        await rm(r.abs, { recursive: true })
+      } catch (error) {
+        return { ok: false, error: '删除失败：' + String(error) }
+      }
+      invalidateIndex(ctx, sc.cwd, rel)
+      return { ok: true, path: rel }
+    },
+    'edrv.fsCopy': async (args) => {
+      // 复制到目标目录（文件/文件夹递归）：同名拒绝覆盖（细节见 fsTransfer）。
+      const sc = await requireSession(ctx, args.sessionId)
+      if ('err' in sc) return { ok: false, error: sc.err }
+      const r = await fsTransfer(ctx, sc, args, 'copy')
+      if ('err' in r) return { ok: false, error: r.err }
+      return { ok: true, from: r.from, to: r.to }
+    },
+    'edrv.fsMove': async (args) => {
+      // 移动到目标目录（文件/文件夹）：同名拒绝覆盖（细节见 fsTransfer）。
+      const sc = await requireSession(ctx, args.sessionId)
+      if ('err' in sc) return { ok: false, error: sc.err }
+      const r = await fsTransfer(ctx, sc, args, 'move')
+      if ('err' in r) return { ok: false, error: r.err }
+      return { ok: true, from: r.from, to: r.to }
+    },
     'mcp.list': async () => ({ ok: true, ...listMcp(ctx) }),
     'mcp.save': async (args) => {
       try { return { ok: true, server: await saveMcp(ctx, args.config) } }
@@ -951,8 +1154,9 @@ export async function handleRpc<M extends RpcMethod>(
   aiHandlers?: Partial<RpcHandlerMap>,
   fileVersions?: FileVersions,
   svnHandlers?: Partial<RpcHandlerMap>,
+  dapHandlers?: Partial<RpcHandlerMap>,
 ): Promise<RpcResult<M>> {
-  const handlers = buildHandlers(ctx, registry, searcher, contentSearcher, lspHandlers, aiHandlers, fileVersions, svnHandlers)
+  const handlers = buildHandlers(ctx, registry, searcher, contentSearcher, lspHandlers, aiHandlers, fileVersions, svnHandlers, dapHandlers)
   const handler = handlers[method]
   if (!handler) return { ok: false, error: '未知方法: ' + String(method) } as RpcResult<M>
   return handler(args)

package/src/search/ripgrep.ts

@@ -15,7 +15,12 @@ const STDOUT_CAP = 4 << 20
 const STDERR_CAP = 64 << 10
 const GRACE_MS = 20_000
 
-/** 默认排除目录（文件/内容搜索共用，导出供 provider 复用）。 */
+/**
+ * 默认排除目录（文件/内容搜索共用，导出供 provider 复用）。
+ * 语义为**大小写敏感**的路径段匹配：`build` 只排除小写构建产物目录，
+ * 不得用 `--glob-case-insensitive` 之类的全局开关，「Module/Build」这类
+ * 源码目录（如 IslandSplash 的 Module/Build/Logic）必须保持可搜索。
+ */
 export const EXCLUDES = [
   'node_modules', '.git', '.tmp', '.cache', 'dist', 'build', 'vendor',
   'coverage', '__pycache__', '.pnpm-store', '.npm-cache', '.codegraph', '.workbuddy',
@@ -52,15 +57,32 @@ interface SearchSubprocess {
 }
 
 /**
- * 将 query 转成 rg 的字面 glob。
- * @author ddj 2026年08月24号
- * @param query 已规范化 query
+ * 将查询文本转成大小写不敏感的 rg 正选 glob。
+ * 逐字符把有大小写的字母展开成 `[aA]` 字符类，**不用**大小写不敏感开关：
+ * ① 全局 `--glob-case-insensitive` 会把 `-g/--glob` 全部当成 `--iglob`，
+ *    连带让 `!**\/build/**` 大小写不敏感，从而排除 `Module/Build/` 这类源码目录
+ *    （Ctrl+P 搜 BuildLogic 恒「无匹配文件」）；
+ * ② 把查询词改用 `--iglob` 也不行——rg 的正选 glob 会覆盖全部黑名单 glob，
+ *    node_modules/.git 等排除项集体失效。
+ * 字符类方案同时满足「查询不区分大小写」且「排除项保持大小写敏感」。
+ * @author ddj 2026年08月24号 / 2026年09月20号
+ * @param query 已规范化查询文本
  * @returns 安全 glob
  */
 export function queryGlob(query: string): string {
   const value = pathText(query)
-  const escaped = value.replace(/[\*?\[\]{}!]/g, (char) => '\\' + char)
-  return '**/*' + escaped + '*'
+  let body = ''
+  for (const char of value) {
+    const lower = char.toLowerCase()
+    const upper = char.toUpperCase()
+    // 有大小写之分的字符（单字符映射，避开 ß→SS 这类长度变化）→ 字符类
+    if (lower !== upper && lower.length === 1 && upper.length === 1) {
+      body += '[' + lower + upper + ']'
+      continue
+    }
+    body += /[\*?\[\]{}!]/.test(char) ? '\\' + char : char
+  }
+  return '**/*' + body + '*'
 }
 
 /**
@@ -159,6 +181,24 @@ export function rgExitFailure(code: number | null | undefined, stderrText: strin
   return { kind: 'hard', message: 'ripgrep 退出码：' + String(code) + (detail ? '（' + detail + '）' : '') }
 }
 
+/**
+ * 构造文件搜索 rg argv（查询 glob 大小写不敏感，排除 glob 大小写敏感）。
+ * 大小写不敏感**只能**靠 queryGlob 的字符类实现：全局 `--glob-case-insensitive`
+ * 会波及排除项（误排除 `Module/Build/`），查询词用 `--iglob` 又会覆盖全部黑名单 glob。
+ * @author ddj 2026年09月20号
+ * @param binary rg 可执行文件路径
+ * @param root 搜索根目录
+ * @param query 已规范化查询文本
+ * @returns 完整 argv（末位为根目录）
+ */
+export function filesArgv(binary: string, root: string, query: string): string[] {
+  const argv = [binary, '--no-config', '--files', '--hidden', '--no-ignore', '--glob', queryGlob(query)]
+  for (const excluded of EXCLUDES) argv.push('--glob', '!**/' + excluded + '/**')
+  for (const excluded of FILE_EXCLUDES) argv.push('--glob', '!' + excluded)
+  argv.push('--', root)
+  return argv
+}
+
 /**
  * 使用打包 ripgrep 搜索工作区文件。
  * @author ddj 2026年08月24号
@@ -172,12 +212,8 @@ export async function searchRipgrep(input: WorkspaceSearchInput): Promise<Worksp
   if (!binary) throw new Error('ripgrep 不可用')
   const root = input.root ?? await searchRoot(input.ctx, input.session)
   const query = prepareQuery(input.query)
-  const argv = [binary, '--no-config', '--files', '--hidden', '--no-ignore', '--glob-case-insensitive', '--glob', queryGlob(query.text)]
-  for (const excluded of EXCLUDES) argv.push('--glob', '!**/' + excluded + '/**')
-  for (const excluded of FILE_EXCLUDES) argv.push('--glob', '!' + excluded)
-  argv.push('--', root)
   const handle = sub.spawn({
-    argv,
+    argv: filesArgv(binary, root, query.text),
     cwd: root,
     stdio: { stdin: 'ignore', stdout: { maxBytes: STDOUT_CAP }, stderr: { maxBytes: STDERR_CAP } },
     graceMs: GRACE_MS,
@@ -202,6 +238,86 @@ export async function searchRipgrep(input: WorkspaceSearchInput): Promise<Worksp
   return { ...parsed, source: 'ripgrep' }
 }
 
+/**
+ * 构造 chunkname 定向查找的 rg argv。
+ * 与 {@link filesArgv} 同源（同样的排除 glob 与大小写口径），差异只在查询 glob 由
+ * chunkname 推导：chunkname 可能带 chunk 前缀（`@`）与无扩展名 stem，故先剥 `@`、
+ * 取 basename、去掉扩展名后作为片段匹配，仍走 {@link queryGlob} 的字符类方案
+ * ——避免 `--glob-case-insensitive` 波及排除项（见 queryGlob 注释）。
+ * @author ddj 2026年09月21号
+ * @param binary rg 可执行文件路径
+ * @param root 搜索根目录
+ * @param chunk 适配器上报的 chunkname
+ * @returns 完整 argv（末位为根目录）；chunk 为空时返回 null
+ */
+export function chunkFilesArgv(binary: string, root: string, chunk: string): string[] | null {
+  const clean = normalizeChunk(chunk)
+  if (!clean) return null
+  const argv = [binary, '--no-config', '--files', '--hidden', '--no-ignore', '--glob', queryGlob(clean)]
+  for (const excluded of EXCLUDES) argv.push('--glob', '!**/' + excluded + '/**')
+  for (const excluded of FILE_EXCLUDES) argv.push('--glob', '!' + excluded)
+  argv.push('--', root)
+  return argv
+}
+
+/**
+ * chunkname → 用于片段匹配的纯文件名片段。
+ * 剥 `@` 前缀、统一分隔符、取 basename、去掉扩展名（xLua chunkname 惯例不含扩展名），
+ * 使 `GuideSystemMgr` 能命中 `GuideSystemMgr.lua`。
+ * @author ddj 2026年09月21号
+ * @param chunk 适配器上报的 chunkname
+ * @returns 纯片段（空输入返回空串）
+ */
+export function normalizeChunk(chunk: string): string {
+  const text = String(chunk ?? '').replace(/^@/, '').replaceAll('\\', '/').trim()
+  if (!text) return ''
+  const base = text.split('/').pop() ?? ''
+  return base.replace(/\.[^.]+$/, '')
+}
+
+/**
+ * 按 chunkname 定向查找工作区文件（DAP findFile 反向匹配专用）。
+ *
+ * 为什么不用工作区全量文件索引：22 万文件的 Unity 工程里，全量枚举按到达序截断，
+ * `Assets/Scripts/Lua/**` 会被 `GameData`/`Entitas` 等目录挤出配额，导致断点命中后
+ * 无法定位源文件（实测前 6000 条中 .lua 数为 0）。此处改为让 rg 在遍历时过滤，
+ * 命中规模与工作区总规模无关（实测同一工作区 0.37s 返回正确结果）。
+ * @author ddj 2026年09月21号
+ * @param ctx DSH 上下文
+ * @param root 工作区根（subprocess 可访问路径）
+ * @param chunk 适配器上报的 chunkname
+ * @param maxResults 候选上限
+ * @returns 绝对路径候选（任何失败都返回空数组，不抛错）
+ */
+export async function findFilesByChunk(ctx: Ctx, root: string, chunk: string, maxResults = 50): Promise<string[]> {
+  const sub = ctx.get('subprocess') as SearchSubprocess | undefined
+  const binary = ripgrepPath()
+  if (!sub || !binary || !root) return []
+  const argv = chunkFilesArgv(binary, root, chunk)
+  if (!argv) return []
+  let handle: SearchHandle
+  try {
+    handle = sub.spawn({
+      argv,
+      cwd: root,
+      stdio: { stdin: 'ignore', stdout: { maxBytes: STDOUT_CAP }, stderr: { maxBytes: STDERR_CAP } },
+      graceMs: GRACE_MS,
+    })
+  } catch (error) {
+    return []
+  }
+  let code: number | null | undefined
+  try {
+    const outcome = await handle.done
+    code = outcome.exitCode ?? outcome.code
+  } catch (error) {
+    return []
+  }
+  // 0=有命中 1=无命中 2=部分不可访问（已收集结果仍有效）：其余视为失败
+  if (code !== 0 && code !== 1 && code !== 2) return []
+  return parseOutput(handle, maxResults).files
+}
+
 /**
  * 构造 ripgrep provider。
  * @author ddj 2026年08月24号