feat: 重构项目结构并添加新功能

- 新增Cloudflare AutoRAG/Vectorize集成文档 - 实现Vertex AI记忆银行功能 - 重构项目目录结构，清理无用文件 - 更新README以反映最新架构 - 添加Google ADK集成测试脚本 - 完善需求文档和设计规范
2025-08-16 10:37:11 +00:00
parent 26338d48cf
commit c4e8cfefc7
106 changed files with 12243 additions and 1839 deletions
--- a/docs/guides/GOOGLE_ADK_MIGRATION_GUIDE.md
+++ b/docs/guides/GOOGLE_ADK_MIGRATION_GUIDE.md
@@ -0,0 +1,211 @@
+# 🔄 Google ADK 迁移指南
+
+## 📋 迁移概述
+
+本指南将帮助您将项目从当前的 OpenRouter/OpenAI Swarm 架构迁移到 Google Agent Development Kit (ADK)。
+
+## 🎯 迁移目标
+
+- **从**: OpenRouter + OpenAI Swarm + 多厂商AI模型
+- **到**: Google ADK + Gemini 模型 + Express Mode API
+- **保持**: 稷下学宫八仙论道系统的核心逻辑和哲学框架
+
+## 📦 第一步：安装 Google ADK
+
+### 1.1 更新 Python 环境要求
+
+<mcreference link="https://google.github.io/adk-docs/get-started/quickstart/" index="1">1</mcreference>
+
+```bash
+# 确保 Python 3.9+ 版本
+python --version
+
+# 创建新的虚拟环境（推荐）
+python -m venv .venv
+
+# 激活虚拟环境
+# macOS/Linux:
+source .venv/bin/activate
+# Windows CMD:
+# .venv\Scripts\activate.bat
+# Windows PowerShell:
+# .venv\Scripts\Activate.ps1
+```
+
+### 1.2 安装 Google ADK
+
+<mcreference link="https://pypi.org/project/google-adk/" index="2">2</mcreference>
+
+```bash
+# 安装稳定版本
+pip install google-adk
+
+# 或安装最新开发版本
+pip install git+https://github.com/google/adk-python.git@main
+```
+
+## 🔑 第二步：配置 API 密钥
+
+### 2.1 获取 Gemini API 密钥
+
+<mcreference link="https://google.github.io/adk-docs/get-started/quickstart/" index="1">1</mcreference>
+
+您有三种选择：
+
+**选项A: Google AI Studio (推荐开发环境)**
+- 前往 [Google AI Studio](https://aistudio.google.com/) 获取免费 API 密钥
+- 环境变量：`GOOGLE_API_KEY`
+
+**选项B: Google Cloud Vertex AI Express Mode**
+- 在 Google Cloud 项目中启用 Express Mode
+- 环境变量：`GOOGLE_API_KEY` + `GOOGLE_GENAI_USE_VERTEXAI=TRUE`
+
+**选项C: Google Cloud Vertex AI (完整版)**
+- 需要 Google Cloud 认证，使用 IAM 而非 API 密钥
+
+### 2.2 更新 Doppler 配置
+
+在您的 Doppler 项目中添加新的环境变量：
+
+```bash
+# 添加 Gemini API 密钥
+doppler secrets set GOOGLE_API_KEY=YOUR_GEMINI_API_KEY
+
+# 如果使用 Express Mode
+doppler secrets set GOOGLE_GENAI_USE_VERTEXAI=TRUE
+
+# 保留现有的 RapidAPI 配置（数据源仍然需要）
+# RAPIDAPI_KEY=your_rapidapi_key
+```
+
+## 🏗️ 第三步：重构核心组件
+
+### 3.1 更新配置管理
+
+需要更新 `config/doppler_config.py`：
+
+```python
+def get_google_api_key() -> str:
+    """获取 Google API 密钥"""
+    return get_secret('GOOGLE_API_KEY')
+
+def get_google_genai_config() -> Dict[str, str]:
+    """获取 Google GenAI 配置"""
+    return {
+        'api_key': get_google_api_key(),
+        'use_vertex_ai': get_secret('GOOGLE_GENAI_USE_VERTEXAI', 'FALSE'),
+        'project_id': get_secret('GOOGLE_CLOUD_PROJECT_ID', '')
+    }
+```
+
+### 3.2 重构稷下学宫智能体系统
+
+将基于 OpenAI Swarm 的八仙论道系统迁移到 ADK：
+
+**原架构**: `src/jixia/debates/swarm_debate.py` (OpenAI Swarm)
+**新架构**: `src/jixia/debates/adk_debate.py` (Google ADK)
+
+### 3.3 ADK 智能体定义
+
+每个"仙"将成为独立的 ADK Agent：
+
+```python
+# 示例：铁拐李智能体
+from google_adk import Agent, FunctionTool
+
+tie_guai_li_agent = Agent(
+    name="铁拐李",
+    model="gemini-2.0-flash-exp",
+    description="逆向思维专家，善于从困境中寻找突破",
+    system_message="你是铁拐李，八仙中的逆向思维专家...",
+    tools=[
+        FunctionTool(name="逆向分析", function=reverse_analysis),
+        FunctionTool(name="困境突破", function=breakthrough_analysis)
+    ]
+)
+```
+
+## 🔄 第四步：分阶段迁移策略
+
+### 阶段1：基础设施迁移 (第1-2天)
+- [ ] 安装 Google ADK
+- [ ] 配置 API 密钥
+- [ ] 创建简单的测试智能体
+- [ ] 验证基本功能
+
+### 阶段2：核心逻辑迁移 (第3-5天)
+- [ ] 重构八仙智能体定义
+- [ ] 迁移论道逻辑
+- [ ] 保持数据源 (RapidAPI) 集成
+- [ ] 测试单个智能体功能
+
+### 阶段3：系统集成 (第6-7天)
+- [ ] 多智能体协作
+- [ ] Streamlit 界面适配
+- [ ] 完整功能测试
+- [ ] 性能优化
+
+### 阶段4：部署和监控 (第8天)
+- [ ] 部署配置
+- [ ] 监控设置
+- [ ] 文档更新
+
+## 📊 功能对照表
+
+| 当前 (OpenRouter/Swarm) | 迁移后 (Google ADK) | 状态 |
+|-------------------------|-------------------|------|
+| OpenAI Swarm 多智能体 | ADK Multi-Agent | ✅ 等价替换 |
+| OpenRouter 模型池 | Gemini 模型系列 | ✅ 统一模型 |
+| 自定义 Tool 系统 | ADK FunctionTool | ✅ 等价替换 |
+| 论道逻辑 | ADK Agent协作 | ✅ 保持逻辑 |
+| RapidAPI 数据源 | 保持不变 | ✅ 无需改动 |
+| Streamlit 界面 | ADK Dev UI + Streamlit | ✅ 双界面 |
+
+## 🎛️ 开发工具对比
+
+### 当前工具
+- OpenRouter API 测试
+- 自定义调试脚本
+- Streamlit 界面
+
+### ADK 工具
+<mcreference link="https://google.github.io/adk-docs/get-started/quickstart/" index="1">1</mcreference>
+
+```bash
+# ADK 开发界面 (推荐)
+adk web
+
+# 命令行运行
+adk run multi_tool_agent
+
+# API 服务器模式
+adk api_server
+```
+
+## 🚨 注意事项
+
+### 保留的组件
+- **RapidAPI 数据源**: 继续使用，无需更改
+- **MongoDB 数据库**: 继续使用
+- **Doppler 配置管理**: 继续使用，仅添加新密钥
+- **稷下学宫哲学框架**: 完全保持
+
+### 移除的组件
+- OpenAI Swarm 依赖
+- OpenRouter API 调用
+- 多厂商 API 密钥管理
+
+### 新增优势
+- **统一的模型生态**: 专注 Gemini 系列
+- **更强的 Google 服务集成**: Search、Cloud 等
+- **官方支持的框架**: 长期维护保证
+- **更好的开发工具**: ADK Dev UI
+
+## 📝 下一步行动
+
+1. **立即开始**: 运行第一步的环境配置
+2. **获取 API 密钥**: 访问 Google AI Studio
+3. **阅读 ADK 文档**: [官方文档](https://google.github.io/adk-docs/)
+4. **测试简单智能体**: 验证基本功能
+
+准备好开始迁移了吗？我可以帮您逐步执行每个阶段！
--- a/docs/guides/MIGRATION_PLAN.md
+++ b/docs/guides/MIGRATION_PLAN.md
@@ -0,0 +1,116 @@
+# 🚀 炼妖壶项目迁移计划
+
+## 🎯 目标
+
+从混乱的当前项目状态迁移到干净、安全、可维护的新项目结构。
+
+## 📍 迁移路径
+
+```
+当前位置: /home/ben/cauldron (混乱状态)
+目标位置: /home/ben/liurenchaxin (全新开始)
+```
+
+## 📋 迁移步骤
+
+### 阶段1: 文档准备 ✅
+- [x] 创建需求规范
+- [x] 制定迁移计划
+- [ ] 完善设计文档
+- [ ] 创建任务清单
+
+### 阶段2: 环境准备
+- [ ] 创建新项目目录
+- [ ] 设置虚拟环境
+- [ ] 配置Doppler (干净的配置)
+- [ ] 建立Git仓库
+
+### 阶段3: 核心功能迁移
+- [ ] 迁移稷下学宫AI辩论系统
+- [ ] 迁移Streamlit主界面
+- [ ] 迁移数据库连接模块
+- [ ] 迁移API集成代码
+
+### 阶段4: 安全加固
+- [ ] 实施密钥管理最佳实践
+- [ ] 配置GitGuardian检查
+- [ ] 设置pre-commit hooks
+- [ ] 建立安全扫描流程
+
+### 阶段5: 测试验证
+- [ ] 功能测试
+- [ ] 安全测试
+- [ ] 性能测试
+- [ ] 部署测试
+
+## 🔒 安全原则
+
+1. **零密钥原则** - 代码中绝不包含任何密钥
+2. **环境变量优先** - 所有配置通过环境变量
+3. **Doppler集中管理** - 统一的密钥管理
+4. **自动化检查** - 提交前自动安全扫描
+
+## 📁 新项目结构
+
+```
+liurenchaxin/
+├── app/                    # 应用入口
+│   ├── streamlit_app.py   # 主界面
+│   └── components/        # UI组件
+├── src/                   # 核心代码
+│   ├── jixia/            # 稷下学宫系统
+│   ├── database/         # 数据库模块
+│   └── api/              # API集成
+├── config/               # 配置管理
+│   └── doppler_config.py # Doppler配置
+├── tests/                # 测试代码
+├── docs/                 # 文档
+├── scripts/              # 工具脚本
+└── .kiro/               # Kiro配置
+    └── specs/           # 规范文档
+```
+
+## 🚫 不迁移的内容
+
+- 历史实验代码
+- 重复的功能实现
+- 过时的依赖
+- 混乱的配置文件
+- 包含密钥的文件
+- 无用的调试脚本
+
+## ✅ 迁移检查清单
+
+### 功能验证
+- [ ] AI辩论系统正常工作
+- [ ] Streamlit界面完整显示
+- [ ] 数据库连接成功
+- [ ] API调用正常
+- [ ] 配置加载正确
+
+### 安全验证
+- [ ] GitGuardian扫描通过
+- [ ] 无硬编码密钥
+- [ ] Doppler配置正确
+- [ ] 环境变量隔离
+- [ ] 访问权限合理
+
+### 质量验证
+- [ ] 代码风格一致
+- [ ] 文档完整
+- [ ] 测试覆盖充分
+- [ ] 性能满足要求
+- [ ] 部署流程顺畅
+
+## 🎉 成功标准
+
+迁移成功的标志：
+1. 新项目通过所有安全扫描
+2. 核心功能100%可用
+3. 启动时间 < 30秒
+4. 代码质量 A级
+5. 文档完整度 > 90%
+
+---
+
+**准备好开始迁移了吗？让我们带着这些文档，前往新的开始！** 🚀
--- a/docs/guides/README_jixia_load_balancing.md
+++ b/docs/guides/README_jixia_load_balancing.md
@@ -0,0 +1,275 @@
+# 稷下学宫八仙论道 - RapidAPI负载均衡系统
+
+## 🏛️ 系统概述
+
+本系统实现了稷下学宫八仙论道的智能API负载均衡策略，通过将不同的RapidAPI数据源分配给不同的"仙人"角色，实现了高效的负载分担和数据获取。
+
+### 🎯 核心目标
+- **负载分担**: 将API调用压力分散到多个数据源
+- **高可用性**: 通过故障转移确保服务连续性
+- **数据统一**: 标准化不同API的数据格式
+- **智能缓存**: 减少重复调用，提升响应速度
+- **实时监控**: 跟踪API健康状态和负载分布
+
+## 👥 八仙角色与API分配
+
+| 仙人 | 角色 | 专长 | 主要API | 备用API |
+|------|------|------|---------|----------|
+| 🗡️ 吕洞宾 | 主力剑仙 | 综合分析与决策 | Alpha Vantage | Webull, Yahoo Finance |
+| 🌸 何仙姑 | 风控专家 | 风险管理与合规 | Yahoo Finance 15 | Webull, Alpha Vantage |
+| 🧙 张果老 | 技术分析师 | 技术指标与图表分析 | Webull | Alpha Vantage, Yahoo Finance |
+| 🎵 韩湘子 | 基本面研究员 | 财务分析与估值 | Alpha Vantage | Seeking Alpha |
+| ⚡ 汉钟离 | 量化专家 | 数据挖掘与算法交易 | Yahoo Finance 15 | Alpha Vantage |
+| 🎭 蓝采和 | 情绪分析师 | 市场情绪与舆情监控 | Webull | Seeking Alpha |
+| 👑 曹国舅 | 宏观分析师 | 宏观经济与政策分析 | Seeking Alpha | Yahoo Finance |
+| 🦯 铁拐李 | 逆向投资专家 | 价值发现与逆向思维 | Alpha Vantage | Webull, Yahoo Finance |
+
+## 📊 可用API资源
+
+### 🥇 高性能API (第一优先级)
+- **Alpha Vantage**: 专业金融数据，实时报价，财务数据
+- **Webull**: 强大搜索功能，活跃数据，技术分析
+
+### 🥈 标准API (第二优先级)
+- **Yahoo Finance 15**: 稳定市场数据，新闻资讯
+- **Seeking Alpha**: 分析报告，专业观点，新闻资讯
+
+## 🏗️ 系统架构
+
+```
+稷下学宫负载均衡系统
+├── 🎭 八仙角色层
+│   ├── 角色定义与专长分工
+│   ├── API偏好配置
+│   └── 数据类型映射
+├── 🔄 负载均衡层
+│   ├── 智能路由算法
+│   ├── 健康检查机制
+│   ├── 速率限制管理
+│   └── 故障转移策略
+├── 🌐 API接入层
+│   ├── Alpha Vantage 接口
+│   ├── Yahoo Finance 15 接口
+│   ├── Webull 接口
+│   └── Seeking Alpha 接口
+├── 🔧 数据处理层
+│   ├── 数据标准化处理
+│   ├── 格式统一转换
+│   └── 错误处理机制
+├── 💾 缓存层
+│   ├── 内存缓存管理
+│   ├── TTL策略控制
+│   └── 缓存命中优化
+└── 📊 监控层
+    ├── API调用统计
+    ├── 负载分布监控
+    ├── 性能指标跟踪
+    └── 健康状态报告
+```
+
+## 🚀 核心功能
+
+### 1. 智能负载分担
+- **角色分工**: 每个仙人使用不同的主要API
+- **权重分配**: 基于API性能和可靠性的智能分配
+- **动态调整**: 根据实时负载情况自动调整
+
+### 2. 自动故障转移
+- **健康检查**: 实时监控API可用性
+- **故障检测**: 连续失败次数阈值检测
+- **备用切换**: 自动切换到备用API
+- **恢复机制**: 主API恢复后自动切回
+
+### 3. 数据标准化
+```python
+# 统一的数据格式
+{
+    'symbol': 'AAPL',
+    'price': 202.38,
+    'change': -5.12,
+    'change_percent': '-2.50%',
+    'volume': 45678900,
+    'high': 207.50,
+    'low': 201.85,
+    'source': 'alpha_vantage',
+    'timestamp': '2025-08-02'
+}
+```
+
+### 4. 智能缓存策略
+- **分层缓存**: 不同数据类型使用不同TTL
+- **缓存预热**: 预先加载热点数据
+- **缓存穿透保护**: 避免缓存雪崩
+
+### 5. 实时监控
+- **API调用统计**: 实时跟踪每个API的调用次数
+- **负载分布**: 可视化负载分布情况
+- **性能指标**: 响应时间、成功率等关键指标
+- **告警机制**: 异常情况自动告警
+
+## 📁 文件结构
+
+```
+/home/ben/liurenchaxin/
+├── src/jixia/
+│   ├── engines/
+│   │   └── jixia_load_balancer.py      # 核心负载均衡引擎
+│   └── config/
+│       └── immortal_api_config.json    # 八仙角色与API配置
+├── demo_jixia_load_balancing.py        # 演示脚本
+├── jixia_load_balancing_strategy.md    # 策略文档
+└── README_jixia_load_balancing.md      # 本说明文档
+```
+
+## 🎮 使用方法
+
+### 1. 环境准备
+```bash
+# 确保已配置RapidAPI密钥
+export RAPIDAPI_KEY="your_rapidapi_key"
+
+# 或使用Doppler管理环境变量
+doppler run python demo_jixia_load_balancing.py
+```
+
+### 2. 基本使用
+```python
+from src.jixia.engines.jixia_load_balancer import JixiaLoadBalancer
+
+# 创建负载均衡器
+load_balancer = JixiaLoadBalancer(rapidapi_key)
+
+# 单个仙人获取数据
+result = load_balancer.get_data_for_immortal('吕洞宾', 'stock_quote', 'AAPL')
+
+# 八仙论道（完整演示）
+results = load_balancer.conduct_immortal_debate('TSLA')
+
+# 查看负载分布
+distribution = load_balancer.get_load_distribution()
+```
+
+### 3. 运行演示
+```bash
+# 完整演示
+cd /home/ben/liurenchaxin
+doppler run python demo_jixia_load_balancing.py
+
+# 查看演示结果
+ls demo_results_*.json
+```
+
+## 📊 演示结果
+
+### 负载分布统计
+基于实际运行的演示结果：
+
+| API | 调用次数 | 负载占比 | 健康状态 | 平均响应时间 |
+|-----|----------|----------|----------|-------------|
+| Alpha Vantage | 8次 | 33.3% | 🟢 健康 | ~1.3s |
+| Yahoo Finance 15 | 7次 | 29.2% | 🟢 健康 | ~1.9s |
+| Webull | 9次 | 37.5% | 🟢 健康 | ~2.0s |
+| Seeking Alpha | 0次 | 0.0% | 🟢 健康 | N/A |
+
+### 性能指标
+- **总API调用**: 24次
+- **成功率**: 100%
+- **平均响应时间**: 1.7秒
+- **缓存命中率**: 约30%
+- **故障转移**: 自动且无缝
+
+## 🔧 配置说明
+
+### API配置 (`immortal_api_config.json`)
+```json
+{
+  "immortals": {
+    "吕洞宾": {
+      "title": "主力剑仙",
+      "specialty": "综合分析与决策",
+      "preferred_apis": {
+        "stock_quote": "alpha_vantage",
+        "company_overview": "alpha_vantage"
+      },
+      "api_weight": 0.15
+    }
+  },
+  "api_configurations": {
+    "alpha_vantage": {
+      "reliability_score": 0.95,
+      "response_time_avg": 0.8,
+      "cost_per_call": 0.001
+    }
+  }
+}
+```
+
+### 负载均衡策略
+- **轮询分配**: 确保负载均匀分布
+- **健康感知**: 基于API健康状态的智能分配
+- **性能优化**: 基于响应时间的动态分配
+- **成本控制**: 优先使用低成本API（可选）
+
+## 🎯 优势特点
+
+### 1. 高可用性
+- ✅ 多API冗余，单点故障不影响整体服务
+- ✅ 自动故障检测和恢复机制
+- ✅ 实时健康监控和告警
+
+### 2. 高性能
+- ✅ 智能缓存减少重复调用
+- ✅ 并发处理提升响应速度
+- ✅ 负载均衡避免单API过载
+
+### 3. 高扩展性
+- ✅ 模块化设计，易于添加新API
+- ✅ 配置驱动，无需修改代码
+- ✅ 插件化架构支持自定义扩展
+
+### 4. 成本优化
+- ✅ 智能API选择降低调用成本
+- ✅ 缓存策略减少不必要的API调用
+- ✅ 负载分散避免超出免费额度
+
+## 🔮 未来规划
+
+### 短期目标
+- [ ] 添加更多RapidAPI数据源
+- [ ] 实现WebSocket实时数据推送
+- [ ] 优化缓存策略和命中率
+- [ ] 添加详细的性能分析报告
+
+### 中期目标
+- [ ] 机器学习驱动的智能路由
+- [ ] 预测性故障检测
+- [ ] 自适应负载均衡算法
+- [ ] 成本优化自动化
+
+### 长期目标
+- [ ] 分布式部署支持
+- [ ] 多租户架构
+- [ ] 实时数据流处理
+- [ ] AI驱动的投资决策支持
+
+## 🤝 贡献指南
+
+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 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。
+
+## 📞 联系方式
+
+- **项目维护者**: 稷下学宫开发团队
+- **技术支持**: 通过 GitHub Issues 提交问题
+- **文档更新**: 欢迎提交文档改进建议
+
+---
+
+*🏛️ 稷下学宫 - 让智慧的光芒照亮投资的道路*