zclaw_openfang/docs/features

ZCLAW 功能全景文档

版本: v0.10.0 更新日期: 2026-04-06 项目状态: 完整 Rust Workspace 架构，10 个核心 Crates，75 技能，Pipeline DSL + Smart Presentation + Agent Growth System + SaaS 平台 + DeerFlow 2.0 核心能力 (ask_clarification 工具, 澄清系统, 渐进式技能加载, 模式差异化行为) + 安全审计 V1 完成 整体完成度: ~90% (核心功能完整，SaaS 平台全面上线，DeerFlow 前端视觉复刻完成，安全渗透测试 15 项修复完成，Admin V2 迁移完成)

---

一、文档索引

1.1 架构层 (Architecture)

文档	功能	成熟度	测试覆盖
01-communication-layer.md	通信层 (3 种连接模式)	L4 (90%)	高
02-state-management.md	状态管理	L4 (90%)	高
03-security-auth.md	安全认证	L4 (95%)	高

1.2 核心功能 (Core Features)

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

1.3 智能层 (Intelligence Layer)

文档	功能	成熟度	聊天集成
00-agent-memory.md	Agent 记忆	L4 (90%)	pre-hook (FTS5+TF-IDF+Embedding)
01-identity-evolution.md	身份演化	L4 (90%)	pre-hook (SOUL.md)
06-context-compaction.md	上下文压缩	L4 (90%)	内核中间件链集成 (CompactionMiddleware)
03-reflection-engine.md	自我反思	L4 (85%)	post-hook (自动触发)
04-heartbeat-engine.md	心跳巡检	L4 (90%)	post-hook (持久化)
05-autonomy-manager.md	自主授权	L4 (80%)	RightPanel UI

1.4 上下文数据库 (Context Database)

文档	功能	成熟度	测试覆盖
00-openviking-integration.md	OpenViking 集成	L3 (70%)	高

1.5 Skills 生态

文档	功能	成熟度	UI 集成
00-skill-system.md	Skill 系统概述	L4 (85%)	Tauri 命令
01-intelligent-routing.md	智能路由	L3 (60%)	意图路由

技能总数: 75 个 SKILL.md，3 种执行模式 (PromptOnly/Shell/Python)，Wasm/Native 待实现

1.6 Hands 系统

文档	功能	成熟度	可用 Hands
00-hands-overview.md	Hands 概述	L4 (85%)	11 个 (9 启用 + 2 禁用)

11 Hands (9 启用): Browser, Slideshow, Speech, Quiz, Whiteboard, Researcher, Collector, Clip, Twitter (需 API Key); 2 禁用: Predictor, Lead

1.7 Tauri 后端

文档	功能	成熟度	Tauri 命令
00-backend-integration.md	后端集成	L4 (85%)	177 (160 @connected + 16 @reserved + 1 unregistered identity_init)

1.8 Pipeline DSL

文档	功能	成熟度	UI 集成
00-pipeline-overview.md	Pipeline 概述	L3 (75%)	PipelinesPanel

1.9 SaaS 平台

文档	功能	成熟度	API 路由
00-saas-overview.md	SaaS 平台总览	L4 (98%)	131 (12 个模块)

SaaS 后端: Axum + PostgreSQL, 12 模块 (Auth, Account, Model Config, Relay, Migration, Role, Prompt OTA, Agent Template, Scheduled Task, Telemetry, Billing, Knowledge), Admin V2 管理后台 (Ant Design Pro), 桌面端完整集成

架构重构成果 (Phase 0-4):

• Worker 系统: 7 个 Worker (log_operation, cleanup_rate_limit, cleanup_refresh_tokens, record_usage, update_last_used, aggregate_usage, generate_embedding)，基于 mpsc channel 的异步调度，支持自动重试
• 声明式 Scheduler: TOML 配置定时任务，支持 run_on_start、灵活间隔 (30s/5m/1h/1d)，无需改代码调整调度
• SQL 迁移系统: Schema v8，TIMESTAMPTZ 时间戳类型，从 migrations/ 目录加载 SQL 文件，向后兼容 TEXT 类型旧库
• 多环境配置: ZCLAW_ENV 环境选择 (development/production/test)，ZCLAW_SAAS_CONFIG 精确路径，ZCLAW_DATABASE_URL 覆盖
• 连接池优化: 50 max / 5 min 连接，10s 获取超时，300s 空闲超时，1800s 最大生命周期
• 速率限制优化: 无锁 AtomicU32 读取 RPM，DashMap + 60s 滑动窗口，300s 定期清理

