BUDDY 伴侣系统

01 概览

在 Claude Code 的源码树里，藏着一个完整但并未正式对外发布的 Tamagotchi 风格伴侣系统，代号 BUDDY。它不是玩笑式占位符，而是一套真正可运行的功能：会生成生物、渲染动画、写入配置、注入系统提示，并在启动阶段做预告。

如果该功能被打开，终端角落会出现一只小型 ASCII 生物。它的物种、眼睛、帽子、稀有度和属性由用户 ID 决定性生成；名字和性格则作为“灵魂”单独存储。这种“骨骼 / 灵魂”分离设计，是整套系统最巧妙的工程点之一。

该系统跨越六个源文件 src/buddy/: types.ts, companion.ts, sprites.ts, CompanionSprite.tsx, prompt.ts， 和 useBuddyNotification.tsx。 每个文件都有明确的职责，整个设计因其巧妙的工程决策而值得仔细阅读。

02 系统架构

BUDDY 这套系统最有意思的地方，是它把“伴侣是什么”拆成了两层：骨骼（物种、眼睛、帽子、稀有度、属性）是确定性的；灵魂（名字、性格、孵化时间）是后天生成并持久化的。

这样一来，系统既能保证同一个用户跨会话拿到的是同一只生物，又能保留足够的个性化空间。工程上，这种拆分同时解决了反作弊、改名兼容和未来扩展三件事。

关键的架构洞察力是 骨头/灵魂分裂:

• Bones （物种、眼睛、帽子、稀有度、统计数据）总是从 hash(userId) — 他们从不接触磁盘。
• Soul （姓名、性格、 hatchedAt）存储在 config.companion 作为 StoredCompanion.

03 Companion.ts — 确定性生物生成

companion.ts 负责把一个用户 ID 变成具体生物配置。关键不在于“随机”，而在于“对同一个用户来说始终随机得一样”。这也是为什么这里不用 Math.random()，而要走可复现的种子 PRNG。

从用户视角看，这意味着你的伴侣像是“抽出来的”；从系统视角看，这其实是一段完全可重复的函数映射：userId + salt -> seed -> bones。

// Mulberry32 — tiny seeded PRNG, good enough for picking ducks
function mulberry32(seed: number): () => number {
  let a = seed >>> 0
  return function () {
    a |= 0
    a = (a + 0x6d2b79f5) | 0
    let t = Math.imul(a ^ (a >>> 15), 1 | a)
    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t
    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
  }
}

种子来自对用户 ID 字符串进行哈希处理。 在 Bun（运行时 Claude Code 使用）上，它委托给 Bun.hash(); 在其他环境中，它会回退到 FNV-1a 实现：

function hashString(s: string): number {
  if (typeof Bun !== 'undefined') {
    return Number(BigInt(Bun.hash(s)) & 0xffffffffn)
  }
  let h = 2166136261  // FNV offset basis
  for (let i = 0; i < s.length; i++) {
    h ^= s.charCodeAt(i)
    h = Math.imul(h, 16777619)
  }
  return h >>> 0
}

const SALT = 'friend-2026-401'

稀有卷

稀有度是通过加权随机抽取来选择的。 权重定义为满足约束常数 types.ts:

export const RARITY_WEIGHTS = {
  common:    60,
  uncommon:  25,
  rare:      10,
  epic:       4,
  legendary:  1,
} as const satisfies Record<Rarity, number>

共同的同伴 never 买一顶帽子。 帽子检查是单行 rollFrom():

hat: rarity === 'common' ? 'none' : pick(rng, HATS),

闪亮的旗帜

有百分之一的机会（rng() < 0.01）任何同伴都会滚动为“闪亮”——一种与稀有性不同的视觉变体。 传奇般的闪亮是万分之一的结果。

Stats

