# Evolution Engine 设计文档

> **日期**: 2026-04-18
> **状态**: Draft
> **目标**: 让 ZCLAW 管家从"记住用户信息"进化到"从交互中自主生成新能力"

## 1. 问题陈述

### 1.1 现状

ZCLAW 在"信息层进化"方面已有基础：

| 能力 | 状态 | 说明 |
|------|------|------|
| 记忆闭环 | ✅ 可用 | 对话→LLM 提取→FTS5+TF-IDF 存储→检索注入 system prompt |
| 经验存储结构 | ✅ 定义完整 | `Experience { pain_pattern, solution_steps, outcome }` |
| 语义路由 | ✅ 三层架构 | TF-IDF + Embedding + LLM fallback |
| 技能 CRUD API | ✅ 就绪 | `create_skill` / `update_skill` / `delete_skill` |
| Pipeline DAG | ✅ 可执行 | 并行/串行/条件分支，16 个 YAML 模板 |
| 轨迹记录 | ✅ 可用 | TrajectoryRecorder 记录 UserRequest/ToolExecution/LlmGeneration |

### 1.2 核心缺口

系统在"能力层进化"方面完全空白：

| 缺口 | 影响 |
|------|------|
| 没有从对话自动生成技能 | 用户解决了问题，系统不会记住"怎么解决的"并固化成可复用技能 |
| Experience 是空壳 | 结构定义完美，但 GrowthIntegration 只提取文本记忆，不填充结构化 solution_steps |
| 用户画像不自动更新 | UserProfileStore 有字段但没有从对话自动填充的管道 |
| 轨迹数据只存不用 | TrajectoryRecorder 记录了行为但没有代码消费它来改善路由 |
| 没有 plan→execute→verify 循环 | 只能执行预定义 Pipeline，不能动态分解新任务 |

### 1.3 目标

实现 Hermes Agent 级别的自我进化能力：

1. **对话→自动生成 SKILL.md** — 用户解决了复杂问题后，系统自动将解决步骤固化为可复用技能
2. **对话→动态 Pipeline** — 从用户交互中学习工作流模式，自动组装 Pipeline
3. **用户反馈→迭代优化** — 根据反馈调整 skill 的 prompt/参数，逐步提升质量

一句话：**让管家"越用越懂你"，从被动问答变成主动能力积累。**

## 2. 设计决策

| 决策 | 选择 | 理由 |
|------|------|------|
| 方案 | 独立 EvolutionEngine 层 | 复用现有积木（Experience/Skill/Pipeline/Memory/Trajectory），只做中枢调度 |
| 目标场景 | 混合（自动执行 + 对话辅助） | 用户群混合，管家模式会根据场景自动判断 |
| 进化时机 | 分层：低风险静默，高风险确认 | 记忆层自动、技能层征得同意、工作流层明确确认 |
| 进化粒度 | 混合：记忆细粒度，技能粗粒度 | 信息积累快，能力固化有质量门控 |
| LLM 成本 | 最小化，用 Haiku 级别 | 进化分析不需要深度推理，Haiku 足够 |

## 3. 架构总览

### 3.1 三层进化模型

```
┌─────────────────────────────────────────────────┐
│              EvolutionEngine (zclaw-growth)       │
│                                                   │
│  L1 记忆进化 (已有，增强)                          │
│  ├── 每次: 对话→提取偏好/知识/经验→FTS5存储         │
│  ├── 每次: 结构化 Experience 提取                   │
│  ├── 每次: 用户画像增量更新                          │
│  └── 每次: 轨迹事件记录                             │
│                                                   │
│  L2 技能进化 (新建)                                │
│  ├── 触发: Experience 复用次数 >= 3 或 用户主动要求  │
│  ├── 流程: 模式分析 → SKILL.md 生成/优化 → 确认    │
│  └── 产物: 新建/更新的 SKILL.md 文件               │
│                                                   │
│  L3 工作流进化 (新建)                               │
│  ├── 触发: 轨迹中检测到重复的工具调用链模式          │
│  ├── 流程: 模式提取 → Pipeline YAML 组装 → 确认    │
│  └── 产物: 新建/更新的 Pipeline YAML 文件          │
│                                                   │
│  反馈闭环 (新建)                                   │
│  ├── 用户对技能/工作流结果的反馈 → 质量评分          │
│  ├── 低评分 → 触发 L2/L3 重新优化                  │
│  └── 高评分 + 高频使用 → 提升信任度                 │
└─────────────────────────────────────────────────┘
```

