iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: 审计后文档同步 — feature-checklist/roadmap/technical-reference 更新

Browse Source 
- feature-checklist: 新增 Admin V2 章节(12项全通过)，Speech/Twitter 状态提升，
  Hands 9/11 可用，安全备注更新
- roadmap: 标记 S1/S3 审批/Hand 为已完成，更新 crate 数量(10)，
  新增审计/依赖/清理已完成项
- technical-reference: 更新日期至 03-30，crate 数量 10
This commit is contained in:
iven
2026-03-30 18:32:02 +08:00
parent 88aa4b1310
commit e7b2d1c099
4 changed files with 56 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
docs/features/roadmap.md
View File

@@ -1,9 +1,9 @@
# ZCLAW 后续工作计划
> **版本**: v0.7.0
> **更新日期**: 2026-03-28
> **基于**: 2026-03-28 代码分析
> **状态**: 核心功能完整，SaaS 平台上线
> **更新日期**: 2026-03-30
> **基于**: 2026-03-30 审计后代码分析
> **状态**: 核心功能完整，审计修复完成，SaaS 平台上线
---
@@ -13,12 +13,12 @@
| 指标 | 状态 |
|------|------|
| Rust Crates | **11 个** (types, memory, runtime, kernel, skills, hands, protocols, pipeline, growth, channels, saas) |
| Rust Crates | **10 个** (types, memory, runtime, kernel, skills, hands, protocols, pipeline, growth, saas) |
| 功能完成度 | 核心功能 90-95%，整体 ~85% |
| 技能数量 | 69 SKILL.md |
| Hands 可用 | 9 (编程式注册，2 个标记 demo) |
| Hands 可用 | 9 (7 完整 + Speech/Twitter 真实实现，2 个标记 demo) |
| Pipeline DSL | 完整实现 (5 模板 + Smart Presentation) |
| SaaS 平台 | 完整实现 (76+ API, 9 模块, 25 数据表) |
| SaaS 平台 | 完整实现 (76+ API, 9 模块, 25 数据表, 连接池断路器) |
| Tauri 命令 | 58+ (kernel 29 + pipeline 13 + viking 13 + llm 3) |
| LLM Provider | 8 个 (含 Gemini) |
| 连接模式 | 3 种 (Kernel / Gateway / SaaS) |
@@ -38,7 +38,7 @@
| zclaw-pipeline | L5 | 95% | DSL + Smart Presentation |
| zclaw-growth | L5 | 95% | FTS5 + TF-IDF + Memory Extractor |
| zclaw-saas | 独立 | 95% | Axum + PostgreSQL, 76+ API |
| ~~zclaw-channels~~ | ~~L5~~ | **已移除** | crate 已清理，功能通过飞书 API 实现 |
| ~~zclaw-channels~~ | ~~L5~~ | **已移除** | Batch 7 清理，功能通过飞书 API 实现 |
---
@@ -48,9 +48,9 @@
| ID | 任务 | 预估 | 状态 |
|----|------|------|------|
| S1 | 实现 Approval 管理后端 (非存根) | 4h | 待开始 |
| S1 | 实现 Approval 管理后端 (非存根) | 4h | ✅ 已完成 (P0 KernelClient 修复) |
| S2 | 完善 A2A 协议完整度 | 4h | 待开始 |
| S3 | hand_run_status / hand_run_list 真实实现 | 3h | 待开始 |
| S3 | hand_run_status / hand_run_list 真实实现 | 3h | ✅ 已完成 (P0 KernelClient 修复) |
| S4 | scheduled_task_create 自动执行 | 3h | 待开始 |
### 2.2 P1 - 应该完成
@@ -60,7 +60,7 @@
| S5 | 提升 SaaS 测试覆盖率 | 8h | 待开始 |
| S6 | 完善 MCP 协议工具验证 | 3h | 待开始 |
| S7 | Browser Hand 稳定性增强 | 4h | 待开始 |
| S8 | Admin UI 完善批量操作 | 3h | 待开始 |
| S8 | 定时任务后端持久化 | 4h | 待开始 |
### 2.3 已完成项
@@ -74,6 +74,10 @@
| S7-old | Compactor 接入聊天流程 | ✅ 完成 |
| S9-old | 消息搜索 (Session + Global) | ✅ 完成 |
| S10-old | Rust 错误提示中文化 | ✅ 完成 |
| Audit | P0-P3 全面审计修复 | ✅ 完成 (6 commits) |
| Deps | serde_yaml 迁移 + workspace 统一 | ✅ 完成 |
| Admin | Admin V2 Ant Design Pro 重写 | ✅ 完成 |
| Clean | console.log 清理 (16 文件) | ✅ 完成 |
---

3
docs/knowledge-base/README.md
View File

