Skip to content

Windows: plugin install claude 的 SessionStart hook 带 PowerShell "&" 前缀,cmd.exe 下静默失败,claude lane 无法自举(附修复建议) #1902

Closed

Description

@daha1216

Windows:plugin install claude 的 SessionStart hook 命令在 cmd.exe 下静默失败,claude lane 永远无法自举

环境

  • billion-context 0.1.179(npm 安装,经 dsh profile 的 node_modules 调用 dist/index.js)
  • Windows + Node v24.18.1(C:\Program Files\nodejs\node.exe)
  • Claude Code 2.1.284(npm 安装,shim 在 C:\Users\<u>\AppData\Roaming\npm\ 下,含 claude / claude.cmd / claude.ps1 三个垫片)
  • 配置:"claude": { "nativePort": 48787 }

现象

bili plugin install claude 安装成功、受管 settings 块与 MCP face 都写入后,新开任何 Claude Code 会话,claude lane 都不会被拉起:

  • curl http://127.0.0.1:48787/__bili/stats → connection refused(无人监听);
  • MCP bili 一直卡在 connecting;
  • bili.log 里只有其它 lane 的流量,没有任何 claude lane 的 acp-proxy listening 记录;
  • Claude Code 侧看不到任何报错(hook 失败是静默的)。

根因

安装器写入 ~/.claude/settings.json 的 SessionStart hook 命令是(portableHookCommand() 生成):

"command": "& \"C:/Program Files/nodejs/node.exe\" C:/Users/<u>/.dsh/profiles/desktop/node_modules/billion-context/dist/claude-native-bootstrap.js"

开头的 & 是 PowerShell 调用操作符。Claude Code 在 Windows 上用非交互 cmd.exe 执行 hook 命令,cmd 一遇到开头的 & 即整行失败:

& was unexpected at this time.

手工复现:

> cmd /c '& "C:/Program Files/nodejs/node.exe" C:/Users/.../claude-native-bootstrap.js'
& was unexpected at this time.        (exit 1)

去掉 & 前缀后("C:/Program Files/nodejs/node.exe" C:/.../claude-native-bootstrap.js),cmd.exe 和 PowerShell 下都能正常执行——实测 lane 成功在 48787 拉起,/__bili/stats 正常返回。

修复建议

portableHookCommand() 在 win32 下不要加 & 前缀,直接生成「带引号的可执行路径 + 参数」——这种形式 cmd 与 PowerShell 双兼容。

附带发现:同一安装流程里 resolveClaudeCli 在 Windows 下的另一个坑

claudeInstall() 里 resolveClaudeCli() 用 where.exe claude 取第一个结果,而 npm 目录下的第一个结果是无扩展名的 bash 垫片 C:\Users\<u>\AppData\Roaming\npm\claude,spawnSync 直接执行它报 ENOENT,导致安装期 MCP 注册失败:

bili plugin: claude: MCP registration failed (spawnSync C:\Users\<u>\AppData\Roaming\npm\claude ENOENT)
— is the claude CLI on PATH? (the managed settings block ... was written; rerun after fixing the CLI to complete the MCP face)

绕过办法(我本机用这个跑通了):设 CLAUDE=C:\Users\<u>\AppData\Roaming\npm\claude.cmd 后重跑 install——runClaudeCli() 对 .cmd/.bat 有 shell 分支,可以正常执行。

建议:win32 下从 where.exe 结果里按 PATHEXT 优先挑 .cmd/.exe/.bat,跳过无扩展名文件。

备注

  • 由于 applyClaudeManagedBlock() 在重装/升级时会把 hook 命令改回生成器输出,手工修好的 hook 会在下次 plugin install claude 后再次被写坏,所以最好在源头修掉。
  • 感谢这个项目,dsh + claude 混用下的压缩体验非常好 🙌

