BUG: 超出工作区（Windows·SMB映射驱动器）File operations judged as "out of workspace"

[arcqiufeng]

DSH 问题报告（Windows · SMB 映射驱动器）：对当前工作区路径操作被判定为“超出工作区”

一、问题概述

在 Windows 上以网络共享（映射驱动器）路径创建 DSH 项目工作区后，在对当前工作区内的路径执行文件操作（读写/编辑等）时，被判定为“超出工作区”（out of workspace / 越界），导致操作被拒。

用户提供的是映射驱动器路径（如 Z:\...），DSH 内部将工作区解析为 UNC 路径（\\<server>\<share>\...），随后沙箱在对工作区边界进行判断时，对这两种路径形态的判断结果不一致，从而误判当前路径越界。

二、环境

• 操作系统：Windows（process.platform === 'win32'）
• 文件服务：NAS 网络共享（SMB），映射盘 Z: → \\<server>\<share>
• DSH 版本：@deepseek-ai/dsh 0.1.0-rc.7（npm 安装）

三、根因分析

对本地安装的 DSH 源码（node_modules/@deepseek-ai/dsh-*）排查，问题与工作区路径的规范化方式有关。

@deepseek-ai/dsh-fs-local/lib/index.js 的 resolveLocalTarget() 使用 node:fs/promises 的 realpath() 解析路径：

// dsh-fs-local/lib/index.js
async function resolveLocalTarget(cwd, path) {
  const displayPath = resolve(cwd, path);
  // ...
  targetKey: FsTargetKey(await realpath(displayPath))
}

在 Windows 上，对映射盘（Z:\...）执行 realpath() 会得到其底层 UNC 规范路径（\\<server>\<share>\...）。当工作区根被规范化为 UNC，而某些操作/路径仍以盘符（Z:\...）形态出现时，沙箱的“工作区包含/边界”判断（如 dsh-fs-local 的 contains() 等）在两种形态之间比较可能出现不一致，从而把工作区内的路径误判为越界（超出工作区）。

说明：以上为基于本地源码的初步定位，最终以上报后维护团队确认的根因为准。

四、影响与一连串后果

该问题会引发一连串连锁后果，具体如下：

1. 核心问题：对当前工作区内的路径执行文件操作（读写/编辑等）被判定为“超出工作区”而被拒绝，正常作业无法进行。
2. 路径形态不一致导致误判：同样的路径，以盘符（Z:\...）和以 UNC（\\<server>\<share>\...）两种形态出现时，工作区边界判断结果不一致，造成“明明在工作区内却报越界”的困惑。
3. 交互/界面受影响：工作区根被规范化为 UNC 后，依赖该路径的界面展示与操作出现异常，文件夹/路径显示不稳定。
4. 第三方插件连锁表现：部分第三方文件浏览插件（如 Better Sidebar）因其自身的绝对路径判断规则（POSIX 语义，只认 / 开头的路径）不识别 UNC，会把工作区路径报为“not an absolute path”。此为上述问题的连锁表现，属第三方插件行为，并非官方 DSH 的功能缺陷，仅用于说明问题影响范围。

五、建议修复方向（供参考）

1. 统一 Windows 工作区路径的形态：将工作区根与操作路径统一规范化为同一形态（盘符或 UNC）后再做“包含/边界”比较，避免盘符与 UNC 混用导致误判。
2. 在 Windows 上使工作区根与 realpath 结果保持一致，使边界判断与用户所提供路径形态一致。

六、复现步骤（供维护者复现）

1. 在 Windows 上把网络共享映射为盘符（例如 net use Z: \\<server>\<share>）。
2. 用该盘符路径（Z:\<项目>\<子目录>）创建/打开一个 DSH 项目工作区。
3. 对当前工作区内的路径执行文件操作。
4. 观察：操作被判定为“超出工作区”（out of workspace）而被拒绝；并观察由此引发的上述一连串后果。

---

DSH Issue Report (Windows · SMB mapped drive): File operations on paths inside the current workspace are judged as "out of workspace"

1. Problem Summary

On Windows, after creating a DSH project workspace using a network-share (mapped drive) path, file operations (read/write/edit, etc.) on paths inside the current workspace are judged as "out of workspace" and rejected.

The user provides a mapped-drive path (e.g. Z:\...); DSH internally resolves the workspace to a UNC path (\\<server>\<share>\...). When the sandbox later checks the workspace boundary, it evaluates the two path forms (drive letter vs UNC) inconsistently, so a path inside the workspace is misjudged as out of bounds.

2. Environment

• OS: Windows (process.platform === 'win32')
• Storage: NAS network share (SMB), mapped drive Z: → \\<server>\<share>
• DSH version: @deepseek-ai/dsh 0.1.0-rc.7 (installed via npm)

3. Root Cause Analysis

After inspecting the locally installed DSH source (node_modules/@deepseek-ai/dsh-*), the issue relates to how the workspace path is canonicalized.

