CodePilot 主动助理架构:定时任务调度、心跳巡检与多渠道通知投递

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

CodePilot 主动助理架构:定时任务调度、心跳巡检与多渠道通知投递

本文围绕 CodePilot 的"主动助理(Proactive Assistant)"设计展开:当助理不再满足于被动回答,而是能够定时唤醒、自行判断"是否有事要说"、并通过系统通知、IM、浮窗等渠道主动触达用户时,调度、心跳与通知三者必须作为一个纵向闭环来设计。读完本文,你将掌握 CodePilot 中定时任务调度引擎(TaskScheduler)、心跳系统(HeartbeatRunner)与通知管理(NotificationManager)的完整架构、底层数据模型、关键源码实现,以及从"竞品借鉴"到"分阶段落地"的工程路线。

核心想法:让助理从"被动回应"变成"主动服务"

CodePilot 的定位是一个多模型 AI Agent 桌面客户端(Electron + Next.js),其助理能力的现状是:助理工作区提供人格 / 记忆 / 问询能力,Bridge 提供微信 / IM 远程控制,Context Assembler 负责上下文组装,语音助手在规划中。但这一切都依赖用户主动发起对话。

主动助理的关键拼图是把四块现有能力串成一条完整的主动链路:

现有能力                          本功能补齐
├─ 助理工作区(人格/记忆/问询)      ├─ 定时任务(cron 调度 + 持久化)
├─ Bridge(微信/IM 远程)           ├─ 心跳系统(定期醒来,有事才说)
├─ 语音助手(规划中)               ├─ 通知投递(系统通知/IM/浮窗/主窗口)
└─ Context Assembler              └─ 后台执行(无 UI 静默跑任务)
         ↓ 合在一起 ↓
    主动助理(Proactive Assistant)

其核心循环是:定时唤醒 → AI 判断是否有事要说 → 通过合适的渠道通知用户。三条原则贯穿始终:

  1. 有事才说,无事沉默:心跳巡检必须避免每次唤醒都产生无意义通知;
  2. 调度状态与用户内容分离:用户只维护"检查什么"(HEARTBEAT.md),"何时跑、上次跑到哪、是否投递成功"由系统持久化状态负责;
  3. 后台静默执行:定时任务在无 UI 环境下运行,失败可重试、可诊断、可回溯。

需要说明的是:2026-08-03 的路由决定中,"默认助理 → 心跳 → Electron 系统通知"这一 P0 垂直链路已由正式执行计划 default-assistant-heartbeat-system-notification.md 接管并在 v0.67.11 发布;本文继续保存任意 cron、Bridge、浮窗、TTS 等更广的后续构想,其中已落地部分会在相应小节以源码事实标注。

竞品调研:四个项目的定时任务实现对比

在设计之前,CodePilot 调研了四个项目的定时任务实现,核心对比维度包括调度引擎、持久化、任务模式、心跳协议、通知渠道、Active Hours 与重试策略:

维度 CoPaw OpenClaw NanoClaw Claude Code
调度引擎 APScheduler (Python) 自建 cron service (TS) SQLite 轮询 (60s) 自建 cron (1s 轮询)
持久化 jobs.json jobs.json SQLite 表 session-scoped 不持久化
任务模式 text / agent main session / isolated group / isolated 复用当前 session
心跳 Heartbeat + HEARTBEAT.md HeartbeatRunner + HEARTBEAT_OK 协议 无 无
通知 Channel (DingTalk/Feishu/Discord) Channel + Device Nodes (系统通知) IPC → Channel 终端内
Active Hours 有 有 (per-agent) 无 无
重试 misfire grace 指数退避 (30s→60m) 无 无

最值得借鉴的模式

调研结论提炼出四类值得吸收的模式:

OpenClaw 的 Heartbeat vs Cron 双轨制:Heartbeat 是"定期醒来"检查一批事项(读取 HEARTBEAT.md),context-aware,有事就说、没事沉默;Cron 则在精确时间点执行特定任务,isolated 模式不干扰主会话。CodePilot 现有的 daily check-in 本质就是 heartbeat 的雏形,两者复用同一套 workspace prompt + Context Assembler。

OpenClaw 的 HEARTBEAT_OK 协议:AI 回复 HEARTBEAT_OK 表示"没事",不打扰用户;其他回复表示"有事要说",投递到渠道通知用户。这一协议的价值在于用一个不可歧义的 token 把"静默"变成可编程的契约,避免每次心跳都产生无意义通知。

NanoClaw 的 context mode:group 模式带上下文跑(适合需要记忆的定期任务),isolated 模式使用全新会话(独立后台任务)。

