---
version: 2.0
last-updated: 2026-03-09
status: design
---

# 08 — Heartbeat 与 Cron 定时任务

## 一、概述

QimingClaw V2 需要**定时任务**能力来支持：

1. **Heartbeat（心跳）** - 定期检查服务器连接、同步状态、执行后台维护
2. **Cron Jobs（定时任务）** - 用户定义的定时执行任务（提醒、定时报告、自动化等）

### 服务器已有能力

Qiming 服务器已有定时会话任务 API：

| 端点 | 能力 |
|------|------|
| `POST /api/agent/task/create` | 创建定时会话 |
| `POST /api/agent/task/update` | 更新定时会话 |
| `POST /api/agent/task/list` | 查询定时会话列表 |
| `POST /api/agent/task/cancel/:id` | 取消定时会话 |
| `GET /api/agent/task/cron/list` | 可选定时范围 |
| `GET /api/task/cron/list` | 可选定时范围 - 任务 |

客户端将复用这些 API，并提供：
- 本地任务缓存和离线查看
- 更丰富的任务类型（提醒、脚本、Webhook）
- Heartbeat 心跳检查能力

```
┌────────────────────────────────────────────────────────────────────────┐
│                      定时任务架构                                       │
├────────────────────────────────────────────────────────────────────────┤
│                                                                        │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │  Heartbeat (心跳)                                                 │  │
│  │  - 周期: 30s ~ 5min (可配置)                                       │  │
│  │  - 职责: 连接检查、状态同步、后台维护                               │  │
│  │  - 触发: 系统自动                                                  │  │
│  └──────────────────────────────────────────────────────────────────┘  │
│                                                                        │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │  Cron Jobs (定时任务)                                              │  │
│  │  - 周期: 用户定义 (cron 表达式)                                    │  │
│  │  - 职责: 定时提醒、定时报告、自动化任务                             │  │
│  │  - 触发: 用户创建 / 服务器同步                                      │  │
│  │  - 复用服务器 /api/agent/task/* API                               │  │
│  └──────────────────────────────────────────────────────────────────┘  │
│                                                                        │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │  Scheduler Core                                                   │  │
│  │  - 统一调度引擎                                                    │  │
│  │  - 任务持久化 (SQLite)                                            │  │
│  │  - 错过任务恢复                                                    │  │
│  │  - 与服务器同步                                                    │  │
│  └──────────────────────────────────────────────────────────────────┘  │
│                                                                        │
└────────────────────────────────────────────────────────────────────────┘
```

---

## 二、Heartbeat（心跳）

### 2.1 设计目标

Heartbeat 是**轻量级周期性检查**，用于：

1. **服务器连接健康检查** - 检测与 Qiming Server 的连接状态
2. **配置同步状态检查** - 检查 MCP、Skills、模型等配置是否需要同步
3. **后台维护** - 清理过期缓存、更新状态、执行低优先级任务
4. **用户提醒** - 检查是否有新的通知、消息等

### 2.2 架构设计

```
┌────────────────────────────────────────────────────────────────────────┐
│                      Heartbeat 架构                                     │
├────────────────────────────────────────────────────────────────────────┤
│                                                                        │
│  ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐  │
│  │ Main Process    │     │ HeartbeatEngine │     │ HeartbeatTasks  │  │
│  │                 │────▶│                 │────▶│                 │  │
│  │ - 应用启动      │     │ - 定时器管理    │     │ - 检查任务列表  │  │
│  │ - 窗口状态      │     │ - 防重复执行    │     │ - 执行检查逻辑  │  │
│  │ - 系统 tray     │     │ - 错误恢复      │     │ - 通知 UI       │  │
│  └─────────────────┘     └─────────────────┘     └─────────────────┘  │
│                                                           │            │
│                                                           ▼            │
│  ┌─────────────────────────────────────────────────────────────────┐  │
│  │  Heartbeat Tasks (可配置)                                        │  │
│  │                                                                  │  │
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌───────────┐  │  │
│  │  │ Server      │ │ Config      │ │ Maintenance │ │ Notify    │  │  │
│  │  │ Health      │ │ Sync Check  │ │ Tasks       │ │ Check     │  │  │
│  │  │ Check       │ │             │ │             │ │           │  │  │
│  │  └─────────────┘ └─────────────┘ └─────────────┘ └───────────┘  │  │
│  │                                                                  │  │
│  │  每次心跳可选择执行哪些任务（根据上次执行时间间隔）                │  │
│  └─────────────────────────────────────────────────────────────────┘  │
│                                                                        │
└────────────────────────────────────────────────────────────────────────┘
```

### 2.3 HeartbeatEngine 实现