### 3.2 与现有系统集成点

| 现有组件 | crate | 集成方式 |
|---------|-------|---------|
| `MemoryExtractor` | zclaw-growth | L1 增强：合并 Experience 结构化提取到同一 prompt |
| `ExperienceStore` | zclaw-growth | L2 输入：复用 `reuse_count` 作为模式检测信号 |
| `TrajectoryRecorder` | zclaw-runtime | L3 输入：分析 `compressed_trajectories` 的工具调用链 |
| `UserProfileStore` | zclaw-memory | L1 增强：自动从对话更新画像字段 |
| `SkillRegistry.create_skill()` | zclaw-skills | L2 输出：调用现有 API 生成 SKILL.md |
| `Pipeline executor` | zclaw-pipeline | L3 输出：生成 YAML 配置文件 |
| `ButlerRouter` | zclaw-runtime | 消费：新技能自动加入语义路由索引 |
| `GrowthIntegration` | zclaw-runtime | 管线增强：在 process_conversation() 中串入新提取器 |

### 3.3 关键设计约束

1. **LLM 调用最小化** — 进化分析只在触发条件满足时才调用，不是每次对话都调
2. **人确认不可绕过** — L2/L3 的产物必须经过用户确认才生效
3. **可回滚** — 每次进化产物附带版本号，用户可以回退到之前版本
4. **成本感知** — 进化分析使用较便宜的模型（Haiku），不用 Opus
5. **内置/用户隔离** — 用户生成的技能存放在独立目录，项目更新不覆盖定制

## 4. L1 记忆进化增强

### 4.1 现状问题

| 问题 | 根因 |
|------|------|
| Experience 结构是空壳 | GrowthIntegration 只提取文本记忆，不填充结构化 Experience |
| 用户画像不自动更新 | UserProfileStore 有 update_field() 但无调用方 |
| 轨迹数据只存不用 | CompressedTrajectory 的 satisfaction_signal 无消费代码 |

### 4.2 新增 ExperienceExtractor

与现有 MemoryExtractor 并行运行，合并到单次 LLM 调用：

```rust
// zclaw-growth/src/experience_extractor.rs

pub struct ExperienceExtractor {
    llm: Arc<dyn LlmDriver>,
}

pub struct ExperienceCandidate {
    pub pain_pattern: String,       // 用户需求的自然语言描述
    pub context: String,            // 上下文信息
    pub solution_steps: Vec<String>, // 解决步骤（有序）
    pub outcome: Outcome,           // Success | Partial | Failed
    pub confidence: f32,            // 提取置信度
    pub tools_used: Vec<String>,    // 使用了哪些 tools/hands
    pub industry_context: Option<String>,
}

impl ExperienceExtractor {
    /// 从完整对话中提取结构化经验
    /// 与 MemoryExtractor 合并在同一次 LLM 调用中执行
    pub async fn extract(
        &self,
        conversation: &[Message],
    ) -> Result<Vec<ExperienceCandidate>> { ... }
}
```

### 4.3 增强对话后处理管线

修改 `GrowthIntegration.process_conversation()`：

```
对话结束
  ├── 现有: MemoryExtractor.extract() → 文本记忆存储
  ├── 新增: ExperienceExtractor.extract() → 结构化经验存储到 ExperienceStore
  ├── 新增: UserProfileUpdater.update() → 画像增量更新
  └── 现有: TrajectoryRecorder 压缩轨迹 → 轨迹存储
```

### 4.4 画像增量更新

