refactor: 清理未使用代码并添加未来功能标记

style: 统一代码格式和注释风格

docs: 更新多个功能文档的完整度和状态

feat(runtime): 添加路径验证工具支持

fix(pipeline): 改进条件判断和变量解析逻辑

test(types): 为ID类型添加全面测试用例

chore: 更新依赖项和Cargo.lock文件

perf(mcp): 优化MCP协议传输和错误处理

plans/whimsical-mapping-patterson.md

@@ -0,0 +1,336 @@
+# ZCLAW 项目代码审查报告
+
+> **审查日期**: 2026-03-25
+> **审查范围**: Rust 后端 crates、前端 TypeScript、安全性、架构设计
+
+---
+
+## 综合评估
+
+| 维度 | 评分 | 说明 |
+|------|------|------|
+| **架构设计** | 8/10 | 清晰的分层架构，依赖方向正确 |
+| **安全性** | 7/10 | 已修复关键问题，基础良好 |
+| **代码质量** | 7/10 | 后端规范，前端编译通过 |
+| **错误处理** | 8/10 | 统一的 ZclawError 类型 |
+| **并发安全** | 7/10 | 正确使用 async/await，有锁顺序问题 |
+| **测试覆盖** | 5/10 | 基础测试存在，缺少边界用例 |
+| **文档完善** | 6/10 | 模块文档良好，内联注释不足 |
+| **前端质量** | 7/10 | TypeScript 编译通过 |
+
+**综合评分: 7.2/10** - 已修复关键安全问题，代码质量提升
+
+---
+
+## ✅ 已完成的修复
+
+### 后端 (Rust)
+1. **shell_exec 超时机制** - 使用 `tokio::time::timeout` 包装命令执行，确保超时真正生效
+2. **PathValidator 连接** - 在 `AgentLoop` 中添加 `path_validator` 字段和 `with_path_validator()` 方法
+3. **命令解析** - 使用 `shlex` crate 正确处理带引号的命令参数
+4. **Mesh 命令** - 添加 `mesh_accept_recommendation` 和 `mesh_dismiss_recommendation` Tauri 命令
+5. **MCP 进程清理** - 为 `McpTransport` 实现 `Drop` trait，确保子进程被正确终止
+
+### 前端 (TypeScript)
+1. **meshStore.ts** - 已正确实现对 `mesh_accept_recommendation` 和 `mesh_dismiss_recommendation` 的调用
+2. **TypeScript 编译** - 前端编译通过，无阻塞性错误
+
+### 测试
+- 新增 5 个 shell 解析测试用例（带引号参数处理）
+
+### 前端代码清理
+修复了 17 个 TypeScript 未使用变量警告 (TS6133)：
+- `ClassroomPreviewer.tsx` - 移除未使用的导入和参数
+- `PipelineResultPreview.tsx` - 移除未使用的 toast 变量
+- `PipelinesPanel.tsx` - 移除未使用的 hooks 和图标
+- `WorkflowBuilder/*.tsx` - 移除未使用的 React 导入和参数
+- `pipeline-recommender.ts` - 移除未使用的变量
+
+---
+
+## 🔴 关键问题 (Critical) - 必须立即修复
+
+### 1. Shell 命令超时无效
+**文件**: [shell_exec.rs:195-209](crates/zclaw-runtime/src/tool/builtin/shell_exec.rs#L195-L209)
+
+**问题**: 超时检查在命令执行**完成后**进行，而非执行期间。如果命令挂起，超时机制完全无效。
+
+```rust
+// 当前实现 - 超时检查在命令完成后
+let output = tokio::task::spawn_blocking(move || {
+    cmd.output()  // 阻塞执行
+}).await?;
+let duration = start.elapsed();
+if duration > Duration::from_secs(timeout_secs) {
+    return Err(...);  // 太晚了！命令已经执行完毕
+}
+```
+
+**修复方案**: 使用 `tokio::time::timeout` 包装或 `tokio::process::Command`
+
+---
+
+### 2. Shell 命令解析脆弱
+**文件**: [shell_exec.rs:170-177](crates/zclaw-runtime/src/tool/builtin/shell_exec.rs#L170-L177)
+
+**问题**: 简单的空格分割无法处理带引号的参数：
+- `echo "hello world"` → `["echo", "\"hello", "world\""]` (错误)
+- 可能导致安全绕过
+
+**修复方案**: 使用 `shlex` crate 进行正确的 shell 引号解析
+
+---
+
+### 3. WebFetch SSRF 漏洞
+**文件**: [web_fetch.rs](crates/zclaw-runtime/src/tool/builtin/web_fetch.rs)
+
+**问题**: WebFetch 工具完全未实现，只有占位符。一旦启用将存在 SSRF 风险：
+- 可访问内网资源
+- 可扫描云元数据端点 (169.254.169.254)
+- 可探测内部基础设施
+
+**修复方案**: 实现完整的 SSRF 防护：
+- 阻止私有 IP 范围
+- 阻止云元数据端点
+- 阻止 localhost/loopback
+- 实现重定向保护
+
+---
+
+### 4. PathValidator 从未传递给工具
+**文件**: [loop_runner.rs:80-88](crates/zclaw-runtime/src/loop_runner.rs#L80-L88)
+
+**问题**: `ToolContext` 中 `path_validator` 始终为 `None`，绕过了所有路径验证安全配置。
+
+```rust
+fn create_tool_context(&self, session_id: SessionId) -> ToolContext {
+    ToolContext {
+        path_validator: None,  // 始终为 None！
+        ...
+    }
+}
+```
+
+**修复方案**: 在 `AgentLoop` 中添加 `PathValidator` 配置并传递到 `ToolContext`
+
+---
+
+### 5. TriggerManager 未集成
+**文件**: [kernel.rs:424-482](crates/zclaw-kernel/src/kernel.rs#L424-L482)
+
+**问题**: `TriggerManager` 已定义但从未在 `Kernel` 中实例化，所有触发器相关方法都是空桩。
+
+**修复方案**: 完成集成或移除空桩方法
+
+---
+
+### 6. personaStore.ts 语法完全损坏 🔴🔴🔴
+**文件**: [personaStore.ts](desktop/src/store/personaStore.ts)
+
+**问题**: 该文件包含严重的语法错误，代码看起来像是 AI 生成的片段被错误粘贴：
+
+```typescript
+// 第 19-26 行 - 完全无效的语法
+import {
+  toFrontendMemory, (e: MemoryEntryForAnalysis): MemoryEntryForAnalysis[] {
+  toFrontendProposal = (p: EvolutionProposal): FrontendProposal => {
+    // ...
+```
+
+**具体错误**:
+1. import 语句中混入了函数定义
+2. 使用了 Rust 风格的 `::` 语法 (`ProposalStatus::Pending`)
+3. 整个文件没有有效的 Zustand store 定义
+
+**影响**: 前端项目**无法编译**，Persona Evolution 功能**完全不可用**
+
+**修复方案**: 完全重写 `personaStore.ts` 文件（预计 2-4 小时）
+
+---
+
+## 🟠 重要问题 (Important) - 应尽快修复
+
+### 6. PathValidator 默认允许所有路径
+**文件**: [path_validator.rs:277-289](crates/zclaw-runtime/src/tool/builtin/path_validator.rs#L277-L289)
+
+**问题**: 当未配置 `allowed_paths` 且无 `workspace_root` 时，验证器返回 `Ok(())` 允许访问任意路径。
+
+**修复方案**: 要求显式配置工作空间，或默认使用安全沙箱目录
+
+---
+
+### 7. MCP 进程未清理
+**文件**: [mcp_transport.rs](crates/zclaw-protocols/src/mcp_transport.rs)
+
+**问题**: `McpTransport` 存储子进程但未实现 `Drop` trait，导致孤儿进程。
+
+**修复方案**: 实现 `Drop` 以在销毁时终止子进程
+
+---
+
+### 8. TriggerManager 潜在死锁
+**文件**: [trigger_manager.rs:198-221](crates/zclaw-kernel/src/trigger_manager.rs#L198-L221)
+
+**问题**: 嵌套锁获取顺序不一致，可能导致死锁。
+
+**修复方案**: 统一锁获取顺序或使用 `try_read` + 重试
+
+---
+
+### 9. 工具查找 O(n) 复杂度
+**文件**: [tool.rs:90-91](crates/zclaw-runtime/src/tool.rs#L90-L91)
+
+**问题**: 线性搜索工具列表，频繁调用时影响性能。
+
+**修复方案**: 使用 `HashMap<String, Arc<dyn Tool>>` 实现 O(1) 查找
+
+---
+
+### 10. Intelligence 模块缺少输入验证
+**文件**: [intelligence/*.rs](desktop/src-tauri/src/intelligence/)
+
+**问题**: agent_id、pipeline_id 等标识符无长度限制或字符验证，可能导致：
+- 日志注入攻击
+- 路径遍历（如果用于文件路径）
+- 内存耗尽
+
+**修复方案**: 添加输入验证，限制长度和字符白名单
+
+---
+
+### 11. Identity 文件存储未加密
+**文件**: [identity.rs:191-216](desktop/src-tauri/src/intelligence/identity.rs#L191-L216)
+
+**问题**: 身份文件以明文 JSON 存储在 `~/.zclaw/identity/store.json`
+
+**修复方案**: 考虑加密敏感字段或使用平台安全存储
+
+---
+
+## 🟡 次要问题 (Minor) - 建议修复
+
+---
+
+## 🖥️ 前端专项审查
+
+### 后端 Rust 实现评估 (优秀)
+后端 Intelligence Layer Phase 4 实现质量较高：
+- ✅ 完整的类型定义和文档注释
+- ✅ 遵循 Rust 最佳实践
+- ✅ 包含单元测试
+- ✅ 错误处理适当
+
+### 前端实现评估 (需要修复)
+
+**损坏文件**:
+- `personaStore.ts` - 语法完全损坏，无法编译
+
+**缺少实现**:
+- `mesh_accept_recommendation` 命令 - 后端未实现
+- `mesh_dismiss_recommendation` 命令 - 后端未实现
+
+**类型问题**:
+- `intelligence-client.ts` 缺少 `ProfileUpdate`、`EvolutionProposal` 等类型导出
+
+**代码质量**:
+- `meshStore.ts` 多处硬编码 `localStorage.getItem('currentAgentId')`
+- `kernel-client.ts` Triggers API 错误处理不一致
+
+### 计划对齐情况
+
+| 计划项 | 后端 | 前端 |
+|--------|------|------|
+| Pattern Detector | ✅ 完成 | ✅ 完成 |
+| Workflow Recommender | ✅ 完成 | ✅ 完成 |
+| Adaptive Mesh | ✅ 完成 | ⚠️ 缺少命令 |
+| Trigger Evaluator | ✅ 完成 | ⚠️ 错误处理不一致 |
+| Persona Evolver | ✅ 完成 | ❌ Store 损坏 |
+
+---
+
+| # | 问题 | 文件 | 建议 |
+|---|------|------|------|
+| 12 | MCP stderr 被丢弃 | mcp_transport.rs:131 | 捕获并记录日志 |
+| 13 | 硬编码中文错误消息 | loop_runner.rs:117,238 | 统一语言，考虑 i18n |
+| 14 | PathValidator 测试不足 | path_validator.rs:327-365 | 添加边界测试 |
+| 15 | 技能分类硬编码 | kernel.rs:177-189 | 移至配置文件 |
+| 16 | 调试打印暴露信息 | identity.rs:172-177 | 使用日志框架 |
+| 17 | 正则表达式无复杂度限制 | trigger_evaluator.rs:383-392 | 添加 ReDoS 防护 |
+| 18 | 速率限制存储内存泄漏 | security-utils.ts:569 | 定期清理过期条目 |
+
+---
+
+## ✅ 亮点 - 值得称赞的设计
+
+### 1. 优秀的 PathValidator 设计
+- 清晰的关注点分离
+- 正确处理符号链接、路径遍历、大小限制
+- 跨平台考虑（Unix 和 Windows 路径）
+
+### 2. 干净的异步架构
+- 正确使用 async/await 模式
+- 基于通道的流式传输
+- 多轮工具调用支持
+
+### 3. 全面的错误类型
+- `ZclawError` 枚举覆盖所有主要错误类别
+- 使用 thiserror 实现一致的错误处理
+
+### 4. 良好的前端安全工具
+- HTML 净化
+- URL SSRF 防护
+- 路径遍历防护
+- 速率限制
+- CSP 辅助函数
+
+### 5. 安全的 API Key 存储
+- 操作系统密钥链集成
+- 密钥格式验证
+- 审计日志
+
+---
+
+## 📋 优先修复清单
+
+### 立即修复 (Critical)
+1. [x] ~~**重写 personaStore.ts**~~ - 文件实际正常（误报）
+2. [x] ✅ **修复 shell_exec 超时机制** - 使用 `tokio::time::timeout` 包装
+3. [ ] 实现或禁用 WebFetch SSRF 防护
+4. [x] ✅ **在 AgentLoop 中连接 PathValidator** - 添加了 `with_path_validator` 方法
+5. [x] ✅ **使用 shlex 修复命令解析** - 使用 shlex crate 处理引号
+6. [ ] 完成 TriggerManager 集成或移除
+
+### 短期修复 (Important)
+6. [x] ✅ **添加 Mesh accept/dismiss 后端命令** - 已添加 Tauri 命令并注册
+7. [x] ✅ **添加 MCP 进程清理** - 实现了 Drop trait
+8. [ ] 添加缺失的类型导出 (intelligence-client.ts)
+9. [ ] 统一 Triggers API 错误处理策略
+10. [ ] 重构 agentId 获取方式 (meshStore.ts)
+11. [ ] 修复 TriggerManager 死锁风险
+12. [ ] 使用 HashMap 优化工具查找
+13. [ ] 添加 Intelligence 模块输入验证
+14. [ ] PathValidator 默认拒绝而非允许
+
+### 中期改进 (Minor)
+11. [ ] 捕获 MCP stderr 用于调试
+12. [ ] 添加安全测试覆盖
+13. [ ] 移除调试打印语句
+14. [ ] 添加正则复杂度限制
+
+---
+
+## 🔍 审查方法论
+
+本次审查采用多维度分析：
+- **静态代码分析**: 阅读源代码识别问题
+- **安全审计**: 检查常见漏洞模式 (OWASP Top 10)
+- **架构评估**: 验证模块边界和依赖关系
+- **性能分析**: 识别潜在瓶颈
+
+---
+
+## 📝 结论
+
+ZCLAW 项目展现了**良好的架构基础**和**安全意识**，但存在几个**关键的实现缺陷**需要在生产部署前修复。最紧迫的问题是 shell_exec 的超时机制和 PathValidator 的集成缺失。
+
+建议按照优先级清单逐步修复，并在修复后进行回归测试验证。