```typescript
/**
 * 心跳引擎
 * 
 * 设计原则：
 * - 轻量级，不阻塞主线程
 * - 可配置检查间隔和任务
 * - 支持动态启用/禁用
 * - 错误自动恢复
 */
class HeartbeatEngine {
  private intervalMs: number;
  private timer: NodeJS.Timeout | null = null;
  private running = false;
  private lastCheckAt: number = 0;
  private tasks: Map<string, HeartbeatTask> = new Map();
  private taskStates: Map<string, TaskState> = new Map();

  constructor(config: HeartbeatConfig) {
    this.intervalMs = config.intervalMs || 60000; // 默认 1 分钟
    this.registerDefaultTasks();
  }

  /**
   * 注册默认心跳任务
   */
  private registerDefaultTasks(): void {
    // 服务器健康检查 - 每次心跳都执行
    this.registerTask({
      id: "server-health",
      name: "服务器健康检查",
      priority: 1,
      minIntervalMs: 0, // 每次都执行
      execute: async (context) => {
        return await this.checkServerHealth(context);
      },
    });

    // 配置同步检查 - 每 5 分钟
    this.registerTask({
      id: "config-sync",
      name: "配置同步检查",
      priority: 2,
      minIntervalMs: 5 * 60 * 1000,
      execute: async (context) => {
        return await this.checkConfigSync(context);
      },
    });

    // 会话同步检查 - 每 2 分钟
    this.registerTask({
      id: "session-sync",
      name: "会话同步检查",
      priority: 3,
      minIntervalMs: 2 * 60 * 1000,
      execute: async (context) => {
        return await this.checkSessionSync(context);
      },
    });

    // 后台维护 - 每 10 分钟
    this.registerTask({
      id: "maintenance",
      name: "后台维护",
      priority: 10,
      minIntervalMs: 10 * 60 * 1000,
      execute: async (context) => {
        return await this.runMaintenance(context);
      },
    });

    // 通知检查 - 每次心跳
    this.registerTask({
      id: "notify-check",
      name: "通知检查",
      priority: 5,
      minIntervalMs: 0,
      execute: async (context) => {
        return await this.checkNotifications(context);
      },
    });
  }

  /**
   * 注册心跳任务
   */
  registerTask(task: HeartbeatTask): void {
    this.tasks.set(task.id, task);
    this.taskStates.set(task.id, {
      lastRunAt: 0,
      lastResult: null,
      errorCount: 0,
    });
  }

  /**
   * 启动心跳
   */
  start(): void {
    if (this.running) return;

    this.running = true;
    this.timer = setInterval(() => {
      this.tick().catch((err) => {
        console.error("[Heartbeat] Tick error:", err);
      });
    }, this.intervalMs);

    // 立即执行一次
    this.tick().catch(console.error);

    console.log(`[Heartbeat] Started with interval ${this.intervalMs}ms`);
  }

  /**
   * 停止心跳
   */
  stop(): void {
    if (this.timer) {
      clearInterval(this.timer);
      this.timer = null;
    }
    this.running = false;
    console.log("[Heartbeat] Stopped");
  }

  /**
   * 执行一次心跳检查
   */
  private async tick(): Promise<HeartbeatResult> {
    const now = Date.now();
    const context: HeartbeatContext = {
      now,
      lastCheckAt: this.lastCheckAt,
      appState: this.getAppState(),
    };

    const results: Record<string, TaskResult> = {};

    // 按优先级排序执行
    const sortedTasks = Array.from(this.tasks.values())
      .sort((a, b) => a.priority - b.priority);

    for (const task of sortedTasks) {
      const state = this.taskStates.get(task.id)!;
      
      // 检查是否需要执行（根据最小间隔）
      if (task.minIntervalMs > 0 && now - state.lastRunAt < task.minIntervalMs) {
        continue;
      }

      try {
        const result = await task.execute(context);
        results[task.id] = result;
        state.lastRunAt = now;
        state.lastResult = result;
        state.errorCount = 0;

        // 如果任务有需要通知的内容
        if (result.notify) {
          this.notifyUI(task.id, result);
        }
      } catch (error) {
        state.errorCount++;
        state.lastResult = { error: String(error) };
        results[task.id] = { error: String(error) };
        console.error(`[Heartbeat] Task ${task.id} error:`, error);
      }
    }

    this.lastCheckAt = now;

    return {
      timestamp: now,
      results,
    };
  }

  /**
   * 获取应用状态
   */
  private getAppState(): AppState {
    // 返回当前应用状态（窗口是否可见、是否空闲等）
    return {
      windowVisible: true, // 从 BrowserWindow 获取
      idle: false, // 从 powerMonitor 获取
      online: navigator.onLine,
    };
  }

  /**
   * 通知 UI
   */
  private notifyUI(taskId: string, result: TaskResult): void {
    // 通过 IPC 或 EventEmitter 通知渲染进程
    const { BrowserWindow } = require("electron");
    const win = BrowserWindow.getAllWindows()[0];
    if (win) {
      win.webContents.send("heartbeat:notify", { taskId, result });
    }
  }

  /**
   * 服务器健康检查
   */
  private async checkServerHealth(context: HeartbeatContext): Promise<TaskResult> {
    const qimingClient = getQimingClient();
    
    if (!qimingClient || !qimingClient.isConnected()) {
      return { 
        status: "disconnected",
        notify: { type: "warning", message: "服务器连接已断开" },
      };
    }

    try {
      const start = Date.now();
      const health = await qimingClient.request("GET", "/api/health");
      const latency = Date.now() - start;

      return {
        status: "connected",
        latency,
        version: health.version,
      };
    } catch (error) {
      return {
        status: "error",
        error: String(error),
        notify: { type: "error", message: "服务器健康检查失败" },
      };
    }
  }

  /**
   * 配置同步检查
   */
  private async checkConfigSync(context: HeartbeatContext): Promise<TaskResult> {
    const syncService = getQimingSyncService();
    const status = syncService.getSyncStatus();

    // 检查是否有需要同步的配置
    const pendingChanges = status.pendingChanges;
    if (pendingChanges > 0) {
      // 触发同步
      await syncService.syncAll();
      return {
        status: "synced",
        changes: pendingChanges,
        notify: { type: "info", message: `已同步 ${pendingChanges} 个配置变更` },
      };
    }

    return { status: "uptodate" };
  }

  /**
   * 会话同步检查
   */
  private async checkSessionSync(context: HeartbeatContext): Promise<TaskResult> {
    const chatEngine = getChatEngine();
    const pendingMessages = chatEngine.getPendingMessages();

    if (pendingMessages.length > 0) {
      await chatEngine.syncMessages();
      return {
        status: "synced",
        count: pendingMessages.length,
      };
    }

    return { status: "uptodate" };
  }

  /**
   * 后台维护
   */
  private async runMaintenance(context: HeartbeatContext): Promise<TaskResult> {
    const tasks: string[] = [];

    // 1. 清理过期缓存
    await this.cleanupExpiredCache();
    tasks.push("cache-cleanup");

    // 2. 清理临时文件
    await this.cleanupTempFiles();
    tasks.push("temp-cleanup");

    // 3. 检查更新
    if (context.appState.idle) {
      await this.checkForUpdates();
      tasks.push("update-check");
    }

    return { status: "done", tasks };
  }

  /**
   * 通知检查
   */
  private async checkNotifications(context: HeartbeatContext): Promise<TaskResult> {
    const qimingClient = getQimingClient();
    
    if (!qimingClient?.isConnected()) {
      return { status: "skipped" };
    }

    try {
      const notifications = await qimingClient.request(
        "GET",
        "/api/notifications/pending",
      );

      if (notifications.length > 0) {
        return {
          status: "found",
          count: notifications.length,
          notify: {
            type: "notification",
            data: notifications,
          },
        };
      }

      return { status: "empty" };
    } catch (error) {
      return { status: "error", error: String(error) };
    }
  }

  /**
   * 获取心跳状态
   */
  getStatus(): HeartbeatStatus {
    return {
      running: this.running,
      intervalMs: this.intervalMs,
      lastCheckAt: this.lastCheckAt,
      tasks: Object.fromEntries(this.taskStates),
    };
  }

  /**
   * 动态调整间隔
   */
  setInterval(ms: number): void {
    this.intervalMs = ms;
    if (this.running) {
      this.stop();
      this.start();
    }
  }
}

// ==================== 类型定义 ====================

interface HeartbeatConfig {
  intervalMs?: number; // 心跳间隔，默认 60000 (1分钟)
  tasks?: HeartbeatTask[]; // 自定义任务
}

interface HeartbeatTask {
  id: string;
  name: string;
  priority: number; // 执行优先级，数字越小越先执行
  minIntervalMs: number; // 最小执行间隔，0 表示每次都执行
  execute: (context: HeartbeatContext) => Promise<TaskResult>;
}

interface HeartbeatContext {
  now: number;
  lastCheckAt: number;
  appState: AppState;
}

interface AppState {
  windowVisible: boolean;
  idle: boolean;
  online: boolean;
}

interface TaskState {
  lastRunAt: number;
  lastResult: TaskResult | null;
  errorCount: number;
}

interface TaskResult {
  status?: string;
  error?: string;
  notify?: NotifyPayload;
  [key: string]: any;
}

interface NotifyPayload {
  type: "info" | "warning" | "error" | "notification";
  message?: string;
  data?: any;
}

interface HeartbeatResult {
  timestamp: number;
  results: Record<string, TaskResult>;
}

interface HeartbeatStatus {
  running: boolean;
  intervalMs: number;
  lastCheckAt: number;
  tasks: Record<string, TaskState>;
}
```

