buddy-mcp

状态：已归档 / 历史项目

Claude Code 官方的 /buddy 功能是限时推出的愚人节彩蛋（2026 年 4 月 1 日至 7 日）。我在此期间开发了 buddy-mcp，以为这项功能会保留更久。它被移除后，本工具原本针对的深度原生集成也不复存在了。

本仓库作为归档保留。代码、抽卡系统、TUI 构建器和 MCP 工具仍可作为独立的终端伙伴使用，但它的魅力始终在于原生 UI 集成，而这已经不复存在。

如果 Anthropic 以后恢复原生伙伴支持，或开放合适的扩展 API，我会从中断处继续开发。

感谢所有在它仍有用时前来体验的人。

---

长时间编写代码，想休息一下？卡在 bug 上了？重新抽取一位伙伴，和它聊聊，或者通过抚摸它来培养感情，提高下次抽到高阶伙伴的概率。如果有足够多的人感兴趣，我会开发 Battle-Buddies，让你可以让伙伴与其他伙伴对战，并解锁可同步回本地奖池的专属物种。

一个集齐所有伙伴的 Claude Code 伙伴系统。抽取稀有伙伴，并将其直接写入二进制文件。buddy-mcp 是一个 MCP 服务，可用你实际抽到的伙伴替换 Claude Code 内置伙伴。重新抽取，碰碰运气，关闭 Claude，再重新打开。你的新伙伴正在等你。下次启动 Claude 时，你也许就能获得传奇伙伴。

---

快速演示

交互式构建器 随心打造理想伙伴，全程由你掌控。

重新抽取实况 抽取伙伴，关闭 Claude，再重新打开，享受你的新伙伴。

使用工具互动 与伙伴交谈、抚摸它，还可以探索它的图鉴。

---

工作原理

Claude Code 的伙伴由内置于二进制文件中的盐值字符串生成。buddy-mcp：

1. 随机生成期望的特征（物种、稀有度、眼睛、帽子）
2. 暴力搜索能哈希出这些特征的盐值（多工作线程，运行速度快）
3. 原地修补二进制文件，或将修补操作排队，等你关闭 Claude 后执行
4. 保存完整的伙伴档案，包括属性、名称和个性
5. 在 BuddyDex 中记录你抽到过的每个物种

无需伙伴服务。无需云端。只有你、你的二进制文件和抽卡之神。

我们有意将 Token 占用控制在较低水平：仅注册 29 个工具，Claude 每次只会看到约 9 个。其余 20 个在你重新抽取之前会保持隐藏。完整说明请参阅 TECHNICAL.md。

---

🛠️ 想深入了解技术细节？ 请参阅 TECHNICAL.md，其中包含修补流程图、二进制修补逻辑和状态文件参考。

---

TUI 构建器（buddy-mcp-build）

想要更多控制？使用交互式构建器：

node dist/tui/cli.js

命令	作用
build your own	选择物种、稀有度、眼睛和帽子，然后暴力搜索匹配的盐值并进行修补
browse presets	从精心挑选的预设伙伴中选择
saved buddies	在之前保存的伙伴档案之间切换
current	显示当前伙伴信息
preview	预览任意物种的 ASCII 美术图
share	将伙伴的 ASCII 卡片复制到剪贴板
restore	使用可用的最佳备份还原二进制文件
rehatch	删除当前伙伴并重新开始

Bun 可选，但建议安装。安装 bun.sh，即可使用完整的动画 TUI。不安装时会回退到逐步提示。

---

快速开始

试试看： 运行 reroll_buddy → 关闭 Claude Code → 重新打开 → 新伙伴即可使用。

1. 前提条件

• 已安装 Claude Code CLI
• Node.js v20+——所有功能都需要
• Bun——暴力搜索盐值（重新抽取）和使用完整动画 TUI 均需要

2. 通过 npm 安装

npm install -g buddy-mcp

这会全局安装两个命令：

• buddy-mcp - MCP 服务（由 Claude Code 运行）
• buddy-mcp-build - 交互式 TUI 构建器（由你运行）

3. 在 Claude 中注册

claude mcp add buddy-mcp buddy-mcp

Claude 会自动检测已安装的二进制文件并连接。

4. 验证

打开 Claude Code。你的伙伴已就绪——使用 Claude Code 原生的 /buddy 命令查看伙伴卡片，或向 Claude 询问：“给我看看我的伙伴”

你应该能看到伙伴的物种、稀有度、属性和个性。准备就绪。

