# ZCLAW 自我进化功能实现计划

> **目标**: 让 ZCLAW 具备 OpenClaw 式的"自我进化"能力，让用户感受到 Agent 能够自我设置人格、持续学习改进。

---

## Context（背景）

### 用户反馈
> "没有 OpenClaw 那样懂得如何对自己进行人格设置，没有那种自我进化的感觉"

### 当前状态分析

**已实现（代码存在但体验不连贯）**：
| 功能 | 文件 | 状态 |
|------|------|------|
| 记忆系统 | `intelligence-client.ts` | ✅ L4 完成 |
| 反思引擎 | `intelligence-backend.ts:312-339` | ✅ L4 完成 |
| 自主授权 | `intelligence-backend.ts:352-433` | ✅ L4 完成 |
| 人格预设 | `personality-presets.ts` | ✅ 4种预设 |
| 引导向导 | `AgentOnboardingWizard.tsx` | ✅ 5步向导 |
| SOUL.md 生成 | `generateSoulContent()` | ⚠️ 只返回字符串，不写入文件 |

**核心问题** ~~（已全部解决 2025-03-24）~~：
1. ~~SOUL.md 生成后**不会写入文件系统**~~ ✅ 已解决
2. ~~反思结果**不会触发人格更新**~~ ✅ 已解决
3. ~~用户**无法审批/回滚人格变更**~~ ✅ 已解决
4. ~~缺少**人格演化历史可视化**~~ ✅ 已解决
5. ~~身份数据重启后丢失~~ ✅ 已解决（添加文件系统持久化）

---

## Part 1: 文档更新

### 1.1 需要创建的文档

| 优先级 | 文档路径 | 内容 |
|--------|----------|------|
| P0 | `docs/features/02-intelligence-layer/01-identity-evolution.md` | 身份演化系统设计 |
| P0 | `docs/features/02-intelligence-layer/04-heartbeat-engine.md` | 心跳巡检机制 |
| P0 | `docs/features/02-intelligence-layer/06-context-compaction.md` | 上下文压缩 |

### 1.2 需要更新的文档

| 优先级 | 文档路径 | 更新内容 |
|--------|----------|----------|
| P0 | `docs/ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md` | Phase 3-4 状态改为"已完成"，添加自我进化 UX 章节 |
| P1 | `docs/features/roadmap.md` | 添加自我进化功能到路线图 |

---

## Part 2: 自我进化功能架构