### 2.4 Heartbeat 与 UI 交互

```typescript
// Main Process
ipcMain.handle("heartbeat:getStatus", () => {
  return heartbeatEngine.getStatus();
});

ipcMain.handle("heartbeat:setInterval", (_, ms: number) => {
  heartbeatEngine.setInterval(ms);
  return { success: true };
});

// Renderer Process
ipcRenderer.on("heartbeat:notify", (_, { taskId, result }) => {
  if (result.notify) {
    switch (result.notify.type) {
      case "warning":
        showToast.warning(result.notify.message);
        break;
      case "error":
        showToast.error(result.notify.message);
        break;
      case "info":
        showToast.info(result.notify.message);
        break;
      case "notification":
        showNotifications(result.notify.data);
        break;
    }
  }
});
```

---

## 三、Cron Jobs（定时任务）

### 3.1 设计目标

Cron Jobs 是**用户定义的定时任务**，用于：

1. **定时提醒** - "每天 9:00 提醒我开会"
2. **定时报告** - "每周一 8:00 发送周报"
3. **自动化任务** - "每小时检查一次某个服务状态"
4. **与 Agent 结合** - "每天 18:00 让 Agent 总结今天的工作"

### 3.2 架构设计

```
┌────────────────────────────────────────────────────────────────────────┐
│                      Cron Jobs 架构                                     │
├────────────────────────────────────────────────────────────────────────┤
│                                                                        │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │  CronScheduler (调度引擎)                                         │  │
│  │                                                                   │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │  │
│  │  │ cron-parser │  │ job-queue   │  │ executor    │              │  │
│  │  │ 解析表达式   │  │ 任务队列    │  │ 执行器      │              │  │
│  │  └─────────────┘  └─────────────┘  └─────────────┘              │  │
│  │                                                                   │  │
│  │  - 支持 cron 表达式                                               │  │
│  │  - 支持一次性任务 (at)                                             │  │
│  │  - 持久化到 SQLite                                                │  │
│  │  - 错过任务恢复 (应用关闭期间)                                     │  │
│  └──────────────────────────────────────────────────────────────────┘  │
│                                 │                                      │
│                                 ▼                                      │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │  Job Types (任务类型)                                             │  │
│  │                                                                   │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │  │
│  │  │ Reminder    │  │ Agent Task  │  │ Custom      │              │  │
│  │  │ 提醒任务    │  │ Agent 任务  │  │ 自定义任务  │              │  │
│  │  └─────────────┘  └─────────────┘  └─────────────┘              │  │
│  │                                                                   │  │
│  │  ┌─────────────┐  ┌─────────────┐                               │  │
│  │  │ Webhook     │  │ Script      │                               │  │
│  │  │ HTTP 回调   │  │ 脚本执行    │                               │  │
│  │  └─────────────┘  └─────────────┘                               │  │
│  └──────────────────────────────────────────────────────────────────┘  │
│                                 │                                      │
│                                 ▼                                      │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │  Server Sync (服务器同步)                                         │  │
│  │                                                                   │  │
│  │  - 从服务器同步定时任务定义                                        │  │
│  │  - 任务执行结果推送到服务器                                        │  │
│  │  - 支持多设备任务同步                                              │  │
│  └──────────────────────────────────────────────────────────────────┘  │
│                                                                        │
└────────────────────────────────────────────────────────────────────────┘
```

