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
// 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)

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

### 心跳结果 (HeartbeatResult)

```rust
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 接口 (前端)

```typescript
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 封装)

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

### 生产模式
```typescript
{
  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
}
```

### 自主模式
```typescript
{
  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](./03-reflection-engine.md) - 反思引擎
- [05-autonomy-manager.md](./05-autonomy-manager.md) - 自主授权
- [01-identity-evolution.md](./01-identity-evolution.md) - 身份演化