# 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, pub importance: u8, pub access_count: u32, pub created_at: DateTime, pub last_accessed: DateTime, } /// 检索配置 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, } impl MemoryExtractor { pub async fn extract( &self, messages: &[Message], config: &ExtractionConfig, ) -> Result>; } // retriever.rs pub struct MemoryRetriever { viking: Arc, } impl MemoryRetriever { pub async fn retrieve( &self, agent_id: &AgentId, query: &str, config: &RetrievalConfig, ) -> Result; } // 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, // 新增 memory_extractor: Arc, // 新增 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. **可行性评估**：评估技术方案的实现难度和依赖