# Trea系统数据流可视化功能设计方案
## 基于光点动画的提示词处理流程实时展示
-–
## 文档信息
| 项目 | 内容 |
|------|------|
| 版本 | v1.0 |
| 日期 | 2026-05-05 |
| 状态 | 设计方案 |
-–
## 1. 功能概述与设计理念
### 1.1 核心功能描述
数据流可视化模块用于实时展示用户提示词在Harness Engineering系统中的处理流程，通过光点动画形式让用户直观感知数据在各模型间的流转状态。
### 1.2 设计目标
- **直观性**：用户一眼可感知数据流向与处理阶段
- **实时性**：光点移动速度与实际处理速度成比例
- **层次性**：通过颜色区分不同层级模型交互
- **可控性**：支持暂停/播放，便于细节查看
### 1.3 视觉风格定义
| 元素 | 样式定义 |
|------|----------|
| 光点基础 | 圆形，半径6px，发光效果 |
| 主任务光点 | 蓝色 `#2196F3`，发光半径15px |
| 子任务光点 | 橙色 `#FF9800`，发光半径10px |
| 连接线 | 渐变线条，宽度2-4px（脉冲效果） |
| 模型节点 | 圆角矩形，60x60px，状态变化时缩放1.1倍 |
-–
## 2. 界面布局设计
### 2.1 整体布局
```
┌─────────────────────────────────────────────────────────────────┐
│ 数据流可视化 [暂停] [播放] │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────┐ │
│ │ 主模型 │ ← 光点从输入区飞来 │
│ │ Node-A │ │
│ └────┬────┘ │
│ │ 分裂成3个子光点 │
│ ┌─────────────┼─────────────┐ │
│ ↓ ↓ ↓ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ 子模型1 │ │ 子模型2 │ │ 子模型3 │ │
│ │ Node-B1 │ │ Node-B2 │ │ Node-B3 │ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ │
├─────────────────────────────────────────────────────────────────┤
│ [用户输入区] → [处理中…] → [任务拆分可视化] → [结果聚合] │
└─────────────────────────────────────────────────────────────────┘
```
### 2.2 模型层级关系图结构
```
┌─────────────────────────────────────────────────────────────────┐
│ 模型层级关系图 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────┐ │
│ │ Level 0 │ 主模型层 │
│ │ 主模型 │ │
│ └─────┬─────┘ │
│ │ │
│ ┌───────────────┼───────────────┐ │
│ ↓ ↓ ↓ │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │ Level 1 │ │ Level 1 │ │ Level 1 │ │
│ │ 子模型1 │ │ 子模型2 │ │ 子模型3 │ │
│ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ │
│ │ │ │ │
│ └───────────────┼───────────────┘ │
│ ↓ │
│ ┌───────────┐ │
│ │ Level 2 │ 细粒度任务处理层 │
│ │ 工具/原子 │ │
│ └───────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
```
-–
## 3. 光点动画详细规格
### 3.1 光点属性定义
```typescript
interface LightPoint {
id: string; // 唯一标识
type: ‘primary’ | ‘sub’ | ‘result’; // 光点类型
color: string; // 颜色值
radius: number; // 半径
glowRadius: number; // 发光效果半径
position: { x: number; y: number }; // 当前位置
targetPosition: { x: number; y: number }; // 目标位置
speed: number; // 移动速度（px/帧）
opacity: number; // 透明度
trail: Position[]; // 拖尾轨迹点
}
interface Position {
x: number;
y: number;
timestamp: number;
}
```
### 3.2 光点类型与颜色
| 类型 | 颜色代码 | 含义 | 半径 | 发光半径 |
|------|----------|------|------|----------|
| 主光点 | `#2196F3` | 用户输入任务 | 6px | 15px |
| 子光点 | `#FF9800` | 拆分后子任务 | 5px | 10px |
| 返回光点 | `#4CAF50` | 结果返回 | 6px | 12px |
| 聚合光点 | `#9C27B0` | 结果聚合 | 7px | 15px |
### 3.3 光点生成与分裂动画
#### 3.3.1 初始光点生成
```
触发时机：用户提交提示词后100ms内
生成动画：
1. 在输入区域中心生成光点（scale: 0 → 1，200ms）
2. 光点出现后立即开始移动
3. 移动轨迹：贝塞尔曲线，从输入区到主模型节点
```
#### 3.3.2 光点分裂动画
```
触发时机：主模型返回任务拆分结果时
分裂过程：
┌─────────────────────────────────────────────────────┐
│ │
│ ● 主光点 │
│ (移动到分裂节点位置) │
│ │ │
│ │ 触发分裂 │
│ ↓ │
│ ┌─────────────────┐ │
│ │ 分裂动画区 │ │
│ │ 延迟: 150ms │ │
│ │ 原光点渐隐 │ │
│ └────────┬────────┘ │
│ ┌─────────┼─────────┐ │
│ ↓ ↓ ↓ │
│ ● ● ● │
│ 子光点1 子光点2 子光点3 │
│ (依次出现，间隔50ms) │
│ │
└─────────────────────────────────────────────────────┘
动画参数：
- 分裂延迟：150ms
- 子光点出现间隔：50ms
- 单个子光点生成动画：150ms (scale 0→1)
```
-–
## 4. 动态连接线规格
### 4.1 连接线类型
| 类型 | 样式 | 应用场景 |
|------|------|----------|
| 实线 | 普通实线 | 稳定的数据流 |
| 虚线 | 短划线动画 | 等待处理状态 |
| 脉冲线 | 宽度动态变化 | 正在传输中的数据 |
### 4.2 脉冲效果实现
```typescript
interface PulseLine {
baseWidth: number; // 基础线宽 2px
maxWidth: number; // 最大线宽 4px
pulseSpeed: number; // 脉冲速度 0.1/帧
pulseWidth: number; // 当前脉冲宽度
flowDirection: ‘forward’ | ‘backward’; // 流向
}
// 脉冲动画伪代码
function updatePulse(line: PulseLine) {
line.pulseWidth += line.pulseSpeed;
if (line.pulseWidth > line.maxWidth) {
line.pulseWidth = line.baseWidth;
}
// 绘制时使用 line.pulseWidth 作为线宽
}
```
### 4.3 动态路径绘制
```
路径绘制规则：
1. 根据起止节点位置计算贝塞尔曲线控制点
2. 控制点偏移量 = 节点间距 * 0.3
3. 路径上叠加脉冲效果动画
4. 箭头指示流向（位于路径末端）
```
-–
## 5. 模型节点状态动画
### 5.1 状态类型定义
| 状态 | 视觉表现 | 动画参数 |
|------|----------|----------|
| 空闲 | 正常显示 | 无 |
| 接收中 | 颜色加深10%，边框高亮 | 150ms ease-out |
| 处理中 | 轻微脉动动画 | scale 1.0-1.05, 500ms循环 |
| 完成 | 颜色恢复，绿色标记 | 200ms |
| 错误 | 红色边框，抖动 | shake 3次 |
### 5.2 状态动画规格
```typescript
interface NodeAnimation {
// 接收状态动画
onReceive: {
scale: 1.0 → 1.1 → 1.0, // 轻微放大
duration: 150,
easing: 'ease-out'
},
// 处理中动画
onProcessing: {
scale: 1.0 → 1.05 → 1.0, // 脉动
duration: 500,
repeat: true,
easing: 'ease-in-out'
},
// 完成动画
onComplete: {
colorShift: normal → highlight → normal,
duration: 200,
easing: 'ease-out'
}
}
```
-–
## 6. 交互控制功能
### 6.1 暂停/播放控制
| 功能 | 快捷键 | 按钮位置 | 说明 |
|------|--------|----------|------|
| 暂停 | `Space` | 顶部工具栏 | 暂停所有动画 |
| 播放 | `Space` | 顶部工具栏 | 恢复动画 |
| 停止 | `Esc` | 顶部工具栏 | 停止并重置 |
| 慢速 | `S` | 顶部工具栏 | 0.5倍速播放 |
| 正常速 | `N` | 顶部工具栏 | 1倍速播放 |
| 快速 | `F` | 顶部工具栏 | 2倍速播放 |
### 6.2 时间轴控制
```
时间轴组件设计：
┌─────────────────────────────────────────────────────────────────┐
│ [|<] [<] [
/❚❚] [>] [>|] [0%]═══════[100%] │
│ 重置 后退 播放/暂停 前进 结尾 进度滑块 │
└─────────────────────────────────────────────────────────────────┘
功能说明：
- 支持拖拽定位到任意时间点
- 显示当前处理阶段名称
- 显示已用时间/预计总时间
```
### 6.3 细节查看模式
| 功能 | 触发方式 | 效果 |
|------|----------|------|
| 节点高亮 | 悬停节点 | 非相关节点降低透明度 |
| 数据预览 | 点击节点 | 弹出数据详情面板 |
| 路径高亮 | 悬停光点 | 完整路径高亮显示 |
| 速度调节 | 滚轮 | 调整播放速度0.1x-3x |
-–
## 7. 数据结构设计
### 7.1 核心数据结构
```typescript
// 数据流事件
interface DataFlowEvent {
id: string;
timestamp: number;
type: EventType;
sourceNodeId: string;
targetNodeId?: string;
data?: any;
duration?: number; // 预计处理时长
}
type EventType =
| ‘input_received’ // 输入接收
| ‘task_splitting’ // 任务拆分
| ‘subtask_created’ // 子任务创建
| ‘subtask_processing’ // 子任务处理中
| ‘subtask_complete’ // 子任务完成
| ‘result_aggregating’ // 结果聚合
| ‘flow_complete’; // 流程完成
// 可视化节点
interface VisualNode {
id: string;
modelId: string;
modelName: string;
level: number; // 层级 0, 1, 2
position: { x: number; y: number };
status: NodeStatus;
inputConnections: string[];
outputConnections: string[];
}
// 可视化连接
interface VisualConnection {
id: string;
sourceNodeId: string;
targetNodeId: string;
type: ‘primary’ | ‘secondary’;
active: boolean;
progress: number; // 0-1 传输进度
}
// 数据流状态
interface DataFlowState {
events: DataFlowEvent[];
activeLightPoints: LightPoint[];
connections: VisualConnection[];
currentPhase: string;
totalDuration: number;
elapsedTime: number;
isPaused: boolean;
playbackSpeed: number;
}
```
### 7.2 事件序列示例
```
用户输入：“分析销售数据并生成报告”
事件序列：
1. { type: ‘input_received’, timestamp: 0 }
└─ 在输入区生成主光点
2. { type: ‘task_splitting’, timestamp: 200, targetNodeId: ‘main_model’ }
└─ 光点移动到主模型
3. { type: ‘subtask_created’, timestamp: 500, data: { count: 3 } }
└─ 主光点分裂为3个子光点
4. { type: ‘subtask_processing’, timestamp: 600, targetNodeId: ‘sub_model_1’ }
└─ 子光点1移动到子模型1
5. { type: ‘subtask_processing’, timestamp: 650, targetNodeId: ‘sub_model_2’ }
└─ 子光点2移动到子模型2
6. { type: ‘subtask_processing’, timestamp: 700, targetNodeId: ‘sub_model_3’ }
└─ 子光点3移动到子模型3
7. { type: ‘result_aggregating’, timestamp: 2000 }
└─ 子光点返回，聚合
8. { type: ‘flow_complete’, timestamp: 2500 }
└─ 最终结果光点到达输出区
```
-–
## 8. 技术实现方案
### 8.1 技术选型
| 层级 | 技术 | 说明 |
|------|------|------|
| 渲染引擎 | Pixi.js | 高性能2D渲染，适合粒子动画 |
| 动画库 | GSAP | 专业动画库，支持时间线控制 |
| 状态管理 | Zustand | 轻量级，支持中间件 |
| 框架 | React 18 | 组件化开发 |
### 8.2 核心模块架构
```
┌─────────────────────────────────────────────────────────────┐
│ DataFlowVisualization │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ CanvasLayer │ │ UILayer │ │
│ │ - 光点渲染 │ │ - 控制面板 │ │
│ │ - 连接线渲染 │ │ - 时间轴 │ │
│ │ - 节点渲染 │ │ - 状态显示 │ │
│ └────────┬────────┘ └────────┬────────┘ │
│ │ │ │
│ └────────────┬───────────┘ │
│ ↓ │
│ ┌─────────────────┐ │
│ │ AnimationEngine │ │
│ │ - 光点动画管理 │ │
│ │ - 脉冲效果控制 │ │
│ │ - 状态机管理 │ │
│ └────────┬────────┘ │
│ ↓ │
│ ┌─────────────────┐ │
│ │ DataFlowStore │ │
│ │ - 状态管理 │ │
│ │ - 事件队列 │ │
│ │ - 回放支持 │ │
│ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
```
### 8.3 性能优化策略
| 优化项 | 方案 | 预期效果 |
|--------|------|----------|
| 光点数量 | 对象池复用 | 减少GC |
| 渲染批次 | 批量绘制光点 | 提升60%性能 |
| 连接线 | 预计算路径 | 减少计算量 |
| 动画 | requestAnimationFrame | 流畅60fps |
| 拖尾效果 | 限制轨迹点数量 | 10个点/光点 |
-–
## 9. 组件清单
### 9.1 组件列表
| 组件名 | 功能 | 状态 |
|--------|------|------|
| DataFlowCanvas | 主画布容器 | 待开发 |
| LightPoint | 光点渲染组件 | 待开发 |
| ConnectionLine | 动态连接线 | 待开发 |
| ModelNode | 模型节点展示 | 待开发 |
| ControlPanel | 播放控制面板 | 待开发 |
| Timeline | 时间轴组件 | 待开发 |
| DataPreview | 数据预览弹窗 | 待开发 |
| PhaseIndicator | 阶段指示器 | 待开发 |
### 9.2 组件API示例
```tsx
// DataFlowCanvas 使用示例
<DataFlowCanvas
width={1200}
height={800}
nodes={modelNodes}
connections={connections}
events={dataFlowEvents}
playbackSpeed={1}
onNodeClick={(nodeId) => console.log(‘node clicked:’, nodeId)}
onPhaseChange={(phase) => console.log(‘phase:’, phase)}
/>
// ControlPanel 使用示例
<ControlPanel
isPaused={isPaused}
playbackSpeed={speed}
progress={progress}
onPlay={() => setIsPaused(false)}
onPause={() => setIsPaused(true)}
onSpeedChange={(s) => setSpeed(s)}
onSeek={(p) => seekTo(p)}
/>
```
-–
## 10. 实施计划
### 10.1 开发阶段
| 阶段 | 内容 | 周期 |
|------|------|------|
| Phase 1 | 基础画布搭建，节点渲染 | 3天 |
| Phase 2 | 光点动画系统 | 4天 |
| Phase 3 | 连接线动态效果 | 2天 |
| Phase 4 | 交互控制系统 | 3天 |
| Phase 5 | 状态管理与数据流集成 | 3天 |
| Phase 6 | 性能优化与测试 | 3天 |
### 10.2 验收标准
| 指标 | 目标值 |
|------|--------|
| 动画流畅度 | ≥55fps |
| 光点数量支持 | ≥50个同时动画 |
| 内存占用 | 增加≤100MB |
| 首屏加载 | ≤1.5s |
| 事件响应 | ≤16ms |
-–
**文档结束**
