{"id":29716388,"url":"https://github.com/tsai1030/full-multi-agent","last_synced_at":"2026-06-06T18:00:35.476Z","repository":{"id":304541011,"uuid":"1018919985","full_name":"Tsai1030/Full-multi-agent","owner":"Tsai1030","description":"RAG Multi Agents","archived":false,"fork":false,"pushed_at":"2026-05-06T00:50:19.000Z","size":16577,"stargazers_count":16,"open_issues_count":1,"forks_count":8,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-06T02:31:36.828Z","etag":null,"topics":["mcp","multiagent","rag","reactjs"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Tsai1030.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-13T10:49:01.000Z","updated_at":"2026-05-06T00:38:04.000Z","dependencies_parsed_at":"2025-07-13T20:34:26.438Z","dependency_job_id":null,"html_url":"https://github.com/Tsai1030/Full-multi-agent","commit_stats":null,"previous_names":["tsai1030/full-multi-agent"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/Tsai1030/Full-multi-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tsai1030%2FFull-multi-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tsai1030%2FFull-multi-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tsai1030%2FFull-multi-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tsai1030%2FFull-multi-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Tsai1030","download_url":"https://codeload.github.com/Tsai1030/Full-multi-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tsai1030%2FFull-multi-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33993195,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-06T02:00:07.033Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mcp","multiagent","rag","reactjs"],"created_at":"2025-07-24T06:09:52.261Z","updated_at":"2026-06-06T18:00:35.466Z","avatar_url":"https://github.com/Tsai1030.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🔮 紫微斗數 Multi-Agent AI 系統\n\n[![GitHub Stars](https://img.shields.io/github/stars/Tsai1030/Full-multi-agent?style=social)](https://github.com/Tsai1030/Full-multi-agent)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![Next.js 14](https://img.shields.io/badge/Next.js-14-black.svg)](https://nextjs.org/)\n[![FastAPI](https://img.shields.io/badge/FastAPI-0.115+-009688.svg)](https://fastapi.tiangolo.com/)\n[![LangGraph](https://img.shields.io/badge/LangGraph-0.2+-orange.svg)](https://langchain-ai.github.io/langgraph/)\n[![Gemini](https://img.shields.io/badge/Gemini-3.5%20Flash-8E75B2.svg)](https://ai.google.dev/)\n[![iztro](https://img.shields.io/badge/iztro-2.5-purple.svg)](https://github.com/SylarLong/iztro)\n\n\u003e 一套以 **真實命盤** 為基礎的紫微斗數 AI 分析系統。\n\u003e 命盤由官方 **iztro 排盤引擎** 精準計算（不由 LLM 編造），再交給 **LangGraph multi-agent**\n\u003e 結合 **ChromaDB RAG 知識庫** 與 **Web Search** 進行深度解盤。全系統僅需一把 **Google Gemini** 金鑰。\n\n---\n\n## 📸 系統展示\n\n### 🧮 真實命盤盤面（本版新功能）\n\n由官方 iztro 引擎精準排盤，自訂主題十二宮格完整呈現主輔星、四化、大限。\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./public/screenshots/命盤截圖.png\" alt=\"紫微斗數命盤盤面\" width=\"85%\" /\u003e\n\u003c/p\u003e\n\n### 操作流程\n\n| 1️⃣ 首頁 | 2️⃣ 輸入出生資料 |\n|:---:|:---:|\n| ![首頁畫面](./public/screenshots/首頁畫面.png) | ![輸入資料畫面](./public/screenshots/輸入資料畫面.png) |\n\n| 3️⃣ 命盤推算中 | 4️⃣ AI 深度解析結果 |\n|:---:|:---:|\n| ![分析載入](./public/screenshots/分析loading.png) | ![分析結果](./public/screenshots/result.png) |\n\n### ⚙️ Multi-Agent 後端運作\n\nLangGraph multi-agent 依序排盤注入、查詢知識庫、彙整解盤的後端流程。\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./public/screenshots/multi-agent後端畫面.png\" alt=\"Multi-Agent 後端畫面\" width=\"85%\" /\u003e\n\u003c/p\u003e\n\n---\n\n## ✨ 核心特色\n\n### 🧮 真實命盤，絕不編造\n- 命盤由 [**iztro**](https://github.com/SylarLong/iztro) 官方排盤引擎在**前端**直接計算，結果與 iztro 完全一致。\n- 完整呈現十二宮：主星（含廟旺亮度）、輔星、雜曜、**生年四化（祿權科忌）**、大限、命主／身主、五行局、身宮。\n- LLM 只負責「解讀」命盤，**不負責排盤**，從根本杜絕星曜幻覺。\n\n### 🎨 自訂主題命盤盤面\n- 傳統 **4×4 十二宮格** 盤面，中央顯示基本命格資訊。\n- 沿用金色／星空神秘主題，四化以彩色標籤標示，響應式設計。\n\n### 🤖 LangGraph Multi-Agent（ReAct Loop）\n- `orchestrator → tools → synthesizer` 的 Graph 架構，動態決定工具呼叫順序。\n- 讀取已排好的命盤，自主查詢知識庫 / 網路，最後彙整成結構化解析報告。\n- 迭代上限保護，確保回應時間可控。\n\n### 📚 RAG 專業知識庫\n- **ChromaDB** 持久化向量庫，啟動時自動索引（idempotent）。\n- 嵌入模型使用 **Gemini Embedding**，紫微斗數知識庫（JSON chunks）。\n\n### 🌐 Web Search\n- 主要使用 **Tavily**，未設金鑰時自動 fallback 至 **DuckDuckGo**。\n\n### 🟣 單一金鑰即可運行\n- LLM（`gemini-3.5-flash`）與 Embedding（`gemini-embedding-2`）皆使用 **Google Gemini**，只需一把金鑰。\n\n---\n\n## 🏗️ 系統架構\n\n```\n┌──────────────────────────────────────────────────────────────────┐\n│                      Frontend (Next.js 14)                         │\n│                                                                    │\n│   出生資料表單 ──▶ iztro 排盤引擎（瀏覽器端，精準計算命盤）          │\n│        │                    │                                      │\n│        │                    ▼                                      │\n│        │            \u003cZiweiChart\u003e 主題盤面（十二宮 / 四化 / 大限）   │\n│        │                                                          │\n│        └────── POST /api/analyze  { birth_data, chart } ──────┐   │\n└──────────────────────────────────────────────────────────────┼───┘\n                                                                │\n┌───────────────────────────────────────────────────────────────▼──┐\n│                       FastAPI (port 8000)                         │\n│  ┌─────────────────────────────────────────────────────────────┐ │\n│  │                   LangGraph StateGraph                       │ │\n│  │                                                              │ │\n│  │   START → orchestrator ──┐  (命盤已注入 prompt)              │ │\n│  │               ▲          │ tool_calls?                       │ │\n│  │               │ loop     ▼                                   │ │\n│  │             tools ◄──────┘                                   │ │\n│  │               │  max_iterations                              │ │\n│  │               ▼                                              │ │\n│  │          synthesizer → END （結構化解盤報告）                │ │\n│  └──────────────┬──────────────────────┬────────────────────────┘ │\n│                 │                      │                          │\n│         search_ziwei_knowledge    web_search                     │\n│            (ChromaDB +          (Tavily / DuckDuckGo)             │\n│             Gemini Embedding)                                    │\n│                                                                  │\n│   LLM：Google Gemini（gemini-3.5-flash）via langchain-google-genai│\n└──────────────────────────────────────────────────────────────────┘\n```\n\n\u003e **設計重點**：命盤計算在前端用 iztro 完成（單一可信來源），同一份命盤 JSON 同時用於\n\u003e 「畫盤」與「送後端解盤」，後端不再爬取外部網站，準確且穩定。\n\n---\n\n## 🚀 快速開始\n\n### 環境需求\n\n| 工具 | 版本 | 說明 |\n|------|------|------|\n| Python | 3.10+ | 後端 |\n| [uv](https://docs.astral.sh/uv/) | 最新版 | Python 套件 / 環境管理 |\n| Node.js | 18+ | 前端 |\n| Yarn | 1.x | 前端套件管理 |\n| Google Gemini API Key | — | [免費取得](https://aistudio.google.com/apikey) |\n\n### 1. 複製專案\n\n```bash\ngit clone https://github.com/Tsai1030/Full-multi-agent.git\ncd Full-multi-agent\n```\n\n### 2. 設定環境變數\n\n複製範例檔並填入你的 Gemini 金鑰（`.env` 已被 git 忽略，不會上傳）：\n\n```bash\ncp .env.example .env\n```\n\n`.env` 至少需填：\n\n```env\nGOOGLE_API_KEY=你的_gemini_api_key\n```\n\n其餘設定（模型名稱、RAG 路徑、CORS 等）已有合理預設值，詳見 [`.env.example`](.env.example)。\n\n### 3. 啟動後端（uv）\n\n```bash\ncd backend\nuv sync                       # 建立 .venv 並安裝所有依賴\nuv run python api_server.py   # 首次啟動會自動建立 RAG 向量庫\n```\n\n後端啟動於 `http://localhost:8000`。\n\n### 4. 啟動前端（yarn）\n\n另開一個終端：\n\n```bash\ncd frontend\nyarn install\nyarn dev\n```\n\n前端啟動於 `http://localhost:3000`。\n\n### 5. 開始使用\n\n| 服務 | URL |\n|------|-----|\n| 前端 | http://localhost:3000 |\n| 命盤分析 | http://localhost:3000/analyze |\n| Swagger UI | http://localhost:8000/docs |\n| 健康檢查 | http://localhost:8000/health |\n\n---\n\n## 🔮 使用流程\n\n1. 前往 `http://localhost:3000/analyze`\n2. 填入出生資料：性別、西元年月日、時辰（地支）\n3. 選擇分析領域：愛情 / 財富 / 未來 / 綜合\n4. （選填）輸入具體問題\n5. 送出後，前端用 **iztro 即時排盤** 並顯示**命盤盤面**\n6. 命盤同步送至後端，**LangGraph multi-agent** 進行解盤\n7. 查看「命盤盤面 + AI 深度解析報告」\n\n### 分析領域\n\n| 領域 | 說明 |\n|------|------|\n| 💕 愛情感情 | 桃花運、夫妻宮、感情運勢與正緣分析 |\n| 💰 財富事業 | 財帛宮、官祿宮、求財方位與事業契機 |\n| 🔮 未來運勢 | 大限流年、人生關鍵時機與趨勢 |\n| 🌟 綜合分析 | 全方位十二宮整合解析 |\n\n---\n\n## 📁 專案結構\n\n```\nFull-multi-agent/\n├── .env.example                  # 環境變數範例（複製為 .env）\n├── zi_wei_dou_shu_rag_chunks.json # RAG 知識庫資料（73 chunks）\n│\n├── backend/\n│   ├── pyproject.toml            # uv 專案定義（Gemini + LangGraph + RAG）\n│   ├── uv.lock\n│   ├── api_server.py             # FastAPI 主程式，lifespan 自動建 RAG\n│   └── src/\n│       ├── config/settings.py    # Pydantic 設定（讀 repo 根目錄 .env）\n│       ├── ziwei/\n│       │   └── format.py         # 命盤 JSON → 中文摘要（餵給 agent）\n│       ├── graph/\n│       │   ├── state.py          # GraphState（含 chart_data）\n│       │   ├── nodes.py          # orchestrator / tool_node / synthesizer（Gemini）\n│       │   ├── edges.py          # should_continue 條件路由\n│       │   └── builder.py        # StateGraph 編譯（lru_cache 單例）\n│       ├── tools/\n│       │   ├── rag_tool.py       # @tool search_ziwei_knowledge\n│       │   └── web_search.py     # @tool web_search（Tavily + DDG）\n│       ├── rag/\n│       │   ├── vector_store.py   # ChromaDB（依 provider 選 embedding）\n│       │   ├── embeddings.py     # Gemini / OpenAI embedding provider\n│       │   ├── indexer.py        # 首次啟動建索引\n│       │   └── retriever.py      # 語意搜尋 + 格式化\n│       ├── mcp/                  # 自訂 Python MCP server（保留，命盤已改前端）\n│       └── api/\n│           ├── models.py         # 請求/回應模型（AnalysisRequest.chart）\n│           └── router.py         # /api/analyze, /api/status, /api/domains\n│\n└── frontend/\n    ├── tailwind.config.ts        # cosmos / gold / mystic 色票與動畫\n    └── src/\n        ├── app/analyze/page.tsx  # form → loading → result 狀態機\n        ├── components/\n        │   ├── ZiweiChart.tsx    # ★ 自訂主題命盤盤面（4×4 十二宮）\n        │   ├── BirthDataForm.tsx\n        │   ├── ResultDisplay.tsx\n        │   └── ...\n        ├── hooks/useAnalysis.ts  # 排盤 + 呼叫後端的狀態機 hook\n        ├── lib/\n        │   ├── ziwei.ts          # ★ iztro 排盤封裝（computeChart）\n        │   └── api.ts\n        └── types/index.ts        # BirthData / ZiweiChart / Palace / Star\n```\n\n---\n\n## 🔧 API 端點\n\n### `POST /api/analyze`\n\n```json\n{\n  \"birth_data\": {\n    \"gender\": \"男\",\n    \"birth_year\": 1990,\n    \"birth_month\": 5,\n    \"birth_day\": 20,\n    \"birth_hour\": \"午\"\n  },\n  \"domain_type\": \"comprehensive\",\n  \"user_question\": \"今年事業運如何？\",\n  \"chart\": { \"...\": \"前端 iztro 計算好的命盤 JSON（十二宮 / 星曜 / 四化）\" }\n}\n```\n\n\u003e `chart` 由前端排盤後附上；後端據此解盤，不會自行排盤。\n\n回應：\n\n```json\n{\n  \"success\": true,\n  \"result\": \"## 命盤基本格局\\n...\",\n  \"metadata\": { \"domain_type\": \"comprehensive\", \"iterations\": 6, \"elapsed_ms\": 18234 }\n}\n```\n\n| 端點 | 說明 |\n|------|------|\n| `POST /api/analyze` | 命盤解析（主要端點） |\n| `GET /api/status` | 系統狀態（RAG 文件數、工具清單） |\n| `GET /api/domains` | 四大分析領域 |\n| `GET /api/birth-hours` | 十二時辰對照 |\n| `GET /health` | 健康檢查 |\n\n---\n\n## ⚙️ 設定說明\n\n所有設定皆可於 `.env` 覆寫（鍵名見 [`.env.example`](.env.example)）。\n\n| 變數 | 預設 | 說明 |\n|------|------|------|\n| `GOOGLE_API_KEY` | — | **必填**，Gemini 金鑰 |\n| `GEMINI_MODEL` | `gemini-3.5-flash` | multi-agent 使用的 LLM |\n| `GEMINI_EMBEDDING_MODEL` | `gemini-embedding-2` | RAG 嵌入模型 |\n| `EMBEDDING_PROVIDER` | `gemini` | `gemini` 或 `openai` |\n| `TAVILY_API_KEY` | 空 | 留空則用 DuckDuckGo |\n| `GRAPH_MAX_ITERATIONS` | `6` | ReAct loop 最大迭代次數 |\n| `RAG_TOP_K` / `RAG_MIN_SCORE` | `5` / `0.3` | RAG 檢索參數 |\n| `APP_CORS_ORIGINS` | `http://localhost:3000` | 前端來源白名單 |\n\n\u003e **時辰對應**：地支 `子→0 … 亥→11`（`子時` 取 `00:00–01:00` 早子，與一般 iztro 應用一致）。\n\n---\n\n## 🧩 技術細節\n\n- **命盤一致性**：前端 [`lib/ziwei.ts`](frontend/src/lib/ziwei.ts) 呼叫 `astro.bySolar(date, timeIndex, gender, true, 'zh-TW')`，序列化後同時供 [`ZiweiChart.tsx`](frontend/src/components/ZiweiChart.tsx) 畫盤與後端解盤。\n- **後端格式化**：[`ziwei/format.py`](backend/src/ziwei/format.py) 把命盤 JSON 轉成中文摘要，注入 orchestrator prompt，明確要求 LLM「以此命盤為唯一依據」。\n- **Gemini 相容處理**：`gemini-3.5-flash` 回覆為 thinking 分段（已轉純文字）；且 function-call turn 必須緊接 user / function-response turn，因此 orchestrator 首回合會將使用者訊息持久化進 state。\n- **設定載入**：`settings.py` 以絕對路徑讀取 **repo 根目錄** 的 `.env`，無論從哪個 cwd 啟動皆可。\n\n---\n\n## 🐛 常見問題\n\n| 問題 | 解決方式 |\n|------|---------|\n| `RAG init failed: API key required` | `.env` 未填 `GOOGLE_API_KEY`，或 `.env` 不在 repo 根目錄 |\n| 命盤日期錯誤 / 排盤失敗 | 確認出生年月日為有效國曆日期 |\n| 前端連不到後端 | 確認後端已啟動於 `:8000`，且 `APP_CORS_ORIGINS` 含前端位址 |\n| 分析很慢 | 正常，multi-agent 會多輪查詢知識庫；可調低 `GRAPH_MAX_ITERATIONS` |\n| 想換模型 | 改 `.env` 的 `GEMINI_MODEL` / `GEMINI_EMBEDDING_MODEL` 即可 |\n\n---\n\n## 📦 技術棧\n\n**Backend** — FastAPI · LangGraph · langchain-google-genai（Gemini）· ChromaDB · Tavily · Loguru · pydantic-settings · uv\n\n**Frontend** — Next.js 14（App Router）· TypeScript · Tailwind CSS · Framer Motion · **iztro** · Yarn\n\n---\n\n## 📝 版本記錄\n\n### v2.1.0（2026-06-06）— 當前版本\n- **新增命盤功能**：以官方 **iztro** 引擎在前端精準排盤，新增自訂主題 **十二宮命盤盤面**。\n- **全面改用 Google Gemini**：LLM 換成 `gemini-3.5-flash`、Embedding 換成 `gemini-embedding-2`，全系統只需一把金鑰。\n- **命盤驅動解盤**：前端排好的命盤 JSON 一併送後端，agent 以真實命盤解讀，後端不再爬取外部網站。\n- **uv 化後端**：新增 `pyproject.toml` / `uv.lock`，以 `uv sync` / `uv run` 管理。\n- **設定修正**：`.env` 改由 repo 根目錄絕對路徑載入，修正從 `backend/` 啟動時金鑰讀不到的問題。\n\n### v2.0.0（2026-04-29）\n- 架構全面重寫：LangGraph StateGraph、自訂 Python MCP Server、Next.js 14 前端。\n\n### v1.x（2025-07）\n- 初始版本：Multi-Agent coordinator + Node.js MCP + React CRA。\n\n---\n\n## 📄 授權\n\n本專案採用 [MIT License](LICENSE)。\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**🔮 以 AI 之眼，洞見命理之道 🔮**\n\n*Built with ❤️ by [Tsai1030](https://github.com/Tsai1030)*\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftsai1030%2Ffull-multi-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftsai1030%2Ffull-multi-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftsai1030%2Ffull-multi-agent/lists"}