[Bug] fs-local 的原子写在「mkdir -p 已存在目录返回 EPERM」的文件系统上全不可写（SSHFS/SFTP 挂载盘必踩）

[devil233-ui]

摘要

@deepseek-ai/dsh-fs-local 的原子写在**「对已存在目录执行 mkdir -p 会返回 EPERM」的文件系统**上完全不可用：模型侧的 write / edit 工具、以及 dsh-better-sidebar 的 fs.write 都会在真正写文件之前中止。通过 SSHFS 挂载的远端目录（sshfs-win + WinFsp）是必然踩到的一类——这类挂载只能走 SFTP，而 SFTP v3 没有「已存在」这个错误码。

环境

• DSH Desktop 2.0.17 / 核心 0.2.0-rc.2，Windows 11
• SSHFS-Win 3.5.20357 + WinFsp 2.1.25156，把远端 Debian 12（OpenSSH 9.2p1）的 /root 挂成本地盘符 X:

症状

• read 工具：正常（能读远端文件，中文也正常）
• write 工具：EPERM: operation not permitted, mkdir '\\sshfs\<host>\'
• edit 工具：同一处 EPERM
• 侧边栏编辑器保存（dsh-better-sidebar 的 fs.write）：同一处 EPERM

根因

第一层：mkdir -p 的语义差异。 packages/fs/fs-local 的 writeFileAtomic() 无条件执行：

const directory = dirname(absolutePath);
await mkdir(directory, { recursive: true });

Node 的递归 mkdir 只有在拿到 EEXIST 时才把「目录已存在」当成成功。而 OpenSSH 的 sftp-server 在 errno_to_portable() 里把 EEXIST 落在 default 分支 → 通用 SSH2_FX_FAILURE；sshfs 再把 SSH_FX_FAILURE 映射成 EPERM。于是对已存在目录的 mkdir -p 返回 EPERM，libuv 原样抛出，写入在第一步就结束。

这不能归咎于某一个实现：SFTP 协议本身没有「已存在」错误码，所有走 SFTP 的挂载盘都会有同样的表现。可以独立复现：md X:\nbr（目录已存在）在 cmd 里同样报「拒绝访问」，而不是「已存在」。

第二层：staging 的 chmod。 即使跨过第一层，紧随的三处调用在同一个挂载上返回 EINVAL（fchmod）：

await chmod(stagingDir, 448);   // EINVAL
await handle.chmod(384);        // EINVAL
if (mode !== void 0) await handle.chmod(mode);

代码自己的注释已写明这类 mode 在 Windows 上是 inert（"inert as a mode on Windows but identifies replacement security semantics"），但失败目前仍是致命的。

建议的修法（我们已在本地改并验证通过）

1. mkdir 容忍 EPERM / EACCES，并 stat 确认目标确实是目录；其他错误原样抛出。
2. 仅在 win32 下把 staging 的两处 chmod 降级为尽力而为，其他平台保持严格语义。

try {
  await mkdir(directory, { recursive: true });
} catch (mkdirFailure) {
  if (mkdirFailure?.code !== "EPERM" && mkdirFailure?.code !== "EACCES") throw mkdirFailure;
  const existingDirectory = await stat(directory).catch(() => void 0);
  if (existingDirectory?.isDirectory() !== true) throw mkdirFailure;
}

验证方式（不用重启 DSH 也能验）

用绝对 file URL 直接 import 打过补丁的真实 dsh-fs-local，new LocalFileSystem(new Context(), { cwd, diffBasisMaxBytes }) 之后依次执行：

resolve → writeText(新建) → readText → writeText(替换) → editText → readText

结果：三条写路径全部通过，远端 cat 内容与写入完全一致；未打补丁时第一条就报 EPERM ... mkdir '\\sshfs\<host>\'。

附：挂载侧另外两个必需的参数（与本仓无关，供其他用户参考）

如果后续要支持「把远端目录当工作区」，除本问题外还有两处拦路虎，都在挂载参数上：

• -o VolumePrefix=...：不带它就是一个「本地型」WinFsp 卷，Node 的 realpath.native（内部走 GetFinalPathNameByHandle）报 UNKNOWN: unknown error, realpath，resolve() 直接失败，DSH 所有文件工具都停在第一步；
• -o FileSecurity=...：不带它时 WinFsp 把 POSIX 700 目录映射成拒绝挂载用户的 DACL，服务器 /root 连列目录都做不到（dir X:\root 报「拒绝访问」）。

把当前用户 SID 写进 DACL 即可解决后者。

说明

我们已阅读 CONTRIBUTING，理解现阶段不接受外部 PR，因此只在此报告并投票。

[Mide69]

我对着当前 master（d743267）核实了，两层原因都成立。packages/fs/fs-local/src/fsio.ts 的 writeFileAtomic 无条件 mkdir(directory, { recursive: true })，随后 staging 目录的 chmod(0o700)、临时文件的 handle.chmod(0o600) 和保留原文件 mode 的 handle.chmod(mode) 都没有容错。

我按你的思路实现了，推到了 fork：

