CodePilot Buddy 游戏化系统深度解析:确定性伙伴生成、双模式心跳与定时任务调度的完整技术实现
CodePilot Buddy 游戏化系统深度解析:确定性伙伴生成、双模式心跳与定时任务调度的完整技术实现
本篇技术指南系统拆解 CodePilot(Electron + Next.js 多模型 AI 桌面客户端)内置的 Buddy 游戏化系统:从确定性 PRNG 伙伴生成与五级稀有度进化,到双模式心跳机制与不可见标记协议,再到 SQLite 持久化定时任务调度器、通知队列与按会话隔离的记忆提取。读者读完将掌握一套完整的、可直接复用的"AI 伙伴"工程实现方案,包括数据流设计、多文件状态同步的防分叉策略,以及 cron 边界解析的务实取舍。
一、系统定位与总体架构
Buddy 是 CodePilot 中一套将 AI 助理从"工具"转变为"伙伴"的游戏化子系统。它不是一个单纯的宠物皮肤,而是贯穿记忆、心跳、定时任务、通知、进化的产品架构核心。技术实现完整记录于 docs/handover/buddy-gamification.md,产品设计思考可参考 docs/insights/buddy-gamification.md。
从源码结构看,Buddy 系统横跨 6 个子系统,核心数据流为:
Wizard/孵化 API → state.json(buddy) → context-assembler(性格 prompt)
→ DashboardPanel(看板卡)
→ ChatListPanel(侧栏)
→ MessageItem(聊天头像)
→ ChatEmptyState(空状态)
1.1 数据存储全景
Buddy 的状态分散存储在多个位置,各有明确职责:
| 数据 | 位置 | 格式 |
|---|---|---|
| Buddy 属性 | {workspace}/.codepilot/state.json → buddy 字段 |
BuddyData (species/rarity/stats/buddyName/emoji) |
| 性格提示 | {workspace}/soul.md → ## Buddy Trait 节 |
Markdown |
| 心跳状态 | state.json → lastHeartbeatDate / heartbeatEnabled |
ISO date string / boolean |
| 定时任务 | SQLite scheduled_tasks 表(durable)/ globalThis Map(session-only) |
ScheduledTask type |
| 通知队列 | globalThis ring buffer(50 条上限) | QueuedNotification[] |
| 记忆提取计数 | globalThis Map<sessionId, number> |
per-session counter |
其中 BuddyData 的核心结构定义在 src/lib/buddy.ts:
export interface BuddyData {
species: Species; // 16 种物种之一
rarity: Rarity; // common → legendary 五级
stats: Record<StatName, number>; // creativity/patience/insight/humor/precision
emoji: string; // 物种 emoji
peakStat: StatName; // 峰值属性,决定性格 hint
hatchedAt: string; // 孵化时间,进化天数计算的起点
buddyName?: string; // 用户自定义名字
}
二、Buddy 生成与进化:确定性 PRNG 与五级稀有度
2.1 核心文件与生成算法
Buddy 生成的唯一入口是 src/lib/buddy.ts,核心是 deterministic PRNG:以 workspace path + timestamp 拼接为种子,先经 FNV-1a 风格哈希(hashString),再用 Mulberry32 算法驱动随机序列。generateBuddy(seed) 的完整流程为:
hashString(seed + ':buddy-2026')产生 32 位哈希mulberry32(hash)创建 PRNG 实例rollRarity(rng)按权重表抽取稀有度pickRandom(rng, SPECIES)从 16 种物种中抽取rollStats(rng, rarity)生成 5 项属性并确定 peakStat
这一设计的工程意义在于:同一个工作区、同一个时间戳生成的 Buddy 永远一致,避免了"刷新页面 Buddy 就变了"的 bug,也让调试与测试完全可预测(同一种子必得同一结果)。
2.2 稀有度权重与属性区间
源码中的 RARITY_WEIGHTS 和 RARITY_FLOORS 定义了稀有度的概率与属性下限:
const RARITY_WEIGHTS = { common: 60, uncommon: 25, rare: 10, epic: 4, legendary: 1 };
const RARITY_FLOORS = { common: 5, uncommon: 15, rare: 25, epic: 35, legendary: 50 };
对应概率为 60% / 25% / 10% / 4% / 1%。属性生成逻辑(rollStats)也随稀有度变化:
- 峰值属性(peak stat):
floor + 50 + rand(0~30),上限 100 - 短板属性(dump stat):
floor - 10 + rand(0~15),下限 1 - 其余属性:
floor + rand(0~40)均匀散布
2.3 稀有度的功能性差异
稀有度不是纯装饰——src/lib/buddy.ts 中的 getRarityAbilities() 将稀有度映射为实际能力:
| 能力 | Common | Uncommon | Rare | Epic | Legendary |
|---|---|---|---|---|---|
| 称号(title) | ❌ | ✅ | ✅ | ✅ | ✅ |
| 性格增强(双属性 trait) | ❌ | ❌ | ✅ | ✅ | ✅ |
| 记忆提取加速(每 2 轮替代每 3 轮) | ❌ | ❌ | ❌ | ✅ | ✅ |
| 传说特效(shimmer 光效) | ❌ | ❌ | ❌ | ❌ | ✅ |
这印证了产品文档 docs/insights/buddy-gamification.md 中"Epic 玩家的 Buddy 确实比 Common 更聪明"的设计:记忆提取频率翻倍让稀有度成为真实的差异化体验。
2.4 进化系统
checkEvolution(buddy, memoryCount, daysActive, conversationCount) 返回 { canEvolve, nextRarity, requirements, current }。源码 src/lib/buddy.ts 中的 EVOLUTION_REQUIREMENTS 定义了三级进化门槛:
| 进化路径 | 记忆数 | 活跃天数 | 对话数 |
|---|---|---|---|
| Common → Uncommon | 10 | 7 | 20 |
| Uncommon → Rare | 30 | 21 | 50 |
| Rare → Epic | 60 | 45 | 100 |
| Epic → Legendary | 100 | 90 | 200 |
注意当前源码中 checkEvolution 的签名已收敛为 (buddy, memoryCount),对话数通过 conversationCount = memoryCount * 3 近似推导。evolveBuddy(buddy) 执行进化:稀有度 +1,全属性按稀有度 floor 差值提升(newFloor - oldFloor),上限 100。进化不是自动触发的——用户必须主动点"检查进化",这是一个刻意设计的主动仪式。
2.5 API 路由
POST /api/workspace/hatch-buddy— 生成或更名 buddy,追加## Buddy Trait到 soul.md。完整实现在 src/app/api/workspace/hatch-buddy/route.ts:- 种子为
workspacePath + ':' + new Date().toISOString() - 若 buddy 已存在且传入
buddyName,仅更新名字并返回{ buddy, alreadyHatched: true } - 将峰值属性对应的性格 hint 追加到 soul.md(兼容
soul.md/Soul.md/SOUL.md三种大小写变体) - 向最新会话注入一条带
show-widget卡片的消息,展示稀有度标签、属性条与传说 shimmer 光效
- 种子为
POST /api/workspace/evolve-buddy— 检查并执行进化,更新 soul.md trait 节
2.6 3D 图片资源的使用位置
Buddy 的视觉呈现依赖 public/buddy/ 目录下的 3D 风格 PNG 资源(src/lib/buddy.ts 中的 SPECIES_IMAGE_URL 映射)。物种图与蛋图 EGG_IMAGE_URL 在多个组件中按"有/无 Buddy"两种状态切换:
| 位置 | 有 Buddy | 无 Buddy | 文件 |
|---|---|---|---|
| Wizard Step 3 | 3D 物种图 + 渐变背景 | — | OnboardingWizard.tsx |
| 聊天空状态(助理) | 3D 物种图 + 渐变背景 | 3D 蛋图 | MessageList.tsx |
| 新建聊天入口 | — | 3D 蛋图 (24px/14px) | ChatEmptyState.tsx |
| 侧栏推广卡 | — | 3D 蛋图 (20px) | ChatEmptyState.tsx → AssistantPromoCard |
| 看板 Buddy 卡 | 3D 物种图 + 渐变背景 | 3D 蛋图 | DashboardPanel.tsx |
跨组件传递使用 globalThis.__codepilot_buddy_info__(由 ChatView 设置,MessageList 读取)。稀有度渐变背景由 RARITY_BG_GRADIENT 定义(common 灰 → legendary 金)。
三、心跳系统:双模式设计与不可见标记协议
心跳是 Buddy 系统中迭代次数最多、状态管理最复杂的子系统(产品文档记载经历了 5 轮审查才稳定)。
3.1 完整心跳触发链路
早期的完整心跳(autoTrigger 模式)链路为:
useAssistantTrigger: 空会话 + state.buddy 存在 + data.needsHeartbeat (server-computed)
→ autoTrigger: true, content: '心跳检查'
→ context-assembler: isHeartbeatTrigger = autoTrigger && userPrompt.includes('心跳检查')
→ buildHeartbeatInstructions() (完整 tick)
→ route.ts (collectStreamResponse): isHeartbeatTurn = autoTrigger && content.includes('心跳检查')
→ HEARTBEAT_OK 处理 / 更新 lastHeartbeatDate
3.2 软心跳链路(普通对话附带)
当用户主动发消息且心跳过期时,走软心跳路径:
context-assembler: !autoTrigger && shouldRunHeartbeat(state)
→ 注入 buildSoftHeartbeatHint()
→ AI 回复中包含 <!-- heartbeat-done --> 标记
route.ts (finally): fullText.includes('<!-- heartbeat-done -->') → 更新 lastHeartbeatDate
route.ts (保存前): contentBlocks 中所有 text block 清除 <!-- heartbeat-done --> → 持久化消息无标记痕迹
3.3 关键演进:从关键词检测到不可见标记
产品文档 docs/insights/buddy-gamification.md 完整记录了三次迭代:
- 无检测:心跳过期 turn 只要收到非空回复就标记完成——AI 根本没看 HEARTBEAT.md 也算完成
- 关键词检测:
heartbeat|心跳|记忆|memory|检查|提醒等词误判率极高(用户讨论 memory leak 也会命中);收窄到HEARTBEAT.md|日常检查又太严(AI 用自然语言表达时检测不到) - 不可见标记(最终方案):在 soft hint 中指示 AI 完成检查后输出
<!-- heartbeat-done -->,后端检测标记更新lastHeartbeatDate,持久化前从所有 contentBlock text 中清除——包括 JSON 序列化路径(tool_use 场景)
这个方案的精妙之处在于:AI 的行为与系统的状态机通过一个约定的信号量解耦。AI 有自由度决定检查方式(自然语言、MCP 工具、简短一提),系统只看"做了没有"的信号。心跳协议本身的定义在 src/lib/heartbeat.ts:HEARTBEAT_TOKEN = 'HEARTBEAT_OK',classifyHeartbeatOutcome() 区分静默/发言两种结果。
3.4 needsHeartbeat 单一数据源
GET /api/settings/workspace 返回:
needsHeartbeat: !!state.buddy && shouldRunHeartbeat(state)
前端 useAssistantTrigger 直接消费该字段,不重新实现判定逻辑。这是针对"前后端判定逻辑分叉"问题的核心决策——早期前端手写版存在两个缺陷:缺少 UTC 兼容日期处理、缺少 activeHours(只在工作时间触发,支持跨午夜区间如 22:00-08:00,见 src/lib/heartbeat.ts 的 isWithinActiveHours)。
3.5 Buddy-welcome 与 Heartbeat 互斥
两者共用 autoTrigger flag,冲突会导致"新用户看到心跳检查而非领养引导"或"心跳指令注入领养 turn"。src/hooks/useAssistantTrigger.ts 中的互斥逻辑:
const needsBuddyWelcome = state.onboardingComplete && !state.buddy && initialMessages.length === 0;
const needsHeartbeat = !!data.needsHeartbeat && !!state.buddy && initialMessages.length === 0;
!state.buddy 与 !!state.buddy 天然互斥,逻辑上不可能同时为 true。
需要特别指出的是:当前源码中前台自动触发的心跳已停用。查看 src/hooks/useAssistantTrigger.ts 的注释可以确认——心跳由后台调度器独占(scheduled_tasks 表中的 source='assistant_heartbeat' 任务,由 executeDueTask 触发),页面挂载只读取状态;前台仅保留一次性 buddy-welcome 领养流程(triggerMsg = '请做自我介绍并引导用户领养伙伴。')。这是为了避免完整 streamClaude turn 携带全部工具导致工具循环失控的历史教训。
四、定时任务调度器:Durable 与 Session-only 双轨制
4.1 核心文件与启动时机
核心实现位于 src/lib/task-scheduler.ts。调度器有三种启动时机,覆盖冷启动与热路径:
src/instrumentation.ts— Next.js 服务启动时(覆盖冷启动)POST /api/chat— 首次聊天时(冗余保障)POST /api/tasks/schedule— 创建任务时
轮询机制为 10 秒 setInterval,用 globalThis 防止 HMR(热更新)重复启动;另有每小时一次的过期任务检查(checkExpiredTasks)。
4.2 Durable vs Session-only 任务
| 维度 | Durable | Session-only |
|---|---|---|
| 存储 | SQLite scheduled_tasks |
globalThis Map<string, ScheduledTask> |
| 跨重启 | ✅ | ❌ |
| 列出 | /api/tasks/list + MCP 合并 |
MCP codepilot_list_tasks 合并显示 |
| 取消 | /api/tasks/{id} DELETE |
MCP codepilot_cancel_task 先查 Map |
| 失败退避 | SQLite updateScheduledTask + applyBackoff |
内存中累加 consecutive_errors + BACKOFF_DELAYS |
| 自动禁用 | 10 次连续失败 | 10 次连续失败 → status = 'disabled' |
executeDueTask(task, isSessionTask) 是双轨制的心脏:
isSessionTask = true:跳过所有 SQLite 写入,错误时 re-throw 让 poll loop 处理isSessionTask = false:走完整 SQLite 记录 +computeNextRun+applyBackoff
退避阶梯定义在源码顶部:BACKOFF_DELAYS = [30000, 60000, 300000, 900000](30 秒 / 1 分钟 / 5 分钟 / 15 分钟),连续失败超过 MAX_CONSECUTIVE_ERRORS(10 次)后自动禁用任务。
4.3 Cron 表达式解析:1461 天统一扫描 + null 语义
getNextCronTime(expression): Date | null 是任务调度最精密的函数,完整实现在 src/lib/task-scheduler.ts:
- 统一 4 年(1461 天)日级扫描,每天先做 dom/month/dow 快速预检,跳过不匹配的日,再扫描该日 1440 分钟
- 支持
*、逗号1,15、范围1-5、步进*/5(matchField实现) - 4 年内无匹配返回
null,由调用方暂停任务(status: 'paused')或拒绝创建(400 错误) schedule/route.ts和notification-mcp.ts都 import 此函数,不再有重复实现
这个设计经历了 4 个版本的演进(产品文档 docs/insights/buddy-gamification.md 有完整记录):48 小时扫描漏周级 → 35 天漏闰年 2 月 29 日 → 366 天双路径仍漏 0 * 29 2 * → 最终统一 1461 天单路径。核心教训是:调度器执行逻辑是 next_run <= now 就触发,任何 fallback 日期(1h / 30 天 / 4 年)最终都会到期并错误执行;null 是唯一不会导致错误执行的返回值——当一个函数不知道答案时,应该明确说"我不知道"(返回 null / 抛异常),而不是编造一个看似合理的答案。
五、通知系统:服务端队列 + 前端轮询 + MCP 工具
5.1 核心文件
| 文件 | 职责 |
|---|---|
| src/lib/notification-manager.ts | 服务端通知队列 + sendNotification() |
src/app/api/tasks/notify/route.ts |
POST 接收通知 / GET 轮询队列 |
src/hooks/useNotificationPoll.ts |
前端 5 秒轮询 + Toast + 系统通知 |
| src/lib/notification-mcp.ts | MCP 工具(notify/schedule/list/cancel/hatch) |
5.2 通知流
服务端触发(task-scheduler / notification-mcp)
├─ sendNotification() → enqueueNotification() (globalThis ring buffer, max 50)
│ → Telegram (urgent only)
└─ 前端 useNotificationPoll (5s interval)
└─ GET /api/tasks/notify → drainNotifications()
├─ showToast() (all priorities)
└─ 系统通知 (normal/urgent):
├─ Electron: electronAPI.notification.show (IPC, 支持点击回到窗口)
└─ Browser: new Notification() (dev fallback)
5.3 端口问题修复(多端口环境兼容)
notification-mcp.ts 中所有 HTTP 调用已重构:
- 通知:直接
import('@/lib/notification-manager').sendNotification(),不走 HTTP(消除端口依赖) - 任务调度:
getBaseUrl()读process.env.PORT,支持 worktree 和 Electron 非默认端口 - 任务列表/取消:同上 + 合并 session-only 任务
task-scheduler.ts 的 sendTaskNotification 同样改为直接 import。
六、记忆提取:按会话隔离与写入检测
6.1 计数器隔离
核心实现位于 src/lib/memory-extractor.ts。提取计数器使用 Map<sessionId, number>(globalThis 存储),每个会话独立计数,避免会话间互相干扰:
- 普通 buddy:每 3 轮提取(
DEFAULT_EXTRACTION_INTERVAL = 3) - Epic/Legendary:每 2 轮提取(
shouldExtractMemory对 epic/legendary 返回 2)
export function shouldExtractMemory(buddyRarity?: string, sessionId?: string): boolean {
const key = sessionId || '__default__';
// 按 sessionId 独立计数,epic/legendary 返回 2,否则 3
}
6.2 写入检测
hasMemoryWritesInResponse(fullResponseJson) 传入 JSON.stringify(contentBlocks)(含 tool_use/tool_result 块),检查 memory 路径模式(memory.md、memory/daily/、soul.md、user.md)——如果 AI 本轮已通过工具写入 memory,跳过自动提取,避免双重写入。
6.3 Symlink 安全
codepilot_memory_get(src/lib/memory-search-mcp.ts)有两层防护:
- 词法检查:
path.relative()拒绝..前缀 - Symlink 检查:
fs.realpathSync()解析真实路径后再验证是否在 workspace 内
防止通过符号链接逃逸出工作区读取任意文件。
七、Buddy 重置流程
PATCH /api/settings/workspace with { resetBuddy: true } 执行三步:
state.buddy = undefined- 清除 soul.md 中
## Buddy Trait节(正则移除到下一个##或文件末尾) - 下次进入空会话 → 触发 buddy-welcome(重新领养引导)
这保证了"重新孵化"的完整闭环:状态、性格提示、领养流程全部归零。
八、空状态视觉一致性矩阵
Buddy 系统对"空状态"做了系统化的视觉统一,避免各入口各画各的:
| 场景 | 组件 | 有 Buddy | 无 Buddy |
|---|---|---|---|
| 聊天空(助理) | MessageList.tsx |
3D 物种图 + 渐变背景 + 名字 | 3D 蛋 + 领养提示 |
| 聊天空(项目) | MessageList.tsx |
— | CodePilot logo |
| 新建聊天页 | ChatEmptyState.tsx |
— | 3D 蛋图替代旧 Brain 图标 |
| 侧栏推广卡 | AssistantPromoCard |
— | 3D 蛋图 (20px) |
| 看板 Buddy 卡 | DashboardPanel.tsx |
3D 物种图 + 渐变背景 + 状态行 | 3D 蛋 + 孵化按钮 |
九、关键设计决策记录(工程经验沉淀)
本节整理文档与源码共同印证的设计决策,每一条都对应真实踩坑后的结论。
9.1 为什么心跳用 <!-- heartbeat-done --> 标记而非关键词检测
- 背景:最初尝试用关键词(heartbeat、记忆、检查等)检测 AI 是否做了心跳检查
- 问题:关键词太泛(讨论 memory leak 也会命中),太窄(AI 用自然语言不一定提到文件名)
- 决策:在 soft hint 中指示 AI 完成检查后输出不可见标记
<!-- heartbeat-done -->,持久化前从所有 contentBlock text 中清除(含 JSON 序列化路径)
9.2 为什么 cron 无匹配返回 null 而非远期日期
- 背景:先后尝试 1h fallback → 30 天 fallback → 4 年 fallback,都会导致提前触发
- 问题:调度器执行逻辑是
next_run <= now,任何 fallback 日期最终都会到期并错误执行 - 决策:返回
null,由调用方暂停任务或拒绝创建。这是唯一不会导致错误执行的方案
9.3 为什么 needsHeartbeat 放在服务端而非前端计算
- 背景:前端重新实现了
shouldRunHeartbeat的日期比较逻辑,与服务端分叉 - 问题:UTC 兼容日期、activeHours 等条件只在服务端
shouldRunHeartbeat()中实现,前端手写版缺少这些 - 决策:
GET /api/settings/workspace返回needsHeartbeat布尔值(含 buddy 存在性检查),前端直接用。单一数据源比"两边各算一次然后祈祷结果一致"可靠得多
9.4 为什么 buddy-welcome 和 heartbeat 通过 !!state.buddy 互斥
- 背景:两者共用
autoTriggerflag,同时为 true 时只发一条消息 - 问题:heartbeat 优先 → 新用户看到心跳检查而非领养引导;buddy-welcome 优先 → 心跳指令被注入到领养 turn 中
- 决策:buddy-welcome 要求
!state.buddy,heartbeat 要求!!state.buddy,逻辑上不可能冲突
十、文件清单与进一步阅读
本轮新增
| 文件 | 用途 |
|---|---|
src/hooks/useNotificationPoll.ts |
前端通知轮询 + Toast + 系统通知 |
本轮主要修改(核心实现入口)
| 文件 | 改动 |
|---|---|
| src/lib/context-assembler.ts | autoTrigger 参数、isHeartbeatTrigger 判定、buildSoftHeartbeatHint、3D 蛋图 |
| src/lib/task-scheduler.ts | session 任务推进/退避/禁用、getNextCronTime→null、getSessionTasks 导出、冷启动 |
| src/lib/notification-manager.ts | 服务端通知队列 + enqueue/drain |
| src/lib/notification-mcp.ts | getBaseUrl() + 直接 import + session 任务合并 |
| src/lib/memory-extractor.ts | 按 sessionId 隔离计数器 |
| src/lib/memory-search-mcp.ts | symlink 安全检查 |
src/app/api/chat/route.ts |
软心跳检测/清除、autoTrigger 传递、记忆写入检测、heartbeat-done 清理 |
src/app/api/tasks/notify/route.ts |
GET 轮询端点、POST 改用 sendNotification |
src/app/api/tasks/schedule/route.ts |
改用 task-scheduler 导出函数、cron null 处理 |
src/app/api/settings/workspace/route.ts |
needsHeartbeat 字段、resetBuddy 清理 soul.md |
| src/hooks/useAssistantTrigger.ts | heartbeat 触发恢复、server-computed needsHeartbeat、buddy 互斥 |
src/components/layout/AppShell.tsx |
useNotificationPoll 集成 |
src/components/chat/MessageList.tsx |
助理空状态 3D buddy/egg |
src/components/chat/ChatEmptyState.tsx |
3D 蛋图替代 Brain 图标 |
src/components/layout/panels/DashboardPanel.tsx |
紧凑状态行、进化反馈、设置按钮位置 |
src/types/electron.d.ts |
notification 接口类型 |
src/instrumentation.ts |
冷启动调度器 |
可复用的三大工程教训
-
涉及多文件状态同步的功能,应该在设计阶段画出完整的状态机图——列出所有状态变量、所有转换条件、所有判断点,确认每个判断点看到的状态一致。心跳的 4 个文件 6 个判断点(useAssistantTrigger、context-assembler、route.ts 触发检测、route.ts 完成检测、route.ts 消息保存、workspace API needsHeartbeat)中任何一个与其他不一致都会产生 bug。
-
函数不知道答案时应返回 null / 抛异常,而不是编造合理答案——cron 的 fallback 日期会在不可预测的未来时间点制造 bug。
-
引入新存储后端时,所有假设"只有一个存储后端"的代码路径都需要审查——session-only 任务修复前,SQLite 写入静默失败、错误计数永远为 0、退避永远不生效;修复后
executeDueTask(task, isSessionTask)按 flag 走不同路径,执行/查询/删除/错误处理每条路径都要适配。
Buddy 系统的完整产品叙事、稀有度心理学、与 Claude Code 宠物系统的设计对比,以及"拟人化界面层"的远景思考,见 docs/insights/buddy-gamification.md;技术细节与更新记录见 docs/handover/buddy-gamification.md。