记忆闭环修复:

• extraction_adapter.rs: 实现 TauriExtractionDriver，将 Kernel 的 LlmDriver 桥接为 LlmDriverForExtraction trait
• 对话 → 记忆提取 → 存储 → 检索 → 注入 → 增强回复 的完整闭环已接通

---

二、关键指标

指标	数值
Rust Crates	10 (types, memory, runtime, kernel, skills, hands, protocols, pipeline, growth, saas)
SKILL.md 文件	75
Hands 总数	11 (9 启用, 2 禁用: Predictor, Lead)
Pipeline 模板	17 YAML
Tauri 命令	177
SaaS API 路由	131 (含 2 个 dev-only mock)
SaaS Workers	7 (log_operation, cleanup_rate_limit, cleanup_refresh_tokens, record_usage, update_last_used, aggregate_usage, generate_embedding)
SQL Schema 版本	v8 (TIMESTAMPTZ 类型, 声明式迁移, password_version, rate_limit_events, is_embedding)
Zustand Store	18
LLM Provider	8 (Kimi, Qwen, DeepSeek, Zhipu, OpenAI, Anthropic, Gemini, Local)
Embedding Provider	6 (OpenAI, Zhipu, Doubao, Qwen, DeepSeek, Local/TF-IDF)
SaaS 数据表	34 (PostgreSQL)
内置工具	7 (file_read, file_write, shell_exec, web_fetch, execute_skill, skill_load, task)
Agent Growth System	SqliteStorage + FTS5 + TF-IDF + Memory Extractor + ExtractionAdapter (闭环)
安全审计	渗透测试 V1: 5 HIGH + 10 MEDIUM 全部修复, 整体评级 B+
Admin V2	Vite + React + Ant Design Pro, 15 页面, HttpOnly Cookie 认证
运行时中间件	11 层: Compaction, Memory, LoopGuard, TokenCalibration, SkillIndex, Title, DanglingTool, ToolError, ToolOutputGuard, Guardrail, SubagentLimit

---

三、Crate 依赖关系

zclaw-types          (L1: 基础类型, 无依赖) — 95%
    ↑
zclaw-memory         (L2: 存储层, SQLite + FactStore) — 92%
    ↑
zclaw-runtime        (L3: 运行时, 4 Driver, 7 工具, 11 层中间件) — 92%
    ↑
zclaw-kernel         (L4: 核心协调, 9 Hands, 75 Skills, Trigger, Export, Clarification) — 88%
    ↑
┌───┴───┬───────┬───────────┬──────────┐
│       │       │           │          │
skills  hands  protocols  pipeline  growth
(85%)   (88%)  (80%)      (95%)     (95%)

zclaw-saas — 独立运行 (Axum + PostgreSQL, 端口 8080) — 98%

---

四、SaaS 平台模块

模块	API 路由	核心能力
Auth	9	JWT + API Token 双认证, TOTP 2FA (AES-256-GCM), 密码修改, HttpOnly Cookie
Account	12	CRUD, 角色管理, 设备注册/心跳, Dashboard, API Token
Model Config	9	Provider/Model/Key CRUD, Key 轮换, 用量统计
Relay	9	SSE 流式中转, Key 池 (RPM/TPM), 重试策略, SSRF 防护
Migration	8	配置 CRUD, 种子数据, push/merge/diff/pull 同步
Role	6	角色 CRUD, 权限模板, 批量应用
Prompt OTA	6	模板 + 版本管理, OTA 检查, 回滚
Agent Template	10	模板 CRUD, tools/capabilities/model 绑定, SOUL.md, 行业模板分配
Scheduled Task	2	定时任务 CRUD
Telemetry	4	Token 用量上报, 统计聚合, 审计摘要
Billing	10	计费计划/订阅/用量/支付 (含 2 个 dev-only mock)
Knowledge	23	知识库分类/条目/版本/搜索/推荐/分析
Worker 系统	—	7 个后台 Worker (log_operation, cleanup_rate_limit, cleanup_refresh_tokens, record_usage, update_last_used, aggregate_usage, generate_embedding)，mpsc 异步调度，自动重试
声明式 Scheduler	—	TOML 配置定时任务，灵活间隔 (30s/5m/1h/1d)，run_on_start，内置 DB 清理 (设备 90 天)

---

五、连接模式

