From 85d8f49b7a97c55bb187eb2f9c6c758e4dc255cb Mon Sep 17 00:00:00 2001 From: eason Date: Wed, 21 Jan 2026 16:49:40 +0800 Subject: [PATCH] docs: update README with project overview, directory structure, core capabilities, and frontend integration tips --- README.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/README.md b/README.md index 3688ceb..659ae0a 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,51 @@ +## 项目简介 + +这是一个基于 **FastAPI** 的后端服务，提供「智能工作流」「知识库问答」「数据库智能查询」等能力，前端可以通过 REST API 调用这些能力。 + +### 主要目录结构（前端常用关注点） +- **`th_agenter/api/endpoints/`**：对外 HTTP 接口（路由） + - `auth.py`：登录、鉴权相关接口 + - `users.py` / `roles.py`：用户与角色管理 + - `chat.py` / `smart_chat.py` / `smart_query.py`：普通聊天、智能问答、智能查询 + - `knowledge_base.py`：知识库管理（上传文档、构建向量库、检索） + - `workflow.py`：工作流定义、获取、执行等接口 +- **`th_agenter/services/`**：业务逻辑层，API 绝大部分会调用这里 + - `workflow_engine.py` / `smart_workflow.py`：工作流执行引擎与智能工作流封装 + - `knowledge_chat.py` / `document_processor.py` / `embedding_factory.py`：知识库问答、向量检索、文档处理 + - `auth.py` / `user.py` 等：账号、权限等业务 +- **`th_agenter/schemas/`**：Pydantic 模型，定义接口请求/响应的数据结构 +- **`th_agenter/models/`**：SQLAlchemy 模型，对应数据库表结构 +- **`th_agenter/core/`**：应用配置、上下文、中间件、异常处理、权限控制等 +- **`th_agenter/db/`**：数据库连接、基础模型、Alembic 迁移脚本封装 +- **`utils/`**：日志（`util_log.py`）、文件、环境、异常等通用工具 +- **`scripts/`**：本地开发相关脚本（如 `start_local.sh`、`install_mysql.sh` 等） +- **`data/`**：本地数据与向量库文件（如 Chroma 存储） + +### 核心能力与典型接口 +- **鉴权与用户体系** + - 登录、Token 相关接口在 `auth.py` 中定义，一般使用 Bearer Token 放在 `Authorization` 头里。 + - 用户、角色、权限相关接口在 `users.py`、`roles.py`、`core/simple_permissions.py` 等文件中。 + +- **聊天与智能问答** + - 普通聊天接口：`chat.py` + - 智能聊天 / 智能问答：`smart_chat.py`、`smart_query.py`、`langchain_chat.py` + - 有些接口可能支持流式返回或长连接（如 SSE），可直接查看对应 endpoint 的返回类型。 + +- **知识库管理** + - 相关接口在 `knowledge_base.py` 中，业务逻辑在 `services/knowledge_base.py`、`services/document_processor.py`、`services/knowledge_chat.py` 中。 + - 支持上传文档（通常是 multipart）、构建向量库、基于文档进行问答。 + +- **工作流引擎** + - 路由在 `workflow.py`，核心执行逻辑在 `services/workflow_engine.py`、`services/smart_workflow.py`、`services/workflow_engine.py` 中。 + - 支持定义工作流、查询工作流详情、执行工作流，并在执行过程中写入日志/上下文（如 `session.desc`）。 + +### 前端对接小提示 +- **接口文档**：服务启动后可以访问 `http://localhost:8000/docs` 查看 Swagger 文档（或 `/redoc`）。 +- **认证方式**：大多需要携带 `Authorization: Bearer `，具体登录接口与返回字段可在 `auth.py` 与对应 `schemas` 中查看。 +- **上传文件**：知识库相关接口通常使用 `multipart/form-data`，前端可以用 `FormData` 构造请求。 +- **错误格式**：统一使用 FastAPI 的 JSON 错误响应格式，并在 `core/exceptions.py` 中做了封装，前端可以根据 `code`/`detail` 等字段做统一处理。 +- **调试追踪**：很多服务里会给 `session.desc` 等字段写入本次请求的行为描述（例如「获取工作流引擎」），方便在日志中排查问题。 + ## 启动项目（本地） 1. 准备环境