# [bug] Windows 工作区路径未保留映射盘符拼写 Windows workspace paths do not preserve the mapped drive letter spelling

[STAYSIMPLE]

[bug] Windows 工作区路径未保留映射盘符拼写

• 分类：Ideas
• 平台：Windows
• DSH 版本：0.2.0-rc.2

摘要

在 Windows 上通过映射盘符添加工作区时，DSH 经 fs.realpath 规范化路径，盘符会被解析为 UNC 形式并持久化。此后工作区标题、会话 cwd、所有工具调用中呈现的路径全部使用 UNC 拼写。

直接后果：保存的工作区路径与用户输入/认可的路径不一致，且被改写后的网络位置会进入模型上下文。

希望工作区路径保留用户输入的原始拼写，同时减少不必要的上下文暴露。

复现步骤

1. 将网络共享映射为盘符：

   net use Z: \\server\share\username\projects

2. 以 Z:\demo 添加工作区。

3. 实际表现：工作区被存储并显示为 \\server\share\username\projects\demo；模型与用户看到的全部路径（会话 cwd、文件工具、交付物路径）均为 UNC 拼写。

根因

源码

@deepseek-ai/dsh-workspace 通过 realpathNormalize（源码 src/paths.ts，编译产物见 lib/types/paths.js 及 lib/index.js 中的内联拷贝）规范化工作区路径：

export async function realpathNormalize(path) {
    if (!fullyQualifiedWorkspacePath(path)) throw new TypeError(...);
    return await realpath(path);   // fs/promises.realpath → native → 映射盘符解析为 UNC
}

平台行为

在 Windows 上，realpath 的 native 路径（GetFinalPathNameByHandle，VOLUME_NAME_DOS）会把经映射网络盘符打开的句柄解析为 UNC 形式。

该行为由 Win32 API 的既有语义决定，自引入 GetFinalPathNameByHandle 的系统版本起一贯如此，理论上与具体 Windows 版本无关。

这是已知的平台行为，并非 DSH 特有：

• nodejs/node#50019：fs.realpath 在 Windows 上无法保留挂载点/盘符拼写；
• VS Code 映射盘符修复：VS Code 遇到同样问题，通过单独解析盘符而非让 realpath 改写来解决；
• OpenJDK canonical-path/UNC 讨论：Java File.getCanonicalPath 在网络驱动器上同样解析为 UNC。

影响

• 信息泄漏：UNC 工作区路径会把内部主机名泄漏进会话日志、提示词与截图；
• 用户不友好：盘符拼写是用户实际输入并在资源管理器中看到的形式，静默改写反直觉。
• 伴生症状：#3749（SMB 映射盘符下文件操作被误判为 "out of workspace"）。工作区以 UNC 记录后，用户/模型改用盘符访问同一目录会被沙盒拒绝。

建议

• workaround：当持久化的路径与用户输入的拼写不一致时，明确告知用户"工作区路径改写为 ..."，让静默改写可见；

• fix：工作区记录尽量保存用户提供的原始拼写，内部身份与用户表示分离。

  用户表示：工作区应保存用户一侧提供的合法路径拼写，界面展示、会话提示词、模型上下文一律以用户提供的表示为准；

  内部身份：在需要一致表示的内部环节（如路径解析、沙箱判定、命令执行等），将同一路径的不同拼写，幂等地映射到规范表示（如UNC），从而保留等价的合法拼写同时不产生歧义。

  这样可连带修复BUG: 超出工作区（Windows·SMB映射驱动器）File operations judged as "out of workspace" #3749。

---

English Version:

[bug] Windows workspace paths do not preserve the mapped drive letter spelling

• Category: Ideas
• Platform: Windows
• DSH version: 0.2.0-rc.2

Summary

When a workspace is added on Windows via a mapped drive letter, DSH canonicalizes the path through fs.realpath, which resolves the drive letter to its UNC form and persists it. From then on, the workspace title, the session cwd, and every path surfaced by tool calls all use the UNC spelling.

Immediate consequence: the stored workspace path no longer matches the path the user entered or endorsed, and the rewritten network location enters the model's context.

The workspace path should preserve the spelling the user entered, and unnecessary context exposure should be reduced.

Reproduction

1. Map a network share to a drive letter:

   net use Z: \\server\share\username\projects

2. Add Z:\demo as a workspace.

3. Observed: the workspace is stored and displayed as \\server\share\username\projects\demo; every path seen by the model and the user (session cwd, file tools, deliverable paths) uses the UNC spelling.

Root cause

Source

@deepseek-ai/dsh-workspace canonicalizes workspace paths through realpathNormalize (source src/paths.ts; compiled artifacts in lib/types/paths.js and the inlined copy in lib/index.js):

export async function realpathNormalize(path) {
    if (!fullyQualifiedWorkspacePath(path)) throw new TypeError(...);
    return await realpath(path);   // fs/promises.realpath → native → mapped drives resolve to UNC
}

Platform behavior

On Windows, the native realpath path (GetFinalPathNameByHandle with VOLUME_NAME_DOS) resolves handles opened through a mapped network drive to their UNC form.

This behavior follows from the established semantics of the Win32 API and has been consistent ever since the system version that introduced GetFinalPathNameByHandle; in principle it is independent of the specific Windows version.

It is a known platform behavior, not DSH-specific:

• nodejs/node#50019: fs.realpath cannot preserve mount-point/drive-letter spellings on Windows;
• VS Code mapped-drive fix: VS Code hit the same problem and solved it by resolving the drive letter separately instead of letting realpath rewrite it;
• OpenJDK canonical-path/UNC discussion: Java's File.getCanonicalPath likewise resolves network drives to UNC.

