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

## 项目概览

**炼妖壶**是一个基于中国哲学传统的多AI智能体辩论平台，当前版本为 **v2.1.0**。项目采用模块化架构，集成了OpenBB金融数据平台和Google ADK智能体框架，提供专业的投资分析和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辩论系统
- **先天八卦顺序**: 严格的辩论顺序规则
- **增强优先级算法**: v2.1.0版本的智能发言权分配
- **双模式支持**: Google ADK模式和传统RapidAPI模式
- **记忆银行**: 集成Vertex AI的记忆系统

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

### 3. 多AI服务支持
- **Google ADK**: 新一代AI代理开发工具包 (v1.10.0)
- **Gemini 2.0 Flash**: 最新的Gemini模型支持
- **OpenRouter**: 多模型AI服务路由
- **Vertex AI**: Google云AI服务 (已配置)
- **OpenAI Swarm**: 智能体框架
- **混合模式**: 支持多种AI服务的无缝切换

## 配置管理

### 必需配置
```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认证和配置
- ✅ Google ADK v1.10.0集成和迁移
- ✅ OpenBB v4.1.0集成
- ✅ 起承转合辩论系统 (v2.1.0)
- ✅ 增强优先级算法 (v2.1.0)
- ✅ 八仙辩论系统
- ✅ 记忆银行系统 (Vertex AI)
- ✅ 多聊天协调系统
- ✅ Streamlit界面
- ✅ 智能降级机制
- ✅ 多AI服务支持
- ✅ 性能监控和健康检查

### 技术栈
- **前端**: Streamlit + Plotly
- **后端**: Python + FastAPI
- **AI服务**: Google ADK v1.10.0, Gemini 2.0 Flash, Vertex AI, OpenRouter
- **数据源**: OpenBB v4.1.0, RapidAPI (17个订阅)
- **记忆系统**: Vertex AI Memory Bank, Cloudflare Memory Bank
- **数据库**: MongoDB (MCP集成)
- **配置管理**: Doppler + 环境变量
- **部署**: Docker + GitHub Actions + GitHub Pages

## 开发指南

### 添加新的AI服务
1. 在 `config/doppler_config.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')"

# 运行v2.1.0综合测试
python tests/test_v2_1_comprehensive.py

# 测试Google ADK集成
python tests/test_google_adk.py

# 启动ADK Web界面
adk web --no-reload
```

## v2.1.0 版本亮点

### 🎭 起承转合辩论架构
- **起**: 八仙按先天八卦顺序发言，建立多维度论证基础
- **承**: 雁阵式承接，正方1234，反方1234的深化论点
- **转**: 36次handoff的自由辩论，优先级算法决定发言顺序
- **合**: 交替总结，反1→正1→反2→正2→反3→正3→反4→正4

### 🧠 增强优先级算法 v2.1.0
- **反驳紧急性权重**: 30%
- **论点强度权重**: 25%
- **时间压力权重**: 20%
- **观众反应权重**: 15%
- **策略需要权重**: 10%

### 📊 性能指标
- **测试通过率**: 100% (7/7项测试全部通过)
- **并发性能**: 63,405 ops/second
- **平均响应时间**: 15.77ms
- **错误率**: 0%

### 🔧 技术改进
- Google ADK v1.10.0完整集成
- 多聊天协调系统优化
- MongoDB MCP服务器集成
- 健康监控和性能分析
- 异步处理和流式响应

## 路线图

### 短期目标 (v2.2.0)
- [ ] 完善Google ADK智能体对话功能
- [ ] 优化起承转合辩论流程
- [ ] 扩展OpenBB到更多金融产品
- [ ] 添加技术分析指标
- [ ] 实现实时数据流
- [ ] 完善Human干预机制

### 中期目标 (v2.3.0)
- [ ] 集成太公三式预测系统
- [ ] 实现梅花心易直觉算法
- [ ] 完善八仙人格量化
- [ ] 添加观众反馈系统

### 长期目标 (v3.0.0)
- [ ] 集成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-22
**版本**: v2.1.0
**维护者**: 稷下学宫团队