ben/liurenchaxin
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

🏗️ 项目重构：模块化清理完成

Browse Source
This commit is contained in:
llama-research
2025-09-01 12:29:27 +00:00
parent ef7657101a
commit f9856c31e5
349 changed files with 41438 additions and 254 deletions
Download Patch File Download Diff File Expand all files Collapse all files

222
modules/documentation-suite/docs/AI_AGENT_TASKS/CLAUDE_CODE_IMPLEMENTATION.md Normal file
View File

@@ -0,0 +1,222 @@
# 💻 Claude AI - OpenBB核心代码实现工作说明书
## 🎯 任务概述
作为核心开发工程师，您需要基于Qwen的架构设计，实现OpenBB与稷下学宫系统的深度集成代码。
## 📋 核心职责
### 1. 核心引擎实现
**任务目标：** 增强现有OpenBB引擎，实现八仙智能数据获取
**关键文件实现：**
```
src/jixia/engines/
├── enhanced_openbb_engine.py # 增强版OpenBB引擎
├── immortal_data_router.py # 八仙数据路由器
├── intelligent_fallback.py # 智能降级机制
└── data_quality_monitor.py # 数据质量监控
```
**核心代码需求：**
```python
class EnhancedOpenBBEngine:
"""增强版OpenBB引擎 - 八仙专属"""
async def get_immortal_insight(self, immortal_name: str,
symbol: str, analysis_type: str):
"""为特定八仙获取专属金融洞察"""
pass
async def orchestrate_debate_data(self, topic: str,
participants: List[str]):
"""为稷下学宫辩论准备数据"""
pass
```
### 2. 智能体数据适配器
**任务目标：** 实现AI智能体与OpenBB数据的无缝对接
**具体实现：**
- 八仙角色数据源适配
- 实时数据流处理
- 智能缓存机制
- 异常处理和重试逻辑
**核心文件：**
- `src/jixia/adapters/openbb_agent_adapter.py`
- `src/jixia/adapters/immortal_data_processor.py`
### 3. Streamlit界面增强
**任务目标：** 优化现有OpenBB标签页，增加八仙论道功能
**需要修改的文件：**
- `app/tabs/openbb_tab.py` - 增强现有界面
- `app/tabs/immortal_debate_tab.py` - 新增八仙辩论界面
**UI功能需求：**
```python
def render_immortal_debate_interface():
"""渲染八仙辩论界面"""
# 1. 股票/主题选择器
# 2. 八仙角色选择器
# 3. 实时数据展示
# 4. 辩论结果可视化
pass
```
### 4. 数据质量保障
**任务目标：** 确保数据准确性和系统稳定性
**实现重点：**
- 数据验证机制
- 异常数据处理
- 性能监控埋点
- 日志记录系统
## 🔧 实现规范
### 代码风格要求：
```python
# 1. 遵循项目现有代码风格
# 2. 完整的类型注解
# 3. 详细的docstring文档
# 4. 异常处理机制
from typing import Dict, List, Optional, Union
from dataclasses import dataclass
from datetime import datetime
@dataclass
class ImmortalInsight:
"""八仙洞察数据模型"""
immortal_name: str
symbol: str
insight_type: str
data: Dict[str, any]
confidence: float
timestamp: datetime
```
### 必须保持的特性：
1. **向后兼容** - 不破坏现有功能
2. **优雅降级** - OpenBB不可用时的备选方案
3. **文化内核** - 保持八仙论道的文化特色
4. **模块化设计** - 便于单元测试和维护
### 性能要求：
- 数据获取响应时间 < 3秒
- 并发处理能力 > 10个请求/秒
- 内存使用 < 500MB
- CPU使用率 < 30%
## 🎭 八仙特色功能实现
### 八仙数据偏好实现：
```python
IMMORTAL_PREFERENCES = {
'吕洞宾': {
'data_types': ['technical_indicators', 'chart_patterns'],
'analysis_style': 'systematic',
'risk_appetite': 'moderate'
},
'何仙姑': {
'data_types': ['risk_metrics', 'volatility'],
'analysis_style': 'conservative',
'risk_appetite': 'low'
},
# ... 其他六仙
}
```
### 智能辩论数据准备：
```python
async def prepare_debate_data(self, topic_symbol: str) -> DebateDataSet:
"""为八仙辩论准备差异化数据视角"""
# 1. 获取基础数据
# 2. 按八仙偏好处理数据
# 3. 生成对比性观点
# 4. 返回结构化辩论数据
pass
```
## 🧪 测试要求
### 必须实现的测试：
```python
# tests/test_enhanced_openbb_engine.py
class TestEnhancedOpenBBEngine:
def test_immortal_data_routing(self):
"""测试八仙数据路由功能"""
pass
def test_fallback_mechanism(self):
"""测试降级机制"""
pass
def test_concurrent_requests(self):
"""测试并发请求处理"""
pass
```
### 集成测试：
- 与现有八仙辩论系统的集成
- Streamlit界面集成测试
- 实际数据获取测试
## 🔄 协作接口
### 接收Qwen的架构输入：
- [ ] 架构设计文档
- [ ] 接口规范定义
- [ ] 数据模型标准
### 为Gemini提供测试目标：
- [ ] 完整的代码实现
- [ ] 单元测试用例
- [ ] 集成测试指南
### 为RovoDev提供文档素材：
- [ ] 代码注释和文档
- [ ] API使用示例
- [ ] 故障排除指南
## 📅 开发里程碑
### 里程碑1（3天）：
- [ ] 核心引擎实现
- [ ] 基础单元测试
- [ ] 简单集成验证
### 里程碑2（2天）：
- [ ] Streamlit界面增强
- [ ] 八仙特色功能
- [ ] 性能优化
### 里程碑3（1天）：
- [ ] 完整测试覆盖
- [ ] 代码审查和优化
- [ ] 文档完善
## 💡 创新挑战
请在实现中展现创新：
1. **智能数据融合算法**
2. **八仙个性化数据处理**
3. **实时性能监控机制**
4. **用户体验优化**
## ⚠️ 特别注意
### 文化敏感性：
- 确保八仙角色的准确性和尊重性
- 保持传统文化与现代技术的平衡
- 避免过度商业化的表达
### 技术债务控制：
- 避免硬编码
- 保持配置的灵活性
- 确保代码的可维护性
---
**注意：** 代码是文化的载体，请让每一行代码都体现稷下学宫的智慧！

274
modules/documentation-suite/docs/AI_AGENT_TASKS/GEMINI_TEST_VALIDATION.md Normal file
View File

@@ -0,0 +1,274 @@
# 🧪 Gemini AI - OpenBB集成测试验证工作说明书
## 🎯 任务概述
作为测试工程师，您需要为OpenBB与稷下学宫系统的集成功能设计并执行全面的测试验证方案。
## 📋 核心职责
### 1. 测试策略制定
**任务目标：** 制定全面的测试策略和验证标准
**测试金字塔设计：**
```
[E2E Tests] # 端到端测试
/ \
[Integration Tests] # 集成测试
/ \
[Unit Tests] [API Tests] # 单元测试 + API测试
```
**测试覆盖范围：**
- 功能测试 (80%覆盖率)
- 性能测试 (响应时间、并发)
- 稳定性测试 (长时间运行)
- 兼容性测试 (多数据源)
### 2. 八仙智能体测试
**任务目标：** 验证八仙角色的数据获取和分析能力
**测试文件结构：**
```
tests/immortal_tests/
├── test_immortal_data_routing.py # 八仙数据路由测试
├── test_immortal_preferences.py # 八仙偏好测试
├── test_debate_data_quality.py # 辩论数据质量测试
└── test_cultural_accuracy.py # 文化准确性测试
```
**关键测试用例：**
```python
class TestImmortalDataRouting:
"""八仙数据路由测试"""
def test_lv_dongbin_technical_analysis(self):
"""测试吕洞宾的技术分析数据获取"""
pass
def test_he_xiangu_risk_metrics(self):
"""测试何仙姑的风险指标数据"""
pass
def test_immortal_data_consistency(self):
"""测试八仙数据的一致性"""
pass
```
### 3. OpenBB集成测试
**任务目标：** 验证OpenBB数据源的集成质量
**测试重点：**
- OpenBB API调用稳定性
- 数据格式标准化
- 错误处理机制
- 降级策略验证
**核心测试文件：**
```python
# tests/openbb_integration/
class TestOpenBBIntegration:
"""OpenBB集成测试套件"""
@pytest.mark.asyncio
async def test_stock_data_retrieval(self):
"""测试股票数据获取"""
symbols = ['AAPL', 'TSLA', 'MSFT']
for symbol in symbols:
data = await engine.get_stock_data(symbol)
assert data is not None
assert 'close' in data.columns
def test_fallback_mechanism(self):
"""测试OpenBB不可用时的降级机制"""
# 模拟OpenBB不可用
with mock.patch('openbb.obb', side_effect=ImportError):
result = engine.get_data_with_fallback('AAPL')
assert result.source == 'demo_data'
```
### 4. 性能和稳定性测试
**任务目标：** 确保系统在各种条件下的性能表现
**性能基准：**
- 数据获取延迟 < 3秒
- 并发处理 > 10 req/s
- 内存使用 < 500MB
- 99.9% 可用性
**负载测试方案：**
```python
# tests/performance/
class TestPerformance:
"""性能测试套件"""
def test_concurrent_data_requests(self):
"""并发数据请求测试"""
import concurrent.futures
with concurrent.futures.ThreadPoolExecutor(max_workers=10) as executor:
futures = [executor.submit(self.get_test_data) for _ in range(100)]
results = [f.result() for f in futures]
assert all(r.success for r in results)
assert max(r.response_time for r in results) < 5.0
```
## 🎭 文化特色测试
### 八仙文化准确性验证：
```python
class TestCulturalAccuracy:
"""文化准确性测试"""
def test_immortal_characteristics(self):
"""验证八仙特征的准确性"""
immortals = get_immortal_configs()
# 验证吕洞宾的技术分析特色
assert immortals['吕洞宾'].specialty == 'technical_analysis'
assert immortals['吕洞宾'].element == '乾'
# 验证何仙姑的风险控制特色
assert immortals['何仙姑'].specialty == 'risk_metrics'
assert immortals['何仙姑'].element == '坤'
def test_debate_cultural_context(self):
"""验证辩论的文化背景准确性"""
debate = create_test_debate('AAPL')
# 确保辩论遵循稷下学宫的传统
assert 'jixia' in debate.context
assert len(debate.participants) == 8 # 八仙
```
## 🔧 测试工具和框架
### 推荐工具栈：
```python
# 测试依赖
pytest>=7.4.0 # 主测试框架
pytest-asyncio>=0.21.0 # 异步测试支持
pytest-mock>=3.11.0 # Mock功能
pytest-cov>=4.1.0 # 覆盖率统计
pytest-benchmark>=4.0.0 # 性能基准测试
# 性能测试
locust>=2.15.0 # 负载测试
memory-profiler>=0.60.0 # 内存分析
# 数据验证
pydantic>=2.0.0 # 数据模型验证
jsonschema>=4.19.0 # JSON架构验证
```
### 测试配置文件：
```yaml
# pytest.ini
[tool:pytest]
testpaths = tests
python_files = test_*.py
python_classes = Test*
python_functions = test_*
addopts =
--cov=src
--cov-report=html
--cov-report=term-missing
--asyncio-mode=auto
```
## 📊 测试报告和指标
### 测试报告模板：
```
tests/reports/
├── unit_test_report.html # 单元测试报告
├── integration_test_report.html # 集成测试报告
├── performance_benchmark.json # 性能基准数据
├── coverage_report/ # 代码覆盖率报告
└── cultural_validation_report.md # 文化验证报告
```
### 关键指标监控：
```python
# 自动化指标收集
class TestMetrics:
"""测试指标收集器"""
def collect_response_times(self):
"""收集响应时间数据"""
pass
def measure_memory_usage(self):
"""监控内存使用情况"""
pass
def validate_data_quality(self):
"""验证数据质量指标"""
pass
```
## 🔄 协作流程
### 与Claude的协作：
1. **接收代码实现** → 制定对应测试用例
2. **执行测试验证** → 反馈BUG和优化建议
3. **性能测试** → 提供优化方向
### 与Qwen的协作：
1. **验证架构设计** → 确认技术指标可达成
2. **测试架构决策** → 验证设计的合理性
### 与RovoDev的协作：
1. **提供测试数据** → 支持文档编写
2. **验证文档准确性** → 确保文档与实际一致
## 📅 测试里程碑
### 阶段一（2天）：测试框架搭建
- [ ] 测试环境配置
- [ ] 基础测试框架
- [ ] Mock数据准备
### 阶段二（3天）：功能测试执行
- [ ] 单元测试执行
- [ ] 集成测试验证
- [ ] 八仙特色功能测试
### 阶段三（2天）：性能和稳定性测试
- [ ] 负载测试执行
- [ ] 性能基准建立
- [ ] 稳定性验证
### 阶段四（1天）：测试报告生成
- [ ] 测试结果汇总
- [ ] 问题清单整理
- [ ] 优化建议制定
## 🎯 验收标准
### 功能验收：
- [ ] 所有单元测试通过率 > 95%
- [ ] 集成测试通过率 > 90%
- [ ] 八仙特色功能100%验证通过
### 性能验收：
- [ ] 响应时间 < 3秒
- [ ] 并发处理 > 10 req/s
- [ ] 内存使用稳定
- [ ] 99%可用性达成
### 文化验收：
- [ ] 八仙角色特征准确
- [ ] 辩论逻辑符合传统
- [ ] 文化表达尊重得体
## 💡 创新测试方法
### 智能化测试：
1. **AI驱动的测试用例生成**
2. **自适应性能基准调整**
3. **文化语境的自动化验证**
4. **用户行为模拟测试**
---
**注意：** 测试不仅是质量保障，更是文化传承的守护者！每一个测试用例都要体现对传统文化的尊重！

122
modules/documentation-suite/docs/AI_AGENT_TASKS/QWEN_ARCHITECTURE_DESIGN.md Normal file
View File

@@ -0,0 +1,122 @@
# 📐 Qwen AI - OpenBB架构设计师工作说明书
## 🎯 任务概述
作为架构设计师，您需要为"炼妖壶-稷下学宫AI辩论系统"设计OpenBB集成的技术架构方案。
## 📋 核心职责
### 1. 系统架构设计
**任务目标：** 设计OpenBB与稷下学宫系统的集成架构
**具体工作：**
- 分析现有系统架构（`src/jixia/engines/`）
- 设计OpenBB数据流架构
- 制定模块间解耦策略
- 设计故障转移和降级机制
**交付物：**
```
docs/architecture/
├── openbb_integration_architecture.md
├── data_flow_diagram.mermaid
├── component_interaction_diagram.mermaid
└── deployment_architecture.md
```
### 2. 数据抽象层设计
**任务目标：** 设计统一的金融数据抽象接口
**具体工作：**
- 定义标准化数据模型
- 设计Provider适配器模式
- 制定数据缓存策略
- 设计数据质量监控机制
**关键文件：**
- `src/jixia/engines/data_abstraction.py`
- `src/jixia/models/financial_data_models.py`
### 3. 性能优化架构
**任务目标：** 确保系统在高并发下的稳定性
**具体工作：**
- 设计异步数据获取架构
- 制定缓存策略（Redis/Memory）
- 设计负载均衡机制
- 制定监控和告警策略
## 🔧 技术约束
### 必须遵循的原则：
1. **渐进式集成** - 不破坏现有功能
2. **可选依赖** - OpenBB失效时优雅降级
3. **文化融合** - 保持八仙论道的文化特色
4. **模块解耦** - 便于后续扩展其他数据源
### 技术栈限制：
- Python 3.10+
- 现有Streamlit界面
- 八仙智能体系统
- Vertex AI记忆银行
## 📊 成功标准
### 架构质量指标：
- [ ] 模块耦合度 < 20%
- [ ] 代码复用率 > 80%
- [ ] 系统可用性 > 99%
- [ ] 响应时间 < 2秒
### 文档完整性：
- [ ] 架构图清晰易懂
- [ ] 接口文档完整
- [ ] 部署指南详细
- [ ] 故障处理手册
## 🎭 与稷下学宫的结合
### 八仙角色映射：
```python
# 设计八仙与数据源的智能映射
immortal_data_mapping = {
'吕洞宾': 'technical_analysis', # 技术分析专家
'何仙姑': 'risk_metrics', # 风险控制专家
'张果老': 'historical_data', # 历史数据分析师
'韩湘子': 'sector_analysis', # 新兴资产专家
'汉钟离': 'market_movers', # 热点追踪
'蓝采和': 'value_discovery', # 潜力股发现
'铁拐李': 'contrarian_analysis', # 逆向思维专家
'曹国舅': 'macro_economics' # 宏观经济分析师
}
```
## 🔄 协作接口
### 与其他AI的协作：
- **Claude（代码实现）**: 提供详细的接口规范和实现指导
- **Gemini（测试验证）**: 制定测试用例和验证标准
- **RovoDev（文档整合）**: 提供架构决策文档和技术规范
## 📅 时间节点
### 阶段一（2天）：
- [ ] 现有系统分析
- [ ] 架构方案设计
- [ ] 核心接口定义
### 阶段二（1天）：
- [ ] 详细设计文档
- [ ] 技术选型说明
- [ ] 风险评估报告
## 💡 创新要求
作为架构师，请在以下方面展现创新：
1. **传统文化与现代技术的融合**
2. **智能化的数据路由策略**
3. **自适应的性能优化机制**
4. **面向未来的可扩展架构**
---
**注意：** 这是一个文化与技术深度融合的项目，请在技术设计中体现中国传统哲学思想！

236
modules/documentation-suite/docs/AI_AGENT_TASKS/README.md Normal file
View File

@@ -0,0 +1,236 @@
# 🎭 四AI协作指南 - OpenBB稷下学宫集成项目
## 🎯 项目使命
将OpenBB金融数据平台与稷下学宫八仙论道系统深度融合，创造传统文化与现代金融科技的完美结合。
## 👥 团队角色与协作关系
```mermaid
graph TD
A[Qwen - 架构设计师] --> B[Claude - 核心开发工程师]
A --> C[Gemini - 测试验证专家]
A --> D[RovoDev - 项目整合专家]
B --> C
B --> D
C --> D
subgraph 协作流程
E[架构设计] --> F[代码实现]
F --> G[测试验证]
G --> H[文档整合]
H --> I[项目交付]
end
```
## 📋 各AI工作说明书链接
| AI角色 | 主要职责 | 工作说明书 |
|--------|----------|------------|
| **Qwen** | 架构设计师 | [`QWEN_ARCHITECTURE_DESIGN.md`](./QWEN_ARCHITECTURE_DESIGN.md) |
| **Claude** | 核心开发工程师 | [`CLAUDE_CODE_IMPLEMENTATION.md`](./CLAUDE_CODE_IMPLEMENTATION.md) |
| **Gemini** | 测试验证专家 | [`GEMINI_TEST_VALIDATION.md`](./GEMINI_TEST_VALIDATION.md) |
| **RovoDev** | 项目整合专家 | [`ROVODEV_PROJECT_INTEGRATION.md`](./ROVODEV_PROJECT_INTEGRATION.md) |
## 🔄 协作工作流
### 第一阶段：设计与规划 (Day 1-3)
```
Qwen 主导：
├── 系统架构设计
├── 接口规范定义
├── 技术选型方案
└── 实施计划制定
其他AI配合：
├── Claude: 技术可行性评估
├── Gemini: 测试策略制定
└── RovoDev: 项目框架搭建
```
### 第二阶段：核心开发 (Day 4-8)
```
Claude 主导：
├── 核心引擎实现
├── API集成开发
├── UI界面增强
└── 功能模块编码
其他AI配合：
├── Qwen: 架构指导和审查
├── Gemini: 同步测试执行
└── RovoDev: 代码集成管理
```
### 第三阶段：测试验证 (Day 9-12)
```
Gemini 主导：
├── 功能测试执行
├── 性能基准测试
├── 集成测试验证
└── 文化准确性检查
其他AI配合：
├── Qwen: 架构层面问题解决
├── Claude: 代码BUG修复
└── RovoDev: 测试结果整合
```
### 第四阶段：整合交付 (Day 13-15)
```
RovoDev 主导：
├── 文档体系整合
├── 用户指南编写
├── 项目质量检查
└── 最终版本发布
其他AI配合：
├── Qwen: 架构文档审核
├── Claude: 技术文档完善
└── Gemini: 测试报告整理
```
## 🎭 文化核心要求
### 八仙角色特征（所有AI必须遵循）：
```python
IMMORTAL_CHARACTERISTICS = {
'吕洞宾': {
'element': '乾', # 八卦方位
'specialty': '技术分析', # 专业特长
'personality': '系统性', # 性格特点
'approach': '理性分析' # 分析方法
},
'何仙姑': {
'element': '坤',
'specialty': '风险控制',
'personality': '稳健保守',
'approach': '风险优先'
},
'张果老': {
'element': '兑',
'specialty': '历史数据',
'personality': '博学深沉',
'approach': '历史借鉴'
},
'韩湘子': {
'element': '艮',
'specialty': '新兴资产',
'personality': '创新进取',
'approach': '前瞻思维'
},
'汉钟离': {
'element': '离',
'specialty': '热点追踪',
'personality': '敏锐活跃',
'approach': '趋势跟踪'
},
'蓝采和': {
'element': '坎',
'specialty': '价值发现',
'personality': '独立思考',
'approach': '逆向分析'
},
'铁拐李': {
'element': '巽',
'specialty': '逆向思维',
'personality': '犀利直接',
'approach': '反向验证'
},
'曹国舅': {
'element': '震',
'specialty': '宏观经济',
'personality': '高瞻远瞩',
'approach': '宏观视角'
}
}
```
### 稷下学宫核心价值：
- **开放包容**：各种观点都能得到尊重
- **理性辩论**：基于数据和逻辑的讨论
- **百家争鸣**：鼓励不同视角的碰撞
- **求同存异**：在分歧中寻找共识
## 📊 质量标准（所有AI共同遵循）
### 技术质量：
- [ ] 代码测试覆盖率 > 80%
- [ ] API响应时间 < 3秒
- [ ] 系统可用性 > 99%
- [ ] 并发处理能力 > 10 req/s
### 文化质量：
- [ ] 八仙特征准确性 100%
- [ ] 传统文化表达尊重性 100%
- [ ] 现代化融合自然度 > 90%
- [ ] 教育价值体现度 > 85%
### 用户体验：
- [ ] 界面直观度 > 90%
- [ ] 功能易用性 > 85%
- [ ] 文档完整性 > 95%
- [ ] 错误处理友好度 > 90%
## 🔄 沟通协作机制
### 日常沟通：
- **每日站会** (15分钟)：进度同步，问题协调
- **技术评审** (每2天)：关键决策讨论
- **质量检查** (每周)：交叉审查工作成果
### 问题升级机制：
```
Level 1: AI间直接协商
Level 2: RovoDev协调处理
Level 3: 项目负责人决策
```
### 文档共享约定：
- 所有设计文档实时共享
- 代码变更及时通知相关AI
- 测试结果定期同步
- 问题和解决方案公开透明
## 🎯 成功标准
### 项目成功的标志：
1. **功能完整**：OpenBB数据与八仙论道完美融合
2. **性能稳定**：各种场景下系统表现良好
3. **文化准确**：传统文化表达准确尊重
4. **用户满意**：最终用户体验优秀
5. **可维护性**：代码和文档便于后续维护
### 团队协作成功的标志：
1. **沟通顺畅**：各AI间协作无障碍
2. **质量一致**：各模块质量标准统一
3. **进度可控**：项目按时交付
4. **创新突出**：在传统与现代结合上有所突破
## 💡 创新目标
### 技术创新：
- 智能化的数据路由算法
- 自适应的性能优化机制
- 文化语境的AI理解能力
### 文化创新：
- 传统文化的现代化表达
- 金融科技的人文内涵
- AI技术的文化责任
### 用户体验创新：
- 沉浸式的文化体验
- 智能化的学习辅助
- 个性化的论道体验
---
## 📞 紧急联系
如遇到跨团队协调问题，请立即联系项目整合专家 RovoDev。
**记住**：我们不仅在构建技术产品，更在传承和发扬中华文化！每一行代码、每一个测试、每一份文档都承载着文化的使命！
---
*"稷下学宫，百家争鸣；开源精神，技术报国！"*

289
modules/documentation-suite/docs/AI_AGENT_TASKS/ROVODEV_PROJECT_INTEGRATION.md Normal file
View File

@@ -0,0 +1,289 @@
# 📚 RovoDev AI - OpenBB项目整合与文档管理工作说明书
## 🎯 任务概述
作为项目整合专家，您需要协调四个AI团队的工作成果，整合OpenBB集成项目的完整文档体系，并确保项目的顺利交付。
## 📋 核心职责
### 1. 项目协调与整合
**任务目标：** 统筹四个AI团队的工作，确保各模块无缝对接
**协调矩阵：**
```
Qwen Claude Gemini RovoDev
架构设计 主导 配合 验证 整合
代码实现 配合 主导 验证 监控
测试验证 配合 配合 主导 汇总
文档整合 配合 配合 配合 主导
```
**关键协调点：**
- 接口规范的一致性
- 代码实现与架构设计的匹配度
- 测试用例覆盖的完整性
- 文档与实际功能的准确性
### 2. 完整文档体系构建
**任务目标：** 建立OpenBB集成的完整文档生态
**文档架构：**
```
docs/openbb_integration/
├── 00_PROJECT_OVERVIEW.md # 项目总览
├── 01_ARCHITECTURE_DESIGN/ # 架构设计（Qwen输出）
│ ├── system_architecture.md
│ ├── data_flow_design.md
│ ├── integration_patterns.md
│ └── deployment_strategy.md
├── 02_IMPLEMENTATION_GUIDE/ # 实现指南（Claude输出）
│ ├── core_engine_implementation.md
│ ├── api_integration_guide.md
│ ├── ui_enhancement_guide.md
│ └── troubleshooting_guide.md
├── 03_TEST_DOCUMENTATION/ # 测试文档（Gemini输出）
│ ├── test_strategy.md
│ ├── test_results_report.md
│ ├── performance_benchmarks.md
│ └── quality_assurance_report.md
├── 04_USER_GUIDES/ # 用户指南
│ ├── getting_started.md
│ ├── immortal_debate_tutorial.md
│ ├── configuration_guide.md
│ └── best_practices.md
├── 05_CULTURAL_INTEGRATION/ # 文化融合文档
│ ├── immortal_characteristics.md
│ ├── jixia_philosophy_in_code.md
│ └── cultural_accuracy_guidelines.md
└── 06_MAINTENANCE/ # 维护文档
├── release_notes.md
├── upgrade_guide.md
├── known_issues.md
└── future_roadmap.md
```
### 3. 用户体验设计
**任务目标：** 确保最终用户能够轻松使用OpenBB集成功能
**用户旅程设计：**
```mermaid
graph TD
A[用户启动应用] --> B[选择OpenBB标签页]
B --> C[查看数据可用性状态]
C --> D{OpenBB是否可用?}
D -->|是| E[选择股票符号]
D -->|否| F[使用演示数据]
E --> G[启动八仙论道]
F --> G
G --> H[查看辩论结果]
H --> I[导出分析报告]
```
**交互设计文档：**
- 界面原型设计
- 用户流程图
- 错误处理流程
- 帮助文档集成
### 4. 质量保证与发布管理
**任务目标：** 确保项目质量并管理发布流程
**质量检查清单：**
- [ ] 代码规范一致性检查
- [ ] 文档完整性验证
- [ ] 功能集成测试通过
- [ ] 性能指标达标
- [ ] 文化准确性确认
- [ ] 用户体验验证
## 🎭 文化融合专项工作
### 传统文化现代化表达：
```markdown
# 八仙论道的现代诠释
## 文化内核保持：
- **稷下学宫精神**：开放包容、百家争鸣
- **八仙特质**：各具特色、相互补充
- **论道传统**：理性辩论、求同存异
## 现代技术表达：
- **数据驱动**：用真实数据支撑观点
- **智能化**：AI技术赋能传统智慧
- **可视化**：现代界面展示古典思想
```
### 文化准确性验证：
```python
# 文化审核检查点
CULTURAL_CHECKPOINTS = {
'immortal_names': '确保八仙姓名准确无误',
'characteristics': '验证八仙特征描述的准确性',
'philosophical_context': '确保稷下学宫背景的正确表达',
'respectful_representation': '确保文化表达的尊重性',
'educational_value': '验证文化教育价值的体现'
}
```
## 📊 项目管理仪表板
### 进度跟踪系统：
```
项目进度监控：
├── 架构设计进度 [████████░░] 80%
├── 代码实现进度 [██████░░░░] 60%
├── 测试验证进度 [████░░░░░░] 40%
└── 文档整合进度 [███████░░░] 70%
质量指标：
├── 代码覆盖率: 85%
├── 文档完整性: 90%
├── 测试通过率: 92%
└── 文化准确性: 95%
```
### 风险管理：
```markdown
## 主要风险点识别：
### 技术风险：
- OpenBB版本兼容性问题
- 性能瓶颈风险
- 数据质量不稳定
### 文化风险：
- 八仙形象表达不当
- 传统文化误读
- 现代化过度商业化
### 项目风险：
- 团队协调不畅
- 进度延迟风险
- 质量标准不一致
```
## 🔄 协作工作流
### 日常协调流程：
```
每日站会 (15分钟)：
├── 各AI汇报昨日进展
├── 今日工作计划
├── 阻塞问题讨论
└── 协作需求确认
每周回顾 (1小时)：
├── 整体进度回顾
├── 质量指标检查
├── 风险评估更新
└── 下周计划调整
```
### 交付物审核流程：
```mermaid
graph LR
A[AI团队提交] --> B[RovoDev初审]
B --> C[质量检查]
C --> D{是否达标?}
D -->|是| E[集成到主项目]
D -->|否| F[反馈修改意见]
F --> A
E --> G[用户验证]
G --> H[正式发布]
```
## 📅 里程碑和时间线
### 第一周：框架建立
- **Day 1-2**: 项目启动，框架搭建
- **Day 3-4**: 各团队初始输出整合
- **Day 5-7**: 首版原型验证
### 第二周：核心开发
- **Day 8-10**: 核心功能开发
- **Day 11-12**: 集成测试执行
- **Day 13-14**: 问题修复和优化
### 第三周：完善和发布
- **Day 15-17**: 文档完善和用户测试
- **Day 18-19**: 最终质量检查
- **Day 20-21**: 项目发布和交付
## 💡 创新整合方案
### 1. 智能文档生成
```python
class IntelligentDocGenerator:
"""智能文档生成器"""
def generate_api_docs(self, code_modules):
"""从代码自动生成API文档"""
pass
def create_tutorial_from_tests(self, test_cases):
"""从测试用例生成使用教程"""
pass
def cultural_context_validator(self, content):
"""文化内容准确性验证"""
pass
```
### 2. 多媒体文档体验
- 交互式代码示例
- 视频教程制作
- 在线演示环境
- 文化背景介绍动画
### 3. 社区协作平台
```markdown
## 开源社区建设：
### 贡献者指南：
- 代码贡献流程
- 文档改进指南
- 文化咨询渠道
- 反馈收集机制
### 社区活动：
- 八仙论道比赛
- 传统文化技术沙龙
- 开源项目展示
- 用户案例分享
```
## 🎯 成功标准
### 项目交付标准：
- [ ] 功能完整性 100%
- [ ] 文档覆盖率 95%+
- [ ] 用户满意度 90%+
- [ ] 文化准确性 100%
- [ ] 性能指标达标 100%
### 长期影响目标：
- [ ] 成为传统文化与AI结合的示范项目
- [ ] 推动开源社区的文化多元化
- [ ] 为金融科技注入文化内涵
- [ ] 建立可持续的维护生态
## 📈 后续运营规划
### 版本迭代计划：
```
v1.0: OpenBB基础集成
v1.1: 性能优化和BUG修复
v1.2: 更多数据源集成
v2.0: 高级分析功能
v2.1: 移动端适配
v3.0: 企业级功能
```
### 社区建设计划：
- 建立用户社区
- 定期发布教程
- 举办线上活动
- 收集用户反馈
---
**注意：** 作为项目整合者，您是传统文化与现代技术的桥梁！请确保每一个细节都体现对文化的尊重和技术的严谨！