### 3.3 CronScheduler 实现

```typescript
import { CronJob } from "cron";
import { getDb } from "../db";

/**
 * Cron 调度器
 * 
 * 设计原则：
 * - 支持 cron 表达式和一次性任务
 * - 持久化存储，应用重启后恢复
 * - 错过任务自动执行（可配置）
 * - 与服务器同步
 */
class CronScheduler {
  private jobs: Map<string, CronJob> = new Map();
  private db: Database;

  constructor() {
    this.db = getDb();
    this.initDb();
    this.loadJobsFromDb();
  }

  /**
   * 初始化数据库表
   */
  private initDb(): void {
    this.db.exec(`
      CREATE TABLE IF NOT EXISTS cron_jobs (
        id TEXT PRIMARY KEY,
        name TEXT NOT NULL,
        description TEXT,
        cron_expression TEXT,
        run_at TEXT,           -- 一次性任务的执行时间 (ISO 8601)
        timezone TEXT DEFAULT 'Asia/Shanghai',
        job_type TEXT NOT NULL, -- reminder, agent, webhook, script, custom
        job_config TEXT,        -- JSON 配置
        enabled INTEGER DEFAULT 1,
        last_run_at INTEGER,
        next_run_at INTEGER,
        created_at INTEGER,
        updated_at INTEGER,
        synced_to_server INTEGER DEFAULT 0,
        server_job_id TEXT
      );

      CREATE INDEX IF NOT EXISTS idx_cron_jobs_next_run ON cron_jobs(next_run_at);
      CREATE INDEX IF NOT EXISTS idx_cron_jobs_enabled ON cron_jobs(enabled);
    `);
  }

  /**
   * 从数据库加载任务
   */
  private loadJobsFromDb(): void {
    const jobs = this.db.prepare(`
      SELECT * FROM cron_jobs WHERE enabled = 1
    `).all() as CronJobRecord[];

    for (const job of jobs) {
      this.scheduleJob(job);
    }

    // 检查错过的任务
    this.recoverMissedJobs();
  }

  /**
   * 创建定时任务
   */
  async createJob(input: CreateJobInput): Promise<CronJobRecord> {
    const id = input.id || this.generateId();
    const now = Date.now();

    // 计算下次执行时间
    const nextRunAt = this.calculateNextRun(input);

    const job: CronJobRecord = {
      id,
      name: input.name,
      description: input.description,
      cron_expression: input.cronExpression || null,
      run_at: input.runAt ? new Date(input.runAt).toISOString() : null,
      timezone: input.timezone || "Asia/Shanghai",
      job_type: input.jobType,
      job_config: JSON.stringify(input.jobConfig),
      enabled: 1,
      last_run_at: null,
      next_run_at: nextRunAt?.getTime() || null,
      created_at: now,
      updated_at: now,
      synced_to_server: 0,
      server_job_id: null,
    };

    // 保存到数据库
    this.db.prepare(`
      INSERT INTO cron_jobs (
        id, name, description, cron_expression, run_at, timezone,
        job_type, job_config, enabled, last_run_at, next_run_at,
        created_at, updated_at, synced_to_server, server_job_id
      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
    `).run(
      job.id, job.name, job.description, job.cron_expression, job.run_at,
      job.timezone, job.job_type, job.job_config, job.enabled, job.last_run_at,
      job.next_run_at, job.created_at, job.updated_at, job.synced_to_server,
      job.server_job_id
    );

    // 如果启用，加入调度
    if (job.enabled) {
      this.scheduleJob(job);
    }

    // 同步到服务器
    this.syncJobToServer(job);

    return job;
  }

  /**
   * 更新定时任务
   */
  async updateJob(id: string, updates: UpdateJobInput): Promise<CronJobRecord | null> {
    const existing = this.db.prepare("SELECT * FROM cron_jobs WHERE id = ?").get(id) as CronJobRecord;
    if (!existing) return null;

    // 停止旧的调度
    this.stopJob(id);

    const now = Date.now();
    const updated = { ...existing, ...updates, updated_at: now };

    // 重新计算下次执行时间
    if (updates.cronExpression !== undefined || updates.runAt !== undefined) {
      updated.next_run_at = this.calculateNextRun({
        cronExpression: updated.cron_expression,
        runAt: updated.run_at,
      })?.getTime() || null;
    }

    // 更新数据库
    this.db.prepare(`
      UPDATE cron_jobs SET
        name = ?, description = ?, cron_expression = ?, run_at = ?,
        timezone = ?, job_type = ?, job_config = ?, enabled = ?,
        last_run_at = ?, next_run_at = ?, updated_at = ?, synced_to_server = 0
      WHERE id = ?
    `).run(
      updated.name, updated.description, updated.cron_expression, updated.run_at,
      updated.timezone, updated.job_type, updated.job_config, updated.enabled,
      updated.last_run_at, updated.next_run_at, updated.updated_at, id
    );

    // 如果启用，重新调度
    if (updated.enabled) {
      this.scheduleJob(updated);
    }

    // 同步到服务器
    this.syncJobToServer(updated);

    return updated;
  }

  /**
   * 删除定时任务
   */
  async deleteJob(id: string): Promise<boolean> {
    // 停止调度
    this.stopJob(id);

    // 从数据库删除
    const result = this.db.prepare("DELETE FROM cron_jobs WHERE id = ?").run(id);

    // 通知服务器
    this.deleteJobFromServer(id);

    return result.changes > 0;
  }

  /**
   * 调度任务
   */
  private scheduleJob(job: CronJobRecord): void {
    // 如果已在调度中，先停止
    this.stopJob(job.id);

    const jobConfig = JSON.parse(job.job_config || "{}");

    if (job.cron_expression) {
      // 周期性任务
      const cronJob = new CronJob(
        job.cron_expression,
        () => this.executeJob(job),
        null,
        true, // start
        job.timezone
      );
      this.jobs.set(job.id, cronJob);
    } else if (job.run_at) {
      // 一次性任务
      const runAt = new Date(job.run_at);
      const delay = runAt.getTime() - Date.now();

      if (delay > 0) {
        const timeout = setTimeout(() => {
          this.executeJob(job);
          // 执行后删除一次性任务
          this.deleteJob(job.id);
        }, delay);
        this.jobs.set(job.id, timeout as any);
      }
    }
  }

  /**
   * 停止任务
   */
  private stopJob(id: string): void {
    const job = this.jobs.get(id);
    if (job) {
      if (job instanceof CronJob) {
        job.stop();
      } else {
        clearTimeout(job);
      }
      this.jobs.delete(id);
    }
  }

  /**
   * 执行任务
   */
  private async executeJob(job: CronJobRecord): Promise<JobResult> {
    const jobConfig = JSON.parse(job.job_config || "{}");
    const startTime = Date.now();

    try {
      let result: any;

      switch (job.job_type) {
        case "reminder":
          result = await this.executeReminder(job, jobConfig);
          break;
        case "agent":
          result = await this.executeAgentTask(job, jobConfig);
          break;
        case "webhook":
          result = await this.executeWebhook(job, jobConfig);
          break;
        case "script":
          result = await this.executeScript(job, jobConfig);
          break;
        case "custom":
          result = await this.executeCustom(job, jobConfig);
          break;
        default:
          throw new Error(`Unknown job type: ${job.job_type}`);
      }

      const executionTime = Date.now() - startTime;

      // 更新执行记录
      this.db.prepare(`
        UPDATE cron_jobs SET
          last_run_at = ?,
          next_run_at = ?,
          updated_at = ?
        WHERE id = ?
      `).run(
        startTime,
        this.calculateNextRun({ cronExpression: job.cron_expression })?.getTime() || null,
        Date.now(),
        job.id
      );

      // 推送执行结果到服务器
      this.pushJobResultToServer(job.id, {
        success: true,
        result,
        executionTime,
        executedAt: startTime,
      });

      return { success: true, result, executionTime };
    } catch (error) {
      const executionTime = Date.now() - startTime;

      // 推送错误结果到服务器
      this.pushJobResultToServer(job.id, {
        success: false,
        error: String(error),
        executionTime,
        executedAt: startTime,
      });

      return { success: false, error: String(error), executionTime };
    }
  }

  /**
   * 执行提醒任务
   */
  private async executeReminder(job: CronJobRecord, config: ReminderConfig): Promise<any> {
    const { title, message, sound, actions } = config;

    // 显示系统通知
    const { Notification } = require("electron");
    new Notification({
      title,
      body: message,
      sound: sound !== false,
      actions: actions?.map((a: any) => ({ type: "button", text: a.label })),
    }).show();

    return { notified: true, title };
  }

  /**
   * 执行 Agent 任务
   */
  private async executeAgentTask(job: CronJobRecord, config: AgentTaskConfig): Promise<any> {
    const { agentId, prompt, context } = config;

    // 获取 Agent 引擎
    const chatEngine = getChatEngine();
    
    // 创建会话并执行
    const session = await chatEngine.createSession({
      agentId,
      title: `[定时任务] ${job.name}`,
    });

    const response = await chatEngine.sendMessage(session.id, prompt, {
      context,
    });

    return {
      sessionId: session.id,
      response: response.content,
    };
  }

  /**
   * 执行 Webhook
   */
  private async executeWebhook(job: CronJobRecord, config: WebhookConfig): Promise<any> {
    const { url, method = "POST", headers, body } = config;

    const response = await fetch(url, {
      method,
      headers: {
        "Content-Type": "application/json",
        ...headers,
      },
      body: body ? JSON.stringify(body) : undefined,
    });

    return {
      status: response.status,
      data: await response.text(),
    };
  }

  /**
   * 执行脚本
   */
  private async executeScript(job: CronJobRecord, config: ScriptConfig): Promise<any> {
    const { language, code, timeout = 30000 } = config;

    // 根据语言选择执行器
    const { spawn } = require("child_process");
    
    let command: string;
    let args: string[];

    switch (language) {
      case "bash":
        command = "bash";
        args = ["-c", code];
        break;
      case "node":
        command = "node";
        args = ["-e", code];
        break;
      case "python":
        command = "python3";
        args = ["-c", code];
        break;
      default:
        throw new Error(`Unsupported language: ${language}`);
    }

    return new Promise((resolve, reject) => {
      const proc = spawn(command, args, { timeout });
      let stdout = "";
      let stderr = "";

      proc.stdout.on("data", (data: Buffer) => { stdout += data.toString(); });
      proc.stderr.on("data", (data: Buffer) => { stderr += data.toString(); });

      proc.on("close", (code: number) => {
        resolve({ exitCode: code, stdout, stderr });
      });

      proc.on("error", reject);
    });
  }

  /**
   * 执行自定义任务
   */
  private async executeCustom(job: CronJobRecord, config: any): Promise<any> {
    // 通过事件系统让外部处理器执行
    const handlers = this.customHandlers.get(job.job_type);
    if (handlers) {
      for (const handler of handlers) {
        await handler(job, config);
      }
    }
    return { handled: true };
  }

  /**
   * 计算下次执行时间
   */
  private calculateNextRun(input: { cronExpression?: string; runAt?: string | Date }): Date | null {
    if (input.cronExpression) {
      const cronJob = new CronJob(input.cronExpression, () => {}, null, false);
      return cronJob.nextDate().toJSDate();
    }
    if (input.runAt) {
      return new Date(input.runAt);
    }
    return null;
  }

  /**
   * 恢复错过的任务
   */
  private recoverMissedJobs(): void {
    const now = Date.now();
    const missedJobs = this.db.prepare(`
      SELECT * FROM cron_jobs 
      WHERE enabled = 1 AND next_run_at IS NOT NULL AND next_run_at < ?
    `).all(now) as CronJobRecord[];

    for (const job of missedJobs) {
      console.log(`[CronScheduler] Recovering missed job: ${job.name}`);
      this.executeJob(job).catch(console.error);
    }
  }

  /**
   * 从服务器同步任务
   */
  async syncFromServer(): Promise<SyncResult> {
    const qimingClient = getQimingClient();
    if (!qimingClient?.isConnected()) {
      return { success: false, pulled: 0, pushed: 0, conflicts: [], error: "Not connected" };
    }

    // 获取服务器上的任务列表
    const serverJobs = await qimingClient.request(
      "GET",
      "/api/scheduler/jobs",
    );

    let pulled = 0;
    let pushed = 0;
    const conflicts: SyncConflict[] = [];

    for (const serverJob of serverJobs) {
      const localJob = this.db.prepare(
        "SELECT * FROM cron_jobs WHERE server_job_id = ?"
      ).get(serverJob.id) as CronJobRecord | undefined;

      if (!localJob) {
        // 服务器有，本地没有 → 创建
        await this.createJobFromServer(serverJob);
        pulled++;
      } else if (localJob.updated_at > serverJob.updatedAt) {
        // 本地更新 → 推送到服务器
        await this.syncJobToServer(localJob);
        pushed++;
      } else if (localJob.updated_at < serverJob.updatedAt) {
        // 服务器更新 → 更新本地
        await this.updateJobFromServer(localJob.id, serverJob);
        pulled++;
      }
    }

    return { success: true, pulled, pushed, conflicts };
  }

  /**
   * 获取所有任务
   */
  getJobs(filter?: JobFilter): CronJobRecord[] {
    let sql = "SELECT * FROM cron_jobs";
    const params: any[] = [];

    if (filter?.enabled !== undefined) {
      sql += " WHERE enabled = ?";
      params.push(filter.enabled ? 1 : 0);
    }

    return this.db.prepare(sql).all(...params) as CronJobRecord[];
  }

  /**
   * 获取单个任务
   */
  getJob(id: string): CronJobRecord | null {
    return this.db.prepare("SELECT * FROM cron_jobs WHERE id = ?").get(id) as CronJobRecord | null;
  }

  /**
   * 手动触发任务
   */
  async triggerJob(id: string): Promise<JobResult> {
    const job = this.getJob(id);
    if (!job) {
      throw new Error(`Job ${id} not found`);
    }
    return this.executeJob(job);
  }

  private generateId(): string {
    return `job_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
  }
}