OpenClaw 的系统通知 tool:Agent 主动调用 notify tool 发系统通知,支持 priority 分级(passive / active / timeSensitive)——这直接启发了 CodePilot 的 priority 分级设计。

架构设计:主进程内的三大核心模块

整体结构把三个模块全部放入 CodePilot 主进程(Electron Main),保证后台常驻:

┌──────────────────────────────────────────────────────┐
│  CodePilot 主进程 (Electron Main)                      │
│                                                       │
│  ┌─────────────────────────────────────────────────┐  │
│  │ TaskScheduler                                    │  │
│  │ • SQLite 持久化(复用现有 db.ts)                  │  │
│  │ • 三种 schedule: cron / interval / once          │  │
│  │ • 两种 context: session(带记忆) / isolated       │  │
│  │ • 轮询检查 due tasks(60s 间隔)                  │  │
│  │ • Active Hours 控制                              │  │
│  │ • 失败重试 + 指数退避                             │  │
│  └──────────┬──────────────────────────────────────┘  │
│             │                                         │
│  ┌──────────▼──────────────────────────────────────┐  │
│  │ HeartbeatRunner                                  │  │
│  │ • 定期"醒来",读 workspace 状态                   │  │
│  │ • 注入 heartbeat prompt → 调 AI                  │  │
│  │ • HEARTBEAT_OK → 静默,不打扰                     │  │
│  │ • 有事 → NotificationManager 投递                │  │
│  │ • 复用现有 daily check-in + Context Assembler    │  │
│  └──────────┬──────────────────────────────────────┘  │
│             │                                         │
│  ┌──────────▼──────────────────────────────────────┐  │
│  │ NotificationManager                              │  │
│  │ • Electron Notification(系统通知)                │  │
│  │ • Bridge 渠道(微信/IM)                          │  │
│  │ • 浮窗弹出(语音播报)                             │  │
│  │ • 主窗口内通知(badge / toast)                    │  │
│  │ • priority 分级: low / normal / urgent           │  │
│  └──────────────────────────────────────────────────┘  │
│                                                       │
│  管理入口:                                            │
│  • 设置页 UI(CRUD + pause / resume / run now)        │
│  • 助理对话中自然语言创建/管理                            │
│  • AI 自己通过 MCP tool 调度(自主创建提醒等)            │
└──────────────────────────────────────────────────────┘

模块 1:TaskScheduler — 定时调度引擎

任务的数据模型建议扩展现有 db.ts,设计如下:

// DB schema(扩展现有 db.ts)
interface ScheduledTask {
  id: string
  name: string
  enabled: boolean
  schedule_type: 'cron' | 'interval' | 'once'
  schedule_value: string        // cron expression / ms interval / ISO timestamp
  timezone: string              // IANA timezone, default 系统时区
  context_mode: 'session' | 'isolated'
  prompt: string                // AI 执行的指令
  dispatch_target: string       // 'notification' | 'bridge' | 'floating' | 'silent'
  active_hours_start?: string   // "09:00"
  active_hours_end?: string     // "22:00"
  next_run: string              // ISO timestamp
  last_run?: string
  last_status?: 'success' | 'error' | 'skipped'
  last_error?: string
  retry_count: number
  max_retries: number
  created_at: string
}

执行流程(七步):

  1. 主进程启动 → 从 SQLite 加载所有 enabled 任务
  2. 每 60s 轮询 next_run < now 的任务
  3. Active Hours 检查 → 不在范围内则跳过
  4. 按 context_mode 执行:session 在助理工作区会话中执行(带完整记忆 / 人格 / 历史);isolated 创建临时会话,执行完即销毁
  5. 执行完成 → 计算 next_run → 按 dispatch_target 投递结果
  6. 失败 → 指数退避重试(30s, 1m, 5m, 15m, 最多 max_retries 次)
  7. once 类型执行完 → 标记 completed

