跳到主要内容

HTTP API 深度解析

本系列文档深入分析 CountBot 的 HTTP 请求和响应格式，展示真实的 API 交互流程。

文档列表​

01. 基础对话的 HTTP 请求响应流程​

展示用户发送简单消息"你好"时的完整 HTTP 交互流程。

包含内容:

  • 前端发送的完整 HTTP 请求
  • 后端如何构建系统提示词
  • 后端如何拼接历史消息
  • 发送给 LLM 的完整 messages 数组
  • LLM 返回的原始响应
  • 后端如何处理流式响应
  • 返回给前端的 SSE 格式
  • 保存到数据库的记录

适用场景: 理解基础对话流程、调试简单消息问题

02. 工具调用的 HTTP 请求响应流程​

展示用户发送"读取 README.md 文件"时的完整工具调用流程。

包含内容:

  • 工具定义的完整 JSON Schema 格式
  • 发送给 LLM 的 tools 参数（完整数组）
  • LLM 返回的 tool_calls 格式
  • 后端如何解析 tool_calls
  • 工具执行后的结果格式
  • 将工具结果添加回 messages 的格式
  • 第二次调用 LLM 的 messages 数组
  • 最终返回给用户的响应
  • 工具调用记录的数据库存储

适用场景: 理解工具调用机制、调试工具执行问题、开发自定义工具

03. 系统提示词构建详解​

详细说明 CountBot 如何构建发送给 LLM 的系统提示词。

包含内容:

  • 系统提示词的作用和重要性
  • 核心身份部分（基本信息、性格设定、工具使用原则）
  • 文件操作规范
  • 记忆系统说明
  • 安全准则
  • 工作原则
  • 技能系统部分（自动加载、按需加载）
  • 多智能体团队部分
  • 会话总结注入
  • 渠道信息注入
  • 完整示例（最小配置、完整配置）
  • 代码位置和配置文件

适用场景: 理解 AI 行为、自定义性格、配置技能、调试提示词问题

04. 多轮对话的 messages 数组演变​

展示 3 轮对话中 messages 数组的完整演变过程。

包含内容:

  • 第 1 轮：用户"你好" → AI 回复
  • 第 2 轮：用户"读取 README.md" → AI 调用工具 → AI 回复
  • 第 3 轮：用户"谢谢" → AI 回复
  • 每一轮的完整 messages 数组结构
  • 历史消息的加载和限制
  • 滚动窗口机制（超出限制时的处理）
  • 会话总结注入
  • 自动记忆写入
  • 完整流程图

适用场景: 理解对话上下文管理、调试历史消息问题、优化记忆使用

05. SSE 流式响应格式详解​

详细说明 CountBot 的 Server-Sent Events (SSE) 流式响应格式。

包含内容:

  • SSE 基础知识
  • CountBot 的 SSE 事件类型（start, message, done, error）
  • 事件数据格式
  • 完整的 SSE 流示例（简单对话、工具调用、错误处理）
  • 后端实现（SSE 生成器、StreamingResponse）
  • 前端实现（原生 EventSource、fetch API、React 示例）
  • 调试技巧（curl 测试、浏览器开发者工具）
  • 常见问题（消息延迟、连接断开、CORS 错误）
  • 性能优化（批量发送、压缩）
  • 安全考虑（认证、速率限制、输入验证）

适用场景: 理解流式响应、调试 SSE 问题、优化前端性能

06. WebSocket 通知格式详解​

详细说明 CountBot 的 WebSocket 实时通知系统。

包含内容:

  • WebSocket 概述（为什么需要 WebSocket）
  • 消息格式（基础结构、消息类型列表）
  • 工具调用通知（tool_call, tool_result, tool_start, tool_complete, tool_error, tool_progress）
  • 子代理任务通知（subagent_start, subagent_progress, subagent_complete, subagent_error）
  • 通用通知（error, ping, pong）
  • 完整示例场景（读取文件、调用子代理、工具执行错误）
  • 后端实现（连接管理、WebSocket 端点、发送通知）
  • 前端实现（原生 WebSocket、React Hook）
  • 调试技巧（wscat 测试、浏览器开发者工具）
  • 安全考虑（认证、速率限制）

适用场景: 理解实时通知、调试 WebSocket 问题、开发实时 UI

快速导航​

按使用场景​

场景推荐文档
我想了解基础对话流程01. 基础对话
我想开发自定义工具02. 工具调用
我想自定义 AI 性格03. 系统提示词
我想优化对话上下文04. 多轮对话
我想实现流式响应05. SSE 流式响应
我想显示实时进度06. WebSocket 通知

