硬链接发布回退 Mushroomcowisheggs/dsh-hardlink-publish-fallback

dsh-hardlink-publish-fallback

补全一次 write 工具调用——它因为所在卷无法用硬链接发布新文件而失败。

它解决的问题

在 Windows 上，@deepseek-ai/dsh-fs-local 发布新文件时，会把暂存的临时文件硬链接到目标位置。这个链接就是防覆盖守卫：如果写入意图确定之后又有文件冒出来，它会拒绝覆盖。

不支持硬链接的卷——exFAT、FAT32（可移动驱动器），以及部分网络共享——会拒绝这次调用。Node 把拒绝暴露成 EISDIR（而不是 ENOTSUP/EPERM），于是写入失败，报错如下：

cannot write "<workspace>\<file>": EISDIR: illegal operation on a directory,
link '<workspace>\.<file>.<pid>.<uuid>.tmpdir\<file>.tmp' -> '<workspace>\<file>'

调用方「不存在才创建」的意图始终无法满足，于是在这个工作区里创建新文件的每一次尝试都会失败，而且是永久性的。更新已有文件不受影响：那条路径改用 rename/ReplaceFileW 发布。结果就是一个让人摸不着头脑的半残工具——「编辑能用，创建永远不行」。

这类卷同样不支持符号链接，对 dsh 本身来说这是另一个更严重的限制：dsh-app-boot 的 healProfilesModuleFallback 会在组装阶段把安装目录软链进配置档，所以把 DSH_HOME 放在这种卷上，任何配置档都启动不了。本插件不处理这个问题；请把 DSH_HOME 放在支持符号链接的文件系统上。

本插件做什么

1. 让真正的 write 照常运行，不做任何改动。
2. 只有当它因硬链接发布的特征而失败时，才重新检查目标是否仍然不存在，然后用一次不带意图的写入来发布——也就是该卷支持的 rename 路径，也是每次文件更新已经在用的那条路径。
3. 记录与一次成功写入相同的观测结果。
4. 接管过程中任何一步失败，都原样返回原始错误。

默认行为不会被改动。 不受影响的写入永远不会进入接管流程，不会覆盖任何已有记录，也不会替换任何服务。检测很严格：FS_IO_ERROR 消息里必须同时出现 .tmpdir 暂存标记和 link 动词，所以无关的 EISDIR 失败（目标是目录、路径组件有问题）绝不会被碰。

安装

从 GitHub 安装。请固定 tag 或 commit——不带 ref 的话，pnpm 会安装默认分支此刻指向的内容，之后一次推送就会悄悄改变用户机器上运行的东西：

dsh plugin --profile web add "github:Mushroomcowisheggs/dsh-hardlink-publish-fallback#v0.1.0"

strongest: pin the exact commit
dsh plugin --profile web add "github:Mushroomcowisheggs/dsh-hardlink-publish-fallback#<40-char-sha>"

本包是纯 JavaScript，没有 prepare/构建脚本，所以 pnpm 没有生命周期脚本要跑，也不需要 allowBuilds 授权。（那条要求针对的是从源码构建的 git 依赖；如果将来如果 version 以后加了构建步骤，用户必须在配置档的 pnpm-workspace.yaml 里把它加入允许列表。）

路径一定要加引号

从本地检出或 tarball 安装时，给路径加双引号。不加引号的 Windows 路径在 pnpm 看到之前就已经被改坏了：\d、\h、\t 这类序列会被当成转义符，所以

WRONG — backslash escapes eat path separators; pnpm then looks for a registry package literally named "dir\my-plugin"
dsh plugin --profile web add some\dir\my-plugin

RIGHT
dsh plugin --profile web add "some\dir\my-plugin"

from a local checkout
dsh plugin --profile web add "<path-to-checkout>"

from a tarball
pnpm pack
dsh plugin --profile web add "<path-to-checkout>\dsh-hardlink-publish-fallback-0.1.0.tgz"

dsh plugin add 会把 bundle 自动追加到配置档的 dsh.profile.bundles，因为这个包声明了 dsh.bundle。

验证

dsh --profile web --dump-config # look for "# == dsh-hardlink-publish-fallback"

然后，在受影响卷上的工作区里，让智能体新建一个文件。没有插件时会报上面的 EISDIR/link 错误；装上插件后，调用会正常返回 Created file。

已在真实硬件上确认（修复过的 exFAT 卷，插件从已发布的 tag 安装）：新建文件、在需要先创建的目录里新建、不经过读取就再次写入同一个文件，都没有残留的暂存文件。这个插件创建的文件，记录的观测结果和正常写入成功时一样，所以之后的行为跟其他文件没有区别。

适用范围与限制

- 只修复新建文件。 更新和 edit 从来不走硬链接路径，所以本来就没问题，不会被拦截。
- 症状偏 Windows，逻辑与宿主无关。 插件依据的是失败特征，不是平台，所以任何 POSIX 文件系统只要以同样的形式拒绝 link()，也一并覆盖。
- 写入盘符根目录时无效。 另一个跨文件系统的缺陷会让 writeFileAtomic 调用 mkdir(<root>, { recursive: true })，这在 Windows 盘符根目录上返回 EPERM（这里在 NTFS 和 exFAT 卷上都验证过）。由于这个插件是通过同一个服务完成写入的，直接在盘符根目录新建文件仍然会失败。请改用子目录。
- 不能替代上游修复。 这是针对 dsh-fs-local 发布逻辑缺陷的运行时变通方案；完整分析和建议的修复见 DEFECT-REPORT.md。
- 存在一个继承来的小 TOCTOU 窗口。 不存在性复查和写入是两次独立调用。原来的 writeText 在自己的探测和发布之间本来就有同样的窗口；复查保住的是防覆盖保护，在这个窗口之外，竞争的创建者仍然无法被悄悄覆盖。

测试

npm test # or: node test/plugin.test.mjs
这套测试套件把插件的接缝（fs、sandboxPolicy）替换成假实现，用来复现无硬链接卷的语义，因此不需要 exFAT 卷，不需要运行中的 harness，也没有任何依赖——只要 Node 能跑，它就能跑。它断言的是这个插件契约里真正要紧的结果：硬链接失败会在没有 no-replace 保护的情况下完成，接管运行时已经存在的目标绝不会被覆盖，无关的失败和成功的写入原样透传，接管内部出错时调用方原本的结果保持不变。

仓库结构

.
├── package.json # declares dsh.bundle.patch
├── cordis.patch.yml # the configuration layer this bundle contributes
├── index.js # the plugin module
├── README.md
├── LICENSE
├── test/
│ └── plugin.test.mjs # behavioural tests (no exFAT volume needed)
├── DEFECT-REPORT.md # the upstream analysis (not published to npm)
├── POST.md # candidate discussion write-up (see PRIOR-REPORTS.md)
└── PRIOR-REPORTS.md # this defect is already reported - read before filing

包文件必须留在仓库根目录：git 安装会打包整个仓库，而不是套用 files 白名单，所以 package.json、index.js 和 cordis.patch.yml 都必须能从根目录解析到。

发现

仓库带有 GitHub dsh-plugin 话题，CONTRIBUTING.md 就是要求社区插件用这种方式让自己可被发现。

许可证

MIT —— 见 LICENSE。