模式	客户端	说明
Mode A: Tauri Kernel	KernelClient	本地直连 LLM (默认模式)
Mode B: Gateway	GatewayClient	WebSocket 本地中转
Mode C: SaaS Cloud	SaaSClient (30+ 方法)	云端中转 + Key 池管理

---

六、变更历史

日期	版本	变更内容
2026-04-06	v0.11.0	DeerFlow 2.0 核心能力借鉴：(1) ask_clarification 工具 + ClarificationMiddleware + ClarificationCard 前端渲染 (2) 渐进式技能加载 — 只注入元数据 + load_skill_content 工具 (3) 模式差异化行为 — Ultra 启用子Agent (4) present_file Artifact 输出物接通 (5) 子Agent 流式进度推送 (6) ask_clarification 澄清系统 (7) 子Agent 唯一 ID 匹配 (task_id 贯穿 6 层) (8) AgentState 序列化 lowercase 修复 (9) pre-existing TS errors 清理
2026-04-03	v0.10.2	行业模板二次深度审计修复：3CRITICAL+6HIGH 全修复 — createFromTemplate 接入后端 API (tools 合并/source_template_id)、种子数据 source='builtin'、不可变 clone 返回、restoreSession 恢复 assignedTemplate、logout 清理模板状态、assignTemplate 错误传播、输入验证、删除死路由、console.warn→logger、model fallback gpt-4o-mini、pgvector 可选、relay 超时 90s
2026-04-03	v0.10.1	数字校准：SaaS API 58→131（新增 knowledge 23 + billing 10 + model_config 16 等）、SaaS Workers 5→7、SaaS 模块 10→12、数据表 25→34、Tauri 命令 175→171（注释排除）、SKILL 76→75、Admin 页面 11→13
2026-04-01	v0.10.0	文档全面更新：SKILL 数量 75、Tauri 命令 130+、API 路由 72+、Admin V2 (Ant Design Pro) 迁移记录、安全渗透测试 V1 修复记录、Schema v8、11 层中间件链、kernel.rs 拆分为 9 子模块、intelligence-client.ts 拆分为 9 子模块
2026-04-01	v0.9.0	DeerFlow 前端视觉复刻：卡片式输入框、下拉模式选择器（闪速/思考/Pro/Ultra）、彩色快捷操作芯片、极简顶栏+token计数+导出、暖灰色系全局样式（#faf9f6/#f5f4f1/#e8e6e1）、DeerFlow 风格侧边栏、推理/工具链/子任务可视化、Artifact 右侧面板、虚拟化消息列表、Gateway 流式 hang 修复（onclose code 1000 → onComplete）、WebView2 textarea 边框修复（CSS !important）
2026-03-30	v0.8.1	Sprint 5 "稳定清扫": Axum CLOSE_WAIT 修复 (CancellationToken + TCP keepalive + SO_LINGER)，E2E 测试重新启用 (去掉 test.skip)，dead code 注解审计 (36→<10)
2026-03-29	v0.8.0	SaaS 后端架构重构完成：Worker 系统 (5 Worker + mpsc 异步调度)，声明式 Scheduler (TOML 配置)，SQL 迁移系统 (Schema v6 + TIMESTAMPTZ)，多环境配置 (ZCLAW_ENV)，连接池优化 (50 max/5 min)，速率限制优化 (无锁 AtomicU32)；记忆闭环修复：extraction_adapter.rs 实现 TauriExtractionDriver，BREAK-01 已修复
2026-03-29	v0.7.0	文档同步：SKILL 数量 70, Tauri 命令 130+ (含 Browser/Intelligence/Memory/CLI/SecureStorage), Hands 11 (9 启用+2 禁用), 智能层完成度修正
2026-03-28	v0.7.0	基于 2026-03-28 代码状态全面更新：SaaS 平台 76+ API 路由/9 模块/25 表，58+ Tauri 命令，8 LLM Provider，3 种连接模式
2026-03-27	v0.6.4	审计修复第四轮，S9 消息搜索跨会话，自主授权后端守卫
2026-03-27	v0.6.0	深度审计更新，整体完成度调整
2026-03-26	v0.1.0	v1.0 发布准备，移除 Team/Swarm
2026-03-25	v0.5.0	Smart Presentation Layer
2026-03-25	v0.4.0	代码现状深度分析
2026-03-24	v0.3.0	Pipeline DSL 系统实现

---

七、清理记录

详见 DEEP_AUDIT_REPORT.md