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

> 🧹 **致AI开发者**: 入此稷下学宫者，当先读 [`AI_DEVELOPER_GUIDELINES.md`](./AI_DEVELOPER_GUIDELINES.md) 了解项目规矩，明藏经阁章法。扫地僧叮嘱：代码如经书，需整齐摆放；文化特色不可丢，八仙智慧要传承。

提示：已支持 Cloudflare AutoRAG/Vectorize 作为记忆后端（RAG）。见 docs/guides/CLOUDFLARE_AUTORAG_INTEGRATION.md。

基于中国哲学传统的多AI智能体辩论平台，重构版本。

## ✨ 核心特性

- **🎭 稷下学宫八仙论道**: 基于中国传统八仙文化的多AI智能体辩论系统
- **🧠 Vertex AI记忆银行**: 集成Google Cloud Memory Bank，让AI智能体具备持久化记忆能力
- **🌍 天下体系分析**: 基于儒门天下观的资本生态"天命树"分析模型
- **🔒 安全配置管理**: 使用Doppler进行统一的密钥和配置管理
- **📊 智能数据源**: 基于17个RapidAPI订阅的永动机数据引擎
- **🎨 现代化界面**: 基于Streamlit的响应式Web界面

## 🏗️ 项目结构

```
liurenchaxin/
├── app/                    # 应用入口
│   ├── streamlit_app.py   # 主Streamlit应用
│   └── tabs/              # 功能模块
│       └── tianxia_tab.py # 天下体系分析
├── src/                   # 核心业务逻辑
│   └── jixia/            # 稷下学宫系统
│       └── engines/      # 核心引擎
│           └── perpetual_engine.py # 永动机引擎
├── config/               # 配置管理
│   └── doppler_config.py # Doppler配置接口
├── scripts/              # 工具脚本
│   └── test_openrouter_api.py # API连接测试
├── tests/                # 测试代码
├── .kiro/               # Kiro AI助手配置
│   └── steering/        # AI指导规则
└── requirements.txt     # 依赖清单
```

## 🚀 快速开始

### 1. 环境准备

#### 方法一：使用自动化设置脚本（推荐）

```bash
# 一键设置虚拟环境和依赖
./setup_venv.sh
```

#### 方法二：手动设置

```bash
# 创建虚拟环境
python3 -m venv venv

# 激活虚拟环境
# macOS/Linux
source venv/bin/activate
# Windows CMD
# venv\Scripts\activate.bat
# Windows PowerShell
# venv\Scripts\Activate.ps1

# 升级pip
pip install --upgrade pip

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

#### 虚拟环境管理

```bash
# 激活虚拟环境
source venv/bin/activate

# 退出虚拟环境
deactivate

# 查看已安装的包
pip list

# 更新依赖（开发时）
pip freeze > requirements.txt
```

### 2. 配置管理

项目使用Doppler进行安全的配置管理。需要配置以下环境变量：

```bash
# 必需配置（数据源）
RAPIDAPI_KEY=your_rapidapi_key

# 选择其一的AI服务密钥
# A) OpenRouter（旧）
OPENROUTER_API_KEY_1=your_openrouter_key
# B) Google ADK / Gemini（新）
GOOGLE_API_KEY=your_gemini_api_key
# 如果使用 Vertex AI Express Mode（可选）
GOOGLE_GENAI_USE_VERTEXAI=TRUE

# Vertex AI Memory Bank 配置（新功能）
GOOGLE_CLOUD_PROJECT_ID=your-project-id
GOOGLE_CLOUD_LOCATION=us-central1
VERTEX_MEMORY_BANK_ENABLED=TRUE

# 可选配置
POSTGRES_URL=your_postgres_url
MONGODB_URL=your_mongodb_url
ZILLIZ_URL=your_zilliz_url
ZILLIZ_TOKEN=your_zilliz_token
```

### 3. 启动应用

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

# 或指定端口
streamlit run app/streamlit_app.py --server.port 8501
```

### 4. 安装Swarm (可选)

如果要使用Swarm八仙论道功能：

```bash
# 安装OpenAI Swarm
python scripts/install_swarm.py

# 或手动安装
pip install git+https://github.com/openai/swarm.git
```

### 5. 测试连接

```bash
# 测试API连接
python scripts/test_openrouter_api.py

# 验证配置
python config/doppler_config.py

# 测试Swarm辩论 (可选)
python src/jixia/debates/swarm_debate.py

# 测试Vertex AI Memory Bank (新功能)
python tests/test_vertex_memory_bank.py
```

## 🎭 稷下学宫八仙论道

