# ZCLAW 功能全景文档

> **版本**: v0.6.0
> **更新日期**: 2026-03-27
> **项目状态**: 完整 Rust Workspace 架构，9 个核心 Crates，78+ 技能，Pipeline DSL + Smart Presentation + Agent Growth System
> **整体完成度**: 68% (基于 2026-03-27 全面审计)
> **架构**: Tauri 桌面应用，Rust Workspace (9 crates) + React 前端

> 📋 **重要**: ZCLAW 采用 Rust Workspace 架构，包含 9 个分层 Crates (types → memory → runtime → kernel → skills/hands/protocols/pipeline/growth)，所有核心能力集成在 Tauri 桌面应用中

---

## 一、文档索引

### 1.1 架构层 (Architecture)

| 文档 | 功能 | 成熟度 | 测试覆盖 |
|------|------|--------|---------|
| [01-communication-layer.md](00-architecture/01-communication-layer.md) | 通信层 | L3 (85%) | 高 |
| [02-state-management.md](00-architecture/02-state-management.md) | 状态管理 | L3 (80%) | 高 |
| [03-security-auth.md](00-architecture/03-security-auth.md) | 安全认证 | L2-L3 (75%) | 高 |

### 1.2 核心功能 (Core Features)

| 文档 | 功能 | 成熟度 | 测试覆盖 |
|------|------|--------|---------|
| [00-chat-interface.md](01-core-features/00-chat-interface.md) | 聊天界面 | L3-L4 (90%) | 高 |
| [01-agent-clones.md](01-core-features/01-agent-clones.md) | Agent 分身 | L3 (85%) | 高 |
| [02-hands-system.md](01-core-features/02-hands-system.md) | Hands 系统 | L2-L3 (64%) | 中 |
| 工作流引擎 | 工作流引擎 | L3 (80%) | 中 |

### 1.3 智能层 (Intelligence Layer) - ✅ 已接入聊天流程 (2026-03-26 更新)

| 文档 | 功能 | 成熟度 | 聊天集成 | 后端状态 |
|------|------|--------|---------|----------|
| [00-agent-memory.md](02-intelligence-layer/00-agent-memory.md) | Agent 记忆 | L3-L4 (90%) | ✅ pre-hook (FTS5+TF-IDF+Embedding) | ✅ SqliteStorage |
| [01-identity-evolution.md](02-intelligence-layer/01-identity-evolution.md) | 身份演化 | L2 (70%) | ✅ pre-hook (SOUL.md → system prompt) | ✅ Rust 实现 |
| [06-context-compaction.md](02-intelligence-layer/06-context-compaction.md) | 上下文压缩 | L2-L3 (75%) | ✅ 已接入内核 (AgentLoop, LLM 摘要) | ✅ Rust 实现 |
| [03-reflection-engine.md](02-intelligence-layer/03-reflection-engine.md) | 自我反思 | L2 (65%) | ✅ post-hook (自动触发) | ✅ Rust 实现 |
| 心跳巡检 | 心跳巡检 | L2-L3 (70%) | ✅ post-hook (record_interaction) | ✅ Rust 实现 |
| [05-autonomy-manager.md](02-intelligence-layer/05-autonomy-manager.md) | 自主授权 | L2-L3 (75%) | ✅ RightPanel 'autonomy' | ✅ TypeScript |

> **智能层集成说明** (2026-03-27): 通过 `intelligence_hooks.rs` 将 identity、memory context、heartbeat、reflection 接入 `agent_chat_stream` 流程。compactor 已在内核 AgentLoop 集成 (15k token 阈值)。已清理死代码: pattern_detector、recommender、mesh、persona_evolver、trigger_evaluator。

### 1.4 上下文数据库 (Context Database)

| 文档 | 功能 | 成熟度 | 测试覆盖 |
|------|------|--------|---------|
| [00-openviking-integration.md](03-context-database/00-openviking-integration.md) | OpenViking 集成 | L2-L3 (70%) | 高 |
| 向量记忆 | L3 (80%) | 中 |
| 会话持久化 | L3-L4 (90%) | 高 |
| 记忆提取 | L3-L4 (90%) | 高 |

### 1.5 Skills 生态 - ✅ 动态扫描 + execute_skill 已实现

| 文档 | 功能 | 成熟度 | UI 集成 |
|------|------|--------|---------|
| [00-skill-system.md](04-skills-ecosystem/00-skill-system.md) | Skill 系统概述 | L3 (80%) | ✅ 通过 Tauri 命令 |
| 内置技能 | 内置技能 (**78+** SKILL.md) | L3 (80%) | N/A |
| 技能发现 | 技能发现 (动态扫描) | **L3** (80%) | ✅ **已集成** |

