LaodingBot/doc/WebUI_Stream_API_前端对接说明.md

# WebUI `/api/chat/stream` 前端对接说明

本文档用于指导前端项目接入 LaodingBot 的流式聊天接口，并可直接作为提示词输入给 LLM，批量改造其他前端代码。

## 1. 接口总览

- 方法: `POST`
- 路径: `/api/chat/stream`
- 请求头: `Content-Type: application/json`
- 响应类型: `text/event-stream`
- 协议: SSE (Server-Sent Events)

说明: 该接口为单次请求、多次推送。后端会持续推送 `data: <json>\n\n` 格式的事件。

## 2. 请求体

```json
{
  "text": "请帮我分析当前目录",
  "session_id": "sess_abc",
  "user_id": "user_001"
}
```

字段说明:

- `text` (string, required): 用户输入文本，去除空白后不能为空。
- `session_id` (string, optional): 会话 ID，不传时后端自动生成。
- `user_id` (string, optional): 用户 ID，不传时后端自动生成。

兼容字段:

- `sessionId` 等价于 `session_id`
- `userId` 等价于 `user_id`

## 3. SSE 事件格式

每条 SSE 消息只包含 `data` 字段，内容是 JSON:

```text
data: {"type":"thought","content":"我先判断是否需要调用工具","step":1}

data: {"type":"tool_call","content":"{\"input\":\"pwd\"}","step":1,"tool_name":"shell"}

data: {"type":"tool_result","content":"C:/Project/MyProject","step":1,"tool_name":"shell"}

data: {"type":"final","content":"当前目录是 C:/Project/MyProject","step":2}

```

事件字段:

- `type` (string): 事件类型
- `content` (string): 事件文本内容
- `step` (number, optional): ReAct 步骤编号
- `tool_name` (string, optional): 工具名

事件类型:

- `thought`: LLM 思考片段（可选透传）
- `tool_call`: 工具调用请求（可选透传）
- `tool_result`: 工具执行结果（可选透传）
- `final`: 最终回答
- `error`: 错误信息

说明:

- 默认情况下（`WEBUI_EXPOSE_REASONING=false`），WebUI 只向前端返回 `final` 和 `error`。
- 当设置 `WEBUI_EXPOSE_REASONING=true` 时，WebUI 会额外透传 `thought`、`tool_call`、`tool_result` 事件。
- 无论是否透传推理事件，`final` 都会分段累计推送，以便前端实现打字机效果。

## 4. 连接生命周期

- 正常结束: 收到 `type=final` 后结束渲染，连接可由浏览器自然关闭。
- 异常结束: 收到 `type=error`，前端应显示错误并结束当前轮次。
- 网络中断: 前端应允许用户重试，并保留已收到的事件记录。

## 5. 前端渲染建议

推荐前端仅处理两类结果:

- 答案区: 显示最后一个 `final`
- 错误区: 显示 `error`

如果开启了 `WEBUI_EXPOSE_REASONING=true`，建议额外提供“思考面板”：

- 思考区: 渲染 `thought`
- 工具区: 渲染 `tool_call` / `tool_result`

建议状态机:

- `idle`: 初始状态
- `streaming`: 请求中且持续接收事件
- `done`: 收到 `final`
- `failed`: 收到 `error` 或请求异常

## 6. TypeScript 对接示例 (fetch + ReadableStream)

```ts
type StreamEventType = 'thought' | 'tool_call' | 'tool_result' | 'final' | 'error';

interface StreamEvent {
  type: StreamEventType;
  content: string;
  step?: number;
  tool_name?: string;
}

export async function streamChat(
  payload: { text: string; session_id?: string; user_id?: string },
  onEvent: (event: StreamEvent) => void,
  signal?: AbortSignal,
): Promise<void> {
  const resp = await fetch('/api/chat/stream', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload),
    signal,
  });

  if (!resp.ok) {
    throw new Error(`HTTP ${resp.status}`);
  }
  if (!resp.body) {
    throw new Error('ReadableStream is not available');
  }

  const reader = resp.body.getReader();
  const decoder = new TextDecoder('utf-8');
  let buffer = '';

  while (true) {
    const { value, done } = await reader.read();
    if (done) break;

    buffer += decoder.decode(value, { stream: true });

    // SSE message delimiter: blank line
    let idx = buffer.indexOf('\n\n');
    while (idx >= 0) {
      const chunk = buffer.slice(0, idx).trim();
      buffer = buffer.slice(idx + 2);

      for (const line of chunk.split('\n')) {
        const text = line.trim();
        if (!text.startsWith('data:')) continue;
        const raw = text.slice(5).trim();
        if (!raw) continue;

        const event = JSON.parse(raw) as StreamEvent;
        onEvent(event);
      }

      idx = buffer.indexOf('\n\n');
    }
  }
}
```

## 7. 给 LLM 的改造任务提示词模板

将下面模板发给 LLM，可用于自动改造其他前端项目:

```text
你要改造一个前端项目的聊天页面，把非流式接口 `/api/chat` 改为流式接口 `/api/chat/stream`。

后端协议约束:
1) 请求方法 POST，Content-Type=application/json
2) 请求体: { text, session_id?, user_id? }
3) 响应是 SSE 文本流，事件格式为 `data: <json>\n\n`
4) JSON 结构:
   - type: thought | tool_call | tool_result | final | error
   - content: string
   - step?: number
   - tool_name?: string
5) 收到 final 视为本轮完成；收到 error 视为失败
6) 默认不要假设前端一定会收到 thought/tool_call/tool_result；仅当 `WEBUI_EXPOSE_REASONING=true` 才会透传

你的改造要求:
1) 保留现有 UI 风格和组件结构，不做无关重构
2) 新增流式读取逻辑，支持中途取消 (AbortController)
3) 将事件按 step 渲染到消息区
4) 兼容旧会话字段命名 (session_id / sessionId, user_id / userId)
5) 增加错误态与重试按钮
6) 不破坏原有上传、历史消息和输入框行为
7) 输出改动文件列表 + 每个文件的关键变更说明

请直接给出可运行代码补丁。
```

## 8. 调试清单

- 检查响应头是否为 `text/event-stream`
- 检查每条事件是否以 `data:` 开头并以空行结尾
- 确认 `final` 和 `error` 都能正确结束当前轮次
- 验证弱网下不会丢失已收到的事件
- 验证用户快速连续提问时，旧流可被取消