# 炼妖壶 (Lianyaohu) - 稷下学宫AI辩论系统

## 项目概览

**炼妖壶**是一个基于中国哲学传统的多AI智能体辩论平台，当前版本为 **v2.0.0**。项目采用模块化架构，集成了OpenBB金融数据平台，提供专业的投资分析和AI辩论功能。

## 快速开始

### 环境要求
- Python 3.12+
- Google Cloud账户 (已配置: abstract-banner-460615-j4)
- RapidAPI密钥
- 可选: OpenRouter API密钥, OpenBB支持

### 安装和运行
```bash
# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate

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

# 启动应用
streamlit run app/streamlit_app.py
```

## 核心功能

### 1. 稷下学宫辩论系统
- **八仙论道**: 基于中国传统八仙文化的AI辩论系统
- **先天八卦顺序**: 严格的辩论顺序规则
- **双模式支持**: Google ADK模式和传统RapidAPI模式
- **记忆银行**: 集成Vertex AI的记忆系统

### 2. OpenBB金融数据集成
- **专业金融数据**: 股票、ETF、价格历史、公司概况等
- **八仙专属数据源**: 每位八仙分配专门的数据源和专业领域
- **智能降级机制**: API失败时自动使用演示数据
- **实时数据展示**: 动态图表和关键指标

### 3. 多AI服务支持
- **Google ADK**: 新一代AI代理开发工具包
- **OpenRouter**: 多模型AI服务路由
- **Vertex AI**: Google云AI服务 (已配置)
- **OpenAI Swarm**: 智能体框架

## 配置管理

### 必需配置
```bash
# 在 .env 文件中设置
RAPIDAPI_KEY=your_rapidapi_key
# 选择以下之一
GOOGLE_API_KEY=your_google_api_key
OPENROUTER_API_KEY_1=your_openrouter_key
```

### 可选配置
```bash
# Google Cloud配置 (已设置项目ID)
GOOGLE_CLOUD_PROJECT_ID=abstract-banner-460615-j4
GOOGLE_CLOUD_LOCATION=us-central1

# 记忆银行配置
VERTEX_MEMORY_BANK_ENABLED=TRUE
JIXIA_MEMORY_BACKEND=vertex
```

## 项目架构

```
liurenchaxin/
├── app/                    # Streamlit应用界面
│   ├── streamlit_app.py   # 主应用入口
│   └── tabs/              # 功能模块
│       ├── openbb_tab.py  # OpenBB数据展示
│       └── adk_debate_tab.py # Google ADK辩论
├── src/jixia/             # 稷下学宫核心系统
│   ├── engines/           # 数据引擎
│   │   ├── openbb_engine.py    # OpenBB集成
│   │   └── perpetual_engine.py # 永动机引擎
│   ├── debates/           # 辩论系统
│   ├── memory/            # 记忆银行
│   └── coordination/      # 多聊天协调
├── OpenBB/                # OpenBB源码 (子模块)
├── config/               # 配置管理
└── docs/                 # 文档
```

## 当前状态

### 已完成功能
- ✅ Google Vertex AI认证和配置
- ✅ OpenBB v4.1.0集成
- ✅ 八仙辩论系统
- ✅ 记忆银行系统 (Vertex AI)
- ✅ Streamlit界面
- ✅ 智能降级机制
- ✅ 多AI服务支持

### 技术栈
- **前端**: Streamlit + Plotly
- **后端**: Python + FastAPI
- **AI服务**: Google Vertex AI, OpenRouter, Google ADK
- **数据源**: OpenBB, RapidAPI (17个订阅)
- **记忆系统**: Vertex AI Memory Bank
- **部署**: Docker + GitHub Actions

## 开发指南

### 添加新的AI服务
1. 在 `config/settings.py` 中添加API密钥配置
2. 在 `src/jixia/agents/` 中创建新的代理类
3. 在 `src/jixia/engines/` 中添加数据引擎
4. 在 `app/tabs/` 中添加界面页签

### 扩展OpenBB功能
1. 查看 `src/jixia/engines/openbb_engine.py`
2. 在 `OpenBBStockData` 类中添加新方法
3. 更新 `app/tabs/openbb_tab.py` 界面
4. 添加相应的错误处理和降级机制

### 记忆银行使用
```python
from src.jixia.memory.factory import get_memory_backend

# 获取记忆后端
memory = get_memory_backend()

# 存储记忆
await memory.add_memory("用户查询", "AI响应", metadata={"source": "debate"})

# 检索相关记忆
relevant_memories = await memory.get_relevant_memories("当前话题")
```

## 故障排除

### 常见问题
1. **Vertex AI认证错误**: 确保运行 `gcloud auth application-default login`
2. **OpenBB导入失败**: 运行 `pip install openbb>=4.1.0`
3. **API密钥错误**: 检查 `.env` 文件中的密钥配置
4. **记忆银行错误**: 确保Vertex AI API已启用

### 调试命令
```bash
# 检查Google Cloud认证
gcloud auth list

# 验证配置
python -c "from config.doppler_config import validate_config; validate_config()"

# 测试Vertex AI连接
python -c "from vertexai import init; init(project='abstract-banner-460615-j4')"
```

## 路线图

### 短期目标
- [ ] 扩展OpenBB到更多金融产品
- [ ] 添加技术分析指标
- [ ] 实现实时数据流
- [ ] 优化辩论算法

### 长期目标
- [ ] 集成OpenBB Workspace
- [ ] 添加投资组合分析
- [ ] 实现量化策略
- [ ] 多语言支持

## 贡献指南

1. Fork项目
2. 创建功能分支: `git checkout -b feature/new-feature`
3. 提交更改: `git commit -m 'Add new feature'`
4. 推送分支: `git push origin feature/new-feature`
5. 创建Pull Request

## 许可证

MIT License - 详见 LICENSE 文件

---

**最后更新**: 2025-08-18
**版本**: v2.0.0
**维护者**: 稷下学宫团队