# 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 迁移完成 - 质量改进，非功能
- 测试覆盖率提升 - 持续改进