zclaw_openfang/plans/sharded-scribbling-dove.md

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

实现步骤:

// 在 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 保持一致