CodePilot Buddy 游戏化系统深度解析:确定性伙伴生成、双模式心跳与定时任务调度的完整技术实现

原创2026-10-09 14:37:081,740 阅读
文章标签:人工智能AI 应用AI Agent大模型桌面应用MCP Clients本地部署交互助手代码智能体Agent 记忆媒体生成即时通讯

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) 的完整流程为:

  1. hashString(seed + ':buddy-2026') 产生 32 位哈希
  2. mulberry32(hash) 创建 PRNG 实例
  3. rollRarity(rng) 按权重表抽取稀有度
  4. pickRandom(rng, SPECIES) 从 16 种物种中抽取
  5. 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 完整记录了三次迭代:

  1. 无检测:心跳过期 turn 只要收到非空回复就标记完成——AI 根本没看 HEARTBEAT.md 也算完成
  2. 关键词检测:heartbeat|心跳|记忆|memory|检查|提醒 等词误判率极高(用户讨论 memory leak 也会命中);收窄到 HEARTBEAT.md|日常检查 又太严(AI 用自然语言表达时检测不到)
  3. 不可见标记(最终方案):在 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。调度器有三种启动时机,覆盖冷启动与热路径:

  1. src/instrumentation.ts — Next.js 服务启动时(覆盖冷启动)
  2. POST /api/chat — 首次聊天时(冗余保障)
  3. 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)有两层防护:

  1. 词法检查:path.relative() 拒绝 .. 前缀
  2. Symlink 检查:fs.realpathSync() 解析真实路径后再验证是否在 workspace 内

防止通过符号链接逃逸出工作区读取任意文件。

七、Buddy 重置流程

PATCH /api/settings/workspace with { resetBuddy: true } 执行三步:

  1. state.buddy = undefined
  2. 清除 soul.md 中 ## Buddy Trait 节(正则移除到下一个 ## 或文件末尾)
  3. 下次进入空会话 → 触发 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 互斥

  • 背景:两者共用 autoTrigger flag,同时为 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 冷启动调度器

可复用的三大工程教训

  1. 涉及多文件状态同步的功能,应该在设计阶段画出完整的状态机图——列出所有状态变量、所有转换条件、所有判断点,确认每个判断点看到的状态一致。心跳的 4 个文件 6 个判断点(useAssistantTrigger、context-assembler、route.ts 触发检测、route.ts 完成检测、route.ts 消息保存、workspace API needsHeartbeat)中任何一个与其他不一致都会产生 bug。

  2. 函数不知道答案时应返回 null / 抛异常,而不是编造合理答案——cron 的 fallback 日期会在不可预测的未来时间点制造 bug。

  3. 引入新存储后端时,所有假设"只有一个存储后端"的代码路径都需要审查——session-only 任务修复前,SQLite 写入静默失败、错误计数永远为 0、退避永远不生效;修复后 executeDueTask(task, isSessionTask) 按 flag 走不同路径,执行/查询/删除/错误处理每条路径都要适配。

Buddy 系统的完整产品叙事、稀有度心理学、与 Claude Code 宠物系统的设计对比,以及"拟人化界面层"的远景思考,见 docs/insights/buddy-gamification.md;技术细节与更新记录见 docs/handover/buddy-gamification.md。

登录后查看全文
CodePilot