Impact

• Information leakage: a UNC workspace path leaks internal hostnames into session logs, prompts, and screenshots;
• Poor UX: the drive-letter spelling is what the user actually typed and sees in Explorer; silently rewriting it is counter-intuitive.
• Related symptom: #3749 (file operations misjudged as "out of workspace" on SMB mapped drives). Once a workspace is recorded as UNC, accessing the same directory via the drive letter gets rejected by the sandbox.

Proposal

• Workaround: whenever the persisted path's spelling differs from what the user entered, tell the user explicitly ("workspace path rewritten to ..."), making the silent rewrite visible;

• Fix: store the user-supplied spelling in the workspace record, decoupling internal identity from the user-facing representation.

  User representation: the workspace should keep the legal path spelling supplied by the user; UI display, session prompts, and model context should all follow the user-supplied representation.

  Internal identity: in internal steps that need a consistent representation (path resolution, sandbox checks, command execution, etc.), map the different spellings of the same path idempotently onto a canonical form (e.g. UNC), so that equivalent legal spellings are preserved without ambiguity.

  This would also fix BUG: 超出工作区（Windows·SMB映射驱动器）File operations judged as "out of workspace" #3749 as a side effect.

[PerryLink]

根因确认了：做的就是这个函数。但有一点比你的报告更简单——「会话 cwd 也变成 UNC」不是第二个 bug，而是必然结果；另外仓库里已经有你要的那个分离模式，可以直接当先例，改法能落到很具体的位置。

1. 根因与调用链

packages/workspace/workspace/src/paths.ts:52-57：

export async function realpathNormalize(path: string): Promise<string> {
  if (!fullyQualifiedWorkspacePath(path)) { throw new TypeError(...) }
  return await realpath(path)
}

你引的片段逐字准确。三条入口都过它：

• packages/workspace/workspace/src/index.ts:237（create）→ :241 createCanonical(canonical, title) —— 用户输入的 path 在 :237 之后即被丢弃，canonical 直接成为记录身份
• index.ts:268-271（initializeDefault）—— 注意 title 取自原始 path，路径取 canonical
• index.ts:501
• 另外 index.ts:812-817（indexHeader）把 header 的 cwd 也规范化，entity.ts:124（attachSession）同样，且 :138-142 是纯字符串相等比较

2. 「会话 cwd 也是 UNC」不是第二个 bug

packages/api/session-controller/src/commands.ts:119：

const cwd = workspace?.path ?? request.cwd ?? this.defaultCwd

会话 cwd 直接取 workspace 的 path，而 path 就是 canonical ⇒ 显示 UNC 是它的必然结果。这可以在报告里合并掉一条子项，让诉求更集中。

3. ⭐ 仓库里已经有你要的「身份 / 表示」分离

这条最有说服力，因为它把抽象建议变成"照隔壁写"。packages/fs/fs-local/src/fsio.ts:106-112：

export interface LocalTarget {
  /** Absolute path (symlinks not resolved) — used for display. */
  displayPath: string
  /** Realpath identity — used as the stable target key and the I/O path. */
  targetKey: FsTargetKey
}

localDisplayPath（:145-151）保留用户拼写，resolveLocalTarget（:161-166）返回 { displayPath, targetKey: FsTargetKey(await realpath(displayPath)) }。这就是"用户表示 vs 内部身份"，而且仓库已经在别处这么做了。

缺的只是一路带到头：packages/fs/fs-local/src/index.ts:137 把 targetKey 塞进 FsTarget 时丢掉了 displayPath，此后 contains()（:152-155）与 processPath()（:140-142）都只读 targetKey。⇒ 这同时解释了「用盘符访问同一目录被判 out of workspace」那一类伴生症状：层间本来有 display/identity 分离，只是两处都只保留了 identity。

4. 由此得到的改法（很小）

• workspace 记录额外存一份用户拼写字段，展示与提示词用它；
• realpathNormalize 保持不变，继续做唯一性判定；
• 需要的话把 displayPath 一路带到 FsTarget 与 sessionPaths。

这正好是包内已有的做法：index.ts:271 就是「canonical 做身份、原始 path 做 title」——只是没有推广到路径本身。

⚠️ 但有一条不能破：paths.ts:39-48 的注释把「symlink 指向已存在工作区目录会碰撞」写成有意设计（"the ONE uniqueness canon of the package"）。任何保留原拼写的改动必须继续用 canonical 判唯一，否则会生成两个指向同一目录的 workspace 记录 —— 那比现在的问题严重。

5. 两处措辞

• 精确的调用点是 realpathNormalize（paths.ts:52），不是你写的 fs.realpath；它内部用 node:fs/promises 的 realpath。这个细节值得改，因为建议的落点就是它旁边的调用方。
• 你引的「VS Code 用单独解析盘符解决」这类外部参照我没有核实，所以我在回答里不引用它 —— 你自己的复现与产物证据已经足够。

6. 版本

你写的是 0.2.0-rc.2；realpathNormalize 在 origin/master（= dsh-v0.2.1-alpha.2）上仍在 paths.ts:52，位置与语义都没变。你说"内联拷贝也在 lib/index.js 里"这件事与 npm pack 产物一致（package/lib/types/paths.js 与 package/lib/index.js），属实。

小结

诉求方向（内部身份 / 用户表示分离）正确，而且与仓库现有架构完全兼容 —— 援引 fs-local 的 LocalTarget 会把这条从"设计建议"变成"补齐一处遗漏"，采纳门槛会低很多。唯一要守住的边界是第 4 节那条唯一性规范。