🔮 Full Multi-Agent 紫微斗數 AI 系統

🌟 世界首創的多智能體協作紫微斗數 AI 分析系統
結合 Claude、GPT、專業領域智能體與 RAG 檢索技術，提供前所未有的命理分析體驗

📸 系統展示

🎨 前端界面展示

輸入界面	分析過程	結果展示

🖥️ 後端系統展示

Multi-Agent 協作過程	完整分析結果

🎯 系統特色

🤖 革命性 Multi-Agent 協作架構

• 🧠 Claude Agent: 深度邏輯推理與結構化分析專家
• ✨ GPT Agent: 創意表達與人性化解釋大師
• 🎯 Domain Agent: 專業領域分析專家（愛情/財富/未來）
• 🎭 智能協調器: 管理 Agent 討論、辯論與共識達成
• 💬 動態討論機制: 多輪協作對話，確保分析深度與準確性

🔍 先進 RAG 知識檢索系統

• 🌐 BGE-M3 嵌入模型: HuggingFace 最先進的多語言嵌入技術
• 💾 ChromaDB 向量數據庫: 高效持久化向量存儲與檢索
• 📚 專業知識庫: 整合《紫微斗數集成全書》等權威資料
• 🔄 智能檢索增強: 動態上下文注入，提升分析準確性

🌐 現代化全棧 Web 應用

• ⚡ FastAPI 後端: 高性能異步 API 服務
• 🎨 React 前端: 現代化響應式用戶界面
• 🎭 Material-UI: 精美的 UI 組件庫
• ✨ Framer Motion: 流暢的動畫效果
• 🧙‍♂️ 巫師主題: 神秘的占卜動畫體驗

🔧 Web 爬蟲整合系統

• 🕷️ 自動命盤獲取: 整合紫微斗數專業網站
• 📊 智能數據解析: 自動解析命盤結構與星曜配置
• 🔄 實時數據處理: 即時獲取最新命盤信息

🌟 系統特色

🤖 Multi-Agent 協作架構

• Claude Agent: 專精邏輯推理和結構化分析
• GPT Agent: 擅長創意表達和故事化解釋
• Domain Agents: 專門領域分析（愛情、財富、未來運勢）
• 協調器: 管理 Agent 間的討論和共識達成

📚 RAG 知識系統

• 使用 HuggingFace BGE-M3 嵌入模型
• 持久化向量資料庫（Chroma）
• 紫微斗數專業知識庫
• 智能檢索和上下文增強

🎯 多種輸出格式

• JSON 格式: 結構化數據輸出
• 論述格式: 自然語言分析報告
• JSON 轉論述: 結合精確分析與易讀輸出

🔧 靈活配置

• 可選擇不同分析領域（愛情、財富、未來、綜合）
• 可控制 Agent 協作過程顯示
• 支援多種輸出格式切換

📁 完整項目架構

