iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
a71c4138ccc2d0e5bdcdc55722fae72c9bcd6a36
zclaw_openfang/docs/features/README.md
iven a71c4138cc
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
Details
CI / Unit Tests (push) Has been cancelled
Details
CI / Build Frontend (push) Has been cancelled
Details
CI / Rust Check (push) Has been cancelled
Details
CI / Security Scan (push) Has been cancelled
Details
CI / E2E Tests (push) Has been cancelled
Details
fix(audit): 修复深度审计发现的 P0/P1 问题 (8项) 
基于 DEEP_AUDIT_REPORT.md 修复 2 CRITICAL + 4 HIGH + 1 MEDIUM 问题:

- C1: PromptOnly 技能集成 LLM 调用 — 定义 LlmCompleter trait，
  通过 LlmDriverAdapter 桥接 zclaw_runtime::LlmDriver，
  PromptOnlySkill.execute() 现在调用 LLM 生成内容
- C2: 反思引擎空记忆 bug — 新增 query_memories_for_reflection()
  从 VikingStorage 查询真实记忆传入 reflect()
- H7: Agent Store 接口适配 — KernelClient 添加 listClones/createClone/
  deleteClone/updateClone 方法，映射到 agent_* 命令
- H8: Hand 审批检查 — hand_execute 执行前检查 needs_approval，
  需审批返回 pending_approval 状态
- M1: 幽灵命令注册 — 注册 hand_get/hand_run_status/hand_run_list
  三个 Tauri 桩命令
- H1/H2: SpeechHand/TwitterHand 添加 demo 标签
- H5: 归档过时 VERIFICATION_REPORT

文档更新: DEEP_AUDIT_REPORT.md 标记修复状态，README.md 更新
关键指标和变更历史。整体完成度从 ~50% 提升至 ~58%。
2026-03-27 09:36:50 +08:00