每个同伴都有五项统计数据： DEBUGGING, PATIENCE, CHAOS, WISDOM， 和 SNARK。 滚动是 RPG 风格的 - 一个峰值统计数据，一个转储统计数据，其余分散 - 并且所有楼层都以稀有度缩放：

function rollStats(rng, rarity): Record<StatName, number> {
  const floor = RARITY_FLOOR[rarity]
  const peak = pick(rng, STAT_NAMES)
  let dump = pick(rng, STAT_NAMES)
  while (dump === peak) dump = pick(rng, STAT_NAMES) // no ties

  for (const name of STAT_NAMES) {
    if (name === peak)  stats[name] = Math.min(100, floor + 50 + Math.floor(rng() * 30))
    else if (name === dump) stats[name] = Math.max(1,   floor - 10 + Math.floor(rng() * 15))
    else                   stats[name] = floor + Math.floor(rng() * 40)
  }
}

传奇人物的巅峰属性在之前可以达到130 Math.min(100, ...) 上限 - 意味着传奇同伴总是最大化他们的峰值统计数据。

性能：滚动缓存

// Called from three hot paths (500ms sprite tick, per-keystroke PromptInput,
// per-turn observer) with the same userId → cache the deterministic result.
let rollCache: { key: string; value: Roll } | undefined
export function roll(userId: string): Roll {
  const key = userId + SALT
  if (rollCache?.key === key) return rollCache.value
  const value = rollFrom(mulberry32(hashString(key)))
  rollCache = { key, value }
  return value
}

由于 PRNG 结果对于每个用户来说都是确定性的，并且是从三个热路径（500ms 计时器、每次击键处理程序、每轮观察者）调用的，因此结果缓存在模块级变量中。 缓存已开启 userId + SALT，因此用户更改（例如切换帐户）会自动破坏它。

04 types.ts — 物种、眼睛、帽子和混淆的名称

types.ts 乍看只是常量列表，实际上里面埋了一个很工程化的约束：有个物种名会撞上内部模型代号金丝雀，所以整个物种集合都改成运行时构造，避免某一个名字显得特别可疑。

这类处理不是为了“炫技混淆”，而是在 CI 审查规则和代码可读性之间找平衡。统一编码所有物种，比只编码一个异常值要更不暴露实现意图。

物种混淆

一个物种名称是在运行时通过十六进制字符代码而不是字符串文字构造的。 评论准确地解释了原因：

// One species name collides with a model-codename canary in excluded-strings.txt.
// The check greps build output (not source), so runtime-constructing the value
// keeps the literal out of the bundle while the check stays armed for the
// actual codename. All species encoded uniformly; `as` casts are type-position
// only (erased pre-bundle).
const c = String.fromCharCode

export const duck    = c(0x64,0x75,0x63,0x6b) as 'duck'
export const goose   = c(0x67,0x6f,0x6f,0x73,0x65) as 'goose'
// ... 16 more species

Anthropic 具有 CI 检查，可对某些字符串（“金丝雀”）的构建输出进行 grep，以检测模型代号的意外泄漏。 18 个物种名称之一恰好与型号代号相匹配。 通过在运行时计算所有物种名称 String.fromCharCode，没有任何字符串文字出现在编译后的包中 - 因此金丝雀检查继续正确地完成其工作，而不会标记无辜的宠物名称。

