跳到主要内容

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 通知格式详解

📧 联系方式

如有问题,请通过以下方式联系: