refactor: 统一导入方式，移除 sys.path 操作

- 重构所有模块导入，移除 sys.path.insert
- 统一使用 from backend.xxx 的绝对导入方式
- rag_core 包内使用相对导入（from .xxx）
- 移动 visualize_graph.py 到 tools/ 目录
- 添加必要的 __init__.py 文件
- 清理废弃文档和脚本

tools/test/check_qdrant.py

@@ -7,13 +7,8 @@ import asyncio
 import os
 import sys
 
-# 添加项目根目录到 Python 路径
-project_root = os.path.join(os.path.dirname(__file__), "..", "..")
-sys.path.insert(0, os.path.join(project_root, "backend"))
-sys.path.insert(0, project_root)
-
-from rag_core import QdrantVectorStore
-from app.model_services import get_embedding_service
+from backend.rag_core import QdrantVectorStore
+from backend.app.model_services import get_embedding_service
 
 
 def check_qdrant_data():
@@ -55,7 +50,7 @@ def check_qdrant_data():
 
 def check_sparse_embedder():
     """检查稀疏嵌入器"""
-    from rag_core import get_sparse_embedder
+    from backend.rag_core import get_sparse_embedder
     
     print("\n" + "="*70)
     print("检查稀疏嵌入器...")

tools/test/quick_test.py

@@ -7,12 +7,9 @@ import asyncio
 import os
 import sys
 
-project_root = os.path.join(os.path.dirname(__file__), "..", "..")
-sys.path.insert(0, os.path.join(project_root, "backend"))
-
 from qdrant_client import models
-from rag_core import QdrantVectorStore, get_sparse_embedder
-from app.model_services import get_embedding_service
+from backend.rag_core import QdrantVectorStore, get_sparse_embedder
+from backend.app.model_services import get_embedding_service
 
 
 def test_dense_retrieval():

tools/test/reset_qdrant.py

@@ -7,13 +7,8 @@ import asyncio
 import os
 import sys
 
-# 添加项目根目录到 Python 路径
-project_root = os.path.join(os.path.dirname(__file__), "..", "..")
-sys.path.insert(0, os.path.join(project_root, "backend"))
-sys.path.insert(0, project_root)
-
-from rag_core import QdrantVectorStore
-from app.model_services import get_embedding_service
+from backend.rag_core import QdrantVectorStore
+from backend.app.model_services import get_embedding_service
 
 
 async def delete_and_recreate():

tools/test/simple_delete.py

@@ -6,10 +6,7 @@
 import sys
 import os
 
-project_root = os.path.join(os.path.dirname(__file__), "..", "..")
-sys.path.insert(0, os.path.join(project_root, "backend"))
-
-from rag_core.client import create_qdrant_client
+from backend.rag_core.client import create_qdrant_client
 
 
 def delete_collection():

tools/test/simple_test.py

@@ -7,12 +7,9 @@ import asyncio
 import os
 import sys
 
-project_root = os.path.join(os.path.dirname(__file__), "..", "..")
-sys.path.insert(0, os.path.join(project_root, "backend"))
-
 from qdrant_client import models
-from rag_core import QdrantVectorStore, get_sparse_embedder
-from app.model_services import get_embedding_service
+from backend.rag_core import QdrantVectorStore, get_sparse_embedder
+from backend.app.model_services import get_embedding_service
 
 
 def check_qdrant_content():

tools/test/test_backend.py

@@ -10,12 +10,9 @@ import sys
 import uuid
 from dotenv import load_dotenv
 
-# 添加项目根目录和 backend 目录到 Python 路径
+# 加载环境变量
 project_root = os.path.join(os.path.dirname(__file__), "..")
-backend_dir = os.path.join(project_root, "backend")
-sys.path.insert(0, project_root)
-sys.path.insert(0, backend_dir)
-load_dotenv()
+load_dotenv(os.path.join(project_root, ".env"))
 
 from backend.app.config import DB_URI
 from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver

tools/test/test_dqrant.py

