# ClawTeam Platform - 演示详解

本文档详细介绍了 ClawTeam 演示场景，解释了 bots 如何协作处理数据。

## 概览

演示展示了一个完整的 bot 协作工作流，其中：
- **Orchestrator Bot** 协调多步骤工作流
- **DataAnalyzer Bot** 执行统计分析
- **Notifier Bot** 发送通知

## 演示场景：数据处理工作流

### 参与 Bots

#### 1. Orchestrator Bot
**角色**：工作流协调器

**能力**：
- `process_workflow`：协调多步骤数据处理

**职责**：
- 接收用户的工作流请求
- 发现具有所需能力的 bots
- 将任务委托给适当的 bots
- 汇总结果

#### 2. DataAnalyzer Bot
**角色**：数据分析专家

**能力**：
- `analyze_data`：分析数值数据数组

**职责**：
- 接受数字数组
- 计算统计信息（总和、平均值、最小值、最大值、中位数、标准差）
- 返回分析结果

#### 3. Notifier Bot
**角色**：通知服务

**能力**：
- `send_notification`：向指定频道发送通知

**职责**：
- 接受通知消息
- 发送到指定频道
- 确认发送

## 工作流执行

### 分步流程

```
用户请求 → Orchestrator → DataAnalyzer → Orchestrator → Notifier → 完成
```

### 详细步骤

#### 步骤 0：用户发起工作流
```json
{
  "toBotId": "orchestrator-bot-id",
  "capability": "process_workflow",
  "parameters": {
    "data": [1, 2, 3, 4, 5]
  },
  "priority": "normal"
}
```

#### 步骤 1：Orchestrator 接收任务
- Orchestrator bot 接收 `process_workflow` 任务
- 验证输入参数
- 规划工作流执行

#### 步骤 2：查找 DataAnalyzer Bot
- Orchestrator 搜索具有 `analyze_data` 能力的 bot
- 使用 Capability Registry API：`/api/capabilities/search?capability=analyze_data`
- 找到 DataAnalyzer bot

#### 步骤 3：委托分析任务
Orchestrator 为 DataAnalyzer 创建任务：
```json
{
  "fromBotId": "orchestrator-bot-id",
  "toBotId": "data-analyzer-bot-id",
  "capability": "analyze_data",
  "parameters": {
    "data": [1, 2, 3, 4, 5]
  },
  "priority": "normal"
}
```

#### 步骤 4：DataAnalyzer 处理数据
DataAnalyzer 通过 WebSocket 接收任务并计算：
```json
{
  "count": 5,
  "sum": 15,
  "avg": 3,
  "min": 1,
  "max": 5,
  "median": 3,
  "stdDev": 1.414
}
```

#### 步骤 5：查找 Notifier Bot
- Orchestrator 搜索具有 `send_notification` 能力的 bot
- 找到 Notifier bot

#### 步骤 6：发送通知
Orchestrator 为 Notifier 创建任务：
```json
{
  "fromBotId": "orchestrator-bot-id",
  "toBotId": "notifier-bot-id",
  "capability": "send_notification",
  "parameters": {
    "message": "数据分析完成！结果：avg=3.00, min=1, max=5, count=5",
    "channel": "workflow-status"
  },
  "priority": "normal"
}
```

#### 步骤 7：完成工作流
Orchestrator 将工作流任务标记为已完成：
```json
{
  "success": true,
  "analysisResult": { ... },
  "processedAt": "2026-02-03T10:30:00Z"
}
```

## 预期时间线

总工作流持续时间：**< 10 秒**

- 任务创建：~100ms
- Bot 发现：每个能力 ~200ms
- 分析执行：~5s
- 通知：~2s
- 总开销：~1s

## 运行演示

### 快速开始

```bash
# 终端 1：启动演示环境
bash scripts/demo/start-demo.sh

# 等待所有服务启动（~30 秒）

# 浏览器：打开 Dashboard
open http://localhost:5173

# 终端 2：触发工作流（可选 - 改用 Dashboard）
curl -X POST http://localhost:3000/api/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "fromBotId": "user",
    "toBotId": "orchestrator-bot-id",
    "capability": "process_workflow",
    "parameters": {"data": [10, 20, 30, 40, 50]},
    "priority": "normal"
  }'
```

### 使用 Dashboard

1. **导航到 Bots 页面**
   - 查看 3 个注册的 bots
   - 检查它们的在线状态
   - 查看它们的能力

2. **创建任务**
   - 转到 Tasks 页面
   - 点击 "Create Task" 按钮
   - 选择 "Orchestrator" 作为 "To Bot"
   - 选择 "process_workflow" 能力
   - 输入参数：`{"data": [1, 2, 3, 4, 5]}`
   - 点击 "Create Task"

3. **观察实时更新**
   - 任务出现在任务列表中
   - 状态变化：pending → processing → completed
   - 查看 DataAnalyzer 和 Notifier 的子任务
   - 所有更新自动发生（WebSocket）

## 预期输出

### Dashboard 视图

**Bot 列表页面：**
```
┌─────────────────────────────────────┐
│ DataAnalyzer         [在线]         │
│ • analyze_data                      │
│   分析数值数据                      │
└─────────────────────────────────────┘

┌─────────────────────────────────────┐
│ Notifier             [在线]         │
│ • send_notification                 │
│   发送通知                          │
└─────────────────────────────────────┘

┌─────────────────────────────────────┐
│ Orchestrator         [在线]         │
│ • process_workflow                  │
│   协调工作流                        │
└─────────────────────────────────────┘
```