### 辩论顺序 (Debate Order)

辩论严格遵循中国哲学中的先天八卦顺序，分为两个阶段：

1.  **第一轮：核心对立辩论**
    此轮按照两两对立的原则进行，顺序如下：
    - **乾坤对立 (男女)**: 吕洞宾 vs 何仙姑
    - **兑艮对立 (老少)**: 张果老 vs 韩湘子
    - **离坎对立 (富贫)**: 汉钟离 vs 蓝采和
    - **震巽对立 (贵贱)**: 曹国舅 vs 铁拐李

2.  **第二轮：顺序发言**
    此轮按照先天八卦的完整顺序进行 (乾一, 兑二, 离三, 震四, 巽五, 坎六, 艮七, 坤八)，顺序如下：
    - **乾**: 吕洞宾
    - **兑**: 张果老
    - **离**: 汉钟离
    - **震**: 曹国舅
    - **巽**: 铁拐李
    - **坎**: 蓝采和
    - **艮**: 韩湘子
    - **坤**: 何仙姑

### 人物设定 (Character Settings)
基于中国传统八仙文化，每位仙人都有专属的卦象、代表和人设：

- **吕洞宾** (乾): 男性代表
- **何仙姑** (坤): 女性代表
- **张果老** (兑): 老者代表
- **韩湘子** (艮): 少年代表
- **汉钟离** (离): 富者代表
- **蓝采和** (坎): 贫者代表
- **曹国舅** (震): 贵者代表
- **铁拐李** (巽): 贱者代表

### Swarm模式 (AI智能体辩论)
基于OpenAI Swarm框架的四仙智能体辩论系统：

- **🗡️ 吕洞宾** (乾卦): 技术分析专家，看涨派，犀利直接
- **🌸 何仙姑** (坤卦): 风险控制专家，看跌派，温和坚定
- **📚 张果老** (兑卦): 历史数据分析师，看涨派，博古通今
- **⚡ 铁拐李** (巽卦): 逆向投资大师，看跌派，挑战共识

#### 支持两种运行模式：
- **OpenRouter模式**: 使用云端AI服务，模型选择丰富
- **Ollama模式**: 使用本地AI服务，完全离线运行

## 🌍 天下体系分析

基于儒门天下观的"天命树"结构模型：

### 四层架构
- **👑 天子**: 定义范式的平台型公司 (如NVIDIA, Tesla, Apple)
- **🏛️ 大夫**: 深度绑定天子的核心供应商 (如TSMC, CATL)
- **⚔️ 士**: 专业供应商和服务商 (如ASML, Luxshare)
- **🔗 嫁接**: 跨生态的策略性链接关系

### 三大生态
- **🤖 AI生态**: NVIDIA统治的AI计算生态
- **⚡ EV生态**: Tesla定义的电动汽车生态
- **📱 消费电子生态**: Apple建立的iOS生态

## 🔧 开发指南

### 代码规范
- 使用Python类型注解
- 遵循PEP 8编码规范
- 所有公共函数必须有文档字符串
- 使用dataclass定义数据结构

### 安全要求
- **零硬编码密钥**: 所有敏感信息通过Doppler或环境变量获取
- **环境隔离**: 开发、测试、生产环境严格分离
- **自动化扫描**: 所有提交必须通过安全检查

### 测试要求
- 所有核心功能必须有单元测试
- API调用必须有集成测试
- 配置管理必须有验证测试

## 📊 API使用统计

项目基于17个RapidAPI订阅构建永动机数据引擎：

- **智能故障转移**: 主API失败时自动切换备用API
- **负载均衡**: 智能分配API调用，避免单点过载
- **使用统计**: 实时监控API使用情况和成本优化

## 🤝 贡献指南

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

## 📄 许可证

本项目采用MIT许可证 - 详见 [LICENSE](LICENSE) 文件

## ⚠️ 免责声明

本系统仅供学习和研究使用。所有投资分析和建议仅供参考，不构成投资建议。投资有风险，决策需谨慎。

---

**炼妖壶 - 让AI辩论照亮投资智慧** 🏛️✨

## 🧪 ADK 开发调试（可选）

如果切换到 Google ADK：

```bash
# 安装 ADK（任选其一）
pip install google-adk
# 或安装最新开发版
pip install git+https://github.com/google/adk-python.git@main

# 启动 ADK 开发界面（在包含 agent 目录的父目录运行）
adk web
# 或命令行
adk run multi_tool_agent
# 或启动 API 服务
adk api_server
```

> 如果遇到 _make_subprocess_transport NotImplementedError，可使用 `adk web --no-reload`。