当前仓库的落地实现在 src/lib/task-scheduler.ts 中已经相当完整,且与原构想存在几处工程化差异值得注意:

  • 轮询间隔从 60s 收敛为 10s:POLL_INTERVAL = 10_000(第 15 行),并利用 globalThis 上的 GLOBAL_KEY 标记保证 HMR 下只启动一次;ensureSchedulerRunning() 还会在 NEXT_PHASE === 'phase-production-build' 或 CODEPILOT_RECOVERY_SAFE_MODE === '1' 时跳过启动,避免构建期污染。
  • 任务类型增加了 kind 维度:reminder(纯文本提醒,prompt 即通知正文,零模型调用,未配置模型也能用)与 ai_task(prompt 走模型,AI 回复即结果)。
  • 并发锁用 SQLite 行级 UPDATE 实现:runScheduledTaskNow 用 UPDATE ... WHERE last_status != 'running' 原子抢占,轮询与手动"Run now"竞争时只有一个赢家,另一个得到 already_running 且引用在途 runId——这正好回应了原文档"任务并发:多个任务同时 due 时串行还是并行"的待确认问题。
  • 启动恢复有三重防线:handleMissedTasks 补偿应用关闭期间错过的 once 任务;recoverStaleRunningTasks 把崩溃遗留的 last_status='running' 行按 30 分钟阈值重置为 error + 指数退避;checkExpiredTasks 自动停用超过 7 天的非 permanent 循环任务。
  • cron 解析器自研:getNextCronTime 实现了 5 字段 cron 表达式解析(支持 *、*/N、,、-),按天扫描最多 4 年(1461 天),支持闰年日期如 0 9 29 2 *;无合法匹配时暂停任务而非伪造执行时间。
  • 确定性抖动防惊群:getJitter 按 taskId 哈希出稳定抖动(间隔的 10%,上限 15 分钟),避免大量同间隔任务同时触发。
  • 失败自动停用:连续失败 10 次(MAX_CONSECUTIVE_ERRORS)自动 disabled,指数退避序列为 30s → 1m → 5m → 15m。

模块 2:HeartbeatRunner — 心跳系统

心跳是一种特殊的定时任务,但更轻量:

每 N 分钟醒来(默认 30m,用户可配)
  → 读 workspace 状态(最近记忆、待办、日历等)
  → 注入 heartbeat prompt("检查是否有需要提醒用户的事项")
  → AI 判断
    → 回复 HEARTBEAT_OK → 什么都不做,静默
    → 回复其他内容 → 投递到通知渠道

与现有 daily check-in 的关系:daily check-in 是"AI 主动找用户聊天"(触发对话);heartbeat 是"AI 后台巡检"(静默检查,有事才说);两者复用同一套 workspace prompt + Context Assembler。

Heartbeat prompt 的三个来源:默认内置 prompt(检查日历、待办、未读消息等);用户可在 workspace 放 HEARTBEAT.md 自定义检查项;定时任务也可以把自己注册为 heartbeat 检查项(批量执行,省 token)。

当前仓库的落地实现(P0 已 shipped,见 default-assistant-heartbeat-system-notification.md):

  • Heartbeat 不是独立 kind,而是 source='assistant_heartbeat' 的 ai_task:ensureHeartbeatTask(src/lib/task-scheduler.ts)幂等保证系统只存在 0 或 1 条 heartbeat 行;interval 下限为 1 小时,cron 表达式由 heartbeatCronForInterval 生成(≥24h 为 0 9 * * *,否则 0 */N * * *)。
  • 静默契约是精确匹配:src/lib/heartbeat.ts 的 classifyHeartbeatOutcome 规定只有 trim 后精确等于 HEARTBEAT_OK 才静默,HEARTBEAT_OK\n\n正文 也视为 speak-up——严格回应了"避免每次心跳都产生无意义通知"的诉求。
  • 空清单零成本:isHeartbeatContentEmpty 判断 HEARTBEAT.md 只含标题 / 空 checklist / 注释时直接 skipped_empty,0 模型调用、0 通知。
  • desired state 与 derived runtime state 分离:src/lib/assistant-heartbeat.ts 的 reconcileAssistantHeartbeat 把用户意图(.assistant/state.json 的 heartbeatEnabled / heartbeatIntervalHours)对账进 SQLite 的调度行;PATCH 顺序锁定为"先原子写 desired,再 reconcile",失败返回 blocked 而非假 success;runner 在执行前重读 desired state,disabled 后残留的 stale 行也会被 skipped_reconcile_drift 收口,保证 0 模型调用。
  • 调度系统防自递归:HEARTBEAT_TASK_PROMPT(src/lib/task-scheduler.ts)明确禁止心跳调用 codepilot_list_tasks / codepilot_schedule_task 等调度内省工具,最多一次 codepilot_memory_recent 调用——心跳巡检其所在的调度系统会无限递归。
  • 默认 HEARTBEAT.md 模板在 src/lib/heartbeat.ts 中提供,检查项包括未完成事项、临近 deadline、超过 3 天未互动、工作区文件变动,并明确"深夜 23:00-08:00 不打扰"。

模块 3:NotificationManager — 通知投递

通知的统一数据结构:

interface Notification {
  title: string
  body: string
  priority: 'low' | 'normal' | 'urgent'
  source: 'heartbeat' | 'scheduled_task' | 'agent'  // 来源
  action?: {
    type: 'open_session' | 'open_url' | 'open_floating'
    payload: string  // session id / url
  }
}

