refactor: 重构项目结构和文件组织
- 将文档文件移动到docs目录下分类存放 - 将测试文件移动到tests目录 - 将工具脚本移动到tools目录 - 更新README中的文件路径说明 - 删除重复和过时的文件 - 优化项目目录结构，提升可维护性
This commit is contained in:
ben
67
docs/architecture/GEMINI_ARCH_REVIEW.md
Normal file
67
docs/architecture/GEMINI_ARCH_REVIEW.md
Normal 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
docs/architecture/PROJECT_SUMMARY.md
Normal file
44
docs/architecture/PROJECT_SUMMARY.md
Normal 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. **清晰的职责划分**：每个模块都有明确的功能定位
|
||||
162
docs/custom_modules_tutorial.md
Normal file
162
docs/custom_modules_tutorial.md
Normal 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.
|
||||
114
docs/development/GAMEFI_FSM_INTEGRATION_PLAN.md
Normal file
114
docs/development/GAMEFI_FSM_INTEGRATION_PLAN.md
Normal 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. **模拟与回测:** 构建一个模拟环境，使用历史交易数据回测该集成系统的有效性，验证其是否能在关键时刻做出正确的状态转移。
|
||||
136
docs/development/MIGRATION_STATUS.md
Normal file
136
docs/development/MIGRATION_STATUS.md
Normal 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] **doppler_config.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
docs/development/RELEASE_v2.0.0.md
Normal file
197
docs/development/RELEASE_v2.0.0.md
Normal 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辩论更有智慧，让预测更有力量！
|
||||
|
||||
160
docs/guides/MEMORY_BANK_ACCESS_GUIDE.md
Normal file
160
docs/guides/MEMORY_BANK_ACCESS_GUIDE.md
Normal 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
docs/guides/MEMORY_BANK_ACCESS_SOLUTION.md
Normal file
152
docs/guides/MEMORY_BANK_ACCESS_SOLUTION.md
Normal 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
docs/guides/MEMORY_BANK_USER_GUIDE.md
Normal file
76
docs/guides/MEMORY_BANK_USER_GUIDE.md
Normal 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投资分析")
|
||||
```
|
||||
236
docs/guides/QUICK_START_GUIDE.md
Normal file
236
docs/guides/QUICK_START_GUIDE.md
Normal 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`
|
||||
- 🚀 开始构建您的投资分析系统！
|
||||
|
||||
---
|
||||
*🏛️ 稷下学宫 - 智慧投资，从负载均衡开始*
|
||||
152
docs/guides/shushu-demo-results.md
Normal file
152
docs/guides/shushu-demo-results.md
Normal 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 方案，我们的系统在数据访问速度、查询精确性和成本控制方面都有显著优势，为术数典籍的数字化应用提供了一个理想的技术解决方案。
|
||||
@@ -1,111 +0,0 @@
|
||||
# n8n RSS去重工作流配置
|
||||
|
||||
## 问题解决方案
|
||||
|
||||
你的原始代码每次执行都会生成新的`article_id`，导致相同文章被重复插入。现在通过以下方案彻底解决：
|
||||
|
||||
### 1. 稳定ID生成策略
|
||||
|
||||
使用**内容哈希**而非时间戳生成稳定的文章ID：
|
||||
|
||||
```javascript
|
||||
// 基于标题+发布时间+内容片段生成稳定ID
|
||||
function generateStableId(title, pubDate, content) {
|
||||
const normalizedTitle = title.trim().toLowerCase();
|
||||
const contentHash = content ? content.substring(0, 100) : '';
|
||||
const dateStr = pubDate || '';
|
||||
|
||||
const combined = normalizedTitle + '|' + dateStr + '|' + contentHash;
|
||||
|
||||
let hash = 0;
|
||||
for (let i = 0; i < combined.length; i++) {
|
||||
const char = combined.charCodeAt(i);
|
||||
hash = ((hash << 5) - hash) + char;
|
||||
hash = hash & hash;
|
||||
}
|
||||
return Math.abs(hash).toString(16);
|
||||
}
|
||||
```
|
||||
|
||||
### 2. n8n节点配置
|
||||
|
||||
#### 节点1: RSS Feed Reader
|
||||
- 配置多个RSS源
|
||||
- 设置合理的抓取频率（建议30分钟-1小时）
|
||||
|
||||
#### 节点2: 数据预处理 (Code节点)
|
||||
```javascript
|
||||
// 使用 scripts/n8n_deduplication_fix.js 中的代码
|
||||
// 主要功能：
|
||||
// 1. 生成稳定的article_id
|
||||
// 2. 查询数据库已存在文章
|
||||
// 3. 过滤重复内容
|
||||
// 4. 添加content_hash字段
|
||||
```
|
||||
|
||||
#### 节点3: MongoDB插入 (Code节点)
|
||||
```javascript
|
||||
// 使用 scripts/n8n_safe_insert.js 中的代码
|
||||
// 使用upsert操作避免重复插入
|
||||
```
|
||||
|
||||
### 3. 数据库索引优化
|
||||
|
||||
已创建的索引：
|
||||
- `article_id_unique`: 基于article_id的唯一索引
|
||||
- `title_unique`: 基于title的索引
|
||||
- `content_hash_index`: 基于content_hash的索引
|
||||
|
||||
### 4. 新增字段说明
|
||||
|
||||
| 字段名 | 类型 | 说明 |
|
||||
|--------|------|------|
|
||||
| `article_id` | String | 基于内容生成的稳定ID，确保唯一性 |
|
||||
| `content_hash` | String | 内容哈希，用于检测内容变化 |
|
||||
| `source_url` | String | 原文链接 |
|
||||
| `last_updated` | String | 最后更新时间 |
|
||||
|
||||
### 5. 工作流执行效果
|
||||
|
||||
- **去重前**: 160篇文章（包含80篇重复）
|
||||
- **去重后**: 80篇唯一文章
|
||||
- **重复检测**: 支持标题和内容双重检测
|
||||
- **稳定性**: 多次执行不会产生重复数据
|
||||
|
||||
### 6. 监控和维护
|
||||
|
||||
#### 定期检查重复数据
|
||||
```bash
|
||||
python scripts/cleanup_duplicates.py
|
||||
```
|
||||
|
||||
#### 查看去重统计
|
||||
```javascript
|
||||
// 在n8n中添加统计节点
|
||||
db.articles.aggregate([
|
||||
{$group: {_id: "$title", count: {$sum: 1}}},
|
||||
{$match: {count: {$gt: 1}}},
|
||||
{$count: "duplicates"}
|
||||
])
|
||||
```
|
||||
|
||||
### 7. 最佳实践
|
||||
|
||||
1. **定期清理**: 每周运行一次清理脚本
|
||||
2. **监控日志**: 关注n8n执行日志中的去重信息
|
||||
3. **索引维护**: 定期检查索引性能
|
||||
4. **备份策略**: 在大量数据操作前备份数据库
|
||||
|
||||
### 8. 故障排除
|
||||
|
||||
#### 如果仍有重复数据
|
||||
1. 检查RSS源是否返回相同内容但不同时间戳
|
||||
2. 验证哈希函数是否正确处理特殊字符
|
||||
3. 确认MongoDB连接配置正确
|
||||
|
||||
#### 性能优化
|
||||
1. 调整RSS抓取频率
|
||||
2. 使用批量插入而非单条插入
|
||||
3. 定期清理过期数据
|
||||
|
||||
现在你的n8n工作流可以安全地多次执行，不会产生重复数据！
|
||||
Reference in New Issue
Block a user