184
modules/documentation-suite/docs/AUTORAG_INTEGRATION_PROMPT.md Normal file
View File

@@ -0,0 +1,184 @@
# 稷下学宫AI辩论系统 - AutoRAG集成提示词
## 🏛️ 系统概述
稷下学宫是一个基于中国传统哲学的AI辩论系统，模拟古代稷下学宫的学术辩论环境。系统中有八位仙人智能体，每位都有独特的投资哲学和辩论风格，需要通过AutoRAG服务获取相关的历史智慧和知识支持。
## 🎭 八仙智能体角色
### 铁拐李 (巽卦) - 逆向投资大师
- **投资哲学**: 逆向思维，挑战市场共识
- **记忆重点**: 市场异常、逆向案例、风险警示、反向策略
- **辩论风格**: 质疑主流观点，提出反向思考
### 吕洞宾 (乾卦) - 理性分析者
- **投资哲学**: 技术分析专家，数据驱动决策
- **记忆重点**: 技术分析、数据洞察、逻辑推理、理性决策
- **辩论风格**: 基于数据和逻辑的严密分析
### 何仙姑 (坤卦) - 直觉洞察者
- **投资哲学**: 风险控制专家，情感智慧
- **记忆重点**: 市场情绪、直觉判断、情感因素、人性洞察
- **辩论风格**: 基于直觉和情感智慧的分析
### 张果老 (兑卦) - 历史智慧者
- **投资哲学**: 历史数据分析师，经验导向
- **记忆重点**: 历史案例、长期趋势、周期规律、经验教训
- **辩论风格**: 引用历史案例和长期趋势
### 汉钟离 (离卦) - 平衡协调者
- **投资哲学**: 热点追踪专家，平衡思维
- **记忆重点**: 平衡策略、综合分析、协调方案、稳健建议
- **辩论风格**: 寻求各方观点的平衡点
### 蓝采和 (坎卦) - 创新思维者
- **投资哲学**: 潜力股发现者，创新导向
- **记忆重点**: 创新机会、新兴趋势、潜力发现、灵活策略
- **辩论风格**: 发现新兴机会和创新角度
### 韩湘子 (艮卦) - 艺术感知者
- **投资哲学**: 新兴资产专家，美学视角
- **记忆重点**: 美学趋势、创意洞察、感性分析、艺术视角
- **辩论风格**: 从美学和艺术角度分析市场
### 曹国舅 (震卦) - 实务执行者
- **投资哲学**: 机构视角分析师，实务导向
- **记忆重点**: 执行策略、机构动向、实务操作、专业分析
- **辩论风格**: 关注实际执行和机构操作
## 🔍 AutoRAG查询需求
### 查询类型
1. **历史智慧检索**: 根据辩论主题查找相关的古代智慧、哲学思想
2. **投资案例搜索**: 寻找历史上的投资成功/失败案例
3. **市场周期分析**: 查找关于市场周期、经济规律的古籍记录
4. **风险管理智慧**: 搜索古代关于风险控制、谨慎投资的思想
5. **人性洞察**: 查找关于人性、情绪、群体心理的古代观察
### 期望的AutoRAG接口
#### 1. 嵌入生成接口
```
POST /embed
{
"text": "需要生成嵌入的文本内容"
}
响应:
{
"embedding": [0.1, 0.2, ...], // 1024维BGE-M3嵌入向量
"model": "bge-m3"
}
```
#### 2. 记忆存储接口
```
POST /upsert
{
"vectors": [
{
"id": "memory_uuid",
"values": [0.1, 0.2, ...],
"metadata": {
"agent_name": "tieguaili",
"chinese_name": "铁拐李",
"content": "记忆内容",
"memory_type": "knowledge|conversation|preference|strategy",
"debate_topic": "辩论主题",
"timestamp": "2024-01-01T00:00:00Z"
}
}
],
"namespace": "agent_name" // 智能体命名空间
}
响应:
{
"success": true,
"inserted_count": 1
}
```
#### 3. 记忆检索接口
```
POST /query
{
"vector": [0.1, 0.2, ...], // 查询向量
"topK": 10, // 返回数量
"namespace": "tieguaili", // 智能体命名空间
"filter": { // 可选过滤条件
"memory_type": "knowledge"
}
}
响应:
{
"matches": [
{
"id": "memory_uuid",
"score": 0.95,
"metadata": {
"content": "相关记忆内容",
"agent_name": "tieguaili",
"memory_type": "knowledge",
"debate_topic": "投资哲学"
}
}
]
}
```
## 📝 使用场景示例
### 场景1: 辩论前的知识准备
```
辩论主题: "NVIDIA股票投资价值分析"
铁拐李查询: "历史上科技股泡沫的案例和教训"
张果老查询: "古代关于新兴技术投资的智慧"
何仙姑查询: "市场狂热时期的风险控制思想"
```
### 场景2: 辩论中的观点支撑
```
当前观点: "AI技术发展存在过度炒作风险"
相关查询: "古代关于技术革新的理性思考"
期望返回: 相关的古籍智慧，支持或反驳当前观点
```
### 场景3: 辩论后的经验总结
```
辩论结果: 铁拐李的逆向观点获得认同
存储记忆: "在AI股票讨论中，逆向思维帮助识别了估值风险"
记忆类型: strategy
```
## 🎯 集成目标
1. **智能记忆**: 每位仙人都有独立的记忆空间，能够学习和积累经验
2. **文化融合**: 将古代智慧与现代投资分析相结合
3. **个性化**: 根据每位仙人的特点，提供差异化的知识支持
4. **持续学习**: 通过辩论过程不断丰富和完善知识库
## 🔧 技术要求
- **向量维度**: 1024 (BGE-M3模型)
- **命名空间**: 支持按智能体分离数据
- **元数据**: 丰富的元数据支持，便于过滤和分类
- **性能**: 低延迟的检索响应，支持实时辩论
- **扩展性**: 支持未来添加更多智能体和记忆类型
## 🌟 期望效果
通过AutoRAG集成，稷下学宫将实现：
- 🧠 **智慧传承**: 古代哲学智慧指导现代投资决策
- 🎭 **角色一致**: 每位仙人保持独特的人格和观点
- 📚 **知识积累**: 持续学习和经验沉淀
- 🔄 **动态辩论**: 基于历史记忆的深度讨论
- 🎯 **精准分析**: 结合传统智慧的投资洞察
---
**让AI辩论照亮投资智慧，让古代智慧指引现代决策** 🏛️✨

218
modules/documentation-suite/docs/GITHUB_PAGES_PUBLISH_PLAN.md Normal file
View File

@@ -0,0 +1,218 @@
# 🌐 GitHub Pages 发布计划
## 📋 发布内容规划
### **🎯 发布目标**
- 展示项目功能和特性
- 提供用户友好的文档
- 吸引潜在用户和贡献者
- 保持专业形象
### **✅ 适合发布的内容**
#### **1. 项目主页 (根目录)**
```
/
├── README.md # 项目主介绍
├── RELEASE_v2.0.0.md # 版本发布说明
├── QUICK_START_GUIDE.md # 快速上手指南
├── VERSION # 版本号
├── requirements.txt # 依赖清单
└── .gitignore # Git忽略文件
```
#### **2. 用户文档 (docs/)**
```
docs/
├── index.md # 文档首页
├── guides/ # 用户指南
│ ├── quick-start.md # 快速开始
│ ├── installation.md # 安装指南
│ ├── configuration.md # 配置指南
│ ├── cloudflare-integration.md # Cloudflare集成
│ ├── google-adk-migration.md # Google ADK迁移
│ └── load-balancing.md # 负载均衡指南
├── features/ # 功能特性
│ ├── debate-system.md # 辩论系统
│ ├── memory-bank.md # 记忆系统
│ ├── eight-immortals.md # 八仙系统
│ └── tianxia-analysis.md # 天下体系
├── api/ # API文档
│ ├── rapidapi-setup.md # RapidAPI设置
│ └── vertex-memory-bank.md # Memory Bank API
└── examples/ # 示例代码
├── basic-usage.md # 基础用法
└── advanced-features.md # 高级功能
```
#### **3. 设计文档 (design/)**
```
design/
├── overview.md # 项目概览
├── architecture.md # 系统架构
├── debate-system.md # 辩论系统设计
└── roadmap.md # 开发路线图
```
#### **4. 演示和示例**
```
examples/
├── basic-debate.md # 基础辩论示例
├── memory-bank-demo.md # 记忆系统演示
└── load-balancing-demo.md # 负载均衡演示
```
### **🔒 保留在 internal/ 的内容**
#### **1. 内部开发文档**
- 开发计划和路线图
- 技术实现细节
- 内部策略文档
- 代码审查记录
#### **2. 敏感信息**
- API密钥配置
- 内部分析报告
- 迁移方案细节
- 历史文档
#### **3. 配置文件**
- 环境配置
- 内部脚本
- AI助手配置
## 🚀 发布步骤
### **第一阶段：内容准备**
1. **优化 README.md**
- 添加项目徽章
- 完善功能介绍
- 添加截图和演示
- 优化安装说明
2. **创建文档首页**
- 设计文档结构
- 创建导航菜单
- 添加搜索功能
3. **整理用户指南**
- 统一文档格式
- 添加代码示例
- 完善配置说明
### **第二阶段：GitHub Pages 配置**
1. **启用 GitHub Pages**
```bash
# 在仓库设置中启用 GitHub Pages
# 选择 docs/ 文件夹作为源
```
2. **配置 Jekyll 主题**
```yaml
# _config.yml
title: 太公心易 - 稷下学宫AI辩论系统
description: 基于中国哲学传统的多AI智能体辩论平台
theme: jekyll-theme-cayman
```
3. **创建导航结构**
```markdown
# docs/index.md
---
layout: default
title: 太公心易文档
---
```
### **第三阶段：内容发布**
1. **发布核心文档**
- 项目介绍
- 快速开始指南
- 功能特性说明
2. **发布用户指南**
- 安装配置
- 使用教程
- 示例代码
3. **发布设计文档**
- 系统架构
- 技术设计
- 开发路线图
## 📊 发布效果预期
### **用户访问路径**
```
GitHub Pages 首页
├── 项目介绍 → README.md
├── 快速开始 → QUICK_START_GUIDE.md
├── 用户指南 → docs/guides/
├── 功能特性 → docs/features/
├── API文档 → docs/api/
└── 示例代码 → docs/examples/
```
### **SEO 优化**
- 添加 meta 标签
- 优化标题和描述
- 添加关键词
- 创建 sitemap
### **用户体验**
- 响应式设计
- 快速加载
- 清晰导航
- 搜索功能
## 🔧 技术实现
### **GitHub Pages 配置**
```yaml
# .github/workflows/pages.yml
name: Deploy to GitHub Pages
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./docs
```
### **文档结构优化**
- 使用 Markdown 格式
- 添加目录导航
- 统一代码高亮
- 优化图片显示
## 📈 维护计划
### **定期更新**
- 每月更新功能文档
- 季度更新架构文档
- 及时更新版本说明
### **用户反馈**
- 收集用户问题
- 更新常见问题
- 优化文档内容
### **版本同步**
- 保持文档与代码同步
- 及时发布新版本说明
- 维护版本历史
---
**发布状态**：🔄 计划中
**预计完成**：2025年8月底

270
modules/documentation-suite/docs/VERTEX_MEMORY_BANK_SETUP.md Normal file
View File

