ab1589921a
## 安全修复 (12项) - Webhook接口添加全局Token认证，过滤敏感请求头 - 修复JWT Base64 padding公式，防止签名验证绕过 - 数据库密码/飞书Token从源码移除，改为环境变量 - 工作流引擎添加路径遍历防护 (_resolve_safe_path) - eval()添加模板长度上限检查 - 审批API添加认证依赖 - 前端v-html增强XSS转义，console.log仅开发模式输出 - 500错误不再暴露内部异常详情 ## Agent运行时修复 (7项) - 删除_inject_knowledge_context中未定义db变量的finally块 - 工具执行添加try/except保护，异常不崩溃Agent - LLM重试计入budget计数器 - self_review异常时passed=False - max_iterations截断标记success=False - 工具参数JSON解析失败时记录警告日志 - run()开始时重置_llm_invocations计数器 ## 配置与基础设施 - DEBUG默认False，SQL_ECHO独立配置项 - init_db()补全13个缺失模型导入 - 新增WEBHOOK_AUTH_TOKEN/SQL_ECHO配置项 - 新增.env.example模板文件 ## 前端修复 (12项) - 登录改用URLSearchParams替代FormData - 401拦截器通过Pinia store统一清理状态 - SSE流超时从60s延长至300s - final/error事件时清除streamTimeout - localStorage聊天记录添加24h TTL - safeParseArgCount替代模板中裸JSON.parse - fetchUser 401时同时清除user对象 ## 新增模块 - 知识进化: knowledge_extractor/retriever/tasks - 数字孪生: shadow_executor/comparison模型 - 行为采集: behavior_middleware/collector/fingerprint_engine - 代码审查: code_review_agent/document_review_agent - 反馈学习: feedback_learner - 瓶颈检测/优化引擎/成本估算/需求估算 - 速率限制器 (rate_limiter) - Alembic迁移 015-020 ## 文档 - 商业化落地计划 - 8篇docs文档 (架构/API/部署/开发/贡献等) - Docker Compose生产配置 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
404 lines
7.2 KiB
Markdown
404 lines
7.2 KiB
Markdown
# 🔌 API 参考文档
|
||
|
||
> **API Reference**
|
||
|
||
本文档描述了天工智能体平台后端 RESTful API 接口规范。所有 API 均通过 Nginx 反向代理暴露，前缀为 `/api/v1`。
|
||
|
||
> 💡 **交互式文档**：启动后端服务后，可访问 `http://localhost:8037/docs` 查看 Swagger UI 文档。
|
||
|
||
---
|
||
|
||
## 一、通用规范
|
||
|
||
### 基础 URL
|
||
|
||
```
|
||
生产环境：https://your-domain.com/api/v1
|
||
开发环境：http://localhost:8037/api/v1
|
||
```
|
||
|
||
### 认证方式
|
||
|
||
所有受保护的接口需在请求头中携带 JWT Token：
|
||
|
||
```http
|
||
Authorization: Bearer <access_token>
|
||
```
|
||
|
||
### 响应格式
|
||
|
||
```json
|
||
// 成功响应
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": { ... }
|
||
}
|
||
|
||
// 错误响应
|
||
{
|
||
"code": 40001,
|
||
"message": "用户不存在",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
### 通用错误码
|
||
|
||
| 状态码 | 错误码 | 说明 |
|
||
|:------|:-------|:------|
|
||
| 200 | 200 | 请求成功 |
|
||
| 400 | 40000 | 请求参数错误 |
|
||
| 401 | 40100 | 未认证（Token 缺失或过期） |
|
||
| 403 | 40300 | 无权限访问 |
|
||
| 404 | 40400 | 资源不存在 |
|
||
| 500 | 50000 | 服务器内部错误 |
|
||
|
||
---
|
||
|
||
## 二、用户模块
|
||
|
||
### 2.1 用户注册
|
||
|
||
注册新用户账号。
|
||
|
||
```http
|
||
POST /api/v1/users/register
|
||
```
|
||
|
||
**请求体：**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|:-----|:-----|:-----|:------|
|
||
| `email` | string | ✅ | 邮箱地址 |
|
||
| `password` | string | ✅ | 密码（至少 8 位，含字母和数字） |
|
||
| `nickname` | string | ❌ | 用户昵称 |
|
||
|
||
**请求示例：**
|
||
|
||
```json
|
||
{
|
||
"email": "user@example.com",
|
||
"password": "Abc12345",
|
||
"nickname": "张三"
|
||
}
|
||
```
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"id": 1,
|
||
"email": "user@example.com",
|
||
"nickname": "张三",
|
||
"created_at": "2026-05-10T08:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2.2 用户登录
|
||
|
||
获取 JWT 访问令牌。
|
||
|
||
```http
|
||
POST /api/v1/users/login
|
||
```
|
||
|
||
**请求体：**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|:-----|:-----|:-----|:------|
|
||
| `email` | string | ✅ | 邮箱地址 |
|
||
| `password` | string | ✅ | 密码 |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"access_token": "eyJhbGciOiJIUzI1NiIs...",
|
||
"refresh_token": "eyJhbGciOiJIUzI1NiIs...",
|
||
"token_type": "bearer",
|
||
"expires_in": 1800
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2.3 Token 刷新
|
||
|
||
使用 Refresh Token 获取新的 Access Token。
|
||
|
||
```http
|
||
POST /api/v1/users/refresh
|
||
```
|
||
|
||
**请求体：**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|:-----|:-----|:-----|:------|
|
||
| `refresh_token` | string | ✅ | 登录时获取的 Refresh Token |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"access_token": "eyJhbGciOiJIUzI1NiIs...",
|
||
"refresh_token": "eyJhbGciOiJIUzI1NiIs...",
|
||
"token_type": "bearer",
|
||
"expires_in": 1800
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2.4 获取当前用户信息
|
||
|
||
获取已登录用户的个人信息。
|
||
|
||
```http
|
||
GET /api/v1/users/me
|
||
```
|
||
|
||
**请求头：**
|
||
```http
|
||
Authorization: Bearer <access_token>
|
||
```
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"id": 1,
|
||
"email": "user@example.com",
|
||
"nickname": "张三",
|
||
"avatar": "https://...",
|
||
"created_at": "2026-05-10T08:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 三、智能体模块
|
||
|
||
### 3.1 创建智能体
|
||
|
||
创建一个新的 AI 智能体。
|
||
|
||
```http
|
||
POST /api/v1/agents
|
||
```
|
||
|
||
**请求体：**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|:-----|:-----|:-----|:------|
|
||
| `name` | string | ✅ | 智能体名称 |
|
||
| `description` | string | ❌ | 智能体描述 |
|
||
| `prompt_template` | string | ✅ | 系统提示词模板 |
|
||
| `model_config` | object | ✅ | LLM 模型配置 |
|
||
|
||
**`model_config` 对象：**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|:-----|:-----|:-----|:------|
|
||
| `provider` | string | ✅ | 模型提供商：`openai` / `azure` / `local` |
|
||
| `model_name` | string | ✅ | 模型名称：`gpt-4o` / `gpt-3.5-turbo` |
|
||
| `temperature` | number | ❌ | 生成温度（默认 0.7） |
|
||
| `max_tokens` | integer | ❌ | 最大 Token 数（默认 2048） |
|
||
|
||
**请求示例：**
|
||
|
||
```json
|
||
{
|
||
"name": "智能客服助手",
|
||
"description": "用于解答常见产品问题",
|
||
"prompt_template": "你是一个专业的客服助手...",
|
||
"model_config": {
|
||
"provider": "openai",
|
||
"model_name": "gpt-4o",
|
||
"temperature": 0.5,
|
||
"max_tokens": 2048
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3.2 获取智能体列表
|
||
|
||
获取当前用户的所有智能体。
|
||
|
||
```http
|
||
GET /api/v1/agents?page=1&page_size=20
|
||
|
||
```
|
||
|
||
**查询参数：**
|
||
|
||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||
|:-----|:-----|:-----|:-------|:------|
|
||
| `page` | integer | ❌ | 1 | 页码 |
|
||
| `page_size` | integer | ❌ | 20 | 每页条数（最大 100） |
|
||
|
||
---
|
||
|
||
### 3.3 获取智能体详情
|
||
|
||
```http
|
||
GET /api/v1/agents/{agent_id}
|
||
```
|
||
|
||
**路径参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|:-----|:-----|:------|
|
||
| `agent_id` | integer | 智能体 ID |
|
||
|
||
---
|
||
|
||
### 3.4 更新智能体
|
||
|
||
```http
|
||
PUT /api/v1/agents/{agent_id}
|
||
```
|
||
|
||
**请求体：**（部分更新）
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|:-----|:-----|:-----|:------|
|
||
| `name` | string | ❌ | 智能体名称 |
|
||
| `description` | string | ❌ | 智能体描述 |
|
||
| `prompt_template` | string | ❌ | 系统提示词 |
|
||
| `model_config` | object | ❌ | 模型配置 |
|
||
|
||
---
|
||
|
||
### 3.5 删除智能体
|
||
|
||
```http
|
||
DELETE /api/v1/agents/{agent_id}
|
||
```
|
||
|
||
---
|
||
|
||
## 四、对话模块
|
||
|
||
### 4.1 创建对话会话
|
||
|
||
```http
|
||
POST /api/v1/conversations
|
||
```
|
||
|
||
**请求体：**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|:-----|:-----|:-----|:------|
|
||
| `agent_id` | integer | ✅ | 关联的智能体 ID |
|
||
| `title` | string | ❌ | 会话标题（可选） |
|
||
|
||
---
|
||
|
||
### 4.2 发送消息
|
||
|
||
向指定对话发送消息，支持流式响应（SSE）。
|
||
|
||
```http
|
||
POST /api/v1/conversations/{conversation_id}/messages
|
||
```
|
||
|
||
**请求体：**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|:-----|:-----|:-----|:------|
|
||
| `content` | string | ✅ | 用户消息内容 |
|
||
|
||
**流式响应（SSE）：**
|
||
|
||
```
|
||
data: {"type": "token", "content": "你好"}
|
||
data: {"type": "token", "content": "，"}
|
||
data: {"type": "token", "content": "请问有什么可以帮您？"}
|
||
data: {"type": "done"}
|
||
data: {"type": "error", "content": "..."}
|
||
```
|
||
|
||
---
|
||
|
||
### 4.3 获取对话历史
|
||
|
||
```http
|
||
GET /api/v1/conversations/{conversation_id}/messages?page=1&page_size=50
|
||
```
|
||
|
||
---
|
||
|
||
## 五、知识库模块
|
||
|
||
### 5.1 上传文档
|
||
|
||
```http
|
||
POST /api/v1/knowledge/documents/upload
|
||
```
|
||
|
||
**请求格式：** `multipart/form-data`
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|:-----|:-----|:-----|:------|
|
||
| `file` | file | ✅ | 支持 PDF / TXT / Markdown |
|
||
| `agent_id` | integer | ✅ | 关联的智能体 ID |
|
||
|
||
---
|
||
|
||
### 5.2 文档检索
|
||
|
||
```http
|
||
POST /api/v1/knowledge/search
|
||
```
|
||
|
||
**请求体：**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|:-----|:-----|:-----|:------|
|
||
| `query` | string | ✅ | 检索关键词 |
|
||
| `agent_id` | integer | ✅ | 限定知识库范围 |
|
||
| `top_k` | integer | ❌ | 返回条数（默认 5） |
|
||
|
||
---
|
||
|
||
## 六、健康检查
|
||
|
||
```http
|
||
GET /api/v1/health
|
||
```
|
||
|
||
**响应：**
|
||
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"version": "1.0.0",
|
||
"timestamp": "2026-05-10T08:00:00Z"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
> 📎 **相关文档**：[快速开始指南](./quickstart.md) | [开发指南](./development-guide.md)
|