# 知识工具服务

这个项目主要完成以下的任务：
1. 可通过sh脚本启动，停止服务
2. 这个服务对外暴露一个接口，可以接收一个question字段，将question转化为若干可以进行爬虫任务的query词
3. 具体转化的任务交给一个agent即可，可以使用langgraph构建，通过执行tools定义的 suggestQuery，根据一个Prompt模版，将传入的问题拆解为若干的query词
4. 注意模块的封装，尽量拆的独立一些
5. 支持异步任务处理，提高系统响应性能

## 项目结构

```
knowledge-tools/
├── src/                    # 源代码目录
│   ├── api/               # API接口模块
│   │   └── main.py        # FastAPI主应用
│   ├── agent/             # LangGraph Agent模块
│   │   └── query_agent.py # 查询生成Agent
│   ├── tools/             # 工具模块
│   │   ├── query_tool.py  # 查询工具
│   │   ├── prompts.py     # Prompt模板
│   │   └── scheduler.py   # 任务调度器
│   ├── database/          # 数据库模块
│   │   ├── connection.py  # 数据库连接管理
│   │   └── models.py      # 数据库模型和DAO
│   └── models/            # 数据模型
│       └── schemas.py     # Pydantic模型
├── logs/                  # 日志目录
├── start.sh              # 启动脚本
├── stop.sh               # 停止脚本
├── main.py               # 主程序入口
├── requirements.txt      # Python依赖
├── app.pid              # 进程ID文件
└── .env                 # 环境变量配置文件
```

## 功能特性

- 🚀 **RESTful API**: 基于FastAPI构建的高性能API服务
- 🤖 **智能Agent**: 使用LangGraph构建的查询生成Agent
- 🗄️ **数据库支持**: MySQL数据库存储任务记录和状态跟踪
- ⚡ **异步处理**: 任务异步处理，提高系统响应性能
- ⏰ **定时调度**: 每分钟自动处理待执行任务
- 🔧 **模块化设计**: 清晰的模块分离，便于维护和扩展
- 📝 **详细日志**: 完整的日志记录和错误处理
- 🛠️ **便捷脚本**: 一键启动/停止服务脚本

## 快速开始

### 1. 环境准备

```bash
# 克隆项目（如果从git仓库）
git clone <repository-url>
cd knowledge-tools

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate     # Windows
```

### 2. 安装依赖

```bash
pip install -r requirements.txt
```

### 3. 配置环境变量

```bash
# 复制环境变量示例文件
cp env.example .env

# 编辑.env文件，设置你的OpenAI API密钥
vim .env
```

### 4. 启动服务

```bash
# 使用脚本启动（推荐）
./start.sh

# 或直接使用Python
python main.py
```

### 5. 测试服务

```bash
# 健康检查
curl http://localhost:8079/health

# 生成查询词（异步处理）
curl -X POST "http://localhost:8079/generate-queries" \
     -H "Content-Type: application/json" \
     -d '{"question": "如何学习Python编程"}'

# 查询任务状态
curl http://localhost:8079/task/1703123456789

# 运行异步处理测试（需要先创建测试脚本）
# python test_async_processing.py
```

## API接口

### 健康检查
- **GET** `/health`
- 返回服务状态

### 生成查询词（异步处理）
- **POST** `/generate-queries`
- 请求体：
  ```json
  {
    "question": "用户的问题"
  }
  ```
- 响应（立即返回，状态为待执行）：
  ```json
  {
    "task_id": 1703123456789,
    "queries": [],
    "original_question": "原始问题",
    "total_count": 0,
    "status": 0
  }
  ```
- 说明：接口立即返回任务ID，实际处理由后台定时任务完成

### 获取任务信息
- **GET** `/task/{task_id}`
- 响应：
  ```json
  {
    "task_id": 1703123456789,
    "question": "用户的问题",
    "queries": ["查询词1", "查询词2", "..."],
    "status": 2,
    "status_text": "成功"
  }
  ```
- 状态说明：
  - `0` - 待执行：任务已创建，等待后台处理
  - `1` - 执行中：任务正在处理中
  - `2` - 成功：任务处理完成，已生成查询词
  - `3` - 失败：任务处理失败

