zclaw_openfang/docs/FUNCTIONAL_VERIFICATION_PLAN.md

ZCLAW 系统功能验证方案

验证目标: 通过模拟真实用户操作流程，对所有功能模块进行深度验证，确保功能实现与设计初衷完全一致。 验证方式: tauri-mcp + Chrome DevTools 协议，直接操控运行中的应用 验证日期: 2026-04-05 当前状态: 稳定化已完成，功能冻结已解除

---

1. 功能模块清单及优先级划分

优先级定义

• P0 致命: 用户无法完成核心操作（登录、聊天、模型切换）
• P1 关键: 主要功能不可用或结果不正确（Agent管理、技能执行、Hands触发）
• P2 重要: 辅助功能异常（自动化面板、Pipeline、课堂、设置）
• P3 一般: 边缘场景或体验优化（记忆图谱、智能层细节）

模块矩阵

#	模块	优先级	涉及组件	验证页面/路径
M01	登录与认证	P0	LoginPage, SaaS登录	登录页
M02	聊天核心	P0	ChatArea, StreamingText	主聊天界面
M03	模型选择与切换	P0	ModelSelector	聊天顶部
M04	Agent/分身管理	P1	CloneManager, AgentStore	侧边栏
M05	技能系统	P1	SkillMarket, SkillCard	技能市场
M06	Hands 自主能力	P1	HandsPanel, HandApprovalModal	自动化面板
M07	自动化面板	P2	AutomationPanel, TriggersPanel	自动化页签
M08	Pipeline 工作流	P2	WorkflowBuilder, IntentInput	工作流编辑器
M09	课堂系统	P2	ClassroomPlayer, SceneRenderer	课堂播放器
M10	设置系统	P2	12个设置页面	设置页签
M11	记忆系统	P2	MemoryPanel, MemoryGraph	右侧面板
M12	智能层	P3	HeartbeatConfig, ReflectionLog	右侧面板/设置
M13	浏览器自动化	P1	BrowserHandCard, TaskTemplateModal	Browser Hand
M14	展示系统	P2	SlideshowRenderer, QuizRenderer	展示播放器
M15	Admin V2	P2	15个管理页面	admin-v2 Web应用

---

2. 各功能模块设计目标与预期效果

M01: 登录与认证

设计目标: 用户通过 SaaS 账户登录后才能使用桌面端功能。 预期效果:

• 登录页展示品牌标识、用户名/密码输入框
• 登录成功后自动跳转到主界面
• 支持 TOTP 两步验证
• 登录失败显示明确错误信息
• 会话恢复：重启应用后自动恢复登录状态（OS keyring）

M02: 聊天核心

设计目标: 用户与 AI Agent 进行多轮对话，获取流式响应。 预期效果:

• 输入框在底部，消息流式显示
• 支持普通文本、代码块、Markdown 渲染
• 消息气泡区分用户/AI
• 流式响应有打字机效果
• 支持取消正在进行的响应
• 历史对话在侧边栏可切换
• 新建对话功能正常
• 建议提示词（SuggestionChips）展示

M03: 模型选择与切换

设计目标: 用户可在多个 LLM Provider 之间切换模型。 预期效果:

• 模型选择器显示可用模型列表
• 切换模型后后续对话使用新模型
• 已连接 SaaS 时显示 SaaS 可用模型
• 未连接时显示本地配置的模型

M04: Agent/分身管理

设计目标: 用户可创建、配置、切换不同的 AI Agent（分身）。 预期效果:

• 侧边栏显示 Agent 列表
• 可创建新 Agent（设置名称、人设、模型偏好）
• 可切换当前活跃 Agent
• 可编辑/删除 Agent
• Agent 配置持久化

M05: 技能系统

设计目标: 用户可浏览、搜索、执行 75 个预定义技能。 预期效果:

• 技能市场展示技能卡片
• 技能按类别分组
• 支持搜索技能
• 点击技能可查看详情
• 可直接触发技能执行
• 技能执行结果在聊天中显示

M06: Hands 自主能力

设计目标: 9 个 Hands 提供浏览器自动化、数据收集、研究等能力。 预期效果:

• Hands 面板展示所有可用 Hands
• 每个 Hand 显示状态、描述
• 可触发 Hand 执行（带参数配置）
• 需要审批的 Hand 弹出审批弹窗
• 执行状态实时更新
• 执行结果可查看

M07: 自动化面板

设计目标: 用户可创建自动化触发器、查看审批队列、管理定时任务。 预期效果:

• 自动化面板展示触发器列表
• 可创建新触发器（选择类型、配置条件）
• 审批队列显示待审批操作
• 定时任务管理

M08: Pipeline 工作流

