autoupgrade-icp-cli

设置 icp CLI 自动升级

这是一个一次性安装程序：它会添加一个 SessionStart 钩子，用于检查 icp 和 ic-wasm 是否为最新版本，并在用户需要时于工作开始前升级它们。完成这些步骤后，用户再也不需要这个技能。

除了 icp，这里也会检查 ic-wasm，因为官方配方（@dfinity/motoko、 @dfinity/rust、@dfinity/static-site、@dfinity/asset-canister）每次构建都会调用它。 如果 icp 已升级而 ic-wasm 仍是旧版本，就会导致构建失败，看起来像是配方有问题，因此只升级其中一个并非理想的默认做法。

icp 自带检查功能（icp settings update-check），值得保持开启，但只有用户运行 icp 命令后才会提示——到那时，Agent 已经决定好要写什么了。这个钩子会在会话的第一条提示词之前运行，因此版本信息会提前进入 Claude 的上下文，而且它也会检查 ic-wasm。

步骤 1 — 询问用户想要哪种模式

安装程序无法替用户做这个决定，因此在写入任何内容前先询问：

“钩子发现有新版本时，有两种行为模式可选： 通知 — 显示版本信息和确切的升级命令，但在你运行该命令前不会安装任何内容。自动 — 在会话开始时自动执行升级。你想选哪种？之后可以编辑钩子中的一个标志来切换。”

如果用户没有偏好，默认选通知——这是可撤销的选择。

还要说明添加钩子的含义，并且不要尝试绕过审批：

“我将添加一个运行 .claude/upgrade-icp-cli.sh 的 SessionStart 钩子。Claude Code 会在钩子自动运行前要求你批准并信任它。”

步骤 2 — 检查前置条件

command -v curl   >/dev/null 2>&1 && echo "curl: ok" || echo "curl: MISSING"
icp --version     2>/dev/null     || echo "icp: not installed"
ic-wasm --version 2>/dev/null     || echo "ic-wasm: not installed"

如果缺少任一工具，告知用户安装命令 （npm install -g @icp-sdk/icp-cli @icp-sdk/ic-wasm），但不要在未经提示的情况下运行——安装工具链与保持工具链为最新版本是两种不同的决定。

步骤 3 — 下载脚本

直接获取已发布的脚本，不要手动转录，这样上游更新时渠道检测也能保持正确：

mkdir -p .claude
curl -fsSL https://skills.internetcomputer.org/.well-known/skills/autoupgrade-icp-cli/scripts/upgrade-icp-cli.sh \
  -o .claude/upgrade-icp-cli.sh

不要手动编写或改述脚本。

步骤 4 — 注册 SessionStart 钩子（幂等）

如果 .claude/settings.json 不存在，就用下方内容创建。如果文件已存在，则合并：保留所有现有键、钩子和权限；仅当尚无等效的 bash .claude/upgrade-icp-cli.sh 命令时，才添加 SessionStart 条目；然后将解析后的 JSON 写回。绝不要覆盖文件。

通知模式（默认）：

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "bash .claude/upgrade-icp-cli.sh --mode notify" }
        ]
      }
    ]
  }
}

自动模式——使用相同条目并添加 --mode auto，同时提高 timeout，因为安装 CLI 二进制文件可能超过默认的 60 秒；如果安装超时，工具会处于只写入了一半的状态：

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "bash .claude/upgrade-icp-cli.sh --mode auto", "timeout": 300 }
        ]
      }
    ]
  }
}

每当你为某人设置自动模式钩子时，都要说明这确实意味着什么：它会在项目处于打开状态时升级构建工具链，并在运行期间阻止会话启动，因此会话启动时使用的 icp 可能与上次会话结束时不同——这可能会改变项目的构建行为和输出，而该项目昨天还能正常构建。有些团队需要这样的行为，另一些团队则会固定版本以避免变化。

步骤 5 — 运行一次、验证并汇报

bash .claude/upgrade-icp-cli.sh --mode notify   # or --mode auto, matching the hook

没有任何输出表示两个工具都是最新版本——这就是成功，而不是失败。手动运行时总会检查网络；钩子会进行节流（见下文），所以当有人想立即得到结果时，也可以运行这个命令。

然后确认钩子条目只出现一次，汇报检测到的版本以及是否进行了升级，并提醒用户留意信任提示。如果项目会提交 .claude/，请将 .claude/.icp-upgrade-check 添加到 .gitignore——它是每台机器各自的时间戳，不是共享配置。

脚本如何决定要运行什么

脚本会解析每个二进制文件的符号链接，并根据路径读取安装渠道，因为不同渠道的升级命令不同，猜错会导致 PATH 上存在两份互相遮蔽的 CLI：

二进制文件解析到的位置	渠道	升级命令（icp / ic-wasm）
…/node_modules/@icp-sdk/…	npm	npm install -g @icp-sdk/icp-cli@latest / npm install -g @icp-sdk/ic-wasm@latest
…/Cellar/…	Homebrew	brew upgrade icp-cli / brew upgrade ic-wasm
~/.config/<app>/ 中的 cargo-dist 收据	shell 安装程序	icp-cli-update / ic-wasm-update
其他任何位置	未知	(无——改为报告发布页面 URL)

最后一行是刻意如此：遇到无法识别的安装时，只会报告，绝不猜测。

有两点值得提醒用户：

• 被遮蔽的安装不会升级。 如果升级成功，但 PATH 仍解析到旧版本，说明另一个渠道的副本正在生效——常见情况是 nvm 下的 npm 全局安装与 ~/.cargo/bin 中的 shell 安装程序副本并存。升级一个渠道绝不会影响另一个渠道的副本；解析二进制文件（command -v icp）查看哪个副本生效，然后删除其中一个，或升级 PATH 上实际生效的那个。
• 自动模式绝不会运行 sudo。 如果 npm 前缀不可写，脚本会改为报告一条 sudo … 命令，因为钩子中的密码提示没有终端可供输入。

节流

成功访问发布源的检查会记录在 .claude/.icp-upgrade-check 中，并且 6 小时内不会重复，因此大多数会话启动时，钩子的开销约为 10 ms，而不是约 1 s。可通过 ICP_UPGRADE_CHECK_INTERVAL=<seconds> 覆盖（0 表示禁用），或使用 --force 绕过一次；从终端运行时始终会执行检查。检查失败时不会记录，因此离线会话会在下次运行时重试。

此操作不会升级的内容

此钩子只管理两个 CLI 二进制文件。icp.yaml 中的 Recipe 版本（@dfinity/[email protected] 等）以及 Motoko 工具链（moc、mops、mops.toml 中的 [toolchain] 固定版本）都是按项目固定的，由用户自行决定——分别加载 icp-cli 和 mops-cli 来管理这些内容。

如果自动升级后构建开始失败，请先查看 icp-cli 发布说明，再判断是否是项目出了问题。

其他参考资料

• icp-cli — CLI 本身的使用方法：icp.yaml、Recipe、环境和部署。
• mops-cli — Motoko 工具链及其自身的版本固定。
• autosync-ic-skills — 配套安装程序，用于保持 .claude/skills/ 中的 IC 技能为最新。两者互不依赖；同时安装很常见。