resolveLocalTarget() in @deepseek-ai/dsh-fs-local/lib/index.js resolves paths with realpath() from node:fs/promises:

// dsh-fs-local/lib/index.js
async function resolveLocalTarget(cwd, path) {
  const displayPath = resolve(cwd, path);
  // ...
  targetKey: FsTargetKey(await realpath(displayPath))
}

On Windows, calling realpath() on a mapped drive (Z:\...) returns its underlying canonical UNC path (\\<server>\<share>\...). When the workspace root is canonicalized to UNC but some operations/paths still appear in drive-letter form (Z:\...), the sandbox's "workspace containment/boundary" checks (e.g. contains() in dsh-fs-local) may compare the two forms inconsistently, misjudging an in-workspace path as out of bounds.

Note: the above is a preliminary localization based on local source; the root cause confirmed by the maintainers after escalation takes precedence.

4. Impact and Chain of Consequences

This issue triggers a chain of consequences, as follows:

1. Core issue: File operations (read/write/edit, etc.) on paths inside the current workspace are judged as "out of workspace" and rejected, blocking normal work.
2. Inconsistent path-form checks cause misjudgment: The same path, when appearing in drive-letter form (Z:\...) versus UNC form (\\<server>\<share>\...), yields inconsistent workspace-boundary results, causing confusion ("why is an in-workspace path reported as out of bounds").
3. UI/interaction affected: Once the workspace root is canonicalized to UNC, interface display and operations that depend on that path behave abnormally; folder/path display becomes unstable.
4. Third-party plugin knock-on: Some third-party file-browsing plugins (e.g. Better Sidebar) use their own absolute-path rules (POSIX semantics, only accepting paths starting with /) and therefore do not recognize UNC, reporting the workspace path as "not an absolute path". This is a knock-on effect of the above issue and is third-party plugin behavior — it is not an official DSH functionality defect, and is mentioned only to illustrate the extent of the impact.

5. Suggested Fix (for reference)

1. Unify the Windows workspace path form: normalize both the workspace root and the operation path to the same form (drive letter or UNC) before performing "containment/boundary" comparisons, to avoid mismatches caused by mixing drive-letter and UNC forms.
2. Keep the workspace root and the realpath result consistent on Windows, so the boundary check matches the path form the user provided.

6. Reproduction Steps (for maintainers)

1. On Windows, map a network share to a drive letter (e.g. net use Z: \\<server>\<share>).
2. Create/open a DSH project workspace using that drive-letter path (Z:\<project>\<subdir>).
3. Perform a file operation on a path inside the current workspace.
4. Observe: the operation is judged as "out of workspace" and rejected; and observe the chain of consequences triggered as described above.

[PensiveFei]

你的根因分析基本正确，我在源码里也验证了：dsh-fs-local 的 resolveLocalTarget() 确实用 realpath() 生成 targetKey（index.js:159），Windows 上对映射盘 Z:\ 调用 realpath() 会返回底层 UNC 路径 \\server\share\...；而 contains() 用 relative() 比较时，盘符形态和 UNC 形态会被当成不同路径，导致工作区内路径被误判为越界。

临时 workaround：创建/打开工作区时直接用 UNC 路径（\\server\share\项目）而不是盘符 Z:\，这样两侧路径形态一致，可绕过误判。

你的修复建议（统一 Windows 路径形态后再比较）方向是对的，建议把它整理成正式的 bug 报告给维护团队，或直接提 PR。

[arcqiufeng]

哦。我以为在这里发个贴就算是报告给维护团队了呢。

[liebesleid-liebesfreud]

我也遇到了这个问题，希望官方能够采纳

[Emil-oss]

团队场景：工作区在 NAS/SMB 共享上（Windows 映射 \\server\share\...，Linux 挂载
/mnt/nas/...）。DSH 大部分文件操作可用，但网络路径下部分工具体验差：

1. glob（文件搜索工具）在 SMB/UNC 路径上超时/中断（目录树大 + 网络延迟）；
2. 目录枚举、递归扫描明显比本地慢（每个 stat/readdir 一次网络往返）；
3. Windows 上部分 API 对 \\ 前缀的 UNC 路径处理不完整（与本地盘符行为不一致）。

复现

• 环境：Windows 11 + DSH Desktop，工作区 = \\192.168.1.59\rpa\...（SMB 共享，几千个文件）
• 操作：在工作区执行 glob 递归搜索 → 30s+ 超时无结果；同目录本地盘则秒回

期望

1. 网络路径与本地路径体验一致（工具不超时、行为一致）；
2. 或提供网络路径优化：目录列表缓存/预取、限制递归深度、超时可配置；
3. 或至少在文档中给出官方建议（如：映射为盘符、仅用单层目录、用哪些工具替代）。

影响

多人团队 + 中央 NAS 是常见协作形态，SMB/共享工作区不是个例。
如果官方不打算支持，也希望能说明原因或推荐替代方案。