@@ -0,0 +1,270 @@
# Vertex AI Memory Bank 配置指南
## 🏛️ 稷下学宫记忆银行集成
本文档介绍如何为稷下学宫AI辩论系统配置和使用Vertex AI Memory Bank功能。
## 📋 前置要求
### 1. Google Cloud 项目设置
- 有效的 Google Cloud 项目
- 启用 Vertex AI API
- 配置适当的 IAM 权限
### 2. 必需的依赖
```bash
pip install google-cloud-aiplatform>=1.38.0
pip install google-adk # 或开发版本
```
### 3. 环境变量配置
在 Doppler 或本地环境中设置以下变量：
```bash
# 必需配置
GOOGLE_API_KEY=your_gemini_api_key
GOOGLE_CLOUD_PROJECT_ID=your-project-id
# 可选配置
GOOGLE_CLOUD_LOCATION=us-central1 # 默认区域
VERTEX_MEMORY_BANK_ENABLED=TRUE # 启用记忆银行
GOOGLE_SERVICE_ACCOUNT_KEY=path/to/service-account.json # 服务账号密钥
```
## 🚀 快速开始
### 1. 验证配置
```bash
# 验证 Google ADK 配置
python config/settings.py
# 测试 Memory Bank 连接
python tests/test_vertex_memory_bank.py
```
### 2. 初始化八仙记忆银行
```python
from src.jixia.memory.vertex_memory_bank import initialize_baxian_memory_banks
# 初始化所有八仙的记忆银行
memory_bank = await initialize_baxian_memory_banks(
project_id="your-project-id",
location="us-central1"
)
```
### 3. 创建记忆增强智能体
```python
from src.jixia.agents.memory_enhanced_agent import create_memory_enhanced_council
# 创建记忆增强的八仙议会
council = await create_memory_enhanced_council()
# 进行记忆增强辩论
result = await council.conduct_memory_debate(
topic="NVIDIA股票投资分析",
participants=["tieguaili", "lvdongbin", "hexiangu"],
rounds=3
)
```
## 🎭 八仙记忆特性
每位仙人都有独特的记忆重点和学习模式：
### 铁拐李 (逆向投资大师)
- **记忆重点**: 市场异常、逆向案例、风险警示、反向策略
- **学习模式**: 关注市场共识的反面，记住历史上的逆向成功案例
### 吕洞宾 (理性分析者)
- **记忆重点**: 技术分析、数据洞察、逻辑推理、理性决策
- **学习模式**: 基于数据和逻辑的严密分析，记住成功的分析框架
### 何仙姑 (直觉洞察者)
- **记忆重点**: 市场情绪、直觉判断、情感因素、人性洞察
- **学习模式**: 关注市场情绪变化，记住情感驱动的市场事件
### 张果老 (历史智慧者)
- **记忆重点**: 历史案例、长期趋势、周期规律、经验教训
- **学习模式**: 从历史中学习，记住重要的历史模式和教训
### 汉钟离 (平衡协调者)
- **记忆重点**: 平衡策略、综合分析、协调方案、稳健建议
- **学习模式**: 寻求各方观点的平衡，记住成功的协调案例
### 蓝采和 (创新思维者)
- **记忆重点**: 创新机会、新兴趋势、潜力发现、灵活策略
- **学习模式**: 发现新兴机会，记住创新投资的成功案例
### 韩湘子 (艺术感知者)
- **记忆重点**: 美学趋势、创意洞察、感性分析、艺术视角
- **学习模式**: 从美学角度分析市场，记住艺术和创意相关的投资
### 曹国舅 (实务执行者)
- **记忆重点**: 执行策略、机构动向、实务操作、专业分析
- **学习模式**: 关注实际执行，记住机构操作和专业分析
## 🔧 高级配置
### 1. 自定义记忆类型
```python
# 支持的记忆类型
MEMORY_TYPES = [
"conversation", # 对话记忆
"preference", # 偏好记忆
"knowledge", # 知识记忆
"strategy" # 策略记忆
]
# 添加自定义记忆
await memory_bank.add_memory(
agent_name="tieguaili",
content="在熊市中，逆向投资策略往往更有效",
memory_type="strategy",
debate_topic="市场策略",
metadata={
"market_condition": "bear_market",
"confidence": 0.8,
"source": "historical_analysis"
}
)
```
### 2. 记忆搜索和过滤
```python
# 搜索特定类型的记忆
strategy_memories = await memory_bank.search_memories(
agent_name="tieguaili",
query="逆向投资",
memory_type="strategy",
limit=10
)
# 获取智能体的完整上下文
context = await memory_bank.get_agent_context(
agent_name="tieguaili",
debate_topic="NVIDIA投资分析"
)
```
### 3. 辩论会话保存
```python
# 自动保存辩论会话
await memory_bank.save_debate_session(
debate_topic="比特币投资价值",
participants=["tieguaili", "lvdongbin", "hexiangu"],
conversation_history=conversation_history,
outcomes={
"winner": "tieguaili",
"key_insights": ["逆向思维在加密货币投资中的重要性"],
"consensus": "需要更谨慎的风险管理"
}
)
```
## 📊 监控和管理
### 1. 记忆银行状态检查
```python
# 检查记忆银行状态
for agent_name, bank_name in memory_bank.memory_banks.items():
chinese_name = memory_bank.baxian_agents[agent_name]
print(f"{chinese_name}: {bank_name}")
```
### 2. 记忆使用统计
```python
# 获取记忆统计信息
stats = await memory_bank.get_memory_stats(agent_name="tieguaili")
print(f"总记忆数: {stats['total_memories']}")
print(f"对话记忆: {stats['conversation_count']}")
print(f"策略记忆: {stats['strategy_count']}")
```
### 3. 记忆清理和维护
```python
# 清理过期记忆（如果需要）
await memory_bank.cleanup_old_memories(
agent_name="tieguaili",
days_old=30,
memory_type="conversation"
)
```
## 🔒 安全和隐私
### 1. 数据加密
- 所有记忆数据在传输和存储时都会加密
- 使用 Google Cloud 的企业级安全措施
### 2. 访问控制
- 每个智能体只能访问自己的记忆银行
- 通过 IAM 控制项目级别的访问权限
### 3. 数据保留
- 可以配置记忆数据的保留期限
- 支持手动删除敏感记忆
## 🚨 故障排除
### 常见问题
#### 1. 项目ID未配置
```
❌ Google Cloud Project ID 未配置
```
**解决方案**: 设置 `GOOGLE_CLOUD_PROJECT_ID` 环境变量
#### 2. API权限不足
```
❌ 403 Forbidden: Vertex AI API access denied
```
**解决方案**:
- 在 Google Cloud Console 中启用 Vertex AI API
- 确保服务账号有适当的权限
#### 3. 记忆银行创建失败
```
❌ 创建记忆银行失败: Region not supported
```
**解决方案**:
- 检查 `GOOGLE_CLOUD_LOCATION` 设置
- 使用支持 Memory Bank 的区域（如 us-central1）
#### 4. 依赖包缺失
```
❌ Google Cloud AI Platform 未安装
```
**解决方案**:
```bash
pip install google-cloud-aiplatform>=1.38.0
```
### 调试模式
```python
# 启用详细日志
import logging
logging.basicConfig(level=logging.DEBUG)
# 测试连接
python tests/test_vertex_memory_bank.py
```
## 📚 参考资源
- [Vertex AI Memory Bank 官方文档](https://cloud.google.com/blog/products/ai-machine-learning/vertex-ai-memory-bank-in-public-preview)
- [Google ADK 文档](https://github.com/google/adk-python)
- [稷下学宫项目文档](../README.md)
## 🤝 贡献指南
如果你想为 Memory Bank 功能贡献代码：
1. 确保所有新功能都有对应的测试
2. 遵循现有的代码风格和注释规范
3. 更新相关文档
4. 提交 Pull Request 前运行完整的测试套件
---
**让AI辩论照亮投资智慧，记忆银行让智慧永续传承** 🏛️✨

2884
modules/documentation-suite/docs/analysis/meta_analysis_results.txt Normal file
View File

File diff suppressed because it is too large Load Diff

140
modules/documentation-suite/docs/analysis/rss_debug_analysis.md Normal file
View File

@@ -0,0 +1,140 @@
# RSS代码只能抓取一条数据的问题分析
## 问题现象
原代码期望抓取100条RSS数据，但实际只能抓取到1条数据。
## 可能的原因分析
### 1. RSS数据结构识别问题
**最可能的原因**：RSS数据的实际结构与代码中的4种预设情况都不匹配。
常见的RSS数据结构包括：
- `rss.channel.item[]` (标准RSS 2.0)
- `feed.entry[]` (Atom格式)
- `channel.item[]` (简化RSS)
- `data[]` (某些API返回格式)
- 直接的对象数组
### 2. 输入数据获取问题
```javascript
const rssSource = inputs[0]?.json; // 可能inputs[0]为空或结构不对
```
### 3. 去重逻辑过于严格
如果MongoDB中已有大量数据，可能导致新数据被过度过滤。
### 4. 错误处理不足
原代码缺乏详细的调试信息，难以定位具体问题。
## 解决方案
### 1. 增强数据结构识别
```javascript
// 扩展RSS结构处理
if (rssSource?.rss?.channel?.item && Array.isArray(rssSource.rss.channel.item)) {
rssItems = rssSource.rss.channel.item;
}
else if (rssSource?.feed?.entry && Array.isArray(rssSource.feed.entry)) {
rssItems = rssSource.feed.entry;
}
// ... 更多结构支持
```
### 2. 添加详细调试信息
```javascript
console.log('输入数据结构:', JSON.stringify(inputs[0], null, 2).substring(0, 500));
console.log('RSS源数据的所有键:', Object.keys(rssSource || {}));
```
### 3. 改进去重逻辑
```javascript
// 只有当MongoDB确实有数据时才进行去重
if (existingItems.length > 0 && existingItems[0] !== null) {
// 执行去重逻辑
} else {
console.log('MongoDB中无现有数据，跳过去重检查');
}
```
### 4. 增强错误处理
```javascript
try {
// 主要逻辑
} catch (error) {
console.error("处理错误：", error.message);
console.error("错误堆栈：", error.stack);
}
```
## 调试步骤
1. **检查输入数据结构**
```javascript
console.log('inputs长度:', inputs.length);
console.log('第一个输入:', inputs[0]);
```
2. **检查RSS源数据**
```javascript
console.log('RSS源数据类型:', typeof rssSource);
console.log('RSS源数据键:', Object.keys(rssSource || {}));
```
3. **检查提取结果**
```javascript
console.log('提取到的RSS条目数:', rssItems.length);
console.log('第一个RSS条目:', rssItems[0]);
```
4. **检查去重影响**
```javascript
console.log('MongoDB现有数据数量:', existingItems.length);
console.log('去重后输出数量:', outputItems.length);
```
## 建议的修复代码
使用 `improved_rss_code.js` 中的改进版本，它包含：
- 更全面的RSS结构支持
- 详细的调试信息输出
- 改进的去重逻辑
- 更好的错误处理
- 更灵活的字段映射
## 常见RSS结构示例
### RSS 2.0格式
```json
{
"rss": {
"channel": {
"item": [
{"title": "新闻1", "link": "url1"},
{"title": "新闻2", "link": "url2"}
]
}
}
}
```
### Atom格式
```json
{
"feed": {
"entry": [
{"title": "新闻1", "link": {"href": "url1"}},
{"title": "新闻2", "link": {"href": "url2"}}
]
}
}
```
### 简化格式
```json
{
"items": [
{"title": "新闻1", "url": "url1"},
{"title": "新闻2", "url": "url2"}
]
}
```

10
modules/documentation-suite/docs/architecture.md Normal file
View File

@@ -0,0 +1,10 @@
# 智能监控系统架构设计
## 系统概述
设计一个分布式智能监控系统，支持实时数据采集和分析。
## 核心组件
- 数据采集层
- 实时处理引擎
- 告警通知模块
- 可视化仪表盘

67
modules/documentation-suite/docs/architecture/GEMINI_ARCH_REVIEW.md Normal file
View File

@@ -0,0 +1,67 @@
# 架构审查报告：太公心易 FSM 系统
**审查人:** Gemini
**日期:** 2025-08-21
**审查范围:** `internal/core/fsm.md`, `internal/core/fsm_analysis.md`, `internal/migration/rfc_taigong_xinyi_fsm_enhancements.md`
## 1. 概述
“太公心易”系统是一个高度创新的AI决策框架，其核心是围绕一个有限状态机（FSM）构建的。该系统巧妙地将复杂的多智能体协作流程映射为道家哲学和中国神话中的概念，形成了一套独特且富有表现力的架构。本次审查旨在评估当前设计的优点、识别潜在风险，并提出初步的重构建议。
## 2. 优点 (Advantages)
1. **高度的可解释性 (High Explainability):** 通过将FSM的状态和功能模块映射为“八仙论道”、“太上老君炼丹”等神话角色和情景，系统设计变得非常直观，易于团队理解和沟通，极大地降低了复杂AI系统的认知门槛。
2. **出色的模块化 (Excellent Modularity):** FSM的每个状态（如`Collecting`, `Refine`, `ExternalFetch`）以及“十二龙子”的角色都定义了清晰的职责边界。这种设计天然地将系统解耦成一系列高内聚、低耦合的组件，为独立开发、测试和扩展奠定了坚实的基础。
3. **设计上的鲁棒性 (Robust by Design):** 设计文档中明确包含了多源外部验证（“灵宝道君”）、冲突检测与解决、以及错误处理状态等机制。这表明系统在设计之初就充分考虑了现实世界中数据的不一致性和不可靠性，具备很强的鲁棒性潜力。
4. **框架的创新性 (Innovative Framework):** 将东方哲学思想与现代AI工程实践（如多智能体、FSM、工作流自动化）相结合，不仅是一个技术框架，更是一个文化与技术融合的范例，具有很强的独创性和探索价值。
## 3. 潜在风险 (Potential Risks)
1. **概念与实现的差距 (Concept-Implementation Gap):** 高度抽象的神话概念在转化为具体、可维护的工程代码时可能面临挑战。例如，“元神出窍”对应异步Webhook，如果日志和监控不能同时反映“神话层”和“技术层”的状态，会给调试带来巨大困难。**这是最主要的风险。**
2. **过度设计的可能性 (Potential for Over-engineering):** RFC中提议的增强FSM状态和完整的十二龙子集成，对于项目的初始阶段可能过于复杂。存在为了贴合神话设定而引入不必要技术复杂度的风险。
3. **性能瓶颈 (Performance Bottlenecks):** 系统的多个阶段都存在潜在的性能问题：
* `Collecting`: 多智能体辩论可能耗时过长或无法收敛。
* `ExternalFetch`: 大量调用外部API（尤其是通过N8N）会引入显著的网络延迟和不确定性。
* `Validation`/`Synthesis`: 多层次的验证和融合会增加计算开销。
4. **对外部系统的强依赖 (Strong Dependency on External Systems):** RFC中提到，系统对N8N的依赖是一个已知的稳定性风险。如果N8N服务中断或响应缓慢，将直接影响整个决策流程的核心环节。
## 4. 初步重构建议 (Preliminary Refactoring Suggestions)
1. **MVP先行，迭代演进 (MVP First, Evolve Iteratively):**
* **简化FSM:** 优先实现最核心的FSM流程：`Collecting` → `Refine` → `ExternalFetch` → `Report`。将RFC中提出的`Validation`, `Synthesis`, `ConflictDetected`等增强状态作为后续迭代的目标。先验证核心价值，再逐步完善。
2. **建立“龙族”抽象接口 (Abstract the "Dragon" Interface):**
* 不要将特定的龙子实现硬编码到FSM状态中。建议定义一个通用的`Dragon`基类或接口，明确其能力（如`can_search`, `can_verify`）。FSM状态根据需要向一个“龙族工厂”请求相应能力的龙子实例。这能有效解耦FSM与龙子的具体实现，提高灵活性。
3. **双层日志与可观测性 (Dual-Layer Logging and Observability):**
* 从项目第一天起，就建立结构化的日志系统。每条日志应同时包含**神话层**和**技术层**的信息。
* **示例:**
```json
{
"timestamp": "2025-08-21T10:00:00Z",
"myth_layer": {
"actor": "灵宝道君",
"action": "撒豆成兵",
"status": "开始验证"
},
"tech_layer": {
"event": "API_CALL_START",
"service": "n8n_webhook",
"endpoint": "/webhook/lingbao-twelve-dragons",
"trace_id": "xyz-123"
}
}
```
* 这种方法可以在保持系统可解释性的同时，为开发者提供清晰的调试路径。
4. **为N8N设计降级策略 (Implement a Fallback Strategy for N8N):**
* 如RFC中所建议，应为`ExternalFetch`状态设计一个降级（Fallback）机制。当调用N8N工作流失败或超时，系统应能自动切换到一个备用的、更简单的验证方式（例如，直接通过Python库调用单个搜索引擎API）。这能显著提升系统的可靠性。
5. **代码驱动，验证设计 (Drive with Code, Validate the Design):**
* 当前项目文档非常丰富，但代码实现尚不明确。建议团队将重心适当向编码倾斜，优先实现RFC附录中提到的核心模块（如`dragon_base.py`, `lingbao_papaniu.py`）。通过实际编码来检验和迭代当前架构设计的可行性。

44
modules/documentation-suite/docs/architecture/PROJECT_SUMMARY.md Normal file
View File

@@ -0,0 +1,44 @@
# 炼妖壶项目结构与核心模块概览
## 项目核心理念
炼妖壶项目（Lianyaohu）是一个融合中国传统文化与现代AI技术的投资分析系统。其核心理念是：
- 利用八仙、龙子等神话角色作为AI智能体，进行多维度的市场分析
- 通过"差序格局"、"十二长生"等传统哲学思想构建市场模型
- 结合现代技术（如FSM状态机、图数据库）实现智能化决策支持
## 核心模块介绍
### 1. 天体图谱 (Celestial Map) - `celestial_map.py`
基于费孝通的"差序格局"理论，构建产业链影响力的图模型：
- 恒星 (Star): 产业链核心/上游公司
- 行星 (Planet): 紧密关联的中游公司
- 卫星 (Satellite): 下游或关联度较弱的公司
- 引力 (Gravity): 公司间的影响强度，通过NetworkX图结构建模
### 2. 市场状态机 (Market FSM) - `market_fsm.py`
一个简化的市场分析有限状态机，演示如何通过抽象基类调用外部引擎：
- 核心状态：Idle → Collecting → CycleAnalysis → Reporting → Idle
- 通过注入神话引擎和周期模型实现解耦
### 3. 神话引擎 (Mythology Engine) - `mythology.py`
将技术组件映射到神话角色的抽象接口：
- 抽象基类`MythologyEngine`定义统一接口
- `DaoistMythologyEngine`实现道家神话映射（如太上老君、灵宝道君等）
### 4. 周期模型 (Cycle Model) - `cycle_models.py`
描述市场或个股生命周期的抽象模型：
- 抽象基类`CycleModel`定义统一接口
- `TwelveStagesOfLifeCycleModel`实现"十二长生"周期模型
### 5. 妖股扫描器 (Monster Stock Scanner) - `monster_stock_scanner.py`
基于"龙生九子"概念的个股分析工具：
- `Dragon`抽象基类定义龙子接口
- `Bixi`(赑屃)负责分析宏观结构性压力（天时）
- `Fuxi`(负屃)负责计算个股主题挤压分数（地利）
- 结合"天时地利人和"识别潜在妖股
## 项目架构特色
1. **文化驱动设计**：所有模块都深度融入中国传统文化元素
2. **高度解耦**：通过抽象基类实现核心逻辑与具体实现的分离
3. **可扩展性强**：可以轻松添加新的神话体系或周期模型
4. **清晰的职责划分**：每个模块都有明确的功能定位

13
modules/documentation-suite/docs/architecture/component_interaction_diagram.mermaid Normal file
View File

@@ -0,0 +1,13 @@
graph LR
A[Streamlit App] --> B[OpenBB Tab]
A --> C[Debate System]
C --> D[Immortal Agents]
D --> E[OpenBB Engine]
D --> F[Perpetual Engine]
B --> G[_load_price_data]
G --> H{OpenBB Available?}
H -- Yes --> I[OpenBB obb]
H -- No --> J[Demo/Synthetic Data]
E --> K{OpenBB Available?}
K -- Yes --> I
K -- No --> L[Error Result]

9
modules/documentation-suite/docs/architecture/data_flow_diagram.mermaid Normal file
View File

@@ -0,0 +1,9 @@
graph TD
A[User Request] --> B{OpenBB Installed?}
B -- Yes --> C{OpenBB Data Available?}
C -- Yes --> D[OpenBB Engine]
C -- No --> E[Fallback to Demo/Synthetic Data]
B -- No --> E
D --> F[Format Data]
E --> F
F --> G[Return to Agent/UI]

181
modules/documentation-suite/docs/architecture/deployment_architecture.md Normal file
View File

@@ -0,0 +1,181 @@
# OpenBB Integration Deployment Architecture
## Environment and Dependencies
### Base Requirements
- **Python Version**: 3.8 or higher
- **Core Dependencies**: As specified in `requirements.txt` (Streamlit, etc.)
### Optional OpenBB Dependency
- **OpenBB Library**: `openbb>=4.1.0`
- **Installation**: Not included in default `requirements.txt` to maintain lightweight base installation
- **Activation**: Install via `pip install "openbb>=4.1.0"` when needed
## Configuration Management
### Environment Variables
- **Standard Project Variables**: Managed through Doppler (RAPIDAPI_KEY, GOOGLE_API_KEY, etc.)
- **OpenBB Provider Variables**:
- For public data sources (like yfinance): No specific configuration required
- For premium data sources (e.g., Polygon, FMP):
- Variables are managed by OpenBB internally
- Follow OpenBB documentation for provider-specific setup
- Example: `POLYGON_API_KEY` for Polygon.io data
### Feature Flags
- **JIXIA_MEMORY_BACKEND**: When set to "cloudflare", enables Cloudflare AutoRAG as memory backend
- **GOOGLE_GENAI_USE_VERTEXAI**: When set to "TRUE", enables Vertex AI for memory bank
## Deployment Scenarios
### 1. Base Deployment (OpenBB Not Installed)
- **Characteristics**:
- Lightweight installation
- Relies on existing RapidAPI-based perpetual engine
- UI falls back to demo or synthetic data in OpenBB tab
- **Use Cases**:
- Minimal environment setups
- Systems where OpenBB installation is not feasible
- Development environments focusing on other features
### 2. Full Deployment (With OpenBB)
- **Characteristics**:
- Enhanced data capabilities through OpenBB
- Access to multiple data providers
- Improved data quality and coverage
- **Use Cases**:
- Production environments requiring comprehensive market data
- Advanced financial analysis and debate scenarios
- Integration with premium data sources
### 3. Hybrid Deployment (Selective Features)
- **Characteristics**:
- Selective installation of OpenBB providers
- Mix of OpenBB and perpetual engine data sources
- Fallback mechanisms ensure continuous operation
- **Use Cases**:
- Cost optimization by using free providers where possible
- Gradual migration from perpetual engine to OpenBB
- Testing new data sources without full commitment
## Containerization (Docker)
### Base Image
- Python 3.10-slim or equivalent
### Multi-Stage Build
1. **Builder Stage**:
- Install build dependencies
- Install Python dependencies
2. **Runtime Stage**:
- Copy installed packages from builder
- Copy application code
- Install optional OpenBB dependencies if specified
### Docker Compose Configuration
- Service definitions for main application
- Optional service for database (if using persistent memory backends)
- Volume mounts for configuration and data persistence
## Cloud Deployment
### Google Cloud Platform (GCP)
- **App Engine**:
- Standard environment with custom runtime
- Environment variables configured through `app.yaml`
- **Cloud Run**:
- Containerized deployment
- Secrets managed through Secret Manager
- **Compute Engine**:
- Full control over VM configuration
- Persistent disks for data storage
### Considerations for Cloud Deployment
- **API Key Security**:
- Use secret management services (Google Secret Manager, Doppler)
- Never store keys in code or environment files
- **Memory Backend Configuration**:
- For Vertex AI Memory Bank: Configure GOOGLE_CLOUD_PROJECT_ID and authentication
- For Cloudflare AutoRAG: Configure CLOUDFLARE_ACCOUNT_ID and API token
- **Scalability**:
- Stateless application design allows horizontal scaling
- Memory backends provide persistence across instances
## Memory Backend Integration
### Vertex AI Memory Bank (Default/Primary)
- **Activation**: Requires GOOGLE_GENAI_USE_VERTEXAI=true and proper GCP authentication
- **Dependencies**: `google-cloud-aiplatform` (installed with google-adk)
- **Deployment**: Requires GCP project with Vertex AI API enabled
### Cloudflare AutoRAG (Alternative)
- **Activation**: Requires JIXIA_MEMORY_BACKEND=cloudflare and Cloudflare credentials
- **Dependencies**: `aiohttp` (already in requirements)
- **Deployment**: Requires Cloudflare account with Vectorize and Workers AI enabled
## Monitoring and Observability
### Health Checks
- Application startup verification
- OpenBB availability check endpoint
- Memory backend connectivity verification
### Logging
- Structured logging for data access patterns
- Error tracking for failed data retrievals
- Performance metrics for data loading times
### Metrics Collection
- API usage counters (both RapidAPI and OpenBB)
- Fallback trigger rates
- Memory backend operation statistics
## Security Posture
### Data Security
- In-memory data processing
- No persistent storage of sensitive financial data
- Secure handling of API responses
### Access Control
- Streamlit authentication (if enabled)
- API key isolation per data provider
- Memory backend access controls through provider mechanisms
### Network Security
- HTTPS for all external API calls
- Outbound firewall rules for API endpoints
- Secure credential injection mechanisms
## Disaster Recovery and Business Continuity
### Data Source Redundancy
- Multiple API providers through OpenBB
- Fallback to perpetual engine when OpenBB fails
- Synthetic data generation for UI continuity
### Memory Backend Failover
- Local simulation mode when cloud backends are unavailable
- Graceful degradation of memory features
### Recovery Procedures
- Automated restart on critical failures
- Manual intervention procedures for configuration issues
- Rollback capabilities through version control
## Performance Optimization
### Caching Strategies
- OpenBB's internal caching mechanisms
- Streamlit's built-in caching for UI components
- Memory backend for persistent agent knowledge
### Resource Management
- Asynchronous data loading where possible
- Memory-efficient data structures
- Connection pooling for API requests
### Scaling Considerations
- Horizontal scaling for handling concurrent users
- Vertical scaling for memory-intensive operations
- Load balancing for distributed deployments

168
modules/documentation-suite/docs/architecture/openbb_integration_architecture.md Normal file
View File

@@ -0,0 +1,168 @@
# OpenBB Integration Architecture for 炼妖壶 (Lianyaohu) - 稷下学宫AI辩论系统
## Overview
This document outlines the architecture for integrating OpenBB v4 into the Lianyaohu 稷下学宫AI辩论系统. The integration aims to provide enriched financial data to the eight immortal agents while maintaining graceful degradation when OpenBB is not installed or available.
## System Context
The Lianyaohu system is a multi-AI-agent debate platform rooted in traditional Chinese philosophy. The eight immortals (八仙) debate investment topics, leveraging data from multiple financial APIs. The system currently uses a "perpetual engine" based on 17 RapidAPI subscriptions. This architecture adds OpenBB as an optional, higher-level data source.
## Key Components and Integration Points
### 1. Core Business Logic (`src/jixia/`)
#### a. `engines/openbb_engine.py`
- **Purpose**: Primary interface to OpenBB v4 data.
- **Key Features**:
- Lazy loading of `openbb` library to prevent import errors if not installed.
- `ImmortalConfig` mapping each immortal to a primary data provider (initially `yfinance`).
- `get_immortal_data` method for agent-specific data retrieval based on specialty.
- `simulate_jixia_debate` for testing and demonstration.
- **Integration Strategy**:
- Uses `from openbb import obb` for unified routing.
- Handles different data types (price, historical, profile, news, earnings, etc.).
- Provides fallback error handling returning `APIResult` objects.
#### b. `engines/openbb_stock_data.py`
- **Purpose**: Utility functions for fetching stock and ETF data.
- **Key Features**:
- `get_stock_data` and `get_etf_data` functions.
- Lazy loading of `openbb`.
- Time window configuration.
- Data formatting utilities.
### 2. Application Entry Point (`app/`)
#### a. `tabs/openbb_tab.py`
- **Purpose**: Streamlit UI tab for visualizing market data.
- **Key Features**:
- `_check_openbb_installed` to detect availability.
- `_load_price_data` with multi-level fallback (OpenBB -> demo JSON -> synthetic data).
- KPI calculation from data.
- Interactive charting with Plotly.
- **Integration Strategy**:
- Prioritizes `obb.equity.price.historical`, falling back to `obb.etf.price.historical`.
- Handles various data frame formats and column names from different providers.
- Graceful UI degradation with informative messages.
### 3. Data Models (`src/jixia/models/`)
*(Note: This directory and specific model files were not found in the current codebase.)*
- **Purpose**: Standardized data models for financial data.
- **Proposed Implementation**:
- Define `FinancialDataPoint`, `StockQuote`, `HistoricalPrice`, etc.
- Used by both OpenBB engine and existing perpetual engine for data abstraction.
### 4. Configuration (`config/settings.py`)
- **Purpose**: Centralized configuration management.
- **Key Features**:
- No direct OpenBB configuration currently, but designed for extensibility.
- Validates environment for hybrid AI provider modes.
## Data Flow Architecture
```mermaid
graph TD
A[User Request] --> B{OpenBB Installed?}
B -- Yes --> C{OpenBB Data Available?}
C -- Yes --> D[OpenBB Engine]
C -- No --> E[Fallback to Demo/Synthetic Data]
B -- No --> E
D --> F[Format Data]
E --> F
F --> G[Return to Agent/UI]
```
1. **Agent Request**: An immortal agent requests data via `OpenBBEngine.get_immortal_data`.
2. **OpenBB Check**: The engine checks if OpenBB is available via lazy import.
3. **Data Retrieval**: If available, the engine calls the appropriate `obb.*` function.
4. **Data Processing**: The engine processes the result into a standardized `APIResult`.
5. **Fallback**: If OpenBB is not installed or the call fails, an error result is returned.
6. **UI Request**: The OpenBB tab requests data via `_load_price_data`.
7. **UI Fallback Chain**:
- Tries `obb.equity.price.historical`.
- Falls back to `obb.etf.price.historical`.
- Falls back to loading demo JSON files.
- Finally falls back to generating synthetic data.
8. **Data Formatting**: The UI formats the data for display, handling various column names and structures.
## Component Interaction Diagram
```mermaid
graph LR
A[Streamlit App] --> B[OpenBB Tab]
A --> C[Debate System]
C --> D[Immortal Agents]
D --> E[OpenBB Engine]
D --> F[Perpetual Engine]
B --> G[_load_price_data]
G --> H{OpenBB Available?}
H -- Yes --> I[OpenBB obb]
H -- No --> J[Demo/Synthetic Data]
E --> K{OpenBB Available?}
K -- Yes --> I
K -- No --> L[Error Result]
```
## Deployment Architecture
### Environment Requirements
- Python 3.8+
- Optional: `openbb>=4.1.0` (not in default requirements)
- Standard project dependencies (Streamlit, etc.)
### Configuration
- No specific OpenBB configuration required for basic `yfinance` use.
- Advanced providers (e.g., Polygon) would require provider-specific environment variables.
### Scalability and Performance
- OpenBB's provider system handles its own rate limiting and caching.
- The lazy loading approach prevents unnecessary overhead if OpenBB is not used.
- Fallback to demo/synthetic data ensures UI responsiveness.
## Failure Handling and Degradation
### OpenBB Not Installed
- `ImportError` is caught in lazy loading.
- Engine returns `APIResult(success=False, error="OpenBB not installed...")`.
- UI falls back to demo/synthetic data gracefully.
### OpenBB API Call Failure
- Exception is caught in `get_immortal_data`.
- Engine returns `APIResult(success=False, error="OpenBB call failed...")`.
- Agent can decide how to handle the failure (e.g., switch to another engine).
### UI Data Loading Failure
- Multi-level fallback ensures data is always available for visualization.
- Users are informed via UI messages if demo/synthetic data is being used.
## Monitoring and Observability
### Logging
- OpenBB engine logs data requests and responses.
- UI logs fallback events.
### Metrics
- Not currently implemented, but could track:
- OpenBB usage frequency.
- Fallback trigger rates.
- Data load times.
## Security Considerations
### API Keys
- OpenBB handles provider API keys internally.
- Standard project security practices (Doppler, no hardcoded keys) apply.
### Data Handling
- Data is processed in memory and not persisted by the OpenBB integration components.
## Future Enhancements
1. **Unified Data Model**: Create standardized data models in `src/jixia/models/` for seamless integration between OpenBB and other data sources.
2. **Provider Configuration**: Allow dynamic configuration of data providers for each immortal.
3. **Enhanced UI Components**: Add more detailed financial data visualizations and analysis tools.
4. **Debate Integration**: Directly link debate outcomes to specific data points from OpenBB.
5. **Advanced OpenBB Routes**: Integrate fundamental data, news, and alternative data sources from OpenBB.
## Conclusion
This architecture successfully integrates OpenBB v4 into the Lianyaohu system while maintaining its core principles of graceful degradation and modular design. The lazy loading approach ensures that the system remains functional and performant regardless of whether OpenBB is installed, providing a robust foundation for future enhancements.

158
modules/documentation-suite/docs/architecture/performance_optimization.md Normal file
View File

@@ -0,0 +1,158 @@
# OpenBB Integration Performance Optimization Architecture
## Overview
This document outlines the performance optimization strategies for the OpenBB integration in the 炼妖壶 (Lianyaohu) - 稷下学宫AI辩论系统. The goal is to ensure the system can handle high concurrency while maintaining low latency and optimal resource utilization.
## Asynchronous Data Architecture
### 1. Asynchronous Data Retrieval
- **Implementation**: Use Python's `asyncio` framework for non-blocking data access
- **Key Components**:
- `DataAbstractionLayer.get_quote_async()` method
- Asynchronous providers (where supported by the underlying library)
- Executor-based fallback for synchronous providers
- **Benefits**:
- Improved responsiveness for UI components
- Better resource utilization for concurrent requests
- Non-blocking operations for agent debates
### 2. Concurrent Provider Access
- **Implementation**: Parallel requests to multiple providers with first-wins semantics
- **Strategy**:
- Launch requests to all configured providers simultaneously
- Return the first successful response
- Cancel remaining requests to conserve resources
- **Benefits**:
- Reduced perceived latency
- Automatic failover without delay
- Optimal use of available bandwidth
## Caching Strategy
### 1. Multi-Level Caching
- **In-Memory LRU Cache**:
- Decorator-based caching for frequently accessed data (quotes, profiles)
- Configurable size limits to prevent memory exhaustion
- Time-to-live (TTL) settings based on data volatility
- **Shared Cache Layer** (Future):
- Redis or Memcached for distributed deployments
- Consistent cache invalidation across instances
- Support for cache warming strategies
### 2. Cache Key Design
- **Granular Keys**: Separate cache entries for different data types and time windows
- **Parameterized Keys**: Include relevant parameters (symbol, date range, provider) in cache keys
- **Versioned Keys**: Incorporate data schema version to handle model changes
### 3. Cache Invalidation
- **Time-Based Expiration**: Automatic expiration based on TTL settings
- **Event-Driven Invalidation**: Clear cache entries when underlying data sources are updated
- **Manual Invalidation**: API endpoints for cache management
## Load Balancing Mechanism
### 1. Provider Selection Algorithm
- **Priority-Based Routing**: Route requests to providers based on configured priorities
- **Health-Based Routing**: Consider provider health metrics when selecting providers
- **Round-Robin for Equal Priority**: Distribute load among providers with the same priority
### 2. Adaptive Load Distribution
- **Real-Time Monitoring**: Track response times and error rates for each provider
- **Dynamic Weight Adjustment**: Adjust provider weights based on performance metrics
- **Circuit Breaker Pattern**: Temporarily disable poorly performing providers
## Resource Management
### 1. Connection Pooling
- **HTTP Connection Reuse**: Maintain pools of HTTP connections for API clients
- **Database Connection Pooling**: Reuse database connections for cache backends
- **Provider-Specific Pools**: Separate connection pools for different data providers
### 2. Memory Management
- **Efficient Data Structures**: Use memory-efficient data structures for caching
- **Object Reuse**: Reuse objects where possible to reduce garbage collection pressure
- **Streaming Data Processing**: Process large datasets in chunks to minimize memory footprint
### 3. Thread and Process Management
- **Async-Appropriate Threading**: Use threads for I/O-bound operations that aren't natively async
- **Process Isolation**: Isolate resource-intensive operations in separate processes
- **Resource Limits**: Configure limits on concurrent threads and processes
## Monitoring and Performance Metrics
### 1. Key Performance Indicators
- **Response Time**: Measure latency for data retrieval operations
- **Throughput**: Track requests per second for different data types
- **Error Rate**: Monitor failure rates for data access operations
- **Cache Hit Ratio**: Measure effectiveness of caching strategies
### 2. Provider Performance Metrics
- **Individual Provider Metrics**: Track performance for each data provider
- **Health Status**: Monitor uptime and responsiveness of providers
- **Cost Metrics**: Track usage and costs associated with different providers
### 3. System-Level Metrics
- **Resource Utilization**: CPU, memory, and network usage
- **Concurrency Levels**: Track active requests and queue depths
- **Garbage Collection**: Monitor GC activity and its impact on performance
## Optimization Techniques
### 1. Data Pre-fetching
- **Predictive Loading**: Pre-fetch data for likely subsequent requests
- **Batch Operations**: Combine multiple requests into single batch operations where possible
- **Background Refresh**: Refresh cached data proactively before expiration
### 2. Data Compression
- **Response Compression**: Use gzip compression for API responses
- **Cache Compression**: Compress cached data to reduce memory usage
- **Efficient Serialization**: Use efficient serialization formats (e.g., Protocol Buffers, MessagePack)
### 3. Database Optimization
- **Indexing Strategy**: Create appropriate indexes for cache lookup operations
- **Query Optimization**: Optimize database queries for performance
- **Connection Management**: Efficiently manage database connections
## Scalability Considerations
### 1. Horizontal Scaling
- **Stateless Design**: Ensure data access components are stateless for easy scaling
- **Load Balancer Integration**: Work with external load balancers for traffic distribution
- **Shared Caching**: Use distributed cache for consistent data across instances
### 2. Vertical Scaling
- **Resource Allocation**: Optimize resource usage for efficient vertical scaling
- **Performance Tuning**: Tune system parameters for better performance on larger instances
- **Memory Management**: Efficiently manage memory to take advantage of larger instances
### 3. Auto-scaling
- **Metrics-Driven Scaling**: Use performance metrics to trigger auto-scaling events
- **Graceful Degradation**: Maintain functionality during scaling operations
- **Cost Optimization**: Balance performance with cost considerations
## Implementation Roadmap
### Phase 1: Core Async Implementation
- Implement `DataAbstractionLayer.get_quote_async()`
- Add async support to provider adapters where possible
- Add executor-based fallback for synchronous providers
### Phase 2: Caching Layer
- Implement in-memory LRU cache
- Add cache key design and invalidation strategies
- Integrate cache with data abstraction layer
### Phase 3: Monitoring and Metrics
- Implement data quality monitoring
- Add performance metrics collection
- Create dashboards for monitoring key metrics
### Phase 4: Advanced Optimizations
- Implement predictive pre-fetching
- Add database optimization for cache backends
- Implement distributed caching for scalability
## Conclusion
This performance optimization architecture provides a comprehensive approach to ensuring the OpenBB integration in the Lianyaohu system can handle high concurrency while maintaining optimal performance. By implementing asynchronous data access, multi-level caching, intelligent load balancing, and comprehensive monitoring, the system will be able to deliver fast, reliable financial data to the eight immortal agents even under heavy load.

130
modules/documentation-suite/docs/architecture/technical_specification.md Normal file
View File

@@ -0,0 +1,130 @@
# 炼妖壶-稷下学宫AI辩论系统 OpenBB集成文档整合
## 概述
本文档整合了"炼妖壶-稷下学宫AI辩论系统"中OpenBB集成的所有关键设计和实现文档，为开发团队提供一个全面的参考指南。
## 架构设计
### 1. 整体架构
系统采用分层架构设计，将OpenBB集成在数据访问层，通过抽象层为上层应用提供统一的数据接口。
### 2. 核心组件
- **OpenBB引擎** (`src/jixia/engines/openbb_engine.py`)：主要的数据访问接口
- **数据抽象层** (`src/jixia/engines/data_abstraction_layer.py`)：统一的数据访问接口
- **Provider适配器**：为不同数据源实现的适配器
- **数据模型** (`src/jixia/models/financial_data_models.py`)：标准化的数据结构定义
### 3. 数据流
```
[八仙智能体] -> [数据抽象层] -> [Provider适配器] -> [OpenBB引擎] -> [OpenBB库]
\-> [永动机引擎] -> [RapidAPI]
```
## 实现细节
### 1. 数据模型
定义了标准化的金融数据结构：
- `StockQuote`：股票报价
- `HistoricalPrice`：历史价格数据
- `CompanyProfile`：公司概况
- `FinancialNews`：金融新闻
### 2. 抽象接口
定义了`DataProvider`抽象基类，所有数据提供商都需要实现该接口：
- `get_quote()`：获取股票报价
- `get_historical_prices()`：获取历史价格数据
- `get_company_profile()`：获取公司概况
- `get_news()`：获取相关新闻
### 3. Provider适配器
为OpenBB和RapidAPI分别实现了适配器：
- `OpenBBDataProvider`：OpenBB数据提供商适配器
- `RapidAPIDataProvider`：RapidAPI数据提供商适配器
### 4. 八仙数据映射
定义了八仙与数据源的智能映射关系，每个八仙都有其专属的数据源和类型偏好。
## 性能优化
### 1. 异步处理
实现了异步数据访问机制，提高系统并发处理能力。
### 2. 缓存策略
采用多级缓存策略，包括内存LRU缓存和未来可扩展的分布式缓存。
### 3. 负载均衡
实现了基于优先级和健康状态的数据源选择算法。
## 测试验证
### 1. 功能测试
- Provider适配器测试
- 数据抽象层测试
- 引擎组件测试
- UI组件测试
- 集成测试
### 2. 性能测试
- 响应时间测试
- 并发访问测试
### 3. 验证标准
- 功能验证标准
- 性能验证标准
- 兼容性验证标准
## 部署架构
### 1. 环境要求
- Python 3.8+
- 可选的OpenBB库 (>=4.1.0)
### 2. 配置管理
- 通过环境变量管理配置
- 支持多种部署场景（基础部署、完整部署、混合部署）
### 3. 安全考虑
- API密钥安全管理
- 数据安全处理
- 访问控制
## 故障处理与降级
### 1. 故障转移机制
当主数据源不可用时，系统能自动切换到备用数据源。
### 2. 优雅降级
当OpenBB未安装时，系统能正常运行并使用演示数据。
## 监控与可观测性
### 1. 关键指标
- 数据源可用性
- 响应时间
- 错误率
- 缓存命中率
### 2. 告警策略
定义了多维度的告警策略，确保系统稳定性。
## 未来发展规划
### 1. 统一数据模型
创建更完善的标准化数据模型。
### 2. Provider配置
实现动态配置数据提供商。
### 3. 增强UI组件
添加更多详细的金融数据可视化和分析工具。
### 4. 辩论集成
直接将辩论结果链接到OpenBB的具体数据点。
### 5. 高级路由
集成OpenBB的更多数据源，如基本面数据、新闻和另类数据。
## 结论
通过以上架构设计和实现，OpenBB集成成功地为"炼妖壶-稷下学宫AI辩论系统"提供了丰富而可靠的金融数据支持，同时保持了系统的可扩展性和稳定性。这套集成方案不仅满足了当前需求，也为未来功能扩展奠定了坚实基础。

287
modules/documentation-suite/docs/architecture/test_validation_plan.md Normal file
View File

@@ -0,0 +1,287 @@
# 炼妖壶-稷下学宫AI辩论系统 OpenBB集成测试与验证方案
## 概述
本文档定义了"炼妖壶-稷下学宫AI辩论系统"中OpenBB集成的测试用例和验证标准，确保集成的正确性、可靠性和性能。
## 测试环境配置
### 基础环境
- Python 3.8+
- 系统依赖：如 requirements.txt 中定义
- 测试框架：pytest
### OpenBB环境变体
1. **未安装OpenBB**：测试降级机制
2. **安装OpenBB但未配置提供商**：测试基本功能
3. **完整配置OpenBB**：测试所有功能
## 测试用例
### 1. 数据抽象层测试
#### 1.1 Provider适配器测试
```python
# tests/test_provider_adapters.py
def test_openbb_provider_initialization():
"""测试OpenBB提供商适配器初始化"""
from src.jixia.engines.openbb_adapter import OpenBBDataProvider
provider = OpenBBDataProvider()
assert provider.name == "OpenBB"
assert provider.priority == 1
def test_rapidapi_provider_initialization():
"""测试RapidAPI提供商适配器初始化"""
from src.jixia.engines.rapidapi_adapter import RapidAPIDataProvider
provider = RapidAPIDataProvider()
assert provider.name == "RapidAPI"
assert provider.priority == 2
def test_provider_data_retrieval():
"""测试提供商数据检索功能"""
# 使用模拟数据测试各提供商的数据获取方法
pass
```
#### 1.2 数据抽象层管理器测试
```python
# tests/test_data_abstraction_layer.py
def test_dal_initialization():
"""测试数据抽象层初始化"""
from src.jixia.engines.data_abstraction_layer import DataAbstractionLayer
dal = DataAbstractionLayer()
# 验证提供商是否正确加载
assert len(dal.providers) >= 1
def test_dal_quote_retrieval():
"""测试数据抽象层报价获取"""
from src.jixia.engines.data_abstraction_layer import DataAbstractionLayer
dal = DataAbstractionLayer()
quote = dal.get_quote("AAPL")
# 验证返回数据结构
if quote is not None:
assert hasattr(quote, 'symbol')
assert hasattr(quote, 'price')
def test_dal_fallback_mechanism():
"""测试故障转移机制"""
# 模拟主提供商失败，验证是否能正确切换到备用提供商
pass
```
### 2. 引擎组件测试
#### 2.1 OpenBB引擎测试
```python
# tests/test_openbb_engine.py
def test_openbb_engine_initialization():
"""测试OpenBB引擎初始化"""
from src.jixia.engines.openbb_engine import OpenBBEngine
engine = OpenBBEngine()
# 验证引擎是否正确初始化
assert engine is not None
def test_openbb_engine_data_retrieval():
"""测试OpenBB引擎数据获取"""
from src.jixia.engines.openbb_engine import OpenBBEngine
engine = OpenBBEngine()
result = engine.get_immortal_data("吕洞宾", "price", "AAPL")
# 验证返回结果结构
assert hasattr(result, 'success')
if result.success:
assert result.data is not None
def test_openbb_engine_unavailable():
"""测试OpenBB不可用时的行为"""
# 通过模拟环境测试OpenBB未安装时的降级行为
pass
```
#### 2.2 永动机引擎测试
```python
# tests/test_perpetual_engine.py
def test_perpetual_engine_initialization():
"""测试永动机引擎初始化"""
from src.jixia.engines.perpetual_engine import JixiaPerpetualEngine
# 注意：需要提供有效的RapidAPI密钥进行测试
pass
def test_perpetual_engine_data_retrieval():
"""测试永动机引擎数据获取"""
pass
```
### 3. UI组件测试
#### 3.1 OpenBB标签页测试
```python
# tests/test_openbb_tab.py
def test_openbb_tab_data_loading():
"""测试OpenBB标签页数据加载"""
# 验证在不同环境下的数据加载行为
pass
def test_openbb_tab_fallback():
"""测试OpenBB标签页降级机制"""
# 验证当OpenBB不可用时是否正确显示演示数据
pass
```
### 4. 集成测试
#### 4.1 八仙智能体数据访问测试
```python
# tests/test_baxian_data_access.py
def test_immortal_data_mapping():
"""测试八仙与数据源的映射关系"""
from src.jixia.engines.baxian_data_mapping import immortal_data_mapping
# 验证所有八仙都有正确的数据源映射
assert len(immortal_data_mapping) == 8
for immortal in ['吕洞宾', '何仙姑', '张果老', '韩湘子', '汉钟离', '蓝采和', '铁拐李', '曹国舅']:
assert immortal in immortal_data_mapping
def test_immortal_data_retrieval():
"""测试八仙智能体数据获取"""
# 验证每个八仙都能通过数据抽象层获取到所需数据
pass
```
#### 4.2 端到端辩论流程测试
```python
# tests/test_debate_flow_with_openbb.py
def test_debate_with_openbb_data():
"""测试使用OpenBB数据的完整辩论流程"""
# 验证辩论系统能正确使用OpenBB提供的数据
pass
```
## 性能测试
### 1. 响应时间测试
```python
# tests/performance/test_response_time.py
def test_quote_retrieval_response_time():
"""测试报价获取响应时间"""
import time
from src.jixia.engines.data_abstraction_layer import DataAbstractionLayer
dal = DataAbstractionLayer()
start_time = time.time()
quote = dal.get_quote("AAPL")
end_time = time.time()
response_time = end_time - start_time
# 验证响应时间在可接受范围内
assert response_time < 2.0 # 假设2秒为阈值
```
### 2. 并发访问测试
```python
# tests/performance/test_concurrent_access.py
def test_concurrent_quote_retrieval():
"""测试并发报价获取"""
import asyncio
from src.jixia.engines.data_abstraction_layer import DataAbstractionLayer
async def get_quote(symbol):
dal = DataAbstractionLayer()
return await dal.get_quote_async(symbol)
async def get_multiple_quotes():
symbols = ["AAPL", "GOOGL", "MSFT", "TSLA"]
tasks = [get_quote(symbol) for symbol in symbols]
return await asyncio.gather(*tasks)
# 运行并发测试
quotes = asyncio.run(get_multiple_quotes())
# 验证所有请求都成功返回
assert len(quotes) == 4
```
## 验证标准
### 功能验证标准
1. **数据准确性**：返回的数据格式和内容符合预期
2. **故障转移**：当主数据源不可用时，系统能自动切换到备用数据源
3. **优雅降级**：当OpenBB未安装时，系统能正常运行并使用演示数据
4. **八仙映射**：每个八仙都能访问其专属的数据源和类型
### 性能验证标准
1. **响应时间**：单次数据请求响应时间不超过2秒
2. **并发处理**：系统能同时处理至少10个并发数据请求
3. **资源使用**：内存使用在合理范围内，无内存泄漏
4. **缓存效率**：缓存命中率应达到80%以上
### 兼容性验证标准
1. **Python版本**：支持Python 3.8及以上版本
2. **OpenBB版本**：支持OpenBB v4.1.0及以上版本
3. **环境变量**：正确处理各种环境变量配置
4. **依赖管理**：OpenBB作为可选依赖，不影响主系统安装
## 持续集成/持续部署(CI/CD)集成
### GitHub Actions工作流
```yaml
# .github/workflows/openbb_integration_test.yml
name: OpenBB Integration Test
on:
push:
branches: [ main, develop ]
pull_request:
branches: [ main ]
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: [3.8, 3.9, '3.10', '3.11']
openbb-installed: [true, false]
steps:
- uses: actions/checkout@v3
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v4
with:
python-version: ${{ matrix.python-version }}
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install -r requirements.txt
if [ "${{ matrix.openbb-installed }}" = "true" ]; then
pip install "openbb>=4.1.0"
fi
- name: Run tests
run: |
pytest tests/test_openbb_*.py
pytest tests/test_data_abstraction_*.py
```
## 监控和告警
### 关键指标监控
1. **数据源可用性**：监控各数据提供商的可用性
2. **响应时间**：监控数据请求的平均响应时间
3. **错误率**：监控数据访问的错误率
4. **缓存命中率**：监控缓存的使用效率
### 告警策略
1. **可用性告警**：当数据源可用性低于95%时触发告警
2. **性能告警**：当平均响应时间超过阈值时触发告警
3. **错误率告警**：当错误率超过1%时触发告警
4. **缓存告警**：当缓存命中率低于70%时触发告警
## 结论
这套测试和验证方案确保了OpenBB集成的高质量交付，通过全面的功能测试、性能测试和持续集成，能够及时发现和修复潜在问题，保证系统的稳定性和可靠性。

19
modules/documentation-suite/docs/baxian_debate_order_guide.md Normal file
View File

@@ -0,0 +1,19 @@
# 八仙辩论次序指南 (Baxian Debate Order Guide)
## 核心原则
辩论次序基于“对立统一”的哲学思想，将八仙分为四组，每组代表一对核心矛盾。此规则为项目级最终版本，作为后续所有相关实现的基准。
## 分组
1. **乾坤 / 男女:** 吕洞宾 (乾/男) vs 何仙姑 (坤/女)
* **逻辑:** 阳与阴，男与女的基本对立。
2. **老少:** 张果老 vs 韩湘子
* **逻辑:** 年长与年少，经验与活力的对立。
3. **贫富:** 汉钟离 vs 蓝采和
* **逻辑:** 富贵与贫穷，物质与精神的对立。汉钟离出身将门，而蓝采和的形象通常是贫穷的歌者。
4. **贵贱:** 曹国舅 vs 铁拐李
* **逻辑:** 皇亲国戚与街头乞丐，社会地位的极端对立。

87
modules/documentation-suite/docs/cloudflare_memory_banks.md Normal file
View File

@@ -0,0 +1,87 @@
# 八仙记忆银行文档 (Cloudflare AutoRAG)
每个八仙智能体都有一个专属的记忆空间，用于存储其在不同辩论主题下的记忆。这些记忆通过Cloudflare Vectorize进行向量索引，并利用Workers AI进行语义检索。
## 记忆类型
1. **对话记忆 (conversation)**: 智能体在特定辩论中的发言和互动记录。
2. **偏好记忆 (preference)**: 智能体的投资偏好、分析方法和决策倾向。
3. **知识记忆 (knowledge)**: 智能体掌握的金融知识、市场信息和分析模型。
4. **策略记忆 (strategy)**: 智能体在辩论中使用的论证策略和战术。
## 八仙记忆空间列表
- **铁拐李 (tieguaili)**
- 标识符: `cf_memory_tieguaili`
- 特点: 擅长技术分析和风险控制
- **汉钟离 (hanzhongli)**
- 标识符: `cf_memory_hanzhongli`
- 特点: 注重基本面分析和长期价值
- **张果老 (zhangguolao)**
- 标识符: `cf_memory_zhangguolao`
- 特点: 擅长宏观趋势分析和周期判断
- **蓝采和 (lancaihe)**
- 标识符: `cf_memory_lancaihe`
- 特点: 关注市场情绪和资金流向
- **何仙姑 (hexiangu)**
- 标识符: `cf_memory_hexiangu`
- 特点: 精于财务数据分析和估值模型
- **吕洞宾 (lvdongbin)**
- 标识符: `cf_memory_lvdongbin`
- 特点: 善于多维度综合分析和创新策略
- **韩湘子 (hanxiangzi)**
- 标识符: `cf_memory_hanxiangzi`
- 特点: 擅长行业比较和相对价值分析
- **曹国舅 (caoguojiu)**
- 标识符: `cf_memory_caoguojiu`
- 特点: 注重合规性、社会责任和ESG因素
## 使用方法
```python
from src.jixia.memory.factory import get_memory_backend
# 获取记忆后端 (自动根据环境变量选择)
memory_bank = get_memory_backend(prefer="cloudflare")
# 为吕洞宾添加偏好记忆
await memory_bank.add_memory(
agent_name="lvdongbin",
content="倾向于使用DCF模型评估科技股的内在价值",
memory_type="preference",
debate_topic="TSLA投资分析"
)
# 搜索吕洞宾关于TSLA的记忆
memories = await memory_bank.search_memories(
agent_name="lvdongbin",
query="TSLA",
memory_type="preference"
)
# 获取上下文
context = await memory_bank.get_agent_context("lvdongbin", "TSLA投资分析")
```
## Cloudflare配置说明
要使用Cloudflare AutoRAG作为记忆后端，需要配置以下环境变量：
- `CLOUDFLARE_ACCOUNT_ID`: Cloudflare账户ID
- `CLOUDFLARE_API_TOKEN`: Cloudflare API令牌 (需要Vectorize和Workers AI权限)
- `JIXIA_MEMORY_BACKEND`: 设置为 `cloudflare`
系统默认使用以下配置：
- Vectorize索引: `autorag-shy-cherry-f1fb`
- 嵌入模型: `@cf/baai/bge-m3`
- AutoRAG域名: `autorag.seekkey.tech`
---
*此文档由系统自动生成和维护*

162
modules/documentation-suite/docs/custom_modules_tutorial.md Normal file
View File

@@ -0,0 +1,162 @@
# Developer Tutorial: Creating Custom Modules
Welcome, contributor! This guide will show you how to extend the "太公心易" system by creating your own custom `MythologyEngine` and `CycleModel`.
The system is built on the principle of decoupling, using Abstract Base Classes (ABCs) to separate the core logic of the `MarketFSM` from the specific cultural or analytical models it uses. By creating new classes that inherit from these ABCs, you can fundamentally change the system's narrative and analytical framework without touching the core FSM logic.
## Part 1: Creating a Custom Mythology Engine
A `MythologyEngine` is responsible for providing the narrative flavor to the system. It maps technical components to mythological figures and processes. Let's create a `GreekMythologyEngine` as an example.
### Step 1: Create a New Python File
Create a new file, for example, `greek_mythology.py`.
### Step 2: Import the `MythologyEngine` ABC
In your new file, import the abstract base class from `mythology.py`:
```python
# greek_mythology.py
from mythology import MythologyEngine
```
### Step 3: Implement the `MythologyEngine` Interface
Create a new class that inherits from `MythologyEngine` and implements all its abstract methods: `get_actor_name`, `get_process_metaphor`, and `get_system_narrative`.
```python
class GreekMythologyEngine(MythologyEngine):
"""
An implementation of the MythologyEngine based on Greek mythology.
"""
def __init__(self):
self._actor_map = {
'collector': 'The Muses',
'refiner': 'Hephaestus',
'verifier': 'Apollo',
'synthesizer': 'Zeus',
}
self._process_map = {
'multi_agent_debate': 'Symposium',
'refinement_process': 'Forging in Aetna',
'external_verification': 'Consulting the Oracle of Delphi',
'final_decision': 'Judgment from Olympus',
}
self._narrative = "This system views the market as a pantheon of competing gods and heroes, striving for dominance on Mount Olympus."
def get_actor_name(self, component: str) -> str:
return self._actor_map.get(component, "An Unknown Titan")
def get_process_metaphor(self, process: str) -> str:
return self._process_map.get(process, "A Herculean Task")
def get_system_narrative(self) -> str:
return self._narrative
```
### Step 4: Integrate with the FSM
Now, you can instantiate your new engine and inject it into the `MarketFSM`. The FSM will work seamlessly with your new narrative layer.
```python
# In your main application file
from market_fsm import MarketFSM
from greek_mythology import GreekMythologyEngine
from cycle_models import TwelveStagesOfLifeCycleModel # We can reuse the old cycle model
# Instantiate your custom engine
greek_engine = GreekMythologyEngine()
cycle_model = TwelveStagesOfLifeCycleModel()
# Inject it into the FSM
fsm = MarketFSM(
mythology_engine=greek_engine,
cycle_model=cycle_model
)
# Run the analysis
fsm.run_analysis({"mock_score": 8})
# The output will now be framed in the language of Greek mythology!
```
## Part 2: Creating a Custom Cycle Model
A `CycleModel` is responsible for analyzing market data and determining the current stage of a given cycle. Let's create a simple `MarketSentimentCycleModel` based on four stages: Greed, Fear, Hope, and Despair.
### Step 1: Create a New Python File
Create a file named `sentiment_cycle.py`.
### Step 2: Import the `CycleModel` ABC
```python
# sentiment_cycle.py
from cycle_models import CycleModel
from typing import Dict, Any, List
```
### Step 3: Implement the `CycleModel` Interface
Create a new class that inherits from `CycleModel` and implements `get_current_stage`, `get_stage_characteristics`, and `get_all_stages`.
```python
class MarketSentimentCycleModel(CycleModel):
"""
A cycle model based on the four stages of market sentiment.
"""
def __init__(self):
self._stages = ["Hope", "Greed", "Fear", "Despair"]
self._characteristics = {
"Hope": {"description": "The market is cautiously optimistic.", "strategy": "Accumulate"},
"Greed": {"description": "Euphoria and high expectations dominate.", "strategy": "Take profits"},
"Fear": {"description": "Panic and uncertainty are widespread.", "strategy": "Reduce risk"},
"Despair": {"description": "Capitulation, the market has given up hope.", "strategy": "Look for bargains"},
}
def get_current_stage(self, data: Dict[str, Any]) -> str:
# A real implementation would analyze news sentiment, VIX, etc.
# Here, we'll use a mock sentiment score from 0 to 1.
sentiment_score = data.get("sentiment", 0.5)
if sentiment_score > 0.75:
return "Greed"
elif sentiment_score > 0.5:
return "Hope"
elif sentiment_score > 0.25:
return "Fear"
else:
return "Despair"
def get_stage_characteristics(self, stage: str) -> Dict[str, Any]:
return self._characteristics.get(stage, {})
def get_all_stages(self) -> List[str]:
return self._stages
```
### Step 4: Integrate with the FSM
You can now use your new cycle model in the FSM, even combining it with a different mythology engine.
```python
# In your main application file
from market_fsm import MarketFSM
from mythology import DaoistMythologyEngine
from sentiment_cycle import MarketSentimentCycleModel
# Instantiate your custom cycle model
sentiment_model = MarketSentimentCycleModel()
daoist_engine = DaoistMythologyEngine()
# Inject it into the FSM
fsm = MarketFSM(
mythology_engine=daoist_engine,
cycle_model=sentiment_model
)
# Run the analysis with data your new model understands
fsm.run_analysis({"sentiment": 0.2})
# The FSM will now report the market is in a state of "Despair".
```
Congratulations! You have successfully extended the "太公心易" system.

100
modules/documentation-suite/docs/development/CANARY_DEV_BETA_DEPLOYMENT.md Normal file
View File

@@ -0,0 +1,100 @@
# 金丝雀/开发/测试部署策略
## 环境命名
根据新的命名约定，三个环境重新命名为：
- **canary** (金丝雀环境): `https://gitea.tailnet-68f9.ts.net/gitea/liurenchaxin.git`
- **dev** (开发环境): `git@bitbucket.org:capitaltrain/liurenchaxin.git`
- **beta** (测试环境): `https://github.com/jingminzhang/taigongxinyi.git`
## 环境用途
- **canary (金丝雀)**: 最新功能测试，早期验证
- **dev (开发)**: 功能开发和集成测试
- **beta (测试)**: 预发布测试，用户验收
## 部署流程
### 1. 日常开发流程
```bash
# 在 canary 环境开发新功能
git checkout main
git pull canary main
# 开发完成后
git add .
git commit -m "feat: 新功能描述"
git push canary main
```
### 2. 集成测试流程
```bash
# 将功能从 canary 推送到 dev 环境
git checkout main
git pull dev main
git merge main
git push dev main
```
### 3. 预发布流程
```bash
# 将功能从 dev 推送到 beta 环境
git checkout main
git pull beta main
git merge main
git push beta main
```
## 快速命令
### 发布新版本
```bash
# 金丝雀环境发布
./scripts/quick-release.sh 1.2.3 canary
# 开发环境发布
./scripts/quick-release.sh 1.2.3 dev
# 测试环境发布
./scripts/quick-release.sh 1.2.3 beta
```
### 回滚操作
```bash
# 回滚金丝雀环境
./scripts/rollback.sh canary 1.2.2
# 回滚开发环境
./scripts/rollback.sh dev 1.2.2
# 回滚测试环境
./scripts/rollback.sh beta 1.2.2
```
### 状态检查
```bash
./scripts/check-status.sh
```
## 分支策略
- **main**: 所有环境统一使用main分支
## 标签命名
- 金丝雀: `v1.2.3-canary`
- 开发: `v1.2.3-dev`
- 测试: `v1.2.3-beta`
## 优势
1. **清晰的命名**: canary/dev/beta 更符合行业标准
2. **渐进发布**: 从金丝雀到测试的渐进式验证
3. **快速回滚**: 每个环境都可以独立回滚
4. **隔离性好**: 不同环境完全隔离，减少干扰

196
modules/documentation-suite/docs/development/DEPLOYMENT_FLOW.md Normal file
View File

@@ -0,0 +1,196 @@
# 六壬神鉴渐进发布流程图
## 🎯 发布流程概览
```
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Development │ │ Staging │ │ Canary │ │ Production │
│ (Gitea) │───▶│ (Bitbucket) │───▶│ (GitHub 10%) │───▶│ (GitHub 100%) │
│ develop分支 │ │ staging分支 │ │ main分支 │ │ main分支 │
└─────────────────┘ └──────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │ │
│ │ │ │
▼ ▼ ▼ ▼
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 功能开发 │ │ 集成测试 │ │ 灰度验证 │ │ 全量发布 │
│ 单元测试 │ │ 性能测试 │ │ 监控验证 │ │ 持续监控 │
│ 代码审查 │ │ 安全扫描 │ │ 用户反馈 │ │ 性能优化 │
└─────────────────┘ └──────────────────┘ └─────────────────┘ └─────────────────┘
```
## 🚀 快速操作指南
### 1. 日常开发流程
#### 开始新功能开发
```bash
# 从 develop 分支创建功能分支
git checkout develop
git pull origin develop
git checkout -b feature/new-feature
# 开发完成后
git add .
git commit -m "feat: 添加新功能"
git push origin feature/new-feature
# 创建 PR 到 develop 分支
# 在 Gitea 上创建 Pull Request
```
#### 推送到开发环境
```bash
# 一键推送到 Gitea 开发环境
git checkout develop
git pull origin develop
git merge feature/new-feature
git push gitea develop
```
### 2. 预发布流程
#### 准备 staging 发布
```bash
# 创建发布分支
git checkout staging
git merge develop
git push staging staging:main
# 或使用快捷命令
git deploy-staging
```
#### 验证 staging 环境
```bash
# 检查 staging 状态
./scripts/check-status.sh
```
### 3. 灰度发布流程
#### 启动灰度发布
```bash
# 创建灰度版本
git checkout main
git merge staging
git tag v1.2.0-canary
git push origin main --tags
```
#### 监控灰度状态
```bash
# 检查发布状态
curl -s https://api.github.com/repos/jingminzhang/taigongxinyi/releases/latest
```
### 4. 全量发布流程
#### 正式版本发布
```bash
# 使用快速发布脚本
./scripts/quick-release.sh 1.2.0 prod
# 或手动操作
git checkout main
git tag v1.2.0
git push origin main --tags
git deploy-prod
```
## 📊 发布检查清单
### 开发阶段检查
- [ ] 代码通过单元测试
- [ ] 功能测试完成
- [ ] 代码审查通过
- [ ] 文档已更新
### Staging 阶段检查
- [ ] 集成测试通过
- [ ] 性能测试完成
- [ ] 安全扫描通过
- [ ] 用户验收测试完成
### 灰度发布检查
- [ ] 监控指标正常
- [ ] 错误率 < 0.1%
- [ ] 用户反馈良好
- [ ] 业务指标稳定
### 全量发布检查
- [ ] 灰度验证通过
- [ ] 回滚方案就绪
- [ ] 监控告警配置
- [ ] 紧急联系清单
## 🔄 回滚操作
### 紧急回滚
```bash
# 快速回滚到指定版本
./scripts/rollback.sh prod 1.1.9
# 或手动回滚
git checkout v1.1.9
git tag v1.2.0-rollback
git push origin main --force
```
### 回滚验证
```bash
# 检查回滚状态
./scripts/check-status.sh
```
## 📈 监控面板
### 关键指标监控
- **系统性能**: CPU、内存、磁盘使用率
- **应用性能**: 响应时间、吞吐量、错误率
- **业务指标**: 用户活跃度、功能使用率
### 告警规则
- 错误率 > 1% → 立即告警
- 响应时间 > 1s → 立即告警
- 服务不可用 → 立即告警
## 🛠️ 工具命令速查
| 操作 | 命令 | 说明 |
|------|------|------|
| 查看状态 | `./scripts/check-status.sh` | 检查所有环境状态 |
| 快速发布 | `./scripts/quick-release.sh 版本号 环境` | 一键发布到指定环境 |
| 紧急回滚 | `./scripts/rollback.sh 环境 版本号` | 快速回滚到指定版本 |
| 推送到 staging | `git deploy-staging` | 推送到 Bitbucket staging |
| 推送到 prod | `git deploy-prod` | 推送到 GitHub production |
| 同步所有远程 | `git sync-all` | 同步所有远程仓库 |
## 📞 紧急联系
| 角色 | 联系方式 | 职责 |
|------|----------|------|
| 技术负责人 | ben@capitaltrain.cn | 技术决策、紧急响应 |
| 运维团队 | ops@capitaltrain.cn | 部署、监控、故障处理 |
| 产品团队 | product@capitaltrain.cn | 业务决策、用户沟通 |
## 🎓 最佳实践
### 1. 分支管理
- 功能分支从 `develop` 创建
- 发布分支从 `staging` 创建
- 热修复分支从 `main` 创建
### 2. 版本命名
- 主版本: 不兼容的重大更新
- 次版本: 向后兼容的功能添加
- 修订版本: bug修复和微小改进
### 3. 发布频率
- 紧急修复: 随时发布
- 常规更新: 每2周一次
- 大版本更新: 每季度一次
### 4. 监控策略
- 灰度期间: 24-48小时密切监控
- 全量发布: 72小时持续监控
- 日常运维: 实时告警监控

114
modules/documentation-suite/docs/development/GAMEFI_FSM_INTEGRATION_PLAN.md Normal file
View File

@@ -0,0 +1,114 @@
# 方案：GameFi“盘下特征”量化及FSM状态转移集成
**制定者:** Gemini
**日期:** 2025-08-21
**目标:** 将`GAMEFI_SYSTEM_SUMMARY.md`中定义的“交易者心境”和“十二长生”（四季轮回）概念，转化为可量化的数据模型，并将其作为“太公心易”FSM系统状态转移的核心驱动条件。
---
## 1. 核心思想
交易者的心境、经验和偏见是驱动其市场行为的“盘下特征”。通过量化这些特征，我们可以让主FSM的决策更具个性化和前瞻性。当检测到交易者进入特定的心理阶段（如“秋季失道”）或表现出强烈的偏见（如“趋势醉”）时，FSM可以主动进入相应状态（如`Refine`或`Validation`）进行干预和辅助。
## 2. “盘下特征”量化方案
我们将构建一个**“交易者状态向量”（Trader State Vector, TSV）**来统一描述交易者的当前心境。该向量由以下三组量化指标构成：
### 2.1. **伤疤资本 (Scar Capital)** - 经验与教训的量化
基于`TradingScar`概念，我们将从交易历史中计算以下指标：
* **总痛苦值 (TotalPain):** 所有`TradingScar`的`pain_level`之和。反映交易者经历的总挫折。
* **平均智慧 (AverageWisdom):** 所有`wisdom_gained`的平均值。反映交易者从错误中学习的能力。
* **伤疤密度 (ScarDensity):** 单位时间（如每季度）内产生的`TradingScar`数量。高密度可能意味着鲁莽或市场环境恶化。
* **恢复能力 (Resilience):** 从重大亏损（高`pain_level`的`Scar`）后，恢复盈利所需的时间。
### 2.2. **偏见画像 (Bias Profile)** - “醉八仙”的量化
通过分析交易行为，为每个交易者生成一个包含八种偏见得分（0到1之间）的画像：
* **趋势醉 (蓝采和):** 在价格接近阶段性高点时买入的频率和资金比例。
* **价值醉 (汉钟离):** 在亏损头寸上持续加仓（“补仓”）的行为频率。
* **消息醉 (曹国舅):** 在重大新闻或财报发布窗口期内，交易频率显著上升。
* **经验醉 (张果老):** 策略的同质性过高，例如只交易特定几只股票或只使用单一指标。
* **技术醉 (韩湘子):** 交易行为与特定技术指标（如MACD金叉/死叉）的强相关性。
* **保守醉 (何仙姑):** 空仓时间占比过高，或在明显上涨趋势中过早卖出。
* **逆向醉 (铁拐李):** 在市场普遍下跌时买入，或在普遍上涨时卖出的频率。
* **理性醉 (吕洞宾):** 交易频率极低，可能错失过多机会（机会成本）。
### 2.3. **修仙阶段 (Journey Stage)** - “猴王四季”的量化
结合**伤疤资本**和**偏见画像**，我们可以为交易者划分出当前的“修仙”阶段：
* **春季·觉醒 (Awakening):**
* `TotalPain`较低，`ScarDensity`较低。
* `AverageWisdom`较高（学习意愿强）。
* 偏见画像尚未固化。
* **夏季·得道 (Attainment):**
* 交易胜率高，账户稳定增长。
* `AverageWisdom`可能开始下降（过度自信）。
* 某几种偏见得分开始显著升高。
* **秋季·失道 (Loss):**
* 出现一次或多次高`pain_level`的`Scar`。
* `TotalPain`急剧上升，`Resilience`指标被考验。
* 高偏见得分与重大亏损有强相关性。
* **冬季·悟道 (Enlightenment):**
* `Resilience`高，能够从亏损中快速恢复。
* 整体偏见画像得分较低且均衡。
* `AverageWisdom`稳定在较高水平。
## 3. FSM状态转移集成方案
“交易者状态向量”（TSV）将被整合到“太公心易”FSM的上下文中，作为状态转移的核心判断依据。
### 3.1. 触发条件示例
FSM不再仅仅响应外部市场事件，更会主动响应交易者的内在状态变化。
* **进入`Refine`状态（太上老君整理）:**
* **触发器:** 检测到交易者进入“秋季·失道”阶段。
* **条件:** `IF trader.stage == 'Loss' AND trader.bias_profile['TrendChasing'] > 0.8`
* **目的:** 交易者因强烈的趋势偏见而遭受重创，FSM需要启动`Refine`流程，帮助其“祛魅”并重构策略。
* **进入`Validation`状态（内部验证/祛魅）:**
* **触发器:** 交易者处于“夏季·得道”阶段，表现出过度自信。
* **条件:** `IF trader.stage == 'Attainment' AND trader.AverageWisdom < threshold`
* **目的:** 在交易者最容易忽视风险时，FSM主动进入`Validation`状态，对其当前的策略进行压力测试和一致性检查。
* **进入`ExternalFetch`状态（灵宝道君核查）:**
* **触发器:** “消息醉”交易者准备进行一笔交易。
* **条件:** `IF trader.bias_profile['NewsTrading'] > 0.7 AND event == 'pre_trade_check'`
* **目的:** 在该交易者依据消息行动前，FSM强制启动`ExternalFetch`，从多个独立信源交叉验证该消息的可靠性。
### 3.2. 状态转移逻辑 (伪代码)
```python
class EnhancedTaigongFSM:
def __init__(self, trader_state_vector):
self.tsv = trader_state_vector
# ... other FSM initializations
def determine_next_state(self, market_event):
# 优先处理由交易者内在状态触发的转移
if self.tsv.stage == 'Loss':
# 如果交易者遭受重创，无论市场如何，优先帮助其反思
return FSMState.REFINE
if self.tsv.is_overconfident():
# 如果交易者过度自信，主动进行风险检查
return FSMState.VALIDATION
# ... 再处理由外部市场事件触发的转移
if market_event == 'HighVolatility':
return FSMState.COLLECTING
return self.current_state
```
## 4. 实施步骤
1. **数据建模:** 在代码中定义`TradingScar`, `BiasProfile`, 和 `TraderStateVector`的类结构。
2. **分析模块开发:** 创建一个分析器，能够接收交易历史数据，并计算出完整的TSV。
3. **FSM上下文集成:** 将TSV对象添加到`TaigongXinyiFSM`的上下文中。
4. **规则引擎实现:** 在FSM的`transition`逻辑中，实现基于TSV的动态状态转移规则。
5. **模拟与回测:** 构建一个模拟环境，使用历史交易数据回测该集成系统的有效性，验证其是否能在关键时刻做出正确的状态转移。

225
modules/documentation-suite/docs/development/GRADUAL_DEPLOYMENT_PLAN.md Normal file
View File

@@ -0,0 +1,225 @@
# 六壬神鉴渐进发布计划
## 概述
本计划基于当前的多环境 Git 配置，实现从开发到生产的渐进式发布流程。
## 环境架构
### 当前配置
- **GitHub** (production): `https://github.com/jingminzhang/taigongxinyi.git`
- **Bitbucket** (staging): `git@bitbucket.org:capitaltrain/liurenchaxin.git`
- **Gitea** (development): `https://gitea.tailnet-68f9.ts.net/gitea/liurenchaxin.git`
### 分支策略
```
main (生产环境)
├── staging (预发布环境)
├── develop (开发环境)
└── feature/* (功能分支)
```
## 渐进发布阶段
### 阶段1：功能开发 (Development)
**目标环境**: Gitea (development)
**分支**: `feature/*` → `develop`
#### 流程
1. 从 `develop` 分支创建功能分支
2. 在功能分支上进行开发
3. 完成功能后合并到 `develop`
4. 推送到 Gitea 进行初步测试
#### 验证清单
- [ ] 单元测试通过
- [ ] 代码审查完成
- [ ] 功能测试通过
- [ ] 文档更新完成
### 阶段2：集成测试 (Staging)
**目标环境**: Bitbucket (staging)
**分支**: `develop` → `staging`
#### 流程
1. 从 `develop` 分支创建发布分支 `release/vX.Y.Z`
2. 在 staging 环境部署测试
3. 进行集成测试和用户验收测试
4. 修复发现的问题
5. 合并到 `staging` 分支
6. 推送到 Bitbucket staging 环境
#### 验证清单
- [ ] 集成测试通过
- [ ] 性能测试通过
- [ ] 安全扫描通过
- [ ] 用户验收测试完成
- [ ] 回滚方案准备就绪
### 阶段3：灰度发布 (Canary)
**目标环境**: GitHub production (10%流量)
**分支**: `staging` → `main`
#### 流程
1. 创建灰度发布标签 `vX.Y.Z-canary`
2. 部署到生产环境 10% 流量
3. 监控关键指标 24-48小时
4. 根据监控结果决定全量发布或回滚
#### 监控指标
- [ ] 错误率 < 0.1%
- [ ] 响应时间 < 500ms
- [ ] 用户满意度 > 95%
- [ ] 业务指标正常
### 阶段4：全量发布 (Production)
**目标环境**: GitHub production (100%流量)
**分支**: `main`
#### 流程
1. 创建正式版本标签 `vX.Y.Z`
2. 全量部署到生产环境
3. 持续监控 72小时
4. 准备热修复方案
## 发布策略
### 版本命名规范
- **主版本** (X.0.0): 重大功能更新或不兼容变更
- **次版本** (X.Y.0): 新功能添加，向后兼容
- **修订版本** (X.Y.Z): bug修复或小改进
### 发布频率
- **紧急修复**: 随时发布
- **常规更新**: 每2周一次
- **大版本更新**: 每季度一次
### 回滚策略
```bash
# 快速回滚到上一个版本
git revert HEAD
git push origin main --force
# 或使用标签回滚
git checkout vX.Y.Z-1
git tag -a vX.Y.Z-rollback -m "Rollback to vX.Y.Z-1"
git push origin vX.Y.Z-rollback
```
## 自动化工具
### Git 钩子配置
在 `.git/hooks/` 目录下创建以下钩子：
#### pre-push
```bash
#!/bin/bash
# 检查测试是否通过
pytest tests/
if [ $? -ne 0 ]; then
echo "测试未通过，禁止推送"
exit 1
fi
```
#### pre-commit
```bash
#!/bin/bash
# 代码格式检查
black --check .
flake8 .
```
### CI/CD 配置
创建 `.github/workflows/deploy.yml`：
```yaml
name: Gradual Deployment
on:
push:
branches: [staging, main]
release:
types: [published]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Run tests
run: |
python -m pytest tests/
deploy-staging:
needs: test
if: github.ref == 'refs/heads/staging'
runs-on: ubuntu-latest
steps:
- name: Deploy to staging
run: echo "Deploying to staging..."
deploy-production:
needs: test
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
steps:
- name: Deploy to production
run: echo "Deploying to production..."
```
## 监控和告警
### 关键指标
- **系统指标**: CPU、内存、磁盘使用率
- **应用指标**: 响应时间、错误率、吞吐量
- **业务指标**: 用户活跃度、功能使用率
### 告警规则
- 错误率 > 1% 触发告警
- 响应时间 > 1秒 触发告警
- 服务不可用 立即告警
## 发布检查清单
### 发布前检查
- [ ] 所有测试通过
- [ ] 代码审查完成
- [ ] 文档已更新
- [ ] 数据库迁移脚本准备就绪
- [ ] 回滚方案已验证
### 发布后检查
- [ ] 服务正常启动
- [ ] 关键功能验证
- [ ] 监控数据正常
- [ ] 用户反馈收集
- [ ] 性能指标对比
## 紧急响应
### 故障处理流程
1. **发现故障** → 立即评估影响范围
2. **5分钟内** → 决定是否回滚
3. **10分钟内** → 执行回滚操作
4. **30分钟内** → 修复问题并验证
5. **1小时内** → 重新发布
### 联系方式
- 技术负责人: ben@capitaltrain.cn
- 运维团队: ops@capitaltrain.cn
- 紧急热线: [待填写]
## 持续改进
### 发布回顾
每次发布后一周内进行回顾会议：
- 分析发布过程中的问题
- 收集用户反馈
- 更新发布流程
- 优化监控指标
### 自动化改进
- 逐步增加自动化测试覆盖率
- 完善监控和告警系统
- 优化部署脚本
- 建立自动化回滚机制

136
modules/documentation-suite/docs/development/MIGRATION_STATUS.md Normal file
View File

@@ -0,0 +1,136 @@
# 稷下学宫 Google ADK 迁移状态报告
## 📊 迁移进度概览
### ✅ 已完成的任务
#### 1. 基础设施迁移
- [x] **Google ADK 安装**: 成功安装 Google ADK 1.10.0
- [x] **API 密钥配置**: 已在 Doppler 中配置 `GOOGLE_API_KEY`
- [x] **环境验证**: 基础测试通过，智能体创建成功
#### 2. 配置系统更新
- [x] **settings.py 增强**:
- 新增 `get_google_api_key()` 函数
- 新增 `get_google_genai_config()` 函数
- 更新 `validate_config()` 支持三种模式：
- `openrouter`: 纯 OpenRouter 模式
- `google_adk`: 纯 Google ADK 模式
- `hybrid`: 混合模式（当前使用）
#### 3. 测试系统建立
- [x] **基础测试**: `test_google_adk.py` - 验证 ADK 安装和配置
- [x] **智能体测试**: `adk_debate_test.py` - 八仙智能体创建测试
- [x] **论道原型**: `adk_simple_debate.py` - 智能体基础功能验证
#### 4. 文档更新
- [x] **README.md**: 新增 Google ADK 安装和配置说明
- [x] **requirements.txt**: 添加 Google ADK 依赖说明
- [x] **迁移指南**: 完整的 `GOOGLE_ADK_MIGRATION_GUIDE.md`
### 🔄 当前状态
#### 配置模式
- **当前模式**: `hybrid` (混合模式)
- **可用服务**: OpenRouter + Google ADK
- **API 密钥状态**:
- ✅ GOOGLE_API_KEY: 已配置 (39字符)
- ✅ OPENROUTER_API_KEY_1: 已配置
- ✅ RAPIDAPI_KEY: 已配置
#### 智能体状态
- **八仙智能体**: 已成功创建
- 铁拐李 (逆向思维专家)
- 汉钟离 (平衡协调者)
- 张果老 (历史智慧者)
- 蓝采和 (创新思维者)
- 何仙姑 (直觉洞察者)
- 吕洞宾 (理性分析者)
- 韩湘子 (艺术感知者)
- 曹国舅 (实务执行者)
- **使用模型**: `gemini-2.0-flash-exp`
### 🚧 待完成的任务
#### 1. 智能体对话功能 (优先级: 高)
- [ ] 学习 ADK 的正确调用方式
- [ ] 实现智能体间的对话逻辑
- [ ] 处理 `run_async` 方法的异步生成器返回值
- [ ] 创建 InvocationContext 管理
#### 2. 核心系统迁移 (优先级: 高)
- [ ] 迁移现有的八仙论道逻辑到 ADK
- [ ] 重构 `src/jixia/debates/` 目录下的核心文件
- [ ] 集成 RapidAPI 数据源到 ADK 智能体
- [ ] 实现论道主题和流程管理
#### 3. 界面集成 (优先级: 中)
- [ ] 更新 Streamlit 界面以支持 ADK
- [ ] 修改 `src/streamlit_app.py`
- [ ] 适配新的智能体调用方式
- [ ] 保持现有的用户体验
#### 4. 高级功能 (优先级: 低)
- [ ] 实现 ADK FunctionTool 集成
- [ ] 添加智能体记忆和上下文管理
- [ ] 优化性能和错误处理
- [ ] 添加监控和日志功能
### 🎯 下一步行动计划
#### 立即执行 (本周)
1. **解决 ADK 调用问题**
- 研究 `run_async` 的正确使用方法
- 创建 InvocationContext 示例
- 实现第一个成功的智能体对话
2. **创建工作原型**
- 实现铁拐李和吕洞宾的简单对话
- 验证论道逻辑的可行性
- 测试多轮对话功能
#### 短期目标 (本月)
1. **完成核心迁移**
- 迁移所有八仙智能体
- 实现完整的论道流程
- 集成现有数据源
2. **界面适配**
- 更新 Streamlit 应用
- 保持功能完整性
- 优化用户体验
### 📈 技术优势
#### Google ADK 带来的改进
1. **统一模型生态**: 直接使用 Gemini 系列模型
2. **官方支持**: Google 官方维护的框架
3. **更好的集成**: 与 Google 服务深度集成
4. **开发工具**: `adk web`, `adk run`, `adk api_server`
5. **性能优化**: 原生支持异步和流式处理
#### 保留的核心价值
1. **稷下学宫哲学框架**: 完全保留
2. **八仙角色设定**: 无缝迁移
3. **RapidAPI 数据源**: 继续使用
4. **MongoDB 数据库**: 保持不变
5. **Doppler 配置管理**: 增强支持
### 🔍 风险评估
#### 技术风险
- **学习曲线**: ADK 框架需要时间熟悉
- **API 变更**: Google ADK 仍在快速发展
- **兼容性**: 需要确保与现有系统的兼容
#### 缓解措施
- **渐进迁移**: 保持混合模式，逐步切换
- **充分测试**: 每个功能都有对应的测试
- **文档完善**: 详细记录迁移过程和决策
---
**最后更新**: 2024年12月
**迁移负责人**: AI Assistant
**当前版本**: Google ADK 1.10.0
**项目状态**: 🟡 进行中 (基础设施完成，核心功能开发中)

197
modules/documentation-suite/docs/development/RELEASE_v2.0.0.md Normal file
View File

@@ -0,0 +1,197 @@
# 🚀 太公心易 v2.0.0 - 起承转合辩论系统
## 📅 发布日期
**2025年8月10日**
## 🎯 重大升级概述
本次升级实现了**起承转合辩论系统**，这是太公心易项目的重大里程碑。系统从简单的群聊升级为具有完整辩论流程的多阶段辩论架构。
## ✨ 新功能特性
### 🎭 起承转合辩论架构
#### **起：八仙按先天八卦顺序**
- 实现八仙按先天八卦顺序的辩论发言
- 每个仙人从自己的卦位角度阐述观点
- 建立多维度的论证基础
#### **承：雁阵式承接**
- 正方1234，反方1234的雁阵式承接
- 总体阐述 + 间或夹枪带棒出言讥讽
- 深化己方论点，削弱对方立场
#### **转：自由辩论（36次handoff）**
- 实现36次发言权转移的自由辩论
- 优先级算法决定发言顺序
- 激烈交锋，争夺话语权
#### **合：交替总结**
- 反1→正1→反2→正2→反3→正3→反4→正4的交替顺序
- 系统总结，最终论证
- 争取最终胜利
### 🧠 Memory Bank 记忆系统
#### **人格连续性保证**
- 基于 Google GenAI 的长期记忆系统
- 八仙人格的稳定性和一致性
- 观点演化和决策历史追踪
#### **记忆功能验证**
- ✅ API 调用成功：Google GenAI API 正常工作
- ✅ 记忆存储成功：生成完整的记忆文件
- ✅ 人格一致性：吕洞宾和何仙姑保持各自特质
- ✅ 记忆连续性：每个仙人都能记住历史对话
## 🏗️ 技术架构升级
### **多阶段状态管理**
```python
class DebateStage(Enum):
QI = "起" # 八仙按先天八卦顺序
CHENG = "承" # 雁阵式承接
ZHUAN = "转" # 自由辩论（36次handoff）
HE = "合" # 交替总结
```
### **优先级算法框架**
- 反驳紧急性权重：30%
- 论点强度权重：25%
- 时间压力权重：20%
- 观众反应权重：15%
- 策略需要权重：10%
### **记忆系统架构**
```python
class DebateMemorySystem:
- 发言者记忆存储
- 辩论历史追踪
- 人格特质维护
- 观点演化分析
```
## 📊 性能指标
### **辩论系统性能**
- **阶段转换**：毫秒级状态切换
- **发言者选择**：实时优先级计算
- **记忆存储**：异步记忆更新
- **状态持久化**：JSON格式状态保存
### **Memory Bank 性能**
- **API响应时间**：1-3秒
- **记忆存储容量**：支持长期历史记录
- **人格一致性**：85%以上的人格稳定性
- **记忆检索**：毫秒级相关记忆召回
## 🔧 技术实现
### **核心组件**
1. **QiChengZhuanHeDebate**：起承转合辩论系统核心
2. **PriorityAlgorithm**：优先级算法实现
3. **DebateMemorySystem**：辩论记忆系统
4. **MemoryBankTest**：记忆系统测试框架
### **依赖升级**
- Google GenAI 1.29.0
- 异步处理支持
- JSON状态持久化
- 枚举类型状态管理
## 🎯 使用示例
### **基础辩论流程**
```python
# 创建辩论系统
debate = QiChengZhuanHeDebate()
# 获取当前发言者
speaker = debate.get_current_speaker()
# 记录发言
debate.record_speech(speaker, "发言内容")
# 推进阶段
debate.advance_stage()
# 保存状态
debate.save_state()
```
### **Memory Bank 使用**
```python
# 创建记忆测试
test = MemoryBankTest()
# 与仙人对话
response = test.chat_with_immortal("吕洞宾", "问题")
# 保存记忆
test.save_memories()
```
## 🚀 下一步计划
### **短期目标（v2.1.0）**
- [ ] 完善优先级算法
- [ ] 实现多群聊协调
- [ ] 添加Human干预机制
- [ ] 优化辩论流程控制
### **中期目标（v2.2.0）**
- [ ] 集成太公三式预测
- [ ] 实现梅花心易直觉
- [ ] 完善八仙人格量化
- [ ] 添加观众反馈系统
### **长期目标（v3.0.0）**
- [ ] 完整的预测系统
- [ ] 商业化部署
- [ ] 多语言支持
- [ ] 移动端应用
## 🐛 已知问题
1. **优先级算法**：当前使用简化版本，需要进一步优化
2. **多群聊协调**：尚未实现完整的群聊网络
3. **Human干预**：干预机制需要进一步完善
4. **性能优化**：大规模辩论的性能需要优化
## 📝 更新日志
### **v2.0.0 (2025-08-10)**
- ✨ 新增起承转合辩论系统
- ✨ 新增Memory Bank记忆系统
- ✨ 新增优先级算法框架
- ✨ 新增状态持久化功能
- 🔧 升级Google GenAI集成
- 🔧 优化八仙人格系统
- 📚 完善技术文档
### **v1.x.x (历史版本)**
- 基础八仙论道系统
- OpenRouter API集成
- Streamlit界面
- RapidAPI数据源
## 🙏 致谢
感谢所有为太公心易项目做出贡献的开发者和用户。特别感谢：
- Google GenAI 团队提供的强大AI能力
- 开源社区的支持和反馈
- 项目团队的辛勤工作
## 📞 联系方式
如有问题或建议，请通过以下方式联系：
- GitHub Issues：[项目地址]
- 邮箱：[联系邮箱]
- 文档：[文档地址]
---
**太公心易 v2.0.0** - 让AI辩论更有智慧，让预测更有力量！

163
modules/documentation-suite/docs/guides/CLAUDE.md Normal file
View File

@@ -0,0 +1,163 @@
---
title: "Claude 集成与使用指南"
status: summer
created: 2025-08-17
owner: Claude
review_by: "2026-02-17"
tags: ["guide", "claude", "core"]
---
# Claude 集成与使用指南
本指南介绍如何在炼妖壶项目中使用 Claude，包括运行时模型接入、GitHub 代码审查助手（可选）以及常见问题排查。此文档面向公开文档；更详细或偏内部的安装步骤请参考内部文档 `internal/setup/CLAUDE_ACTION_SETUP.md`。
## 适用场景
- 在项目中调用 Claude 模型（通过 LiteLLM/OpenRouter/Anthropic）用于分析、辩论与推理
- 在 GitHub 的 Issue/PR 中通过评论触发 Claude 进行代码审查、调试辅助与架构讨论（可选）
## 快速开始（运行时模型）
项目推荐通过 LiteLLM 路由到不同模型供应商。你可以选择两种常见方式接入 Claude：
- 方式 A：使用 OpenRouter 免费路由（如 `anthropic/claude-3.5-sonnet:free`）
- 方式 B：直接使用 Anthropic 官方 API（需要付费 API Key）
### 环境变量
至少准备以下中的一个或多个（按你的接入方式选择）：
- OPENROUTER_API_KEY: 使用 OpenRouter 路由时需要
- ANTHROPIC_API_KEY: 直接调用 Anthropic API 时需要
建议将密钥保存到本地 `.env` 或 CI/CD 的 Secret 中，不要提交到仓库。
### LiteLLM 配置提示
仓库中 `litellm/config.yaml` 是示例配置。你可以添加 Claude 相关配置，例如：
```yaml
model_list:
- model_name: claude-free
litellm_params:
model: anthropic/claude-3.5-sonnet:free
# 如果使用 OpenRouter，请在运行环境里提供 OPENROUTER_API_KEY
- model_name: claude-sonnet
litellm_params:
model: anthropic/claude-3-5-sonnet-20240620
# 如果直接使用 Anthropic 官方，请在运行环境里提供 ANTHROPIC_API_KEY
```
> 提示：内部文档 `internal/technical/Sanqing_Baxian_OpenRouter_Model_Assignment.md` 与 `internal/technical/Final_Baxian_Sanqing_Model_Configuration.md` 描述了项目在三清八仙体系中对 Claude 的模型分配建议，可作为策略参考。
## GitHub 助手（可选）
如果你希望在 GitHub 的 Issue/PR 评论中 @Claude 进行协助，请按以下步骤配置。若当前仓库没有工作流文件，请根据下面示例新建。
1) 在 GitHub 仓库设置中添加 Secret（任选一种或两种）：
- ANTHROPIC_API_KEY: 你的 Anthropic API Key
- CLAUDE_CODE_OAUTH_TOKEN: Claude Code OAuth Token（Pro/Max）
2) 安装 Claude GitHub App（如果还未安装）
- 访问 https://github.com/apps/claude
- 选择安装到你的仓库并授权必要权限
3) 新建或更新工作流文件 `.github/workflows/claude.yml`
```yaml
name: Claude Assistant
on:
issue_comment:
types: [created]
pull_request_review_comment:
types: [created]
jobs:
run-claude:
if: contains(github.event.comment.body, '@claude') || contains(github.event.comment.body, '@太公') || contains(github.event.comment.body, '@八仙')
runs-on: ubuntu-latest
permissions:
contents: read
issues: write
pull-requests: write
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.11'
- name: Install deps
run: |
python -m pip install --upgrade pip
pip install litellm
- name: Run Claude reply
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
python - <<'PY'
import os, json, requests
body = os.environ.get('GITHUB_EVENT_PATH')
import sys, pathlib
event = json.load(open(os.environ['GITHUB_EVENT_PATH']))
comment_body = event['comment']['body']
issue_url = event['issue']['comments_url'] if 'issue' in event else event['pull_request']['comments_url']
if '@claude' in comment_body or '@太公' in comment_body or '@八仙' in comment_body:
prompt = comment_body.replace('@claude','').replace('@太公','').replace('@八仙','').strip()
else:
sys.exit(0)
# 调用 Claude（示例：通过 LiteLLM 统一调用，环境里准备好 API Key）
import litellm
litellm.set_verbose(False)
resp = litellm.completion(model="anthropic/claude-3.5-sonnet:free", messages=[{"role":"user","content":prompt}])
text = resp.choices[0].message.get('content') if hasattr(resp.choices[0], 'message') else resp['choices'][0]['message']['content']
headers = {"Authorization": f"Bearer {os.environ['GITHUB_TOKEN']}", "Accept": "application/vnd.github+json"}
requests.post(issue_url, headers=headers, json={"body": text})
PY
```
- 触发词默认支持：`@claude`、`@太公`、`@八仙`
- 你可以在工作流的 `if:` 条件中添加更多触发词
> 注意：内部文档 `internal/setup/CLAUDE_ACTION_SETUP.md` 提供了更完整的 Action 版配置与触发词说明。
## 使用示例
- 代码审查：
- 在 PR 评论中输入：`@claude 请审查这个MCP管理器的实现，关注安全性和性能`
- 功能实现建议：
- 在 Issue 评论中输入：`@claude 帮我实现一个新的Yahoo Finance数据获取功能`
- 架构讨论：
- 在评论中输入：`@太公 如何优化当前的金融数据分析流程？`
- 调试帮助：
- 在评论中输入：`@八仙 这个错误是什么原因：[粘贴错误信息]`
## 成本与安全
- API 成本：使用 Anthropic 直连会产生费用；OpenRouter 免费路由有速率与配额限制
- 权限：GitHub App 与工作流权限请最小化配置
- 敏感信息：不要在公开评论中包含敏感数据；密钥请使用 Secret 管理
## 常见问题排查
- 无法调用成功：确认已在运行环境设置了相应的 API Key（`OPENROUTER_API_KEY` 或 `ANTHROPIC_API_KEY`）
- 工作流未触发：确认评论中包含触发词，且仓库已启用 `Actions`；检查 `if:` 条件
- 响应为空或报错：降低请求长度，检查模型名称是否正确，或改用其他可用模型
## 参考
- 内部：`internal/setup/CLAUDE_ACTION_SETUP.md`
- 内部：`internal/technical/Final_Baxian_Sanqing_Model_Configuration.md`
- 内部：`internal/technical/Sanqing_Baxian_OpenRouter_Model_Assignment.md`

