Agent/frontend/htmlTemplate/需求.md

一、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; } ```

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; currentid: 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; goaltree: {/ 同 5.1.2 _/}; } ```

2. goal_added（新增节点）

```typescript interface GoalAddedEvent { event: 'goal_added'; eventid: 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; cumulativestats?: {/ 统计数据 _/}; }>; } ```

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

4. message_added（新消息）

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

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

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_startid: string; branch: {/ Branch 对象 _/}; } ```

7. branch_completed（分支完成）

```typescript interface BranchCompletedEvent { event: 'branch_completed'; event_id: number; explore_start_id: string; branch_id: string; summary: string; cumulativestats: {/ 统计数据 _/}; 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. 用户可以点击展开/收起子层级