@@ -6,14 +6,11 @@ import numpy as np
 from dotenv import load_dotenv
 from qdrant_client import QdrantClient
 
-# 添加项目根目录和 backend 目录到 Python 路径
+# 加载环境变量
 project_root = os.path.join(os.path.dirname(__file__), "..")
-backend_dir = os.path.join(project_root, "backend")
-sys.path.insert(0, project_root)
-sys.path.insert(0, backend_dir)
-load_dotenv()
+load_dotenv(os.path.join(project_root, ".env"))
 
-from rag_core import LlamaCppEmbedder
+from backend.rag_core import LlamaCppEmbedder
 
 QDRANT_URL = os.getenv("QDRANT_URL", "http://127.0.0.1:6333")
 QDRANT_API_KEY = os.getenv("QDRANT_API_KEY")

tools/test/test_frontend.py

@@ -7,15 +7,6 @@
 import sys
 import os
 
-# 添加必要的路径
-project_root = os.path.dirname(os.path.abspath(__file__))
-frontend_src = os.path.join(project_root, "frontend", "src")
-backend_dir = os.path.join(project_root, "backend")
-
-sys.path.insert(0, project_root)
-sys.path.insert(0, frontend_src)
-sys.path.insert(0, backend_dir)
-
 print("=" * 60)
 print("前端导入测试")
 print("=" * 60)
@@ -32,7 +23,7 @@ except Exception as e:
 # 测试 2: 导入配置
 print("\n[测试 2] 导入配置...")
 try:
-    from config import config
+    from frontend.src.config import config
     print(f"✅ config 导入成功: page_title={config.page_title}")
 except Exception as e:
     print(f"❌ 导入失败: {e}")
@@ -40,7 +31,7 @@ except Exception as e:
 # 测试 3: 导入状态管理
 print("\n[测试 3] 导入状态管理...")
 try:
-    from state import AppState
+    from frontend.src.state import AppState
     print("✅ AppState 导入成功")
 except Exception as e:
     print(f"❌ 导入失败: {e}")
@@ -48,7 +39,7 @@ except Exception as e:
 # 测试 4: 导入 API 客户端
 print("\n[测试 4] 导入 API 客户端...")
 try:
-    from api_client import api_client
+    from frontend.src.api_client import api_client
     print("✅ api_client 导入成功")
 except Exception as e:
     print(f"❌ 导入失败: {e}")
@@ -56,9 +47,9 @@ except Exception as e:
 # 测试 5: 导入组件
 print("\n[测试 5] 导入组件...")
 try:
-    from components.sidebar import render_sidebar
-    from components.chat_area import render_chat_area
-    from components.info_panel import render_info_panel
+    from frontend.src.components.sidebar import render_sidebar
+    from frontend.src.components.chat_area import render_chat_area
+    from frontend.src.components.info_panel import render_info_panel
     print("✅ 所有组件导入成功")
 except Exception as e:
     print(f"❌ 导入失败: {e}")

tools/test/test_rag.py

@@ -15,10 +15,9 @@ import os
 from dotenv import load_dotenv
 
 # 加载环境变量（Qdrant URL、PostgreSQL 连接等）
-load_dotenv()
+project_root = os.path.join(os.path.dirname(__file__), "..")
+load_dotenv(os.path.join(project_root, ".env"))
 
-# 添加项目根目录到路径
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
 from pydantic import SecretStr
 from langchain_openai import ChatOpenAI
 from rag_indexer.index_builder import IndexBuilderConfig

tools/test/test_rag_indexer_result.py

@@ -6,18 +6,12 @@
 
 import asyncio
 import os
-import sys
-
-# 添加项目根目录到 Python 路径
-project_root = os.path.join(os.path.dirname(__file__), "..", "..")
-sys.path.insert(0, os.path.join(project_root, "backend"))
-sys.path.insert(0, project_root)
 
 from rag_indexer.index_builder import IndexBuilder
 from rag_indexer.splitters import SplitterType
 
