zclaw_openfang/docs/features

ZCLAW 功能全景文档

版本: v0.6.4 更新日期: 2026-03-27 项目状态: 完整 Rust Workspace 架构，10 个核心 Crates，69 技能，Pipeline DSL + Smart Presentation + Agent Growth System 整体完成度: ~72% (基于 2026-03-27 深度审计 + 四轮修复后) 架构: Tauri 桌面应用，Rust Workspace (10 crates) + React 前端

审计修复 (2026-03-27): 累计修复 23 项 (P0×3 + P1×8 + P2×7 + 误判×2 + 审计×3)，详见 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	通信层	L3 (85%)	高
02-state-management.md	状态管理	L3 (80%)	高
03-security-auth.md	安全认证	L2-L3 (75%)	高

1.2 核心功能 (Core Features)

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

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

文档	功能	成熟度	聊天集成	后端状态
00-agent-memory.md	Agent 记忆	L3-L4 (90%)	✅ pre-hook (FTS5+TF-IDF+Embedding)	✅ SqliteStorage
01-identity-evolution.md	身份演化	L2 (70%)	✅ pre-hook (SOUL.md → system prompt)	✅ Rust 实现
06-context-compaction.md	上下文压缩	L2-L3 (75%)	✅ 已接入内核 (AgentLoop, LLM 摘要)	✅ Rust 实现
03-reflection-engine.md	自我反思	L2 (60%)	✅ post-hook (自动触发 + 真实记忆 + 持久化)	✅ Rust 实现
心跳巡检	心跳巡检	L2-L3 (70%)	✅ post-hook (record_interaction + VikingStorage 持久化)	✅ Rust 实现
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 查询真实记忆进行分析。反思结果和状态已持久化到 VikingStorage metadata，重启后自动恢复 (H4/M4)。心跳引擎交互记录已持久化，idle-greeting 检查跨重启生效 (H4)。记忆系统已统一到 VikingStorage 单一存储 (H3)。已清理死代码: pattern_detector、recommender、mesh、persona_evolver、trigger_evaluator。

1.4 上下文数据库 (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	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	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	后端集成	L3 (80%)	高
安全存储	安全存储	L3 (80%)	高
本地 Gateway	本地 Gateway	L3 (80%)	高

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

文档	功能	成熟度	UI 集成
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 | 🧠 头脑风暴见 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	✅ 完成 (Session + Global 双模式)
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.4	审计修复 (P2 第四轮): S9 消息搜索跨会话 (Session + Global 双模式，VikingStorage 搜索)、M5-补 自主授权后端守卫、M3 hand_approve 参数修复、M4-补 反思历史累积存储、心跳历史持久化。累计修复 23 项，整体完成度 65%→72%。
2026-03-27	v0.6.3	审计修复 (P1/P2): H3 记忆双存储统一到 VikingStorage、H4 心跳引擎持久化 + 启动恢复、M4 反思结果持久化。整体完成度 58%→62%。
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 审计修复 (P1/P2 第二轮)

修复项	ID	说明
记忆双存储统一	H3	完全重写 memory_commands.rs，统一委派到 VikingStorage，移除 PersistentMemoryStore 双写
心跳引擎持久化	H4	record_interaction() 持久化到 VikingStorage metadata，heartbeat_init() 启动时恢复
反思结果持久化	M4	reflect() 后持久化 ReflectionState/Result 到 VikingStorage，重启后自动恢复
清理 dead_code warnings	—	PersistentMemoryStore impl 添加 #[allow(dead_code)]，移除未使用的 build_uri

7.3 审计修复 (P2 第四轮)

修复项	ID	说明
自主授权后端守卫	M5-补	hand_execute/skill_execute 接收 autonomy_level 参数，三级守卫 (supervised/assisted/autonomous)
hand_approve 参数	M3	移除 _ 前缀，添加审计日志，返回值包含 hand_name
反思历史累积	M4-补	新增 reflection:history:{agent_id} 数组(最多 20 条)，向后兼容 reflection:latest
心跳历史持久化	—	tick() 同步存储历史到 VikingStorage，heartbeat_init() 恢复历史
身份回滚 UI	—	确认 IdentityChangeProposal.tsx 已实现 HistoryItem + restoreSnapshot
跨会话消息搜索	S9	MessageSearch 新增 Session/Global 双模式，Global 调用 memory_search 搜索 VikingStorage

7.4 代码清理

清理项	说明
移除 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%) 因核心反思逻辑尚未深度迭代。累计修复 23 项后整体完成度从 ~50% 提升到 ~72%。