CodePilot 主动助理架构:定时任务调度、心跳巡检与多渠道通知投递
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 判断是否有事要说 → 通过合适的渠道通知用户。三条原则贯穿始终:
- 有事才说,无事沉默:心跳巡检必须避免每次唤醒都产生无意义通知;
- 调度状态与用户内容分离:用户只维护"检查什么"(HEARTBEAT.md),"何时跑、上次跑到哪、是否投递成功"由系统持久化状态负责;
- 后台静默执行:定时任务在无 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
}
执行流程(七步):
- 主进程启动 → 从 SQLite 加载所有 enabled 任务
- 每 60s 轮询
next_run < now的任务 - Active Hours 检查 → 不在范围内则跳过
- 按 context_mode 执行:
session在助理工作区会话中执行(带完整记忆 / 人格 / 历史);isolated创建临时会话,执行完即销毁 - 执行完成 → 计算 next_run → 按 dispatch_target 投递结果
- 失败 → 指数退避重试(30s, 1m, 5m, 15m, 最多 max_retries 次)
- 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事件才 ackdelivered;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 可调用
notifytool 发即时通知
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 中均有完整的落地证据可循。