投递渠道按 priority 和用户配置决定:

priority 默认行为
low 主窗口内 badge,不弹通知
normal Electron 系统通知(macOS Notification Center / Windows Notification)
urgent 系统通知 + 声音 + Bridge 渠道(微信/IM) + 浮窗弹出

点击通知的行为:跳转到相关会话(open_session)、拉起浮窗显示摘要(open_floating),用户可配置默认行为。

当前仓库的落地实现在 src/lib/notification-manager.ts:

  • 事件 / 投递分层(1:N):一个逻辑通知 = 一行 notification_events(伞事件),每个候选渠道 = 一行 notification_deliveries,通过 event_id 关联。先落库再由消费者 claim,杜绝内存 ring buffer 承担可靠性。
  • 渠道 × priority 矩阵已收敛:low / normal / urgent 都写 electron-native 投递(P0.5 起页面右下角 toast 不再充当通知渠道,只服务操作反馈);bridge-telegram 仅 urgent 才写候选行,未配置时标 not_configured,配置但禁用时标 skipped,非 urgent 干脆不写 bridge 行——避免"考虑过 Bridge 但放弃"的语义误导。
  • 投递状态枚举冻结:queued | delivered | error | not_configured | skipped,claim / 重试只能由 additive 列(claim_owner、claimed_at、attempt_count、last_attempt_at、next_attempt_at)表达,见 src/lib/db.ts 中 1529-1538 行的迁移。
  • "已投递"只表示 OS 接受:Electron Main 必须收到 show 事件才 ack delivered;Windows 额外监听 failed,macOS / Linux 不等待不存在的 failed 事件而走 bounded timeout(P0.3 的 lifecycle adapter 合同)。
  • 点击路由由 Main 暂存:native payload 至少含 event_id、session_id、task_id 与 action kind,点击先 show/focus 主窗口,renderer 未 ready 时进入 bounded pending queue,ready 后按 event id 幂等消费。

与现有系统的集成点

现有模块 集成方式
db.ts 新增 scheduled_tasks + task_run_logs 表
assistant-workspace.ts Heartbeat 复用 workspace 文件加载 + prompt 注入
context-assembler.ts 新增 entryPoint: 'scheduled',按需注入上下文
claude-client.ts 任务执行复用现有 SDK 调用链路
stream-session-manager.ts isolated 任务创建临时 session
Bridge (conversation-engine) urgent 通知可通过 Bridge 投递到 IM
浮窗(规划中) urgent 通知可触发浮窗弹出 + TTS 播报
设置页 新增"定时任务"tab(任务列表/创建/编辑/日志)

上述集成点在仓库中已有相当比例成为现实:db.ts 中 scheduled_tasks、task_run_logs、notification_events、notification_deliveries 四张表全部存在(src/lib/db.ts),且 task_run_logs 增加 notification_event_id 列把"运行记录"与"通知投递"关联起来;任务执行走 src/lib/agent-task-runner.ts 的 runScheduledAgentTask,经 ensureTaskBoundSession 创建/复用 source='task' 的任务绑定会话(隐藏在主导航列表之外),并继承源会话的 runtime、provider、model 与权限 profile——后台任务永远不会把结果写进用户可见的普通聊天。heartbeat 的 speak-up 则写入 buddy 会话(懒创建),点击通知通过 heartbeatNotificationAction 返回 /chat/<sessionId> 路由(src/lib/task-scheduler.ts)。

AI 自主调度:MCP tool 定义

AI 在对话中可以自己创建定时任务,这是"主动助理"的最后一环:

用户:"明天下午三点提醒我开会"
  → AI 调用 schedule_task tool
  → 创建 once 类型任务,dispatch_target: 'notification'

用户:"每天早上九点给我总结昨天的邮件"
  → AI 调用 schedule_task tool
  → 创建 cron 类型任务,prompt 包含邮件总结指令

AI heartbeat 发现用户日历有冲突:
  → AI 调用 notify tool
  → 立即发系统通知

MCP tool 定义:

// tool: schedule_task
interface ScheduleTaskInput {
  name: string
  schedule_type: 'cron' | 'interval' | 'once'
  schedule_value: string
  prompt: string
  context_mode?: 'session' | 'isolated'
  dispatch_target?: 'notification' | 'bridge' | 'floating' | 'silent'
  priority?: 'low' | 'normal' | 'urgent'
  active_hours?: { start: string; end: string }
}

// tool: notify (立即通知)
interface NotifyInput {
  title: string
  body: string
  priority?: 'low' | 'normal' | 'urgent'
  action?: { type: string; payload: string }
}