// ==================== 类型定义 ====================

interface CronJobRecord {
  id: string;
  name: string;
  description: string | null;
  cron_expression: string | null;
  run_at: string | null;
  timezone: string;
  job_type: "reminder" | "agent" | "webhook" | "script" | "custom";
  job_config: string;
  enabled: number;
  last_run_at: number | null;
  next_run_at: number | null;
  created_at: number;
  updated_at: number;
  synced_to_server: number;
  server_job_id: string | null;
}

interface CreateJobInput {
  id?: string;
  name: string;
  description?: string;
  cronExpression?: string; // cron 表达式
  runAt?: string | Date; // 一次性任务执行时间
  timezone?: string;
  jobType: CronJobRecord["job_type"];
  jobConfig: ReminderConfig | AgentTaskConfig | WebhookConfig | ScriptConfig | any;
}

interface UpdateJobInput {
  name?: string;
  description?: string;
  cronExpression?: string;
  runAt?: string | Date;
  timezone?: string;
  jobConfig?: any;
  enabled?: boolean;
}

interface ReminderConfig {
  title: string;
  message: string;
  sound?: boolean;
  actions?: { label: string; action: string }[];
}

interface AgentTaskConfig {
  agentId: number;
  prompt: string;
  context?: Record<string, any>;
}

