feat:对部分代码提出了修改建议,用TODO高亮了。修改了AgentManager添加智能体的方法,现在可以通过自动遍历Agents目录来获取,方便切换到private分支管理私有代码

This commit is contained in:
miluELK 2025-10-23 14:08:08 +08:00
parent d56cec5002
commit d53a32e6b8
13 changed files with 425 additions and 30 deletions

13
.gitignore vendored
View File

@ -35,10 +35,17 @@ cache
.cursor
.trae
.pytest_cache
*.nogit*
*.private*
*.local*
### (企业私有代码 - 仅忽略敏感配置,不忽略代码文件)
# 移除了 *.private* 和 *_private 规则,允许 Git 本地管理
# 通过 .git/info/exclude 或本地分支管理私有代码
*.secret*
*.nogit*
# *.local* 保留用于本地配置文件
*.local.py
*.local.js
*.local.yaml
*.pdf
src/data

295
CLAUDE.md Normal file
View File

@ -0,0 +1,295 @@
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## 项目概述
**语析 (Yuxi-Know)** 是一个基于大模型的智能知识库与知识图谱问答系统,融合了 RAG检索增强生成与知识图谱技术。
- **技术栈**: FastAPI + Vue.js 3 + LangGraph + LightRAG + Neo4j + Milvus
- **Python版本**: ≥3.11
- **当前版本**: v0.3.0-beta
- **许可证**: MIT
## 开发命令
### Docker 环境管理
```bash
# 启动所有服务
make start
# 或: docker compose up -d
# 停止所有服务
make stop
# 或: docker compose down
# 查看后端日志
make logs
# 或: docker logs --tail=50 api-dev
```
### 代码质量
```bash
# 代码检查
make lint
# 或: uv run python -m ruff check .
# 代码格式化
make format
# 或: uv run ruff format . && uv run ruff check . --fix
# 查看格式化差异
make format_diff
# 或: uv run ruff format --diff .
```
### 测试
```bash
# 运行 API 单元测试
make router-tests
# 或: docker compose exec -T api uv run --group test pytest test/api
# 运行特定测试文件
docker compose exec -T api uv run --group test pytest test/api/test_xxx.py
# 带覆盖率报告
docker compose exec -T api uv run --group test pytest test/ --cov=src --cov-report=html
```
## 架构设计
### 分层架构
```
前端层 (Vue.js 3)
↓ HTTP/REST API
API层 (FastAPI)
业务逻辑层 (Service)
├─ 智能体系统 (Agent - LangGraph)
├─ 知识库管理 (KnowledgeBase)
├─ 任务管理 (Tasker)
└─ 认证服务 (Auth)
数据访问层
├─ SQLite (对话、用户、统计)
├─ Neo4j (知识图谱)
├─ Milvus/Chroma (向量数据库)
└─ MinIO (文件存储)
```
### 核心目录结构
```
src/ # 核心Python源代码
├── agents/ # 智能体框架 (LangGraph)
│ ├── chatbot/ # 聊天机器人智能体
│ ├── react/ # ReAct智能体
│ └── common/ # 通用组件 (工具、模型、上下文)
├── knowledge/ # 知识库核心模块
│ ├── implementations/ # 具体实现 (Milvus, Chroma, LightRAG)
│ └── manager.py # 知识库管理器
├── models/ # LLM模型加载 (chat, embed, rerank)
├── storage/ # 数据存储层
│ ├── db/ # SQLite ORM模型
│ ├── minio/ # MinIO对象存储
│ └── conversation/ # 对话历史管理
├── config/ # 配置管理
│ └── static/ # 静态配置 (models.yaml, agents_meta.yaml)
├── plugins/ # 文档处理插件 (MinerU, PaddleOCR)
└── utils/ # 工具函数
server/ # FastAPI应用层
├── main.py # FastAPI应用入口
├── routers/ # API路由 (7个主要路由)
│ ├── auth_router.py # /api/auth/*
│ ├── chat_router.py # /api/chat/*
│ ├── knowledge_router.py # /api/knowledge/*
│ ├── graph_router.py # /api/graph/*
│ ├── dashboard_router.py # /api/dashboard/*
│ ├── system_router.py # /api/system/*
│ └── task_router.py # /api/tasks/*
├── services/ # 业务逻辑服务
│ └── tasker.py # 后台异步任务管理器
└── utils/ # 服务层工具 (认证、用户管理)
web/ # Vue.js前端应用
├── src/
│ ├── views/ # 页面视图
│ ├── components/ # 可复用组件
│ ├── layouts/ # 布局模板 (AppLayout, BlankLayout)
│ ├── router/ # Vue Router配置
│ ├── stores/ # Pinia状态管理
│ ├── apis/ # API调用层
│ └── utils/ # 前端工具函数
└── vite.config.js # Vite构建配置
```
## 关键架构决策
### 1. 智能体系统 (LangGraph)
所有智能体基于 **LangGraph** 的状态机模型构建:
- **状态定义**: `messages[]`, `context` (包含 system_prompt, model, tools, mcps)
- **节点**: `llm_call` (调用LLM), `dynamic_tools_node` (工具执行)
- **边**: 通过 `tools_condition` 判断是否需要工具调用
- **持久化**: 使用 SQLite Checkpointer 支持中断恢复
**可用工具**:
- 知识库查询工具
- 知识图谱查询工具
- Web搜索工具 (Tavily)
- 计算器工具
- MySQL查询工具
### 2. 知识库系统
支持三种知识库实现:
- **Milvus**: 生产级向量数据库
- **Chroma**: 轻量级向量数据库
- **LightRAG**: 图增强检索系统,自动构建知识图谱
所有知识库通过 `KnowledgeBaseFactory` 工厂模式创建,由 `KnowledgeBaseManager` 统一管理。
### 3. 异步任务系统 (Tasker)
所有耗时操作(文档处理、知识图谱构建)均通过 **Tasker** 异步队列处理:
- **任务队列**: FIFO队列管理
- **进度跟踪**: 实时更新任务状态
- **结果存储**: 完成后存储到 SQLite
- **失败重试**: 支持失败回调处理
### 4. 文档处理
支持多种格式文档:
- **文本**: `.txt`, `.md`
- **文档**: `.doc`, `.docx`, `.pdf`
- **网页**: `.html`, `.htm`
- **数据**: `.json`, `.csv`, `.xls`, `.xlsx`
- **图片**: `.jpg`, `.jpeg`, `.png`, `.bmp`, `.tiff` (需要 OCR)
处理流程:
1. 选择合适的解析器 (MinerU for PDF, PaddleOCR for images)
2. 文本提取与分块
3. Embedding 向量化
4. 存储到向量数据库
5. 可选:知识图谱构建 (LightRAG)
## 配置管理
### 环境变量配置
项目根目录 `.env` 文件(从 `.env.template` 复制):
```bash
# 模型提供商 API Key (推荐使用硅基流动)
SILICONFLOW_API_KEY=xxx
OPENAI_API_KEY=xxx
DEEPSEEK_API_KEY=xxx
ZHIPUAI_API_KEY=xxx
# 数据库配置
NEO4J_URI=bolt://graph:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=0123456789
MILVUS_URI=http://milvus:19530
# 文档处理服务 (需要GPU)
MINERU_OCR_URI=http://mineru:30000
PADDLEX_URI=http://paddlex:8080
# Web搜索 (可选)
TAVILY_API_KEY=xxx
```
### 模型配置
`src/config/static/models.yaml` 定义所有可用的 LLM 和 Embedding 模型:
- **LLM模型**: 支持 OpenAI, DeepSeek, SiliconFlow, Together, ZhipuAI 等
- **Embedding模型**: 支持 OpenAI, HuggingFace 本地模型
- **重排序模型**: 支持 Jina Reranker
## 数据库服务
### Docker Compose 服务
| 服务名 | 端口 | 用途 |
|--------|------|------|
| `api-dev` | 5050 | FastAPI后端服务 |
| `web-dev` | 5173 | Vue.js前端服务 |
| `graph` (Neo4j) | 7474/7687 | 知识图谱数据库 |
| `milvus` | 19530 | 向量数据库 |
| `minio` | 9000/9001 | 对象存储 |
| `etcd` | 2379 | Milvus元数据存储 |
### 访问地址
- **Web界面**: http://localhost:5173
- **API文档**: http://localhost:5050/docs
- **Neo4j浏览器**: http://localhost:7474
## 开发最佳实践
### 后端开发
1. **路由**: 新增 API 路由在 `server/routers/` 下,并在 `server/routers/__init__.py` 注册
2. **业务逻辑**: 核心业务代码放在 `src/` 下,避免在路由中编写复杂逻辑
3. **异步任务**: 耗时操作必须使用 Tasker 异步处理
4. **代码规范**: 提交前运行 `make lint``make format`
5. **测试**: 为新增 API 编写单元测试 `test/api/test_xxx.py`
### 前端开发
1. **API调用**: 统一在 `web/src/apis/` 下定义 API 函数
2. **状态管理**: 使用 Pinia stores (`web/src/stores/`)
3. **组件**: 可复用组件放在 `web/src/components/`
4. **样式**: 使用 Less参考 `web/src/assets/css/base.css` 配色系统
5. **热更新**: Vite 支持热更新,无需重启容器
### 智能体开发
1. **工具定义**: 在 `src/agents/common/tools.py` 定义新工具
2. **工具包**: 复杂工具可创建 toolkit`src/agents/common/toolkits/mysql/`
3. **LangGraph状态**: 在智能体 graph 定义中添加自定义 State 字段
4. **上下文管理**: 使用 `Context` 对象传递智能体配置
## 重要文件
| 文件 | 用途 |
|------|------|
| `src/config/app.py` | 全局配置管理 |
| `server/main.py` | FastAPI应用入口 |
| `src/knowledge/manager.py` | 知识库管理器 |
| `src/agents/chatbot/graph.py` | LangGraph智能体定义 |
| `server/services/tasker.py` | 异步任务管理器 |
| `src/storage/db/models.py` | SQLAlchemy ORM模型 |
| `docker-compose.yml` | 服务编排配置 |
| `pyproject.toml` | Python依赖与工具配置 |
| `web/src/router/index.js` | 前端路由配置 |
## 常见问题
1. **Milvus启动失败**: `docker compose up milvus -d && docker restart api-dev`
2. **模型加载失败**: 检查 `.env` 中的 API Key 是否正确配置
3. **任务卡住**: 查看 Tasker 日志,可能是工具执行超时
4. **前端无法连接后端**: 检查 Vite 配置中的代理设置
## v0.3 重大变更
- **.env 文件位置**: 从 `src/.env` 移到项目根目录
- **数据库重构**: 不再使用 MemorySaver改用新的存储结构
- **自定义模型移除**: 改用自定义 provider 方式
- **新增功能**: Dashboard 统计、消息反馈、用户管理增强
## 文档资源
- **在线文档**: https://xerrors.github.io/Yuxi-Know/
- **视频演示**: https://www.bilibili.com/video/BV1ETedzREgY/