211
modules/documentation-suite/docs/guides/GOOGLE_ADK_MIGRATION_GUIDE.md Normal file
View File

@@ -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/settings.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. **测试简单智能体**: 验证基本功能
准备好开始迁移了吗？我可以帮您逐步执行每个阶段！

160
modules/documentation-suite/docs/guides/MEMORY_BANK_ACCESS_GUIDE.md Normal file
View File

@@ -0,0 +1,160 @@
# Vertex AI Memory Bank 访问指南
## 📋 项目概览
- **项目ID**: `inner-radius-469712-e9`
- **项目名称**: My First Project
- **项目编号**: 849796462624
- **区域**: `us-central1`
- **创建时间**: 2025-08-21T12:27:33.480028Z
- **状态**: ACTIVE
## 🧠 Memory Bank 实例
### 八仙智能体 Memory Bank 列表
我们已成功创建并验证了以下Memory Bank实例：
1. **铁拐李** (`tieguaili`)
- Memory Bank ID: `memory_bank_tieguaili_inner-radius-469712-e9`
- 状态: ✅ 活跃
2. **汉钟离** (`zhongliquan`)
- Memory Bank ID: `memory_bank_zhongliquan_inner-radius-469712-e9`
- 状态: ✅ 活跃
3. **吕洞宾** (`lvdongbin`)
- Memory Bank ID: `memory_bank_lvdongbin_inner-radius-469712-e9`
- 状态: ✅ 活跃
- 测试数据: 包含对话、偏好、知识、策略等4种类型记忆
4. **何仙姑** (`hehe_erxian`)
- Memory Bank ID: `memory_bank_hehe_erxian_inner-radius-469712-e9`
- 状态: ✅ 活跃
5. **蓝采和** (`lantsaihe`)
- Memory Bank ID: `memory_bank_lantsaihe_inner-radius-469712-e9`
- 状态: ✅ 活跃
6. **韩湘子** (`hanxiangzi`)
- Memory Bank ID: `memory_bank_hanxiangzi_inner-radius-469712-e9`
- 状态: ✅ 活跃
7. **曹国舅** (`caoguo_jiu`)
- Memory Bank ID: `memory_bank_caoguo_jiu_inner-radius-469712-e9`
- 状态: ✅ 活跃
8. **何仙姑** (`hexiangu`)
- Memory Bank ID: `memory_bank_hexiangu_inner-radius-469712-e9`
- 状态: ✅ 活跃
## 🌐 Web端访问方式
### Google Cloud Console 直接链接
1. **Memory Bank 专用页面**:
```
https://console.cloud.google.com/vertex-ai/generative/memory-banks?project=inner-radius-469712-e9
```
2. **Vertex AI 主页**:
```
https://console.cloud.google.com/vertex-ai?project=inner-radius-469712-e9
```
3. **生成式AI 控制台**:
```
https://console.cloud.google.com/vertex-ai/generative?project=inner-radius-469712-e9
```
### 导航路径
在Google Cloud Console中：
1. 选择项目: `inner-radius-469712-e9`
2. 导航到: **Vertex AI** → **生成式AI** → **Memory Banks**
3. 或搜索: "Memory Bank" 或 "记忆银行"
## 🔧 命令行访问
### 已配置的工具
- ✅ `gcloud` CLI 已安装并认证
- ✅ Application Default Credentials 已设置
- ✅ Vertex AI API (`aiplatform.googleapis.com`) 已启用
- ✅ Python SDK 可正常使用
### 测试脚本
1. **基础列表查看**: `list_memory_banks.py`
2. **详细功能测试**: `detailed_memory_bank_info.py`
3. **GCP API查询**: `view_memory_banks_gcp.py`
### 运行命令
```bash
# 激活虚拟环境
source venv/bin/activate
# 查看Memory Bank列表
python list_memory_banks.py
# 详细测试功能
python detailed_memory_bank_info.py
# GCP API查询
python view_memory_banks_gcp.py
```
## 📊 Memory Bank 功能验证
### ✅ 已验证功能
1. **创建Memory Bank**: 为每个智能体创建独立的记忆银行
2. **添加记忆**: 支持4种记忆类型
- `conversation`: 对话记忆
- `preference`: 偏好记忆
- `knowledge`: 知识记忆
- `strategy`: 策略记忆
3. **搜索记忆**: 基于关键词和类型搜索
4. **获取上下文**: 为特定辩论主题生成上下文
5. **记忆统计**: 按类型统计记忆数量
### 📈 测试数据示例
**吕洞宾** 的测试记忆：
- 对话记忆: "在关于AI伦理的辩论中，我强调了技术发展应该以人为本..."
- 偏好记忆: "我偏好使用古典哲学的智慧来论证现代问题，特别是道家思想。"
- 知识记忆: "区块链技术的核心是去中心化和不可篡改性，这与道家'无为而治'的理念有相通之处。"
- 策略记忆: "在辩论中，当对手使用激进论点时，我会用温和的反问来引导思考..."
## 🔐 权限和安全
### 认证状态
- ✅ Google Cloud 用户: `benhouzhong@gmail.com`
- ✅ 默认项目: `inner-radius-469712-e9`
- ✅ 访问令牌: 有效
- ✅ IAM权限: 足够访问Vertex AI服务
### 启用的服务
- ✅ `aiplatform.googleapis.com` (Vertex AI API)
- ✅ `generativelanguage.googleapis.com` (Generative Language API)
- ✅ `ml.googleapis.com` (AI Platform API)
## 🚀 下一步建议
1. **Web端验证**: 使用提供的链接在Google Cloud Console中查看Memory Bank
2. **功能扩展**: 为其他智能体添加更多测试数据
3. **集成测试**: 在实际辩论系统中测试Memory Bank功能
4. **监控设置**: 配置Memory Bank使用情况的监控和告警
## 📝 注意事项
- Memory Bank 功能目前处于公开预览阶段
- 某些高级功能可能需要特殊权限或白名单
- API端点可能会随着服务更新而变化
- 建议定期备份重要的记忆数据
---
*最后更新: 2025-08-22 11:44*
*项目: 稷下学宫AI辩论系统*