Full-Multi-Agent/
├── 📱 前端系統 (React)
│   ├── frontend/
│   │   ├── src/
│   │   │   ├── components/
│   │   │   │   ├── ZiweiForm.js              # 🎯 用戶輸入表單
│   │   │   │   ├── LoadingAnimation.js       # ⏳ 標準載入動畫
│   │   │   │   ├── WizardDivination.js       # 🧙‍♂️ 巫師占卜動畫
│   │   │   │   ├── ResultDisplay.js          # 📊 結果顯示 (Markdown)
│   │   │   │   ├── Header.js                 # 🎨 頁面標題
│   │   │   │   └── SimpleBackground.js       # 🌌 背景組件
│   │   │   ├── App.js                        # 🚀 主應用組件
│   │   │   ├── App.css                       # 🎨 全局樣式
│   │   │   └── index.js                      # 🔗 React 入口點
│   │   ├── public/
│   │   │   └── wizard_icon/                  # 🧙‍♂️ 巫師主題圖標
│   │   ├── package.json                      # 📦 前端依賴配置
│   │   └── package-lock.json                 # 🔒 依賴版本鎖定
│
├── 🚀 後端系統 (FastAPI)
│   ├── src/
│   │   ├── agents/                           # 🤖 Multi-Agent 系統
│   │   │   ├── base_agent.py                 # 🏗️ Agent 基礎類別
│   │   │   ├── claude_agent.py               # 🧠 Claude 智能體
│   │   │   ├── gpt_agent.py                  # ✨ GPT 智能體
│   │   │   └── domain_agent.py               # 🎯 領域專家智能體
│   │   ├── coordination/                     # 🎭 協調系統
│   │   │   ├── coordinator.py                # 🎯 Multi-Agent 協調器
│   │   │   └── discussion.py                 # 💬 Agent 討論機制
│   │   ├── rag/                              # 🔍 RAG 檢索系統
│   │   │   ├── rag_system.py                 # 🎛️ RAG 主控制器
│   │   │   ├── bge_embeddings.py             # 🌐 BGE-M3 嵌入模型
│   │   │   ├── vector_store.py               # 💾 ChromaDB 向量數據庫
│   │   │   └── gpt4o_generator.py            # 🔄 GPT4o 知識生成器
│   │   ├── output/                           # 📝 輸出格式化
│   │   │   └── gpt4o_formatter.py            # 🎨 GPT4o 格式化器
│   │   ├── web_scraper/                      # 🕷️ Web 爬蟲系統
│   │   │   ├── ziwei_scraper.py              # 🔮 紫微斗數爬蟲
│   │   │   └── data_parser.py                # 📊 命盤數據解析器
│   │   ├── config/                           # ⚙️ 配置管理
│   │   │   └── settings.py                   # 🔧 系統配置
│   │   └── prompts/                          # 📝 Prompt 模板
│   │       └── system_prompts.py             # 🎯 系統 Prompt
│   ├── main.py                               # 🎮 系統主控制器
│   └── api_server.py                         # 🌐 FastAPI 服務器
│
├── 📊 數據與資源
│   ├── data/
│   │   ├── knowledge/                        # 📚 知識庫文件
│   │   └── vector_db/                        # 💾 向量數據庫
│   ├── vector_db_test1/                      # 🧪 測試向量數據庫
│   ├── wizard_icon/                          # 🧙‍♂️ 巫師圖標資源
│   ├── 前後端呈現畫面/                        # 📸 系統展示截圖
│   │   ├── 前端輸入個人資訊畫面.png            # 🎯 輸入界面
│   │   ├── 前端分析畫面.png                   # ⏳ 分析過程
│   │   ├── 前端分析結果畫面.png                # 📊 結果展示
│   │   ├── 前端分析後最後完整結果呈現.png       # 📋 完整結果
│   │   └── multi-agent後端畫面.png            # 🖥️ 後端協作
│   └── 紫微斗數集成全書.pdf                   # 📖 專業知識資料
│
├── 🔧 配置與工具
│   ├── .env                                  # 🔐 環境變數 (不在 Git 中)
│   ├── .env.example                          # 📋 配置範例
│   ├── .gitignore                            # 🚫 Git 忽略文件
│   ├── requirements.txt                      # 📦 Python 依賴
│   └── full-multi-agent.md                   # 📚 完整架構文檔
│
├── 🧪 測試與開發
│   ├── test_*.py                             # 🔬 各種測試腳本
│   ├── debug_*.py                            # 🐛 調試工具
│   └── examples/                             # 📝 使用範例
│
└── 📚 文檔系統
    ├── README.md                             # 📖 項目說明 (本文件)
    ├── COMPLETE_SYSTEM_ARCHITECTURE.md      # 🏗️ 完整系統架構
    ├── FRONTEND_SETUP.md                     # 🎨 前端設置指南
    ├── README_RAG.md                         # 🔍 RAG 系統說明
    ├── QUICK_START_GUIDE.md                  # 🚀 快速開始指南
    └── docs/                                 # 📚 詳細文檔
        └── rag_setup_guide.md                # 🔍 RAG 設置指南

🚀 快速開始

📋 系統需求