> ✅ **更新**: Skills 动态扫描已实现。Kernel 集成 `SkillRegistry`，通过 Tauri 命令 `skill_list` 和 `skill_refresh` 动态发现所有 **78+ 个**技能。**新增 `execute_skill` 工具**，允许 Agent 在对话中直接调用技能。

### 1.6 Hands 系统 - ✅ 7/11 完整实现 + 审批流程 (2026-03-26 更新)

| 文档 | 功能 | 成熟度 | 可用 Hands |
|------|------|--------|-----------|
| [00-hands-overview.md](05-hands-system/00-hands-overview.md) | Hands 概述 (11个) | L2-L3 (64%) | **7/11 (64%)** |

> ✅ **更新 (2026-03-26)**:
> - 7 个 Hands 有完整 Rust 后端实现 (Browser, Collector, Researcher, Slideshow, Speech, Whiteboard, Quiz)
> - ✅ **审批流程**: Kernel 新增 `pending_approvals` 管理，`hand_approve`/`hand_cancel` Tauri 命令已实现真实审批逻辑
> - ⚠️ **Predictor** 和 **Lead** 仅有 HAND.toml 配置文件，无 Rust 实现
> - ⚠️ **Clip** 需要 FFmpeg，**Twitter** 需要 API Key

### 1.7 Tauri 后端

| 文档 | 功能 | 成熟度 | 测试覆盖 |
|------|------|--------|---------|
| [00-backend-integration.md](06-tauri-backend/00-backend-integration.md) | 后端集成 | L3 (80%) | 高 |
| 安全存储 | 安全存储 | L3 (80%) | 高 |
| 本地 Gateway | 本地 Gateway | L3 (80%) | 高 |

### 1.8 Pipeline DSL 系统 - ✅ 新增 (v0.3.0)

| 文档 | 功能 | 成熟度 | UI 集成 |
|------|------|--------|---------|
| [00-pipeline-overview.md](07-pipeline-dsl/00-pipeline-overview.md) | Pipeline 概述 | **L2-L3** (75%) | ✅ PipelinesPanel |

> ✅ **新增**: Pipeline DSL 自动化工作流系统
> - **教育类**: 互动课堂生成器
> - **营销类**: 营销方案生成器
> - **法律类**: 合同智能审查
> - **研究类**: 文献综述生成器
> - **生产力类**: 智能会议纪要
>
> **特性**: YAML 声明式配置、状态管理、LLM 集成、Agent 智能推荐、结果预览组件

### 1.9 Smart Presentation Layer - ✅ 新增 (v0.5.0)

| 组件 | 功能 | 成熟度 | UI 集成 |
|------|------|--------|---------|
| PresentationContainer | 主容器，自动类型检测 | **L3** (85%) | ✅ PipelinesPanel |
| TypeSwitcher | 手动切换展示类型 | **L3** (85%) | ✅ 集成 |
| ChartRenderer | 数据可视化渲染 | **L3** (85%) | ✅ 集成 |
| QuizRenderer | 互动测验渲染 | **L3** (85%) | ✅ 集成 |
| SlideshowRenderer | 幻灯片渲染 | **L3** (85%) | ✅ 集成 |
| DocumentRenderer | Markdown 文档渲染 | **L3** (85%) | ✅ 集成 |

> ✅ **新增**: Smart Presentation Layer 智能展示层
> - **自动检测**: 分析数据结构推荐最佳展示格式
> - **多渲染器**: Chart, Quiz, Slideshow, Document
> - **类型切换**: 用户可手动切换展示类型
> - **Rust 分析器**: 后端 PresentationAnalyzer 提供类型推荐

### 1.10 其他功能

| 功能 | 成熟度 | 备注 |
|------|--------|------|
| 智能路由 (Intelligent Routing) | L1 (15%) | 仅基础意图分类 |
| 通道适配 (Channels) | L1 (10%) | 仅 ConsoleChannel 测试适配器 |
| A2A 协议 | L1 (40%) | 基础协议定义，未完整实现 |
| 浏览器自动化 (Browser Automation) | L3 (80%) | BrowserHand 可用 |

---

## 二、后续工作计划

> 📋 详细计划见 [roadmap.md](roadmap.md) | 🧠 头脑风暴见 [brainstorming-notes.md](brainstorming-notes.md)