https://github.com/Mide69/deepseek-harness/tree/fix/fs-local-atomic-write-mkdir-eperm

和你本地补丁有两处刻意不同：

1. mkdir 容忍 EPERM 和 EACCES，但必须 stat 确认路径是目录才放行，其他错误、路径不是目录、路径查不到，都原样抛出最初的 mkdir 错误。这一层不按平台判断，因为状态码怎么映射是挂载点决定的，不是操作系统决定的。
2. chmod 只在 win32 下忽略 EINVAL，不是忽略所有错误。POSIX 上 0o700 和 0o600 就是暂存文件的隐私保证，所以保持严格。目前只有 EINVAL 有报告证据，别的错误码没有证据就不放。

加了 ensureDirectory 和 applyStagingMode 两个小函数，用注入的错误码测了每个分支（existing dir 接受 EPERM/EACCES，文件和查不到的路径重新抛出，其他错误码重新抛出，win32 与 linux 对 EINVAL 的不同处理），fsio.ts 覆盖率仍是 100%。fs-local 整个测试套件通过，typecheck 和 lint 通过，README 中英文和 Agent Note 也补了。

我这边没有 SFTP 挂载环境，所以真实挂载上的行为是按你的报告和注入的错误码验证的，没有在 sshfs-win 上亲测。你要是方便，用你那套「绝对 file URL 直接 import」的方式在你的挂载上跑一遍这个分支会很有价值。

你说的 VolumePrefix 和 FileSecurity 两个挂载参数不在这个包里，我没动。

[devil233-ui]

在真实 SSHFS 挂载上跑完了这个分支，全绿。补上你提到的那块验证。

环境与验证方式

• Windows 11 + SSHFS-Win 3.5.20357 / WinFsp 2.1.25156，把远端 Debian 12（OpenSSH 9.2p1）的 /root 挂成本地盘符 X:（网络型卷，挂载参数含 -o VolumePrefix=/sshfs/root@<host>）
• 分支 fix/fs-local-atomic-write-mkdir-eperm @ 972e4e6a，按仓库脚本 tsc -b 构建（产物落在 lib/types/，对齐到 lib/ 后按 main/exports 加载）
• 就是你说的那套办法：把打补丁的 @deepseek-ai/dsh-fs-local 连同运行时依赖铺成扁平 node_modules，用绝对 file URL 直接 import，new LocalFileSystem(new Context(), { cwd })，不重启 DSH、不经过宿主

真实挂载上的结果

[2/3] smoke import OK
verify dir: X:\.fslocal-fix-verify\run-…（每次运行用新的 run-<时间戳> 子目录）
1 writeText(create) on pre-existing nested dir OK (EPERM mkdir path)
2 readText OK
3 writeText(replace) OK (chmod/fchmod staging path)
4 editText OK
5 nested brand-new mkdir -p OK
6 no staging garbage left in target dir
ALL CHAIN GREEN on X:\.fslocal-fix-verify\run-…

第 1 步正是关键：目标目录预先存在，writeFileAtomic() 里那行 mkdir(directory, { recursive: true }) 在 sshfs 上拿到 EPERM。未打补丁的 0.2.1-alpha.2 在这一行就中止（EPERM … mkdir），你的 ensureDirectory 放行之后整条写链走通，落盘内容逐字核对一致。

错误注入对照（补充证据）

把加载进来的 bundle 里 node:fs/promises 的具名导入改写成注入版（ESM 具名绑定无法从外部重绑），让「recursive mkdir 命中已存在目录」抛 EPERM、chmod 与 FileHandle.chmod 抛 EINVAL，再用 internals.platform 固定平台：

组合	结果
0.2.1-alpha.2，注入 EPERM/EINVAL，platform=win32	WRITE FAILED [EPERM]
你的分支，同注入，platform=win32	WRITE SUCCEEDED（内容一致、无暂存垃圾）
你的分支，同注入，platform=linux	WRITE FAILED [EINVAL]
两边都不注入（对照）	都成功

第三行是特意验的：EINVAL 在 POSIX 下没有被静默吞掉，你说的那层隐私保证确实保住了。

两点与分支无关的观察

1. mkdir 已存在目录回 EPERM 的影响面比 writeFileAtomic 更大：任何直接 fs.mkdir(path, { recursive: true }) 的调用都会中招——我写测试脚本时，自己的 mkdirSync() 就先撞了两次（第二次运行时目录已存在）。ensureDirectory 目前只覆盖 fs-local 内部这一处。
2. 暂存目录清理依赖 rm(recursive)：在这个挂载上 Node 的 rm(path, { recursive: true, force: true }) 会静默 no-op（不抛错也不删）。一次中止的写入会留下 .{name}.{pid}.{uuid}.tmpdir/（我们在一次依赖缺失导致的中止后就捡到了残留）。成功路径上暂存目录是空的、能删掉，所以「无残留」检查通过；但中止路径或许值得再收紧一点。

再次感谢——ensureDirectory + applyStagingMode 的边界比我本地那版更严（我那份是忽略全部 chmod 失败，你只忽略 win32 上的 EINVAL）。我这边直接换成你的实现，等合并之后再作废本地补丁。