Merge branch 'feature/documents'

Author: xerrors

AGENTS.md

@@ -1,32 +1,51 @@
 
 # 项目目录结构 (Project Overview)
 
-Yuxi-Know 是一个基于知识图谱和向量数据库的智能知识库系统。它通过 FastAPI 提供后端 API，使用 Vue.js 构建前端界面，并利用 Docker Compose 进行整体服务的编排和管理。
+Yuxi-Know 是一个基于大模型的智能知识库与知识图谱智能体开发平台，融合了 RAG 技术与知识图谱技术，基于 LangGraph v1 + Vue.js + FastAPI + LightRAG 架构构建。项目完全通过 Docker Compose 进行管理，支持热重载开发。
 
-文档中心在 `docs` 文件夹下面。
+## 开发准则
+
+Avoid over-engineering. Only make changes that are directly requested or clearly necessary. Keep solutions simple and focused.
+
+Don't add features, refactor code, or make "improvements" beyond what was asked. A bug fix doesn't need surrounding code cleaned up. A simple feature doesn't need extra configurability.
+
+Don't add error handling, fallbacks, or validation for scenarios that can't happen. Trust internal code and framework guarantees. Only validate at system boundaries (user input, external APIs). Don't use backwards-compatibility shims when you can just change the code.
+
+Don't create helpers, utilities, or abstractions for one-time operations. Don't design for hypothetical future requirements. The right amount of complexity is the minimum needed for the current task. Reuse existing abstractions where possible and follow the DRY principle.
 
 ## 开发与调试工作流 (Development & Debugging Workflow)
 
 本项目完全通过 Docker Compose 进行管理。所有开发和调试都应在运行的容器环境中进行。使用 `docker compose up -d` 命令进行构建和启动。
 
-核心原则: 由于 api-dev 和 web-dev 服务均配置了热重载 (hot-reloading)，本地修改代码后无需重启容器，服务会自动更新。应该先检查项目是否已经在后台启动（`docker ps`），查看日志（`docker logs api-dev --tail 100`）具体的可以阅读 [docker-compose.yml](docker-compose.yml).
+**核心原则**: 由于 api-dev 和 web-dev 服务均配置了热重载 (hot-reloading)，本地修改代码后无需重启容器，服务会自动更新。应该先检查项目是否已经在后台启动（`docker ps`），查看日志（`docker logs api-dev --tail 100`）具体的可以阅读 [docker-compose.yml](docker-compose.yml).
 
-前端开发规范：
+### 前端开发规范
 
-- API 接口规范：所有的 API 接口都应该定义在 web/src/apis 下面，并继承自 apiGet/apiPost/apiRequest 以及其他。
+- API 接口规范：所有的 API 接口都应该定义在 web/src/apis 下面
 - Icon 应该从 @ant-design/icons-vue 或者 lucide-vue-next （推荐，但是需要注意尺寸）
 - Vue 中的样式使用 less，非必要情况必须使用[base.css](web/src/assets/css/base.css) 中的颜色变量。
-- UI风格要简洁，同时要保持一致性，颜色要尽量参考 不要悬停位移，不要过度使用阴影以及渐变色。
+- UI风格要简洁，同时要保持一致性，不要悬停位移，不要过度使用阴影以及渐变色。
 - 绝对不要尝试使用 npm/pnpm 等等运行前端开发服务器。
 
 
-后端开发规范：
+### 后端开发规范
+
+```bash
+# 代码检查和格式化
+make lint          # 检查代码规范
+make format        # 格式化代码
+
+# 直接在容器内执行命令
+docker compose exec api uv run python test/your_script.py  # 放在 test 文件夹
+```
+
+注意：
 
-- 项目使用 uv 来管理依赖，所以必须使用 uv run 来调试。
-- Python 代码要符合 Python 的规范，符合 pythonic 风格，尽量使用较新的语法，避免使用旧版本的语法（版本兼容到 3.12+），使用 make lint 检查 lint。使用 make format 来格式化代码。
+- Python 代码要符合 Python 的规范，符合 pythonic 风格
+- 尽量使用较新的语法，避免使用旧版本的语法（版本兼容到 3.12+）
 
-其他：
+**其他**：
 
