CodePilot 定时任务与通知系统:从 MCP 工具到 SQLite 调度器的完整实现指南

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

CodePilot 定时任务与通知系统:从 MCP 工具到 SQLite 调度器的完整实现指南

本文基于 CodePilot 仓库内 scheduled-tasks-notifications.md 的原始设计计划展开,并结合仓库中实际落地的实现源码(src/lib/task-scheduler.ts、src/lib/notification-mcp.ts、src/lib/notification-manager.ts、src/app/api/tasks/* 等)进行验证与深化。读者将掌握 CodePilot 中"AI 可创建定时任务、全局可发通知"这一能力的完整链路:MCP 工具定义、SQLite 持久化 Schema、API 路由、10 秒轮询调度器、多渠道通知分发,以及心跳系统与定时任务的边界划分。读完本文,你可以直接理解并复用这套"通知即 MCP 工具 + 调度器在服务端轮询"的架构方案。

说明:该计划文档已由仓库维护者归档至 superseded/(被 refactor-closeout 的 Phase 3 接管),但其中的架构设计与代码骨架已在当前仓库中完整落地并持续演进,因此本文以"设计 → 实现 → 演进"的脉络呈现。

为什么需要"通知与定时任务":方案选型背景

在最初的设计阶段,团队对比了四个参考项目的实现(Claude Code / OpenClaw / CoPaw / NanoClaw),聚焦五个维度:存储方式、调度类型、通知方式、AI 是否可创建、持久化与失败处理。

维度 Claude Code OpenClaw CoPaw NanoClaw
存储 内存(session-scoped) JSON 文件 JSON 文件 SQLite
调度类型 cron / once at / every / cron cron cron / interval / once
通知方式 当前 terminal 多渠道(IM + webhook) Console push IPC → IM
AI 可创建 ✅ CronCreate tool ❌ ❌ ✅ IPC file
持久化 ❌ 进程退出即丢失 ✅ ✅ ✅
失败处理 无 指数退避 + 告警冷却 简单日志 日志
漂移防护 无 锚点 + stagger APScheduler 锚点

最终选型结论(即 CodePilot 采用的方案):

  • 存储:SQLite——仓库已有 db.ts 统一管理数据库,NanoClaw 验证可行;
  • 调度:cron + interval + once 三种类型,覆盖最全面的调度需求;
  • 通知:MCP tool(全局可用,任何上下文都能调用)+ Electron 系统通知 + 已有 Telegram;
  • AI 创建:MCP tool,比 NanoClaw 的 IPC 方式更简洁;
  • 持久化:SQLite,跨应用重启保留。

这套选型的核心判断是:通知能力必须全局可用,不能绑定在某个助理模式或项目上下文中;而调度器不能依赖 Next.js API 路由的生命周期,需要一个独立、持久的运行载体。

系统架构总览

设计文档给出了完整的双层架构:Electron Main Process 与 Renderer(Next.js)之间通过 IPC 与 HTTP API 协作。

┌────────────────────────────────────────────────────┐
│  Electron Main Process                              │
│                                                     │
│  ┌───────────────────────────────────────────────┐  │
│  │ TaskScheduler                                  │  │
│  │ • setInterval 轮询(10s 间隔)                  │  │
│  │ • SQLite 读取 due tasks                        │  │
│  │ • 触发执行:IPC → Renderer → POST /api/chat    │  │
│  │ • 漂移防护:锚点计算                            │  │
│  │ • 失败退避:指数退避 30s → 5m → 15m             │  │
│  └───────────────────────────────────────────────┘  │
│                                                     │
│  ┌───────────────────────────────────────────────┐  │
│  │ NotificationManager                            │  │
│  │ • Electron Notification API(系统通知)          │  │
│  │ • IPC → Renderer Toast(应用内通知)             │  │
│  │ • Telegram(复用已有 telegram-bot.ts)          │  │
│  └───────────────────────────────────────────────┘  │
│                                                     │
│         ↕ IPC                                       │
├────────────────────────────────────────────────────┤
│  Renderer (Next.js)                                 │
│                                                     │
│  ┌───────────────────────────────────────────────┐  │
│  │ Notification MCP (codepilot-notify)            │  │
│  │ • codepilot_notify:发即时通知                   │  │
│  │ • codepilot_schedule_task:创建定时任务          │  │
│  │ • codepilot_list_tasks:列出任务                │  │
│  │ • codepilot_cancel_task:取消任务               │  │
│  │ → 全局注册,所有上下文可用(不限助理)             │  │
│  └───────────────────────────────────────────────┘  │
│                                                     │
│  ┌───────────────────────────────────────────────┐  │
│  │ API Routes                                     │  │
│  │ • POST /api/tasks/notify  — MCP 调用的后端      │  │
│  │ • POST /api/tasks/schedule — 创建任务           │  │
│  │ • GET  /api/tasks/list    — 列出任务           │  │
│  │ • DELETE /api/tasks/:id   — 取消任务           │  │
│  │ • POST /api/tasks/:id/run — 立即执行           │  │
│  └───────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────┘

四条核心设计原则贯穿始终:

  1. 通知是 MCP tool——任何上下文(助理/项目/Bridge)都能调 codepilot_notify 发通知;
  2. 定时任务也是 MCP tool——AI 通过 codepilot_schedule_task 创建/管理任务;
  3. 调度器在 Electron Main Process——不依赖 Next.js API 路由的生命周期;
  4. 通知多渠道——Electron 系统通知 + Toast + Telegram(已有)。

需要说明的是,架构图中的"调度器在 Electron Main Process"在实现阶段经过一次关键修正:由于 Electron Main Process 不能直接调用 Next.js API(需走 HTTP localhost 或 IPC),实现改为调度器跑在 Next.js API 层(Node.js 服务端进程),用 setInterval 服务端轮询——因为 CodePilot 的 Next.js dev server 始终运行,这个方案更可靠。这一点在源码 task-scheduler.ts 的头部注释中明确记录。

Phase 1:Notification MCP——全局通知工具

工具定义(实现版)

设计文档规划了 2 个核心工具,落地后的 notification-mcp.ts 扩展到了 5 个(含新增的 codepilot_hatch_buddy,与助手伙伴功能联动)。MCP 服务命名为 codepilot-notify,通过 createSdkMcpServer 创建,属于进程内(in-process)MCP server。

codepilot_notify:发送即时通知

tool(
  'codepilot_notify',
  'Send an immediate notification to the user. Supports system notification, in-app toast, and Telegram (for urgent). Use when a task completes, something needs attention, or user asked to be notified.',
  {
    title: z.string().describe('Notification title'),
    body: z.string().describe('Notification body text'),
    priority: z.enum(['low', 'normal', 'urgent']).optional().default('normal')
      .describe('low=toast only, normal=toast+system, urgent=toast+system+telegram'),
  },
  async ({ title, body, priority }) => {
    try {
      const { sendNotification } = await import('@/lib/notification-manager');
      await sendNotification({ title, body, priority });
      return { content: [{ type: 'text' as const, text: `Notification sent: "${title}"` }] };
    } catch (err) {
      return { content: [{ type: 'text' as const, text: `Failed to send notification: ${err instanceof Error ? err.message : 'unknown'}` }] };
    }
  },
)

优先级语义在实现中保持不变:low 仅 Toast、normal Toast + 系统通知、urgent Toast + 系统通知 + Telegram(若已配置)。

codepilot_schedule_task:创建定时任务

实现版本在原始 schedule_type: cron/interval/once 基础上,新增了 kind(任务类型) 与 durable(是否持久化) 两个关键参数,这是后续演进的核心:

tool(
  'codepilot_schedule_task',
  'Create a scheduled task. Pick `kind` based on user intent: ' +
    '`reminder` for natural-language reminders (e.g. "remind me to drink water in 5 minutes" — ' +
    'shows a notification with the prompt as body, NEVER calls a model); `ai_task` for ' +
    'workflows where an AI should run on schedule (e.g. "every Monday review last week\'s commits" ' +
    '— feeds the prompt to the configured provider). Supports cron / interval / once schedules.',
  {
    name: z.string().describe('Task name (e.g. "Drink water reminder")'),
    prompt: z.string().describe(
      'For kind=reminder: notification body the user will see. ' +
      'For kind=ai_task: instruction handed to the model.',
    ),
    kind: z.enum(['reminder', 'ai_task']).describe(
      "Task kind: 'reminder' (notification only, no AI call) or 'ai_task' (run prompt against configured provider)",
    ),
    schedule_type: z.enum(['cron', 'interval', 'once']).describe('Schedule type'),
    schedule_value: z.string().describe('cron: "0 9 * * *", interval: "30m"/"2h", once: ISO timestamp like "2026-03-31T15:00:00"'),
    priority: z.enum(['low', 'normal', 'urgent']).optional().default('normal'),
    notify_on_complete: z.boolean().optional().default(true),
    durable: z.boolean().optional().default(true).describe('true=persists across restart, false=session-only'),
  },
  // handler:durable=true 时 POST /api/tasks/schedule 持久化;
  // durable=false 时直接写入内存 Map(addSessionTask),并本地计算 next_run
)

kind 的引入解决了原始设计的一个隐患:自然语言提醒(reminder)不需要也不应该调用模型。kind='reminder' 时,prompt 文本本身就是通知正文,完全绕过 AI 调用——即使未配置任何模型,"5 分钟后提醒我喝水"也能工作;kind='ai_task' 才把 prompt 交给已配置的 provider 执行。这一拆分在 db.ts 的 createScheduledTask 中也做了服务端强校验:kind 必须是 'reminder' 或 'ai_task',否则直接抛错,杜绝"自然语言提醒误调模型"的回归。

codepilot_list_tasks / codepilot_cancel_task:任务查询与管理

  • codepilot_list_tasks 支持按 status(active/paused/completed/disabled/all)过滤,返回结果会合并 SQLite 持久化任务与内存 session 任务,session 任务以 (session) 后缀标记;
  • codepilot_cancel_task 接收 task_id,优先尝试删除内存 session 任务,未命中则回退到 DELETE /api/tasks/:id 删除持久化任务。

System Prompt 注入

设计文档给出了系统提示词模板,实现中保留为 NOTIFICATION_MCP_SYSTEM_PROMPT(见 notification-mcp.ts),并扩展了使用场景指引,例如:

  • 用户说"提醒我..."或"X 分钟后..." → codepilot_schedule_task(schedule_type: "once");
  • 用户说"每天/每小时..." → codepilot_schedule_task(schedule_type: "cron" 或 "interval");
  • 任务完成需要告知用户 → codepilot_notify。

全局注册方式

设计文档要求在 claude-client.ts 中无条件(不放在任何条件块内)注册。实现还补充了**隐藏运行上下文(hidden run context)**机制:MCP 工具工厂接受 { sessionId, workingDirectory } 上下文(在注册时闭包捕获),codepilot_schedule_task 执行时将这些值作为 origin_session_id 与 working_directory 注入 POST body——模型无法覆盖它们,因为取值来自闭包而非模型参数。这一设计解决了跨项目串扰问题:从项目 A 创建的定时任务,触发时不会错误写入项目 B 的会话。

Phase 2:TaskScheduler——SQLite 持久化调度器

DB Schema

设计文档给出了 scheduled_tasks 表 DDL。落地实现(db.ts)在此基础上新增了 kind 与 source 两列,并配套了 task_run_logs(单次执行日志)、notification_events / notification_deliveries(通知事件与投递明细)等表,形成完整的任务生命周期记录链。核心列含义如下:

列 类型/约束 含义
id TEXT PK 任务 ID(crypto.randomBytes(8).toString('hex') 生成)
name / prompt TEXT NOT NULL 任务名称 / 触发后执行的指令(reminder 时即通知正文)
schedule_type TEXT CHECK cron / interval / once
schedule_value TEXT NOT NULL cron 表达式 / 间隔串 / ISO 时间戳
kind TEXT reminder(仅通知不调模型)/ ai_task(调模型执行)
source TEXT user(用户任务)/ assistant_heartbeat(系统心跳注入,默认 'user')
next_run TEXT NOT NULL 下次执行时间(datetime(next_run) 与 datetime('now') 比较)
last_status TEXT CHECK success / error / skipped / running(5 状态机只存在于 task_run_logs.status,此列受 SQLite CHECK 约束未扩展)
consecutive_errors INTEGER DEFAULT 0 连续失败次数,驱动指数退避与自动禁用
status TEXT DEFAULT 'active' active / paused / completed / disabled
priority TEXT DEFAULT 'normal' low / normal / urgent
notify_on_complete INTEGER DEFAULT 1 完成后是否通知(0/1)
permanent INTEGER 1 表示永不过期(心跳任务)
session_id / origin_session_id TEXT 会话归属与来源会话(防跨项目串扰)
working_directory TEXT 任务所属工作目录
created_at / updated_at TEXT 时间戳,默认 datetime('now')

索引:idx_scheduled_tasks_next_run(按 next_run 查询到期任务)、idx_scheduled_tasks_status(按状态过滤)。

API 路由

设计文档规划了完整路由集,实现已全部落地(src/app/api/tasks/ 目录):

POST   /api/tasks/schedule       — 创建任务
GET    /api/tasks/list           — 列出任务(可选 status 过滤)
GET    /api/tasks/:id            — 获取单个任务
DELETE /api/tasks/:id            — 取消/删除任务
POST   /api/tasks/:id/run        — 立即执行
POST   /api/tasks/:id/pause      — 暂停
POST   /api/tasks/:id/resume     — 恢复
POST   /api/tasks/notify         — 发送即时通知

以 schedule/route.ts 为例,创建流程的服务端校验要点:

  1. 必填校验:name、prompt、schedule_type、schedule_value 缺失返回 400;
  2. source 字段保留:路由拒绝任何显式 source 字段(400),assistant_heartbeat 仅允许 ensureHeartbeatTask 内部注入——"提醒工具不能创建心跳任务"成为显式契约;
  3. kind 强校验:非 reminder/ai_task 返回 400,不做默认值兜底(防止 AI 工具创建"提醒"却静默走模型路径);
  4. next_run 计算:once 直接转 ISO;interval 用 parseInterval 换算毫秒并加到现在;cron 用 getNextCronTime 计算,4 年内无匹配返回 400;
  5. notify_on_complete 归一化:布尔值(true/false)在入库前归一为 0/1,避免 better-sqlite3 对原始布尔绑定抛错(SQLite3 can only bind numbers, strings, bigints, buffers, and null);
  6. 创建后调用 ensureSchedulerRunning() 确保调度器轮询已启动。

调度器实现:服务端 10 秒轮询

设计文档中"Electron Main Process 调度器"方案在实现时被修正为 Next.js 服务端轮询(见 task-scheduler.ts),关键常量与机制:

const POLL_INTERVAL = 10_000; // 10s 轮询
const GLOBAL_KEY = '__codepilot_scheduler__';
const BACKOFF_DELAYS = [30000, 60000, 300000, 900000]; // 30s, 1m, 5m, 15m
const MAX_CONSECUTIVE_ERRORS = 10;   // 连续失败 10 次自动禁用
const RECURRING_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 周期任务 7 天自动过期

ensureSchedulerRunning() 的幂等启动逻辑:

  • 用 globalThis 上的标记位保证只启动一次(同时天然对抗 dev 模式 HMR 导致的多实例);
  • 生产构建阶段(NEXT_PHASE === 'phase-production-build')与恢复安全模式(CODEPILOT_RECOVERY_SAFE_MODE === '1')下不启动;
  • 启动时依次执行:错过任务恢复(handleMissedTasks)→ 停滞 running 恢复(recoverStaleRunningTasks)→ 过期任务清理(checkExpiredTasks,每小时一次);
  • 轮询定时器与过期清理定时器均 .unref(),不阻止进程退出。

每次轮询:从 SQLite 读取 due tasks(getDueTasks():datetime(next_run) <= datetime('now') AND status = 'active' AND last_status != 'running'),对每个到期任务调用统一入口 runScheduledTaskNow(task.id);同时扫描内存中的 session-only 任务并就地执行。

到期任务查询的坑:getDueTasks 中 next_run 是 ISO 字符串(如 '2026-05-09T09:05:00.000Z'),而 datetime('now') 返回空格分隔形式('2026-05-09 09:06:00'),直接字符串比较会导致当日"5 分钟后的 once 任务"永不触发。修复方式是把 next_run 包进 datetime() 再比较(db.ts)。

执行引擎:reminder 与 ai_task 的分流

执行入口 executeDueTask 是整条链路的枢纽,按 kind 分流(task-scheduler.ts):

  • kind === 'reminder':prompt 即通知正文,零模型调用直接返回,随后发送 ⏰ 前缀通知——这正是"无模型也能用提醒"的实现基础;
  • kind === 'ai_task':优先走 runScheduledAgentTask(agent-task-runner.ts,复用完整 agent 能力,可创建任务绑定会话);兜底路径使用 generateTextFromProvider 轻量生成(通过 resolveProvider({ callScene: 'scheduled_task' }) 解析 provider,系统提示要求"Be concise and direct",maxTokens: 1000),不做 streaming UI;
  • 成功后 computeNextRun 推进 next_run,并根据 notify_on_complete 发送 ✅ 通知;失败则 consecutive_errors++、applyBackoff 指数退避、发 ❌ urgent 通知,并把失败消息写入任务绑定的会话(仅当 session_id 指向 source='task' 的会话,防止跨项目污染)。

单行运行日志(one execution = one row):每次执行先插入一条 task_run_logs(status='running')拿到 runId,结束后用 updateTaskRunLog 原地翻转为 success/error,并把 notification_event_id 回写到该行——任务、运行、通知三者可追溯。

并发与漂移防护

  • 原子行锁:runScheduledTaskNow 用 UPDATE scheduled_tasks SET last_status='running' WHERE id=? AND (last_status IS NULL OR last_status != 'running') 抢占执行权;changes === 0 说明已有执行在进行,返回 already_running 并附上在飞行 runId——轮询与手动"Run Now"竞态时只会产生一次模型调用;
  • 锚点计算:interval 任务基于 last_run 锚点推进,用 while (nextRun <= now) 跳过错过的周期,避免重启后连环补跑;
  • 确定性抖动(deterministic jitter):同一任务始终得到同一抖动偏移(基于 taskId 前 8 位哈希),最大为间隔的 10%、上限 15 分钟,防止大量同间隔任务"惊群";
  • cron 解析器:getNextCronTime 是自实现的 5 字段解析器,按天扫描 1461 天(4 年)、每天 1440 分钟,支持 *、*/N、逗号列表、区间 a-b,能正确处理闰年日期(如 0 9 29 2 *);4 年内无匹配返回 null,任务被置为 paused;
  • interval 解析:parseInterval 支持 30m、2h、1d、30s,非法输入默认 10 分钟;
  • 停滞恢复:应用崩溃时任务可能停留在 last_status='running',recoverStaleRunningTasks 在启动时把超过 30 分钟未更新的 running 任务翻转为 error 并应用退避;
  • 错过任务恢复:应用关闭期间过期的 once 任务,启动时通过 handleMissedTasks 立即执行并发送"Missed during downtime — running now"通知(只发通知,不再把"过期提醒"写入最新工作区会话——后者曾造成跨项目串扰)。

周期任务自动过期

非 permanent 的周期任务创建超过 7 天后自动 disabled(checkExpiredTasks,启动时 + 每小时执行),并发送 low 优先级"已自动过期"通知。心跳任务 permanent: 1 豁免。

Phase 3:Electron 系统通知与多渠道分发

通知后端

设计文档给出 ipcMain.handle('show-notification', ...) 方案。落地实现演化为**事件/投递分离(events/deliveries split)**模型(notification-manager.ts):

  • 一条逻辑通知 = 一条 notification_events 行(伞形事件,evt-${Date.now()}-${random} 生成 ID,记录 task_id、session_id、action、source、title、body、priority);
  • 每个候选渠道 = 一条 notification_deliveries 行,通过 event_id 关联(1:N);渠道状态:queued / delivered / error / not_configured / skipped;
  • 渠道 × 优先级矩阵(实现版与设计版略有差异,最终策略以源码为准):
优先级 electron-native(系统通知) bridge-telegram
low queued 不写入(非 urgent 不构成候选渠道)
normal queued 不写入
urgent queued queued / not_configured / skipped → delivered / error
  • Telegram 仅在 urgent 且满足 telegram_enabled === 'true' 且配置了 telegram_bot_token 与 telegram_chat_id 时投递,复用 telegram-bot.ts 的 notifyGeneric;未配置写 notified_configured,已禁用写 skipped;
  • 投递行通过 UNIQUE(event_id, channel) 约束与 UPSERT 保证幂等,服务端/渲染进程重启后未投递的队列仍保留在持久化行中(无破坏性内存排空)。

Electron Main 侧(main.ts)使用原生 Notification API 构建系统通知,并通过 notification-click-queue.ts 管理点击事件;点击后唤起主窗口并路由到指定页面(如 /settings/tasks?focus=… 或心跳的 /chat/:sessionId,见 heartbeatNotificationAction)。

前端调用与设计差异说明

设计文档中的 sendNotification 前端实现(先 Toast、再 electronAPI.showNotification、再 fetch Telegram)在演进中调整为:通知实现集中在 Next.js 服务端进程(即 notification-manager.ts 在服务端运行),渲染进程的 Toast 只作为交互反馈面而非投递渠道,最终展示统一由 Electron Main 完成(每个优先级都走 electron-native),各渠道通过 ack 回写投递行状态。设计意图不变:一套 sendNotification({ title, body, priority, taskId, sessionId, action }) 统一分发,调用方无需关心渠道细节。

Phase 4:管理 UI 与看板集成

设计文档规划了设置页"定时任务"tab(任务列表:名称、调度、状态、下次执行、操作按钮;创建表单;暂停/恢复/删除/立即执行)与看板计数。落地实现对应:

任务执行需要权限时,任务状态被置为 paused 并发送 urgent 通知,用户进入任务绑定的会话选择"Re-run this task"或"Abandon"——v1 不做持久化恢复。

实施顺序与独立价值

设计文档给出四阶段实施顺序,Phase 1 单独就具有价值——AI 可以在任何对话中发通知:

Phase 1 (Notification MCP) ←── 最先做,立即有价值
    ↓
Phase 2 (TaskScheduler)    ←── 核心调度器
    ↓
Phase 3 (Electron 通知)    ←── 系统通知增强
    ↓
Phase 4 (管理 UI)          ←── 可视化管理

从当前仓库状态看,四个阶段均已落地:src/lib/notification-mcp.ts(Phase 1)、src/lib/task-scheduler.ts + src/app/api/tasks/*(Phase 2)、electron/main.ts + src/lib/notification-manager.ts(Phase 3)、src/components/settings/TasksSection.tsx(Phase 4),并有 task-scheduler.test.ts、scheduler-reminder-and-recovery.test.ts、scheduler-trigger-unification.test.ts 等单元测试保障。

与心跳系统的边界

设计文档明确了定时任务与心跳系统的分工(该边界已在 ensureHeartbeatTask 实现中落实):

维度 心跳 定时任务
作用域 助理 workspace 专属 全局,任何项目
触发 打开会话时 后台调度器
内容 HEARTBEAT.md 检查清单 用户自定义 prompt
静默协议 HEARTBEAT_OK 无

实现要点:

  • 心跳不是独立的 kind,而是 kind='ai_task' 且 source='assistant_heartbeat' 的任务,运行时按 source 分支复用伙伴会话并应用静默契约(HEARTBEAT_TASK_PROMPT:最多一次工具调用、HEARTBEAT_OK 精确匹配才算静默);
  • ensureHeartbeatTask({ enabled, intervalHours }) 幂等:禁用时删除心跳行;启用时保证恰好一行,interval 变更就地更新不更换 ID;interval 最小 1 小时(intervalHours < 1 按 1 处理),>= 24h 生成 0 9 * * *(每日 9 点),否则生成 0 */N * * *;
  • stale-check 守卫:心跳任务若 last_run 距今小于心跳间隔(由 cron 反推),本轮跳过执行、仅把 next_run 推进——防止"应用在 3:01 启动就把 3:00 的 cron 心跳立即补跑一次";
  • 心跳静默时不通知、不标记、不写助理消息;speak-up 时通知带 💬 前缀,点击跳回 /chat/:sessionId;
  • 设计文档的远期设想——"未来心跳可用 TaskScheduler 作为底层调度器(替代打开会话时触发)"——已在当前实现中兑现:心跳正是运行在 TaskScheduler 之上的 assistant_heartbeat 任务。

延伸阅读

登录后查看全文
CodePilot