// tool: list_tasks / cancel_task / pause_task / resume_task

从仓库现状看,/api/tasks/schedule 与任务 CRUD 路由、/api/tasks/[id]/run(Run Now)、/api/tasks/[id]/runs(运行历史 + 投递详情 join)等 HTTP 面已存在,为 AI 自主调度提供了服务端基础;原文档规划的 schedule_task / notify 等 MCP tool 形态仍在 Phase 3 构想中,未全部落地。

实现优先级:四个阶段的演进路线

原文档给出了清晰的渐进式落地顺序,仓库实际进度与之高度吻合:

Phase 1:通知基础 + 简单定时(✅ 已落地)

  • NotificationManager(Electron Notification API)
  • TaskScheduler 基础(SQLite 持久化 + 轮询 + cron/once)
  • 设置页 UI(任务列表 + 创建)
  • AI 可调用 notify tool 发即时通知

Phase 2:心跳系统(✅ P0 已随 v0.67.11 发布,packaged native smoke 部分待验收)

  • HeartbeatRunner(定期醒来 + HEARTBEAT_OK 协议)
  • 与 workspace prompt 集成
  • Active Hours 控制
  • HEARTBEAT.md 自定义检查项

Phase 3:AI 自主调度(⏳ 部分基础就绪)

  • schedule_task / cancel_task 等 MCP tool
  • 对话中自然语言管理任务
  • isolated 上下文模式

Phase 4:多渠道投递(⏳ 规划中)

  • Bridge 渠道投递(urgent 级别)
  • 浮窗弹出 + 语音播报(依赖语音助手,见 voice-assistant.md)
  • 投递策略配置(用户选择哪些渠道接收哪些级别)

待确认的问题与当前仓库给出的答案

原文档在收尾时留下了五个开放问题,其中多数已被后续的 P0 执行计划与源码实现回答:

原文档待确认问题 当前仓库的答案
轮询间隔 60s 够用吗?once 类型"3 分钟后提醒"精度不够 落地为 10s 轮询(POLL_INTERVAL = 10_000);once 精度瓶颈仍存在,且 next_run 以分钟级 cron 计算,秒级提醒建议走 interval 型 session task
Electron 后台限制:最小化/不活跃时 setInterval 可能被节流 P0.3 明确由 Electron Main 独占 electron-native 投递、生命周期 adapter 处理;powerSaveBlocker / Main Process timer 仍是后续选项
任务并发:多个任务同时 due 时串行还是并行 每个任务独立 fire-and-forget 执行,但同一任务由 SQLite 行锁保证单实例;并行度受 API 调用量控制,runScheduledTaskNow 对并发返回 already_running
Token 消耗:heartbeat 每次调 AI,30m 间隔一天 48 次 多项成本防线:heartbeat 默认 off;interval 下限 1 小时;空 checklist 0 模型调用(skipped_empty);desired off 时 runner 前置 gate 0 Provider call;连续失败 10 次自动停用;prompt 严格限制工具调用(最多 1 次 memory_recent)
用户感知:后台跑任务时主窗口是否显示指示器 任务运行状态、上次 / 下次执行时间、失败原因在设置页"定时任务"tab 中可见;heartbeat 的 desired / scheduler / last attempt / next run / last delivery 字段分离展示,不混进 Markdown

总结:一条贯穿文件、调度、模型与系统 API 的纵向链路

CodePilot 的主动助理设计最有价值的一点,是它把"定时调度"、"心跳巡检"与"通知投递"当作一条真实事件贯穿的纵向闭环来建设:用户内容(HEARTBEAT.md、workspace 文件)只负责表达"检查什么";调度状态(scheduled_tasks)、运行记录(task_run_logs)与投递事实(notification_events / notification_deliveries)各自落在 SQLite 的独立表里;Electron Main 独占系统通知的 claim / ack / click 路由;每一层都保留 source breadcrumb 以支撑诊断。

对于想要在自己项目中实现同类能力的开发者,可以按本文的三个模块逐步落地:先做"事件 / 投递"分层的 NotificationManager 与带行锁的 TaskScheduler,再做带精确 HEARTBEAT_OK 静默契约的 HeartbeatRunner,最后开放 AI 自主调度的 MCP tool 与多渠道投递。四个阶段的划分、DB schema 与执行契约在仓库的 default-assistant-heartbeat-system-notification.md(P0 执行计划)与 task-scheduler.ts、heartbeat.ts、notification-manager.ts、assistant-heartbeat.ts 中均有完整的落地证据可循。

登录后查看全文
CodePilot