```
┌─────────────────────────────────────────────────────────────┐
│                    Self-Evolution Flow                       │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   ┌──────────┐    ┌───────────┐    ┌──────────────────┐     │
│   │ 对话历史 │───▶│ 反思引擎  │───▶│ 人格变更提案     │     │
│   │          │    │           │    │ (SOUL.md delta)  │     │
│   └──────────┘    └───────────┘    └────────┬─────────┘     │
│                                              │               │
│                                              ▼               │
│   ┌──────────┐    ┌───────────┐    ┌──────────────────┐     │
│   │ 更新后的 │◀───│ 用户审批  │◀───│ 审批 UI          │     │
│   │ SOUL.md  │    │           │    │ (变更对比)       │     │
│   └──────────┘    └───────────┘    └──────────────────┘     │
│        │                                                     │
│        ▼                                                     │
│   ┌──────────────────────────────────────────────────┐      │
│   │              演化历史                              │      │
│   │  - 时间戳快照                                     │      │
│   │  - 差异可视化                                      │      │
│   │  - 回滚能力                                        │      │
│   └──────────────────────────────────────────────────┘      │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

---

## Part 3: 实现计划

### P0: 立即实现（快速见效） ✅ 已完成

#### P0.1: 连接 Onboarding 到 SOUL.md 持久化 ✅ 已完成

**目标**: 让人格选择真正写入文件

**修改文件**: `desktop/src/components/AgentOnboardingWizard.tsx`

**实现步骤**:
```typescript
// 在 handleSubmit() 中，创建 clone 后：
const soulContent = generateSoulContent({
  agentName: formData.agentName,
  emoji: formData.emoji,
  personality: formData.personality,
  scenarios: formData.scenarios,
});
await intelligenceClient.identity.updateFile(clone.id, 'soul', soulContent);
```

**验证**: 完成引导后检查 `~/.zclaw/agents/{agentId}/SOUL.md` 是否存在

---

#### P0.2: 创建缺失的智能层文档

**目标**: 文档化已实现的功能

**创建文件**:
1. `docs/features/02-intelligence-layer/01-identity-evolution.md`
2. `docs/features/02-intelligence-layer/04-heartbeat-engine.md`
3. `docs/features/02-intelligence-layer/06-context-compaction.md`

---

### P1: 核心自我进化功能 ✅ 已完成

#### P1.1: 人格变更提案 UI ✅ 已完成

**目标**: 展示人格变更供用户审批

**新建文件**:
- `desktop/src/components/IdentityChangeProposal.tsx` - 差异视图 + 接受/拒绝按钮
- `desktop/src/components/EvolutionHistory.tsx` - 变更时间线

**修改文件**:
- `desktop/src/components/RightPanel.tsx` - 添加 'evolution' tab

---

#### P1.2: 连接反思引擎到人格提案 ✅ 已完成

**目标**: 自动生成人格变更建议

**修改文件**:
- `desktop/src/lib/intelligence-backend.ts` - 增强 `reflection.reflect()` 生成提案
- `desktop/src/domains/intelligence/store.ts` - 添加提案状态管理

**实现逻辑**:
1. 反思运行后分析模式
2. 如果模式表明需要人格变更（如"用户偏好简洁回复"）：
   - 生成 SOUL.md 修改建议
   - 调用 `identity.proposeChange()`
3. 通知用户有待审批的提案

---

#### P1.3: 演化历史与回滚 ✅ 已完成

**目标**: 让用户查看和回滚人格变更

**新建文件**:
- `desktop/src/components/PersonalityVersionControl.tsx`

**实现**:
1. 每次 `identity.updateFile()` 前创建快照
2. 存储快照（时间戳 + 原因）
3. UI 显示变更时间线
4. 用户点击"恢复"可回滚

---

### P2: 增强体验 ✅ 已完成

#### P2.1: 主动人格建议 ✅ 已完成

**目标**: Agent 主动建议人格改进

**触发条件**:
- 用户重复纠正（"不要那么啰嗦"）
- 发现新偏好
- 上下文变化（新项目、不同角色）

**实现**: 心跳巡检时检测，达到阈值后排队提案

---

## Part 4: 关键文件清单

| 文件 | 修改类型 | 说明 |
|------|----------|------|
| `desktop/src/components/AgentOnboardingWizard.tsx` | 修改 | 添加 SOUL.md 持久化 |
| `desktop/src/lib/intelligence-client.ts` | 修改 | 确保 identity.updateFile() 正常工作 |
| `desktop/src/lib/intelligence-backend.ts` | 修改 | 反思→人格提案连接 |
| `desktop/src/components/RightPanel.tsx` | 修改 | 添加 evolution tab |
| `desktop/src/components/IdentityChangeProposal.tsx` | 新建 | 人格变更审批 UI |
| `desktop/src/components/EvolutionHistory.tsx` | 新建 | 演化历史时间线 |
| `docs/features/02-intelligence-layer/01-identity-evolution.md` | 新建 | 身份演化文档 |

---

## Part 5: 验证计划

### 用户体验验证

| 场景 | 预期结果 |
|------|----------|
| 完成引导向导 | SOUL.md 创建，包含选定人格 |
| Agent 反思对话 | 生成人格变更提案 |
| 用户批准提案 | SOUL.md 更新，创建快照 |
| 用户查看演化历史 | 显示时间线和差异 |
| 用户点击回滚 | 人格恢复到之前版本 |

### 技术验证

| 测试 | 命令 |
|------|------|
| 类型检查 | `pnpm tsc --noEmit` |
| 单元测试 | `pnpm vitest run` |
| E2E 测试 | `pnpm playwright test --project=tauri` |

---

## 实现优先级总结

| 优先级 | 任务 | 状态 |
|--------|------|------|
| P0.1 | SOUL.md 持久化 | ✅ 已完成 |
| P0.2 | 创建文档 | ✅ 已完成 |
| P1.1 | 人格变更 UI | ✅ 已完成 |
| P1.2 | 反思→人格连接 | ✅ 已完成 |
| P1.3 | 演化历史回滚 | ✅ 已完成 |
| P2.1 | 主动建议 | ✅ 已完成 |
| 额外 | 身份数据持久化 | ✅ 已完成 |
| 额外 | 错误反馈 UI | ✅ 已完成 |
| 额外 | 配置 localStorage 持久化 | ✅ 已完成 |
| 深度分析 | Fallback 反思引擎实现 | ✅ 已完成 |
| 深度分析 | 心跳人格改进检查实现 | ✅ 已完成 |
| 深度分析 | 心跳引擎自动启动 | ✅ 已完成 |
| 深度分析 | Fallback identity localStorage | ✅ 已完成 |
| 深度分析 | 配置默认值统一 | ✅ 已完成 |

**计划状态**: ✅ 全部完成 (2025-03-24)

---

## 深度分析修复记录 (2025-03-24)

### 发现的问题

| 优先级 | 问题 | 描述 |
|--------|------|------|
| CRITICAL | Fallback 反思引擎不产生提案 | `fallbackReflection.reflect()` 返回空数组 |
| HIGH | 心跳人格改进检查是占位符 | `check_personality_improvement()` 返回 None |
| HIGH | 心跳引擎未自动启动 | 需要手动调用 `heartbeat.start()` |
| MEDIUM | Fallback identity 不持久化 | 内存中的 Map，页面刷新后丢失 |
| LOW | 配置默认值不一致 | Rust: `allow_soul_modification: false`, TS: `true` |

### 修复内容

1. **Fallback 反思引擎** (`intelligence-client.ts:403-555`)
   - 实现完整的模式分析逻辑
   - 基于记忆类型、重要性、访问频率生成模式观察
   - 自动生成改进建议和人格变更提案

2. **心跳人格改进检查** (`heartbeat.rs:330-460`)
   - 添加 `CORRECTION_COUNTERS` 全局状态
   - 实现 `record_user_correction()` 公共 API
   - 基于用户纠正阈值触发人格改进建议

3. **心跳引擎自动启动** (`App.tsx:160-170`)
   - 在应用 bootstrap 阶段自动初始化心跳引擎
   - 使用默认配置启动 `zclaw-main` agent

4. **Fallback identity localStorage** (`intelligence-client.ts:558-680`)
   - 添加 `IDENTITY_STORAGE_KEY` 和 `PROPOSALS_STORAGE_KEY`
   - 所有修改操作后自动保存到 localStorage
   - 启动时从 localStorage 加载已保存数据

5. **配置默认值统一** (`reflection.rs:41-51`)
   - Rust `allow_soul_modification` 默认值改为 `true`
   - 与 TypeScript 保持一致