From e7b2d1c0994d623c0dfd13c303b5ee444df5008c Mon Sep 17 00:00:00 2001 From: iven Date: Mon, 30 Mar 2026 18:32:02 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=A1=E8=AE=A1=E5=90=8E=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E5=90=8C=E6=AD=A5=20=E2=80=94=20feature-checklist/roa?= =?UTF-8?q?dmap/technical-reference=20=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - feature-checklist: 新增 Admin V2 章节(12项全通过)，Speech/Twitter 状态提升， Hands 9/11 可用，安全备注更新 - roadmap: 标记 S1/S3 审批/Hand 为已完成，更新 crate 数量(10)， 新增审计/依赖/清理已完成项 - technical-reference: 更新日期至 03-30，crate 数量 10 --- docs/features/roadmap.md | 24 +++++---- docs/knowledge-base/README.md | 3 ++ docs/knowledge-base/feature-checklist.md | 49 ++++++++++++++----- .../zclaw-technical-reference.md | 6 +-- 4 files changed, 56 insertions(+), 26 deletions(-) diff --git a/docs/features/roadmap.md b/docs/features/roadmap.md index c9e49ef..52d66ff 100644 --- a/docs/features/roadmap.md +++ b/docs/features/roadmap.md @@ -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 文件) | ✅ 完成 | --- diff --git a/docs/knowledge-base/README.md b/docs/knowledge-base/README.md index 2975ecb..53c0a79 100644 --- a/docs/knowledge-base/README.md +++ b/docs/knowledge-base/README.md @@ -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 对比分析 | diff --git a/docs/knowledge-base/feature-checklist.md b/docs/knowledge-base/feature-checklist.md index 34d179c..4682123 100644 --- a/docs/knowledge-base/feature-checklist.md +++ b/docs/knowledge-base/feature-checklist.md @@ -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 级别验证 | diff --git a/docs/knowledge-base/zclaw-technical-reference.md b/docs/knowledge-base/zclaw-technical-reference.md index 777c387..3bfc61c 100644 --- a/docs/knowledge-base/zclaw-technical-reference.md +++ b/docs/knowledge-base/zclaw-technical-reference.md @@ -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 |