设计目标: 用户可通过意图路由触发 Pipeline 工作流，或可视化编辑工作流。 预期效果:

• 意图输入可路由到匹配的 Pipeline
• 工作流编辑器支持拖拽节点
• 节点类型：LLM、Skill、Hand、HTTP、并行、条件
• 可保存和运行工作流
• 执行结果可查看

M09: 课堂系统

设计目标: AI 生成多 Agent 互动的教学场景。 预期效果:

• 可输入主题生成课堂
• 生成进度实时显示
• 课堂播放器展示多 Agent 对话
• 场景切换流畅
• 支持学生笔记
• 白板绘制功能
• TTS 语音播放

M10: 设置系统

设计目标: 12 个设置页面覆盖所有配置需求。 预期效果:

• 通用设置：语言、主题、代理
• 使用统计：用量图表
• 积分/计费：余额、充值
• 模型与 API：Provider 配置、API Key
• MCP 服务：外部工具连接
• 技能管理：技能列表
• IM 通道：飞书等集成
• 工作区：文件路径配置
• 隐私：数据收集选项
• 安全存储：敏感信息
• 关于：版本信息

M11: 记忆系统

设计目标: AI 记住用户偏好和历史对话要点。 预期效果:

• 记忆面板展示已存储的记忆
• 记忆图谱可视化
• 可搜索记忆
• 可删除单条记忆
• Viking 存储功能正常

M12: 智能层

设计目标: Heartbeat（心跳）、Reflection（反思）、Identity（身份进化）协同工作。 预期效果:

• 心跳配置可查看/修改
• 反思日志可查看
• 身份变化提案通知可响应
• 压缩器自动管理上下文窗口

M13: 浏览器自动化

设计目标: 通过 Chromium 自动化浏览器操作。 预期效果:

• 可创建浏览器会话
• 任务模板可选择
• 截图预览可查看
• 表单填写自动化
• 数据抓取功能

M14: 展示系统

设计目标: 生成幻灯片、测验、文档等展示内容。 预期效果:

• 幻灯片播放器正常
• 测验渲染和交互
• 文档渲染
• 图表渲染

M15: Admin V2 管理后台

设计目标: 管理员通过 Web 界面管理 SaaS 平台。 预期效果:

• 仪表盘展示关键指标
• 账户管理 CRUD
• 模型服务配置
• 角色权限管理
• 计费管理
• 中继任务管理
• 知识库管理
• 定时任务管理
• Prompt 模板管理
• 操作日志查看
• 配置同步管理

---

3. 详细用户操作场景模拟方案

Phase 1: 核心交互（P0）

场景 S1.1: 首次登录

1. 启动应用，观察加载过程
2. 检查登录页 UI 元素完整性
3. 输入错误凭证，验证错误提示
4. 输入正确凭证，验证登录流程
5. 检查登录后状态持久化

场景 S1.2: 基础聊天

1. 在聊天框输入 "你好，请介绍一下你自己"
2. 观察流式响应是否正常
3. 验证 Markdown 渲染（代码块、列表、标题）
4. 输入 "请用 Python 写一个快排" → 验证代码块渲染
5. 点击取消按钮中断响应
6. 创建新对话，验证历史对话保留

场景 S1.3: 模型切换

1. 打开模型选择器
2. 列出所有可用模型
3. 切换到不同模型
4. 发送消息验证新模型响应
5. 验证模型标识在 UI 中正确显示

Phase 2: Agent 管理与技能（P1）

场景 S2.1: Agent CRUD

1. 打开 Agent 管理面板
2. 创建新 Agent（名称、人设描述）
3. 切换到新 Agent
4. 验证人设在对话中体现
5. 编辑 Agent 属性
6. 删除 Agent

场景 S2.2: 技能浏览与执行

1. 进入技能市场
2. 浏览技能分类
3. 搜索特定技能（如 "翻译"）
4. 查看技能详情
5. 执行一个简单技能
6. 验证结果在聊天中展示

场景 S2.3: Hands 触发

1. 进入 Hands 面板
2. 查看 9 个可用 Hands 状态
3. 触发一个无需审批的 Hand（如 Researcher）
4. 验证执行状态和结果
5. 触发需审批的 Hand（如 Browser）
6. 验证审批弹窗和审批流程

Phase 3: 自动化与工作流（P2）

场景 S3.1: 自动化面板

1. 切换到自动化页签
2. 查看触发器列表
3. 创建新触发器
4. 查看审批队列
5. 查看执行历史

场景 S3.2: Pipeline 工作流

1. 进入工作流编辑器
2. 拖拽节点创建简单工作流
3. 保存工作流
4. 运行工作流
5. 查看执行结果

