bf6d81f9c6
Some checks failed
CI / Rust Check (push) Has been cancelled
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
style: 统一代码格式和注释风格 docs: 更新多个功能文档的完整度和状态 feat(runtime): 添加路径验证工具支持 fix(pipeline): 改进条件判断和变量解析逻辑 test(types): 为ID类型添加全面测试用例 chore: 更新依赖项和Cargo.lock文件 perf(mcp): 优化MCP协议传输和错误处理
312 lines
8.7 KiB
Markdown
312 lines
8.7 KiB
Markdown
# 心跳巡检引擎 (Heartbeat Engine)
|
||
|
||
> **成熟度**: L4 - 生产
|
||
> **最后更新**: 2026-03-25
|
||
> **负责人**: Intelligence Layer Team
|
||
> **后端实现**: Rust (Phase 2 迁移完成) - **90% 完整度**
|
||
> **验证状态**: ✅ 代码已验证
|
||
> **新增组件**: trigger_evaluator.rs (待完善)
|
||
|
||
## 概述
|
||
|
||
心跳巡检引擎是 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) - 身份演化
|