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

心跳巡检引擎 (Heartbeat Engine)

成熟度: L4 - 生产 最后更新: 2026-03-24 负责人: Intelligence Layer Team 后端实现: Rust (Phase 2 迁移完成) 验证状态: ✅ 代码已验证

概述

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

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

---

核心概念

心跳配置 (HeartbeatConfig)

---

核心概念

心跳配置 (HeartbeatConfig)

// Rust 后端实现 (heartbeat.rs)
pub struct HeartbeatConfig {
    pub enabled: bool,
    pub interval_minutes: u64,           // 默认 30 分钟
    pub quiet_hours_start: Option<String>, // "22:00" 格式
    pub quiet_hours_end: Option<String>,   // "08:00" 格式
    pub notify_channel: NotifyChannel,    // ui | desktop | all
    pub proactivity_level: ProactivityLevel, // silent | light | standard | autonomous
    pub max_alerts_per_tick: usize,       // 默认 5
}

心跳提醒 (HeartbeatAlert)

pub struct HeartbeatAlert {
    pub title: String,
    pub content: String,
    pub urgency: Urgency,  // low | medium | high
    pub source: String,
    pub timestamp: String,
}

心跳结果 (HeartbeatResult)

pub struct HeartbeatResult {
    pub status: HeartbeatStatus,  // ok | alert
    pub alerts: Vec<HeartbeatAlert>,
    pub checked_items: usize,
    pub timestamp: String,
}

---

主动级别

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

---

技术实现

核心文件

文件	用途
desktop/src-tauri/src/intelligence/heartbeat.rs	Rust 后端实现 (762 行)
desktop/src/lib/intelligence-backend.ts	TypeScript 命令封装
desktop/src/lib/intelligence-client.ts	统一客户端接口

Tauri 命令

命令	说明
heartbeat_init	初始化心跳引擎
heartbeat_start	启动心跳定时器
heartbeat_stop	停止心跳
heartbeat_tick	手动执行一次巡检
heartbeat_get_config	获取当前配置
heartbeat_update_config	更新配置
heartbeat_get_history	获取历史记录

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>;
}

后端 API (TypeScript 封装)

// intelligence-backend.ts
export const heartbeat = {
  init: async (agentId: string, config?: HeartbeatConfig): Promise<void> =>
    invoke('heartbeat_init', { agentId, config }),

  start: async (agentId: string): Promise<void> =>
    invoke('heartbeat_start', { agentId }),

  stop: async (agentId: string): Promise<void> =>
    invoke('heartbeat_stop', { agentId }),

  tick: async (agentId: string): Promise<HeartbeatResult> =>
    invoke('heartbeat_tick', { agentId }),

  getConfig: async (agentId: string): Promise<HeartbeatConfig> =>
    invoke('heartbeat_get_config', { agentId }),

  updateConfig: async (agentId: string, config: HeartbeatConfig): Promise<void> =>
    invoke('heartbeat_update_config', { agentId, config }),

  getHistory: async (agentId: string, limit?: number): Promise<HeartbeatResult[]> =>
    invoke('heartbeat_get_history', { agentId, limit }),
};

---

## 心跳巡检任务

每次心跳 `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 │ │ │ │ (人格变更提案) │ │ │ └──────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────┘

---

## 配置示例

### 开发者模式
```typescript
{
  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. Rust 后台定时器 - 心跳在 Rust tokio 运行时中执行
2. 持久化调度 - 重启后需要重新初始化心跳
3. 静默时段 - 已实现，使用本地时区

未来改进

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

---

相关文档

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