interface WebhookConfig {
  url: string;
  method?: "GET" | "POST" | "PUT" | "DELETE";
  headers?: Record<string, string>;
  body?: any;
}

interface ScriptConfig {
  language: "bash" | "node" | "python";
  code: string;
  timeout?: number;
}

interface JobResult {
  success: boolean;
  result?: any;
  error?: string;
  executionTime: number;
}

interface JobFilter {
  enabled?: boolean;
  type?: string;
}
```

### 3.4 IPC 接口

```typescript
// Cron Scheduler IPC
'cron:list'           → CronJobRecord[]       // 获取任务列表
'cron:get'            → CronJobRecord         // 获取单个任务
'cron:create'         → CronJobRecord         // 创建任务
'cron:update'         → CronJobRecord         // 更新任务
'cron:delete'         → { success: boolean }  // 删除任务
'cron:trigger'        → JobResult             // 手动触发
'cron:sync'           → SyncResult            // 从服务器同步
'cron:status'         → SchedulerStatus       // 调度器状态
```

---

## 四、Heartbeat vs Cron 对比

| 特性 | Heartbeat | Cron Jobs |
|------|-----------|-----------|
| **触发方式** | 系统自动，固定间隔 | 用户定义，cron 表达式 |
| **用途** | 健康检查、后台维护、状态同步 | 定时提醒、定时任务、自动化 |
| **任务类型** | 预定义的检查任务 | 用户创建的任意任务 |
| **持久化** | 无需（状态在内存） | 需要（SQLite 持久化） |
| **服务器同步** | 状态同步 | 任务定义 + 执行结果同步 |
| **错过处理** | 跳过，等下次 | 可配置恢复执行 |
| **UI 控制** | 可调整间隔 | 完整 CRUD |

---

## 五、与服务器同步

### 5.1 Heartbeat 同步

```typescript
// 心跳检查时，同步状态到服务器
interface HeartbeatSyncPayload {
  timestamp: number;
  clientId: string;
  status: {
    serverHealth: "connected" | "disconnected" | "error";
    lastSyncAt: number;
    pendingChanges: number;
    activeSessions: number;
  };
}

