在 Claude Code 这类以 Agent Runtime 为核心的产品中，真正决定能力上限的，通常是模型调用链、工具编排、上下文注入、压缩与恢复等核心机制。相比之下，Buddy 显然不是主功能。

它体量不大，也不承担关键执行职责，更像是附着在终端界面旁的一层轻量交互设计。

但恰恰因为如此，Buddy 才值得被拿出来单独分析。

一个成熟的软件产品，价值不只体现在主干能力是否强大，也体现在这些“非核心但高完成度”的细节里：它们往往最能体现团队对产品边界、交互节奏与工程质量的把握。Buddy 就属于这类设计。

本文不把 Buddy 当作 Claude Code 的核心卖点，而把它当作一个小而完整的产品切片：看它如何以较低的实现成本，做出角色感、陪伴感与记忆点，同时又不干扰主工作流。

一、Buddy 的本质：不是第二个 Agent，而是一层陪伴式角色系统

从源码设计看，Buddy 并不是另一个完整的 Agent，也不是主 Assistant 的第二人格。

它更接近一层轻量的陪伴式角色系统，主要由三部分组成：

1. 稳定生成的角色身份；
2. 轻量的终端渲染与动画表现；
3. 对主 Assistant 的明确边界约束。

这一定义很重要。

因为如果把 Buddy 设计成“第二个会说话的 Assistant”，它就必须参与更多上下文管理、拥有更强的人格表达、甚至与主回复竞争注意力。而 Claude Code 并没有这样做。

它采取的是一种更克制的路线：Buddy 在场，但不抢戏；能互动，但不主导；有角色感，但不污染主 Agent 的人格边界。

对于专业工具产品而言，这种克制本身就是一种能力。

图 1：Buddy 在 Claude Code 界面中的实际位置。作为非核心功能，它的存在感被控制在恰到好处的范围内。

二、数据模型：将“骨架”与“灵魂”分开

Buddy 里一个非常值得借鉴的设计，是它将角色信息拆成了两层：

// Deterministic parts — derived from hash(userId)export type CompanionBones = {
  rarity: Rarity
  species: Species
  eye: Eye
  hat: Hat
  shiny: boolean
  stats: Record<StatName, number>}// Model-generated soul — stored in config after first hatchexport type CompanionSoul = {
  name: string
  personality: string}export type Companion = CompanionBones &
  CompanionSoul & {
    hatchedAt: number}// What actually persists in config. Bones are regenerated from hash(userId)// on every read so species renames don't break stored companions and users// can't edit their way to a legendary.export type StoredCompanion = CompanionSoul & { hatchedAt: number }

其中：

• Bones 负责外观和属性；
• Soul 负责名字与性格；
• 实际持久化时，只保存 soul 与时间戳。

这带来三个直接收益：

1. 角色身份稳定

同一用户得到的是同一只 Buddy，而不是每次启动随机变化的临时角色。

1. 配置层更安全

真正读取 companion 时，系统会重新生成骨架，再与 soul 合并：

export function getCompanion(): Companion | undefined {const stored = getGlobalConfig().companion
  if (!stored) return undefinedconst { bones } = roll(companionUserId())return { ...stored, ...bones }}

这意味着用户无法通过修改配置直接“伪造”稀有度或物种。

1. 后续演化更轻松

当物种列表、属性规则或配置格式发生变化时，系统只要保留 soul，就仍然能重建角色骨架。这是一种对长期维护更友好的结构。

从工程上看，这是一个很典型的“小功能也按长期能力来设计”的例子。

图 2：Buddy 的数据模型将可重建的骨架（Bones）与可持久化的灵魂（Soul）拆开，使角色身份稳定、配置更安全，也降低了后续演化成本。

三、生成机制：确定性、轻量、可走热路径

Buddy 的角色生成逻辑不复杂，但很讲究。

它采用的是“确定性种子 + 轻量 PRNG”的组合：

function mulberry32(seed: number): () => number {let a = seed >>> 0return function () {
    a |= 0
    a = (a + 0x6d2b79f5) | 0let t = Math.imul(a ^ (a >>> 15), 1 | a)
    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t
    return ((t ^ (t >>> 14)) >>> 0) / 4294967296}}

再通过这个随机流，从预设集合中抽取 species、eye、hat、stats 和 rarity：

function rollFrom(rng: () => number): Roll {const rarity = rollRarity(rng)const bones: CompanionBones = {
    rarity,
    species: pick(rng, SPECIES),
    eye: pick(rng, EYES),
    hat: rarity === 'common' ? 'none' : pick(rng, HATS),
    shiny: rng() < 0.01,
    stats: rollStats(rng, rarity),}return { bones, inspirationSeed: Math.floor(rng() * 1e9) }}

更值得注意的是，它还对结果做了缓存：

const SALT = 'friend-2026-401'// 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 } | undefinedexport function roll(userId: string): Roll {const key = userId + SALTif (rollCache?.key === key) return rollCache.value
  const value = rollFrom(mulberry32(hashString(key)))
  rollCache = { key, value }return value
}

这段注释说明得很明确：Buddy 的生成结果会被三个热路径反复使用——sprite tick、逐键输入、observer 反应。

这意味着，Buddy 虽然不是核心功能，但它的实现仍然遵循核心功能级别的性能要求。

四、角色边界：Buddy 在场，但不是主 Assistant

Buddy 最成熟的一点，并不在动画，而在边界控制。

