iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
4aa3f884ecb3a0a07a6d9cce10f3162fb0a4c0b6
zclaw_openfang/docs/features/README.md
iven eb956d0dce
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
feat: 新增管理后台前端项目及安全加固 
refactor(saas): 重构认证中间件与限流策略
- 登录限流调整为5次/分钟/IP
- 注册限流调整为3次/小时/IP
- GET请求不计入限流

fix(saas): 修复调度器时间戳处理
- 使用NOW()替代文本时间戳
- 兼容TEXT和TIMESTAMPTZ列类型

feat(saas): 实现环境变量插值
- 支持${ENV_VAR}语法解析
- 数据库密码支持环境变量注入

chore: 新增前端管理界面
- 基于React+Ant Design Pro
- 包含路由守卫/错误边界
- 对接58个API端点

docs: 更新安全加固文档
- 新增密钥管理规范
- 记录P0安全项审计结果
- 补充TLS终止说明

test: 完善配置解析单元测试
- 新增环境变量插值测试用例
2026-03-31 00:11:33 +08:00

186 lines
9.7 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.8.1
> **更新日期**: 2026-03-30
> **项目状态**: 完整 Rust Workspace 架构，10 个核心 Crates，70 技能，Pipeline DSL + Smart Presentation + Agent Growth System + SaaS 平台
> **整体完成度**: ~87% (核心功能完整，SaaS 平台全面上线，Worker + Scheduler 系统上线，记忆闭环接通)
---
## 一、文档索引
### 1.1 架构层 (Architecture)
| 文档 | 功能 | 成熟度 | 测试覆盖 |
|------|------|--------|---------|
| [01-communication-layer.md](00-architecture/01-communication-layer.md) | 通信层 (3 种连接模式) | L4 (90%) | 高 |
| [02-state-management.md](00-architecture/02-state-management.md) | 状态管理 | L3 (80%) | 高 |
| [03-security-auth.md](00-architecture/03-security-auth.md) | 安全认证 | L3 (75%) | 高 |
### 1.2 核心功能 (Core Features)
| 文档 | 功能 | 成熟度 | 测试覆盖 |
|------|------|--------|---------|
| [00-chat-interface.md](01-core-features/00-chat-interface.md) | 聊天界面 | L4 (92%) | 高 |
| [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%) | 中 |
### 1.3 智能层 (Intelligence Layer)
| 文档 | 功能 | 成熟度 | 聊天集成 |
|------|------|--------|---------|
| [00-agent-memory.md](02-intelligence-layer/00-agent-memory.md) | Agent 记忆 | L4 (90%) | pre-hook (FTS5+TF-IDF+Embedding) |
| [01-identity-evolution.md](02-intelligence-layer/01-identity-evolution.md) | 身份演化 | L3 (90%) | pre-hook (SOUL.md) |
| [06-context-compaction.md](02-intelligence-layer/06-context-compaction.md) | 上下文压缩 | L4 (90%) | 内核中间件链集成 (CompactionMiddleware) |
| [03-reflection-engine.md](02-intelligence-layer/03-reflection-engine.md) | 自我反思 | L3 (85%) | post-hook (自动触发) |
| [04-heartbeat-engine.md](02-intelligence-layer/04-heartbeat-engine.md) | 心跳巡检 | L3 (90%) | post-hook (持久化) |
| [05-autonomy-manager.md](02-intelligence-layer/05-autonomy-manager.md) | 自主授权 | L3 (75%) | RightPanel UI |
### 1.4 上下文数据库 (Context Database)
| 文档 | 功能 | 成熟度 | 测试覆盖 |
|------|------|--------|---------|
| [00-openviking-integration.md](03-context-database/00-openviking-integration.md) | OpenViking 集成 | L3 (70%) | 高 |
### 1.5 Skills 生态
| 文档 | 功能 | 成熟度 | UI 集成 |
|------|------|--------|---------|
| [00-skill-system.md](04-skills-ecosystem/00-skill-system.md) | Skill 系统概述 | L3 (80%) | Tauri 命令 |
| [01-intelligent-routing.md](04-skills-ecosystem/01-intelligent-routing.md) | 智能路由 | L2 (50%) | 意图路由 |
> 技能总数: **70** 个 SKILL.md，3 种执行模式 (PromptOnly/Shell/Python)，Wasm/Native 待实现
### 1.6 Hands 系统
| 文档 | 功能 | 成熟度 | 可用 Hands |
|------|------|--------|-----------|
| [00-hands-overview.md](05-hands-system/00-hands-overview.md) | Hands 概述 | L3 (60%) | 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](06-tauri-backend/00-backend-integration.md) | 后端集成 | L4 (85%) | **130+** (kernel 34 + pipeline 10 + browser 22 + intelligence 35 + memory 14 + cli 13 + viking 13 + llm 3 + secure_storage 4) |
### 1.8 Pipeline DSL
| 文档 | 功能 | 成熟度 | UI 集成 |
|------|------|--------|---------|
| [00-pipeline-overview.md](07-pipeline-dsl/00-pipeline-overview.md) | Pipeline 概述 | L3 (75%) | PipelinesPanel |
### 1.9 SaaS 平台
| 文档 | 功能 | 成熟度 | API 路由 |
|------|------|--------|---------|
| [00-saas-overview.md](08-saas-platform/00-saas-overview.md) | SaaS 平台总览 | L4 (97%) | **76+** (9 个模块) |
> SaaS 后端: Axum + PostgreSQL, 9 模块 (Auth, Account, Model Config, Relay, Migration, Role, Prompt OTA, Agent Template, Telemetry), Admin 管理后台, 桌面端完整集成
>
> **架构重构成果 (Phase 0-4)**:
> - **Worker 系统**: 5 个 Worker (log_operation, cleanup_rate_limit, cleanup_refresh_tokens, record_usage, update_last_used)，基于 mpsc channel 的异步调度，支持自动重试
> - **声明式 Scheduler**: TOML 配置定时任务，支持 run_on_start、灵活间隔 (30s/5m/1h/1d)，无需改代码调整调度
> - **SQL 迁移系统**: Schema v6，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 文件** | **70** |
| **Hands 总数** | **11** (9 启用, 2 禁用: Predictor, Lead) |
| **Pipeline 模板** | **5** |
| **Tauri 命令** | **130+** |
| **SaaS API 路由** | **76+** |
| **SaaS Workers** | **5** (log_operation, cleanup_rate_limit, cleanup_refresh_tokens, record_usage, update_last_used) |
| **SQL Schema 版本** | **v6** (TIMESTAMPTZ 类型, 声明式迁移) |
| **Zustand Store** | **14+** |
| **LLM Provider** | **8** (Kimi, Qwen, DeepSeek, Zhipu, OpenAI, Anthropic, Gemini, Local) |
| **Embedding Provider** | **6** (OpenAI, Zhipu, Doubao, Qwen, DeepSeek, Local/TF-IDF) |
| **SaaS 数据表** | **25** (PostgreSQL) |
| **内置工具** | **5** (file_read, file_write, shell_exec, web_fetch, execute_skill) |
| **Agent Growth System** | SqliteStorage + FTS5 + TF-IDF + Memory Extractor + ExtractionAdapter (闭环) |
---
## 三、Crate 依赖关系
```
zclaw-types (L1: 基础类型, 无依赖) — 95%
↑
zclaw-memory (L2: 存储层, SQLite) — 90%
↑
zclaw-runtime (L3: 运行时, 4 Driver, 5 工具) — 90%
↑
zclaw-kernel (L4: 核心协调, 11 Hands, 70 Skills) — 85%
↑
┌───┴───┬───────┬───────────┬──────────┬────────┐
│ │ │ │ │ │
skills hands protocols pipeline growth
(80%) (85%) (75%) (90%) (95%) (已移除)
zclaw-saas — 独立运行 (Axum + PostgreSQL, 端口 8080) — 97%
```
---
## 四、SaaS 平台模块
| 模块 | API 路由 | 核心能力 |
|------|---------|---------|
| Auth | 8 | JWT + API Token 双认证, TOTP 2FA (AES-256-GCM), 密码修改 |
| Account | 12 | CRUD, 角色管理, 设备注册/心跳, Dashboard, API Token |
| Model Config | 14 | Provider/Model/Key CRUD, Key 轮换, 用量统计 |
| Relay | 9 | SSE 流式中转, Key 池 (RPM/TPM), 重试策略, SSRF 防护 |
| Migration | 9 | 配置 CRUD, 种子数据, push/merge/diff/pull 同步 |
| Role | 7 | 角色 CRUD, 权限模板, 批量应用 |
| Prompt OTA | 8 | 模板 + 版本管理, OTA 检查, 回滚 |
| Agent Template | 5 | 模板 CRUD, tools/capabilities/model 绑定 |
| Telemetry | 4 | Token 用量上报, 统计聚合, 审计摘要 |
| **Worker 系统** | — | 5 个后台 Worker (log_operation, cleanup_rate_limit, cleanup_refresh_tokens, record_usage, update_last_used)，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-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](./DEEP_AUDIT_REPORT.md)
Reference in New Issue View Git Blame Copy Permalink