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)

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

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

### 心跳结果 (HeartbeatResult)

```typescript
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 接口

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

### 后端实现

```typescript
// 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                  │  │
│   │   (人格变更提案)                              │  │
│   └──────────────────────────────────────────────┘  │
│                                                      │
└─────────────────────────────────────────────────────┘
```

---

## 配置示例

### 开发者模式
```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. **前端定时器依赖** - 心跳依赖页面打开，后台时不运行
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) - 身份演化