claude-mem 在 Windows 含空格路径下启动失败的根因与修复从 spawn 陷阱到 cmd.exe 包装方案【免费下载链接】claude-memPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode More项目地址: https://gitcode.com/GitHub_Trending/cl/claude-mem本文围绕 claude-mem 仓库中的缺陷修复文档 windows-spaces-issue.md 展开当 Windows 用户名包含空格例如C:\Users\Anderson Wang\时Claude SDK Agent 无法启动、PostToolUse hook 永久挂在(1/2 done)的完整排查过程。读完本文你将理解 Node.js 在 Windows 上直接 spawn.cmd文件的两个典型陷阱并掌握 claude-mem 采用的「PATH 解析 cmd.exe /d /c包装」修复方案以及它在当前源码中的落地形态。症状hook 永久挂起与 exited with code 1该问题的表现非常具有误导性。表面上看worker 进程运行正常但以下现象同时出现PostToolUse hook 一直停留在(1/2 done)状态不再推进Worker 日志中反复出现以下错误文档原文摘录ERROR [SESSION] Generator failed {providerclaude, errorClaude Code process exited with code 1} ERROR [SESSION] Generator exited unexpectedly严重程度为 High核心功能被破坏且仅影响 Windows 平台。关键在于Claude Code CLI 本身在终端里手工运行完全正常问题只出现在 claude-mem 以子进程方式拉起它的时候——这直接指向进程派生spawn路径上的跨平台差异。根因两处 Windows 代码路径上的缺陷文档将根因定位在两个文件上二者叠加才导致了最终的失败缺陷 1自动检测返回的完整路径带空格在SDKAgent.ts的自动检测逻辑中解析出的 Claude CLI 路径是完整绝对路径例如C:\Users\Anderson Wang\AppData\Roaming\npm\claude.cmd路径中Anderson Wang含空格且指向的是一个.cmd批处理 shim而非原生可执行文件。这个返回值随后被直接交给 Node.js 的spawn()使用。缺陷 2spawn()无法直接执行含空格的.cmd文件在ProcessRegistry.ts中Node.js 的spawn()在没有 shell 参与的平台上对「批处理文件 空格路径」组合处理不当.cmd文件本质上是脚本需要命令解释器cmd.exe参与执行而直接把它当作可执行文件 spawn遇到含空格的路径就会以退出码 1 失败——这正是日志里exited with code 1的来源。从当前源码结构看文档中的SDKAgent.ts后来被重构拆分可执行文件的发现逻辑收敛到了共享模块 find-claude-executable.ts而 Claude 会话的派生入口位于 ClaudeProvider.ts第 198 行调用findClaudeExecutable(SDK)。两处缺陷对应的修复也分别落在「可执行文件发现」与「子进程派生」两个层。修复一可执行文件发现——优先走where claude.cmd PATH 解析文档提出的第一个修复是在 Windows 上优先返回claude.cmd经由 PATH 解析而不是返回自动检测到的完整路径。原文的提议代码为// On Windows, prefer claude.cmd (via PATH) to avoid spawn issues with spaces in paths if (process.platform win32) { try { execSync(where claude.cmd, { encoding: utf8, windowsHide: true, stdio: [ignore, pipe, ignore] }); return claude.cmd; // Let Windows resolve via PATHEXT } catch { // Fall through to generic error } }其核心思路是把「定位二进制」这件事交给 Windows 自身的 PATH PATHEXT 机制避免把带空格的完整路径硬塞给 spawn。当前仓库中该策略的完整实现位于 find-claude-executable.ts 的discoverCandidates()函数约第 200–214 行if (_internals.platform() win32) { // claude.cmd first: spawning the .cmd wrapper avoids spawn issues with // spaces in the .exe path (long-standing Windows preference). for (const command of [where claude.cmd, where claude]) { try { const output _internals.execSync(command, { encoding: utf8, windowsHide: true, stdio: [ignore, pipe, ignore], }); candidates.push(...output.split(\n).map((line) line.trim()).filter(Boolean)); } catch { // Not found via this lookup — try the next discovery source. } } }可以看到源码沿袭并强化了文档的修复策略有几处值得注意的工程细节claude.cmd排在where claude之前源码注释明确写道「spawning the .cmd wrapper avoids spawn issues with spaces in the .exe path (long-standing Windows preference)」——这正是本文缺陷 1/2 的长期经验沉淀收集所有 PATH 命中而不仅是第一个用whereWindows/which -a类 Unix枚举全部候选防止 PATH 前部的过期旧版二进制遮蔽后部的当前版本候选去重基于 symlink 真实路径realpathSync解析后去重多个 PATH 目录可能指向同一真实二进制能力探测而非仅版本检查每个候选都会执行--permission-mode dontAsk --version能力探针CAPABILITY_PROBE_ARGS因为 claude-mem 每次派生都传该参数旧版 CLI 会在 flag 解析阶段直接退出码 1——这与本文的「exited with code 1」症状形态相同能力探针能在派生前就把不兼容二进制排除掉探针使用execFileSync而非execSync候选路径作为独立参数传递永远不经 shell 解释防止路径中含,;,等字符时的 shell 注入Windows 上可通过精心构造的CLAUDE_CODE_PATH触发成功结果缓存 15 分钟RESOLUTION_CACHE_TTL_MS失败不缓存用户更新 CLI 后下次观察即生效无需重启 worker。非 Windows 平台则走which -a claude并补充两个已知安装位置~/.local/bin/claude、~/.claude/local/claude。当多个候选都可用时按「最高版本优先、PATH 顺序仅用于平局决胜」的规则选择compareVersionKeysDesc。修复二cmd.exe /d /c包装器处理.cmd派生文档提出的第二个修复是在 Windows 上对以.cmd结尾的命令用cmd.exe /d /c包装后再 spawnconst useCmdWrapper process.platform win32 spawnOptions.command.endsWith(.cmd); if (useCmdWrapper) { child spawn(cmd.exe, [/d, /c, spawnOptions.command, ...spawnOptions.args], { cwd: spawnOptions.cwd, env: spawnOptions.env, stdio: [pipe, pipe, pipe], signal: spawnOptions.signal, windowsHide: true }); }当前仓库中该逻辑的最终实现位于 process-registry.ts 的spawnSdkProcess()约第 624–645 行const useCmdWrapper process.platform win32 options.command.endsWith(.cmd); const env sanitizeEnv(options.env ?? process.env); const filteredArgs normalizeSpawnSdkArgs(options.args, options.extraArgs); const isWin process.platform win32; const child useCmdWrapper ? spawnHidden(cmd.exe, [/d, /c, options.command, ...filteredArgs], { cwd: options.cwd, env, detached: !isWin, stdio: [pipe, pipe, pipe], signal: options.signal, windowsHide: true, }) : spawnHidden(options.command, filteredArgs, { cwd: options.cwd, env, detached: !isWin, stdio: [pipe, pipe, pipe], signal: options.signal, windowsHide: true, });与文档提议相比最终实现有几处演进统一走spawnHidden包装spawn.ts它在spawn之上默认注入windowsHide: true避免 worker 后台运行时弹出黑色控制台窗口。该文件同时定义了扩展名常量WINDOWS_CMD_EXTENSIONS {.cmd, .bat}与WINDOWS_NATIVE_EXTENSIONS {.exe, .com}供各处判断命令类型detached: !isWin只有非 Windows 平台创建独立进程组便于按pgid整组发信号Windows 没有 POSIX 进程组概念改用taskkill /T树杀见下文清理路径参数过滤normalizeSpawnSdkArgsSDK 在某个可选 flag 无值时会编码为--flag 空字符串占位该函数会把「紧跟长选项后的空字符串」整对剥掉防止空字符串被 shell 误解析——这正对应文档 Why This Works 一节提到的Using direct arguments instead ofshell: trueprevents empty string misparsing。值得注意的是同文件中还有一个更精细的同步派生场景处理spawn.ts 的buildSpawnSyncInvocation()对.cmd/.bat命令构造cmd /d /s /c cmdline形式并对每个参数单独加引号、外层再包一层引号同时设置windowsVerbatimArguments: true。源码注释解释了其中的两个细节/s /c会剥掉最外层引号、保留内部每参引号从而让含空格的 shim 路径存活windowsVerbatimArguments则阻止 Node 再次转义否则前导变成\被 cmd.exe 拒收。这说明「含空格路径 .cmd」问题的修复在异步派生与同步派生两条路径上都做了针对性处理。为什么这套组合拳有效文档 Why This Works 给出的三点解释结合源码可以逐条印证PATHEXT ResolutionWindows 按 PATH 目录逐个搜索并对每个目录尝试 PATHEXT 中的扩展名.COM、.EXE、.BAT、.CMD……。返回裸命令名claude.cmd或由where得到的路径后系统解析阶段天然处理了目录名含空格的情况Node 侧不需要自己拼接或转义长路径。cmd.exe 包装cmd.exe /d /c command args...让真正的解释器来执行.cmdshim空格路径与参数传递都由命令解释器正确处理/d参数跳过 AutoRun 注册表项行为更可预测。避免shell: true的解析陷阱全程使用「命令 参数数组」的直接 spawn 形式配合normalizeSpawnSdkArgs清除空字符串占位参数空字符串参数不会被 shell 语义误读。此外进程清理路径也是 Windows 适配的一部分reapSession()与ensureSdkExit中Windows 分支调用killProcessTree()而不是process.kill()源码注释说明原因——Windows 上被杀的往往只是.cmd/.exeshim 本身它包裹的真实子进程以及继承的 socket会存活下来只有taskkill /T树杀能到达全部后代。这套「树杀 start-token 防 PID 复用误杀」机制与 spawn 侧的 cmd 包装共同保证了会话生命周期的完整性。诊断增强让 code 1 不再无声文档中的原始症状之所以难排查正是因为 CLI 死于 flag 解析阶段却只留下一个不透明的{code1}。当前实现为此加了两层可观测性process-registry.ts 中spawnSdkProcess()会滚动保留子进程 stderr 的最后 2048 字符STDERR_TAIL_MAX_CHARS并在close事件而非exit因为管道中的 stderr 缓冲区可能尚未排空触发非零退出码时把 tail 一并写入 WARN 日志——CLI 若在参数解析阶段崩掉真实原因会直接出现在日志里find-claude-executable.ts 的能力探针把「能跑但拒绝 flag」incompatible与「根本跑不起来」broken分类处理并在成功解析时以 INFO 级别记录最终选择了哪个二进制Using Claude CLI vversion at path使「worker 活着但零观察」这类静默失败可以从默认日志中定位。验证方式与向后兼容文档给出的验证结论在 Windows 11、用户名含空格的环境下实测PostToolUse hook 正常完成Observations 成功写入数据库不再出现 process exited with code 1 错误。当前仓库中可继续追踪的验证入口包括find-claude-executable.test.ts覆盖候选选择、版本平局决胜、where claude.cmd与where claude双查询等场景如模拟where claude.cmd命中旧版本、where claude命中新版本的择优逻辑process-registry.test.ts 与 wait-for-slot.test.ts覆盖进程注册表与会话级清理行为安装侧install.ts 在 Windows 上也遵循同一原则lookupWindowsCommand(claude) ?? claude.cmd即优先解析出原生可执行文件找不到时回退到.cmdshim。文档同时强调的兼容性边界保持CLAUDE_CODE_PATH向后兼容在 find-claude-executable.ts 中~/.claude-mem/settings.json里显式配置的CLAUDE_CODE_PATH优先级最高且会被expandTilde展开settings.json 中写的~/.local/bin/claude不会被字面量~卡住配置路径不存在会直接报错fail loud配置路径指向过旧 CLI 或桌面版应用也会给出明确指引而不是静默失败不影响非 Windows 平台所有修复分支均以process.platform win32为前置条件POSIX 路径的进程组管理与信号语义保持原样。小结这个缺陷的本质是「Node.js 跨平台 spawn 语义差异」与「npm 全局安装产物形态」的叠加Windows 上 npm 全局包落地为含用户目录的.cmdshim而用户目录名带空格时「完整路径 直接 spawn」这条朴素路径必然失败。claude-mem 的修复方案可以概括为两条原则对任何需要在 Windows 上派生命令行工具的项目都有参考价值发现阶段把 PATH/PATHEXT 解析交给系统where claude.cmd优先并对每个候选做能力探测而非仅版本探测派生阶段对.cmd/.bat命令一律用cmd.exe /d /c异步或cmd.exe /d /s /c ...windowsVerbatimArguments同步包装且始终以参数数组传递、规避shell: true可观测性兜底保留 stderr 尾部、区分「退出码 1 的原因」让平台相关失败在默认日志中可见。【免费下载链接】claude-memPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode More项目地址: https://gitcode.com/GitHub_Trending/cl/claude-mem创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考