346 lines
19 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# ZCLAW 功能全景文档
> **版本**: v0.6.2
> **更新日期**: 2026-03-27
> **项目状态**: 完整 Rust Workspace 架构，10 个核心 Crates，69 技能，Pipeline DSL + Smart Presentation + Agent Growth System
> **整体完成度**: ~58% (基于 2026-03-27 深度审计 + P0/P1 修复后)
> **架构**: Tauri 桌面应用，Rust Workspace (10 crates) + React 前端
>
> **审计修复 (2026-03-27)**: 修复 2 个 CRITICAL + 4 个 HIGH + 1 个 MEDIUM 问题，详见 [DEEP_AUDIT_REPORT.md](./DEEP_AUDIT_REPORT.md)
> **重要**: ZCLAW 采用 Rust Workspace 架构，包含 10 个分层 Crates (types → memory → runtime → kernel → skills/hands/protocols/pipeline/growth/channels)，所有核心能力集成在 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 系统 | L3 (60%) | 中 |
| 工作流引擎 | 工作流引擎 | 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 (55%) | ✅ 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 阈值)。反思引擎已修复空记忆 bug (C2)，现在从 VikingStorage 查询真实记忆进行分析。已清理死代码: 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 命令 |
| 内置技能 | 内置技能 (**69** SKILL.md) | L3 (75%) | N/A |
| 技能发现 | 技能发现 (动态扫描) | **L3** (80%) | ✅ **已集成** |
> ✅ **更新 (2026-03-27)**: Skills 动态扫描已实现。Kernel 集成 `SkillRegistry`，通过 Tauri 命令 `skill_list` 和 `skill_refresh` 动态发现所有 **69 个**技能。**新增 `execute_skill` 工具**，允许 Agent 在对话中直接调用技能。**PromptOnly 技能已集成 LLM 调用**（通过 `LlmCompleter` trait 桥接 `LlmDriver`），直接执行技能时现在会产生 AI 生成内容。
### 1.6 Hands 系统 - ✅ 7/9 完整实现 + 审批流程 (2026-03-27 更新)
| 文档 | 功能 | 成熟度 | 可用 Hands |
|------|------|--------|-----------|
| [00-hands-overview.md](05-hands-system/00-hands-overview.md) | Hands 概述 (9个) | L3 (60%) | **7/9 (78%)** |
> ✅ **更新 (2026-03-27)**:
> - 7 个 Hands 有完整 Rust 后端实现 (Browser, Collector, Researcher, Slideshow, Whiteboard, Quiz)
> - ✅ **审批流程**: `hand_execute` 现在检查 `needs_approval`，需审批的 hand 返回 `pending_approval` 状态
> - ✅ **演示标记**: SpeechHand、TwitterHand 已添加 `"demo"` 标签
> - ✅ **幽灵命令修复**: `hand_get`、`hand_run_status`、`hand_run_list` 已注册为桩命令
> - ⚠️ **SpeechHand**、**TwitterHand** 标记为 demo 模式（模拟实现）
> - ⚠️ **Clip** 需要 FFmpeg
### 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** | **10** (types, memory, runtime, kernel, skills, hands, protocols, pipeline, growth, channels) |
| **SKILL.md 文件** | **69** |
| 动态发现技能 | 69 (100%) |
| Hands 总数 | 9 |
| **已实现 Hands** | **7 (78%)** — 2 个标记为 demo |
| **Kernel 注册 Hands** | **9/9 (100%)** |
| **Pipeline 模板** | **5** (教育/营销/法律/研究/生产力) |
| Zustand Store | **14** |
| Tauri 命令 | **100+** |
| 代码行数 (前端) | ~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-27 | v0.6.2 | **审计修复 (P0/P1)**: C1 PromptOnly LLM 集成、C2 反思引擎空记忆修复、H7 Agent Store 接口适配、H8 Hand 审批检查、M1 幽灵命令注册、H1/H2 demo 标记、H5 归档过时报告。整体完成度 50%→58%。|
| 2026-03-27 | v0.6.1 | **功能完整性修复**: 激活 LoopGuard 循环防护、实现 CapabilityManager.validate() 安全验证、handStore/workflowStore KernelClient 适配器、Credits 标注开发中、Skills 动态化、ScheduledTasks localStorage 降级、token 用量追踪 |
| 2026-03-27 | v0.6.0a | **全面审计更新**：所有成熟度标注调整为实际完成度 (平均 68%)，新增清理记录 |
| 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-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 | 初始版本，完成全部功能文档 |
---
## 七、清理记录 (2026-03-27)
### 7.1 审计修复 (P0/P1)
| 修复项 | ID | 说明 |
|--------|-----|------|
| PromptOnly LLM 集成 | C1 | 定义 `LlmCompleter` trait，通过 `LlmDriverAdapter` 桥接，PromptOnly 技能现在调用 LLM |
| 反思引擎空记忆 | C2 | 新增 `query_memories_for_reflection()`，reflect() 现在接收真实记忆数据 |
| Agent Store 适配 | H7 | `KernelClient` 添加 `listClones/createClone/deleteClone` 适配方法 |
| Hand 审批检查 | H8 | `hand_execute` 执行前检查 `needs_approval`，需审批返回 pending 状态 |
| 幽灵命令注册 | M1 | 注册 `hand_get/hand_run_status/hand_run_list` 三个 Tauri 桩命令 |
| SpeechHand demo 标记 | H1 | 添加 `"demo"` 标签到 speech.rs 和 speech.HAND.toml |
| TwitterHand demo 标记 | H2 | 添加 `"demo"` 标签到 twitter.rs 和 twitter.HAND.toml |
| 归档过时报告 | H5 | VERIFICATION_REPORT.md 顶部添加归档声明 |
### 7.2 代码清理
| 清理项 | 说明 |
|--------|------|
| 移除 8 个 OpenClaw 兼容别名 | `gateway_*` 系列废弃函数 |
| 清理 7 个 dead_code 方法 | `generation.rs` 中未使用的代码 |
| 替换 println! 为 tracing | `pipeline_commands.rs` 日志规范化 |
| 新增 LLM 摘要支持 | Compactor 现支持 LLM 驱动的上下文压缩 |
| 禁用 Predictor/Lead | HAND.toml 保留但标记无 Rust 后端 |
| 标记 Wasm/Native SkillMode | 明确标注为尚未实现 |
| 清理 browser/mod.rs | 移除未使用的 re-exports |
| 清理 5 个死代码模块 | pattern_detector, recommender, mesh, persona_evolver, trigger_evaluator |
| 激活 LoopGuard | AgentLoop 循环防护已接入 (warn/block/circuit_breaker) |
| 实现 CapabilityManager.validate() | 安全验证：ToolAll+AgentKill、ToolAll+ShellExec(*) 组合拒绝 |
| 删除 Predictor/Lead HAND.toml | 无 Rust 实现的配置文件已彻底删除 |
| Credits.tsx 标注开发中 | 移除假数据，显示"开发中"占位 |
| Skills.tsx 动态化 | 移除硬编码系统技能卡片，改为从 skillsCatalog 动态加载 |
| ScheduledTasks 持久化 | 添加 localStorage 降级，刷新不丢失 |
| Token 用量追踪 | chatStore 新增 addTokenUsage/getTotalTokens |
> **审计说明**: 成熟度等级已根据代码审计调整为实际值。Identity Evolution 标注为 L2 (70%) 是因为其 `dead_code` 属性属于 Tauri 运行时模式（在 Tauri 上下文中实际被调用），而非真正的死代码。Reflection Engine L2 (65%) 因核心反思逻辑尚未深度迭代。
Reference in New Issue View Git Blame Copy Permalink