# 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. 验证结果汇总报告模板

```markdown
# 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)
```