bf6d81f9c6
Some checks failed
CI / Rust Check (push) Has been cancelled
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
style: 统一代码格式和注释风格 docs: 更新多个功能文档的完整度和状态 feat(runtime): 添加路径验证工具支持 fix(pipeline): 改进条件判断和变量解析逻辑 test(types): 为ID类型添加全面测试用例 chore: 更新依赖项和Cargo.lock文件 perf(mcp): 优化MCP协议传输和错误处理
197 lines
6.1 KiB
Markdown
197 lines
6.1 KiB
Markdown
# ZCLAW 项目存量分析与交付优化方案
|
||
|
||
## 上下文
|
||
|
||
**目标**: 对 ZCLAW 项目进行深度和广度的梳理分析，了解项目存量，目标是完善系统并交付上线，不要过度开发和演化。
|
||
|
||
**分析日期**: 2026-03-25
|
||
|
||
**选定方向**: 先完成现有功能，确保核心功能可用
|
||
|
||
**交付必需功能**:
|
||
1. ✅ 文件工具 (file_read/file_write) - 实现路径安全验证
|
||
2. ✅ MCP 客户端集成 - 连接 BasicMcpClient 到 McpTransport
|
||
3. ✅ Triggers/Approvals API - 需要后端+前端配合
|
||
|
||
---
|
||
|
||
## 一、项目存量分析
|
||
|
||
### 1.1 项目规模
|
||
|
||
| 层级 | 组件数量 | 说明 |
|
||
|------|----------|------|
|
||
| 前端组件 | ~100 个 | React + TypeScript |
|
||
| Rust Crates | 8 个 | zclaw-types/memory/runtime/kernel/skills/hands/channels/protocols/pipeline |
|
||
| Rust 源文件 | ~90 个 | 后端核心能力 |
|
||
| 文档 | ~100 个 | 架构、知识库、计划等 |
|
||
| Store | 15+ 个 | Zustand 状态管理 |
|
||
|
||
### 1.2 功能完成度
|
||
|
||
| 功能模块 | 状态 | 说明 |
|
||
|----------|------|------|
|
||
| 聊天界面 | ✅ 完成 | 流式响应、多模型切换 |
|
||
| 分身管理 | ✅ 完成 | 创建、配置、切换 Agent |
|
||
| 自动化面板 | ✅ 完成 | Hands 触发、参数配置 |
|
||
| 技能系统 | ✅ 完成 | SKILL.md 解析、执行器 |
|
||
| Pipeline DSL | ✅ 完成 | 自动化工作流 |
|
||
| Intelligence Layer | ✅ 90% | 已迁移至 Rust，Agent Swarm TODO |
|
||
| MCP 协议 | ⚠️ 部分 | 传输层完成，客户端未集成 |
|
||
| Browser Hand | ✅ 完成 | 浏览器自动化 |
|
||
| Channel 适配器 | ⚠️ 占位 | Telegram/Discord/Slack 未实现 |
|
||
| 文件工具 | ⚠️ 占位 | 读写占位，缺路径验证 |
|
||
| Triggers/Approvals | ❌ 未实现 | 后端有类型定义，无 API |
|
||
|
||
---
|
||
|
||
## 二、待完成功能详细分析
|
||
|
||
### 2.1 文件工具 (file_read/file_write)
|
||
|
||
**现状**:
|
||
- `crates/zclaw-runtime/src/tool/builtin/file_read.rs` - 返回占位内容
|
||
- `crates/zclaw-runtime/src/tool/builtin/file_write.rs` - 返回假成功
|
||
- 安全配置已存在: `config/security.toml` 定义了 `allowed_paths` 和 `blocked_paths`
|
||
|
||
**实现方案**:
|
||
1. 在 ToolContext 中添加路径验证器
|
||
2. 实现 `validate_path()` 函数，检查 allowed/blocked paths
|
||
3. 实现真实的文件读写操作
|
||
4. 添加文件大小限制检查
|
||
|
||
**修改文件**:
|
||
- `crates/zclaw-runtime/src/tool/builtin/file_read.rs`
|
||
- `crates/zclaw-runtime/src/tool/builtin/file_write.rs`
|
||
- `crates/zclaw-runtime/src/tool/mod.rs` (添加 PathValidator)
|
||
|
||
### 2.2 MCP 客户端集成
|
||
|
||
**现状**:
|
||
- `crates/zclaw-protocols/src/mcp_transport.rs` - ✅ 完整实现 stdio 传输
|
||
- `crates/zclaw-protocols/src/mcp.rs` - BasicMcpClient 使用 HTTP，返回占位
|
||
|
||
**实现方案**:
|
||
1. 让 BasicMcpClient 使用 McpTransport 而非 reqwest::Client
|
||
2. 或者创建新的 StdioMcpClient 包装 McpTransport
|
||
|
||
**修改文件**:
|
||
- `crates/zclaw-protocols/src/mcp.rs` - 重构 BasicMcpClient
|
||
|
||
### 2.3 Triggers/Approvals API
|
||
|
||
**现状**:
|
||
- 后端类型定义完整: `crates/zclaw-hands/src/trigger.rs` (TriggerConfig, TriggerType, TriggerState)
|
||
- 前端 API 占位: `desktop/src/lib/kernel-client.ts:771-785` 抛出 "Not implemented"
|
||
- Tauri 命令缺失: 无 trigger/approval 相关命令
|
||
|
||
**实现方案**:
|
||
1. **后端**: 在 zclaw-kernel 添加 trigger/approval 管理
|
||
2. **Tauri**: 添加 trigger_list, trigger_create, trigger_update, trigger_delete 命令
|
||
3. **前端**: 连接 kernel-client 到 Tauri 命令
|
||
|
||
**修改文件**:
|
||
- `crates/zclaw-kernel/src/kernel.rs` - 添加 trigger/approval 方法
|
||
- `desktop/src-tauri/src/kernel_commands.rs` - 添加 Tauri 命令
|
||
- `desktop/src/lib/kernel-client.ts` - 实现前端 API
|
||
|
||
---
|
||
|
||
## 三、实施计划
|
||
|
||
### Phase 1: 文件工具 (预计 2-3 小时)
|
||
|
||
1. 创建 `crates/zclaw-runtime/src/tool/path_validator.rs`
|
||
2. 实现 PathValidator 结构体
|
||
3. 更新 file_read.rs 和 file_write.rs
|
||
4. 添加单元测试
|
||
|
||
### Phase 2: MCP 客户端集成 (预计 1-2 小时)
|
||
|
||
1. 重构 BasicMcpClient 使用 McpTransport
|
||
2. 测试与真实 MCP server 的连接
|
||
|
||
### Phase 3: Triggers/Approvals API - 完整实现 (预计 4-6 小时)
|
||
|
||
**后端实现**:
|
||
1. 创建 `crates/zclaw-kernel/src/trigger_manager.rs`
|
||
- TriggerManager 结构体
|
||
- CRUD 操作 (create, read, update, delete, list)
|
||
- 状态持久化 (SQLite)
|
||
- 触发器执行调度 (tokio::time 定时任务)
|
||
|
||
2. 更新 `crates/zclaw-kernel/src/kernel.rs`
|
||
- 添加 trigger_manager 字段
|
||
- 暴露 trigger 方法
|
||
|
||
**Tauri 命令**:
|
||
3. 更新 `desktop/src-tauri/src/kernel_commands.rs`
|
||
- `trigger_list` - 列出所有触发器
|
||
- `trigger_create` - 创建触发器
|
||
- `trigger_update` - 更新触发器
|
||
- `trigger_delete` - 删除触发器
|
||
- `trigger_get` - 获取单个触发器
|
||
- `approval_list` - 列出待审批
|
||
- `approval_respond` - 响应审批
|
||
|
||
**前端实现**:
|
||
4. 更新 `desktop/src/lib/kernel-client.ts`
|
||
- 实现 listTriggers, createTrigger, updateTrigger, deleteTrigger
|
||
- 实现 listApprovals, respondToApproval
|
||
|
||
5. 更新 `desktop/src/store/handStore.ts`
|
||
- 连接到新的 kernel-client API
|
||
|
||
**端到端测试**:
|
||
6. 在自动化面板验证触发器创建和执行
|
||
|
||
---
|
||
|
||
## 四、验证方案
|
||
|
||
### 文件工具验证
|
||
```bash
|
||
# 运行 Rust 测试
|
||
cargo test -p zclaw-runtime --lib tool
|
||
|
||
# 手动验证
|
||
# 在聊天中让 Agent 读取/写入文件
|
||
```
|
||
|
||
### MCP 验证
|
||
```bash
|
||
# 启动 MCP server
|
||
npx -y @anthropic/mcp-server-filesystem /tmp/test
|
||
|
||
# 在 ZCLAW 中添加 MCP 服务并测试工具列表
|
||
```
|
||
|
||
### Triggers 验证
|
||
```bash
|
||
# 运行前端测试
|
||
pnpm vitest run tests/desktop/gatewayStore.test.ts
|
||
|
||
# 手动验证
|
||
# 在自动化面板创建触发器，检查是否保存和执行
|
||
```
|
||
|
||
---
|
||
|
||
## 五、风险评估
|
||
|
||
| 风险 | 可能性 | 影响 | 缓解措施 |
|
||
|------|--------|------|----------|
|
||
| 文件工具路径验证绕过 | 中 | 高 | 严格测试边界情况 |
|
||
| MCP 协议版本不兼容 | 低 | 中 | 使用标准 MCP 1.0 |
|
||
| Triggers 状态持久化 | 中 | 中 | 使用 SQLite |
|
||
|
||
---
|
||
|
||
## 六、不纳入本次交付的内容
|
||
|
||
- Local LLM 驱动 (Ollama) - 用户未选择
|
||
- Channel 适配器 (Telegram/Discord/Slack) - 非核心功能
|
||
- Agent Swarm - 标记为 TODO
|
||
- Store 迁移完成 - 质量改进，非功能
|
||
- 测试覆盖率提升 - 持续改进
|