前言

在 Claude Code 的源码中，有一个名为 buddy 的模块——它实现了一套完整的“虚拟伴侣”程序。按理说，这只坐在你输入框旁边的小精灵，不是一个简单的装饰品。而是一套设计相当精密的游戏化 UX 程序。

一、类型程序设计：types.ts

1. 物种定义的工程化技巧：对抗“扫描器”的防御性操作

types.ts 是整个程序的基础。可以关注的第一个细节是物种的定义方式：

const c = String.fromCharCode;//
export const duck = c as 'duck';export const dragon = c as 'dragon';

这里用 String.fromCharCode 通过字符码点拼接字符串，而不是直接写字面量 'duck'。注释解释了原因：

开发者是否担心代码被 CI/CD 安全扫描误拦截？CI/CD 流水线中有一个脚本会扫描 bundle 产物中是否包含某些敏感字符串，某个物种名恰好与模型代号冲突。通过运行时构造字符串，就能让 bundle 产物中不出现该字面量，同时不影响功能。这种做法在大型团队的安全审计流程中并不罕见。

2. 稀有度权重程序：Gacha 游戏的概率艺术

export const RARITY_WEIGHTS = {
common的观点是，60,uncommon: 25。rare: 10,epic: 4,legendary: 1,} as const satisfies Record

定义5 个稀有度等级，概率总和为 100，传奇仅 1% 概率。这与经典的 Gacha 游戏设计如出一辙。as const satisfies Record 的写法既保留了字面量类型推断。又用 satisfies 做了结构完整性校验，是 TypeScript 高阶的惯用手法。

3. Companion 数据模型的分层设计：彻底杜绝“存档作弊”

整个 Companion 被拆分成三层：

层级	类型	内容	持久化策略
Bones	CompanionBones	稀有度、物种、眼型、帽子、闪光、属性	不持久化每次从 userId 重新生成
Soul	CompanionSoul	名字、性格	存储在 config
完整体	Companion	Bones + Soul + hatchedAt	运行时合并

如何防止使用者。使用者编辑 config.companion 只能改变名字和性格。稀有度是由账号 ID 决定的，无法伪造。老实说，

二、随机生成引擎：companion.ts

这是整个程序的主要。包含了一个完整的“确定性随机角色生成”流水线。

1. Mulberry32 伪随机数生成器：轻量且可靠

function mulberry32: => number {
let a = seed>> 0;return function {
a = | 0;let t = Math.imul,1) | 0;t = t + Math.imul,61) | 0;return )>> 14)>> 0) / 4294967296;说起来，}
}

Mulberry32 是一个轻量级的 32 位整数伪随机数生成器。其实，其特点是这方面，体积极小、质量足够、有状态闭包。对于宠物场景，它完全够用。

2. 字符串哈希函数：FNV-1a 实现

function hashString: number {
if {
return Number) & 0xffffffff);其实，}
let h = 2166136261;for {
h ^= s.charCodeAt;h = Math.imul;不过，}
return h>> 0;}

这是 FNV-1a 哈希算法的 32 位实现。在 JavaScript 环境中通过 Math.imul 避免了浮点数精度问题。

3. 稀有度抽取算法：加权随机样

function rollRarity => number): Rarity {
const total = Object.values.reduce => a + b,0);let roll = rng * total;for {
roll -= RARITY_WEIGHTS;其实，if return rarity;}
return 'common';}

经典的加权随机样，时间复杂度 O。由于 RARITIES 数组顺序固定且权重递减，大多数情况下在前两次迭代就能返回结果。

4. 属性点分配：峰谷程序让宠物更有个性

const RARITY_FLOOR: Record = {
common的观点是。0,uncommon: 10,rare: 25,epic: 40,legendary: 50,}
function rollStats {
const floor = RARITY_FLOOR;const peak = pick;// 峰值属性
let dump = pick;// 垃圾属性
while dump = pick;for {
if stats = Math.min * 30);else if stats = Math.max * 15);
else stats = floor + rng * 40;}
}

想要让每个宠物的属性平平无奇吗？这里采用了 RPG 中常见的“峰谷分配”机制：随机选一个峰值属性使其出众。随机选一个垃圾属性作为短板，其余属性均衡分布。稀有度越高，floor 越大，代表着传奇伴侣所有属性都至少从50 起。