### 获取任务列表
- **GET** `/tasks?status=2&limit=10`
- 参数：
  - `status`: 任务状态筛选（0-待执行，1-执行中，2-成功，3-失败）
  - `limit`: 限制数量
- 响应：
  ```json
  {
    "tasks": [...],
    "total": 10
  }
  ```

## 服务管理

### 启动服务
```bash
./start.sh
```

### 停止服务
```bash
./stop.sh
```

### 查看日志
```bash
tail -f logs/app.log
```

## 异步任务处理

### 工作流程

1. **任务提交**: 调用 `/generate-queries` 接口提交问题
2. **立即返回**: 接口立即返回任务ID和待执行状态
3. **后台处理**: 定时调度器每分钟检查并处理待执行任务
4. **状态查询**: 通过 `/task/{task_id}` 接口查询任务处理状态

### 任务状态

- `0` - 待执行: 任务已创建，等待处理
- `1` - 执行中: 任务正在处理中
- `2` - 成功: 任务处理完成，已生成查询词
- `3` - 失败: 任务处理失败

### 测试异步处理

可以创建测试脚本验证异步处理功能：

```bash
# 创建测试脚本后运行
python test_async_processing.py
```

## 配置说明

主要配置项在 `.env` 文件中：

```env
# Gemini API配置
GEMINI_API_KEY=your_gemini_api_key_here
GEMINI_MODEL=gemini-1.5-pro

# 数据库配置
DB_HOST=rm-bp13g3ra2f59q49xs.mysql.rds.aliyuncs.com
DB_PORT=3306
DB_USER=wqsd
DB_PASSWORD=wqsd@2025
DB_NAME=ai_knowledge
DB_CHARSET=utf8

# 服务配置
HOST=0.0.0.0
PORT=8079
DEBUG=True

# 日志配置
LOG_LEVEL=INFO
LOG_FILE=logs/app.log
```

## 开发说明

### 模块说明

1. **API模块** (`src/api/`): 负责HTTP接口和路由处理
2. **Agent模块** (`src/agent/`): 包含LangGraph Agent逻辑
3. **工具模块** (`src/tools/`): 定义各种工具、Prompt模板和任务调度器
4. **数据库模块** (`src/database/`): 数据库连接、模型和DAO操作
5. **模型模块** (`src/models/`): 定义数据模型和Schema

### 扩展开发

- 添加新工具：在 `src/tools/` 目录下创建新的工具类
- 修改Prompt：编辑 `src/tools/prompts.py` 文件
- 调整Agent逻辑：修改 `src/agent/query_agent.py` 文件
- 添加新接口：在 `src/api/main.py` 中添加新的路由
- 调整调度策略：修改 `src/tools/scheduler.py` 文件

## 数据库表结构

项目使用MySQL数据库存储任务信息，需要创建以下表：

```sql
CREATE TABLE `knowledge_suggest_query` (
  `question` text COMMENT '问题',
  `task_id` bigint(20) NOT NULL COMMENT '任务id',
  `querys` mediumtext COMMENT '产出的query词，json格式',
  `status` int(11) DEFAULT NULL COMMENT '0:待执行；1:执行中；2:成功； 3:失败；',
  PRIMARY KEY (`task_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 COMMENT='生成query词任务';
```

## 注意事项

1. 确保已正确配置Gemini API密钥
2. 确保数据库连接配置正确，并已创建相应的表
3. 服务默认运行在8079端口，可通过环境变量修改
4. 日志文件保存在 `logs/app.log`
5. 生产环境建议设置 `DEBUG=False`
6. 异步任务处理：任务提交后立即返回，实际处理由后台定时任务完成
7. 定时调度器每分钟检查一次待执行任务，每次处理一条

## 故障排除

1. **服务启动失败**: 检查端口是否被占用，查看日志文件
2. **API调用失败**: 确认Gemini API密钥是否正确配置
3. **数据库连接失败**: 检查数据库配置和网络连接
4. **依赖安装失败**: 确保Python版本 >= 3.8
5. **任务处理失败**: 检查Agent配置和API密钥，查看任务状态
6. **定时任务不工作**: 检查调度器是否正常启动，查看日志文件
7. **进程无法停止**: 使用 `./stop.sh` 脚本，或手动查找并终止相关进程