152
modules/documentation-suite/docs/guides/MEMORY_BANK_ACCESS_SOLUTION.md Normal file
View File

@@ -0,0 +1,152 @@
# Vertex AI Memory Bank 访问解决方案
## 问题说明
您遇到的"打不开"问题是因为 **Vertex AI Memory Bank 目前没有独立的Web控制台界面**。Memory Bank是Vertex AI Agent Engine的一个预览功能，只能通过API、SDK和命令行工具访问。
## 为什么没有Web界面
根据Google官方文档，Memory Bank具有以下特点：
- 🔄 **预览功能**：Memory Bank目前处于公开预览阶段
- 🛠️ **API优先**：主要通过编程接口访问
- 🤖 **Agent Engine集成**：与Vertex AI Agent Engine深度集成
- 📍 **区域限制**：仅在us-central1区域支持
## 可用的访问方式
### 1. 编程访问（推荐）
#### Python SDK
```python
# 我们已经验证的方式
from jixia.memory.factory import get_memory_backend
# 初始化Memory Bank
memory_backend = await get_memory_backend("vertex")
# 创建记忆银行
memory_bank = await memory_backend.create_memory_bank(agent_id="your_agent")
# 添加记忆
await memory_bank.add_memory("用户偏好信息")
# 搜索记忆
results = await memory_bank.search_memories("查询内容")
```
#### 直接使用Google Cloud SDK
```python
from google.cloud import aiplatform
from google.adk.memory import VertexAiMemoryBankService
# 创建Memory Bank服务
memory_service = VertexAiMemoryBankService(
project="your-project-id",
location="us-central1",
agent_engine_id="your-agent-engine-id"
)
```
### 2. REST API访问
```bash
# 使用gcloud获取访问令牌
gcloud auth print-access-token
# 调用Memory Bank API
curl -X POST \
"https://aiplatform.googleapis.com/v1/projects/YOUR_PROJECT/locations/us-central1/reasoningEngines/YOUR_ENGINE/memories" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{"memory": {"content": "记忆内容"}}'
```
### 3. Agent Development Kit (ADK)
```python
from google import adk
from google.adk.memory import VertexAiMemoryBankService
# 创建带记忆功能的Agent
agent = adk.Agent(
model="gemini-2.0-flash",
name='stateful_agent',
tools=[adk.tools.preload_memory_tool.PreloadMemoryTool()]
)
```
## 当前项目状态
### ✅ 已验证功能
- **环境配置**：Application Default Credentials已设置
- **Memory Bank创建**：成功为8个"八仙"角色创建记忆银行
- **记忆操作**：lvdongbin的记忆银行已添加测试数据
- **API访问**：所有核心功能均可正常使用
### 📊 Memory Bank实例
```
1. ✅ lvdongbin (包含测试数据)
2. ✅ tieguaili
3. ✅ hanxiangzi
4. ✅ lanzaihe
5. ✅ hesengu
6. ✅ zhonghanli
7. ✅ caogujiu
8. ✅ hanzhongli
```
## 替代访问方案
### 1. 使用我们创建的脚本
运行现有的Python脚本来管理Memory Bank：
```bash
# 激活虚拟环境
source venv/bin/activate
# 列出所有Memory Bank
python list_memory_banks.py
# 查看详细信息
python detailed_memory_bank_info.py
# 通过API查看
python view_memory_banks_gcp.py
```
### 2. 创建自定义Web界面
如果需要Web界面，可以考虑：
- 使用Streamlit创建简单的Web界面
- 构建Flask/FastAPI应用
- 集成到现有的管理系统中
### 3. Google Cloud Console集成
虽然没有专门的Memory Bank界面，但可以在以下位置查看相关信息：
- **Vertex AI** → **Agent Engine**
- **API & Services** → **Enabled APIs**
- **Cloud Logging** → 查看Memory Bank操作日志
## 未来发展
根据Google的产品路线图：
- Memory Bank目前处于**公开预览**阶段
- 未来可能会提供更完整的Web控制台
- 建议关注Google Cloud官方更新
## 技术支持
如需进一步帮助：
1. 📚 查看[官方文档](https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/memory-bank/overview)
2. 💬 加入[Vertex AI Google Cloud社区](https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/memory-bank/overview)
3. 🛠️ 使用我们已验证的代码示例
## 总结
Memory Bank功能完全正常，只是访问方式与传统的Web控制台不同。通过编程接口，您可以实现所有必要的Memory Bank操作，包括创建、添加、搜索和管理记忆。
---
*最后更新：2025年1月*

