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

```rust
// 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 核心接口

```rust
// 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`：

```rust
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. **可行性评估**：评估技术方案的实现难度和依赖