深入 claude-sneakpeek 源码：Step-based VariantBuilder 如何优雅构建 Claude Code 变体

claude-sneakpeek是一款帮你构建Claude Code 隔离变体（variant）的开源工具：它会安装一份与现有安装完全独立的 Claude Code（独立配置、会话、MCP 服务器和凭证），并通过补丁解锁 swarm mode（蜂群模式）等未公开的特性。本文带你深入它的源码，看看核心的Step-based VariantBuilder是如何把「构建一个变体」这件复杂的事拆成一条优雅、可组合的流水线。

先搞清楚：claude-sneakpeek 构建了什么？

运行一条命令：

npx @realmikekelly/claude-sneakpeek quick --name claudesp

工具就会在你的机器上「长出」一个完整的隔离实例：

~/.claude-sneakpeek/claudesp/ ├── npm/ # 独立安装的 Claude Code ├── config/ # 独立配置、会话、MCP 服务器 └── variant.json # 变体元数据 ~/.local/bin/claudesp # 包装脚本，直接当命令用

构建过程涉及目录创建、npm 安装、源码补丁（开启 swarm mode）、主题定制、包装脚本生成等一系列操作。步骤一多，代码就容易变成「意大利面」。claude-sneakpeek 的答案就是：把每个动作抽象成一个 Step（步骤），由 Builder 统一编排。

整体设计：一个 Context + 一群 Step

核心实现位于 src/core/variant-builder/ 目录。整个模式只有两个关键角色：

• BuildContext（构建上下文）：在 types.ts 中定义，是贯穿所有步骤的「共享背包」，包含四个部分：
  • paths：所有预计算的路径（变体目录、config 目录、npm 目录、包装脚本路径等）
  • prefs：解析好的偏好设置（npm 包名、是否启用 prompt pack、技能安装等）
  • state：构建过程中累积的可变状态（二进制路径、警告备注、最终元数据）
  • report：进度上报函数，CLI/TUI 界面靠它显示「Installing...」「Writing configuration...」
• BuildStep（构建步骤）：每个步骤是一个实现execute(ctx)/executeAsync(ctx)接口的小类，只依赖上下文、彼此不感知，可以任意增删排序。

VariantBuilder的构造函数就是一张「工序表」，见 VariantBuilder.ts：

注意第 3 步和第 6 步的注册方式——它们由特性开关条件注册（如...(NATIVE_MULTIAGENT_SUPPORTED ? [new SwarmModeStep()] : [])），开关定义在 constants.ts。这让「某版本不支持某特性」变成一行声明，而不是散落各处的 if 判断。

亮点步骤：SwarmModeStep 如何「解锁」蜂群模式

swarm mode 是 claude-sneakpeek 最核心的卖点。它的原理非常克制：

Claude Code 2.1.16+ 内部已经写好了多智能体代码（TeammateTool、任务委托、成员消息邮箱等），只是被一个 feature flag 门控函数挡着。swarm-mode-patch.ts 用正则定位这个门控函数，把它替换为「永远返回 true」的版本。补丁流程在 SwarmModeStep.ts 中，每一步都很「防御式」：

1. 先备份：cli.js→cli.js.backup，随时可还原
2. 补丁失败不崩溃：找不到门控函数时，只往state.notes里追加一条警告，构建继续进行
3. 写回后验证：重新读取文件并检测状态，确认补丁真正生效才标记swarmModeEnabled = true

关于门控函数细节，可参考项目内的调研文档 docs/research/native-multiagent-gates.md。

最后一步 FinalizeStep.ts 会把整个构建过程沉淀为variant.json（provider、npm 版本、swarmModeEnabled等），后续的 update / doctor / remove 都依赖这份元数据。

同步 + 异步双模：消灭重复代码的动机

源码文件头注释直接点明了设计动机：「This builder eliminates duplication between sync and async createVariant functions」。

为什么需要两种模式？同步版给 CLI 快速路径用；异步版给 TUI 界面用——长耗时操作（比如 npm 安装）期间，report函数里会yieldToEventLoop()（通过setImmediate让出事件循环），让 Ink/React 界面有机会刷新进度条。

于是每个 Step 只需实现两个方法，Builder 按构造时传入的isAsync决定走哪条路，见 index.ts 中极简的公开 API：

export const createVariant = (params) => new VariantBuilder(false).build(params); export const createVariantAsync = async (params) => new VariantBuilder(true).buildAsync(params);

新增一个功能步骤？写一个小类、往工序表里插一行，同步异步两条路自动都生效——这正是 Step-based 设计最优雅的地方：变化的部分被封装在 Step 内部，不变的编排逻辑永远不动。

更新流程同样优雅：VariantUpdater

变体更新没有另起炉灶，而是复用同一套模式：VariantUpdater.ts 维护一条update-steps工序表（重构建 → 重装 npm → swarm 补丁 → 模型映射 → 主题 → 包装脚本 → 配置 → 元数据），上下文类型是UpdateContext，同样支持同步/异步双模。创建和更新两条流水线对称，心智负担减半。

总结：三个可以抄走的工程实践

1. Builder + Step 编排：把多阶段流程拆成语义清晰的原子步骤，Builder 只负责顺序，Step 只负责自己的事，新增功能零侵入；
2. 单一 Context 贯穿：路径、偏好、状态、上报函数集中在一个对象里传递，避免参数爆炸；
3. 双模执行：execute/executeAsync成对实现 + 事件循环让位，同一套步骤同时服务 CLI 和 TUI 进度显示。

想动手研究的话，可以从以下入口读起：

• 编排核心：VariantBuilder.ts 与 types.ts
• 全部步骤：src/core/variant-builder/steps/
• 更新流水线：src/core/variant-builder/update-steps/
• 架构总览：docs/architecture/overview.md
• 特性文档：swarm mode 相关特性、Mirror Claude 变体
• 支持仓库克隆后运行npx @realmikekelly/claude-sneakpeek quick --name claudesp快速体验完整构建流程 🚀