```rust
// zclaw-growth/src/profile_updater.rs

pub struct UserProfileUpdater;

impl UserProfileUpdater {
    /// 从单次 LLM 提取结果中更新画像
    /// 不额外调用 LLM，复用 ExperienceExtractor 的输出
    pub async fn update(
        profile_store: &UserProfileStore,
        extraction: &CombinedExtraction, // 包含记忆+经验+画像信号
    ) -> Result<()> {
        // 更新字段：
        // - industry: 从 Experience 中的 industry_context 推断
        // - recent_topics: 追加本次对话主题
        // - pain_points: 追加 Experience 的 pain_pattern
        // - preferred_tools: 统计 tools_used 更新频率
        // - communication_style: 分析用户消息长度/格式
    }
}
```

| 画像维度 | 提取逻辑 | 更新频率 |
|---------|---------|---------|
| `industry` | 对话中提到的行业关键词 | 检测到变化时 |
| `recent_topics` | 对话主题分类 | 每次对话追加 |
| `pain_points` | Experience 中的 pain_pattern | 每次新经验 |
| `preferred_tools` | 轨迹中高频使用的 tools | 每次对话更新 |
| `communication_style` | 用户消息的长度/格式偏好 | 每次对话微调 |

### 4.5 成本控制

- ExperienceExtractor 和 MemoryExtractor **合并为单次 LLM 调用**
- 画像更新从同一个 LLM 响应中提取，不额外调用
- 总新增成本：**0 次额外 LLM 调用**（prompt 更长，token 开销增加约 20%）

## 5. L2 技能进化

### 5.1 触发机制

| 触发条件 | 说明 | 进化级别 |
|---------|------|---------|
| `Experience.reuse_count >= 3` | 同一 pain_pattern 被检索复用了 3 次+ | 自动触发 |
| 用户明确要求 | "帮我保存成一个技能" / "下次直接这样做" | 立即触发 |
| 管家主动提议 | 检测到用户第 N 次问同类问题（N=2） | 管家触发 |
| `CompressedTrajectory.outcome = Success` + 高频 | 轨迹分析发现成功模式 | 批量触发 |

### 5.2 技能生成流程

```
触发信号
  │
  ▼
Phase 1: 模式聚合 (PatternAggregator)
  收集同一 pain_pattern 下的所有 Experience
  对比 solution_steps，找出共同步骤
  │
  ▼
Phase 2: 技能生成 (SkillGenerator) — LLM 调用（Haiku）
  输入：聚合的模式 + 原始对话样本
  输出：SKILL.md 文件内容
  包含：name, description, triggers, tools, steps
  │
  ▼
Phase 3: 质量门控 (QualityGate)
  - triggers 不与现有 75 个内置技能冲突
  - tools 依赖是否已在 HandRegistry 注册
  - SKILL.md 格式校验（loader.rs 可解析）
  - 置信度 >= 0.7
  │
  ▼
Phase 4: 用户确认 (ConfirmationGate)
  管家对话中呈现：
  "我注意到你经常做 [X]，
   我帮你整理成了一个技能 [技能名]，
   以后直接说 [触发词] 就能用了。确认？"
  用户可以：确认 / 修改 / 拒绝
  │
  ▼ (确认)
Phase 5: 注册生效 (SkillRegistrar)
  调用 SkillRegistry.create_skill()
  自动重建语义路由索引
  通知 ButlerRouter 新技能可用
```

### 5.3 核心数据结构

```rust
// zclaw-growth/src/skill_generator.rs

pub struct SkillCandidate {
    pub name: String,
    pub description: String,
    pub triggers: Vec<String>,
    pub tools: Vec<String>,
    pub steps: Vec<SkillStep>,
    pub category: String,
    pub source_experiences: Vec<Uuid>,  // 来源 Experience ID
    pub confidence: f32,
    pub version: u32,                   // 迭代版本
}

pub struct SkillStep {
    pub instruction: String,   // 步骤说明
    pub tool: Option<String>,  // 使用的工具（如果有）
    pub expected_output: String, // 预期输出
}

pub struct EvolutionEvent {
    pub id: Uuid,
    pub event_type: EvolutionEventType,
    pub candidate: SkillCandidate,
    pub status: EvolutionStatus,   // Pending | Confirmed | Rejected | Optimized
    pub user_feedback: Option<String>,
    pub created_at: DateTime<Utc>,
}
```