完整物种列表

    __
  <(· )___
   (  ._>
    `--´

     (·>
     ||
   _(__)_
    ^^^^

   .----.
  ( ·  · )
  (      )
   `----´

   /\_/\
  ( ·   ·)
  (  ω  )
  (")_(")

  /^\  /^\
 <  ·  ·  >
 (   ~~   )
  `-vvvv-´

   .----.
  ( ·  · )
  (______)
  /\/\/\/\

   /\  /\
  ((·)(·))
  (  ><  )
   `----´

  .---.
  (·>·)
 /(   )\
  `---´

   _,--._
  ( ·  · )
 /[______]\
  ``    ``

 ·    .--.
  \  ( @ )
   \_`--´
  ~~~~~~~

   .----.
  / ·  · \
  |      |
  ~`~``~`~

}~(______)~{
}~(· .. ·)~{
  ( .--. )
  (_/  \_)

  n______n
 ( ·    · )
 (   oo   )
  `------´

 n  ____  n
 | |·  ·| |
 |_|    |_|
   |    |

   .[||].
  [ ·  · ]
  [ ==== ]
  `------´

   (\__/)
  ( ·  · )
 =(  ..  )=
  (")__(")

 .-o-OO-o-.
(__________)
   |·  ·|
   |____|

  /\    /\
 ( ·    · )
 (   ..   )
  `------´

眼睛和帽子

export const EYES = ['·', '✦', '×', '◉', '@', '°'] as const

export const HATS = [
  'none', 'crown', 'tophat', 'propeller',
  'halo', 'wizard', 'beanie', 'tinyduck',
] as const

眼睛角色通过 {E} 精灵字符串中的模板占位符 — replaceAll('{E}', bones.eye)。 这就是一组精灵 ASCII 艺术如何适用于所有 6 种眼睛样式。

05 sprites.ts — ASCII 艺术引擎

ASCII 精灵系统真正处理的不是‘画几只小动物’，而是如何在极窄的字符约束里同时支持多物种、多眼睛、多帽子和多帧动画，并且不让终端布局乱跳。

因此这里的实现更接近一个小型模板引擎：基础帧给出身体结构，眼睛占位符负责个性差异，帽子槽负责顶部装饰，而动画帧则负责节拍感和生命感。

// Each sprite is 5 lines tall, 12 wide (after {E}→1char substitution).
// Multiple frames per species for idle fidget animation.
// Line 0 is the hat slot — must be blank in frames 0-1; frame 2 may use it.
const BODIES: Record<Species, string[][]> = {
  [duck]: [
    ['            ', '    __      ', '  <({E} )___  ', '   (  ._>   ', '    `--´    '],
    ['            ', '    __      ', '  <({E} )___  ', '   (  ._>   ', '    `--´~   '], // tail wiggle
    ['            ', '    __      ', '  <({E} )___  ', '   (  .__>  ', '    `--´    '], // bill shift
  ],
  // ... 17 more species
}

The renderSprite() 函数按顺序处理三个问题：

export function renderSprite(bones: CompanionBones, frame = 0): string[] {
  const frames = BODIES[bones.species]
  const body = frames[frame % frames.length]!.map(line =>
    line.replaceAll('{E}', bones.eye),  // 1. substitute eye
  )
  const lines = [...body]
  if (bones.hat !== 'none' && !lines[0]!.trim()) {
    lines[0] = HAT_LINES[bones.hat]         // 2. inject hat (only when row 0 is blank)
  }
  if (!lines[0]!.trim() && frames.every(f => !f[0]!.trim()))
    lines.shift()                            // 3. drop blank hat row when no hat + no animation
  return lines
}

步骤 3 是一个微妙的布局优化：如果一个物种从不使用顶行进行动画效果并且没有帽子，则完全删除该行，以便精灵渲染得更紧凑。 但是，如果任何帧使用该行（例如第 2 帧中的龙的喷火），则该行必须在所有帧上保持存在，否则精灵将在动画期间改变高度 - 这将导致终端布局跳跃。

帽子的定义

const HAT_LINES: Record<Hat, string> = {
  none:      '',
  crown:     '   \\^^^/    ',
  tophat:    '   [___]    ',
  propeller: '    -+-     ',
  halo:      '   (   )    ',
  wizard:    '    /^\\     ',
  beanie:    '   (___)    ',
  tinyduck:  '    ,>      ',
}

The tinyduck 帽子使一只小鸭子坐在你同伴的头上。 戴着小鸭帽的鸭子是宇宙允许的可能性。

06 CompanionSprite.tsx — 实时动画小部件