### 2.1 短期计划 (1-2 周)

| ID | 任务 | 优先级 | 状态 |
|----|------|--------|------|
| S1 | 智能层接入聊天流程 (identity/memory/heartbeat/reflection) | P0 | ✅ 完成 |
| S2 | 双存储统一 (SqliteStorage 优先) | P0 | ✅ 完成 |
| S3 | Hand 审批流程真实实现 | P0 | ✅ 完成 |
| S4 | Gemini/Local LLM 驱动实现 | P1 | ✅ 完成 |
| S5 | WorkflowBuilder 接入可视化视图 | P2 | ✅ 完成 |
| S6 | 导出功能清理 (PPTX/PDF 友好提示) | P2 | ✅ 完成 |
| S7 | Compactor 接入聊天流程 | P1 | ✅ 完成 |
| S8 | 定时任务 KernelClient 支持 | P1 | 待开始 |
| S9 | 添加消息搜索功能 | P1 | 待开始 |
| S10 | 优化错误提示 | P1 | 待开始 |

### 2.2 中期计划 (1-2 月)

| ID | 任务 | 价值 | 风险 |
|----|------|------|------|
| M1 | 记忆图谱可视化 | 高 | 中 |
| M2 | 技能市场 MVP | 高 | 中 |
| M3 | 主动学习引擎 | 高 | 高 |
| M4 | 工作流编辑器 | 高 | 中 |

### 2.3 关键决策待定

1. **目标用户定位**: 个人 vs 团队 vs 企业？
2. **记忆存储策略**: 纯本地 vs 可选云同步？
3. **开源策略**: 完全开源 vs 核心闭源？
4. **定价策略**: 免费 vs 付费 vs 混合？

---

## 三、功能优先级矩阵 (ICE 评分)

| 功能 | Impact | Confidence | Ease | ICE 分 | 状态 |
|------|--------|------------|------|--------|------|
| Agent 记忆 | 10 | 9 | 7 | 630 | 已完成 |
| 身份演化 | 8 | 9 | 9 | 648 | 已完成 |
| 上下文压缩 | 9 | 8 | 6 | 432 | 已完成 |
| 心跳巡检 | 9 | 8 | 6 | 432 | 已完成 |
| 多 Agent 协作 | 9 | 6 | 4 | 216 | 已移除（Pipeline 替代） |
| 自主授权 | 8 | 7 | 5 | 280 | 已完成 |
| 向量记忆 | 9 | 7 | 5 | 315 | 已完成 |
| 会话持久化 | 7 | 9 | 8 | 504 | 已完成 |

**评分说明**:
- **Impact (影响)**: 10 = 决定性功能，1 = 边缘功能
- **Confidence (信心)**: 10 = 完全确定，1 = 高度不确定
- **Ease (容易度)**: 10 = 极易实现，1 = 极难实现
- **ICE 分** = Impact × Confidence × Ease

---

## 三、成熟度等级定义

| 等级 | 名称 | 描述 |
|------|------|------|
| L0 | 概念 | 有设计想法，未实现 |
| L1 | 原型 | 基本可用，有已知问题 |
| L2 | 可用 | 功能完整，有测试 |
| L3 | 成熟 | 稳定可靠，有文档 |
| L4 | 生产 | 经过验证，可扩展 |

---

## 四、模块依赖关系

```
┌─────────────────────────────────────────────────────────────┐
│                      UI 组件层                               │
│  ChatArea │ PipelinesPanel │ RightPanel │ Settings          │
└─────────────────────────────┬───────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────┐
│                      状态管理层                              │
│  chatStore │ connectionStore │ handStore │ configStore      │
└─────────────────────────────┬───────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────┐
│                      智能层                                  │
│  AgentMemory │ ReflectionEngine │ AutonomyManager           │
└─────────────────────────────┬───────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────┐
│                      通信层                                  │
│  GatewayClient │ VikingClient │ TauriGateway                │
└─────────────────────────────┬───────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────┐
│                      后端层                                  │
│  ZCLAW Kernel │ OpenViking Server │ Tauri Backend        │
└─────────────────────────────────────────────────────────────┘
```

---

## 五、关键指标

