zclaw_openfang/plans/crispy-spinning-reef.md

ZCLAW Agent 成长功能设计方案

一、上下文

1.1 背景与目标

问题：ZCLAW 的学习系统存在前后端分离问题——前端有完整的学习逻辑，但与后端执行系统完全隔离，导致 Agent 无法真正"成长"。

目标：设计并实现完整的 Agent 成长功能，让 Agent 像个人管家一样持续学习和进化。

1.2 需求总结

维度	决策
成长维度	偏好记忆 + 知识积累 + 技能掌握（全部）
整合策略	完全后端化，Rust 重写学习系统
存储架构	OpenViking 作为完整记忆层
学习触发	对话后自动 + 用户显式触发
行为影响	智能检索 + 动态注入（Token 预算控制）

---

二、系统现状分析

2.1 Agent 核心架构

组件	位置	职责
AgentConfig	crates/zclaw-types/src/agent.rs	Agent 静态配置
AgentRegistry	crates/zclaw-kernel/src/registry.rs	运行时注册管理
AgentLoop	crates/zclaw-runtime/src/loop_runner.rs	LLM 执行循环
Kernel	crates/zclaw-kernel/src/kernel.rs	协调层

关键问题：AgentConfig 是静态配置，没有成长相关字段。

2.2 记忆系统现状

能力	状态	说明
短期记忆 (Session)	✅ 已实现	SQLite sessions + messages 表
KV 存储	✅ 已实现	未被学习系统使用
长期记忆检索	❌ 缺失	历史会话无法智能召回
语义检索	❌ 缺失	无向量嵌入或相似度搜索
智能摘要	❌ 缺失	compact() 仅简单丢弃旧消息

2.3 现有资源

OpenViking（字节跳动开源的上下文数据库）：

• 位置：docs/features/03-context-database/00-openviking-integration.md
• 能力：L0/L1/L2 分层存储、语义搜索、本地部署
• 状态：已集成，成熟度 L4

---

三、设计方案

3.1 整体架构

┌─────────────────────────────────────────────────────────────────┐
│                    ZCLAW Agent 成长系统                          │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                   zclaw-growth (新 Crate)                │   │
│  │  ──────────────────────────────────────────────────────  │   │
│  │  • MemoryExtractor - 从对话中提取偏好/知识/经验          │   │
│  │  • MemoryRetriever - 语义检索相关记忆                    │   │
│  │  • PromptInjector - 动态构建 system_prompt              │   │
│  │  • GrowthTracker - 追踪成长指标和演化                    │   │
│  └─────────────────────────────────────────────────────────┘   │
│                              │                                  │
│                              ▼                                  │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                   OpenViking (记忆层)                    │   │
│  │  ──────────────────────────────────────────────────────  │   │
│  │  URI 结构:                                               │   │
│  │  • agent://{id}/preferences/{category}  - 用户偏好       │   │
│  │  • agent://{id}/knowledge/{domain}      - 知识积累       │   │
│  │  • agent://{id}/experience/{skill}      - 技能经验       │   │
│  │  • agent://{id}/sessions/{sid}          - 对话历史       │   │
│  └─────────────────────────────────────────────────────────┘   │
│                              │                                  │
│                              ▼                                  │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                   zclaw-runtime (修改)                   │   │
│  │  ──────────────────────────────────────────────────────  │   │
│  │  AgentLoop 集成:                                         │   │
│  │  1. 对话前 → MemoryRetriever 检索相关记忆               │   │
│  │  2. 构建请求 → PromptInjector 注入记忆                   │   │
│  │  3. 对话后 → MemoryExtractor 提取新记忆                 │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

3.2 数据流

用户输入
    │
    ▼
┌─────────────────────────────────────────┐
│ 1. 记忆检索                              │
│    • 用当前输入查询 OpenViking           │
│    • 召回 Top-5 相关记忆                 │
│    • Token 预算控制 (500 tokens)         │
└─────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────┐
│ 2. Prompt 构建                          │
│    system_prompt = base +               │
│      "## 用户偏好\n" + preferences +     │
│      "## 相关知识\n" + knowledge         │
└─────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────┐
│ 3. LLM 对话                             │
│    • 正常的 AgentLoop 执行               │
└─────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────┐
│ 4. 记忆提取 (对话后)                     │
│    • 分析对话内容                        │
│    • 提取偏好/知识/经验                  │
│    • 写入 OpenViking (L0/L1/L2)          │
└─────────────────────────────────────────┘

3.3 OpenViking URI 结构

agent://{agent_id}/
├── preferences/
│   ├── communication-style    # 沟通风格偏好
│   ├── response-format        # 回复格式偏好
│   ├── language-preference    # 语言偏好
│   └── topic-interests        # 主题兴趣
├── knowledge/
│   ├── user-facts            # 用户相关事实
│   ├── domain-knowledge      # 领域知识
│   └── lessons-learned       # 经验教训
├── experience/
│   ├── skill-{id}            # 技能使用经验
│   └── hand-{id}             # Hand 使用经验
└── sessions/
    └── {session_id}/         # 对话历史
        ├── raw               # 原始对话 (L0)
        ├── summary           # 摘要 (L1)
        └── keywords          # 关键词 (L2)