CompanionSprite 把静态骨骼变成会动的伴侣。它决定什么时候眨眼、什么时候进入兴奋态、什么时候显示宠物爱心，以及窄终端和全屏模式下分别应该怎样布局。

从架构上说，它既是渲染组件，也是行为调度器。BUDDY 的‘活着’感，主要就来自这里的节拍、时序和模式切换。

动画常量和空闲序列

const TICK_MS = 500             // 2 ticks per second
const BUBBLE_SHOW = 20          // ticks → ~10s visible
const FADE_WINDOW = 6           // last ~3s: bubble dims as warning
const PET_BURST_MS = 2500       // hearts float for 2.5s after /buddy pet

// Idle sequence: mostly rest (frame 0), occasional fidget (frames 1-2), rare blink.
// Sequence indices map to sprite frames; -1 means "blink on frame 0".
const IDLE_SEQUENCE = [0, 0, 0, 0, 1, 0, 0, 0, -1, 0, 0, 2, 0, 0, 0]

空闲序列经过仔细加权：同伴大部分时间都在第 0 帧中休息，偶尔坐立不安（第 1 帧和第 2 帧），并且很少眨眼（索引 -1 通过用破折号替换眼睛字符来表示眨眼）。 这给了生物一种自然、有机的感觉，而不是机械循环。

宠物之心动画

const H = figures.heart  // ♥
const PET_HEARTS = [
  `   ${H}    ${H}   `,
  `  ${H}  ${H}   ${H}  `,
  ` ${H}   ${H}  ${H}   `,
  `${H}  ${H}      ${H} `,
  '·    ·   ·  ',   // hearts fade to dots on last frame
]

当你跑步时 /buddy pet，该组件在精灵上方显示 5 帧漂浮的心，每帧循环 500 毫秒（总共 2.5 秒）。 最后一帧淡入点——这是一种有意的放松，而不是突然的中断。

兴奋与空闲动画模式

if (reaction || petting) {
  spriteFrame = tick % frameCount   // excited: cycle all frames fast
} else {
  const step = IDLE_SEQUENCE[tick % IDLE_SEQUENCE.length]!
  if (step === -1) { spriteFrame = 0; blink = true }
  else { spriteFrame = step % frameCount }
}

在反应期间（语音气泡活跃）或被抚摸时，精灵进入“兴奋”模式并连续循环所有帧。 静止时，它跟随较慢、较重的 IDLE_SEQUENCE.

窄终端回退

export const MIN_COLS_FOR_FULL_SPRITE = 100

if (columns < MIN_COLS_FOR_FULL_SPRITE) {
  // Collapse to one-line face. When speaking, quip replaces the name.
  const quip = reaction && reaction.length > NARROW_QUIP_CAP
    ? reaction.slice(0, NARROW_QUIP_CAP - 1) + '…' : reaction
  const label = quip ? `"${quip}"` : focused ? ` ${companion.name} ` : companion.name
  return <Box paddingX={1} alignSelf="flex-end">
    <Text>{renderFace(companion)} {label}</Text>
  </Box>
}

在 100 个终端列以下，完整的 5 行精灵被单行脸部字符串替换（例如 (·>) 对于企鹅）。 语音气泡俏皮话被截断为 24 个字符，并内联显示在脸部旁边。 这 companionReservedColumns() 出口告诉 PromptInput 要减去多少水平空间，以便输入框不会与同伴重叠。

全屏模式与回滚模式

对话气泡有两个渲染路径，具体取决于全屏是否处于活动状态：

07 Prompt.ts — 将 Companion 注入 Claude 的上下文中

BUDDY 并不只是 UI 彩蛋，它还会通过系统提示附件进入 Claude 的上下文。这里最关键的设计点是：Claude 被明确告知“自己不是这个伴侣”。