### 5.4 技能迭代优化

```
用户使用自动生成的技能
  │
  ├── 满意 → reuse_count++ → 强化（不改动）
  │
  └── 不满意 → 收集反馈信号
        │
        ▼
      反馈分析 (LLM 调用)
        │
        ├── 修改 triggers → 重新路由
        ├── 修改 steps → 优化流程
        ├── 修改 tools → 换工具
        └── 降级为记忆 → 不够通用，回退为 Experience
```

### 5.5 技能存储隔离

| 类型 | 存储路径 | 来源 | 可修改 |
|------|---------|------|--------|
| 内置技能 | `skills/` | 随项目发布 | 否 |
| 用户技能 | `~/.zclaw/skills/` 或 SaaS 存储 | L2 进化生成 | 是 |
| 临时技能 | 仅内存 | 对话中临时 | 自动销毁 |

`SkillRegistry` 已支持 `add_skill_dir()`，只需增加用户技能目录扫描。

## 6. L3 工作流进化

### 6.1 触发机制

```
TrajectoryAnalyzer（后台周期任务，每小时执行一次）
  │
  ├── 扫描最近 7 天的 CompressedTrajectory
  ├── 按相似度聚类（工具链序列相似度）
  ├── 发现重复模式（出现 2 次以上的相同工具链）
  │
  └── 触发信号：发现可固化的工作流模式
```

### 6.2 Pipeline 自动组装

```rust
// zclaw-growth/src/workflow_composer.rs

pub struct WorkflowComposer {
    llm: Arc<dyn LlmDriver>,
}

pub struct PipelineCandidate {
    pub name: String,
    pub description: String,
    pub triggers: Vec<String>,
    pub yaml_content: String,          // 生成的 Pipeline YAML
    pub source_trajectories: Vec<Uuid>, // 来源轨迹
    pub confidence: f32,
}

impl WorkflowComposer {
    /// 从相似轨迹中组装 Pipeline
    /// 输入：聚类后的轨迹组（相同工具链模式）
    /// 输出：PipelineCandidate（YAML + 元数据）
    pub async fn compose(
        &self,
        trajectories: &[CompressedTrajectory],
        hand_registry: &HandRegistry,
    ) -> Result<Option<PipelineCandidate>> { ... }
}
```

### 6.3 生成示例

用户经常做：搜索→抓取→总结→格式化

```yaml
# 自动生成的 Pipeline
name: "每日资讯简报"
description: "搜索指定主题，抓取内容，生成结构化简报"
triggers:
  - "每日简报"
  - "资讯汇总"
  - "新闻总结"
steps:
  - id: search
    action: hand
    hand: researcher
    params:
      action: search
      query: "${inputs.topic}"
  - id: fetch
    action: hand
    hand: collector
    params:
      urls: "${steps.search.output.urls}"
  - id: summarize
    action: llm_generate
    params:
      prompt: "将以下内容整理为结构化简报：${steps.fetch.output}"
```

## 7. 反馈闭环

### 7.1 反馈信号收集

| 信号类型 | 收集方式 | 权重 |
|---------|---------|------|
| 显式反馈 | 用户说"不好"/"换一个"/"就这样" | 高 |
| 隐式反馈 | 用户是否继续追问同类问题 | 中 |
| 使用频率 | 技能/Pipeline 被调用的次数 | 中 |
| 完成率 | 技能执行后用户是否继续操作 | 低 |
| 对比评分 | 同一任务使用技能 vs 不使用的满意度差异 | 高 |

### 7.2 闭环路径

```
用户使用进化产物（技能/Pipeline）
  │
  ├── 正面反馈 → 信任度++ → 推荐优先级提升
  │               → 如果足够成熟 → 提升为"推荐技能"
  │
  ├── 负面反馈 → 信任度-- → 触发优化循环
  │               → LLM 分析失败原因
  │               → 修改技能 steps/triggers/tools
  │               → 重新请用户确认
  │
  └── 长期不用 → 自然衰减 → 降级为记忆 → 最终清理
```

### 7.3 反馈数据结构

