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. **清晰的职责划分**：每个模块都有明确的功能定位
|
||||
Reference in New Issue
Block a user