AI-Wiki

定义与身份

version-check.js 是 claude-mem 在 Setup 阶段使用的版本检查脚本，定位是一个快速、非阻塞的安装新鲜度检测器。

它对应的是 Hook 架构中的 Setup Hook，在每次会话开始前运行，但不负责安装运行时，也不直接修复环境。它的职责只是检查当前安装是否过期，并在发现问题时提示用户执行修复命令。

文档明确说明：真正的运行时安装工作由 npx claude-mem install 和 npx claude-mem repair 在 Hook 之外完成；version-check.js 本身只做一个 sub-100ms 的版本标记检查。

所属位置与调用方式

version-check.js 的源码位置是 scripts/version-check.js，在 Setup 阶段通过如下命令调用：

{
  "hooks": {
    "Setup": [{
      "hooks": [{
        "type": "command",
        "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/version-check.js",
        "timeout": 60
      }]
    }]
  }
}

这里的超时配置是 60，但文档对它的实际设计目标说得更严格：它应当在 100 毫秒以内完成。

角色职责

version-check.js 的核心职责只有一个：

检测当前插件加载版本与已安装运行时是否一致。
如果不一致，提醒用户执行修复。
无论结果如何，都不要阻塞 Claude Code 的主会话。

这与 Hooks architecture 摘要中的总体原则一致：从外部观察主会话、在合适时机注入能力，但不打断、不修改 Claude Code 的正常行为。

工作机制

根据文档，version-check.js 的工作流程是固定的四步：

读取由 npx 安装器写入的 .install-version 标记文件。
将该标记与当前加载的插件版本进行比较。
如果发现版本不匹配，则向 stderr 写入 run: npx claude-mem repair。
始终以退出码 0 结束。

其中第 1 步里的 .install-version 不是临时信息，而是由 npx claude-mem install 或 npx claude-mem repair 在完成安装时写下的版本标记，用来代表“当前运行时是按哪个插件版本准备好的”。

第 2 步比较的对象是：

安装器此前写入的 .install-version 标记；
当前已经加载的插件版本。

如果两者不同，系统就认为这是一次陈旧安装（stale install），典型场景是插件被外部升级了，但插件缓存里的运行时环境没有同步更新。

检测到不匹配时的行为

当 version-check.js 发现 .install-version 与当前插件版本不一致时，它不会尝试自动安装，也不会中止会话，而是只做一件事：

向标准错误输出写入：run: npx claude-mem repair

这条信息的作用是给出明确、可执行的修复指令。文档特别指出，这种不匹配通常发生在插件被外部升级后，例如执行了 claude plugin update，导致插件代码版本变了，但先前安装好的运行时依旧停留在旧版本状态。

非阻塞边界

version-check.js 的一个关键设计边界是：永远不能阻塞会话启动。

因此它有两个非常明确的约束：

始终退出码为 0；
只做 sub-100ms 的轻量检查。

“始终退出 0” 的含义是，即使检测出版本不匹配、即使安装已经过期，它也只是提示修复，而不会把 Setup 阶段变成失败状态。这满足 Hook 体系的非侵入式要求：Hook 失败不能破坏 Claude Code 主流程。

“sub-100ms” 的含义则是它不能执行重安装、不能拉取依赖、不能进行重型初始化。文档还明确强调，它除了读取版本标记外，没有额外的 I/O。

它不做什么

为了避免与安装器职责混淆，version-check.js 的非职责范围也很重要：

不安装 Bun；
不安装 uv；
不执行 bun install；
不写入 .install-version；
不在 Setup 阶段直接修复损坏或过期环境。

这些工作都属于 npx claude-mem install 与 npx claude-mem repair。文档指出，这两个命令会在插件缓存中准备运行时，包含全局安装 Bun 与 uv、执行 bun install，并写入 .install-version 标记；整个过程在可见的 clack spinner 后面完成。

在整体架构中的位置

在 claude-mem 的 Hook 生命周期里，version-check.js 属于 Setup 阶段的预检查脚本，而不是后续的业务 Hook 之一。

与其他脚本相比，它的角色非常特殊：

不像 summary-hook.js 那样生成会话摘要；
不像 cleanup-hook.js 那样在 SessionEnd 阶段收尾；
也不像 SessionStart、UserPromptSubmit、PostToolUse 对应脚本那样处理上下文注入、会话初始化或 observation 捕获。

它更接近一种 Progressive Enhancement 式的保护层：在不干扰主流程的前提下，尽早发现环境陈旧问题，并把修复动作留给显式命令完成。

关键事实汇总

读取由 npx 安装器写入的 .install-version 标记文件。
将该标记与当前加载的插件版本进行比较。
发现不匹配时向 stderr 写入 run: npx claude-mem repair。
始终以退出码 0 结束，以保持非阻塞。
运行在 Setup 阶段，每次会话前执行。
目标执行时间小于 100ms。
Setup Hook 自身不负责安装任何运行时。

version-check.js