这条边界让整套体验成立了。用户在叫 BUDDY 名字时，Claude 要让开，而不是代替它表演；否则 UI 里的气泡角色和模型本体会抢身份。

export function companionIntroText(name: string, species: string): string {
  return `# Companion

A small ${species} named ${name} sits beside the user's input box and
occasionally comments in a speech bubble. You're not ${name} — it's a
separate watcher.

When the user addresses ${name} directly (by name), its bubble will answer.
Your job in that moment is to stay out of the way: respond in ONE line or
less, or just answer any part of the message meant for you. Don't explain
that you're not ${name} — they know. Don't narrate what ${name} might say
— the bubble handles that.`
}

每个对话都会注入一次附件，并通过检查现有消息中的先前信息来进行重复数据删除。 companion_intro 同名附件：

export function getCompanionIntroAttachment(messages): Attachment[] {
  if (!feature('BUDDY')) return []
  const companion = getCompanion()
  if (!companion || getGlobalConfig().companionMuted) return []

  // Skip if already announced for this companion.
  for (const msg of messages ?? []) {
    if (msg.attachment?.type === 'companion_intro' &&
        msg.attachment.name === companion.name) return []
  }

  return [{ type: 'companion_intro', name: companion.name, species: companion.species }]
}

08 useBuddyNotification.tsx — 启动窗口

启动窗口逻辑把产品运营意图直接写进了代码：预告只在固定窗口内出现，真正的命令则在之后长期可用，且时间判断使用本地时区而不是 UTC。

这说明 BUDDY 并不是简单被某个 feature flag 打开，而是被当成一次有节奏的发布事件来设计：控制曝光波次、控制讨论节奏，也控制生成负载。

// Local date, not UTC — 24h rolling wave across timezones. Sustained Twitter
// buzz instead of a single UTC-midnight spike, gentler on soul-gen load.
// Teaser window: April 1-7, 2026 only. Command stays live forever after.
export function isBuddyTeaserWindow(): boolean {
  if ("external" === 'ant') return true   // internal builds: always show
  const d = new Date()
  return d.getFullYear() === 2026 &&
         d.getMonth() === 3 &&   // month 3 = April (0-indexed)
         d.getDate() <= 7
}

export function isBuddyLive(): boolean {
  if ("external" === 'ant') return true
  const d = new Date()
  return d.getFullYear() > 2026 ||
        (d.getFullYear() === 2026 && d.getMonth() >= 3)
}

在预告窗口期间，如果尚未孵化出同伴，则会出现 rainbow-colored /buddy 在启动通知栏中显示 15 秒。 彩虹是通过将每个字符映射到 getRainbowColor(index):

function RainbowText({ text }) {
  return <>{[...text].map((ch, i) =>
    <Text key={i} color={getRainbowColor(i)}>{ch}</Text>
  )}</>
}

addNotification({
  key: 'buddy-teaser',
  jsx: <RainbowText text="/buddy" />,
  priority: 'immediate',
  timeoutMs: 15_000,
})

钩子还导出 findBuddyTriggerPositions()，一个使用正则表达式来定位所有 /buddy 字符串中的出现次数 — 使用者 PromptInput 在您键入命令时突出显示该命令。

09 伴侣是什么样子

为了使系统具体化，下面是一张史诗级稀有蝾螈的配套卡示例：

}~(______)~{
}~(✦ .. ✦)~{
  ( .--. )
  (_/  \_)
   axiBot

史诗伴侣的统计分布示例（下限=35，峰值=调试，转储=耐心）：

10 完整数据流：第一次孵化到语音气泡

如果把 BUDDY 当成一条完整链路来看，它不是“先画图，再起名字”这么简单，而是：触发命令、生成骨骼、生成灵魂、注入系统提示、持续渲染精灵、再按状态吐出气泡。

这也解释了为什么这套功能虽然看起来像玩具，却跨了那么多文件：它同时涉及状态、配置、UI、提示工程和上线机制。

11 深潜