5. Salt 与缓存机制：性能与功能的平衡

const SALT = 'friend--';export function roll: Roll {
const key = userId + SALT;if return rollCache.value;const value = rollFrom));rollCache = { key,value };return value;}

SALT 的值暗示这是愚人节上线的功能。Salt 的作用是：如果将来需要对所有使用者“重新洗牌”，只需更换 Salt 即可。缓存是一个单元素 LRU 策略：对同一个 userId 直接返回缓存，避免重复昂贵的哈希计算。

三、精灵渲染引擎：sprites.ts

1. ASCII Art 精灵程序：字符的生命力

每个物种有若干帧动画，每帧是多行的字符 ASCII 画。使用 {E} 作为眼睛的占位符，渲染时替换为实际眼型：

说到duck。dragon: ]

renderSprite 函数逻辑精妙：第一行作为帽子槽，普通帧保持空白，特殊帧用它显示“烟雾”特效。只有当第一行为为空，帽子会被渲染进去。

四、提示词注入：prompt.ts

function companionIntroText: string {
return `# Companion
A small ${species} named ${name} sits beside user's input box...
When user addresses ${name} directly,its bubble will answer.
Your job in that moment is to stay out of way: respond in ONE line or less...`;

如何让AI感知宠物？Companion 的气泡回复是注入到主 LLM 上文中的程序提示词。去重逻辑保证了这段提示词只注入一次避免重复污染 Token 消耗。

五、React 组件层：CompanionSprite.tsx

1. 动画时钟设计：让像素“动”起来

const TICK_MS = 500;const IDLE_SEQUENCE =;

每 500ms 触发一次 tick。大部分时间是静止，偶尔轻微动作、眨眼或特殊动作。完全模拟了真实动物的“懒散”状态。

2. 气泡淡出程序：细腻的交互反馈

const BUBBLE_SHOW = 30000;// 30秒
const FADE_WINDOW = 5000;// 最终5秒开始变暗

气泡显示30秒。最终5秒进入淡出状态，颜色变为 inactive，提示使用者气泡即将消失。这是很细腻的 UX 设计。

3. 爱心粒子程序：情感反馈的主要

const PET_BURST_MS = 1000;const PET_HEARTS =;不过，

执行 /buddy 命令时爱心动画依次播放。爱心从密集到稀疏，最终消散。

六、通知与生命周期：useBuddyNotification.tsx

function isBuddyTeaser: boolean {
const d = new Date;return d.getFullYear === 2024 && d.getMonth === 2 && d.getDate <= 1;
}

判断当前是否在预告窗口。在预告期，未孵化的使用者启动会看到彩虹色的 /buddy 提示。注释说明本地时间而非 UTC，是为了在不同时区形成一个“24小时滚动波浪”。避免在 UTC 午夜造成单点流量峰冲击后端。

七、整体架构

types.ts ← 数据模型定义
companion.ts ← 确定性随机生成引擎
↓
sprites.ts ← ASCII 精灵渲染
↓
CompanionSprite.tsx ← React 组件
↓
prompt.ts ← LLM 上下文注入
useBuddyNotification.tsx ← 启动通知 & 命令触发检测

整个程序体现了几个可以参考的设计原则：

1. 骨肉分离可变的“灵魂”与不可篡改的“骨骼”分开存储。防止使用者作弊，同时保证向后兼容。不过，
2. 确定性生成用 hash 作为种子。保证同一使用者永远得到同一只宠物，既有“专属感”，又避免了服务端存储 bones 的开销。
3. 防御性工程Salt、字符码点构造字符串、bones 后置覆盖——每处细节都有明确的防御目的。
4. 渐进式 UX预告窗口 → 孵化 → 闲置动画 → 气泡回复 → 爱心互动。构成了完整的使用者旅程，而非一个静态彩蛋。

这只坐在终端里的小鸭子，背后藏的是一套从哈希函数到 React Compiler 的完整工程程序。下次你的 Claude Code 里出现一只小精灵。不妨想想——它的稀有度，从你第一次注册账号那天起，就已经注定了。

---