一、html需求详述
新建templateHtml.py来生成html文件
1.1 顶部导航栏

**内容**:

1. **标题区域**
   - 显示当前选中 Trace 的 task 名称
   - 可配置的图标和文字

2. **筛选条件区域**
   - 使用原生 HTML 表单元素（select、input 等）
   - 筛选项包括但不限于:
     - 状态筛选（running/completed/failed）
     - Trace 选择下拉框
     - 刷新按钮
   - 筛选条件变化时触发数据重新加载


1.2 主体内容区域 

**功能**: 流程图可视化展示

1.2.1 节点交互

**交互行为**:

- 点击节点时,在主体内容区域高亮显示从 root 到该节点的完整路径
- 同时显示该节点最近的边的内容

1.2.2 边交互

**交互行为**:
- 内容以层级结构展示,支持展开/收起

1.3 右侧详情面板


**显示模式**:

1. **节点详情模式**
   - 显示节点的基本信息
   - 显示节点的元数据
   - 显示相关的边信息



二、数据交互规范
新建templateData.py来获取接口数据
2.1 HTTP 接口

**Base URL**: `http://www.bai.com`

2.1.1 获取 Trace 列表

**接口**: `GET /api/traces?status=running&limit=20`

**用途**: 获取 trace_id 列表，顶部 title 显示选中 trace 的 task

**查询参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `status` | string | 否 | 过滤状态：`running` / `completed` / `failed` |
| `mode` | string | 否 | 过滤模式：`call` / `agent` |
| `limit` | int | 否 | 返回数量（默认 50，最大 100）|

**响应数据**:
\`\`\`typescript
interface TraceListResponse {
traces: Array<{
trace_id: string;
mode: string; // "agent" | "call"
task: string; // 任务描述，用于顶部标题显示
status: string; // "running" | "completed" | "failed"
total_messages: number;
total_tokens: number;
total_cost: number;
current_goal_id: string;
created_at: string;
}>;
total: number;
}
\`\`\`

**html使用**:

- 顶部 title 显示 `trace.task`
- 可根据 status 筛选正在运行/已完成的任务

2.1.2 获取 GoalTree 数据（渲染流程节点）

**接口**: `GET /api/traces/{trace_id}`

**用途**: 获取完整的 GoalTree 数据，根据 `goal_tree.goals` 渲染流程节点

**响应数据**:
\`\`\`typescript
interface TraceDetailResponse {
trace_id: string;
mode: string;
task: string;
status: string;
total_messages: number;
total_tokens: number;
total_cost: number;
created_at: string;
completed_at: string | null;

// GoalTree 数据 - 用于渲染流程节点
goal_tree: {
mission: string;
current_id: string | null;
goals: Array<{
id: string; // Goal 唯一 ID
parent_id: string | null; // 父节点 ID（用于构建层级）
branch_id: string | null; // 所属分支（null=主线）
type: string; // "normal" | "explore_start" | "explore_merge"
description: string; // 目标描述
reason: string; // 创建理由
status: string; // "pending" | "in_progress" | "completed" | "abandoned"
summary: string | null; // 完成时的总结

      // 统计数据（用于边的显示）
      self_stats: {
        message_count: number;
        total_tokens: number;
        total_cost: number;
        preview: string | null;  // 工具调用摘要，如 "read → edit × 2"
      };
      cumulative_stats: {
        message_count: number;
        total_tokens: number;
        total_cost: number;
        preview: string | null;
      };

      // 分支相关（仅 explore 类型）
      branch_ids?: string[];  // explore_start 关联的分支
      explore_start_id?: string;  // explore_merge 关联的 explore_start
      merge_summary?: string;
      selected_branch?: string;
    }>;

};

// 分支元数据（用于分支节点显示）
branches: Record<string, {
id: string;
explore_start_id: string;
description: string;
status: string;
summary: string | null;
cumulative_stats: {
message_count: number;
total_tokens: number;
total_cost: number;
preview: string | null;
};
goal_count: number;
last_message: any;
}>;
}
\`\`\`

**html使用**:

- **节点渲染**: 遍历 `goal_tree.goals` 数组，每个 Goal 对象渲染为一个流程节点
- **节点层级**: 通过 `parent_id` 构建父子关系
- **节点类型**: 根据 `type` 字段区分普通节点、分支开始、分支汇合
- **节点状态**: 使用 `status` 字段设置节点样式（进行中/已完成/待处理）
- **边的统计**: 使用 `self_stats` 或 `cumulative_stats` 显示边上的统计信息

#### 5.1.3 获取 Messages 数据（渲染边的详细内容）

**接口**: `GET /api/traces/{trace_id}/messages?goal_id={goal_id}`

**用途**: 获取指定 Goal 关联的所有 Messages，用于渲染流程节点之间的边的详细执行内容

**查询参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `goal_id` | string | 否 | 过滤指定 Goal 的 Messages |
| `branch_id` | string | 否 | 过滤指定分支的所有 Messages |

**响应数据**:
\`\`\`typescript
interface MessagesResponse {
messages: Array<{
message_id: string;
role: string; // "assistant" | "tool"
sequence: number; // 全局顺序
goal_id: string; // 关联的 Goal ID
branch_id: string | null;

    // assistant 消息
    description?: string;
    content?: {
      text: string;
      tool_calls?: Array<{
        id: string;
        name: string;  // 工具名称
        arguments: any;
      }>;
    };

    // tool 消息
    tool_call_id?: string;

    // 统计信息
    tokens: number | null;
    cost: number | null;
    created_at: string;

}>;
total: number;
}
\`\`\`

**html使用**:

- **边详情显示**: 点击边时，调用此接口获取该边对应的 Goal 的所有 Messages
- **层级展示**: 将 Messages 按 sequence 排序，组织成时间线或对话形式
- **工具调用**: 显示 assistant 消息中的 tool_calls 和对应的 tool 返回结果

#### 5.1.4 获取分支详情（按需加载）

**接口**: `GET /api/traces/{trace_id}/branches/{branch_id}`

**用途**: 展开分支时，按需加载分支内的详细 GoalTree

**响应数据**:
\`\`\`typescript
interface BranchDetailResponse {
id: string;
explore_start_id: string;
description: string;
status: string;
summary: string | null;
goal_tree: {
mission: string;
current_id: string | null;
goals: Array<{/_ 同 5.1.2 的 Goal 结构 _/}>;
};
cumulative_stats: {
message_count: number;
total_tokens: number;
total_cost: number;
preview: string | null;
};
}
\`\`\`

### 5.2 WebSocket 实时通信

**连接地址**: `ws://43.106.118.91:8000/api/traces/{trace_id}/watch?since_event_id=0`