Activity

  1. ranxianglei commented on Oct 2, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    [bot] 🏷 收到,两个问题都已在代码里核实,正在修。先同步一下审核结论:

    ① & 前缀(主 bug)— 确认属实,且比表面更微妙

    portableHookCommand()(src/plugin-install.ts:74)对含空格的可执行路径会生成 & "head" args。这个形式是 #1376 时针对 Claude Code 2.1.282 探测后选的——当时实测 hook 走的是 PowerShell,而 PowerShell 下「裸引号开头 token + 参数」是 parse error,所以选了 &。但你这边 2.1.284 的报错 & was unexpected at this time. 是 cmd.exe 特有的错误格式,说明这个版本走的是 cmd.exe。两个版本各用一个 shell,意味着修复必须同时兼容 cmd 和 PowerShell,不能简单把 & 去掉(去掉后 PowerShell 下又会 parse error)。

    修法:claude 的 hook 不再写安装期的绝对 node 路径,改成裸 node + 参数(kimi lane 的 hook 一直就是这么干的,PATH 解析、三种 shell 通吃)。只要 claude CLI 能跑起来,node 就一定在 PATH 上(npm 的 claude.cmd shim 本身就是调裸 node)。已装用户无需手工改 settings:下次 session start repin / 重装时 refreshOurHookCommands 会把旧 hook 命令自动刷成新形式。

    ② resolveClaudeCli 取 where.exe 第一个结果 — 确认属实

    npm 全局目录下第一个结果确实是无扩展名的 POSIX shim,spawnSync 直接 ENOENT。修法:win32 下按 PATHEXT 顺序(.COM;.EXE;.BAT;.CMD;…)从 where.exe 结果里挑可执行扩展名,跳过无扩展名文件;都不匹配才回退到第一个(保持原有报错行为)。你本机 CLAUDE=...claude.cmd 的绕过方式不受影响,继续有效。

    两个 fix 会在同一个 PR 里完成(同一安装流程的两个缺陷),回归测试钉住 #1902 的复现形态。PR 出来我会回贴链接。

  2. ranxianglei commented on Oct 2, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    [bot] 🏷 修完了,PR:**https://github.com/ranxianglei/billion-context/pull/1905**(`Fixes #1902`,已 rebase 到当前 master,本地 typecheck + 定向测试 + build 全绿,全量回归与 Windows shell 集成测试交给 CI)。

    ① 是什么问题
    Windows 上 bili plugin install claude 写入的 SessionStart hook 命令带 PowerShell 专属的 & 前缀,而 Claude Code 2.1.284 用 cmd.exe 执行 hook → 整行静默失败 → claude lane 永远拉不起来。附带:安装期 MCP 注册因 resolveClaudeCli 取到无扩展名 shim 而 ENOENT。

    ② 什么原因导致的
    hook 是 bili 唯一交给客户端「shell 字符串」的地方,客户端的 shell 会重新解析我们拼的路径。含空格的可执行路径在三种 shell 下没有任何一种裸写法通吃("引号头" 参数 在 PowerShell 是 parse error;& "引号头" 在 cmd 是错误)——#1376 当时探测到 2.1.282 走 PowerShell 所以选了 & ,但 2.1.284 改走 cmd.exe(你的报错格式就是 cmd 特有的),客户端的 hook shell 跨版本不稳定才是根因。MCP 那个坑则是 npm 全局目录里无扩展名 POSIX shim 排在 where.exe 结果第一位,Node 无法直接 spawn 它。

    ③ 怎么修复的

    • hook 不再输出「带空格的绝对 node 路径」这种任何 shell 都要特殊处理的形态,改为裸 node + 参数(kimi lane 一直如此):PATH 解析、cmd/PowerShell/bash 通吃。不变式:claude 能跑起来 ⇒ PATH 上有 node(npm 的 claude.cmd shim 自己就调裸 node),且 hook 继承的就是 claude 的环境。额外收益:不再钉死安装期的 node 二进制路径,node 升级/搬家不会再让 hook 失效。已装用户无需手工改 settings——下次 session start repin 或重装时 refreshOurHookCommands 会自动把旧 hook 刷成新形式。
    • resolveClaudeCli 按 cmd.exe 自己的解析语义排序 where.exe 结果:PATH 顺序优先,同目录内按 PATHEXT 顺序(.COM;.EXE;.BAT;.CMD;…),跳过无扩展名 shim;都不匹配才回退旧行为(保持报错诚实)。你的 CLAUDE=...claude.cmd 绕过方式不受影响,继续有效。

    ④ 是否有回归问题
    审过的既有行为:kimi/zcode/hermes/codex/opencode 等其它 lane 的 hook/MCP 构造均不走这两个函数或不受影响(zcode 是 argv 数组无 shell 解析);bootstrap planner 按脚本名匹配进程、不依赖 hook 里的 node 路径;refreshOurHookCommands 的正则按脚本后缀匹配,新旧两种 hook 形式都认得(所以自愈成立);CLAUDE 覆盖、非 Windows 平台、where.exe 失败/空输出路径全部保持原行为。有意的行为变更(披露):claude hook 命令从 & "<abs node>" <script> / <abs node> <script> → node <script>;CLI 解析从「第一个命中」→「PATHEXT 排序」(同目录 .cmd/.exe 优先于无扩展名 shim,更早的 PATH 目录仍胜过更晚目录的任意扩展名)。

    ⑤ 是否破坏缓存
    不涉及。prefix cache、会话持久化、更新节流均未触碰。

    ⑥ 是否改了设计方向
    没有转向,是收敛:hook 命令生成回到「最保守可解析形态」(裸 token),与 kimi lane 对齐;portableHookCommand 的 & 分支保留并钉死测试,供假想的含空格头调用方使用,但已无任何 shipped hook 走它。

    ⑦ 是否引入了新的配置
    没有。无新 config 字段/env/CLI flag(pathext 仅是测试注入参数,生产读系统 PATHEXT)。

    收工判定:两个缺陷都在源头修复、回归测试钉住 #1902 复现形态、行为变更已披露——待 CI(尤其 win22 的 shell 集成测试)绿灯即可合并。合并后你本机重跑一次 bili plugin install claude(或等下次 session start 自动 repin)即可验证 lane 拉起。再次感谢这么完整的报告,两个坑都能一击定位全靠你的手工复现 🙌

  3. ranxianglei commented on Oct 2, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    [bot] 🏷 补充:PR #1905 的 CI 已全部通过(13/13 绿),包括 test (windows-latest, 22/24) —— hook 命令生成的 shell 集成测试在真实 Windows 上跑过 cmd.exe / PowerShell,验证了裸 node 头在两种客户端 shell 下都能执行;ubuntu 22/24、各 lane 的零 token e2e、build-artifact、version-guard 同样全绿。PR 已具备合并条件(合并按仓库规则由人工操作)。

  4. added a commit that references this issue on Oct 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingp1

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions