stock-ai-agent/README.md

# A股AI分析Agent系统

基于AI Agent的股票智能分析系统，提供自然语言对话界面，支持实时行情查询、技术分析、基本面分析等功能。

## 功能特性

- **自然语言对话**：通过对话方式查询股票信息
- **实时行情查询**：获取股票实时价格、涨跌幅等数据
- **技术指标分析**：计算MA、MACD、RSI、KDJ、BOLL等技术指标
- **基本面信息**：查询公司概况、行业、上市日期等
- **数据可视化**：生成专业的K线图和技术指标图表
- **技能插件系统**：可扩展的技能架构，支持动态启用/禁用
- **对话历史**：保存和查看历史分析记录

## 技术栈

### 后端
- **框架**：FastAPI
- **AI Agent**：LangChain + 智谱AI GLM-4
- **数据源**：Tushare
- **缓存**：内存缓存（无需Redis）
- **数据库**：SQLite
- **语言**：Python 3.11+ (推荐 3.11 或 3.12)

### 前端
- **框架**：Vue 3 (CDN版本)
- **UI**：Bootstrap 5
- **图表**：Lightweight Charts
- **通信**：Fetch API

## 项目结构

```
Stock_Agent/
├── backend/                    # 后端代码
│   ├── app/
│   │   ├── agent/             # AI Agent核心
│   │   ├── api/               # API路由
│   │   ├── models/            # 数据模型
│   │   ├── services/          # 数据服务
│   │   ├── skills/            # 技能插件
│   │   ├── utils/             # 工具函数
│   │   ├── config.py          # 配置管理
│   │   └── main.py            # 应用入口
│   └── requirements.txt       # Python依赖
├── frontend/                   # 前端代码
│   ├── css/                   # 样式文件
│   ├── js/                    # JavaScript文件
│   └── index.html             # 主页面
├── .env.example               # 环境变量示例
├── .gitignore
└── README.md
```

## 快速开始

### ⚠️ 重要提示：Python 版本

**推荐使用 Python 3.11 或 3.12**。如果您使用 Python 3.13，可能会遇到依赖安装问题。

详细的安装问题解决方案请查看：[安装指南](docs/INSTALL_GUIDE.md)

### 1. 环境准备

**系统要求**：
- Python 3.11 或 3.12（推荐）
- 无需 Redis（使用内存缓存）

