Files
zclaw_openfang/plans/abstract-weaving-crab.md
iven aa6a9cbd84
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Rust Check (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
feat: 新增技能编排引擎和工作流构建器组件
refactor: 统一Hands系统常量到单个源文件
refactor: 更新Hands中文名称和描述

fix: 修复技能市场在连接状态变化时重新加载
fix: 修复身份变更提案的错误处理逻辑

docs: 更新多个功能文档的验证状态和实现位置
docs: 更新Hands系统文档

test: 添加测试文件验证工作区路径
2026-03-25 08:27:25 +08:00

23 KiB
Raw Permalink Blame History

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 推荐执行顺序

Phase 1 (架构层)
├── 通信层 (45 min)
├── 状态管理 (30 min)
└── 安全认证 (30 min)

Phase 2 (核心功能)
├── 聊天界面 (30 min)
├── Agent 管理 (20 min)
└── 多 Agent 协作 (20 min)

Phase 3 (智能层)
├── 记忆系统 (30 min)
├── 身份演化 (20 min)
├── 反思引擎 (15 min)
├── 心跳引擎 (15 min)
├── 自主授权 (15 min)
└── 上下文压缩 (10 min)

Phase 4 (技能系统)
└── 技能验证 (30 min)

Phase 5 (Hands 系统)
└── Hands 验证 (45 min)

Phase 6 (后端集成)
└── Kernel 验证 (30 min)

预计总时间: 约 6 小时

8.2 自动化测试

类型 位置 命令
单元测试 tests/desktop/ pnpm vitest run
E2E 测试 desktop/tests/e2e/ pnpm test:e2e
类型检查 - pnpm tsc --noEmit

九、验证记录模板

9.1 功能验证记录

## [功能名称] 验证记录

**日期**: YYYY-MM-DD
**验证人**:
**环境**: Windows/macOS/Linux

### 验证结果

| # | 验证项 | 状态 | 备注 |
|---|--------|------|------|
| 1 | xxx | ✅/❌ | |

### 发现的问题

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

问题描述:

// 修复前
Self {
    database_url: default_database_url(),
    llm,
    skills_dir: None,  // ← 硬编码为 None
}

影响: 通过 Tauri 初始化 Kernel 时,技能目录永远不会被扫描,导致:

  • skills.list() 返回空列表
  • 系统提示词中没有任何技能信息
  • LLM 无法调用 execute_skill 工具

修复:

// 修复后
skills_dir: default_skills_dir(),  // 使用默认的 ./skills 目录

验证方法:

  1. 启动应用,发送 "查询腾讯财报"
  2. 预期: 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() 改进

// 当前 (不可靠)
fn default_skills_dir() -> Option<PathBuf> {
    std::env::current_dir().ok().map(|cwd| cwd.join("skills"))
}

// 建议 (更可靠)
fn default_skills_dir() -> Option<PathBuf> {
    // 1. 优先使用可执行文件目录
    std::env::current_exe()
        .ok()
        .and_then(|exe| exe.parent().map(|p| p.join("skills")))
        // 2. 回退到当前目录
        .or_else(|| std::env::current_dir().ok().map(|cwd| cwd.join("skills")))
}

H2: 技能分类改为动态

// 当前 (硬编码)
let category_patterns = [
    ("开发工程", vec!["senior-developer", ...]),
    ...
];

// 建议 (从 SKILL.md 读取)
// 在 SKILL.md frontmatter 中添加 category 字段
// categories:
//   - development
// 或从目录结构推断

H3: Hand ID 集中管理

// 创建常量文件
// hands/constants.ts
export const HAND_IDS = {
  BROWSER: 'browser',
  RESEARCHER: 'researcher',
  COLLECTOR: 'collector',
  ...
} as const;

// 所有地方引用常量而非硬编码字符串

12.5 验证检查清单

修复后需验证:

  • 从不同工作目录启动应用,技能仍能正确加载
  • 新增技能后,系统提示词自动包含
  • 重命名技能后,分类仍正确(如使用动态分类)
  • 前端 Hand 配置与后端一致

本验证计划基于 ZCLAW v0.2.5 代码状态生成