View File

@ -15,7 +15,7 @@ services:
- ./saves:/app/saves
- ./test:/app/test
- ./scripts:/app/scripts
- ./.env :/app/.env
- ./.env:/app/.env
- ${MODEL_DIR:-./models}:/models # 使用默认值处理未定义的环境变量
ports:
- "5050:5050"
@ -38,8 +38,8 @@ services:
- MINIO_URI=${MINIO_URI:-http://milvus-minio:9000}
- MODEL_DIR_IN_DOCKER=/models
- RUNNING_IN_DOCKER=true
- NO_PROXY=localhost,127.0.0.1,milvus,graph,milvus-minio,milvus-etcd-dev,etcd,minio,mineru,paddlex
- no_proxy=localhost,127.0.0.1,milvus,graph,milvus-minio,milvus-etcd-dev,etcd,minio,mineru,paddlex
- NO_PROXY=localhost,127.0.0.1,milvus,graph,milvus-minio,milvus-etcd-dev,etcd,minio,mineru,paddlex,api.siliconflow.cn
- no_proxy=localhost,127.0.0.1,milvus,graph,milvus-minio,milvus-etcd-dev,etcd,minio,mineru,paddlex,api.siliconflow.cn
# endregion api_envs
command: uv run --no-dev uvicorn server.main:app --host 0.0.0.0 --port 5050 --reload
restart: unless-stopped
@ -145,7 +145,7 @@ services:
- ETCD_SNAPSHOT_COUNT=50000
volumes:
- ./docker/volumes/milvus/etcd:/etcd
command: etcd -advertise-client-urls=http://127.0.0.1:2379 -listen-client-urls http://0.0.0.0:2379 --data-dir /etcd
command: etcd -advertise-client-urls=http://etcd:2379 -listen-client-urls http://0.0.0.0:2379 --data-dir /etcd
healthcheck:
test: ["CMD", "etcdctl", "endpoint", "health"]
interval: 60s

View File

@ -9,7 +9,7 @@ from fastapi.responses import JSONResponse
from starlette.middleware.base import BaseHTTPMiddleware
from server.routers import router
from server.services.tasker import tasker
from server.utils.lifespan import lifespan
from server.utils.auth_middleware import is_public_path
from server.utils.common_utils import setup_logging
@ -24,7 +24,7 @@ RATE_LIMIT_ENDPOINTS = {("/api/auth/token", "POST")}
_login_attempts: defaultdict[str, deque[float]] = defaultdict(deque)
_attempt_lock = asyncio.Lock()
app = FastAPI()
app = FastAPI(lifespan=lifespan)
app.include_router(router, prefix="/api")
# CORS 设置
@ -119,16 +119,5 @@ class AuthMiddleware(BaseHTTPMiddleware):
app.add_middleware(LoginRateLimitMiddleware)
app.add_middleware(AuthMiddleware)
@app.on_event("startup")
async def start_tasker() -> None:
await tasker.start()
@app.on_event("shutdown")
async def stop_tasker() -> None:
await tasker.shutdown()
if __name__ == "__main__":
uvicorn.run(app, host="0.0.0.0", port=5050, threads=10, workers=10, reload=True)

View File

@ -112,7 +112,7 @@ async def get_agent(current_user: User = Depends(get_required_user)):
metadata = yaml.safe_load(f)
return {"agents": agents, "metadata": metadata}
#TODO:[未完成]这个thread_id在前端是直接生成的1234最好传入thread_id时做校验只允许uuid4
@chat.post("/agent/{agent_id}")
async def chat_agent(
agent_id: str,
@ -254,6 +254,7 @@ async def chat_agent(
logger.error(f"Error saving messages from LangGraph state: {e}")
logger.error(traceback.format_exc())
#TODO:[功能建议]针对需要人工审批后再执行的工具可以使用langgraph的interrupt方法中断对话等待用户输入后再使用command跳转回去
async def stream_messages():
# 代表服务端已经收到了请求
yield make_chunk(status="init", meta=meta, msg=HumanMessage(content=query).model_dump())

15
server/utils/lifespan.py Normal file
View File

@ -0,0 +1,15 @@
import asyncio
from contextlib import asynccontextmanager
from fastapi import FastAPI
from server.services import tasker
#TODO:[已完成]使用lifespan进行统一生命周期管理
@asynccontextmanager
async def lifespan(app: FastAPI):
await tasker.start()
"""FastAPI lifespan事件管理器"""
yield
await tasker.shutdown()

15
server/utils/singleton.py Normal file
View File

@ -0,0 +1,15 @@
from threading import Lock
class SingletonMeta(type):
"""
This is a thread-safe implementation of Singleton.
"""
_instances = {}
_lock: Lock = Lock()
def __call__(cls, *args, **kwargs):
with cls._lock:
if cls not in cls._instances:
instance = super().__call__(*args, **kwargs)
cls._instances[cls] = instance
return cls._instances[cls]

View File

@ -1,7 +1,10 @@
import asyncio
import importlib
import inspect
from pathlib import Path
from .chatbot.graph import ChatbotAgent
from .react.graph import ReActAgent
from src.agents.common.base import BaseAgent
from src.utils import logger
class AgentManager:
@ -35,10 +38,51 @@ class AgentManager:
agents = self.get_agents()
return await asyncio.gather(*[a.get_info() for a in agents])
def auto_discover_agents(self):
"""自动发现并注册 src/agents/ 下的所有智能体。
遍历 src/agents/ 目录下的所有子文件夹如果子文件夹包含 __init__.py
则尝试从中导入 BaseAgent 的子类并注册(使用自动导入的方式支持私有agent)
"""
# 获取 agents 目录的路径
agents_dir = Path(__file__).parent
# 遍历所有子目录
for item in agents_dir.iterdir():
logger.info(f"尝试导入模块:{item}")
# 跳过非目录、common 目录、__pycache__ 等
if not item.is_dir() or item.name.startswith("_") or item.name == "common":
continue
# 检查是否有 __init__.py 文件
init_file = item / "__init__.py"
if not init_file.exists():
logger.warning(f"{item} 不是一个有效的模块")
continue
# 尝试导入模块
try:
module_name = f"src.agents.{item.name}"
module = importlib.import_module(module_name)
# 查找模块中所有 BaseAgent 的子类
for name, obj in inspect.getmembers(module):
if (
inspect.isclass(obj)
and issubclass(obj, BaseAgent)
and obj is not BaseAgent
and obj.__module__.startswith(module_name)
):
logger.info(f"自动发现智能体: {obj.__name__} 来自 {item.name}")
self.register_agent(obj)
except Exception as e:
logger.warning(f"无法从 {item.name} 加载智能体: {e}")
agent_manager = AgentManager()
agent_manager.register_agent(ChatbotAgent)
agent_manager.register_agent(ReActAgent)
# 自动发现并注册所有智能体
agent_manager.auto_discover_agents()
agent_manager.init_all_agents()
__all__ = ["agent_manager"]

View File

@ -9,10 +9,20 @@ from src.agents.common.tools import get_buildin_tools
from src.storage.minio import upload_image_to_minio
from src.utils import logger
@tool
#TODO:[已完成]修改了tool定义的示例使用更符合langgraph调用的方式
@tool(name_or_callable="全能计算器",description="可以对给定的2个数字选择进行加减乘除四种计算")
def calculator(a: float, b: float, operation: str) -> float:
"""Calculate two numbers. operation: add, subtract, multiply, divide"""
"""
可以对给定的2个数字选择进行加减乘除四种计算
Args:
a: 第一个数字
b: 第二个数字
operation: 计算操作符号可以是addsubtractmultiplydivide
Returns:
float: 最终的计算结果
"""
try:
if operation == "add":
return a + b

View File

@ -0,0 +1,3 @@
from .graph import ReActAgent
__all__ = ["ReActAgent"]

View File

@ -43,9 +43,11 @@ MODEL_NAMES:
name: SiliconFlow
url: https://cloud.siliconflow.cn/models
base_url: https://api.siliconflow.cn/v1
default: deepseek-ai/DeepSeek-V3.2-Exp
default: Qwen/Qwen3-32B
env: SILICONFLOW_API_KEY
models:
- Qwen/Qwen3-Next-80B-A3B-Thinking
- Qwen/Qwen3-32B
- deepseek-ai/DeepSeek-V3.2-Exp
- Qwen/Qwen3-235B-A22B-Thinking-2507
- Qwen/Qwen3-235B-A22B-Instruct-2507
@ -98,6 +100,12 @@ MODEL_NAMES:
- anthropic/claude-sonnet-4
EMBED_MODEL_INFO:
siliconflow/Pro/BAAI/bge-m3:
name: Pro/BAAI/bge-m3
dimension: 1024
base_url: https://api.siliconflow.cn/v1/embeddings
api_key: SILICONFLOW_API_KEY
siliconflow/BAAI/bge-m3:
name: BAAI/bge-m3
dimension: 1024
@ -127,6 +135,10 @@ EMBED_MODEL_INFO:
dimension: 1024
RERANKER_LIST:
siliconflow/Pro/BAAI/bge-reranker-v2-m3:
name: Pro/BAAI/bge-reranker-v2-m3
base_url: https://api.siliconflow.cn/v1/rerank
api_key: SILICONFLOW_API_KEY
siliconflow/BAAI/bge-reranker-v2-m3:
name: BAAI/bge-reranker-v2-m3

View File

@ -12,6 +12,7 @@ from src.storage.db.models import Conversation, ConversationStats, Message, Tool
from src.utils import logger
from src.utils.datetime_utils import utc_now
#TODO:[未完成]待修改为异步版本
class ConversationManager:
"""Manager for conversation storage operations"""

View File

@ -5,6 +5,7 @@ from contextlib import contextmanager
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
from server.utils.singleton import SingletonMeta
from src import config
from src.storage.db.models import Base, User
from src.utils import logger
@ -18,8 +19,10 @@ except ImportError:
def validate_database_schema(db_path):
return True, []
# TODO:[优化建议]需要将数据库修改为异步的aiosqlite或者异步mysql缓存使用Redis存储
# TODO:[已完成]为DBManager添加单例模式
class DBManager:
class DBManager(metaclass=SingletonMeta):
"""数据库管理器 - 只提供基础的数据库连接和会话管理"""
def __init__(self):