zclaw_openfang/plans/vivid-drifting-brook.md

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. 在自动化面板验证触发器创建和执行

---

四、验证方案

文件工具验证

# 运行 Rust 测试
cargo test -p zclaw-runtime --lib tool

# 手动验证
# 在聊天中让 Agent 读取/写入文件

MCP 验证

# 启动 MCP server
npx -y @anthropic/mcp-server-filesystem /tmp/test

# 在 ZCLAW 中添加 MCP 服务并测试工具列表

Triggers 验证

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