• Python: 3.9+
• Node.js: 16.0+
• 內存: 建議 8GB+
• 存儲: 建議 5GB+ 可用空間

1️⃣ 項目克隆與設置

# 克隆項目
git clone https://github.com/Tsai1030/Full-multi-agent.git
cd Full-multi-agent

# 創建 Python 虛擬環境 (推薦)
python -m venv myenv
source myenv/bin/activate  # Linux/Mac
# 或
myenv\Scripts\activate     # Windows

2️⃣ 後端設置

# 安裝 Python 依賴
pip install -r requirements.txt

# 複製環境變數範例
cp .env.example .env

編輯 .env 文件，填入您的 API 金鑰：

# 🔑 AI 模型 API 金鑰
OPENAI_API_KEY=sk-proj-your_openai_api_key_here
ANTHROPIC_API_KEY=sk-ant-your_anthropic_api_key_here

# 🤖 模型配置 (使用 GPT-4o Mini 節省成本)
OPENAI_MODEL_GPT4O=gpt-4o-mini
ANTHROPIC_MODEL=claude-3-5-sonnet-20241022

# 🔍 RAG 系統配置
EMBEDDING_MODEL=BAAI/bge-m3
EMBEDDING_PROVIDER=huggingface
EMBEDDING_DEVICE=cpu
VECTOR_DB_PATH=./data/vector_db

# 🕷️ 紫微斗數網站配置
ZIWEI_WEBSITE_URL=https://fate.windada.com/cgi-bin/fate
ZIWEI_REQUEST_TIMEOUT=30

# 🌐 服務配置
APP_HOST=localhost
APP_PORT=8000
CORS_ORIGINS=http://localhost:3000

3️⃣ 前端設置

# 進入前端目錄
cd frontend

# 安裝 Node.js 依賴
npm install

# 或使用 yarn
yarn install

4️⃣ 啟動系統

方法一：分別啟動前後端

# 終端 1: 啟動後端 (在項目根目錄)
python api_server.py
# 後端將在 http://localhost:8000 運行

# 終端 2: 啟動前端 (在 frontend 目錄)
cd frontend
npm start
# 前端將在 http://localhost:3000 運行

方法二：使用批處理腳本 (Windows)

# 啟動後端
start_server.bat

# 啟動前端 (在 frontend 目錄)
cd frontend
npm start

5️⃣ 訪問系統

1. 前端界面: http://localhost:3000
2. 後端 API: http://localhost:8000
3. API 文檔: http://localhost:8000/docs (Swagger UI)

🎯 首次使用