| 指标 | 数值 |
|------|------|
| **Rust Crates** | **9** (types, memory, runtime, kernel, skills, hands, protocols, pipeline, growth) |
| **SKILL.md 文件** | **78+** |
| 动态发现技能 | 78+ (100%) |
| Hands 总数 | 11 |
| **已实现 Hands** | **7 (64%)** |
| **Kernel 注册 Hands** | **7/9 (78%)** |
| **Pipeline 模板** | **5** (教育/营销/法律/研究/生产力) |
| Zustand Store | **18+** |
| Tauri 命令 | **80+** |
| 代码行数 (前端) | ~30,000 |
| 代码行数 (后端 Rust) | ~18,000 |
| LLM Provider 支持 | **8** (Kimi, Qwen, DeepSeek, Zhipu, OpenAI, Anthropic, Gemini, Local/Ollama) |
| 智能层组件 | **5** (Memory, Heartbeat, Reflection, Identity, Compaction) |
| MCP 协议 | ✅ 已实现 (stdio transport) |
| execute_skill 工具 | ✅ 已实现 |
| **Pipeline DSL** | ✅ 完整实现 |
| **内置工具** | **5** (file_read, file_write, shell_exec, web_fetch, execute_skill) |
| **Agent Growth System** | ✅ 完整实现 (SqliteStorage + FTS5 + TF-IDF + Memory Extractor) |

### 5.1 Crate 依赖关系

```
zclaw-types          (L1: 基础类型, 无依赖) - 95% 完整度
    ↑
zclaw-memory         (L2: 存储层, SQLite) - 90% 完整度
    ↑
zclaw-runtime        (L3: 运行时, LLM 驱动, 工具执行) - 90% 完整度
    ↑
zclaw-kernel         (L4: 核心协调, Agent 调度) - 85% 完整度
    ↑
┌───┴───┬───────┬───────────┬──────────┬────────┐
│       │       │           │          │        │
skills  hands  protocols  pipeline  growth  channels
(80%)  (85%)   (75%)      (90%)     (95%)   (规划中)
```

### 5.2 Agent Growth System (zclaw-growth)

**✅ 完整实现 (v0.6.0)**

| 组件 | 功能 | 状态 |
|------|------|------|
| SqliteStorage | SQLite + FTS5 全文搜索 | ✅ L4 |
| MemoryRetriever | TF-IDF 语义检索 | ✅ L4 |
| PromptInjector | Token 预算控制注入 | ✅ L4 |
| MemoryExtractor | LLM 驱动记忆提取 | ✅ L4 |
| VikingAdapter | 存储抽象层 | ✅ L4 |

**测试覆盖**: 135 tests (70 zclaw-growth + 65 desktop)

---

## 六、变更历史

| 日期 | 版本 | 变更内容 |
|------|------|---------|
| 2026-03-26 | v0.1.0 | **v1.0 发布准备**：移除 Team/Swarm 功能（~8,100 行，Pipeline 替代），安全修复，CI/CD 建立 |
| 2026-03-26 | v0.5.0 | **Smart Presentation Layer**：自动类型检测，Chart/Quiz/Slideshow/Document 渲染器，PresentationAnalyzer Rust 后端 |
| 2026-03-25 | v0.4.0 | **代码现状深度分析**：8 个 Rust Crates 完整度评估，78+ 技能确认，18+ Store 状态管理，新增 Mesh/Persona 智能组件 |
| 2026-03-27 | v0.6.0a | **全面审计更新**：所有成熟度标注调整为实际完成度 (平均 68%)，新增清理记录 |
| 2026-03-25 | v0.3.0 | **Pipeline DSL 系统实现**，5 类 Pipeline 模板，Agent 智能推荐，结果预览组件 |
| 2026-03-24 | v0.2.5 | **execute_skill 工具实现**，智能层完全实现验证，技能数更新为 78+ |
| 2026-03-24 | v0.2.4 | Hands Review: 修复 BrowserHand Kernel 注册问题，所有 9 个已实现 Hands 均可访问 |
| 2026-03-24 | v0.2.3 | Hands 后端集成: 9/11 Hands 可用 (新增 Clip, Twitter) |
| 2026-03-24 | v0.2.2 | Hands 后端集成: 7/11 Hands 可用 (新增 Researcher, Collector) |
| 2026-03-24 | v0.2.1 | Hands 后端集成: 5/11 Hands 可用 (Browser, Slideshow, Speech, Quiz, Whiteboard) |
| 2026-03-24 | v0.2.0 | 更新为内部 Kernel 架构，Streaming + MCP 协议，修正 Skills/Hands 数量 |
| 2026-03-17 | v1.1 | 智能层集成状态更新 |
| 2026-03-16 | v1.0 | 初始版本，完成全部功能文档 |