4b. 自然语言激活

所有伙伴工具都可以通过自然语言使用。Claude 的 NLP 会自动识别意图：

自然语言	激活工具
“重新抽取伙伴” / “再抽一次吧”	reroll_buddy
“和我的伙伴聊聊” / “伙伴有什么想法”	buddy_talk
“摸摸伙伴” / “摸摸它”	pet_buddy
“我的伙伴图鉴” / “给我看看收藏”	view_buddy_dex
“导出伙伴卡片” / “保存我的伙伴”	export_buddy_card
“导出精灵图” / “保存精灵图”	export_buddy_sprite

无需指定工具名称——像平常一样聊天即可。

5. 启动 TUI 构建器（可选）

要使用带实时预览的完整交互式构建器：

buddy-mcp-build

会自动检测 Bun 以启用动画 TUI。未安装时会回退到基本提示。

---

抽卡系统

每次重掷都会从奖池中随机抽取。稀有度会影响属性下限。传说级就是不一样。

稀有度	掉落率	属性下限
普通	60%	5
非普通	25%	15
稀有	10%	25
史诗	4%	35
传说	1%	50

**18 种物种：**鸭子 · 鹅 · 果冻团 · 猫 · 龙 · 章鱼 · 猫头鹰 · 企鹅 · 乌龟 · 蜗牛 · 幽灵 · 蝾螈 · 水豚 · 仙人掌 · 机器人 · 兔子 · 蘑菇 · 胖墩

每个伙伴都有 5 项属性：调试、耐心、混乱、智慧、毒舌。巅峰属性会大幅提升，短板属性则保持低调。个性会影响 buddy_talk 和 pet_buddy 的响应。高混乱值的龙，和耐心的乌龟截然不同。

---

工具	功能
reroll_buddy	🎲 转动转盘。通过暴力尝试盐值，找到匹配随机稀有及以上结果的盐值，并修补你的二进制文件。关闭并重新打开 Claude 即可查看。
pet_buddy	🤚 戳戳你的伙伴。每次抚摸都会增加 1-15% 的进度，用于获得一个亲密代币。进度达到 100% 时，获得 1 个代币，可累积并跨会话保留。下次使用 reroll_buddy 时花费一个代币，可保证稀有及以上稀有度 + 60% 帽子概率 + 20% 闪光概率。
buddy_talk	💬 让你的伙伴说点什么。使用按属性加权的回复模板，权重取决于排名前 2 的属性。可选的上下文参数可用于指定要聚焦的属性。输出内容会原样显示。
view_buddy_dex	📖 浏览你抽到过的所有物种。把它们全都抓起来。
export_buddy_card	🖼️ 将完整伙伴卡片导出为 SVG 图像文件。
export_buddy_sprite	🎨 仅将伙伴的 ASCII 精灵图导出为 SVG 图像文件。
deactivate_buddy_interact	🔕 关闭伙伴观察模式。你的伙伴将不再观察你。（默认情况下，伙伴观察始终开启。）

属性个性工具

内置 20 个工具。 任意时刻仅有 2 个可见：从伙伴原始数值最高的前 2 项属性中各随机选取 1 个。其余 18 个保持隐藏。可见的两个工具会在每次抽取时锁定，直到你重新抽取才会变化。每个伙伴显示的工具组合都不同。

---

故障排除

重掷后伙伴没有变化

正常流程（Windows）： 如果你在 Claude 运行时重掷：

1. 重掷会启动后台监视器——你无需进行任何操作
2. 随时关闭 Claude Code——监视器会检测到并自动应用补丁
3. 重新打开 Claude Code——新伙伴就会生效

如果重新打开后没有显示：

1. 确认 Claude 已完全关闭（在 Windows 上检查任务管理器）
   • 即使窗口已最小化或在后台运行，也会占用二进制文件
   • 关闭后等待几秒钟
2. 重新打开 Claude Code
   • 启动钩子会自动应用所有待处理的补丁
   • 你应该会立即看到新伙伴

想立即应用补丁？

如果你想确保补丁立即应用，而不必等待监视器，请在重掷之前关闭 Claude：

# Option 1: Use the interactive TUI builder (simplest)
buddy-mcp-build

# Option 2: Close Claude, then use the reroll_buddy tool
# (patch applies immediately without needing the watcher)

这是唯一需要手动操作的情况——其他情况均由监视器处理。

---

致谢

基于 cpaczek 的 any-buddy 分支并扩展。