// 服务器可选择性推送通知
// /api/heartbeat POST
```

### 5.2 Cron Jobs 同步

```typescript
// ==================== 服务器已有 API ====================
// POST /api/agent/task/create    // 创建定时会话
// POST /api/agent/task/update    // 更新定时会话
// POST /api/agent/task/list      // 查询定时会话列表
// POST /api/agent/task/cancel/:id // 取消定时会话
// GET  /api/agent/task/cron/list // 可选定时范围
// GET  /api/task/cron/list       // 可选定时范围 - 任务

// ==================== 客户端同步策略 ====================

/**
 * CronSyncAdapter - 与服务器定时任务同步
 * 
 * 复用服务器已有的定时任务 API，客户端提供：
 * 1. 任务定义的本地缓存和离线查看
 * 2. 任务执行结果的本地记录
 * 3. 更丰富的任务类型支持（提醒、脚本等）
 */
class CronSyncAdapter {
  constructor(
    private qimingClient: QimingApiClient,
    private cronScheduler: CronScheduler,
  ) {}

  /**
   * 从服务器同步定时会话任务
   */
  async syncFromServer(agentId?: number): Promise<SyncResult> {
    // 1. 获取服务器定时任务列表
    const serverTasks = await this.qimingClient.request(
      "POST",
      "/api/agent/task/list",
      {
        agentId,
        taskStatus: "EXECUTING", // 获取执行中的任务
      },
    );

    let pulled = 0;
    let pushed = 0;

    // 2. 同步到本地
    for (const serverTask of serverTasks) {
      const localTask = this.cronScheduler.getJob(
        this.getLocalJobId(serverTask.id),
      );

      if (!localTask) {
        // 服务器有，本地没有 → 创建本地任务
        await this.cronScheduler.createJob({
          id: this.getLocalJobId(serverTask.id),
          name: serverTask.topic,
          description: serverTask.summary,
          cronExpression: serverTask.taskCron,
          jobType: "agent",
          jobConfig: {
            agentId: serverTask.agentId,
            conversationId: serverTask.id,
            topic: serverTask.topic,
            summary: serverTask.summary,
          },
          serverJobId: String(serverTask.taskId),
        });
        pulled++;
      }
    }

    // 3. 推送本地新增的任务到服务器
    const localOnly = this.cronScheduler.getJobs({ synced: false });
    for (const local of localOnly) {
      if (local.job_type === "agent") {
        // 只推送 Agent 类型任务
        await this.qimingClient.request("POST", "/api/agent/task/create", {
          agentId: local.job_config.agentId,
          topic: local.name,
          summary: local.description,
          taskCron: local.cron_expression,
        });
        pushed++;
      }
    }

    return { success: true, pulled, pushed, conflicts: [] };
  }