**获取API密钥**：
- [Tushare](https://tushare.pro/)：注册并获取Token
- [智谱AI](https://open.bigmodel.cn/)：注册并获取API Key

### 2. 安装依赖

```bash
# 进入后端目录
cd backend

# 创建虚拟环境（使用 Python 3.11）
python3.11 -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# 安装依赖
pip install --upgrade pip
pip install -r requirements.txt
```

**如果遇到安装错误**，请查看 [安装指南](docs/INSTALL_GUIDE.md) 获取详细解决方案。

### 3. 配置环境变量

复制 `.env.example` 为 `.env` 并填写配置：

```bash
cp .env.example .env
```

编辑 `.env` 文件：

```env
# Tushare API
TUSHARE_TOKEN=your_tushare_token_here

# 智谱AI GLM-4 API
ZHIPUAI_API_KEY=your_zhipuai_key_here

# 其他配置保持默认即可
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0

# 其他配置保持默认即可
```

### 4. 启动Redis（可选）

如果要使用缓存功能，请先启动Redis：

```bash
# macOS (使用Homebrew)
brew services start redis

# Linux
sudo systemctl start redis

# Windows
# 下载并运行Redis for Windows
```

### 5. 启动后端服务

```bash
# 在backend目录下
cd backend

# 启动服务
python -m app.main

# 或使用uvicorn
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

服务启动后，访问：
- 前端界面：http://localhost:8000
- API文档：http://localhost:8000/docs

## 使用指南

### 基本查询

1. **查询实时行情**
   ```
   查询600519的实时行情
   贵州茅台的价格
   000001现在多少钱
   ```

2. **查看K线图**
   ```
   600519的K线图
   贵州茅台的走势
   ```

3. **技术指标分析**
   ```
   600519的技术指标
   分析贵州茅台的MACD
   ```

4. **基本面信息**
   ```
   600519的基本信息
   贵州茅台是什么行业
   ```

### 技能管理

点击右上角"技能管理"按钮，可以：
- 查看所有可用技能
- 启用/禁用特定技能
- 查看技能描述

## API文档

启动服务后，访问 http://localhost:8000/docs 查看完整的API文档。

### 主要接口

#### 1. 发送消息
```http
POST /api/chat/message
Content-Type: application/json

{
  "message": "查询600519的实时行情",
  "session_id": "optional_session_id"
}
```

#### 2. 获取对话历史
```http
GET /api/chat/history/{session_id}
```

#### 3. 获取股票行情
```http
GET /api/stock/quote/{stock_code}
```

#### 4. 获取K线数据
```http
GET /api/stock/kline/{stock_code}?start_date=20240101&end_date=20240201
```

#### 5. 获取技能列表
```http
GET /api/skills/
```

## 开发指南

### 添加新技能

1. 在 `backend/app/skills/` 目录下创建新的技能文件
2. 继承 `BaseSkill` 类并实现 `execute` 方法
3. 在 `backend/app/agent/core.py` 中注册新技能

示例：

```python
from app.skills.base import BaseSkill, SkillParameter

class MyNewSkill(BaseSkill):
    def __init__(self):
        super().__init__()
        self.name = "my_skill"
        self.description = "我的新技能"
        self.parameters = [
            SkillParameter(
                name="param1",
                type="string",
                description="参数1",
                required=True
            )
        ]

    async def execute(self, **kwargs) -> Dict[str, Any]:
        # 实现技能逻辑
        return {"result": "success"}
```

### 扩展数据源

在 `backend/app/services/` 目录下添加新的数据服务类，参考 `tushare_service.py` 的实现。

## 常见问题

### 1. Redis连接失败

如果Redis未安装或未启动，系统会自动降级，不影响核心功能，但会失去缓存能力。

### 2. Tushare API限制

免费版Tushare有调用频率限制（120次/分钟）。如果遇到限制，可以：
- 等待一段时间后重试
- 考虑升级到付费版
- 使用Redis缓存减少API调用

### 3. 股票代码格式

支持的股票代码格式：
- 6位数字：600000、000001
- 带后缀：600000.SH、000001.SZ
- 股票名称：贵州茅台、中国平安

### 4. 端口被占用

如果8000端口被占用，可以修改 `.env` 文件中的 `API_PORT` 配置。

## 性能优化

1. **启用Redis缓存**：显著减少API调用和响应时间
2. **调整缓存TTL**：在 `cache_service.py` 中根据需求调整缓存时间
3. **限制历史消息数**：在 `context.py` 中调整 `max_history` 参数

## 安全建议

1. **生产环境**：
   - 修改 `.env` 中的 `SECRET_KEY`
   - 设置 `DEBUG=False`
   - 配置严格的CORS策略
   - 使用HTTPS

2. **API密钥**：
   - 不要将 `.env` 文件提交到版本控制
   - 定期更换API密钥
   - 使用环境变量或密钥管理服务

## 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启Pull Request

## 许可证

本项目采用 MIT 许可证。

## 联系方式

如有问题或建议，请提交Issue。

## 致谢

- [Tushare](https://tushare.pro/) - 金融数据接口
- [智谱AI](https://open.bigmodel.cn/) - AI模型服务
- [FastAPI](https://fastapi.tiangolo.com/) - Web框架
- [LangChain](https://www.langchain.com/) - AI Agent框架
- [Lightweight Charts](https://tradingview.github.io/lightweight-charts/) - 图表库