**查询参数**:
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `since_event_id` | int | `0` | 从哪个事件 ID 开始。`0` = 补发所有历史 |

**事件类型**:

#### 1. connected（连接成功）

连接后推送完整 GoalTree，前端据此初始化流程图。

\`\`\`typescript
interface ConnectedEvent {
event: 'connected';
trace_id: string;
current_event_id: number;
goal_tree: {/_ 同 5.1.2 _/};
}
\`\`\`

#### 2. goal_added（新增节点）

\`\`\`typescript
interface GoalAddedEvent {
event: 'goal_added';
event_id: number;
goal: {/_ Goal 对象 _/};
parent_id: string | null;
}
\`\`\`

**前端处理**: 插入新节点，重新生成 DAG

#### 3. goal_updated（节点状态变化）

\`\`\`typescript
interface GoalUpdatedEvent {
event: 'goal_updated';
event_id: number;
goal_id: string;
updates: {
status?: string;
summary?: string;
};
affected_goals: Array<{
goal_id: string;
status?: string;
summary?: string;
cumulative_stats?: {/_ 统计数据 _/};
}>;
}
\`\`\`

**前端处理**: 更新节点状态和统计数据，更新边的显示

#### 4. message_added（新消息）

\`\`\`typescript
interface MessageAddedEvent {
event: 'message_added';
event_id: number;
message: {/_ Message 对象 _/};
affected_goals: Array<{
goal_id: string;
self_stats?: {/_ 统计数据 _/};
cumulative_stats?: {/_ 统计数据 _/};
}>;
affected_branches?: Array<{
branch_id: string;
explore_start_id: string;
cumulative_stats: {/_ 统计数据 _/};
}>;
}
\`\`\`

**前端处理**: 更新相关节点和边的统计数据

#### 5. trace_completed（任务完成）

\`\`\`typescript
interface TraceCompletedEvent {
event: 'trace_completed';
event_id: number;
trace_id: string;
total_messages: number;
total_tokens: number;
total_cost: number;
}
\`\`\`

**前端处理**: 标记任务完成，关闭 WebSocket

#### 6. branch_started（分支开始）

\`\`\`typescript
interface BranchStartedEvent {
event: 'branch_started';
event_id: number;
explore_start_id: string;
branch: {/_ Branch 对象 _/};
}
\`\`\`

#### 7. branch_completed（分支完成）

\`\`\`typescript
interface BranchCompletedEvent {
event: 'branch_completed';
event_id: number;
explore_start_id: string;
branch_id: string;
summary: string;
cumulative_stats: {/_ 统计数据 _/};
last_message: any;
}
\`\`\`

### 5.3 数据加载流程

**初始化流程**:

1. 调用 `GET /api/traces?status=running&limit=20` 获取 trace 列表
2. 顶部 title 显示 `trace.task`
3. 调用 `GET /api/traces/{trace_id}` 获取 GoalTree 数据
4. 根据 `goal_tree.goals` 渲染流程节点
5. 建立 WebSocket 连接 `ws://43.106.118.91:8000/api/traces/{trace_id}/watch` 进行实时更新

**节点交互流程**:

1. 用户点击节点（Goal）
2. 在主体内容区域高亮显示从 root 到该节点的路径
3. 右侧详情面板显示节点的基本信息（description, reason, status, summary）
4. 显示节点的统计信息（self_stats 和 cumulative_stats）

**边交互流程**:

1. 用户点击边（两个节点之间的连线）
2. 确定边对应的 target Goal 的 goal_id
3. 调用 `GET /api/traces/{trace_id}/messages?goal_id={goal_id}` 获取该 Goal 的 Messages
4. 右侧详情面板显示 Messages 列表，按时间顺序展示
5. 支持展开/收起每条消息的详细内容（tool_calls、返回结果等）


三、交互细节

3.1 节点点击交互流程

1. 用户点击节点
2. 系统计算从 root 到该节点的路径
3. 主体内容区域高亮显示路径
4. 右侧详情面板显示节点详情
5. 如果有最近的边,同时显示边的内容

3.2 边点击交互流程

1. 用户点击边
2. 系统获取边的完整内容（包括层级结构）
3. 右侧详情面板切换到边详情模式
4. 显示层级内容,默认展开第一层
5. 用户可以点击展开/收起子层级