按技术栈​

技术相关文档
HTTP/REST API01. 基础对话, 02. 工具调用
Server-Sent Events05. SSE 流式响应
WebSocket06. WebSocket 通知
LLM 集成03. 系统提示词, 04. 多轮对话
数据库设计02. 工具调用, 04. 多轮对话

按开发阶段​

阶段推荐文档
快速入门01. 基础对话
功能开发02. 工具调用, 03. 系统提示词
性能优化04. 多轮对话, 05. SSE 流式响应
用户体验05. SSE 流式响应, 06. WebSocket 通知
调试排错所有文档

代码位置速查​

功能文件路径
Chat API 端点backend/api/chat.py
Agent Loop 核心逻辑backend/modules/agent/loop.py
上下文构建backend/modules/agent/context.py
工具注册表backend/modules/tools/registry.py
LLM Providerbackend/modules/providers/factory.py / backend/modules/providers/openai_provider.py / backend/modules/providers/anthropic_provider.py
WebSocket 连接管理backend/ws/connection.py
WebSocket 路由backend/app.py
工具通知backend/ws/tool_notifications.py
会话管理backend/modules/session/manager.py
提示词模板backend/modules/agent/prompts.py

阅读建议​

新手入门​

  1. 先阅读 01. 基础对话，理解基础流程
  2. 再阅读 03. 系统提示词，了解 AI 行为配置
  3. 然后阅读 05. SSE 流式响应，学习前端集成

进阶开发​

  1. 阅读 02. 工具调用，学习工具开发
  2. 阅读 04. 多轮对话，优化上下文管理
  3. 阅读 06. WebSocket 通知，实现实时 UI

问题排查​

  1. 对话不符合预期 → 03. 系统提示词
  2. 工具调用失败 → 02. 工具调用
  3. 历史消息丢失 → 04. 多轮对话
  4. 流式响应延迟 → 05. SSE 流式响应
  5. 实时通知不显示 → 06. WebSocket 通知

实战示例​

示例 1: 发送简单消息​

curl -X POST http://localhost:8000/api/chat/send \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "message": "你好",
    "attachments": null
  }'

详细说明见 01. 基础对话

示例 2: 调用工具​

curl -X POST http://localhost:8000/api/chat/send \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "message": "读取 README.md 文件",
    "attachments": null
  }'

详细说明见 02. 工具调用

示例 3: 获取消息历史​

curl -X GET "http://localhost:8000/api/chat/sessions/550e8400-e29b-41d4-a716-446655440000/messages"

详细说明见 04. 多轮对话

示例 4: 连接 WebSocket​

const ws = new WebSocket('ws://localhost:8000/ws/550e8400-e29b-41d4-a716-446655440000');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
};

详细说明见 06. WebSocket 通知

关键概念​

messages 数组​

发送给 LLM 的消息列表，包含：

  • system: 系统提示词（定义 AI 行为）
  • user: 用户消息
  • assistant: AI 回复
  • tool: 工具执行结果

详细说明见 04. 多轮对话

tools 数组​

可用工具的定义列表，每个工具包含：

  • name: 工具名称
  • description: 工具描述
  • parameters: JSON Schema 格式的参数定义

详细说明见 02. 工具调用

tool_calls​

LLM 返回的工具调用请求，包含：

  • id: 调用 ID
  • type: 类型（固定为 "function"）
  • function.name: 工具名称
  • function.arguments: JSON 字符串格式的参数

详细说明见 02. 工具调用

SSE 事件​

Server-Sent Events 的事件类型：

  • start: 消息开始
  • message: 内容片段
  • done: 消息完成
  • error: 错误信息

详细说明见 05. SSE 流式响应

WebSocket 消息​

实时通知的消息类型：

  • tool_call: 工具调用开始
  • tool_result: 工具执行结果
  • subagent_start: 子代理任务开始
  • subagent_progress: 子代理任务进度
  • subagent_complete: 子代理任务完成

详细说明见 06. WebSocket 通知

🤝 贡献​

如果你发现文档中的错误或有改进建议，欢迎：

  1. 提交 Issue
  2. 发起 Pull Request
  3. 在社区讨论

📝 更新日志​

  • 2024-01-15: 创建完整的 HTTP API 深度解析文档系列
    • 01. 基础对话的 HTTP 请求响应流程
      1. 工具调用的 HTTP 请求响应流程
      1. 系统提示词构建详解
      1. 多轮对话的 messages 数组演变
      1. SSE 流式响应格式详解
      1. WebSocket 通知格式详解

📧 联系方式​

如有问题，请通过以下方式联系：