76
modules/documentation-suite/docs/guides/MEMORY_BANK_USER_GUIDE.md Normal file
View File

@@ -0,0 +1,76 @@
# 炼妖壶 (Lianyaohu) - 稷下学宫AI辩论系统
## 八仙记忆银行配置与使用指南
每个八仙智能体都有一个专属的记忆银行，用于存储其在不同辩论主题下的记忆。系统支持两种记忆后端：Google Vertex AI Memory Bank 和 Cloudflare AutoRAG。
## 配置说明
### 选择记忆后端
通过设置环境变量 `JIXIA_MEMORY_BACKEND` 来选择记忆后端：
```bash
# 使用Google Vertex AI (默认)
export JIXIA_MEMORY_BACKEND=vertex
# 使用Cloudflare AutoRAG
export JIXIA_MEMORY_BACKEND=cloudflare
```
### Google Vertex AI 配置
需要配置以下环境变量：
- `GOOGLE_API_KEY`: Google API 密钥
- `GOOGLE_CLOUD_PROJECT_ID`: Google Cloud 项目ID
- `GOOGLE_CLOUD_LOCATION`: 部署区域 (可选，默认 us-central1)
### Cloudflare AutoRAG 配置
需要配置以下环境变量：
- `CLOUDFLARE_ACCOUNT_ID`: Cloudflare 账户ID
- `CLOUDFLARE_API_TOKEN`: 具有 Vectorize 和 Workers AI 权限的 API 令牌
## 八仙记忆银行详情
系统为以下八位仙人创建了专属记忆银行：
1. **铁拐李 (tieguaili)** - 擅长技术分析和风险控制
2. **汉钟离 (hanzhongli)** - 注重基本面分析和长期价值
3. **张果老 (zhangguolao)** - 擅长宏观趋势分析和周期判断
4. **蓝采和 (lancaihe)** - 关注市场情绪和资金流向
5. **何仙姑 (hexiangu)** - 精于财务数据分析和估值模型
6. **吕洞宾 (lvdongbin)** - 善于多维度综合分析和创新策略
7. **韩湘子 (hanxiangzi)** - 擅长行业比较和相对价值分析
8. **曹国舅 (caoguojiu)** - 注重合规性、社会责任和ESG因素
## 使用方法
在代码中使用记忆银行：
```python
from src.jixia.memory.factory import get_memory_backend
# 获取记忆后端 (自动根据环境变量选择)
memory_bank = get_memory_backend()
# 为吕洞宾添加偏好记忆
await memory_bank.add_memory(
agent_name="lvdongbin",
content="倾向于使用DCF模型评估科技股的内在价值",
memory_type="preference",
debate_topic="TSLA投资分析"
)
# 搜索吕洞宾关于TSLA的记忆
memories = await memory_bank.search_memories(
agent_name="lvdongbin",
query="TSLA",
memory_type="preference"
)
# 获取上下文
context = await memory_bank.get_agent_context("lvdongbin", "TSLA投资分析")
```

116
modules/documentation-suite/docs/guides/MIGRATION_PLAN.md Normal file
View File

