From 85e13b64810a964b428ceb39c9dce389674a7da0 Mon Sep 17 00:00:00 2001 From: Wenjie Zhang Date: Thu, 28 Aug 2025 13:16:19 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0Makefile=E5=B9=B6?= =?UTF-8?q?=E6=94=B9=E8=BF=9B=E9=94=99=E8=AF=AF=E6=97=A5=E5=BF=97=E8=AE=B0?= =?UTF-8?q?=E5=BD=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs: 更新项目文档结构并删除旧文档 refactor: 优化工具工厂的错误处理逻辑 --- .github/ISSUE_TEMPLATE/提交一个bug.md | 15 ++++++++++ AGENTS.md | 43 +++++++++++++++++++++++++++ Makefile | 13 ++++++++ docs/vibe/AGENT.md | 43 --------------------------- src/agents/tools_factory.py | 9 +++--- 5 files changed, 75 insertions(+), 48 deletions(-) create mode 100644 AGENTS.md create mode 100644 Makefile delete mode 100644 docs/vibe/AGENT.md diff --git a/.github/ISSUE_TEMPLATE/提交一个bug.md b/.github/ISSUE_TEMPLATE/提交一个bug.md index 456967e7..59e1be1e 100644 --- a/.github/ISSUE_TEMPLATE/提交一个bug.md +++ b/.github/ISSUE_TEMPLATE/提交一个bug.md @@ -18,9 +18,24 @@ assignees: '' 请运行以下命令，并提供部分相关日志： ```sh +# macOS / Linux +make logs + +# Windows docker logs --tail=100 api-dev +git rev-parse HEAD ``` + + +``` +make logs 的输出： + + + +``` + + 3️⃣ 相关截图 diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..f2f03852 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,43 @@ + +# 项目目录结构 (Project Overview) + +Yuxi-Know 是一个基于知识图谱和向量数据库的智能知识库系统。它通过 FastAPI 提供后端 API，使用 Vue.js 构建前端界面，并利用 Docker Compose 进行整体服务的编排和管理。 + + +``` +Yuxi-Know/ +├── docker/ # Docker 配置文件 +├── scripts/ # 脚本文件，如批量上传等 +├── server/ # 服务端代码（部分） +├── src/ # 主要源代码目录 +│ ├── agents/ # 智能体应用 +│ ├── config/ # 配置文件 +│ ├── knowledge/ # 知识库相关 +│ ├── models/ # 数据模型 +│ ├── plugins/ # 插件（存放OCR） +│ ├── static/ # 静态资源（配置文件） +│ └── utils/ # 工具函数 +├── web/ # 前端代码 +└── docker-compose.yml # Docker Compose 配置 +``` + +# 核心服务与容器 (Core Services & Containers) + +项目使用 Docker Compose 管理多个服务，主要容器名称如下： +- `api-dev` - FastAPI 后端服务 +- `web-dev` - Vue.js 前端开发服务器 +- `graph` - Neo4j 图数据库 +- `milvus` - 向量数据库，包含 etcd 和 MinIO 依赖 +- `mineru` - 可选的 MinerU OCR 服务（需要 GPU） +- `paddlex` - 可选的 PaddleX OCR 服务（需要 GPU） + +## 开发与调试工作流 (Development & Debugging Workflow) + +本项目完全通过 Docker Compose 进行管理。所有开发和调试都应在运行的容器环境中进行。使用 `docker compose up -d` 命令进行构建和启动。 + +核心原则: 由于 api-dev 和 web-dev 服务均配置了热重载 (hot-reloading)，本地修改代码后无需重启容器，服务会自动更新。应该先检查项目是否已经在后台启动（`docker ps`），具体的可以阅读 [docker-compose.yml](docker-compose.yml). + +## 风格说明 + +- UI风格要简洁，同时要保持一致性，颜色要尽量参考 [base.css](web/src/assets/css/base.css) 中的颜色。不要悬停位移，不要过度使用阴影以及渐变色。 +- Python 代码要符合 Python 的规范，尽量使用较新的语法，避免使用旧版本的语法（版本兼容到 3.12+），使用 uvx ruff check 检查 lint。 diff --git a/Makefile b/Makefile new file mode 100644 index 00000000..4262f15c --- /dev/null +++ b/Makefile @@ -0,0 +1,13 @@ + +.PHONY: start logs + +start: + docker compose up -d + +stop: + docker compose down + +logs: + @docker logs --tail=50 api-dev + @echo "Commit ID: $$(git rev-parse HEAD)" + @echo "System: $$(uname -a)" diff --git a/docs/vibe/AGENT.md b/docs/vibe/AGENT.md deleted file mode 100644 index ed7ba9d3..00000000 --- a/docs/vibe/AGENT.md +++ /dev/null @@ -1,43 +0,0 @@ - -# 项目目录结构 - -``` -Yuxi-Know/ -├── docker/ # Docker 配置文件 -├── docs/ # 项目文档 -├── scripts/ # 脚本文件，如批量上传等 -├── server/ # 服务端代码（部分） -├── src/ # 主要源代码目录 -│ ├── agents/ # 智能体应用 -│ ├── config/ # 配置文件 -│ ├── knowledge/ # 知识库相关 -│ ├── models/ # 数据模型 -│ ├── plugins/ # 插件 -│ ├── static/ # 静态资源 -│ └── utils/ # 工具函数 -├── web/ # 前端代码 -└── docker-compose.yml # Docker Compose 配置 -``` - -# 主要容器名称 - -项目使用 Docker Compose 管理多个服务，主要容器名称如下： -- `api-dev` - FastAPI 后端服务 -- `web-dev` - Vue.js 前端开发服务器 -- `graph` - Neo4j 图数据库 -- `milvus` - 向量数据库，包含 etcd 和 MinIO 依赖 -- `mineru` - 可选的 MinerU OCR 服务（需要 GPU） -- `paddlex` - 可选的 PaddleX OCR 服务（需要 GPU） - -## 项目调试 - -此项目是使用 Docker 进行部署的，使用 `docker compose up -d` 命令进行构建和启动。因此当进行任何修改的时候，不要尝试启动这个项目，应该先检查项目是否已经在后台启动（`docker ps`），具体的可以阅读 [docker-compose.yml](docker-compose.yml). - -前端和后端都是配置了自动启动的，因此当修改完成后，会自动更新，可以使用 docker logs 查看日志。对于部分场景可以创建一个 test_router.py 在 [server/routers](server/routers) 中，然后通过 API 测试功能场景。对于前端的 UI 修改，则不用测试。 -对于后端的修改，可以写个独立的脚本尝试调用 API，比如 [test_api.py](scripts/test_api.py)。注意使用 `uv run` 来执行脚本。 - -## 风格说明 - -UI风格要简洁，同时要保持一致性，颜色要尽量参考 [base.css](web/src/assets/css/base.css) 中的颜色。不要悬停位移，不要过度使用阴影以及渐变色。 - -Python 代码要符合 Python 的规范，尽量使用较新的语法，避免使用旧版本的语法（版本兼容到 3.12+），使用 uvx ruff check 检查 lint。 diff --git a/src/agents/tools_factory.py b/src/agents/tools_factory.py index 29d28079..20206975 100644 --- a/src/agents/tools_factory.py +++ b/src/agents/tools_factory.py @@ -1,6 +1,5 @@ import asyncio -import hashlib -import os +import traceback from typing import Annotated, Any from pydantic import BaseModel, Field @@ -90,10 +89,10 @@ def get_kb_based_tools() -> dict[str, Any]: ) kb_tools[tool_id] = tool - logger.debug(f"Successfully created tool {tool_id} for database {db_id}") + # logger.debug(f"Successfully created tool {tool_id} for database {db_id}") except Exception as e: - logger.error(f"Failed to create tool for database {db_id}: {e}") + logger.error(f"Failed to create tool for database {db_id}: {e}, \n{traceback.format_exc()}") continue return kb_tools @@ -176,7 +175,7 @@ def query_knowledge_graph(query: Annotated[str, "The keyword to query knowledge logger.debug(f"Knowledge graph query returned {len(result.get('triples', [])) if isinstance(result, dict) else 'N/A'} triples") return result except Exception as e: - logger.error(f"Knowledge graph query error: {e}") + logger.error(f"Knowledge graph query error: {e}, {traceback.format_exc()}") return f"知识图谱查询失败: {str(e)}" def get_static_tools() -> dict[str, Any]: