zclaw_openfang/docs/superpowers/specs/2026-04-18-evolution-engine-design.md

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 调用：

// 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 画像增量更新

// 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 核心数据结构

// 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 自动组装

// 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 生成示例

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

# 自动生成的 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 反馈数据结构

// 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，不侵入运行时主流程
隐私问题	经验/技能数据本地存储，用户可查看/删除