**任务列表页面：**
```
┌─────────────────────────────────────┐
│ process_workflow    [已完成]        │
│ Orchestrator → Orchestrator         │
│ 时长：8.5s                          │
│ 结果：{ success: true, ... }        │
└─────────────────────────────────────┘

┌─────────────────────────────────────┐
│ analyze_data        [已完成]        │
│ Orchestrator → DataAnalyzer         │
│ 时长：5.2s                          │
│ 结果：{ avg: 3, min: 1, ... }       │
└─────────────────────────────────────┘

┌─────────────────────────────────────┐
│ send_notification   [已完成]        │
│ Orchestrator → Notifier             │
│ 时长：2.1s                          │
│ 结果：{ sent: true }                │
└─────────────────────────────────────┘
```

### 终端输出

**DataAnalyzer 日志：**
```
[DataAnalyzer] Starting bot...
[DataAnalyzer] Registered with ID: abc-123
[DataAnalyzer] WebSocket connected
[DataAnalyzer] Bot started successfully
[DataAnalyzer] Received task: analyze_data (task-456)
[DataAnalyzer] Processing task: task-456
[DataAnalyzer] Analysis result: { count: 5, sum: 15, avg: 3, ... }
[DataAnalyzer] Task completed: task-456
```

**Notifier 日志：**
```
[Notifier] Starting bot...
[Notifier] Registered with ID: def-789
[Notifier] WebSocket connected
[Notifier] Bot started successfully
[Notifier] Processing notification: task-789
[Notifier] 📢 Notification sent to workflow-status:
[Notifier] Message: 数据分析完成！结果：avg=3.00, min=1, max=5, count=5
```

**Orchestrator 日志：**
```
[Orchestrator] Starting bot...
[Orchestrator] Registered with ID: ghi-012
[Orchestrator] WebSocket connected
[Orchestrator] Bot started successfully
[Orchestrator] Starting workflow: task-123
[Orchestrator] Step 1: Finding DataAnalyzer bot...
[Orchestrator] Found DataAnalyzer: abc-123
[Orchestrator] Step 2: Delegating analysis task...
[Orchestrator] Waiting for analysis to complete...
[Orchestrator] Analysis complete: { avg: 3, ... }
[Orchestrator] Step 3: Finding Notifier bot...
[Orchestrator] Found Notifier: def-789
[Orchestrator] Step 4: Sending notification...
[Orchestrator] Workflow completed successfully
```

## 故障排除

### 常见问题

#### Bots 未出现在 Dashboard 中
- 检查 bot 日志：`tail -f logs/data-analyzer.log`
- 验证 API 服务器正在运行：`curl http://localhost:3000/health`
- 检查数据库连接

#### 任务未执行
- 验证 bots 在线（Dashboard 中的绿色状态）
- 检查浏览器控制台中的 WebSocket 连接
- 查看 API 服务器日志：`tail -f logs/api.log`

#### WebSocket 断开连接
- 检查防火墙设置
- 验证端口 3000 可访问
- 在日志中查找连接错误

### 获取帮助

如果遇到问题：
1. 检查 `logs/` 目录中的所有日志
2. 验证所有服务正在运行：`ps aux | grep node`
3. 检查 Docker 服务：`docker-compose ps`
4. 查看浏览器控制台中的错误消息（F12）

## 下一步

完成演示后：

1. **探索代码**
   - 查看 `examples/bots/` 中的 bot 实现
   - 研究 `packages/client-sdk/` 中的 Client SDK
   - 检查 `packages/dashboard/` 中的 Dashboard 组件

2. **创建您自己的 Bot**
   - 按照指南操作：`examples/创建您的Bot.md`
   - 尝试不同的能力
   - 测试 bot 交互

3. **自定义工作流**
   - 修改 Orchestrator 逻辑
   - 为现有 bots 添加新能力
   - 创建新的演示场景

4. **深入了解**
   - 阅读架构文档：`docs/architecture.md`
   - 探索 API 文档：http://localhost:3000/docs
   - 研究核心模块（Task Coordinator、Message Bus 等）

## 演示变体

### 变体 1：大数据集
```json
{
  "data": [1, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50]
}
```

### 变体 2：多个工作流
同时创建多个任务以查看并行处理。

### 变体 3：优先级测试
创建不同优先级的任务（urgent、high、normal、low）以观察任务排序。

### 变体 4：错误处理
尝试无效输入以查看错误处理：
```json
{
  "data": "not-an-array"
}
```

## 架构亮点

演示展示了这些关键平台功能：

1. **动态 Bot 发现**：Bots 通过能力相互发现
2. **异步任务委托**：即发即忘的任务创建
3. **实时更新**：基于 WebSocket 的状态更新
4. **优先级队列**：按优先级处理任务
5. **错误处理**：优雅的失败和重试
6. **可观察性**：完全可见的任务流程

## 性能指标

演示工作流的预期性能：

- **Bot 注册**：< 500ms
- **能力搜索**：< 100ms
- **任务创建**：< 50ms
- **任务分发**：< 200ms（通过 WebSocket）
- **端到端工作流**：< 10s

在 Dashboard 的任务卡片中监控这些指标（Duration 字段）。

---

**实施日期**：2026-02-03
**状态**：演示就绪 ✅
