dsh 在部分 Windows 10 机器上因 koffi 原生崩溃而不可用（含症状/修复思路/修改过程）

[dac114514]

说明：本仓库 Issues 未开放，故发在 Discussion。环境为 Windows 10 Pro 19043 (21H1) + Intel Core i5-5200U，Node v24.14.0，dsh 0.1.0-rc.6，koffi 2.16.3 / 3.1.4 均复现。

一、问题症状

1. npm 安装失败
   安装到 koffi 时报错：

   Failed to load prebuilt binary, rebuilding from source
   Error: CMake does not seem to be available
   

   首次 npx @deepseek-ai/dsh web 还会因为首次要装 500+ 包、且 npmmirror 逐条抓取很慢而看起来"卡死"。

2. 原生文件夹选择器崩溃
   Web UI 里点"添加工作区"，报：

   directory picker failed: win32 folder dialog worker exited before reporting a result
   

3. 服务静默挂掉
   dsh 能启动，但页面加载 / 创建会话 / 保存会话时进程直接崩溃退出（退出码 3221225477 = 0xC0000005，原生访问冲突），无任何日志（JS 无法捕获原生崩溃），表现为"服务突然没响应"。

4. 整体不可用
   上述任一项都会中断正常使用流程。

二、根因与修复思路

根因：dsh 依赖链里的 koffi（FFI 库）win32-x64 预编译二进制在这台机器上任何 FFI 操作（koffi.load()）即触发 0xC0000005。koffi 在 dsh 中有 4 条 Windows 专属路径被用到：

包	用途
koffi 自身 install 脚本	预编译可用性检测（子进程 require(koffi) 崩溃 → 误判 → 源码编译 → 缺 CMake → 安装失败）
@deepseek-ai/dsh-host-directory-picker-native	原生文件夹对话框（IFileOpenDialog）
@deepseek-ai/dsh-session-persistence-jsonl	会话持久化（MoveFileExW）
@deepseek-ai/dsh-fs-local	ACL 保留原子写（GetFileSecurityW / ReplaceFileW）

修复思路：既然 koffi 在这台机器上不可用，就绕开 dsh 对 koffi 的全部调用，用纯 Node 实现顶替（这正是非 Windows 平台已有的行为）：

• 跳过 koffi 崩溃的安装检测脚本（预编译二进制照常作为 optional 依赖装入）
• 目录选择器改用 -browse 后端（Node stdlib 做目录浏览）
• 会话持久化、ACL 原子写改用 fs.rename 等标准 fs 操作

三、修改过程（3 处）

① 安装（绕过 koffi install 脚本崩溃）

npm i -g @deepseek-ai/dsh --ignore-scripts --registry=https://registry.npmjs.org

--ignore-scripts 跳过 koffi 的 cnoke.cjs --prebuild 检测脚本（它因 require(koffi) 崩溃而误判预编译不可用）；@koromix/koffi-win32-x64 作为 optional 依赖照常装入。dsh 本身没有必须运行的 install 脚本，跳过无副作用。

② 目录选择器（~/.dsh/profiles/web/cordis.patch.yml）
禁用 -auto（启动时自动选 native 后端），插入 -browse 后端：

- id: directory-picker
  disabled: true
- insert:
    - id: directory-picker-browse
      name: '@deepseek-ai/dsh-host-directory-picker-browse'
    - id: directory-picker-browse-client
      name: '@deepseek-ai/dsh-client-ui-directory-picker-browse'

③ 两个包的 koffi 调用改为纯 Node（全局 node_modules 内）

@deepseek-ai/dsh-fs-local/lib/index.js —— writeFileAtomic 的默认实现改为不触发 koffi：

// 原来：
const copyFileDacl = internals.copyFileDacl ?? copyFileDaclWin32;
const replaceFile = internals.replaceFile ?? replaceFileWin32;
// 改为（跳过 Win32 ACL 复制/替换，保留 internals 覆盖能力）：
const copyFileDacl = internals.copyFileDacl ?? (async () => {});
const replaceFile = internals.replaceFile ?? ((replaced, replacement) => rename(replacement, replaced));

@deepseek-ai/dsh-session-persistence-jsonl/lib/index.js —— publishNewFileWin32 改为 fs.rename（并在 fs/promises import 中补上 rename）：

// 原来：
async function publishNewFileWin32(existing, replacement) {
	const api = await win32();  // 惰性加载 koffi → 本机崩溃
	if (api.moveFileExW(...) === 0) throw win32Error(...);
}
// 改为：
async function publishNewFileWin32(existing, replacement) {
	await rename(existing, replacement);
}

代价：丢失 Windows ACL 保留与 MoveFileExW 持久化增强（日常使用无感）。补丁为幂等脚本，npm update 后重跑 patch-dsh.js 即可（备份为 *.bak-koffi）。

四、最小复现（不依赖 dsh）

npm i @koromix/koffi-win32-x64@3.1.4
node -e "require('@koromix/koffi-win32-x64'); require('@koromix/koffi-win32-x64').load('kernel32.dll')"

• Node 父进程 spawnSync 捕获子进程退出码 3221225477（0xC0000005）。
• require 成功（能打印版本），崩溃发生在 koffi.load() / 进程退出。
• 对照：同环境下 node-pty@1.1.0 加载与退出正常（exit 0），排除"机器上所有原生模块都崩"。

五、已排查排除的原因

• ❌ Node 版本问题（v22.23.2 / v24.14.0 都崩）
• ❌ koffi 3.x 回归（2.16.3 也崩）
• ❌ 沙箱/工具链环境（cmd /c 与 PowerShell 直跑同样崩）
• ❌ VC++ 运行库缺失（vcruntime140 14.32 已装）
• ✅ 确认为 koffi win32-x64 预编译二进制与部分机器的兼容问题

六、给维护者的建议

1. 确认 koffi 是否有针对此类环境的修复版本，或提供"预编译检测失败时跳过而非源码编译"的开关（当前 cnoke.cjs 在 require 崩溃时误判并尝试源码编译，是第二个失败点）。
2. 建议 dsh 的 win32 路径在调用 koffi 前做可用性探测，失败时降级到纯 Node 实现而非让进程原生崩溃、静默挂掉。

[Annalasu]

同样的问题，感谢思路

[ipcer-firegod]

同样的问题，感谢

[Volosheninov]

thanks.

[sjh9714]

这个坑我们在做 Windows 修复包的时候也撞到了。koffi 3.1.3/3.1.4 的 win32-x64 预编译是坏的，一条链上会炸三处。安装失败、目录选择器崩溃、会话保存无声退出。楼里说的 pin 到 3.1.2 是对的。

我把这个检测做进了 dsh-win32 的 doctor。npx dsh-win32 doctor 会扫描 profile 里的 koffi 版本，命中坏版本时直接给出修复命令。顺带它还检查 PS7、Git Bash、localhost 403 这些常见坑。https://github.com/sjh9714/dsh-win32

[Electricitysheep]

koffi 在部分 Windows 10 机器崩溃——#293（koffi 3.1.3/3.1.4 预编译损坏锁 3.1.2）同族，你这条补了硬件维度（旧 CPU/老系统）。

排查：锁 koffi@3.1.2 试下，或确认原生模块加载路径。Windows 原生依赖坑第 2/3 章有整理：https://github.com/Electricitysheep/dsh-handbook/blob/main/docs/02-quickstart.md