ZCLAW 功能验证计划
版本: v0.2.5
创建日期: 2026-03-24
验证范围: 所有已实现功能的完整性、可用性验证
一、验证概述
1.1 验证目标
基于 docs/features 目录的文档,系统化验证 ZCLAW 所有已实现功能的:
- 完整性 - 功能是否完整实现
- 可用性 - 功能是否可正常使用
- 集成性 - 前后端是否正确集成
- 持久性 - 数据是否正确持久化
1.2 验证范围统计
| 模块 |
功能数量 |
验证点数量 |
| 架构层 |
3 |
45 |
| 核心功能 |
6 |
38 |
| 智能层 |
6 |
42 |
| 技能系统 |
3 |
15 |
| Hands 系统 |
9 |
20 |
| 后端集成 |
100+ |
25 |
| 总计 |
127+ |
185 |
二、Phase 1: 架构层验证
2.1 通信层验证 (01-communication-layer.md)
2.1.1 LLM Provider 连接验证
| # |
验证项 |
测试方法 |
预期结果 |
| 1.1 |
Kimi Provider |
配置 Kimi API Key,发送消息 |
流式响应正常 |
| 1.2 |
Qwen Provider |
配置通义千问 API Key |
流式响应正常 |
| 1.3 |
DeepSeek Provider |
配置 DeepSeek API Key |
流式响应正常 |
| 1.4 |
智谱 Provider |
配置智谱 API Key |
流式响应正常 |
| 1.5 |
OpenAI Provider |
配置 OpenAI Key |
流式响应正常 |
| 1.6 |
Anthropic Provider |
配置 Claude API Key |
流式响应正常 |
| 1.7 |
Gemini Provider |
配置 Gemini API Key |
流式响应正常 |
| 1.8 |
Local Provider (Ollama) |
启动 Ollama,配置 localhost:11434 |
流式响应正常 |
| 1.9 |
自定义 baseUrl |
配置自定义 URL |
请求发送到自定义地址 |
关键文件: desktop/src/lib/kernel-client.ts, crates/zclaw-runtime/src/driver/
2.1.2 Tauri 命令验证
| # |
命令 |
验证方法 |
预期结果 |
| 2.1 |
kernel_init |
首次启动应用 |
initialized: true |
| 2.2 |
kernel_status |
调用状态 API |
返回当前状态 |
| 2.3 |
kernel_shutdown |
关闭应用 |
优雅关闭 |
| 2.4 |
agent_create |
创建新 Agent |
返回 { id, name, state } |
| 2.5 |
agent_list |
调用列表 API |
返回 Agent 数组 |
| 2.6 |
agent_get |
获取 Agent 详情 |
返回完整信息 |
| 2.7 |
agent_delete |
删除 Agent |
成功删除 |
| 2.8 |
agent_chat |
发送非流式消息 |
返回完整响应 |
| 2.9 |
agent_chat_stream |
发送流式消息 |
收到流式事件 |
关键文件: desktop/src-tauri/src/kernel_commands.rs
2.1.3 流式响应验证
| # |
验证项 |
测试方法 |
预期结果 |
| 3.1 |
delta 事件 |
发送消息 |
UI 逐字显示 |
| 3.2 |
tool_start 事件 |
触发工具调用 |
显示工具开始状态 |
| 3.3 |
tool_end 事件 |
工具完成 |
显示工具输出 |
| 3.4 |
complete 事件 |
消息完成 |
停止流式,显示 token 统计 |
| 3.5 |
error 事件 |
模拟错误 |
显示错误信息 |
| 3.6 |
sessionId 路由 |
并发发送多条 |
事件正确路由 |
| 3.7 |
流式取消 |
调用 cancelStream |
清理监听器 |
2.1.4 错误处理验证
| # |
场景 |
预期行为 |
| 4.1 |
未配置模型 |
显示中文提示 |
| 4.2 |
API Key 无效 |
显示 401 错误 |
| 4.3 |
网络中断 |
显示连接失败 |
| 4.4 |
流式错误 |
UI 恢复可交互 |
| 4.5 |
自动重连 |
reconnecting 状态 |
2.2 状态管理验证 (02-state-management.md)
2.2.1 Store 持久化验证
| # |
Store |
验证项 |
测试方法 |
| 5.1 |
chatStore |
对话历史保留 |
刷新页面后验证 |
| 5.2 |
chatStore |
partialize |
检查 localStorage 内容 |
| 5.3 |
configStore |
配置保留 |
修改后刷新验证 |
| 5.4 |
offlineStore |
离线队列保留 |
离线发送后刷新 |
关键文件: desktop/src/store/chatStore.ts, desktop/src/store/configStore.ts
2.2.2 Store 间通信验证
| # |
验证项 |
测试方法 |
| 6.1 |
客户端注入 |
检查 initializeStores() |
| 6.2 |
连接状态同步 |
连接后验证 Agent 自动加载 |
| 6.3 |
跨 Store 访问 |
发送消息时检查连接状态 |
| 6.4 |
单例模式 |
多次调用验证同一实例 |
2.2.3 Date 对象恢复验证
| # |
验证项 |
测试方法 |
| 7.1 |
日期转换 |
刷新后验证时间显示 |
| 7.2 |
streaming 清除 |
流式中刷新验证 |
| 7.3 |
当前会话恢复 |
切换对话后刷新 |
2.3 安全认证验证 (03-security-auth.md)
2.3.1 设备认证验证
| # |
验证项 |
测试方法 |
| 8.1 |
密钥生成 |
清空存储后启动 |
| 8.2 |
密钥持久化 |
验证 Keyring 调用 |
| 8.3 |
JWT Token 存储 |
验证非明文存储 |
| 8.4 |
Token 刷新 |
过期后自动刷新 |
关键文件: desktop/src/lib/secure-storage.ts
2.3.2 存储后端验证
| # |
平台 |
存储后端 |
| 9.1 |
Windows |
DPAPI |
| 9.2 |
macOS |
Keychain |
| 9.3 |
Linux |
Secret Service |
| 9.4 |
降级 |
AES-GCM 加密 localStorage |
三、Phase 2: 核心功能验证
3.1 聊天界面验证
| # |
功能 |
验证方法 |
预期结果 |
| 10.1 |
流式响应展示 |
发送消息 |
实时显示 |
| 10.2 |
Markdown 渲染 |
发送 Markdown 内容 |
正确渲染 |
| 10.3 |
代码块渲染 |
发送代码 |
语法高亮 |
| 10.4 |
多会话管理 |
创建/切换/删除 |
状态正确 |
| 10.5 |
模型选择 |
切换模型 |
使用新模型 |
| 10.6 |
消息自动滚动 |
长对话 |
自动滚动到底部 |
| 10.7 |
输入框调整 |
输入多行 |
高度自动调整 |
| 10.8 |
记忆增强注入 |
发送相关历史 |
自动注入上下文 |
| 10.9 |
上下文压缩 |
超过阈值 |
自动压缩 |
关键文件: desktop/src/components/ChatArea.tsx, desktop/src/store/chatStore.ts
3.2 Agent 分身管理验证
| # |
功能 |
验证方法 |
预期结果 |
| 11.1 |
创建 Agent |
通过向导创建 |
成功创建 |
| 11.2 |
配置 Agent |
修改 SOUL.md |
配置生效 |
| 11.3 |
切换 Agent |
切换当前 Agent |
状态更新 |
| 11.4 |
人格预设 |
选择不同预设 |
SOUL.md 不同 |
| 11.5 |
身份持久化 |
重启应用 |
Agent 保留 |
关键文件: desktop/src/components/AgentOnboardingWizard.tsx, desktop/src/lib/personality-presets.ts
3.3 多 Agent 协作验证
| # |
模式 |
验证方法 |
预期结果 |
| 12.1 |
Sequential |
创建链式任务 |
按顺序执行 |
| 12.2 |
Parallel |
创建并行任务 |
并发执行 |
| 12.3 |
Debate |
创建辩论任务 |
多轮讨论后综合 |
关键文件: desktop/src/components/SwarmDashboard.tsx, desktop/src/lib/agent-swarm.ts
四、Phase 3: 智能层验证
4.1 Agent 记忆系统验证 (00-agent-memory.md)
4.1.1 记忆类型验证
| # |
类型 |
测试方法 |
预期结果 |
| 13.1 |
fact |
存储事实记忆 |
正确存储 |
| 13.2 |
preference |
存储偏好记忆 |
正确存储 |
| 13.3 |
lesson |
存储教训记忆 |
正确存储 |
| 13.4 |
context |
存储上下文记忆 |
正确存储 |
| 13.5 |
task |
存储任务记忆 |
正确存储 |
4.1.2 记忆操作验证
| # |
操作 |
Tauri 命令 |
验证方法 |
| 14.1 |
初始化 |
memory_init |
调用成功 |
| 14.2 |
存储 |
memory_store |
存储成功 |
| 14.3 |
获取 |
memory_get |
正确获取 |
| 14.4 |
搜索 |
memory_search |
返回相关记忆 |
| 14.5 |
删除 |
memory_delete |
删除成功 |
| 14.6 |
统计 |
memory_stats |
返回统计 |
| 14.7 |
导出 |
memory_export |
导出 Markdown |
| 14.8 |
导入 |
memory_import |
导入成功 |
关键文件: desktop/src-tauri/src/memory_commands.rs, desktop/src/components/MemoryPanel.tsx
4.1.3 记忆 UI 集成验证
| # |
组件 |
验证方法 |
| 15.1 |
MemoryPanel |
点击 RightPanel |
| 15.2 |
MemoryGraph |
查看记忆图谱 |
| 15.3 |
统计显示 |
查看统计 |
| 15.4 |
清理功能 |
点击清理 |
4.2 身份演化验证 (01-identity-evolution.md)
| # |
功能 |
API/命令 |
验证方法 |
| 16.1 |
获取身份 |
identity_get |
返回身份文件 |
| 16.2 |
更新文件 |
identity_update_file |
更新成功 |
| 16.3 |
变更提案 |
identity_propose_change |
创建提案 |
| 16.4 |
批准提案 |
identity_approve_proposal |
应用变更 |
| 16.5 |
拒绝提案 |
identity_reject_proposal |
丢弃提案 |
| 16.6 |
快照历史 |
identity_get_snapshots |
返回历史 |
| 16.7 |
回滚 |
identity_restore_snapshot |
恢复成功 |
关键文件: desktop/src/lib/intelligence-client.ts, desktop/src/components/IdentityChangeProposal.tsx
4.3 反思引擎验证 (03-reflection-engine.md)
| # |
功能 |
Tauri 命令 |
验证方法 |
| 17.1 |
记录对话 |
reflection_record_conversation |
记录成功 |
| 17.2 |
触发检查 |
reflection_should_reflect |
返回是否触发 |
| 17.3 |
执行反思 |
reflection_reflect |
返回结果 |
| 17.4 |
获取历史 |
reflection_get_history |
返回历史 |
验证触发条件:
- 对话次数: 每 5 次后
- 时间间隔: 每 24 小时
- 首次触发: 3 次对话后
关键文件: desktop/src-tauri/src/intelligence/reflection.rs, desktop/src/components/ReflectionLog.tsx
4.4 心跳引擎验证 (04-heartbeat-engine.md)
| # |
功能 |
Tauri 命令 |
验证方法 |
| 18.1 |
初始化 |
heartbeat_init |
初始化成功 |
| 18.2 |
启动 |
heartbeat_start |
开始跳动 |
| 18.3 |
停止 |
heartbeat_stop |
停止跳动 |
| 18.4 |
手动触发 |
heartbeat_tick |
执行检查 |
| 18.5 |
获取配置 |
heartbeat_get_config |
返回配置 |
| 18.6 |
更新配置 |
heartbeat_update_config |
更新成功 |
| 18.7 |
获取历史 |
heartbeat_get_history |
返回历史 |
验证检查函数:
check_pending_tasks - 待办任务积压
check_memory_health - 记忆健康
check_idle_greeting - 长时间未互动
check_personality_improvement - 人格改进
check_learning_opportunities - 学习机会
关键文件: desktop/src-tauri/src/intelligence/heartbeat.rs
4.5 自主授权验证 (05-autonomy-manager.md)
4.5.1 自主级别验证
| # |
级别 |
行为 |
验证方法 |
| 19.1 |
supervised |
所有操作需确认 |
设置后验证 |
| 19.2 |
assisted |
低风险自动,中高需确认 |
设置后验证 |
| 19.3 |
autonomous |
低中风险自动,高需确认 |
设置后验证 |
4.5.2 风险等级验证
| # |
等级 |
操作类型 |
验证方法 |
| 20.1 |
Low |
memory_save, reflection_run |
验证自动执行 |
| 20.2 |
Medium |
hand_trigger, skill_install |
验证需确认 |
| 20.3 |
High |
memory_delete, identity_update |
验证始终需确认 |
关键文件: desktop/src/lib/autonomy-manager.ts, desktop/src/components/AutonomyConfig.tsx
4.6 上下文压缩验证
| # |
功能 |
Tauri 命令 |
验证方法 |
| 21.1 |
Token 估算 |
compactor_estimate_tokens |
返回估算值 |
| 21.2 |
阈值检查 |
compactor_check_threshold |
返回是否超阈值 |
| 21.3 |
执行压缩 |
compactor_compact |
返回压缩结果 |
压缩配置:
- 阈值: 15000 tokens
- 策略: 滑动窗口 + 摘要
五、Phase 4: 技能系统验证
5.1 技能发现验证
| # |
验证项 |
测试方法 |
预期结果 |
| 22.1 |
技能扫描 |
调用 skill_list |
返回 77 个技能 |
| 22.2 |
技能刷新 |
调用 skill_refresh |
重新扫描成功 |
| 22.3 |
技能分类 |
检查分类 |
14 个分类正确 |
关键文件: crates/zclaw-skills/src/registry.rs, desktop/src/lib/skill-discovery.ts
5.2 技能执行验证
| # |
验证项 |
测试方法 |
预期结果 |
| 23.1 |
执行技能 |
调用 skill_execute |
正确执行 |
| 23.2 |
触发词匹配 |
发送触发词消息 |
自动推荐技能 |
| 23.3 |
工具权限 |
检查 SKILL.md tools |
正确限制 |
5.3 技能分类抽样验证
| 分类 |
代表技能 |
验证项 |
| 开发工程 |
senior-developer |
代码生成 |
| 测试/QA |
code-reviewer |
代码审查 |
| 设计/UX |
ui-designer |
设计建议 |
| 安全 |
security-engineer |
安全分析 |
| 数据分析 |
analytics-reporter |
数据报告 |
| 运维/DevOps |
devops-automator |
自动化 |
六、Phase 5: Hands 系统验证
6.1 已实现 Hands 验证 (9/11)
| # |
Hand |
触发方式 |
需审批 |
验证方法 |
| 24.1 |
browser |
手动/Webhook |
是 |
启动浏览器会话 |
| 24.2 |
researcher |
手动/事件 |
否 |
执行研究任务 |
| 24.3 |
collector |
定时/事件/手动 |
否 |
数据收集 |
| 24.4 |
slideshow |
手动 |
否 |
生成幻灯片 |
| 24.5 |
speech |
手动/事件 |
否 |
语音合成 |
| 24.6 |
quiz |
手动 |
否 |
生成测验 |
| 24.7 |
whiteboard |
手动 |
否 |
白板协作 |
| 24.8 |
clip |
手动/定时 |
否 |
需 FFmpeg |
| 24.9 |
twitter |
定时/事件 |
是 |
需 API Key |
关键文件: crates/zclaw-hands/src/hands/, desktop/src/store/handStore.ts
6.2 依赖检查验证
| # |
Hand |
依赖 |
验证方法 |
| 25.1 |
clip |
FFmpeg |
检测 FFmpeg 可用性 |
| 25.2 |
twitter |
Twitter API Key |
检测 API Key |
| 25.3 |
browser |
WebDriver |
检测浏览器驱动 |
6.3 审批流程验证
| # |
验证项 |
测试方法 |
| 26.1 |
状态流转 |
触发需审批 Hand |
| 26.2 |
批准操作 |
点击批准 |
| 26.3 |
拒绝操作 |
点击拒绝 |
七、Phase 6: 后端集成验证
7.1 Kernel 集成验证
| # |
验证项 |
测试方法 |
预期结果 |
| 27.1 |
内部 Kernel |
调用 kernel_init |
initialized: true |
| 27.2 |
多 LLM 支持 |
配置不同 Provider |
正确切换 |
| 27.3 |
Agent 生命周期 |
创建/删除 Agent |
正确管理 |
| 27.4 |
流式响应 |
发送流式消息 |
事件正确 |
| 27.5 |
MCP 协议 |
检查 MCP 支持 |
已实现 |
关键文件: crates/zclaw-kernel/src/lib.rs
7.2 浏览器自动化验证
| # |
命令 |
验证方法 |
| 28.1 |
browser_create_session |
创建会话 |
| 28.2 |
browser_navigate |
导航页面 |
| 28.3 |
browser_click |
点击元素 |
| 28.4 |
browser_type |
输入文本 |
| 28.5 |
browser_screenshot |
截图 |
| 28.6 |
browser_execute_script |
执行 JS |
| 28.7 |
browser_scrape_page |
抓取页面 |
八、验证执行顺序
8.1 推荐执行顺序
预计总时间: 约 6 小时
8.2 自动化测试
| 类型 |
位置 |
命令 |
| 单元测试 |
tests/desktop/ |
pnpm vitest run |
| E2E 测试 |
desktop/tests/e2e/ |
pnpm test:e2e |
| 类型检查 |
- |
pnpm tsc --noEmit |
九、验证记录模板
9.1 功能验证记录
十、关键文件路径汇总
10.1 前端文件
| 模块 |
路径 |
| Kernel Client |
desktop/src/lib/kernel-client.ts |
| 智能客户端 |
desktop/src/lib/intelligence-client.ts |
| 技能发现 |
desktop/src/lib/skill-discovery.ts |
| 自主管理 |
desktop/src/lib/autonomy-manager.ts |
| 安全存储 |
desktop/src/lib/secure-storage.ts |
| 聊天 Store |
desktop/src/store/chatStore.ts |
| Hand Store |
desktop/src/store/handStore.ts |
10.2 后端文件
| 模块 |
路径 |
| Kernel 命令 |
desktop/src-tauri/src/kernel_commands.rs |
| 记忆命令 |
desktop/src-tauri/src/memory_commands.rs |
| 心跳引擎 |
desktop/src-tauri/src/intelligence/heartbeat.rs |
| 反思引擎 |
desktop/src-tauri/src/intelligence/reflection.rs |
| 身份管理 |
desktop/src-tauri/src/intelligence/identity.rs |
| Kernel 核心 |
crates/zclaw-kernel/src/lib.rs |
| 技能注册 |
crates/zclaw-skills/src/registry.rs |
| Hands 实现 |
crates/zclaw-hands/src/hands/ |
10.3 文档文件
| 文档 |
路径 |
| 功能索引 |
docs/features/README.md |
| 通信层 |
docs/features/00-architecture/01-communication-layer.md |
| 状态管理 |
docs/features/00-architecture/02-state-management.md |
| 记忆系统 |
docs/features/02-intelligence-layer/00-agent-memory.md |
| 身份演化 |
docs/features/02-intelligence-layer/01-identity-evolution.md |
| 技能系统 |
docs/features/04-skills-ecosystem/00-skill-system.md |
| Hands 系统 |
docs/features/05-hands-system/00-hands-overview.md |
十一、验收标准
11.1 通过标准
| 指标 |
标准 |
| 功能完整性 |
≥ 95% 验证点通过 |
| 关键功能 |
100% 通过 (聊天、Agent、记忆) |
| 无阻塞性问题 |
0 个 High 严重度问题 |
| 数据持久化 |
100% 正确 |
11.2 阻塞问题定义
- High: 功能完全不可用
- Medium: 功能部分可用,有规避方案
- Low: UI/体验问题,不影响核心功能
十二、硬编码问题审计报告
审计日期: 2026-03-24
触发原因: 发现 skills_dir: None 导致技能系统完全失效
12.1 已修复问题
问题 #1: skills_dir: None 导致技能不加载 (CRITICAL - 已修复)
文件: crates/zclaw-kernel/src/config.rs:337
问题描述:
影响: 通过 Tauri 初始化 Kernel 时,技能目录永远不会被扫描,导致:
skills.list() 返回空列表
- 系统提示词中没有任何技能信息
- LLM 无法调用
execute_skill 工具
修复:
验证方法:
- 启动应用,发送 "查询腾讯财报"
- 预期: LLM 应调用
execute_skill("finance-tracker", {...})
12.2 待修复问题清单
高优先级 (HIGH)
| # |
问题 |
文件:行号 |
影响 |
| H1 |
default_skills_dir() 依赖 current_dir() |
config.rs:161-165 |
工作目录不同时技能加载失败 |
| H2 |
categorize_skills() 包含 50+ 硬编码技能 ID |
kernel.rs:173-185 |
新增/重命名技能后分类失效 |
| H3 |
前端 Hand ID 硬编码在多处 |
automation.ts, hands.ts |
Hand 配置变更后前端不一致 |
中优先级 (MEDIUM)
| # |
问题 |
文件:行号 |
影响 |
| M1 |
默认模型不一致 |
kernel_commands.rs vs config-parser.ts |
gpt-4o-mini vs gpt-4 |
| M2 |
API URL 硬编码在多处 |
config.rs, llm/mod.rs, driver 文件 |
无法统一配置 |
| M3 |
系统提示词示例硬编码 finance-tracker |
kernel.rs:162 |
技能重命名后示例过时 |
| M4 |
前端存储键硬编码 |
gateway-storage.ts, 多个 store |
无法自定义前缀 |
低优先级 (LOW)
| # |
问题 |
文件:行号 |
影响 |
| L1 |
工具名称有常量但未使用 |
tool.rs:79-90 vs builtin/*.rs |
代码不一致 |
| L2 |
超时/阈值等配置硬编码 |
compactor.rs, heartbeat.rs |
无法动态调整 |
| L3 |
Tauri 允许来源硬编码 |
lib.rs:97 |
安全配置不灵活 |
12.3 硬编码位置详细列表
后端 (Rust)
| 类别 |
文件 |
内容 |
| 配置默认值 |
config.rs:200-247 |
9 个 LLM Provider URL |
| 配置默认值 |
config.rs:285-326 |
8 个 fallback URL |
| 驱动 URL |
driver/local.rs:27,31,35 |
Ollama/LM Studio/vLLM localhost |
| 驱动 URL |
driver/gemini.rs:25 |
Google Generative Language API |
| 驱动 URL |
driver/anthropic.rs:27 |
Anthropic API |
| 驱动 URL |
driver/openai.rs:31 |
OpenAI API |
| 模型默认值 |
kernel_commands.rs:43-46 |
openai, gpt-4o-mini, 4096, 0.7 |
| 技能分类 |
kernel.rs:173-185 |
11 个分类,50+ 技能 ID |
| 阈值配置 |
compactor.rs:38-44 |
15000, 20000, 4000, 6, 800 |
| 心跳配置 |
heartbeat.rs:36-37 |
30s interval, 5 max alerts |
| 浏览器 |
browser/commands.rs:63 |
localhost:4444 WebDriver |
| 网关 |
lib.rs:554 |
ws://127.0.0.1:4200 |
前端 (TypeScript)
| 类别 |
文件 |
内容 |
| 网关 URL |
gateway-storage.ts:47,51 |
127.0.0.1:50051, 127.0.0.1:4200 |
| 模型默认值 |
config-parser.ts:77,81-82 |
gpt-4, openai |
| 模型默认值 |
llm-service.ts:57-66 |
gpt-4o-mini, doubao-pro-32k |
| 内核默认值 |
kernel-client.ts:248,340-341 |
openai, anthropic, claude-sonnet-4 |
| 存储键 |
多个 store 文件 |
zclaw-*, zclaw-main |
| Hand ID |
automation.ts:49-57,267-279 |
7 个 Hand 映射 |
| Hand 定义 |
hands.ts:97-189 |
完整 Hand 定义 |
| 技能 ID |
skillMarketStore.ts:304+ |
技能市场定义 |
12.4 建议修复方案
H1: default_skills_dir() 改进
H2: 技能分类改为动态
H3: Hand ID 集中管理
12.5 验证检查清单
修复后需验证:
本验证计划基于 ZCLAW v0.2.5 代码状态生成