+- 使用 YUXI_SUPER_ADMIN_NAME / YUXI_SUPER_ADMIN_PASSWORD 调试接口
 - 如果需要新建说明文档（仅开发者可见，非必要不创建），则保存在 `docs/vibe` 文件夹下面
-- 测试脚本可以放在 test 文件夹下面，可以从 docker 中启动测试（不要使用本地 Python 环境）
 - 代码更新后要检查文档部分是否有需要更新的地方，文档的目录定义在 `docs/.vitepress/config.mts` 中。文档应该更新最新版（`docs/latest`）

CLAUDE.md

@@ -1,159 +1,51 @@
-# CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## 项目概述
+# 项目目录结构 (Project Overview)
 
 Yuxi-Know 是一个基于大模型的智能知识库与知识图谱智能体开发平台，融合了 RAG 技术与知识图谱技术，基于 LangGraph v1 + Vue.js + FastAPI + LightRAG 架构构建。项目完全通过 Docker Compose 进行管理，支持热重载开发。
 
-## 开发环境管理
+## 开发准则
 
-### 核心原则
-- 所有开发调试都应在运行的 Docker 容器环境中进行
-- 使用 `docker compose up -d` 启动完整开发环境
-- api-dev 和 web-dev 服务均配置热重载，本地修改代码后无需重启容器
-- 先检查 `docker ps` 确认服务状态，使用 `docker logs api-dev --tail 100` 查看日志
+Avoid over-engineering. Only make changes that are directly requested or clearly necessary. Keep solutions simple and focused.
 
-### 常用命令
+Don't add features, refactor code, or make "improvements" beyond what was asked. A bug fix doesn't need surrounding code cleaned up. A simple feature doesn't need extra configurability.
 
-#### 项目启动和停止
-```bash
-# 启动所有服务
-make start
-# 或
-docker compose up -d
-
-# 停止所有服务
-make stop
-# 或
-docker compose down
-
-# 查看日志
-make logs
-# 或
-docker logs --tail=50 api-dev
-```
+Don't add error handling, fallbacks, or validation for scenarios that can't happen. Trust internal code and framework guarantees. Only validate at system boundaries (user input, external APIs). Don't use backwards-compatibility shims when you can just change the code.
 
-#### 后端开发（在 Docker 容器内）
-```bash
-# 代码检查和格式化
-make lint          # 检查代码规范
-make format        # 格式化代码
-make format_diff   # 查看格式化差异
+Don't create helpers, utilities, or abstractions for one-time operations. Don't design for hypothetical future requirements. The right amount of complexity is the minimum needed for the current task. Reuse existing abstractions where possible and follow the DRY principle.
 
-# 运行测试
-make router-tests  # 运行 API 路由测试
+## 开发与调试工作流 (Development & Debugging Workflow)
 
-# 直接在容器内执行命令
-docker compose exec api uv run python your_script.py
-```
+本项目完全通过 Docker Compose 进行管理。所有开发和调试都应在运行的容器环境中进行。使用 `docker compose up -d` 命令进行构建和启动。
 
-#### 前端开发
-```bash
-# 在 web 目录下执行
-pnpm run dev        # 开发模式（已通过 Docker 配置）
-pnpm run build      # 构建生产版本
-pnpm run lint       # ESLint 检查
-pnpm run format     # Prettier 格式化
-```
+**核心原则**: 由于 api-dev 和 web-dev 服务均配置了热重载 (hot-reloading)，本地修改代码后无需重启容器，服务会自动更新。应该先检查项目是否已经在后台启动（`docker ps`），查看日志（`docker logs api-dev --tail 100`）具体的可以阅读 [docker-compose.yml](docker-compose.yml).
 
-#### 文档开发
-```bash
-# 在 docs 目录下执行
-pnpm run docs:dev   # 开发文档
-pnpm run docs:build # 构建文档
-```
+### 前端开发规范
 
-## 项目架构
+- API 接口规范：所有的 API 接口都应该定义在 web/src/apis 下面
+- Icon 应该从 @ant-design/icons-vue 或者 lucide-vue-next （推荐，但是需要注意尺寸）
+- Vue 中的样式使用 less，非必要情况必须使用[base.css](web/src/assets/css/base.css) 中的颜色变量。
+- UI风格要简洁，同时要保持一致性，不要悬停位移，不要过度使用阴影以及渐变色。
+- 绝对不要尝试使用 npm/pnpm 等等运行前端开发服务器。
 