1. 打開前端界面 (http://localhost:3000)
2. 填入個人出生資訊：
   • 性別：男/女
   • 出生年月日
   • 出生時辰
3. 選擇分析領域：愛情💕 / 財富💰 / 未來🔮
4. 點擊「開始分析」
5. 欣賞巫師占卜動畫 🧙‍♂️
6. 查看詳細的 Markdown 格式分析結果 📊

⚙️ 系統配置

🎯 分析領域配置

系統支援四種專業分析領域：

🎨 輸出格式配置

# 在後端 API 中可選擇的輸出格式：
output_format="json"              # 📊 結構化 JSON 數據
output_format="narrative"         # 📝 純論述文字格式
output_format="json_to_narrative" # 🎯 JSON 分析 + 論述輸出 (推薦)

🤖 Agent 協作配置

# 控制 Multi-Agent 協作過程顯示
show_agent_process=True   # 🔍 顯示詳細協作過程 (開發/調試)
show_agent_process=False  # 🚀 隱藏過程細節 (生產環境)

# Agent 協作參數
MAX_DISCUSSION_ROUNDS=3   # 最大討論輪數
CONSENSUS_THRESHOLD=0.7   # 共識達成閾值
DISCUSSION_TIMEOUT=120    # 討論超時時間 (秒)

🔍 RAG 系統配置

# BGE-M3 嵌入模型配置
EMBEDDING_MODEL=BAAI/bge-m3       # 嵌入模型名稱
EMBEDDING_DEVICE=cpu              # 運行設備 (cpu/cuda)
EMBEDDING_BATCH_SIZE=32           # 批處理大小
EMBEDDING_MAX_LENGTH=8192         # 最大文本長度

# 向量數據庫配置
VECTOR_DB_PATH=./data/vector_db   # 數據庫路徑
COLLECTION_NAME=ziwei_knowledge   # 集合名稱
TOP_K=5                          # 檢索結果數量
MIN_SCORE=0.7                    # 最小相似度分數

🎭 前端界面配置

// 動畫配置
const useWizardAnimation = true;     // 🧙‍♂️ 使用巫師占卜動畫
const animationDuration = 190;      // ⏱️ 動畫持續時間 (秒)

// 主題配置
const theme = {
  palette: {
    mode: 'dark',                  // 🌙 深色主題
    primary: { main: '#667eea' },  // 🎨 主色調
    secondary: { main: '#764ba2' } // 🎨 輔助色調
  }
};

🏗️ 核心技術架構

🤖 Multi-Agent 協作系統

graph TD
    A[用戶輸入] --> B[命盤爬取]
    B --> C[Multi-Agent 協調器]
    C --> D[Claude Agent<br/>邏輯推理]
    C --> E[GPT Agent<br/>創意表達]
    C --> F[Domain Agent<br/>專業分析]
    D --> G[討論與共識]
    E --> G
    F --> G
    G --> H[RAG 知識增強]
    H --> I[格式化輸出]
    I --> J[前端展示]

🎭 Agent 協作流程

1. 🚀 初始化階段

   • 載入各 Agent 的專業 Prompt
   • 建立討論上下文環境
   • 設定協作參數

2. 🔍 並行分析階段

   • Claude Agent: 深度邏輯推理與結構分析
   • GPT Agent: 創意表達與人性化解釋
   • Domain Agent: 專業領域知識應用

3. 💬 討論協商階段

   • 多輪對話交流觀點
   • 辯論分歧點並尋求共識
   • 整合各方專業見解

4. 🎯 共識達成階段

   • 評估分析一致性
   • 形成統一結論
   • 準備最終輸出

🔍 RAG 檢索增強系統

graph LR
    A[查詢文本] --> B[BGE-M3 嵌入]
    B --> C[向量檢索]
    C --> D[ChromaDB]
    D --> E[相關文檔]
    E --> F[上下文增強]
    F --> G[GPT4o 生成]
    G --> H[增強結果]

📚 RAG 處理流程

1. 📄 文檔預處理

   # 文檔分塊與清理
   chunks = text_splitter.split_documents(documents)
   cleaned_chunks = preprocess_text(chunks)
   

2. 🌐 向量化嵌入

   # BGE-M3 嵌入生成
   embeddings = bge_model.encode(text_chunks)
   

3. 💾 向量存儲

   # ChromaDB 持久化存儲
   collection.add(
       documents=chunks,
       embeddings=embeddings,
       metadatas=metadata
   )
   

4. 🔎 相似度檢索

   # 基於查詢的檢索
   results = collection.query(
       query_embeddings=query_embedding,
       n_results=top_k
   )
   

5. 🔄 知識增強

   # 將檢索結果注入 Agent 分析
   enhanced_prompt = f"Context: {retrieved_docs}\nQuery: {user_query}"
   

🕷️ Web 爬蟲系統

class ZiweiScraper:
    async def get_ziwei_chart(self, birth_data):
        # 🔧 構建請求參數
        params = self.build_request_params(birth_data)

        # 🌐 發送 HTTP 請求
        response = await self.session.post(url, data=params)

        # 📊 解析 HTML 響應
        chart_data = self.parse_response(response.text)

        return chart_data

🎨 前端 Markdown 處理

// 自定義 Markdown 處理器
const processMarkdown = (text) => {
    // ## 標題 → <h2>
    text = text.replace(/^## (.+)$/gm, '<h2 class="md-h2">$1</h2>');

    // **粗體** → <strong>
    text = text.replace(/\*\*(.+?)\*\*/g, '<strong class="md-strong">$1</strong>');

    // 1. 列表 → <ol><li>
    text = text.replace(/^(\d+)\. (.+)$/gm, '<li class="md-li">$2</li>');

    return text;
};

📊 系統監控與性能

🔍 實時監控指標

📈 性能優化策略

# 🚀 成本優化
OPENAI_MODEL_GPT4O=gpt-4o-mini    # 節省 90%+ API 成本

# ⚡ 速度優化
EMBEDDING_DEVICE=cuda             # GPU 加速 (如可用)
EMBEDDING_BATCH_SIZE=64           # 增加批處理大小

# 🎯 準確性優化
TOP_K=10                          # 增加檢索結果數量
MIN_SCORE=0.8                     # 提高相似度閾值

🔧 調試工具

# 🧪 測試腳本
python test_gpt4o_mini.py         # 測試 GPT-4o Mini 配置
python test_main_system.py        # 測試主系統功能
python test_rag_system.py         # 測試 RAG 檢索系統
python test_markdown_output.py    # 測試 Markdown 輸出

# 🐛 調試工具
python debug_claude_agent.py      # 調試 Claude Agent
python debug_settings.py          # 調試配置設定
python debug_website.py           # 調試網站爬蟲

🛠️ 開發指南

🆕 添加新的 Agent

# 1. 創建新 Agent 類
class NewAgent(BaseAgent):
    def __init__(self, agent_id="new_agent"):
        super().__init__(
            agent_id=agent_id,
            role=AgentRole.CUSTOM_ANALYSIS,
            model_name="your-model",
            logger=logger
        )

    async def analyze(self, context):
        # 實現分析邏輯
        return analysis_result

# 2. 在協調器中註冊
coordinator.add_agent(NewAgent())

🎨 擴展輸出格式

# 在 GPT4oFormatter 中添加新格式
class GPT4oFormatter:
    async def format_custom_style(self, result, context):
        # 實現自定義格式化邏輯
        return formatted_result

    # 更新格式選擇邏輯
    format_methods = {
        "json": self.format_json,
        "narrative": self.format_narrative,
        "custom": self.format_custom_style  # 新格式
    }

📝 自定義 Prompt 模板

# 在 src/prompts/system_prompts.py 中添加
CUSTOM_DOMAIN_PROMPT = """
你是專精於 {domain} 領域的紫微斗數專家...
請根據以下命盤信息進行深度分析：
{chart_data}
"""

# 使用自定義 Prompt
agent.set_system_prompt(CUSTOM_DOMAIN_PROMPT.format(
    domain="健康養生",
    chart_data=chart_info
))

🔌 API 擴展

# 在 api_server.py 中添加新端點
@app.post("/analyze_custom")
async def analyze_custom(request: CustomRequest):
    # 實現自定義分析邏輯
    result = await ai_system.custom_analysis(request.data)
    return CustomResponse(**result)

🎯 前端組件擴展

// 創建新的分析結果組件
const CustomResultDisplay = ({ result, onAction }) => {
    return (
        <Box sx={{ /* 自定義樣式 */ }}>
            {/* 自定義渲染邏輯 */}
        </Box>
    );
};

// 在 App.js 中整合
{currentStep === 'custom-result' && (
    <CustomResultDisplay
        result={analysisResult}
        onAction={handleCustomAction}
    />
)}

� 部署指南

🐳 Docker 部署 (推薦)

# Dockerfile 範例
FROM python:3.9-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
EXPOSE 8000

CMD ["python", "api_server.py"]

# docker-compose.yml
version: '3.8'
services:
  backend:
    build: .
    ports:
      - "8000:8000"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    volumes:
      - ./data:/app/data

  frontend:
    build: ./frontend
    ports:
      - "3000:3000"
    depends_on:
      - backend

☁️ 雲端部署

Vercel (前端)

cd frontend
vercel --prod

Railway/Heroku (後端)

# 設置環境變數
railway variables set OPENAI_API_KEY=your_key
railway deploy

🔧 故障排除

常見問題與解決方案

🔍 日誌查看

# 查看系統日誌
tail -f logs/ziwei_ai.log

# 查看特定錯誤
grep "ERROR" logs/ziwei_ai.log

# 查看 Agent 協作過程
grep "Agent" logs/ziwei_ai.log

📈 性能基準

🎯 測試環境

• CPU: Intel i7-10700K
• 內存: 16GB DDR4
• GPU: NVIDIA RTX 3070 (可選)

⏱️ 性能指標

�📝 版本更新日誌

🎉 v2.0.0 (2025-07-13) - 當前版本

• ✨ 全新前端界面: React + Material-UI + Framer Motion
• 🧙‍♂️ 巫師主題動畫: 神秘的占卜載入體驗
• 📝 Markdown 格式支持: 結構化結果顯示
• 🔧 GPT-4o Mini 整合: 節省 90%+ API 成本
• 🕷️ Web 爬蟲系統: 自動命盤數據獲取
• 🎨 響應式設計: 完美適配各種設備
• 🔍 增強 RAG 系統: 更精準的知識檢索

📋 v1.5.0 (2025-07-12)

• 🤖 Multi-Agent 協作優化: 改進討論機制
• 📚 知識庫擴充: 新增專業命理資料
• 🎯 領域專精: 愛情、財富、未來三大領域
• 🔄 輸出格式多樣化: JSON、論述、混合格式

🚀 v1.0.0 (2025-07-10)

• ✅ 初始版本發布: 基礎 Multi-Agent 系統
• 🔍 RAG 檢索系統: BGE-M3 + ChromaDB
• 📊 命令行界面: 基礎功能實現

🌟 未來規劃

🎯 短期目標 (1-3 個月)

• 🔐 用戶認證系統: 個人化分析記錄
• 📱 移動端 App: React Native 跨平台應用
• 🎨 主題定制: 多種視覺主題選擇
• 📊 分析歷史: 個人命理分析記錄
• 🔔 通知系統: 重要運勢提醒

🚀 中期目標 (3-6 個月)

• 🤖 更多 AI 模型: 整合 Gemini、Claude-3 等
• 🌐 多語言支持: 英文、日文界面
• 📈 數據分析: 用戶行為與偏好分析
• 🎯 個性化推薦: AI 驅動的個人建議
• 💬 社區功能: 用戶交流與分享

🌈 長期願景 (6-12 個月)

• 🧠 自學習系統: 基於用戶反饋的模型優化
• 🌍 全球化部署: 多地區雲端服務
• 🎓 教育模式: 紫微斗數學習系統
• 🤝 專家合作: 與命理大師合作優化
• 🔬 學術研究: 發表相關研究論文

📄 開源協議

本項目採用 MIT License 開源協議。

MIT License

Copyright (c) 2025 Tsai1030

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

🤝 貢獻指南

🎯 如何貢獻

1. 🍴 Fork 項目: 點擊右上角 Fork 按鈕
2. 🌿 創建分支: git checkout -b feature/amazing-feature
3. 💻 提交更改: git commit -m 'Add amazing feature'
4. 📤 推送分支: git push origin feature/amazing-feature
5. 🔄 創建 PR: 提交 Pull Request

📋 貢獻類型

• 🐛 Bug 修復: 修復系統錯誤
• ✨ 新功能: 添加新的功能特性
• 📚 文檔改進: 完善文檔說明
• 🎨 UI/UX 優化: 改進用戶界面
• ⚡ 性能優化: 提升系統性能
• 🧪 測試添加: 增加測試覆蓋率

👥 貢獻者

感謝所有為這個項目做出貢獻的開發者！

📞 聯繫方式

• 📧 Email: [您的郵箱]
• 🐙 GitHub: @Tsai1030
• 💬 Issues: 項目 Issues
• 📋 Discussions: 項目討論區

⭐ 支持項目

如果這個項目對您有幫助，請考慮：

• ⭐ 給項目加星: 點擊右上角的 Star 按鈕
• 🔄 分享項目: 推薦給其他開發者
• 🐛 報告問題: 幫助我們改進系統
• 💡 提出建議: 分享您的想法和建議