# Task Timeline View Design Document

## 1. Overview
The **Task Timeline View (Task Trace UI)** is a new management page that provides a unified, chronological view of all messages, tool calls, and actions performed by multiple Agents collaborating on a single "Task" (identified by a `taskId`). 
This page solves the "Black Box" problem by aggregating isolated agent conversation logs into a single, sortable, filterable timeline.

## 2. Core Features
- **Left Panel (Task List):** Displays all recent tasks in the system. Cards show the `taskId`, task progress/status, and the agents involved.
- **Right Panel (Unified Timeline):** A chronological feed of all `history.json` items spanning across all agents involved in the selected task.
- **Filtering & Search:** 
    - **Filter by Agent:** A multi-select dropdown to only show messages from specific agents (e.g. Master, Innovator, Hunter).
    - **Search Box:** Full-text search to filter messages by keyword.
    - **Sort Toggle:** Switch between ascending (oldest first) and descending (newest first) chronological order.

## 3. Backend Architecture Changes

### Data Source Challenge
Tasks in the system often represent an orchestration spawned from Master, such as `jobId` or `conversationId` mappings. 
To link conversations to a single logical "Task", we will scrape the meta tags from agent conversations. In recent builds, `meta.json` or directory names often reflect the global `jobId` or `conversationId` (e.g., `tpl-train-lemonv_drama-xxx` or `train-xxx`).

### New API Endpoints (`server/routes/tasks.js`)

**1. `GET /api/tasks`**
- **Action:** Scans the job store (`.data/jobs-train.json` or `.data/jobs.json`) and conversation metadata to return an array of top-level tasks.
- **Response Format:**
  ```json
  [
    {
       "taskId": "train-xxx",
       "type": "train-create",
       "status": "completed",
       "progress": "✅ 训练完成",
       "createdAt": "2026-03-29T12:00:00Z",
       "agentsInvolved": ["master", "innovator", "hunter", "digester", "evolver"]
    }
  ]
  ```

**2. `GET /api/tasks/:taskId/timeline`**
- **Action:** Aggregates and flattens all conversation logs associated with a `taskId`.
    - It searches all companies and system agents (`data/companies/*/agents/*` and `system/agents/*`).
    - Finds all conversation folders where the folder name or `meta.json`'s `conversationId` / `jobId` matches or contains the target `taskId`.
    - Reads `history.json` for all these matched conversations.
    - Annotates each message with `agentId` and `companyId`.
    - Sorts the final array globally by `timestamp`.
- **Response Format:**
  ```json
  [
    {
       "timestamp": "2026-03-29T12:00:01Z",
       "role": "assistant",
       "content": "🔧 [TOOL_CALL] Glob...",
       "agentId": "master",
       "companyId": "system",
       "conversationId": "conv-mnbq123"
    },
    {
       "timestamp": "2026-03-29T12:00:05Z",
       "role": "assistant",
       "content": "正在执行 hunted...",
       "agentId": "hunter",
       "companyId": "system",
       "conversationId": "hunt-xxx"
    }
  ]
  ```

## 4. Frontend Architecture Changes

### Routing (`web/src/router/index.js`)
- Add a new route `/tasks` mapped to the `TaskTimelineView`.

### Layout (`web/src/views/TaskTimelineView.vue`)
- **Structure:** Uses a `<div class="flex h-screen">` to split Left and Right.
- **Left Column:** Needs a highly scannable List View of Tasks.
    - Each item should highlight its Status using distinct colors (Green for `completed`, Yellow for `running`, Red for `failed`).
    - Highlights the list of involved agents using small tags (`<el-tag size="small">`).
- **Right Column:**
    - **Header:** Sticky Header containing Search (`<el-input>`), Agent Select Dropdown (`<el-select multiple>`), and Sort Button (`<el-button>`).
    - **Timeline Feed:** A scrollable `div` containing blocks of agent messages. Reuses the markdown renderer (`vue-markdown`) and adds specialized syntax highlighting/styling for the `🔧 [TOOL_CALL]` blocks to make them easily readable.
    - **Agent Identity Header:** Every message block starts with a distinct visual header `avatar/icon + Agent Name + precise time`.

### Navigation (`web/src/components/Sidebar.vue`)
- Add a new navigation item "Task Logs" / "任务看板" right below "MasterBot" or "Companies".

## 5. Implementation Steps
1. **Backend Base:** Create `server/services/task-service.js` containing the heavy logic for aggregating cross-agent logs.
2. **Backend Routes:** Create `server/routes/tasks.js` and mount it to `server/index.js` or `server/app.js`.
3. **Frontend API:** Expose API bindings for Tasks in the Vue frontend.
4. **Frontend View:** Implement `TaskTimelineView.vue` with dummy data to build the layout.
5. **Integration:** Connect the frontend view with the live `/api/tasks` backend and polish the UI interactions (filtering/sorting).