-### 技术栈
-- **后端**: FastAPI + Python 3.11+，使用 uv 管理依赖
-- **前端**: Vue 3.5 + Vite 7 + Ant Design Vue + Pinia
-- **AI框架**: LangChain v1 + LangGraph v1 + LightRAG
-- **数据库**: Neo4j (图数据库) + Milvus (向量数据库) + MinIO (对象存储)
-- **容器化**: Docker Compose 多服务编排
 
-### 核心目录结构
-```
-├── server/          # FastAPI 后端服务
-├── web/             # Vue.js 前端应用
-├── src/             # 核心业务逻辑代码
-├── docs/            # 文档中心 (VitePress)
-├── test/            # 测试代码
-├── docker/          # Docker 配置文件
-├── scripts/         # 脚本工具
-├── saves/           # 数据保存目录
-├── models/          # 模型文件目录
-└── docker-compose.yml
-```
+### 后端开发规范
 
-### 主要服务
-- `api-dev`: FastAPI 后端服务 (端口 5050)
-- `web-dev`: Vue.js 前端服务 (端口 5173)
-- `graph`: Neo4j 图数据库 (端口 7474, 7687)
-- `milvus`: Milvus 向量数据库 (端口 19530)
-- `minio`: MinIO 对象存储 (端口 9000, 9001)
-- `mineru`: MinerU 文档解析服务 (可选)
-- `paddlex`: PaddleX OCR 服务 (可选)
+```bash
+# 代码检查和格式化
+make lint          # 检查代码规范
+make format        # 格式化代码
 
-## 开发规范
+# 直接在容器内执行命令
+docker compose exec api uv run python test/your_script.py  # 放在 test 文件夹
+```
 
-### 前端开发规范
-- **API 接口**: 所有 API 接口定义在 `web/src/apis` 下，继承自 `apiGet/apiPost/apiRequest`
-- **图标**: 从 `@ant-design/icons-vue` 或 `lucide-vue-next` 选取
-- **样式**: 使用 Less，优先采用 `web/src/assets/css/base.css` 中的颜色
-- **UI风格**: 简洁一致，避免悬停位移、过度阴影和渐变色
-- **组件库**: 基于 Ant Design Vue，保持组件一致性
+注意：
 
-### 后端开发规范
-- **包管理**: 使用 uv 管理依赖，调试时使用 `uv run`
-- **代码规范**: 符合 Pythonic 风格，支持 Python 3.12+ 语法
-- **代码质量**: 使用 `make lint` 检查，`make format` 格式化
-- **API设计**: 遵循 RESTful 规范，使用 Pydantic 进行数据验证
-
-### 通用开发规范
-- **文档更新**: 代码更新后同步更新 `docs/latest` 中的相关文档
-- **测试**: 测试脚本放在 `test/` 目录，从 Docker 容器中运行
-- **环境变量**: 配置通过 `.env` 文件管理
-- **数据安全**: 敏感数据不提交到版本控制
-
-## 特色功能模块
-
-### 智能体系统
-- 基于 LangGraph v1 的智能体框架
-- 支持多代理协作和工具调用
-- 提供完整的智能体开发套件
-
-### 知识管理
-- 多模态文档解析 (PDF、Word、图片等)
-- 知识图谱自动构建和可视化
-- 向量化存储和检索
-
-### 数据处理
-- MinerU 文档解析集成
-- PaddleX OCR 文字识别
-- 支持多种模型提供商 (OpenAI、DeepSeek、阿里云等)
-
-## 调试和故障排除
-
-### 常见问题排查
-1. **服务启动失败**: 检查端口占用和 Docker 服务状态
-2. **API 连接问题**: 确认 `VITE_API_URL` 环境变量配置
-3. **模型加载问题**: 检查 `models/` 目录和权限设置
-4. **数据库连接**: 确认 Neo4j 和 Milvus 服务健康状态
-
-### 日志查看
-```bash
-# 查看各服务日志
-docker logs api-dev --tail 100
-docker logs web-dev --tail 50
-docker logs graph --tail 50
-docker logs milvus --tail 50
-```
+- Python 代码要符合 Python 的规范，符合 pythonic 风格
+- 尽量使用较新的语法，避免使用旧版本的语法（版本兼容到 3.12+）
 