-from rag_core import QdrantVectorStore, get_sparse_embedder
-from app.model_services import get_embedding_service
+from backend.rag_core import QdrantVectorStore, get_sparse_embedder
+from backend.app.model_services import get_embedding_service
 from qdrant_client import models
 
 
@@ -36,6 +30,7 @@ async def test_index_builder():
     )
     
     # 测试文档路径
+    project_root = os.path.join(os.path.dirname(__file__), "..", "..")
     test_file = os.path.join(project_root, "data", "user_docs", "doublestory.txt")
     
     if os.path.exists(test_file):

tools/test/test_retrievers.py

@@ -7,10 +7,7 @@ import asyncio
 import os
 import sys
 
-project_root = os.path.join(os.path.dirname(__file__), "..", "..")
-sys.path.insert(0, os.path.join(project_root, "backend"))
-
-from app.rag.retriever import create_hybrid_retriever, create_parent_hybrid_retriever
+from backend.app.rag.retriever import create_hybrid_retriever, create_parent_hybrid_retriever
 
 
 def test_hybrid_retriever():

tools/visualize_graph.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+"""
+LangGraph 图结构可视化脚本
+快速查看节点和边的连接关系
+运行方式：python tools/visualize_graph.py
+"""
+import sys
+from pathlib import Path
+from dotenv import load_dotenv
+
+# 确定项目根目录（Agent1 目录）
+# 当前文件位置：tools/visualize_graph.py
+# 向上 1 级到 Agent1
+PROJECT_ROOT = Path(__file__).parent.parent
+BACKEND_DIR = PROJECT_ROOT / "backend"
+
+# 关键：把 backend 目录加入 sys.path，这样才能找到 rag_core
+# 注意：这只对直接运行脚本有效，对 -m 方式无效（因为 -m 方式在脚本运行前就导入了）
+if str(BACKEND_DIR) not in sys.path:
+    sys.path.insert(0, str(BACKEND_DIR))
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+load_dotenv(PROJECT_ROOT / ".env")
+
+from backend.app.agent.agent_service import AIAgentService
+from backend.app.config import DB_URI
+from backend.app.main_graph.checkpoint.postgres.aio import AsyncPostgresSaver
+import asyncio
+
+
+async def visualize_graph():
+    """可视化 LangGraph 结构"""
+    print("=" * 80)
+    print("  LangGraph 图结构可视化")
+    print("=" * 80)
+    print(f"项目根目录: {PROJECT_ROOT}")
+    print(f"Backend 目录: {BACKEND_DIR}")
+
+    async with AsyncPostgresSaver.from_conn_string(DB_URI) as checkpointer:
+        await checkpointer.setup()
+
+        # 创建服务实例
+        print("\n正在初始化 Agent 服务...")
+        agent_service = AIAgentService(checkpointer)
+        await agent_service.initialize()
+
+        for model_name, graph in agent_service.graphs.items():
+            print(f"\n{'=' * 80}")
+            print(f"  模型: {model_name}")
+            print(f"{'=' * 80}")
+
+            # 获取图结构
+            graph_structure = graph.get_graph()
+
+            # 1. 直接打印节点和边
+            print("\n[1] 节点列表:")
+            print("-" * 80)
+            for node_id, node in graph_structure.nodes.items():
+                print(f"  - {node_id}: {node.name}")
+
+            print("\n[2] 边列表:")
+            print("-" * 80)
+            for edge in graph_structure.edges:
+                print(f"  {edge.source} --> {edge.target}")
+
+            # 3. ASCII 字符画（需要 grandalf）
+            print("\n[3] ASCII 字符画:")
+            print("-" * 80)
+            try:
+                print(graph_structure.draw_ascii())
+            except Exception as e:
+                print(f"⚠️  ASCII 绘制失败: {e}")
+
+            # 4. Mermaid 源码
+            print("\n[4] Mermaid 源码 (可复制到 https://mermaid.live/):")
+            print("-" * 80)
+            print(graph_structure.draw_mermaid())
+
+
+if __name__ == "__main__":
+    asyncio.run(visualize_graph())