场景 S3.3: 课堂生成

1. 触发课堂生成
2. 观察生成进度
3. 播放课堂内容
4. 测试场景交互（白板、笔记、TTS）

Phase 4: 设置与智能层（P2-P3）

场景 S4.1: 设置页面遍历

1. 逐一打开 12 个设置页面
2. 验证每个页面的数据加载
3. 修改设置并保存
4. 验证设置持久化

场景 S4.2: 记忆系统

1. 打开右侧面板记忆页签
2. 查看已存储记忆
3. 搜索记忆
4. 查看记忆图谱
5. 删除单条记忆

场景 S4.3: 智能层

1. 查看心跳配置
2. 查看反思日志
3. 查看身份状态
4. 响应身份变化提案

Phase 5: Admin V2 管理后台

场景 S5.1: Admin 登录与仪表盘

1. 打开 Admin V2 Web 界面
2. 管理员登录
3. 查看仪表盘关键指标

场景 S5.2: 账户与角色管理

1. 账户列表查看
2. 创建/编辑/禁用账户
3. 角色权限配置

场景 S5.3: 模型与中继管理

1. Provider 配置
2. 模型管理
3. API Key 轮换
4. 中继任务查看

场景 S5.4: 知识库与定时任务

1. 知识库分类管理
2. 知识条目 CRUD
3. 定时任务配置

---

4. 功能验证点及判断标准

验证等级定义

等级	标识	含义
PASS	✅	功能完全符合设计预期
PARTIAL	⚠️	功能部分实现或存在非关键问题
FAIL	❌	功能不可用或严重偏离设计
N/A	➖	前置条件不满足，无法验证

每个验证点的检查维度

1. UI 完整性: 页面元素是否完整渲染，无空白/缺失
2. 交互响应: 用户操作是否得到预期反馈
3. 数据正确性: 显示数据是否与后端一致
4. 状态一致性: 操作后 UI 状态是否正确更新
5. 错误处理: 异常操作是否有合理提示
6. 持久化: 修改是否被正确保存

通用判断标准

• PASS: 6 个维度全部满足
• PARTIAL: 1-2 个维度不满足但不影响核心功能
• FAIL: 3 个以上维度不满足或核心功能不可用

---

5. 问题记录与跟踪机制

问题严重性分级

级别	定义	示例
BLOCKER	系统无法启动或核心功能完全不可用	应用崩溃、登录失败
CRITICAL	主要功能不可用	聊天无法发送、模型无法切换
MAJOR	功能部分失效或结果不正确	技能执行无结果、设置无法保存
MINOR	UI 问题或体验不佳	样式错乱、文案错误
TRIVIAL	极小问题，不影响使用	拼写错误、间距不均

问题记录模板

### ISS-XXX: [简短标题]
- **模块**: M01-M15
- **严重性**: BLOCKER/CRITICAL/MAJOR/MINOR/TRIVIAL
- **验证点**: 对应的验证点编号
- **现象描述**: 详细描述观察到的行为
- **预期行为**: 应该发生什么
- **复现步骤**:
  1. 步骤一
  2. 步骤二
  3. ...
- **实际截图/日志**: 附件
- **影响范围**: 影响哪些用户/场景
- **根因分析**: 初步判断的原因
- **修复建议**: 建议的修复方向

---

6. 验证结果汇总报告模板

# ZCLAW 功能验证报告

**验证日期**: YYYY-MM-DD
**验证人**: Claude Code (tauri-mcp)
**应用版本**: 从 package.json 获取
**测试环境**: Windows 11 + Tauri 2.x

## 执行摘要

| 指标 | 数值 |
|------|------|
| 总验证点数 | N |
| PASS | N (X%) |
| PARTIAL | N (X%) |
| FAIL | N (X%) |
| N/A | N (X%) |
| BLOCKER | N |
| CRITICAL | N |
| MAJOR | N |
| MINOR | N |
| TRIVIAL | N |

## 模块验证矩阵

| 模块 | 验证点数 | PASS | PARTIAL | FAIL | N/A | 备注 |
|------|---------|------|---------|------|-----|------|
| M01 登录 | | | | | | |
| M02 聊天 | | | | | | |
| ... | | | | | | |

## 问题清单

### BLOCKER
[列表]

### CRITICAL
[列表]

### MAJOR
[列表]

### MINOR
[列表]

### TRIVIAL
[列表]

## 关键发现

### 功能亮点
1. ...
2. ...

### 需要关注的问题
1. ...
2. ...

## 修复优先级建议

1. **立即修复** (BLOCKER + CRITICAL)
2. **本迭代修复** (MAJOR)
3. **后续迭代** (MINOR + TRIVIAL)