-### 性能监控
-- 使用健康检查端点 `/api/system/health`
-- 监控 GPU 使用情况 (如果使用 GPU 服务)
-- 检查内存和磁盘使用情况
+**其他**：
 
-You MUST read `./AGENTS.md`
+- 使用 YUXI_SUPER_ADMIN_NAME / YUXI_SUPER_ADMIN_PASSWORD 调试接口
+- 如果需要新建说明文档（仅开发者可见，非必要不创建），则保存在 `docs/vibe` 文件夹下面
+- 代码更新后要检查文档部分是否有需要更新的地方，文档的目录定义在 `docs/.vitepress/config.mts` 中。文档应该更新最新版（`docs/latest`）

Makefile

@@ -4,6 +4,10 @@
 PYTEST_ARGS ?=
 
 start:
+	@if [ ! -f .env ]; then \
+		echo "Error: .env file not found. Please create it from .env.template"; \
+		exit 1; \
+	fi
 	docker compose up -d
 
 stop:

docker/api.Dockerfile

@@ -1,35 +1,40 @@
 # 使用轻量级Python基础镜像
 FROM python:3.12-slim
 COPY --from=ghcr.io/astral-sh/uv:0.7.2 /uv /uvx /bin/
+COPY --from=node:20-slim /usr/local/bin /usr/local/bin
+COPY --from=node:20-slim /usr/local/lib/node_modules /usr/local/lib/node_modules
+COPY --from=node:20-slim /usr/local/include /usr/local/include
+COPY --from=node:20-slim /usr/local/share /usr/local/share
 
 # 设置工作目录
 WORKDIR /app
 
 # 环境变量设置
 ENV TZ=Asia/Shanghai \
-    UV_LINK_MODE=copy \
+    UV_PROJECT_ENVIRONMENT="/usr/local" \
+    UV_COMPILE_BYTECODE=1 \
     DEBIAN_FRONTEND=noninteractive
 
+RUN npm install -g npm@latest && npm cache clean --force
+
 # 设置代理和时区，更换镜像源，安装系统依赖 - 合并为一个RUN减少层数
-RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone && \
-    # 更换为阿里云镜像源加速下载
-    sed -i 's|http://deb.debian.org/debian|http://mirrors.tuna.tsinghua.edu.cn/debian|g' /etc/apt/sources.list.d/debian.sources && \
-    sed -i 's|http://security.debian.org/debian-security|http://mirrors.tuna.tsinghua.edu.cn/debian-security|g' /etc/apt/sources.list.d/debian.sources && \
-    # sed -i 's|mirrors.aliyun.com|mirrors.tuna.tsinghua.edu.cn|g' /etc/apt/sources.list.d/debian.sources && \
-    # 清理apt缓存并更新，避免空间不足问题
-    apt-get clean && \
-    rm -rf /var/lib/apt/lists/* /var/cache/apt/archives/* && \
-    apt-get update && \
-    # 安装系统依赖，减少缓存占用
-    apt-get install -y --no-install-recommends --fix-missing \
-        python3-dev \
+RUN set -ex \
+    # (A) 设置时区
+    && ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone \
+    # (B) 替换清华源 (针对 Debian Bookworm 的新版格式)
+    && sed -i 's|deb.debian.org|mirrors.tuna.tsinghua.edu.cn|g' /etc/apt/sources.list.d/debian.sources \
+    && sed -i 's|security.debian.org/debian-security|mirrors.tuna.tsinghua.edu.cn/debian-security|g' /etc/apt/sources.list.d/debian.sources \
+    # (C) 安装必要的系统库
+    && apt-get update \
+    && apt-get install -y --no-install-recommends --fix-missing \
+        curl \
         ffmpeg \
         libsm6 \
         libxext6 \
-        curl \
-        && apt-get autoremove -y && \
-        apt-get autoclean && \
-        rm -rf /var/lib/apt/lists/* /var/cache/apt/archives/* /tmp/* /var/tmp/*
+    # (D) 清理垃圾，减小体积
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
 
 # 复制项目配置文件
 COPY ../pyproject.toml /app/pyproject.toml