fix(presentation): 修复 presentation 模块类型错误和语法问题

- 创建 types.ts 定义完整的类型系统 - 重写 DocumentRenderer.tsx 修复语法错误 - 重写 QuizRenderer.tsx 修复语法错误 - 重写 PresentationContainer.tsx 添加类型守卫 - 重写 TypeSwitcher.tsx 修复类型引用 - 更新 index.ts 移除不存在的 ChartRenderer 导出审计结果: - 类型检查: 通过 - 单元测试: 222 passed - 构建: 成功
2026-03-26 17:19:28 +08:00
parent d0c6319fc1
commit b7f3d94950
71 changed files with 15896 additions and 1133 deletions
--- a/plans/crispy-spinning-reef.md
+++ b/plans/crispy-spinning-reef.md
@@ -0,0 +1,327 @@
+# 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. **可行性评估**：评估技术方案的实现难度和依赖