ruflo 安装被未发布依赖 pin 卡住（@claude-flow/mcp alpha 未发布）

你会遇到什么

执行安装/CI 时，解析依赖的阶段卡住不往前走，报 @claude-flow/mcp 相关依赖无法解析——你重试、换网络都没用。这不是网络问题：依赖 pin 指向了一个还没发布的版本，解析器找不到，怎么试都不会出现。

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

先给结论：依赖声明里 pin 了一个未发布的版本（issue #3095，open 2026-08-25：@claude-flow/mcp alpha.10 未发布），解析期直接失败。

链路：npm/npx 解析依赖 → 拉取 registry 元数据 → 按 pin 版本查找 → 版本不存在 → 解析失败。断点在第三步：发布节奏问题，客户端无解。

对照实测（2026-08-29）：本环境 npx -y ruflo init（v3.38.20 + npmmirror）没有复现——此时版本已满足（如实标注未复现）；说明这是一个时间窗问题：上游发布后自愈。

推论：pin 类解析失败先验证「该版本是否真实存在」（npm view <包> versions），再选路：等发布、锁可用版本区间、或换源重试（npmmirror 同步有延迟时回官方源）。

一步步来

1. 验证版本是否存在 — 必做

npm view @claude-flow/mcp versions：若 pinned 版本不在列表 = 未发布，重试无意义。

2. 等发布或锁可用版本 — 按场景

上游发布后重试；或在你自己的依赖里锁定已发布的可用版本区间。

3. 换源再试 — 排查

npmmirror 同步有延迟时回官方源；反向同理（官方慢时走 npmmirror）。

4. 反馈上游 — 排查

确认是未发布 pin 后，在对应 issue 里跟进（#3095），不要在本地下功夫。

怎么确认修好了

• 依赖解析阶段正常推进直至安装完成；
• ruflo --version 正常输出；init 流程可跑通（2026-08-29 实测同款路径）。

其它环境的表现

• CI 流水线：解析失败会让整条流水线红；先判定 pin 问题再改流水线；
• 时间窗：上游发布后自愈——遇到时先查 issue 时间线；

症状

安装/CI 卡在依赖解析，@claude-flow/mcp 相关依赖无法解析。

原因

依赖 pin 指向未发布版本（issue #3095，open 2026-08-25：@claude-flow/mcp alpha.10 未发布），解析期失败。

解法

1. 等上游发布后重试；或安装时锁定已发布的可用版本区间。
2. 换 npm 源重试（npmmirror 同步有延迟时回官方源）。