zclaw_openfang/docs/features/02-intelligence-layer/01-identity-evolution.md

# 身份演化系统 (Identity Evolution)

> **成熟度**: L4 - 生产
> **最后更新**: 2026-03-25
> **负责人**: Intelligence Layer Team
> **验证状态**: ✅ 代码已验证
> **后端实现**: Rust (identity.rs) - **90% 完整度**
> **新增组件**: persona_evolver.rs, mesh.rs (待完善)

## 概述

身份演化系统是 ZCLAW 自我进化能力的核心，让 Agent 能够：
1. **定义人格** - 通过 SOUL.md 定义核心特质
2. **演化人格** - 基于对话反思自动改进
3. **版本管理** - 跟踪人格变更历史，支持回滚
4. **变更提案** - 创建待审批的人格变更

---

## 核心概念

### 身份文件 (Identity Files)

每个 Agent 有三个核心身份文件：

| 文件 | 用途 | 示例内容 |
|------|------|----------|
| `soul` (SOUL.md) | Agent 人格定义 | 核心特质、沟通风格、专业领域 |
| `instructions` | 行为指令集 | 执行规则、约束条件 |
| `user_profile` (USER.md) | 用户画像 | 用户偏好、角色、场景 |

### 身份变更提案 (Identity Change Proposal)

```typescript
interface IdentityChangeProposal {
  id: string;
  agent_id: string;
  file: 'soul' | 'instructions' | 'user_profile';
  current_content: string;
  proposed_content: string;
  diff: string;                    // Unified diff
  reason: string;                  // AI 生成的变更原因
  status: 'pending' | 'approved' | 'rejected';
  created_at: string;
}
```

---

## 技术实现

### 核心文件

| 文件 | 用途 |
|------|------|
| `desktop/src/lib/intelligence-client.ts` | 前端身份 API 客户端 |
| `desktop/src/lib/intelligence-backend.ts` | 身份管理后端实现 |
| `desktop/src/lib/personality-presets.ts` | 人格预设和 SOUL.md 生成 |
| `desktop/src/components/AgentOnboardingWizard.tsx` | 引导向导，创建时持久化 SOUL.md |

### API 接口

```typescript
// intelligence-client.ts
identity: {
  // 获取 Agent 的所有身份文件
  get(agentId: string): Promise<IdentityFiles>;

  // 读取单个文件内容
  readFile(agentId: string, file: string): Promise<string>;

  // 更新文件内容（自动创建快照）
  updateFile(agentId: string, file: string, content: string): Promise<void>;

  // 构建完整的人格 Prompt
  buildPrompt(agentId: string, memoryContext?: string): Promise<string>;

  // 变更提案
  proposeChange(proposal: Omit<IdentityChangeProposal, 'id' | 'status' | 'created_at'>): Promise<IdentityChangeProposal>;
  getProposals(): Promise<IdentityChangeProposal[]>;
  approveProposal(proposalId: string): Promise<IdentityFiles>;
  rejectProposal(proposalId: string): Promise<void>;

  // 版本管理
  getSnapshots(agentId: string, limit?: number): Promise<IdentitySnapshot[]>;
  restoreSnapshot(agentId: string, snapshotId: string): Promise<IdentityFiles>;
}
```

### SOUL.md 生成

```typescript
// personality-presets.ts
export function generateSoulContent(config: {
  agentName: string;
  emoji?: string;
  personality?: string;      // professional | friendly | creative | concise
  scenarios?: string[];      // coding, writing, product, data, design...
  communicationStyle?: string;
}): string;
```

生成的 SOUL.md 包含：
- 核心特质（基于人格预设）
- 沟通风格
- 专业领域
- 边界约束
- 语气设定

---

## 数据流

### 创建时持久化

```
AgentOnboardingWizard
    │
    ├── createClone() → 创建 Agent
    │
    ├── generateSoulContent() → 生成 SOUL.md
    │
    ├── generateUserContent() → 生成 USER.md
    │
    └── identity.updateFile() → 持久化到存储
```

### 演化流程

```
对话历史
    │
    ▼
反思引擎 (Reflection Engine)
    │
    ├── 分析对话模式
    │
    ├── 识别人格改进点
    │
    ▼
identity.proposeChange() → 创建变更提案
    │
    ▼
用户审批 UI
    │
    ├── approveProposal() → 应用变更
    │       │
    │       └── 创建快照
    │
    └── rejectProposal() → 丢弃提案
```

---

## 人格预设

| ID | 名称 | 特质 |
|----|------|------|
| `professional` | 专业严谨 | 严谨分析、准确执行、专业术语、结构化输出 |
| `friendly` | 友好亲切 | 热情回应、通俗易懂、主动关怀、耐心解答 |
| `creative` | 创意灵活 | 创新思维、多角度探索、灵活应变、突破常规 |
| `concise` | 简洁高效 | 直击要点、快速响应、高效执行、精炼表达 |

---

## 使用场景

### 场景 1：首次创建 Agent

1. 用户通过 AgentOnboardingWizard 创建 Agent
2. 选择人格预设和使用场景
3. 系统自动生成 SOUL.md 和 USER.md
4. 持久化到身份存储

### 场景 2：基于反思的人格演化

1. Agent 进行多轮对话
2. 反思引擎分析对话模式
3. 发现用户偏好（如"不要那么啰嗦"）
4. 生成人格变更提案
5. 用户审批后更新 SOUL.md

### 场景 3：回滚到之前版本

1. 用户觉得新人格不合适
2. 查看演化历史
3. 选择之前的快照
4. 一键恢复

---

## 集成点

| 组件 | 集成方式 |
|------|----------|
| **RightPanel** | 显示身份文件内容、变更提案 |
| **ReflectionEngine** | 触发人格变更提案 |
| **AutonomyManager** | 审批自主级别下的自动变更 |
| **ChatStore** | 使用 `buildPrompt()` 构建系统提示 |

---

## 限制与未来改进

### 当前限制

1. **前端回滚 UI 未实现** - `getSnapshots()` 和 `restoreSnapshot()` API 存在但无 UI
2. **变更提案通知缺失** - 提案创建后无主动通知用户
3. **Tauri 模式下文件存储** - 当前使用内存存储，重启后丢失

### 新增组件 (2026-03-25)

| 组件 | 位置 | 状态 | 说明 |
|------|------|------|------|
| persona_evolver.rs | `desktop/src-tauri/src/intelligence/` | 🆕 新增 | 人格演进引擎 (待完善) |
| mesh.rs | `desktop/src-tauri/src/intelligence/` | 🆕 新增 | 智能网格 (待完善) |
| pattern_detector.rs | `desktop/src-tauri/src/intelligence/` | 🆕 新增 | 模式检测 (待完善) |
| trigger_evaluator.rs | `desktop/src-tauri/src/intelligence/` | 🆕 新增 | 触发评估 (待完善) |

### 未来改进

1. **文件系统持久化** - 将身份文件写入 `~/.zclaw/agents/{agentId}/`
2. **变更提案通知** - 添加桌面通知或消息提示
3. **人格版本对比** - 可视化 diff 显示变更内容
4. **多人格切换** - 支持同一 Agent 保存多套人格配置
5. **智能网格集成** - 与 mesh.rs 集成实现多 Agent 协作演化

---

## 相关文档

- [00-agent-memory.md](./00-agent-memory.md) - 记忆系统
- [03-reflection-engine.md](./03-reflection-engine.md) - 反思引擎
- [05-autonomy-manager.md](./05-autonomy-manager.md) - 自主授权