@ 文件补全无法识别 Windows 目录软连接（junction / 指向目录的符号链接）

[substitute525]

所属包： @deepseek-ai/dsh（dsh web） · 组件： @deepseek-ai/dsh-file-reference-local

使用场景

我们会把多个独立项目通过软链接聚合到一个"虚拟项目"目录里。在 Windows 上这些链接是目录 junction（mklink /J 创建），例如：

C:\work\virtual-project
├─ service-a/   (junction → C:\work\real-projects\service-a)
├─ platform-b/  (junction → C:\work\real-projects\platform-b)
...

开发这个聚合模块时，我们经常需要引用那些链接项目里的文件（README、mapper XML、共享接口等），因此依赖聊天里的 @ 文件补全来找到并打开它们。

问题： @ 既不会列出这些软链接目录，也无法展开它们。

• 全局搜索 @service-a → 搜不到 service-a。
• 目录展开 @service-a/ → 列不出任何内容。

探查到的根因

在 dsh-file-reference-local 里，搜索由 WorkspaceFileSearch（位于 lib/index.js）实现。有两条路径都会把符号链接丢弃：

1. 全局索引扫描 — scanWorkspace 用 entry.isDirectory() 判断目录：

   if (entry.isDirectory()) { ... 入索引并递归 ... } else if (entry.isFile()) { ... }

   在 Windows 上，Node 会把这个 junction 报告为 Dirent.isSymbolicLink() === true、Dirent.isDirectory() === false。于是这个软链接目录既不会作为候选项，也不会被递归进去 → 它及其中所有内容对 @ 都不可见。

2. 目录展开 — resolveDisplayDirectory 逐段校验路径，并对任何符号链接一刀切拒绝：

   const status = await lstat(current);
   if (status.isSymbolicLink() || !status.isDirectory()) return void 0;

   所以 @dir/ 也无法穿过软链接目录。

我已在 Windows 上直接验证了 Node 的行为：对这些 junction 执行 readdir(..., { withFileTypes: true })，返回的都是 isDir=false, isSymlink=true；lstat 也报告 isSymbolicLink()===true。

建议的改进

当 @ 补全遇到"目标 stat 解析后是一个目录"的符号链接时，把它当作目录处理：

• 在 scanWorkspace / listDirectory 中：对 entry.isSymbolicLink() 且非 entry.isFile() 的条目，用 fs.stat（跟随链接）解析；如果目标是目录，则以 kind: "directory" 入索引并递归进去。
• 在 resolveDisplayDirectory 中：把"凡符号链接一律拒绝"改为基于 stat 的目录判断，使软链接目录可以被进入，同时仍然忽略"指向文件的链接"和悬空链接。
• 保留现有的 fromRoot 逃逸保护（路径仍是以 workspace 根为基准做普通字符串解析，因此即使 junction 指向根目录之外也是安全的）。

需要注意的权衡：跟随链接意味着索引可能把工作目录之外的大目录树也拉进来。一个保守的做法是只跟随解析后仍落在 workspace 根目录内的链接，和/或增加一个配置项（例如 followDirectoryLinks）以便按需关闭。已有的 maxEntries 上限会限制总的索引条目数。

[argszero]

两条代码路径都在上游 master（4e84901e64 = alpha.4）逐行确认，你的根因判断准确，但修复要注意一个安全约束：

1. 全局索引扫描（file-reference-local/src/search.ts）

• :221-228：if (entry.isDirectory()) { 入索引 + 递归 } else if (entry.isFile()) { 入索引 }——Windows junction 的 Dirent 是 isSymbolicLink()===true, isDirectory()===false, isFile()===false，两个分支都落空 → 不进索引、不递归，目录及其内容对 @ 全不可见。

2. 目录展开（同文件 :240-255 的 listDirectory + :257-280 的 resolveDisplayDirectory）

• :275 if (status.isSymbolicLink() || !status.isDirectory()) return undefined——per-segment lstat 对 junction 报 isSymbolicLink → 直接拒绝。listDirectory 里同样的 isDirectory/isFile 二分支也让 junction 目录列不出候选。

3. 安全约束（修复必须守住的）：resolveDisplayDirectory 一刀切拒 symlink 不是疏忽——@ 文件引用会把文件内容原文引用进 LLM 上下文。如果简单改成「遇到 symlink 就当作目录跟随」，一个指向工作区外的 junction（Windows 上 junction 可指向任意卷）就会变成任意文件读取通道：agent 只需 @C:\secret\... 就能把目标文件内容带进对话。所以正确修法不是「放行 symlink」，而是「解析后做 containment 校验」：

• 在 scanWorkspace 递归与 resolveDisplayDirectory 逐段校验处，对 isSymbolicLink()===true 的条目用 realpath（或 stat，stat 跟随链接）解析出真实目标路径；
• 校验目标仍在 workspace root 内（relative(root, realTarget) 不以 .. 开头、非绝对跨卷），通过才当作目录入索引/放行；
• 显示路径保留链接名，索引/读取走真实路径——与 fs-sandbox 的 containment 逻辑同构（同仓库已有 sameIdentity/isPathUnder 先例可参考）。

4. 测试：search.spec.ts 已存在；POSIX 上 fs.symlink(dir, target, 'dir') 产生的目录符号链接与 Windows junction 在 Dirent 层面同为 symlink，逻辑一致，无需 Windows 专属 fixture 就能覆盖新分支——补两类用例：链接目标在 root 内（应可索引/展开）+ 链接目标逃出 root（应拒绝）。

顺带：这是 Windows 路径处理域的又一例（此前 #1420 是 shell:true 参数路径带空格被拆碎），同域问题建议归一个 owner 视角统一审。若确认按 containment 方向修，我可以补一版搜索路径的 diff 草图。