@@ -7,6 +7,7 @@
```
knowledge-base/
├── README.md # 本文件 - 索引
├── axum-dashmap-deadlock.md # Axum + DashMap 运行时死锁：根因分析与修复
├── zclaw-technical-reference.md # ZCLAW 技术参考
├── websocket-protocol.md # WebSocket 协议文档
├── configuration.md # 配置系统文档
@@ -38,6 +39,7 @@ knowledge-base/
| 连接失败 | [troubleshooting.md](./troubleshooting.md) | 端口、认证、配置 |
| 流式响应不工作 | [troubleshooting.md](./troubleshooting.md) | 事件类型、代理配置 |
| LLM 错误 | [troubleshooting.md](./troubleshooting.md) | API Key 未配置 |
| **运行时死锁** | [axum-dashmap-deadlock.md](./axum-dashmap-deadlock.md) | DashMap/Mutex 锁跨 await、parking_lot 阻塞 worker thread |
### 开发指南
@@ -61,6 +63,7 @@ knowledge-base/
| 日期 | 版本 | 变更 |
|------|------|------|
| 2026-03-30 | v2.3 | 添加 Axum + DashMap 运行时死锁根因分析，含死锁机制、修复方案、防范模式和审计清单 |
| 2026-03-26 | v2.2 | 添加语义记忆审计记录，含可复用的审计方法论和差距模式 |
| 2026-03-26 | v2.1 | 添加 OpenMAIC 深度分析，补充 StreamBuffer、Director、Action 引擎架构 |
| 2026-03-22 | v2.0 | 重构为 ZCLAW 独立产品文档，添加 OpenMAIC 对比分析 |

49
docs/knowledge-base/feature-checklist.md
View File

@@ -2,8 +2,9 @@
> 列出所有功能模块，逐一验证完整性和可用性。
**验证日期**: 2026-03-27
**验证日期**: 2026-03-30
**验证环境**: Windows 11, ZCLAW 0.6.0, Tauri 2.x Desktop
**上次更新后变更**: 10 个 commit（审计修复 P0-P3 + Admin V2 + 依赖健康度）
---
@@ -56,15 +57,15 @@
| Collector | 数据收集聚合 | ✅ 可用 | Rust 后端实现 |
| Researcher | 深度研究 | ✅ 可用 | Rust 后端实现 |
| Slideshow | 幻灯片生成 | ✅ 可用 | Rust 后端实现 |
| Speech | 语音合成 | ✅ 可用 | Rust 后端实现 |
| Speech | 语音合成 | ✅ 可用 | Rust 后端 + Browser TTS 前端集成 |
| Whiteboard | 白板演示 | ✅ 可用 | Rust 后端实现 |
| Quiz | 测验生成 | ✅ 可用 | Rust 后端实现 |
| Predictor | 预测分析 | ❌ 仅有配置 | 无 Rust 后端实现 |
| Lead | 销售线索发现 | ❌ 仅有配置 | 无 Rust 后端实现 |
| Clip | 视频处理 | ⚠️ 需 FFmpeg | 依赖外部 FFmpeg |
| Twitter | Twitter 自动化 | ⚠️ 需 API Key | 依赖 Twitter API Key |
| Twitter | Twitter 自动化 | ✅ 可用 | 12 个 API v2 真实调用（写操作需 OAuth 1.0a） |
> **统计**: 7/11 Hands 可用，2 个无后端，2 个需外部依赖
> **统计**: 9/11 Hands 可用，2 个无后端，1 个需外部依赖
### 5.2 Workflows
@@ -99,10 +100,30 @@
| 安全等级 | `SecurityStatus.tsx` | ⚠️ 前端模拟 | 计算逻辑在前端，非后端 Tauri 命令 |
> **说明**: 安全配置在 `config.toml` 中有完整定义 (auth/rbac/rate_limit/audit)，Tauri 后端有 `secure_storage.rs`，但前端 UI 面板使用 fallback 数据而非真实后端状态。
> 审计修复后：console.log 清理完成（16 文件 23 处 → 结构化 logger），DOMPurify XSS 防护已加回，硬编码密钥 fallback 已标记 dev-only。
## 6. 设置页面
## 6. Admin V2 (管理后台)
### 6.1 通用设置
| 功能 | 组件位置 | 验证状态 | 说明 |
|------|----------|----------|------|
| Dashboard | `Dashboard.tsx` | ✅ 通过 | Ant Design Pro 纯 SPA 重写 |
| Accounts | `Accounts.tsx` | ✅ 通过 | 账号 CRUD |
| Models | `Models.tsx` | ✅ 通过 | 模型管理 |
| Providers | `Providers.tsx` | ✅ 通过 | 提供商管理 |
| API Keys | `ApiKeys.tsx` | ✅ 通过 | 密钥管理 |
| Prompts | `Prompts.tsx` | ✅ 通过 | Prompt 模板 |
| Relay | `Relay.tsx` | ✅ 通过 | 中转管理 |
| Usage | `Usage.tsx` | ✅ 通过 | 用量统计 |
| Logs | `Logs.tsx` | ✅ 通过 | 日志查看 |
| Config | `Config.tsx` | ✅ 通过 | 系统配置 |
| Agent Templates | `AgentTemplates.tsx` | ✅ 通过 | Agent 模板 |
| Error Boundary | `main.tsx` | ✅ 通过 | 审计修复中已添加 |
> **说明**: Admin V2 已从 Next.js 迁移至 Ant Design Pro 纯 SPA (Vite + port 5173)。后端 Axum 已添加连接池断路器（80% → 503 degraded）。
## 7. 设置页面
### 7.1 通用设置
| 功能 | 组件位置 | 验证状态 | 说明 |
|------|----------|----------|------|
@@ -110,7 +131,7 @@
| 主题切换 | App 根组件 | ✅ 通过 | 深色/浅色模式正常 |
| 开机自启 | Tauri 配置 | ⚠️ 待验证 | Tauri 专用功能 |
### 6.2 模型与 API
### 7.2 模型与 API
| 功能 | 组件位置 | 验证状态 | 说明 |
|------|----------|----------|------|
@@ -121,7 +142,7 @@
> **统计**: 共 7 个中文提供商 + 3 个国际提供商 (OpenAI/Anthropic/Gemini) + 1 个本地驱动
### 6.3 其他设置
### 7.3 其他设置
| 功能 | 组件位置 | 验证状态 | 说明 |
|------|----------|----------|------|
@@ -132,7 +153,7 @@
| MCP 服务 | `Settings/MCPServices.tsx` | ❌ API 404 | 后端未实现 |
| 工作区配置 | `Settings/Workspace.tsx` | ❌ API 404 | 后端未实现 |
## 7. 右侧面板
## 8. 右侧面板
| 功能 | 组件位置 | 验证状态 | 说明 |
|------|----------|----------|------|
@@ -141,7 +162,7 @@
| 反思日志 | `ReflectionLog` (RightPanel) | ✅ 通过 | 显示反思分析结果 |
| 安全面板 | `SecurityLayersPanel` (RightPanel) | ⚠️ 前端模拟 | 使用 fallback 数据 |
## 8. 侧边栏
## 9. 侧边栏
| 功能 | 组件位置 | 验证状态 | 说明 |
|------|----------|----------|------|
@@ -152,7 +173,7 @@
---
## 9. 智能层 (Intelligence Layer)
## 10. 智能层 (Intelligence Layer)
| 模块 | Rust 实现 | Tauri 命令 | Hooks 集成 | 完成度 | 说明 |
|------|----------|-----------|-----------|--------|------|
@@ -175,16 +196,17 @@
| 分身管理 | 5 | 4 | 0 | 1 |
| IM 频道 | 3 | 1 | 0 | 2 |
| 定时任务 | 3 | 0 | 1 | 2 |
| Hands | 11 | 7 | 2 | 2 |
| Hands | 11 | 9 | 1 | 1 |
| Workflows | 4 | 3 | 1 | 0 |
| Triggers | 4 | 3 | 1 | 0 |
| 审计日志 | 2 | 0 | 0 | 2 |
| 安全状态 | 2 | 0 | 2 | 0 |
| Admin V2 | 12 | 12 | 0 | 0 |
| 设置页面 | 9 | 6 | 1 | 2 |
| 右侧面板 | 4 | 3 | 1 | 0 |
| 侧边栏 | 4 | 4 | 0 | 0 |
| 智能层 | 6 | 5 | 1 | 0 |
| **总计** | **63** | **42** | **8** | **11** |
| **总计** | **75** | **56** | **8** | **11** |
---
@@ -214,5 +236,6 @@
| 日期 | 变更 |
|------|------|
| 2026-03-30 | 审计后更新：新增 Admin V2 章节(12项全通过)，Speech/Twitter 状态提升，安全备注更新，Hands 9/11 可用 |
| 2026-03-27 | 全面更新至 0.6.0：核心聊天全部通过，新增智能层章节，更新 Hands/Workflows/Triggers 状态，清理过时信息 |
| 2026-03-14 | 初始版本，完成 API 级别验证 |

6
docs/knowledge-base/zclaw-technical-reference.md
View File

@@ -1,7 +1,7 @@
# ZCLAW Kernel 技术参考文档
> **文档版本**: v2.1
> **更新日期**: 2026-03-24
> **文档版本**: v2.2
> **更新日期**: 2026-03-30
> **目标**: 为 ZCLAW 内部 Kernel 架构提供技术参考
---
@@ -13,7 +13,7 @@
| 属性 | 值 |
|------|-----|
| **项目名称** | ZCLAW |
| **架构** | 8 个 Rust Crates 模块化设计 |
| **架构** | 10 个 Rust Crates 模块化设计 |
| **定位** | AI Agent 桌面客户端 |
| **许可** | MIT |