---

四、详细设计

4.1 新 Crate 结构

crates/zclaw-growth/
├── Cargo.toml
├── src/
│   ├── lib.rs                 # 入口和公共 API
│   ├── extractor.rs           # 记忆提取器
│   ├── retriever.rs           # 记忆检索器
│   ├── injector.rs            # Prompt 注入器
│   ├── tracker.rs             # 成长追踪器
│   ├── types.rs               # 类型定义
│   └── viking_adapter.rs      # OpenViking 适配器

4.2 核心数据结构

// types.rs

/// 记忆类型
pub enum MemoryType {
    Preference,    // 偏好
    Knowledge,     // 知识
    Experience,    // 经验
    Session,       // 对话
}

/// 记忆条目
pub struct MemoryEntry {
    pub uri: String,
    pub memory_type: MemoryType,
    pub content: String,
    pub keywords: Vec<String>,
    pub importance: u8,
    pub access_count: u32,
    pub created_at: DateTime<Utc>,
    pub last_accessed: DateTime<Utc>,
}

/// 检索配置
pub struct RetrievalConfig {
    pub max_tokens: usize,           // 默认 500
    pub preference_budget: usize,    // 默认 200
    pub knowledge_budget: usize,     // 默认 200
    pub experience_budget: usize,    // 默认 100
    pub min_similarity: f32,         // 默认 0.7
    pub max_results: usize,          // 默认 10
}

4.3 核心接口

// extractor.rs
pub struct MemoryExtractor {
    llm_driver: Arc<dyn LlmDriver>,
}

impl MemoryExtractor {
    pub async fn extract(
        &self,
        messages: &[Message],
        config: &ExtractionConfig,
    ) -> Result<Vec<ExtractedMemory>>;
}

// retriever.rs
pub struct MemoryRetriever {
    viking: Arc<VikingAdapter>,
}

impl MemoryRetriever {
    pub async fn retrieve(
        &self,
        agent_id: &AgentId,
        query: &str,
        config: &RetrievalConfig,
    ) -> Result<RetrievalResult>;
}

// injector.rs
pub struct PromptInjector {
    config: RetrievalConfig,
}

impl PromptInjector {
    pub fn inject(
        &self,
        base_prompt: &str,
        memories: &RetrievalResult,
    ) -> String;
}

4.4 AgentLoop 集成

修改 crates/zclaw-runtime/src/loop_runner.rs：

pub struct AgentLoop {
    // ... 现有字段
    memory_retriever: Arc<MemoryRetriever>,  // 新增
    memory_extractor: Arc<MemoryExtractor>,  // 新增
    prompt_injector: PromptInjector,          // 新增
    growth_enabled: bool,                     // 新增
}

4.5 前端变化

• 新增组件：desktop/src/components/GrowthPanel.tsx
• 修改 Store：desktop/src/store/agentStore.ts 添加成长状态

---

五、执行计划

5.1 知识库文档（本次任务）

创建以下文档到 docs/knowledge-base/：

1. agent-growth-analysis.md - Agent 成长功能深度分析
2. system-architecture-deep-dive.md - 系统架构深度剖析
3. growth-improvement-roadmap.md - 成长功能改进路线图

5.2 实现阶段（后续任务）

阶段	内容	预估
Phase 1	zclaw-growth crate 骨架 + 类型定义	1-2 天
Phase 2	MemoryRetriever + VikingAdapter	2-3 天
Phase 3	PromptInjector + AgentLoop 集成	2-3 天
Phase 4	MemoryExtractor (LLM 驱动)	3-4 天
Phase 5	前端 UI + 状态管理	2-3 天
Phase 6	测试 + 优化	2-3 天

---

六、关键文件路径

核心类型

• crates/zclaw-types/src/agent.rs - AgentConfig
• crates/zclaw-types/src/message.rs - Message
• crates/zclaw-types/src/id.rs - AgentId, SessionId

存储层

• crates/zclaw-memory/src/store.rs - MemoryStore
• crates/zclaw-memory/src/schema.rs - SQLite Schema

运行时

• crates/zclaw-runtime/src/loop_runner.rs - AgentLoop

OpenViking 集成

• desktop/src/lib/viking-client.ts - 前端客户端
• desktop/src-tauri/src/viking_commands.rs - Tauri 命令
• docs/features/03-context-database/00-openviking-integration.md - 文档

前端学习系统（将被后端化）

• desktop/src/lib/active-learning.ts
• desktop/src/lib/memory-extractor.ts
• desktop/src/store/activeLearningStore.ts

---

七、验证方式

1. 文档完整性：确保所有章节内容完整，代码路径准确
2. 架构验证：通过阅读代码确认流程图准确性
3. 可行性评估：评估技术方案的实现难度和依赖