```rust
// zclaw-growth/src/feedback_collector.rs

pub struct EvolutionFeedback {
    pub evolution_id: Uuid,           // 关联的 EvolutionEvent
    pub artifact_type: ArtifactType,  // Skill | Pipeline
    pub signal: FeedbackSignal,       // Explicit | Implicit | Usage | Completion
    pub sentiment: Sentiment,         // Positive | Negative | Neutral
    pub details: Option<String>,      // 用户原始反馈文本
    pub timestamp: DateTime<Utc>,
}
```

## 8. 数据流全景

```
用户对话
  │
  ├──[L1] 每次对话后 ──→ 合并 LLM 提取
  │                         ├── 文本记忆 (偏好/知识/经验)
  │                         ├── 结构化 Experience (pain→solution→outcome)
  │                         ├── 画像增量更新
  │                         └── 轨迹事件记录
  │                         │
  │                         ▼
  │                    经验库 (FTS5)
  │                    轨迹库 (SQLite)
  │                    用户画像 (SQLite)
  │                         │
  ├──[L2] 模式触发时 ──→ 模式聚合 → 技能生成 → 质量门控 → 用户确认 → 注册
  │
  ├──[L3] 周期分析时 ──→ 轨迹聚类 → 工作流组装 → 质量门控 → 用户确认 → 注册
  │
  └──[反馈] 使用后 ──→ 质量评分 → 优化/衰减/提升
```

## 9. 新增模块清单

所有模块在 `zclaw-growth` crate 中，不新增 crate：

| 模块 | 文件 | 职责 |
|------|------|------|
| ExperienceExtractor | `experience_extractor.rs` | 结构化经验提取 |
| ProfileUpdater | `profile_updater.rs` | 画像增量更新 |
| PatternAggregator | `pattern_aggregator.rs` | 经验模式聚合 |
| SkillGenerator | `skill_generator.rs` | SKILL.md 生成 |
| WorkflowComposer | `workflow_composer.rs` | Pipeline YAML 组装 |
| QualityGate | `quality_gate.rs` | 质量门控验证 |
| EvolutionEngine | `evolution_engine.rs` | 中枢调度（触发+协调） |
| FeedbackCollector | `feedback_collector.rs` | 反馈信号收集与分析 |

需修改的现有文件：

| 文件 | 修改内容 |
|------|---------|
| `zclaw-runtime/src/growth.rs` | GrowthIntegration 增加新提取器和触发检查 |
| `zclaw-runtime/src/middleware/butler_router.rs` | 消费进化事件，呈现确认对话 |
| `zclaw-skills/src/registry.rs` | 增加用户技能目录扫描 |
| `zclaw-kernel/src/kernel/skills.rs` | 暴露进化相关 Tauri 命令 |
| `zclaw-kernel/src/kernel/mod.rs` | 注册 EvolutionEngine 到 Kernel |

## 10. 实施建议

### 10.1 分阶段实施

| 阶段 | 内容 | 依赖 |
|------|------|------|
| Phase 1: L1 增强 | ExperienceExtractor + ProfileUpdater + 合并提取 | 无外部依赖 |
| Phase 2: L2 核心 | PatternAggregator + SkillGenerator + QualityGate | Phase 1 |
| Phase 3: L2 集成 | 确认对话 UI + SkillRegistrar + ButlerRouter 集成 | Phase 2 |
| Phase 4: L3 核心 | TrajectoryAnalyzer + WorkflowComposer | Phase 1 |
| Phase 5: 反馈闭环 | FeedbackCollector + 优化循环 | Phase 2 + 3 |

### 10.2 风险和缓解

| 风险 | 缓解措施 |
|------|---------|
| LLM 提取质量不稳定 | 置信度阈值过滤 + 质量门控 + 用户确认 |
| 进化产物与内置技能冲突 | QualityGate 检查 triggers 冲突 |
| 用户技能目录膨胀 | 信任度衰减 + 长期不用自动归档 |
| 增加系统复杂度 | 所有进化逻辑集中在 zclaw-growth，不侵入运行时主流程 |
| 隐私问题 | 经验/技能数据本地存储，用户可查看/删除 |