docs: add self-evolution documentation and fix SOUL.md persistence

- Create 01-identity-evolution.md: Identity system architecture (SOUL.md, USER.md, change proposals, version management) - Create 04-heartbeat-engine.md: Proactive behavior system (heartbeat config, alerts, proactivity levels) - Create 06-context-compaction.md: Context compression system (token management, summarization, information retention) - Update ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md: Add Phase 5 self-evolution UX roadmap - Fix AgentOnboardingWizard: Persist SOUL.md and USER.md after agent creation - Fix llm-service: Add Tauri kernel mode detection for memory system LLM calls - Fix kernel: Kernel config takes priority over agent's persisted model Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-24 00:38:31 +08:00
parent a389082dd4
commit 6c64d704d7
5 changed files with 982 additions and 3 deletions
--- a/docs/features/02-intelligence-layer/04-heartbeat-engine.md
+++ b/docs/features/02-intelligence-layer/04-heartbeat-engine.md
@@ -0,0 +1,274 @@
+# 心跳巡检引擎 (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) - 身份演化