Claude Code 并没有把 Buddy 的人格粗暴混进主 Assistant，而是通过 attachment 方式给模型补充一个很明确的角色说明：

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.`}

这里最关键的一句其实是：

You're not ${name} — it's a separate watcher.

这意味着系统一开始就明确划定了边界：

• Buddy 是 Buddy；
• 主 Assistant 是主 Assistant；
• 用户点名 Buddy 时，主 Assistant 要主动退后。

对应的 attachment 注入逻辑也很克制：

export function getCompanionIntroAttachment(
  messages: Message[] | undefined,): Attachment[] {if (!feature('BUDDY')) return []const companion = getCompanion()if (!companion || getGlobalConfig().companionMuted) return []for (const msg of messages ?? []) {if (msg.type !== 'attachment') continueif (msg.attachment.type !== 'companion_intro') continueif (msg.attachment.name === companion.name) return []}return [{
      type: 'companion_intro',
      name: companion.name,
      species: companion.species,},]}

它具备三个非常专业的特征：

• 可以通过 feature gate 完整关闭；
• 可以通过 mute 状态静音；
• 可以避免重复注入。

换句话说，Buddy 的存在方式是“可控的角色上下文”，而不是“持续性噪声”。

图 3：Buddy 与主 Assistant 之间存在明确的角色边界。它可以在场、可以互动，但不会接管主回复，也不会与主工作流争夺注意力。

五、生命感从哪里来：不是复杂动画，而是节奏设计

Buddy 看起来“像活着”，并不是因为它有多复杂的图形系统，而是因为它的节奏处理很到位。

CompanionSprite 里有几组非常关键的时间参数：

const TICK_MS = 500;const BUBBLE_SHOW = 20; // ticks → ~10s at 500msconst FADE_WINDOW = 6; // last ~3s the bubble dims so you know it's about to goconst PET_BURST_MS = 2500; // how long hearts float after /buddy petconst IDLE_SEQUENCE = [0, 0, 0, 0, 1, 0, 0, 0, -1, 0, 0, 2, 0, 0, 0];

这组参数对应的设计很克制：

• 大部分时间静止；
• 偶尔动一下；
• 偶尔眨眼；
• 说话时短暂出现气泡，再缓慢淡出；
• 被 pet 后有一小段正反馈动画。

对应逻辑同样简单：

if (reaction || petting) {
  spriteFrame = tick % frameCount;} else {const step = IDLE_SEQUENCE[tick % IDLE_SEQUENCE.length]!;if (step === -1) {
    spriteFrame = 0;
    blink = true;} else {
    spriteFrame = step % frameCount;}}const body = renderSprite(companion, spriteFrame).map(line =>
  blink ? line.replaceAll(companion.eye, '-') : line
)

这种实现方式并不追求动画的丰富度，而是追求“存在感的合理性”。

对终端产品来说，这一点非常重要：Buddy 不能比主功能更喧闹，但它需要足够稳定地存在，才能建立情感连接。

六、布局处理：它不是浮层，而是正式参与输入区计算

Buddy 的另一个成熟之处，是它并不是一个简单覆盖在界面角落的视觉元素，而是正式参与了输入区的宽度计算。

export function companionReservedColumns(terminalColumns: number, speaking: boolean): number {if (!feature('BUDDY')) return 0;const companion = getCompanion();if (!companion || getGlobalConfig().companionMuted) return 0;if (terminalColumns < MIN_COLS_FOR_FULL_SPRITE) return 0;const nameWidth = stringWidth(companion.name);const bubble = speaking && !isFullscreenActive() ? BUBBLE_WIDTH : 0;return spriteColWidth(nameWidth) + SPRITE_PADDING_X + bubble;}

PromptInput 则直接根据这段宽度来缩减输入列数：

useBuddyNotification();const companionSpeaking = feature('BUDDY') ?useAppState(s => s.companionReaction !== undefined) : false;const { columns, rows } = useTerminalSize();const textInputColumns = columns - 3 - companionReservedColumns(columns, companionSpeaking);

这意味着 Buddy 的设计原则不是“先画出来再说”，而是“确保它的存在不会破坏主交互区”。

同时，窄屏场景也做了专门降级：

if (columns < MIN_COLS_FOR_FULL_SPRITE) {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>{petting && <Text color="autoAccept">{figures.heart} </Text>}<Text bold color={color}>{renderFace(companion)}</Text>{' '}<Text italic dimColor={!focused && !reaction} bold={focused} inverse={focused && !reaction} color={reaction ? fading ? 'inactive' : color : focused ? color : undefined}>{label}</Text></Text></Box>;}

因此，Buddy 即使存在，也始终服从主工作流。这是它能够长期成立的前提。

七、它在什么时候与用户互动

从现有源码看，Buddy 的互动主要发生在四种场景下。

1. 启动期 teaser

当用户尚未拥有 companion 时，系统会在特定时间窗内通过通知提示 /buddy：

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

这是一种轻量级的发现机制，而不是强打断式引导。

1. 输入阶段识别 /buddy

Buddy 在输入体验中具备触发词识别能力：

export function findBuddyTriggerPositions(text: string): Array<{ start: number; end: number }> {if (!feature('BUDDY')) return [];const triggers: Array<{ start: number; end: number }> = [];const re = /\/buddy\b/g;let m: RegExpExecArray | null;while ((m = re.exec(text)) !== null) {
    triggers.push({