  /**
   * 获取服务器支持的 cron 预设
   */
  async getCronPresets(): Promise<TaskCronInfo[]> {
    return await this.qimingClient.request("GET", "/api/agent/task/cron/list");
  }

  /**
   * 创建定时会话任务（直接调用服务器 API）
   */
  async createServerTask(input: CreateTimedConversationTaskDto): Promise<TimedConversationTaskInfo> {
    const result = await this.qimingClient.request(
      "POST",
      "/api/agent/task/create",
      input,
    );

    // 同时创建本地任务用于缓存
    await this.cronScheduler.createJob({
      id: this.getLocalJobId(result.id),
      name: input.topic,
      description: input.summary,
      cronExpression: input.taskCron,
      jobType: "agent",
      jobConfig: {
        agentId: input.agentId,
        conversationId: result.id,
        topic: input.topic,
        summary: input.summary,
      },
      serverJobId: result.taskId,
    });

    return result;
  }

  /**
   * 取消定时会话任务
   */
  async cancelServerTask(conversationId: number): Promise<void> {
    await this.qimingClient.request(
      "POST",
      `/api/agent/task/cancel/${conversationId}`,
    );

    // 同时删除本地任务
    this.cronScheduler.deleteJob(this.getLocalJobId(conversationId));
  }

  private getLocalJobId(serverId: number): string {
    return `server_task_${serverId}`;
  }
}

// ==================== 类型定义（来自服务器）====================

interface TaskCronInfo {
  typeName: string; // 类型：每天/每周/每月
  items: TaskCronItemDto[];
}

interface TaskCronItemDto {
  cron: string;  // cron 表达式
  desc: string;  // 描述
}

interface CreateTimedConversationTaskDto {
  agentId: number;
  devMode?: boolean;
  id?: number;
  summary: string;   // 任务内容
  taskCron: string;  // cron 表达式
  topic: string;     // 任务主题
}

interface TimedConversationTaskInfo {
  id?: number;
  agentId?: number;
  agent?: AgentDetailDto;
  topic?: string;
  summary?: string;
  taskCron?: string;
  taskCronDesc?: string;
  taskId?: string;
  taskStatus?: TaskStatus;
  created?: string;
  modified?: string;
}
```

---

## 六、UI 设计

### Heartbeat 状态页

```
┌─ 系统状态 ────────────────────────────────────────────────────────────┐
│                                                                       │
│  心跳间隔: 1 分钟                                    [调整] [暂停]     │
│  上次检查: 30 秒前                                                    │
│                                                                       │
│  ── 检查任务状态 ──────────────────────────────────────────────────── │
│                                                                       │
│  ✓ 服务器健康检查     已连接 · 延迟 45ms · 版本 2.1.0                 │
│  ✓ 配置同步检查       已同步 · 无待同步变更                           │
│  ✓ 会话同步检查       已同步 · 0 条待同步消息                         │
│  ○ 后台维护           等待中 · 下次执行: 5 分钟后                     │
│  ✓ 通知检查           无新通知                                        │
│                                                                       │
└───────────────────────────────────────────────────────────────────────┘
```

### Cron Jobs 管理页

```
┌─ 定时任务 ────────────────────────────────────────────────────────────┐
│                                                                       │
│  [+ 创建任务]  [从服务器同步]                        共 5 个任务       │
│                                                                       │
│  ── 任务列表 ──────────────────────────────────────────────────────── │
│                                                                       │
│  ☑ 早会提醒          每天 09:00      提醒     [编辑] [删除] [立即执行] │
│     "记得参加每日早会"                                                 │
│                                                                       │
│  ☑ 周报生成          每周一 18:00    Agent   [编辑] [删除] [立即执行]  │
│     "请生成本周工作总结"                                               │
│                                                                       │
│  ☑ 服务健康检查      每小时          Webhook [编辑] [删除] [立即执行]  │
│     POST https://api.example.com/health                              │
│                                                                       │
│  ☐ 日志清理          每天 00:00      脚本    [编辑] [删除] [立即执行]  │
│     ✗ 已禁用                                                          │
│                                                                       │
│  ── 创建/编辑任务 ────────────────────────────────────────────────────│
│                                                                       │
│  名称:    [________________]                                         │
│  类型:    ○ 提醒  ○ Agent 任务  ○ Webhook  ○ 脚本                     │
│                                                                       │
│  ── 提醒配置 ──────────────────────                                   │
│  标题:    [________________]                                         │
│  内容:    [________________]                                         │
│  ☑ 播放提示音                                                         │
│                                                                       │
│  ── 调度时间 ──────────────────────                                   │
│  ○ 周期性:  [选择预设: 每天/每周/每月/自定义 cron]                     │
│           [0 9 * * *]  预览: 每天 09:00                               │
│                                                                       │
│  ○ 一次性: [选择日期时间: 2026-03-10 14:30]                           │
│                                                                       │
│  时区:    Asia/Shanghai                                               │
│                                                                       │
│  [取消]  [保存并同步到服务器]                                          │
│                                                                       │
└───────────────────────────────────────────────────────────────────────┘
```

---

## 相关文档

- [总体架构](./01-ARCHITECTURE.md)
- [会话管理](./04-SESSION-CHAT.md)
- [Channel 多渠道接入](./05-CHANNELS.md)
- [Agent 自我进化](./06-SELF-EVOLUTION.md)