@@ -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/ # 配置管理
│ └── settings.py # Doppler配置
├── tests/ # 测试代码
├── docs/ # 文档
├── scripts/ # 工具脚本
└── .kiro/ # Kiro配置
└── specs/ # 规范文档
```
## 🚫 不迁移的内容
- 历史实验代码
- 重复的功能实现
- 过时的依赖
- 混乱的配置文件
- 包含密钥的文件
- 无用的调试脚本
## ✅ 迁移检查清单
### 功能验证
- [ ] AI辩论系统正常工作
- [ ] Streamlit界面完整显示
- [ ] 数据库连接成功
- [ ] API调用正常
- [ ] 配置加载正确
### 安全验证
- [ ] GitGuardian扫描通过
- [ ] 无硬编码密钥
- [ ] Doppler配置正确
- [ ] 环境变量隔离
- [ ] 访问权限合理
### 质量验证
- [ ] 代码风格一致
- [ ] 文档完整
- [ ] 测试覆盖充分
- [ ] 性能满足要求
- [ ] 部署流程顺畅
## 🎉 成功标准
迁移成功的标志：
1. 新项目通过所有安全扫描
2. 核心功能100%可用
3. 启动时间 < 30秒
4. 代码质量 A级
5. 文档完整度 > 90%
---
**准备好开始迁移了吗？让我们带着这些文档，前往新的开始！** 🚀

236
modules/documentation-suite/docs/guides/QUICK_START_GUIDE.md Normal file
View File

@@ -0,0 +1,236 @@
# 🚀 稷下学宫负载均衡系统 - 快速上手指南
## 📋 前置条件
1. **RapidAPI账户**: 确保已订阅以下API服务
- Alpha Vantage
- Yahoo Finance 15
- Webull
- Seeking Alpha
2. **环境配置**: 已配置Doppler环境变量管理
```bash
doppler secrets | grep RAPIDAPI_KEY
```
## ⚡ 5分钟快速体验
### 1. 运行完整演示
```bash
cd /home/ben/liurenchaxin
doppler run python demo_jixia_load_balancing.py
```
### 2. 查看演示结果
```bash
# 查看生成的结果文件
ls demo_results_*.json
# 查看AAPL的详细结果
cat demo_results_aapl.json | jq .
```
## 🎯 核心功能演示
### 单个仙人数据获取
```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')
print(f"价格: ${result.data['price']}, 来源: {result.api_used}")
```
### 八仙论道完整演示
```python
# 进行八仙论道
results = load_balancer.conduct_immortal_debate('TSLA')
# 查看负载分布
distribution = load_balancer.get_load_distribution()
for api, stats in distribution.items():
print(f"{api}: {stats['calls']}次调用 ({stats['percentage']:.1f}%)")
```
## 📊 预期输出示例
```
🏛️ 稷下学宫八仙论道开始 - 主题: AAPL
============================================================
🎭 吕洞宾 正在获取 stock_quote 数据...
✅ 成功从 alpha_vantage 获取数据 (响应时间: 1.33s)
💰 吕洞宾: $202.38 (-2.5004%) via alpha_vantage
🎭 何仙姑 正在获取 stock_quote 数据...
✅ 成功从 yahoo_finance_15 获取数据 (响应时间: 1.87s)
💰 何仙姑: $N/A (N/A) via yahoo_finance_15
📊 负载分布统计:
alpha_vantage: 3 次调用 (37.5%) - 健康
yahoo_finance_15: 2 次调用 (25.0%) - 健康
webull: 3 次调用 (37.5%) - 健康
```
## 🔧 自定义配置
### 修改仙人API偏好
编辑 `/home/ben/liurenchaxin/src/jixia/config/immortal_api_config.json`:
```json
{
"immortals": {
"吕洞宾": {
"preferred_apis": {
"stock_quote": "webull", // 改为使用Webull
"company_overview": "alpha_vantage"
}
}
}
}
```
### 调整缓存策略
```python
# 修改缓存TTL
load_balancer.cache_ttl = 600 # 10分钟缓存
# 清空缓存
load_balancer.cache.clear()
```
## 🚨 故障排除
### 常见问题
1. **API密钥错误**
```
❌ 错误: 请设置RAPIDAPI_KEY环境变量
```
**解决**: 确保Doppler配置正确
```bash
doppler secrets set RAPIDAPI_KEY="your_key_here"
```
2. **API调用失败**
```
⚠️ alpha_vantage 不可用，尝试备用API...
```
**解决**: 系统会自动故障转移，无需干预
3. **数据格式异常**
```
💰 价格: $N/A
```
**解决**: 某些API返回格式不同，系统会标准化处理
### 调试模式
```python
# 启用详细日志
import logging
logging.basicConfig(level=logging.DEBUG)
# 查看API健康状态
for api, status in load_balancer.health_checker.health_status.items():
print(f"{api}: {'健康' if status['healthy'] else '异常'}")
```
## 📈 性能优化建议
### 1. 缓存优化
```python
# 针对不同数据类型设置不同缓存时间
cache_strategies = {
'stock_quote': 60, # 1分钟
'company_overview': 3600, # 1小时
'market_news': 1800 # 30分钟
}
```
### 2. 并发控制
```python
# 控制并发请求数量
import time
for immortal in immortals:
result = load_balancer.get_data_for_immortal(immortal, 'stock_quote', symbol)
time.sleep(0.2) # 避免过快请求
```
### 3. 批量处理
```python
# 批量获取多个股票数据
symbols = ['AAPL', 'TSLA', 'MSFT', 'GOOGL']
results = {}
for symbol in symbols:
results[symbol] = load_balancer.conduct_immortal_debate(symbol)
```
## 🎯 最佳实践
### 1. 监控API使用情况
```python
# 定期检查负载分布
distribution = load_balancer.get_load_distribution()
print(f"总调用次数: {sum(stats['calls'] for stats in distribution.values())}")
```
### 2. 合理使用缓存
```python
# 对于实时性要求不高的数据，优先使用缓存
result = load_balancer.get_data_for_immortal('韩湘子', 'company_overview', 'AAPL')
if result.cached:
print("使用缓存数据，节省API调用")
```
### 3. 错误处理
```python
result = load_balancer.get_data_for_immortal('吕洞宾', 'stock_quote', 'AAPL')
if not result.success:
print(f"获取数据失败: {result.error}")
# 实施降级策略
else:
# 正常处理数据
process_stock_data(result.data)
```
## 📚 进阶使用
### 自定义数据处理器
```python
class CustomDataNormalizer(DataNormalizer):
def normalize_stock_quote(self, raw_data, api_source):
# 自定义数据标准化逻辑
normalized = super().normalize_stock_quote(raw_data, api_source)
# 添加自定义字段
normalized['custom_score'] = self.calculate_score(normalized)
return normalized
# 使用自定义处理器
load_balancer.data_normalizer = CustomDataNormalizer()
```
### 自定义健康检查
```python
class CustomHealthChecker(APIHealthChecker):
def _perform_health_check(self, api_name):
# 自定义健康检查逻辑
# 例如：检查API响应时间、错误率等
pass
load_balancer.health_checker = CustomHealthChecker()
```
## 🎉 完成！
现在您已经掌握了稷下学宫负载均衡系统的基本使用方法。
### 下一步
- 📖 阅读完整文档: `README_jixia_load_balancing.md`
- 🔧 查看配置文件: `src/jixia/config/immortal_api_config.json`
- 💻 研究核心代码: `src/jixia/engines/jixia_load_balancer.py`
- 🚀 开始构建您的投资分析系统！
---
*🏛️ 稷下学宫 - 智慧投资，从负载均衡开始*

275
modules/documentation-suite/docs/guides/README_jixia_load_balancing.md Normal file
View File

@@ -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 提交问题
- **文档更新**: 欢迎提交文档改进建议
---
*🏛️ 稷下学宫 - 让智慧的光芒照亮投资的道路*

152
modules/documentation-suite/docs/guides/shushu-demo-results.md Normal file
View File

@@ -0,0 +1,152 @@
# 术数书 Hyperdrive + NeonDB 查询系统演示结果
## 系统概述
我们成功部署了一个基于 Cloudflare Hyperdrive + NeonDB 的术数书查询系统，通过高性能的边缘计算和数据库连接池优化，实现了对古代术数典籍的快速查询和检索。
## 部署信息
- **Worker URL**: https://hyperdrive.seekkey.tech/
- **Hyperdrive ID**: ef43924d89064cddabfaccf06aadfab6
- **数据库**: NeonDB PostgreSQL
- **连接池**: 已启用
- **边缘缓存**: 全球分布
## 可用 API 端点
### 1. 基础端点
- `GET /` - 系统信息和端点列表
- `GET /test-connection` - 测试数据库连接
- `GET /test-query` - 测试数据库查询
### 2. 术数书查询端点
- `GET /query-tables` - 查询数据库表结构
- `GET /query-shushu?limit=N` - 查询术数书内容
- `GET /search-shushu?q=keyword&limit=N` - 搜索术数书内容
- `GET /shushu-stats` - 获取术数书统计信息
## 数据库结构
通过 `/query-tables` 端点发现的表结构：
```json
{
"status": "success",
"message": "Tables retrieved successfully",
"tables": [
{
"table_name": "books",
"table_schema": "public"
},
{
"table_name": "hyperdrive_test",
"table_schema": "public"
},
{
"table_name": "playing_with_neon",
"table_schema": "public"
}
]
}
```
## 术数书内容示例
通过 `/query-shushu?limit=3` 成功获取的术数书内容：
### 书籍信息
- **ID**: 1
- **标题**: 《神相全编》
- **作者**: 袁珙
- **类别**: 相术
- **子类别**: 面相手相
- **总字数**: 33,897 字
- **创建时间**: 2025-07-17T15:48:55.563Z
### 内容片段
```
诈。口尖唇薄者多妄。冷笑无情多诈。偷视不正多诈。视上顾下多诈。
妄说语言如太急者多诈。牙齿疏者多诈。又曰鼻尖毫出、眼细视低，
口角高低，步履纵横，行步不匀，脚走高低多诈。
宽大
升斗满，部位中正，印堂开阔，诸部圆满，鼻窍微露。阴德眼上下堂
有黄气，卧蚕出见，印堂黄气，精舍黄气。带令地角朝天、耳有轮廓
朝水，口有棱角。眼带桃花眉如线。又如新月久视，意气可人。
贪食格
鼻如鹰嘴者多贪，心狡。眼红者多贪，心毒。眉卓者多贪。嘴尖者多贪。
鼻勾者多贪。
劳碌格
眼长多劳碌。骨粗多劳碌。面如马面驴唇劳碌。眉重气弱者劳碌。
鱼尾纹多者劳碌。
```
## 系统特点
### 1. 高性能优化
- **Hyperdrive 连接池**: 减少数据库连接开销
- **边缘缓存**: 全球分布式缓存，降低延迟
- **智能路由**: 自动选择最近的数据中心
### 2. 成本优化
- **连接复用**: 大幅减少 NeonDB 的连接数消耗
- **查询缓存**: 减少重复查询的数据库负载
- **按需扩展**: 根据访问量自动调整资源
### 3. 功能特性
- **多表查询**: 自动检测和查询可能的术数书表
- **全文搜索**: 支持关键词搜索术数书内容
- **统计分析**: 提供数据库使用统计信息
- **RESTful API**: 标准化的 API 接口
## 与 AutoRAG 对比的优势
### 1. 数据访问速度
- **Hyperdrive**: 全球边缘缓存，毫秒级响应
- **AutoRAG**: 依赖本地或远程向量数据库，可能有网络延迟
### 2. 数据一致性
- **Hyperdrive**: 直接查询源数据库，保证数据实时性
- **AutoRAG**: 向量化数据可能存在更新延迟
### 3. 查询精确性
- **Hyperdrive**: SQL 精确查询，支持复杂条件
- **AutoRAG**: 语义相似性查询，可能存在误差
### 4. 成本效益
- **Hyperdrive**: 连接池优化，降低数据库成本
- **AutoRAG**: 需要额外的向量数据库和计算资源
## 使用场景
### 1. 学术研究
- 快速检索古代术数典籍
- 支持精确的文本查询
- 提供完整的原文内容
### 2. 应用开发
- 为术数应用提供数据 API
- 支持多种查询方式
- 高并发访问支持
### 3. 知识服务
- 构建术数知识库
- 提供实时查询服务
- 支持多终端访问
## 技术栈
- **前端**: Cloudflare Workers (TypeScript)
- **数据库**: NeonDB (PostgreSQL)
- **连接优化**: Cloudflare Hyperdrive
- **部署**: Cloudflare Workers Platform
- **API**: RESTful JSON API
## 总结
通过 Cloudflare Hyperdrive + NeonDB 的组合，我们成功构建了一个高性能、低成本的术数书查询系统。该系统不仅提供了快速的数据访问能力，还通过智能缓存和连接池优化，在 NeonDB 免费配额下支持了更大的访问量。
相比传统的 AutoRAG 方案，我们的系统在数据访问速度、查询精确性和成本控制方面都有显著优势，为术数典籍的数字化应用提供了一个理想的技术解决方案。

24
modules/documentation-suite/docs/index.md Normal file
View File

@@ -0,0 +1,24 @@
# 炼妖壶文档首页
欢迎访问项目文档。以下是常用入口：
- 快速上手与指南
- [Claude 集成与使用指南](guides/CLAUDE.md)
- [快速开始：负载均衡示例](guides/README_jixia_load_balancing.md)
- [Cloudflare AutoRAG 集成](guides/CLOUDFLARE_AUTORAG_INTEGRATION.md)
- [Google ADK 迁移指南](guides/GOOGLE_ADK_MIGRATION_GUIDE.md)
- 记忆与后端
- [Vertex Memory Bank 设置](../docs/VERTEX_MEMORY_BANK_SETUP.md)
- RapidAPI 相关
- [负载均衡策略](rapidapi/jixia_load_balancing_strategy.md)
- [订阅清单](rapidapi/api_inventory.md)
- [优化配置示例](rapidapi/optimized_config.md)
- [测试报告样例](rapidapi/test_report_20250802_120925.md)
- 工作流与工具
- [n8n MongoDB Upsert 配置](../docs/n8n_mongodb_upsert_config.md)
- [n8n 去重工作流](../docs/n8n_deduplication_workflow.md)
- 分析与要求
- [RSS 调试分析记录](analysis/rss_debug_analysis.md)
- [项目要求概览](requirements.md)
内网与仅限内部的内容保持在 `internal/`，不会发布到 GitHub Pages。

160
modules/documentation-suite/docs/memory_bank_design.md Normal file
View File

@@ -0,0 +1,160 @@
# Memory Bank 设计与实现文档
## 概述
Memory Bank 是 稷下学宫AI辩论系统 的核心组件之一，旨在为每个AI智能体（八仙）提供持久化的记忆能力。通过集成不同的后端实现（如 Google Vertex AI Memory Bank 和 Cloudflare AutoRAG），系统能够灵活地存储、检索和利用智能体在辩论过程中积累的知识和经验。
## 架构设计
### 核心抽象
系统通过 `MemoryBankProtocol` 定义了记忆银行的通用接口，确保了不同后端实现的可替换性。
```python
@runtime_checkable
class MemoryBankProtocol(Protocol):
async def create_memory_bank(self, agent_name: str, display_name: Optional[str] = None) -> str: ...
async def add_memory(
self,
agent_name: str,
content: str,
memory_type: str = "conversation",
debate_topic: str = "",
metadata: Optional[Dict[str, Any]] = None,
) -> str: ...
async def search_memories(
self,
agent_name: str,
query: str,
memory_type: Optional[str] = None,
limit: int = 10,
) -> List[Dict[str, Any]]: ...
async def get_agent_context(self, agent_name: str, debate_topic: str) -> str: ...
async def save_debate_session(
self,
debate_topic: str,
participants: List[str],
conversation_history: List[Dict[str, str]],
outcomes: Optional[Dict[str, Any]] = None,
) -> None: ...
```
### 工厂模式
通过 `get_memory_backend` 工厂函数，系统可以根据配置动态选择合适的记忆后端实现。
```python
def get_memory_backend(prefer: Optional[str] = None) -> MemoryBankProtocol:
# 根据环境变量 JIXIA_MEMORY_BACKEND 选择后端
# 支持 "vertex" 和 "cloudflare"
...
```
## 后端实现
### Vertex AI Memory Bank
基于 Google Vertex AI 的 Memory Bank 服务实现。
**特点**:
- 与 Google Cloud 生态系统深度集成
- 提供企业级的安全性和可靠性
- 支持复杂的元数据过滤和查询
**配置**:
- `GOOGLE_API_KEY`: Google API 密钥
- `GOOGLE_CLOUD_PROJECT_ID`: Google Cloud 项目ID
- `GOOGLE_CLOUD_LOCATION`: 部署区域 (默认 us-central1)
### Cloudflare AutoRAG
基于 Cloudflare Vectorize 和 Workers AI 实现的向量检索增强生成方案。
**特点**:
- 全球分布的边缘计算网络
- 成本效益高，适合中小型项目
- 易于部署和扩展
**配置**:
- `CLOUDFLARE_ACCOUNT_ID`: Cloudflare 账户ID
- `CLOUDFLARE_API_TOKEN`: 具有 Vectorize 和 Workers AI 权限的 API 令牌
## 使用指南
### 初始化记忆银行
```python
from src.jixia.memory.factory import get_memory_backend
# 根据环境变量自动选择后端
memory_bank = get_memory_backend()
# 或者显式指定后端
memory_bank = get_memory_backend(prefer="cloudflare")
```
### 为智能体创建记忆空间
```python
# 为吕洞宾创建记忆银行/空间
await memory_bank.create_memory_bank("lvdongbin")
```
### 添加记忆
```python
await memory_bank.add_memory(
agent_name="lvdongbin",
content="倾向于使用DCF模型评估科技股的内在价值",
memory_type="preference",
debate_topic="TSLA投资分析"
)
```
### 搜索记忆
```python
memories = await memory_bank.search_memories(
agent_name="lvdongbin",
query="TSLA",
memory_type="preference"
)
```
### 获取上下文
```python
context = await memory_bank.get_agent_context("lvdongbin", "TSLA投资分析")
```
## 最佳实践
1. **合理分类记忆类型**:
- `conversation`: 记录对话历史，用于上下文理解和连贯性。
- `preference`: 存储智能体的偏好和倾向，指导决策过程。
- `knowledge`: 积累专业知识和数据，提升分析深度。
- `strategy`: 总结辩论策略和战术，优化表现。
2. **定期维护记忆**:
- 实施记忆的定期清理和归档策略，避免信息过载。
- 通过 `save_debate_session` 方法系统性地保存重要辩论会话。
3. **优化搜索查询**:
- 使用具体、明确的查询词以提高搜索相关性。
- 结合 `memory_type` 过滤器缩小搜索范围。
4. **错误处理**:
- 在生产环境中，务必对所有异步操作进行适当的错误处理和重试机制。
## 未来扩展
1. **混合后端支持**: 允许同时使用多个后端，根据数据类型或访问模式进行路由。
2. **记忆压缩与摘要**: 自动对长篇记忆进行摘要，提高检索效率。
3. **情感分析**: 为记忆添加情感标签，丰富检索维度。
---
*此文档旨在为开发者提供 Memory Bank 模块的全面技术参考*

59
modules/documentation-suite/docs/n8n_mongodb_upsert_config.md Normal file
View File

@@ -0,0 +1,59 @@
# n8n MongoDB去重配置
## 方案1: JS函数 + MongoDB Upsert
### JS函数节点配置
使用 `scripts/n8n_minimal_news.js` 的代码，只做基本处理和本批次去重。
### MongoDB节点配置
1. **操作类型**: Update
2. **Collection**: articles
3. **Update Key**: title (用标题作为唯一键)
4. **Upsert**: 启用 ✅
5. **Update Document**:
```json
{
"$setOnInsert": {
"id": "={{$json.id}}",
"title": "={{$json.title}}",
"published_time": "={{$json.published_time}}",
"source_url": "={{$json.source_url}}",
"created_at": "={{new Date().toISOString()}}"
},
"$set": {
"last_seen": "={{new Date().toISOString()}}"
}
}
```
## 方案2: 纯MongoDB节点去重
### MongoDB节点配置
1. **操作类型**: Update Many
2. **Collection**: articles
3. **Filter**: `{"title": "={{$json.title}}"}`
4. **Upsert**: 启用 ✅
5. **Update**:
```json
{
"$setOnInsert": {
"title": "={{$json.title}}",
"published_time": "={{$json.published_time}}",
"source_url": "={{$json.source_url}}",
"created_at": "={{new Date().toISOString()}}"
}
}
```
## 推荐方案
使用**方案1**，因为：
- JS函数生成连续的ID
- MongoDB只负责去重插入
- 逻辑清晰，易于调试
## 测试步骤
1. 第一次运行：应该插入所有新文章
2. 第二次运行：应该0条插入（全部跳过）
3. 检查数据库：确认没有重复标题

38
modules/documentation-suite/docs/openbb_integration/00_PROJECT_OVERVIEW.md Normal file
View File

@@ -0,0 +1,38 @@
# OpenBB 集成项目总览
本目录构建了本项目中 OpenBB v4 集成的完整文档生态，包括架构、实现、测试、用户指南、文化融合与维护。
## 目标
- 以 OpenBB v4 作为统一市场数据路由入口（`from openbb import obb`）
- 在未安装或不可用时，提供稳健的兜底策略（演示/合成数据）
- 将集成能力与稷下学宫/八仙论道的产品体验深度融合
## 核心组件
- UI：`app/tabs/openbb_tab.py`（自动检测 OpenBB 可用性，提供回退）
- 引擎：`src/jixia/engines/openbb_engine.py`、`src/jixia/engines/openbb_stock_data.py`
- 示例/演示数据：`examples/data/*.json`
## 用户旅程（摘要）
```mermaid
graph TD
A[用户启动应用] --> B[选择OpenBB标签页]
B --> C[查看数据可用性状态]
C --> D{OpenBB是否可用?}
D -->|是| E[选择股票符号]
D -->|否| F[使用演示数据]
E --> G[启动八仙论道]
F --> G
G --> H[查看辩论结果]
H --> I[导出分析报告]
```
## 快速链接
- 实现指南（API 集成与回退策略）：[02_IMPLEMENTATION_GUIDE/api_integration_guide.md](../openbb_integration/02_IMPLEMENTATION_GUIDE/api_integration_guide.md)
- 故障排查：[02_IMPLEMENTATION_GUIDE/troubleshooting_guide.md](../openbb_integration/02_IMPLEMENTATION_GUIDE/troubleshooting_guide.md)
- 测试策略与报告：[03_TEST_DOCUMENTATION/](../openbb_integration/03_TEST_DOCUMENTATION/)
- 用户指南：[04_USER_GUIDES/](../openbb_integration/04_USER_GUIDES/)
## 维护与路线图
- 版本说明与升级：见 [06_MAINTENANCE](../openbb_integration/06_MAINTENANCE/)
> 注：本结构与 docs/AI_AGENT_TASKS/ROVODEV_PROJECT_INTEGRATION.md 的“文档架构”保持一致，以便多团队协作与交付。

3
modules/documentation-suite/docs/openbb_integration/01_ARCHITECTURE_DESIGN/data_flow_design.md Normal file
View File

@@ -0,0 +1,3 @@
# 数据流设计
占位：将补充从 UI 输入 -> 引擎 -> OpenBB/provider -> DataFrame -> KPI/图表 的完整数据流与序列图。

7
modules/documentation-suite/docs/openbb_integration/01_ARCHITECTURE_DESIGN/deployment_strategy.md Normal file
View File

@@ -0,0 +1,7 @@
# 部署策略
- OpenBB 作为可选依赖提供，默认不强制安装
- 在需要时通过 `pip install "openbb>=4.1.0"` 启用
- 国内网络场景建议使用镜像或代理
后续将补充 CI/CD、环境矩阵与缓存策略。

7
modules/documentation-suite/docs/openbb_integration/01_ARCHITECTURE_DESIGN/integration_patterns.md Normal file
View File

@@ -0,0 +1,7 @@
# 集成模式
- 路由优先：`obb.equity.price.historical`，必要时回退到 `obb.etf.price.historical`
- 结果标准化：兼容 `.to_df()` / `.to_dataframe()` / 原始对象 -> DataFrame
- 列规范化：Date / Close 归一化，保证后续图表与 KPI 计算稳定
后续将补充更多模式（基本面/新闻/宏观等）。

17
modules/documentation-suite/docs/openbb_integration/01_ARCHITECTURE_DESIGN/system_architecture.md Normal file
View File

@@ -0,0 +1,17 @@
# 系统架构（Qwen 输出）
本章描述 OpenBB 集成在系统中的位置、边界与依赖。
## 组件边界
- UI 层：`app/tabs/openbb_tab.py`
- 引擎层：`src/jixia/engines/openbb_engine.py`、`openbb_stock_data.py`
- 数据层：OpenBB provider（yfinance、polygon、fmp 等）与演示/合成数据
## 关键架构决策
- 使用 OpenBB v4 统一路由
- 延迟导入（lazy import）降低对未安装环境的侵入
- 明确回退机制，保证用户体验连续性
## 后续补充
- 数据流与上下行依赖
- 与“八仙论道”系统的耦合点与解耦方案

56
modules/documentation-suite/docs/openbb_integration/02_IMPLEMENTATION_GUIDE/api_integration_guide.md Normal file
View File

@@ -0,0 +1,56 @@
# OpenBB 集成指南（迁移版）
本页介绍 OpenBB v4 在本项目中的安装、配置、代码结构、回退机制、开发与测试、典型问题与后续计划。
## 1. 为什么选择 OpenBB v4
- 统一的路由接口：`from openbb import obb`
- 多数据提供商聚合（如 yfinance、polygon、fmp 等）
- 返回对象支持 `.results` 或 `.to_df()`，便于统一处理
## 2. 安装与环境准备
默认未安装 OpenBB（requirements.txt 中为可选依赖）。如需启用：
```bash
pip install "openbb>=4.1.0"
```
若你使用的是国内网络，建议配置合适的 PyPI 镜像或使用代理。
## 3. 配置说明
无需额外配置即可使用 `provider='yfinance'` 的公共数据。若你有付费数据源（如 polygon），可通过环境变量或 OpenBB 的 provider 配置进行设置。
## 4. 代码结构与调用方式
- Streamlit UI: `app/tabs/openbb_tab.py`
- 自动检测 OpenBB 是否可用；若不可用则使用演示数据或合成数据
- 优先路由：`obb.equity.price.historical`，ETF 回退至 `obb.etf.price.historical`
- 引擎模块: `src/jixia/engines/openbb_engine.py`
- 延迟导入 OpenBB：首次调用时 `from openbb import obb`
- 对 `.results` / `.to_df()` / `.to_dataframe()` 做兼容处理
- 辅助脚本: `src/jixia/engines/openbb_stock_data.py`
- 延迟导入 `obb`
- ETF 历史数据路径更新为 `obb.etf.price.historical`
## 5. 回退机制
- UI 层（OpenBB Tab）
- 未安装 OpenBB 或请求失败：读取 `examples/data/*.json` 的演示数据；仍失败则生成合成数据
- 引擎层
- 若未安装 OpenBB：返回 `success=False`，带错误消息，不影响其他功能
## 6. 开发与测试
- 单元测试建议：
- 未安装 OpenBB 时，`_load_price_data` 能返回演示/合成数据
- 已安装 OpenBB 时，能通过 `obb.equity.price.historical` 获取 DataFrame
- 在本仓库中新增了占位测试：`tests/test_openbb_fallback.py`
## 7. 典型问题排查
- ImportError: No module named 'openbb'
- 未安装 OpenBB；按第2节安装。
- 返回空数据
- 检查 symbol 是否正确；尝试更换 provider 或缩短时间窗口。
- 列名/索引不匹配
- UI 中已对常见列/索引做了规范化处理；如仍异常，可打印原始 DataFrame 排查。
## 8. 后续计划
- 接入更多 OpenBB 路由（基本面、新闻、财报、因子）
- 与辩论系统结果联动，生成投资洞察卡片
- 支持用户自定义 provider 优先级与兜底策略

10
modules/documentation-suite/docs/openbb_integration/02_IMPLEMENTATION_GUIDE/core_engine_implementation.md Normal file
View File

@@ -0,0 +1,10 @@
# 核心引擎实现（Claude 输出）
- 延迟导入 OpenBB
- 统一结果转 DataFrame
- 列/索引规范化与时间窗口裁剪
- 失败时不影响其他功能（返回 success=False 或进入兜底路径）
参考代码位置：
- `src/jixia/engines/openbb_engine.py`
- `src/jixia/engines/openbb_stock_data.py`

8
modules/documentation-suite/docs/openbb_integration/02_IMPLEMENTATION_GUIDE/troubleshooting_guide.md Normal file
View File

@@ -0,0 +1,8 @@
# 故障排查指南
常见问题与解决方案：
- ImportError: No module named 'openbb' → 安装 `openbb>=4.1.0`
- 返回空数据 → 检查 symbol，尝试其他 provider 或缩短时间窗口
- 列名/索引不匹配 → 打印原始 DataFrame，参考 UI 中的规范化逻辑
更多请参考：[api_integration_guide.md](./api_integration_guide.md) 第 7 节。

6
modules/documentation-suite/docs/openbb_integration/02_IMPLEMENTATION_GUIDE/ui_enhancement_guide.md Normal file
View File

@@ -0,0 +1,6 @@
# UI 增强指南
- 状态提示（OpenBB 可用/不可用）
- 动态参数（symbol、时间窗口）
- KPI 卡片（最新价、近30日涨幅、最大回撤）
- 未来扩展位：基本面、新闻、情绪、宏观等

3
modules/documentation-suite/docs/openbb_integration/03_TEST_DOCUMENTATION/performance_benchmarks.md Normal file
View File

@@ -0,0 +1,3 @@
# 性能基准
占位：记录不同 provider 与窗口设置下的响应时间、吞吐、内存曲线。

6
modules/documentation-suite/docs/openbb_integration/03_TEST_DOCUMENTATION/quality_assurance_report.md Normal file
View File

@@ -0,0 +1,6 @@
# 质量保证报告
- 代码规范检查
- 文档完整性
- 测试通过率
- 文化准确性与用户体验评估（与 05_CULTURAL_INTEGRATION 联动）

3
modules/documentation-suite/docs/openbb_integration/03_TEST_DOCUMENTATION/test_results_report.md Normal file
View File

@@ -0,0 +1,3 @@
# 测试结果报告
占位：记录关键用例、环境、通过率与截图/日志摘要。

6
modules/documentation-suite/docs/openbb_integration/03_TEST_DOCUMENTATION/test_strategy.md Normal file
View File

@@ -0,0 +1,6 @@
# 测试策略（Gemini 输出）
- 未安装 OpenBB：UI 能回退到演示/合成数据
- 已安装 OpenBB：能成功调用 `obb.equity.price.historical`
- 数据清洗后具有 Date/Close 列，KPI 计算不报错
- 覆盖边界：空数据、异常路由、索引为日期等

6
modules/documentation-suite/docs/openbb_integration/04_USER_GUIDES/best_practices.md Normal file
View File

@@ -0,0 +1,6 @@
# 最佳实践
- 将 OpenBB 作为轻依赖，必要时再安装
- 使用统一的 DataFrame 规范化逻辑
- 谨慎处理长时间窗口与缺失数据
- 提供清晰的状态反馈与兜底

5
modules/documentation-suite/docs/openbb_integration/04_USER_GUIDES/configuration_guide.md Normal file
View File

@@ -0,0 +1,5 @@
# 配置指南
- 默认使用公共数据（yfinance）
- 付费 provider（polygon/fmp 等）可通过 OpenBB provider 配置或环境变量设置
- UI 参数：symbol、时间窗口、KPI 展示

8
modules/documentation-suite/docs/openbb_integration/04_USER_GUIDES/getting_started.md Normal file
View File

@@ -0,0 +1,8 @@
# 入门指南
1) 可选安装：`pip install "openbb>=4.1.0"`
2) 运行应用，进入 OpenBB 标签页
3) 输入股票/ETF 代码（如 AAPL），选择时间窗口
4) 若未安装 OpenBB，将自动使用演示数据
更多：见 [API 实现指南](../02_IMPLEMENTATION_GUIDE/api_integration_guide.md)。

3
modules/documentation-suite/docs/openbb_integration/04_USER_GUIDES/immortal_debate_tutorial.md Normal file
View File

@@ -0,0 +1,3 @@
# 八仙论道教程（占位）
将补充如何基于市场数据触发与解读“八仙论道”的步骤与最佳实践。

3
modules/documentation-suite/docs/openbb_integration/05_CULTURAL_INTEGRATION/cultural_accuracy_guidelines.md Normal file
View File

@@ -0,0 +1,3 @@
# 文化准确性指南（占位）
将补充文化审核检查点、示例与注意事项。

3
modules/documentation-suite/docs/openbb_integration/05_CULTURAL_INTEGRATION/immortal_characteristics.md Normal file
View File

@@ -0,0 +1,3 @@
# 八仙特质（占位）
将列举八仙角色特性，并映射到数据分析风格/观点生成策略。

4
modules/documentation-suite/docs/openbb_integration/05_CULTURAL_INTEGRATION/jixia_philosophy_in_code.md Normal file
View File

@@ -0,0 +1,4 @@
# 稷下学宫哲学在代码中的体现（占位）
- 开放包容、百家争鸣 → 多 provider 聚合与辩论系统
- 求同存异、理性决策 → 数据驱动 + 观点对齐

5
modules/documentation-suite/docs/openbb_integration/06_MAINTENANCE/future_roadmap.md Normal file
View File

@@ -0,0 +1,5 @@
# 路线图
- v1.x：路由扩展、稳定性增强
- v2.x：高级分析与移动端适配
- v3.x：企业级能力与治理

4
modules/documentation-suite/docs/openbb_integration/06_MAINTENANCE/known_issues.md Normal file
View File

@@ -0,0 +1,4 @@
# 已知问题
- 某些 symbol 在特定 provider 下返回为空或字段不齐
- 长窗口数据清洗后为空的边界情况

4
modules/documentation-suite/docs/openbb_integration/06_MAINTENANCE/release_notes.md Normal file
View File

@@ -0,0 +1,4 @@
# 发布说明
- 参考：`docs/development/RELEASE_v2.0.0.md`
- 在此记录 OpenBB 集成相关的变更、修复与新增功能。

5
modules/documentation-suite/docs/openbb_integration/06_MAINTENANCE/upgrade_guide.md Normal file
View File

@@ -0,0 +1,5 @@
# 升级指南
- OpenBB 版本升级注意事项
- provider 配置兼容性
- 本项目接口变化记录

36
modules/documentation-suite/docs/openbb_integration/README.md Normal file
View File

@@ -0,0 +1,36 @@
# OpenBB 集成文档索引
本目录提供 OpenBB v4 在本项目中的完整集成文档。
- 00 项目总览：./00_PROJECT_OVERVIEW.md
- 01 架构设计（Qwen 输出）：
- ./01_ARCHITECTURE_DESIGN/system_architecture.md
- ./01_ARCHITECTURE_DESIGN/data_flow_design.md
- ./01_ARCHITECTURE_DESIGN/integration_patterns.md
- ./01_ARCHITECTURE_DESIGN/deployment_strategy.md
- 02 实现指南（Claude 输出）：
- ./02_IMPLEMENTATION_GUIDE/core_engine_implementation.md
- ./02_IMPLEMENTATION_GUIDE/api_integration_guide.md
- ./02_IMPLEMENTATION_GUIDE/ui_enhancement_guide.md
- ./02_IMPLEMENTATION_GUIDE/troubleshooting_guide.md
- 03 测试文档（Gemini 输出）：
- ./03_TEST_DOCUMENTATION/test_strategy.md
- ./03_TEST_DOCUMENTATION/test_results_report.md
- ./03_TEST_DOCUMENTATION/performance_benchmarks.md
- ./03_TEST_DOCUMENTATION/quality_assurance_report.md
- 04 用户指南：
- ./04_USER_GUIDES/getting_started.md
- ./04_USER_GUIDES/immortal_debate_tutorial.md
- ./04_USER_GUIDES/configuration_guide.md
- ./04_USER_GUIDES/best_practices.md
- 05 文化融合文档：
- ./05_CULTURAL_INTEGRATION/immortal_characteristics.md
- ./05_CULTURAL_INTEGRATION/jixia_philosophy_in_code.md
- ./05_CULTURAL_INTEGRATION/cultural_accuracy_guidelines.md
- 06 维护：
- ./06_MAINTENANCE/release_notes.md
- ./06_MAINTENANCE/upgrade_guide.md
- ./06_MAINTENANCE/known_issues.md
- ./06_MAINTENANCE/future_roadmap.md
快速入口：API 实现指南 → ./02_IMPLEMENTATION_GUIDE/api_integration_guide.md

196
modules/documentation-suite/docs/rapidapi/api_inventory.md Normal file
View File

@@ -0,0 +1,196 @@
# RapidAPI 订阅清单
## 📋 概览
基于Doppler配置和实际测试，记录当前RapidAPI订阅的API服务及其可用性。
**API密钥**: `[REDACTED - 从Doppler获取RAPIDAPI_KEY]`
**总订阅数**: 17个API服务
**最后更新**: 2025-08-02
## ✅ 已验证可用的API (4个)
### 1. Alpha Vantage (`alpha-vantage.p.rapidapi.com`) ⚡
- **状态**: ✅ 可用 (响应时间: 1.26s)
- **用途**: 股票基本面数据、财报数据
- **测试结果**: 成功获取AAPL全球报价数据
- **数据字段**: Global Quote
- **端点**:
- `/query?function=GLOBAL_QUOTE&symbol={symbol}` - 实时报价
- `/query?function=OVERVIEW&symbol={symbol}` - 公司概览
- `/query?function=EARNINGS&symbol={symbol}` - 财报数据
### 2. Webull (`webull.p.rapidapi.com`) ⚡
- **状态**: ✅ 可用 (响应时间: 1.56s)
- **用途**: 股票搜索、报价
- **测试结果**: 成功获取AAPL搜索数据
- **数据字段**: stocks, busiModel
- **端点**:
- `/stock/search?keyword={symbol}` - 股票搜索
- `/market/get-active-gainers` - 活跃涨幅股
### 3. Yahoo Finance 15 (`yahoo-finance15.p.rapidapi.com`)
- **状态**: ✅ 可用 (响应时间: 2.07s)
- **用途**: 实时股价、市场数据
- **测试结果**: 成功获取AAPL报价数据
- **数据字段**: meta, body
- **端点**:
- `/api/yahoo/qu/quote/{symbol}` - 股票报价
- `/api/yahoo/co/collections/day_gainers` - 涨幅榜
- `/api/yahoo/co/collections/day_losers` - 跌幅榜
### 4. Seeking Alpha (`seeking-alpha.p.rapidapi.com`)
- **状态**: ✅ 可用 (响应时间: 3.32s)
- **用途**: 股票分析、新闻
- **测试结果**: 成功获取AAPL分析数据
- **数据字段**: data
- **端点**:
- `/symbols/get-profile?symbols={symbol}` - 股票档案
- `/news/list?category=market-news` - 市场新闻
## ❌ 未订阅或失败的API (13个)
### 权限问题 (403 Forbidden)
以下API显示"You are not subscribed to this API"，表示未订阅：
- **yahoo_finance_api_data** (`yahoo-finance-api1.p.rapidapi.com`)
- **yahoo_finance_basic** (`yahoo-finance127.p.rapidapi.com`)
- **morning_star** (`morningstar1.p.rapidapi.com`)
- **investing_com** (`investing-cryptocurrency-markets.p.rapidapi.com`)
- **finance_api** (`real-time-finance-data.p.rapidapi.com`)
### API不存在 (404 Not Found)
以下API显示"API doesn't exists"，可能已下线：
- **yahoo_finance_realtime** (`yahoo-finance-low-latency.p.rapidapi.com`)
- **tradingview** (`tradingview-ta.p.rapidapi.com`)
- **sec_filings** (`sec-filings.p.rapidapi.com`)
### 端点错误 (404 Endpoint Not Found)
以下API存在但端点路径不正确：
- **yh_finance** (`yh-finance-complete.p.rapidapi.com`)
- **ms_finance** (`ms-finance.p.rapidapi.com`)
- **exchangerate_api** (`exchangerate-api.p.rapidapi.com`)
- **crypto_news** (`cryptocurrency-news2.p.rapidapi.com`)
### 无响应数据 (204 No Content)
- **yh_finance_complete** (`yh-finance.p.rapidapi.com`) - 返回空响应
## 🔄 需要进一步测试的API
### 8. YH Finance Complete (`yh-finance.p.rapidapi.com`)
- **状态**: 🟡 待测试
- **用途**: 完整的Yahoo Finance数据
### 9. Yahoo Finance API Data (`yahoo-finance-api1.p.rapidapi.com`)
- **状态**: 🟡 待测试
- **用途**: Yahoo Finance API数据
### 10. Yahoo Finance Low Latency (`yahoo-finance-low-latency.p.rapidapi.com`)
- **状态**: 🟡 待测试
- **用途**: 低延迟实时数据
### 11. YH Finance Complete (`yh-finance-complete.p.rapidapi.com`)
- **状态**: 🟡 待测试
- **用途**: 完整金融数据
### 12. Yahoo Finance 127 (`yahoo-finance127.p.rapidapi.com`)
- **状态**: 🟡 待测试
- **用途**: Yahoo Finance基础数据
### 13. Real Time Finance Data (`real-time-finance-data.p.rapidapi.com`)
- **状态**: 🟡 待测试
- **用途**: 实时金融数据
### 14. MS Finance (`ms-finance.p.rapidapi.com`)
- **状态**: 🟡 待测试
- **用途**: 微软金融数据
### 15. SEC Filings (`sec-filings.p.rapidapi.com`)
- **状态**: 🟡 待测试
- **用途**: SEC文件数据
### 16. ExchangeRate API (`exchangerate-api.p.rapidapi.com`)
- **状态**: 🟡 待测试
- **用途**: 汇率数据
### 17. Cryptocurrency News 2 (`cryptocurrency-news2.p.rapidapi.com`)
- **状态**: 🟡 待测试
- **用途**: 加密货币新闻
## 📊 使用统计
### 成功率分析
- **可用API**: 4/17 (23.5%)
- **未订阅API**: 5/17 (29.4%)
- **API不存在**: 3/17 (17.6%)
- **端点错误**: 4/17 (23.5%)
- **其他问题**: 1/17 (5.9%)
### 八仙论道中的API使用情况
- **吕洞宾**: Alpha Vantage ✅
- **何仙姑**: Yahoo Finance 15 ✅
- **张果老**: Seeking Alpha ✅
- **韩湘子**: 多个API失败 ❌
- **汉钟离**: 多个API失败 ❌
- **蓝采和**: Webull ✅
- **曹国舅**: Seeking Alpha ✅
- **铁拐李**: 多个API失败 ❌
## 🔧 优化建议
### 1. 端点配置优化
- 需要为每个API配置正确的端点路径
- 研究各API的具体参数要求
- 添加更多数据类型的端点映射
### 2. 故障转移策略
- 优先使用已验证可用的API
- 将Yahoo Finance系列API作为主要数据源
- Alpha Vantage作为基本面数据的首选
### 3. API测试计划
- 逐个测试待测试的API
- 记录每个API的具体用法和限制
- 建立API健康检查机制
## 📝 测试记录
### 2025-08-02 全面测试记录
```
✅ alpha_vantage: 1.26s - 成功获取AAPL全球报价
✅ webull: 1.56s - 成功获取AAPL搜索数据
✅ yahoo_finance_1: 2.07s - 成功获取AAPL报价数据
✅ seeking_alpha: 3.32s - 成功获取AAPL分析数据
❌ yahoo_finance_api_data: 403 - 未订阅
❌ yahoo_finance_basic: 403 - 未订阅
❌ morning_star: 403 - 未订阅
❌ investing_com: 403 - 未订阅
❌ finance_api: 403 - 未订阅
❌ yahoo_finance_realtime: 404 - API不存在
❌ tradingview: 404 - API不存在
❌ sec_filings: 404 - API不存在
❌ yh_finance: 404 - 端点不存在
❌ ms_finance: 404 - 端点不存在
❌ exchangerate_api: 404 - 端点不存在
❌ crypto_news: 404 - 端点不存在
❌ yh_finance_complete: 204 - 无响应数据
```
## 🚀 下一步行动
1. **完善端点配置**: 为所有API添加正确的端点映射
2. **批量测试**: 使用自动化脚本测试所有待测试API
3. **文档更新**: 根据测试结果更新此文档
4. **性能优化**: 基于可用性调整八仙论道的API分配策略
---
**维护者**: Ben
**联系方式**: 通过Doppler配置管理API密钥
**更新频率**: 每次API测试后更新

341
modules/documentation-suite/docs/rapidapi/jixia_load_balancing_strategy.md Normal file
View File

@@ -0,0 +1,341 @@
# 🏛️ 稷下学宫八仙论道负载分担策略
## 📋 概述
基于现有的RapidAPI订阅和雅虎财经数据接口，设计一套智能负载分担策略，让八仙论道系统中的不同角色调用不同的API端点获取相同类型的数据，实现API负载均衡和系统稳定性。
## 🎯 核心理念
**"同样的数据，不同的路径"** - 通过多API轮换获取相同类型的市场数据，避免单一API过载，确保系统稳定运行。
## 📊 可用API资源清单
### ✅ 已验证可用的API (4个)
```python
AVAILABLE_APIS = {
'alpha_vantage': {
'host': 'alpha-vantage.p.rapidapi.com',
'response_time': 1.26,
'rate_limit': '500/min, 500k/month',
'specialty': ['stock_quote', 'company_overview', 'earnings']
},
'yahoo_finance_15': {
'host': 'yahoo-finance15.p.rapidapi.com',
'response_time': 2.07,
'rate_limit': '500/min, 500k/month',
'specialty': ['stock_quote', 'market_movers', 'news']
},
'webull': {
'host': 'webull.p.rapidapi.com',
'response_time': 1.56,
'rate_limit': '500/min, 500k/month',
'specialty': ['stock_search', 'market_gainers']
},
'seeking_alpha': {
'host': 'seeking-alpha.p.rapidapi.com',
'response_time': 3.32,
'rate_limit': '500/min, 500k/month',
'specialty': ['company_profile', 'market_analysis']
}
}
```
## 🎭 八仙负载分担配置
### 数据类型映射策略
```python
DATA_TYPE_API_MAPPING = {
# 股票报价数据 - 3个API可提供
'stock_quote': {
'吕洞宾': 'alpha_vantage', # 主力剑仙用最快的API
'何仙姑': 'yahoo_finance_15', # 风控专家用稳定的API
'张果老': 'webull', # 技术分析师用搜索强的API
'韩湘子': 'alpha_vantage', # 基本面研究用专业API
'汉钟离': 'yahoo_finance_15', # 量化专家用市场数据API
'蓝采和': 'webull', # 情绪分析师用活跃数据API
'曹国舅': 'seeking_alpha', # 宏观分析师用分析API
'铁拐李': 'alpha_vantage' # 逆向投资用基础数据API
},
# 公司概览数据 - 2个API可提供
'company_overview': {
'吕洞宾': 'alpha_vantage', # 技术分析需要完整数据
'何仙姑': 'seeking_alpha', # 风控需要分析师观点
'张果老': 'alpha_vantage', # 技术分析偏好数据API
'韩湘子': 'seeking_alpha', # 基本面研究需要深度分析
'汉钟离': 'alpha_vantage', # 量化需要结构化数据
'蓝采和': 'seeking_alpha', # 情绪分析需要市场观点
'曹国舅': 'seeking_alpha', # 宏观分析需要专业观点
'铁拐李': 'alpha_vantage' # 逆向投资需要基础数据
},
# 市场动态数据 - 2个API可提供
'market_movers': {
'吕洞宾': 'yahoo_finance_15', # 剑仙关注市场热点
'何仙姑': 'webull', # 风控关注活跃股票
'张果老': 'yahoo_finance_15', # 技术分析关注涨跌榜
'韩湘子': 'webull', # 基本面研究关注搜索热度
'汉钟离': 'yahoo_finance_15', # 量化关注市场数据
'蓝采和': 'webull', # 情绪分析关注活跃度
'曹国舅': 'yahoo_finance_15', # 宏观关注整体趋势
'铁拐李': 'webull' # 逆向投资关注异常股票
},
# 新闻和分析数据 - 2个API可提供
'market_news': {
'吕洞宾': 'yahoo_finance_15', # 剑仙需要快速资讯
'何仙姑': 'seeking_alpha', # 风控需要深度分析
'张果老': 'yahoo_finance_15', # 技术分析关注市场新闻
'韩湘子': 'seeking_alpha', # 基本面需要分析师观点
'汉钟离': 'yahoo_finance_15', # 量化关注数据驱动新闻
'蓝采和': 'seeking_alpha', # 情绪分析需要市场情绪
'曹国舅': 'seeking_alpha', # 宏观需要政策分析
'铁拐李': 'yahoo_finance_15' # 逆向投资关注反向指标
}
}
```
## 🔄 智能轮换策略
### 1. 时间窗口轮换
```python
TIME_BASED_ROTATION = {
# 交易时段 (9:30-16:00 EST) - 优先使用快速API
'trading_hours': {
'primary_apis': ['alpha_vantage', 'webull'],
'backup_apis': ['yahoo_finance_15', 'seeking_alpha']
},
# 非交易时段 - 可以使用较慢但更详细的API
'after_hours': {
'primary_apis': ['seeking_alpha', 'yahoo_finance_15'],
'backup_apis': ['alpha_vantage', 'webull']
}
}
```
### 2. 负载感知轮换
```python
LOAD_AWARE_ROTATION = {
# 当某个API接近限制时，自动切换到其他API
'rate_limit_thresholds': {
'alpha_vantage': 450, # 90% of 500/min
'yahoo_finance_15': 450,
'webull': 450,
'seeking_alpha': 450
},
# 故障转移优先级
'failover_priority': {
'alpha_vantage': ['webull', 'yahoo_finance_15'],
'yahoo_finance_15': ['webull', 'alpha_vantage'],
'webull': ['alpha_vantage', 'yahoo_finance_15'],
'seeking_alpha': ['yahoo_finance_15', 'alpha_vantage']
}
}
```
## 🏗️ 实现架构
### 核心组件
```python
class JixiaLoadBalancer:
"""稷下学宫负载均衡器"""
def __init__(self):
self.api_pool = APIPool(AVAILABLE_APIS)
self.immortal_mapping = DATA_TYPE_API_MAPPING
self.rate_limiter = RateLimiter()
self.health_checker = APIHealthChecker()
def get_data_for_immortal(self, immortal_name: str, data_type: str, symbol: str):
"""为特定仙人获取数据"""
# 1. 获取该仙人的首选API
preferred_api = self.immortal_mapping[data_type][immortal_name]
# 2. 检查API健康状态和速率限制
if self.is_api_available(preferred_api):
return self.call_api(preferred_api, data_type, symbol)
# 3. 故障转移到备用API
backup_apis = LOAD_AWARE_ROTATION['failover_priority'][preferred_api]
for backup_api in backup_apis:
if self.is_api_available(backup_api):
return self.call_api(backup_api, data_type, symbol)
# 4. 如果所有API都不可用，返回缓存数据
return self.get_cached_data(data_type, symbol)
def is_api_available(self, api_name: str) -> bool:
"""检查API是否可用"""
# 检查健康状态
if not self.health_checker.is_healthy(api_name):
return False
# 检查速率限制
if self.rate_limiter.is_rate_limited(api_name):
return False
return True
```
### 数据统一化处理
```python
class DataNormalizer:
"""数据标准化处理器"""
def normalize_stock_quote(self, raw_data: dict, api_source: str) -> dict:
"""将不同API的股票报价数据标准化"""
if api_source == 'alpha_vantage':
return self._normalize_alpha_vantage_quote(raw_data)
elif api_source == 'yahoo_finance_15':
return self._normalize_yahoo_quote(raw_data)
elif api_source == 'webull':
return self._normalize_webull_quote(raw_data)
def _normalize_alpha_vantage_quote(self, data: dict) -> dict:
"""标准化Alpha Vantage数据格式"""
global_quote = data.get('Global Quote', {})
return {
'symbol': global_quote.get('01. symbol'),
'price': float(global_quote.get('05. price', 0)),
'change': float(global_quote.get('09. change', 0)),
'change_percent': global_quote.get('10. change percent', '0%'),
'volume': int(global_quote.get('06. volume', 0)),
'source': 'alpha_vantage'
}
def _normalize_yahoo_quote(self, data: dict) -> dict:
"""标准化Yahoo Finance数据格式"""
body = data.get('body', {})
return {
'symbol': body.get('symbol'),
'price': float(body.get('regularMarketPrice', 0)),
'change': float(body.get('regularMarketChange', 0)),
'change_percent': f"{body.get('regularMarketChangePercent', 0):.2f}%",
'volume': int(body.get('regularMarketVolume', 0)),
'source': 'yahoo_finance_15'
}
```
## 📊 监控和统计
### API使用统计
```python
class APIUsageMonitor:
"""API使用监控器"""
def __init__(self):
self.usage_stats = {
'alpha_vantage': {'calls': 0, 'errors': 0, 'avg_response_time': 0},
'yahoo_finance_15': {'calls': 0, 'errors': 0, 'avg_response_time': 0},
'webull': {'calls': 0, 'errors': 0, 'avg_response_time': 0},
'seeking_alpha': {'calls': 0, 'errors': 0, 'avg_response_time': 0}
}
def record_api_call(self, api_name: str, response_time: float, success: bool):
"""记录API调用统计"""
stats = self.usage_stats[api_name]
stats['calls'] += 1
if not success:
stats['errors'] += 1
# 更新平均响应时间
current_avg = stats['avg_response_time']
total_calls = stats['calls']
stats['avg_response_time'] = (current_avg * (total_calls - 1) + response_time) / total_calls
def get_load_distribution(self) -> dict:
"""获取负载分布统计"""
total_calls = sum(stats['calls'] for stats in self.usage_stats.values())
if total_calls == 0:
return {}
return {
api: {
'percentage': (stats['calls'] / total_calls) * 100,
'success_rate': ((stats['calls'] - stats['errors']) / stats['calls']) * 100 if stats['calls'] > 0 else 0,
'avg_response_time': stats['avg_response_time']
}
for api, stats in self.usage_stats.items()
}
```
## 🎯 实施计划
### 第一阶段：基础负载均衡
1. **实现核心负载均衡器** - 基本的API轮换逻辑
2. **数据标准化处理** - 统一不同API的数据格式
3. **简单故障转移** - 基本的备用API切换
### 第二阶段：智能优化
1. **速率限制监控** - 实时监控API使用情况
2. **健康检查机制** - 定期检测API可用性
3. **性能优化** - 基于响应时间优化API选择
### 第三阶段：高级功能
1. **预测性负载均衡** - 基于历史数据预测API负载
2. **成本优化** - 基于API成本优化调用策略
3. **实时监控面板** - 可视化API使用情况
## 📈 预期效果
### 性能提升
- **API负载分散**: 单个API负载降低60-70%
- **系统稳定性**: 故障率降低80%以上
- **响应速度**: 平均响应时间提升30%
### 成本控制
- **API使用优化**: 避免单一API过度使用
- **故障恢复**: 减少因API故障导致的数据缺失
- **扩展性**: 支持更多API的无缝接入
## 🔧 配置示例
### 环境配置
```bash
# Doppler环境变量
RAPIDAPI_KEY=your_rapidapi_key
ALPHA_VANTAGE_API_KEY=your_alpha_vantage_key
# 负载均衡配置
LOAD_BALANCER_ENABLED=true
API_HEALTH_CHECK_INTERVAL=300 # 5分钟
RATE_LIMIT_BUFFER=50 # 保留50个请求的缓冲
```
### 使用示例
```python
# 在稷下学宫系统中使用
from jixia_load_balancer import JixiaLoadBalancer
load_balancer = JixiaLoadBalancer()
# 八仙论道时，每个仙人获取数据
for immortal in ['吕洞宾', '何仙姑', '张果老', '韩湘子', '汉钟离', '蓝采和', '曹国舅', '铁拐李']:
quote_data = load_balancer.get_data_for_immortal(immortal, 'stock_quote', 'TSLA')
overview_data = load_balancer.get_data_for_immortal(immortal, 'company_overview', 'TSLA')
print(f"{immortal}: 获取到{quote_data['source']}的数据")
```
---
## 🎉 总结
通过这套负载分担策略，稷下学宫八仙论道系统可以：
1. **智能分配API调用** - 不同仙人使用不同API获取相同数据
2. **实现真正的负载均衡** - 避免单一API过载
3. **提高系统稳定性** - 多重故障转移保障
4. **优化成本效益** - 充分利用现有API资源
5. **支持无缝扩展** - 新API可轻松接入系统
**"八仙过海，各显神通"** - 让每个仙人都有自己的数据获取路径，共同构建稳定可靠的智能投资决策系统！🚀

165
modules/documentation-suite/docs/rapidapi/optimized_config.md Normal file
View File

@@ -0,0 +1,165 @@
# 优化的RapidAPI配置
基于实际测试结果，优化八仙论道系统的API配置。
## 🎯 可用API配置 (4个)
### 高性能API (响应时间 < 2s)
```python
FAST_APIS = {
'alpha_vantage': {
'host': 'alpha-vantage.p.rapidapi.com',
'response_time': 1.26,
'data_types': ['quote', 'overview', 'earnings'],
'specialty': 'fundamental_analysis'
},
'webull': {
'host': 'webull.p.rapidapi.com',
'response_time': 1.56,
'data_types': ['search', 'quote', 'gainers'],
'specialty': 'stock_search'
}
}
```
### 标准API (响应时间 2-4s)
```python
STANDARD_APIS = {
'yahoo_finance_1': {
'host': 'yahoo-finance15.p.rapidapi.com',
'response_time': 2.07,
'data_types': ['quote', 'gainers', 'losers'],
'specialty': 'market_data'
},
'seeking_alpha': {
'host': 'seeking-alpha.p.rapidapi.com',
'response_time': 3.32,
'data_types': ['profile', 'news'],
'specialty': 'analysis_news'
}
}
```
## 🎭 优化的八仙API分配
基于可用API重新分配八仙的数据源：
```python
OPTIMIZED_IMMORTAL_APIS = {
'吕洞宾': { # 技术分析专家
'primary': 'alpha_vantage',
'backup': ['yahoo_finance_1'],
'data_type': 'overview',
'specialty': 'comprehensive_analysis'
},
'何仙姑': { # 风险控制专家
'primary': 'yahoo_finance_1',
'backup': ['webull'],
'data_type': 'quote',
'specialty': 'risk_management'
},
'张果老': { # 历史数据分析师
'primary': 'seeking_alpha',
'backup': ['alpha_vantage'],
'data_type': 'profile',
'specialty': 'fundamental_analysis'
},
'韩湘子': { # 新兴资产专家
'primary': 'webull',
'backup': ['yahoo_finance_1'],
'data_type': 'search',
'specialty': 'emerging_trends'
},
'汉钟离': { # 热点追踪
'primary': 'yahoo_finance_1',
'backup': ['webull'],
'data_type': 'gainers',
'specialty': 'hot_trends'
},
'蓝采和': { # 潜力股发现
'primary': 'webull',
'backup': ['alpha_vantage'],
'data_type': 'search',
'specialty': 'undervalued_stocks'
},
'曹国舅': { # 机构分析
'primary': 'seeking_alpha',
'backup': ['alpha_vantage'],
'data_type': 'profile',
'specialty': 'institutional_analysis'
},
'铁拐李': { # 逆向投资
'primary': 'alpha_vantage',
'backup': ['seeking_alpha'],
'data_type': 'overview',
'specialty': 'contrarian_analysis'
}
}
```
## 📊 端点映射
### Alpha Vantage
```python
'alpha_vantage': {
'quote': f'/query?function=GLOBAL_QUOTE&symbol={symbol}',
'overview': f'/query?function=OVERVIEW&symbol={symbol}',
'earnings': f'/query?function=EARNINGS&symbol={symbol}'
}
```
### Yahoo Finance 15
```python
'yahoo_finance_1': {
'quote': f'/api/yahoo/qu/quote/{symbol}',
'gainers': '/api/yahoo/co/collections/day_gainers',
'losers': '/api/yahoo/co/collections/day_losers'
}
```
### Seeking Alpha
```python
'seeking_alpha': {
'profile': f'/symbols/get-profile?symbols={symbol}',
'news': '/news/list?category=market-news'
}
```
### Webull
```python
'webull': {
'search': f'/stock/search?keyword={symbol}',
'gainers': '/market/get-active-gainers'
}
```
## 🚀 性能优化建议
### 1. API优先级策略
- **第一优先级**: Alpha Vantage, Webull (< 2s)
- **第二优先级**: Yahoo Finance 15 (2-3s)
- **第三优先级**: Seeking Alpha (3-4s)
### 2. 故障转移策略
- 快速API之间互为备份
- 避免使用不可用的API作为备份
- 设置合理的超时时间 (8s)
### 3. 负载均衡
- 将高频请求分散到不同API
- 避免单一API过载
- 监控API使用统计
## 💡 实施建议
1. **更新永动机引擎**: 移除不可用的API配置
2. **优化八仙分配**: 基于API可用性重新分配
3. **添加健康检查**: 定期测试API可用性
4. **监控和告警**: 跟踪API响应时间和成功率
## 📈 预期效果
- **成功率提升**: 从当前的60%提升到95%+
- **响应时间**: 平均响应时间从3s降低到2s
- **稳定性**: 减少API调用失败导致的辩论中断
- **用户体验**: 更快的辩论响应和更稳定的数据获取

112
modules/documentation-suite/docs/rapidapi/test_report_20250802_120925.md Normal file
View File

@@ -0,0 +1,112 @@
# RapidAPI 测试报告
## 📊 测试概览
- **测试时间**: 2025-08-02 12:09:25
- **总API数**: 17
- **成功数**: 4 (23.5%)
- **失败数**: 13 (76.5%)
## ✅ 可用的API (4个)
### alpha_vantage
- **主机**: `alpha-vantage.p.rapidapi.com`
- **响应时间**: 1.26s
- **数据字段**: Global Quote
### webull
- **主机**: `webull.p.rapidapi.com`
- **响应时间**: 1.56s
- **数据字段**: stocks, busiModel
### yahoo_finance_1
- **主机**: `yahoo-finance15.p.rapidapi.com`
- **响应时间**: 2.07s
- **数据字段**: meta, body
### seeking_alpha
- **主机**: `seeking-alpha.p.rapidapi.com`
- **响应时间**: 3.32s
- **数据字段**: data
## ❌ 失败的API (13个)
### yh_finance_complete
- **主机**: `yh-finance.p.rapidapi.com`
- **状态码**: 204
- **错误**: Unknown...
### yahoo_finance_api_data
- **主机**: `yahoo-finance-api1.p.rapidapi.com`
- **状态码**: 403
- **错误**: {"message":"You are not subscribed to this API."}...
### yahoo_finance_realtime
- **主机**: `yahoo-finance-low-latency.p.rapidapi.com`
- **状态码**: 404
- **错误**: {"message":"API doesn't exists"}...
### yh_finance
- **主机**: `yh-finance-complete.p.rapidapi.com`
- **状态码**: 404
- **错误**: {"message":"Endpoint '\/stock\/v2\/get-summary' does not exist"}...
### yahoo_finance_basic
- **主机**: `yahoo-finance127.p.rapidapi.com`
- **状态码**: 403
- **错误**: {"message":"You are not subscribed to this API."}...
### morning_star
- **主机**: `morningstar1.p.rapidapi.com`
- **状态码**: 403
- **错误**: {"message":"You are not subscribed to this API."}...
### tradingview
- **主机**: `tradingview-ta.p.rapidapi.com`
- **状态码**: 404
- **错误**: {"message":"API doesn't exists"}...
### investing_com
- **主机**: `investing-cryptocurrency-markets.p.rapidapi.com`
- **状态码**: 403
- **错误**: {"message":"You are not subscribed to this API."}...
### finance_api
- **主机**: `real-time-finance-data.p.rapidapi.com`
- **状态码**: 403
- **错误**: {"message":"You are not subscribed to this API."}...
### ms_finance
- **主机**: `ms-finance.p.rapidapi.com`
- **状态码**: 404
- **错误**: {"message":"Endpoint '\/stock\/v2\/get-summary' does not exist"}...
### sec_filings
- **主机**: `sec-filings.p.rapidapi.com`
- **状态码**: 404
- **错误**: {"message":"API doesn't exists"}...
### exchangerate_api
- **主机**: `exchangerate-api.p.rapidapi.com`
- **状态码**: 404
- **错误**: {"message":"Endpoint '\/latest' does not exist"}...
### crypto_news
- **主机**: `cryptocurrency-news2.p.rapidapi.com`
- **状态码**: 404
- **错误**: {"message":"Endpoint '\/v1\/cryptonews' does not exist"}...
## 🔧 优化建议
### 立即可用的API
以下API响应快速，建议优先使用：
- **alpha_vantage**: 1.26s
- **webull**: 1.56s
### 需要修复的API
以下API需要检查端点配置或权限：
- **yh_finance_complete**: Unknown error...
- **yahoo_finance_api_data**: {"message":"You are not subscribed to this API."}...
- **yahoo_finance_realtime**: {"message":"API doesn't exists"}...
- **yh_finance**: {"message":"Endpoint '\/stock\/v2\/get-summary' do...
- **yahoo_finance_basic**: {"message":"You are not subscribed to this API."}...

123
modules/documentation-suite/docs/requirements.md Normal file
View File

@@ -0,0 +1,123 @@
# 炼妖壶项目清理与重构需求文档
## 介绍
炼妖壶项目经过长期开发，积累了大量代码和配置文件，但项目结构变得混乱，存在安全隐患（密钥泄露）和维护困难。本规范旨在系统性地清理和重构项目，建立清晰的架构和安全的开发流程。
## 需求
### 需求1：项目结构清理
**用户故事：** 作为开发者，我希望项目有清晰的目录结构和文件组织，以便快速理解和维护代码。
#### 验收标准
1. WHEN 查看项目根目录 THEN 应该只包含必要的核心文件和目录
2. WHEN 查看任何目录 THEN 应该有清晰的README说明其用途
3. WHEN 寻找特定功能代码 THEN 应该能在预期的目录中找到
4. WHEN 删除无用文件后 THEN 项目仍能正常运行
5. IF 文件超过6个月未使用 THEN 应该被归档或删除
### 需求2：安全配置管理
**用户故事：** 作为开发者，我希望所有密钥和敏感配置都安全管理，不会意外泄露到代码库中。
#### 验收标准
1. WHEN 扫描代码库 THEN 不应该发现任何硬编码的密钥或敏感信息
2. WHEN 开发者需要密钥 THEN 应该从环境变量或Doppler获取
3. WHEN 提交代码 THEN 应该自动检查是否包含敏感信息
4. WHEN 新开发者加入 THEN 应该有清晰的密钥管理指南
5. IF 发现密钥泄露 THEN 应该有自动化的处理流程
### 需求3：核心功能保留
**用户故事：** 作为用户，我希望在项目重构后，所有核心功能（AI辩论、数据分析、Streamlit界面）仍然可用。
#### 验收标准
1. WHEN 启动Streamlit应用 THEN 应该能正常访问所有功能页面
2. WHEN 运行AI辩论 THEN 应该能正常生成辩论内容
3. WHEN 连接数据库 THEN 应该能正常读写数据
4. WHEN 调用外部API THEN 应该能正常获取响应
5. WHEN 运行测试 THEN 所有核心功能测试应该通过
### 需求4：开发体验优化
**用户故事：** 作为开发者，我希望有良好的开发体验，包括清晰的文档、简单的启动流程和有效的调试工具。
#### 验收标准
1. WHEN 新开发者克隆项目 THEN 应该能在10分钟内启动应用
2. WHEN 查看文档 THEN 应该能找到所有必要的设置和使用说明
3. WHEN 遇到问题 THEN 应该有清晰的故障排除指南
4. WHEN 添加新功能 THEN 应该有明确的开发规范可遵循
5. WHEN 部署应用 THEN 应该有自动化的部署流程
### 需求5：技术债务清理
**用户故事：** 作为维护者，我希望清理技术债务，移除过时的代码和依赖，提高代码质量。
#### 验收标准
1. WHEN 检查依赖 THEN 不应该有未使用或过时的包
2. WHEN 运行代码分析 THEN 不应该有严重的代码质量问题
3. WHEN 查看代码 THEN 应该有一致的编码风格和注释
4. WHEN 运行性能测试 THEN 应用响应时间应该在可接受范围内
5. IF 发现重复代码 THEN 应该被重构为可复用的模块
### 需求6：部署和运维简化
**用户故事：** 作为运维人员，我希望部署和监控应用变得简单可靠。
#### 验收标准
1. WHEN 部署到生产环境 THEN 应该使用一键部署脚本
2. WHEN 应用运行异常 THEN 应该有清晰的日志和监控信息
3. WHEN 需要扩展 THEN 应该支持水平扩展
4. WHEN 备份数据 THEN 应该有自动化的备份策略
5. WHEN 回滚版本 THEN 应该能快速回滚到稳定版本
## 优先级
1. **P0 (紧急)**: 安全配置管理 - 立即解决密钥泄露问题
2. **P1 (高)**: 项目结构清理 - 建立清晰的项目架构
3. **P2 (中)**: 核心功能保留 - 确保重构不影响核心功能
4. **P3 (中)**: 开发体验优化 - 改善开发流程
5. **P4 (低)**: 技术债务清理 - 长期代码质量改进
6. **P5 (低)**: 部署和运维简化 - 运维流程优化
## 迁移策略
鉴于当前项目状态混乱，采用**全新开始**的策略：
1. **文档先行** - 完善所有需求和设计文档
2. **干净迁移** - 在新目录 `/home/ben/liurenchaxin` 重新开始
3. **选择性迁移** - 只迁移核心功能代码，抛弃历史包袱
4. **安全优先** - 从一开始就建立安全的配置管理
## 核心功能清单（需要保留）
### 必须迁移的功能
- 🤖 **稷下学宫AI辩论系统** (八仙辩论)
- 📊 **Streamlit主界面**
- 🔗 **Doppler配置管理**
- 💾 **数据库连接** (PostgreSQL, MongoDB, Zilliz)
- 🔌 **外部API集成** (OpenRouter, Anthropic等)
### 可选迁移的功能
- 📈 **金融数据分析**
- 🔄 **N8N工作流**
- 📱 **MCP服务器**
- 🧪 **实验性功能**
## 成功标准
项目重构成功的标志：
- ✅ 通过GitGuardian安全扫描，无密钥泄露
- ✅ 项目目录结构清晰，符合最佳实践
- ✅ 所有核心功能正常工作
- ✅ 新开发者能在10分钟内启动项目
- ✅ 代码质量评分达到B级以上
- ✅ 部署时间缩短到5分钟以内
- ✅ 完全摆脱历史技术债务

74
modules/documentation-suite/docs/vertex_memory_banks.md Normal file
View File

@@ -0,0 +1,74 @@
# 八仙记忆银行文档 (Vertex AI)
每个八仙智能体都有一个专属的记忆银行，用于存储其在不同辩论主题下的记忆。这些记忆包括对话历史、个人偏好、知识库和策略洞察。
## 记忆类型
1. **对话记忆 (conversation)**: 智能体在特定辩论中的发言和互动记录。
2. **偏好记忆 (preference)**: 智能体的投资偏好、分析方法和决策倾向。
3. **知识记忆 (knowledge)**: 智能体掌握的金融知识、市场信息和分析模型。
4. **策略记忆 (strategy)**: 智能体在辩论中使用的论证策略和战术。
## 八仙记忆银行列表
- **铁拐李 (tieguaili)**
- ID: `memory_bank_tieguaili_{PROJECT_ID}`
- 特点: 擅长技术分析和风险控制
- **汉钟离 (hanzhongli)**
- ID: `memory_bank_hanzhongli_{PROJECT_ID}`
- 特点: 注重基本面分析和长期价值
- **张果老 (zhangguolao)**
- ID: `memory_bank_zhangguolao_{PROJECT_ID}`
- 特点: 擅长宏观趋势分析和周期判断
- **蓝采和 (lancaihe)**
- ID: `memory_bank_lancaihe_{PROJECT_ID}`
- 特点: 关注市场情绪和资金流向
- **何仙姑 (hexiangu)**
- ID: `memory_bank_hexiangu_{PROJECT_ID}`
- 特点: 精于财务数据分析和估值模型
- **吕洞宾 (lvdongbin)**
- ID: `memory_bank_lvdongbin_{PROJECT_ID}`
- 特点: 善于多维度综合分析和创新策略
- **韩湘子 (hanxiangzi)**
- ID: `memory_bank_hanxiangzi_{PROJECT_ID}`
- 特点: 擅长行业比较和相对价值分析
- **曹国舅 (caoguojiu)**
- ID: `memory_bank_caoguojiu_{PROJECT_ID}`
- 特点: 注重合规性、社会责任和ESG因素
## 使用方法
```python
from src.jixia.memory.factory import get_memory_backend
# 获取记忆后端 (自动根据环境变量选择)
memory_bank = get_memory_backend()
# 为吕洞宾添加偏好记忆
await memory_bank.add_memory(
agent_name="lvdongbin",
content="倾向于使用DCF模型评估科技股的内在价值",
memory_type="preference",
debate_topic="TSLA投资分析"
)
# 搜索吕洞宾关于TSLA的记忆
memories = await memory_bank.search_memories(
agent_name="lvdongbin",
query="TSLA",
memory_type="preference"
)
# 获取上下文
context = await memory_bank.get_agent_context("lvdongbin", "TSLA投资分析")
```
---
*此文档由系统自动生成和维护*