zclaw_openfang/docs/features/02-intelligence-layer/04-heartbeat-engine.md

心跳巡检引擎 (Heartbeat Engine)

成熟度: L4 - 生产 最后更新: 2026-03-24 负责人: Intelligence Layer Team

概述

心跳巡检引擎是 ZCLAW 主动行为的核心，定期执行检查任务：

1. 主动巡检 - 定期检查系统状态、待办事项
2. 智能提醒 - 根据上下文生成提醒
3. 自主触发 - 在自主级别下自动执行操作

---

核心概念

心跳配置 (HeartbeatConfig)

interface HeartbeatConfig {
  enabled: boolean;                    // 是否启用心跳
  interval_minutes: number;            // 心跳间隔（分钟）
  quiet_hours_start: string | null;    // 静默时段开始（如 "22:00"）
  quiet_hours_end: string | null;      // 静默时段结束（如 "08:00"）
  notify_channel: 'ui' | 'desktop' | 'all';  // 通知渠道
  proactivity_level: 'silent' | 'light' | 'standard' | 'autonomous';  // 主动级别
  max_alerts_per_tick: number;         // 每次心跳最大提醒数
}

心跳提醒 (HeartbeatAlert)

interface HeartbeatAlert {
  title: string;                       // 提醒标题
  content: string;                     // 提醒内容
  urgency: 'low' | 'medium' | 'high';  // 紧急程度
  source: string;                      // 来源模块
  timestamp: string;                   // 时间戳
}

心跳结果 (HeartbeatResult)

interface HeartbeatResult {
  status: 'ok' | 'alert';              // 状态
  alerts: HeartbeatAlert[];            // 提醒列表
}

---

主动级别

级别	行为
silent	仅记录日志，不发送通知
light	发送 UI 内通知
standard	发送桌面通知
autonomous	自主执行操作（需用户授权）

---

技术实现

核心文件

文件	用途
desktop/src/lib/intelligence-backend.ts	心跳后端实现
desktop/src/domains/intelligence/store.ts	状态管理
desktop/src/domains/intelligence/types.ts	类型定义

Store 接口

interface IntelligenceStore {
  // 状态
  heartbeatConfig: HeartbeatConfig | null;
  heartbeatHistory: HeartbeatResult[];
  isHeartbeatRunning: boolean;

  // 操作
  initHeartbeat(agentId: string, config?: HeartbeatConfig): Promise<void>;
  startHeartbeat(agentId: string): Promise<void>;
  stopHeartbeat(agentId: string): Promise<void>;
  tickHeartbeat(agentId: string): Promise<HeartbeatResult>;
}

后端实现

// intelligence-backend.ts
export const heartbeat = {
  config: {
    get: async (agentId: string): Promise<HeartbeatConfig> => {...},
    update: async (agentId: string, config: Partial<HeartbeatConfig>): Promise<HeartbeatConfig> => {...},
  },

  start: async (agentId: string): Promise<void> => {...},
  stop: async (agentId: string): Promise<void> => {...},
  tick: async (agentId: string): Promise<HeartbeatResult> => {...},
};

---

心跳巡检任务

每次心跳 tick 执行以下检查：

1. 任务检查

• 检查是否有待办任务 (type=task)
• 检查任务是否到期
• 生成任务提醒

2. 上下文检查

• 检查对话历史长度
• 触发上下文压缩建议
• 检查记忆提取机会

3. 反思检查

• 检查距离上次反思的对话数
• 触发反思引擎
• 生成人格变更提案

4. 系统检查

• 检查 Gateway 连接状态
• 检查 API 配额
• 检查更新可用性

---

使用场景

场景 1：定时任务提醒

心跳 tick (每 30 分钟)
    │
    ├── 检查任务记忆
    │
    ├── 发现到期任务："明天 10 点提醒我开会"
    │
    └── 生成 HeartbeatAlert
            title: "任务提醒"
            content: "10:00 有会议"
            urgency: "medium"

场景 2：反思触发

心跳 tick
    │
    ├── 检查对话数 >= 10
    │
    ├── 距离上次反思 > 1 小时
    │
    └── 触发 ReflectionEngine.reflect()
            │
            └── 生成人格变更提案

场景 3：自主级别下的自动操作

心跳 tick (autonomous 级别)
    │
    ├── 检查用户授权
    │
    ├── 发现可自动执行的任务
    │
    └── 执行操作（如：整理记忆、压缩上下文）

---

与其他组件的集成

┌─────────────────────────────────────────────────────┐
│                    Heartbeat Engine                  │
├─────────────────────────────────────────────────────┤
│                                                      │
│   ┌──────────────┐     ┌──────────────┐             │
│   │ Memory Store │◀────│ 任务检查     │             │
│   └──────────────┘     └──────────────┘             │
│          │                    │                      │
│          │                    ▼                      │
│   ┌──────────────┐     ┌──────────────┐             │
│   │ Reflection   │◀────│ 反思触发     │             │
│   │ Engine       │     └──────────────┘             │
│   └──────────────┘                                   │
│          │                                           │
│          │                                           │
│          ▼                                           │
│   ┌──────────────────────────────────────────────┐  │
│   │           Identity Evolution                  │  │
│   │   (人格变更提案)                              │  │
│   └──────────────────────────────────────────────┘  │
│                                                      │
└─────────────────────────────────────────────────────┘

---

配置示例

开发者模式

{
  enabled: true,
  interval_minutes: 5,
  quiet_hours_start: null,
  quiet_hours_end: null,
  notify_channel: 'ui',
  proactivity_level: 'light',
  max_alerts_per_tick: 3
}

生产模式

{
  enabled: true,
  interval_minutes: 30,
  quiet_hours_start: "22:00",
  quiet_hours_end: "08:00",
  notify_channel: 'all',
  proactivity_level: 'standard',
  max_alerts_per_tick: 5
}

自主模式

{
  enabled: true,
  interval_minutes: 15,
  quiet_hours_start: "23:00",
  quiet_hours_end: "07:00",
  notify_channel: 'desktop',
  proactivity_level: 'autonomous',
  max_alerts_per_tick: 10
}

---

限制与未来改进

当前限制

1. 前端定时器依赖 - 心跳依赖页面打开，后台时不运行
2. 无持久化调度 - 重启后心跳不自动恢复
3. 静默时段实现不完整 - 时区处理可能有问题

未来改进

1. 后台心跳 - 使用 Service Worker 或 Tauri 后台任务
2. 智能间隔调整 - 根据用户活跃度动态调整间隔
3. 云端同步 - 多设备心跳状态同步

---

相关文档

• 03-reflection-engine.md - 反思引擎
• 05-autonomy-manager.md - 自主授权
• 01-identity-evolution.md - 身份演化