docs: 更新文档结构和内容，添加新功能说明（新增区分开发版和稳定版）

2025-11-08 10:52:09 +08:00 · 2025-11-08 10:52:09 +08:00 · 62cdd8648f
commit 62cdd8648f
parent 8b4b7c230c
27 changed files with 1634 additions and 39 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@ -28,4 +28,4 @@ Yuxi-Know 是一个基于知识图谱和向量数据库的智能知识库系统

 - 如果需要新建说明文档（仅开发者可见，非必要不创建），则保存在 `docs/vibe` 文件夹下面
 - 测试脚本可以放在 test 文件夹下面，可以从 docker 中启动测试（不要使用本地 Python 环境）
- 代码更新后要检查文档部分是否有需要更新的地方，文档的目录定义在 `docs/.vitepress/config.mts` 中
+- 代码更新后要检查文档部分是否有需要更新的地方，文档的目录定义在 `docs/.vitepress/config.mts` 中。文档应该更新最新版（`docs/latest`）
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@ -5,8 +5,8 @@ import markdownItTaskCheckbox from 'markdown-it-task-checkbox'
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
  lang: 'zh-CN',
-  title: "Yuxi-Know Docs",
-  description: "文档中心",
+  title: "Yuxi-Know",
+  description: "语析",
  base: '/Yuxi-Know/',
  markdown: {
    config: (md) => {
@ -17,40 +17,76 @@ export default defineConfig({
    // https://vitepress.dev/reference/default-theme-config
    logo: "/favicon.svg",
    nav: [
-      { text: '快速开始', link: '/intro/quick-start' },
-    ],
-
-    sidebar: [
      {
-        text: '简介',
+        text: 'Version',
        items: [
-          { text: '什么是 Yuxi-Know？', link: '/intro/project-overview' },
-          { text: '快速开始', link: '/intro/quick-start' },
-          { text: '模型配置', link: '/intro/model-config' },
-          { text: '知识库与知识图谱', link: '/intro/knowledge-base' }
-        ]
-      },
-      {
-        text: '高级配置',
-        items: [
-          { text: '配置系统详解', link: '/advanced/configuration' },
-          { text: '文档解析', link: '/advanced/document-processing' },
-          { text: '智能体', link: '/advanced/agents-config' },
-          { text: '品牌自定义', link: '/advanced/branding' },
-          { text: '其他配置', link: '/advanced/misc' }
-        ]
-      },
-      {
-        text: '更新日志',
-        items: [
-          { text: '版本说明 v0.3', link: '/changelog/0.3-release-notes' },
-          { text: '路线图', link: '/changelog/roadmap' },
-          { text: '参与贡献', link: '/changelog/contributing' },
-          { text: '常见问题', link: '/changelog/faq' }
+          { text: 'Latest (开发版)', link: '/latest/intro/quick-start' },
+          { text: 'v0.3.0 (稳定版)', link: '/v0.3.0/intro/quick-start' }
        ]
      }
    ],

+    sidebar: {
+      '/latest/': [
+        {
+          text: '简介',
+          items: [
+            { text: '什么是 Yuxi-Know？', link: '/latest/intro/project-overview' },
+            { text: '快速开始', link: '/latest/intro/quick-start' },
+            { text: '模型配置', link: '/latest/intro/model-config' },
+            { text: '知识库与知识图谱', link: '/latest/intro/knowledge-base' }
+          ]
+        },
+        {
+          text: '高级配置',
+          items: [
+            { text: '配置系统详解', link: '/latest/advanced/configuration' },
+            { text: '文档解析', link: '/latest/advanced/document-processing' },
+            { text: '智能体', link: '/latest/advanced/agents-config' },
+            { text: '品牌自定义', link: '/latest/advanced/branding' },
+            { text: '其他配置', link: '/latest/advanced/misc' }
+          ]
+        },
+        {
+          text: '更新日志',
+          items: [
+            { text: '路线图', link: '/latest/changelog/roadmap' },
+            { text: '参与贡献', link: '/latest/changelog/contributing' },
+            { text: '常见问题', link: '/latest/changelog/faq' }
+          ]
+        }
+      ],
+      '/v0.3.0/': [
+        {
+          text: '简介',
+          items: [
+            { text: '什么是 Yuxi-Know？', link: '/v0.3.0/intro/project-overview' },
+            { text: '快速开始', link: '/v0.3.0/intro/quick-start' },
+            { text: '模型配置', link: '/v0.3.0/intro/model-config' },
+            { text: '知识库与知识图谱', link: '/v0.3.0/intro/knowledge-base' }
+          ]
+        },
+        {
+          text: '高级配置',
+          items: [
+            { text: '配置系统详解', link: '/v0.3.0/advanced/configuration' },
+            { text: '文档解析', link: '/v0.3.0/advanced/document-processing' },
+            { text: '智能体', link: '/v0.3.0/advanced/agents-config' },
+            { text: '品牌自定义', link: '/v0.3.0/advanced/branding' },
+            { text: '其他配置', link: '/v0.3.0/advanced/misc' }
+          ]
+        },
+        {
+          text: '更新日志',
+          items: [
+            { text: '版本说明 v0.3', link: '/v0.3.0/changelog/0.3-release-notes' },
+            { text: '参与贡献', link: '/v0.3.0/changelog/contributing' },
+            { text: '常见问题', link: '/v0.3.0/changelog/faq' }
+          ]
+        }
+      ]
+    },
+
    socialLinks: [
      { icon: 'github', link: 'https://github.com/xerrors/Yuxi-Know' }
    ],
--- a/docs/index.md
+++ b/docs/index.md
@ -11,11 +11,11 @@ hero:
    alt: VitePress
  actions:
    - theme: brand
-      text: 快速开始
-      link: /intro/quick-start
+      text: Latest 文档
+      link: /latest/intro/quick-start
    - theme: alt
-      text: 在线演示
-      link: https://www.bilibili.com/video/BV1ETedzREgY/
+      text: v0.3.0 文档
+      link: /v0.3.0/intro/quick-start

 features:
  - title: 🤖 智能体与模型
@ -32,12 +32,12 @@ features:
    details: 完整的测试套件、API 文档、监控日志，适合企业级部署和使用
 ---

-
-
-## 轻松部署
+## 快速开始

 ```sh
 docker compose up --build -d
 ```

-查看端口与服务说明：高级配置 → 其他配置 → 服务端口。
+## 在线演示
+
+观看视频演示：[Bilibili](https://www.bilibili.com/video/BV1DF14BTETq)
--- a/docs/latest/advanced/agents-config.md
+++ b/docs/latest/advanced/agents-config.md
--- a/docs/latest/advanced/branding.md
+++ b/docs/latest/advanced/branding.md
--- a/docs/latest/advanced/configuration.md
+++ b/docs/latest/advanced/configuration.md
--- a/docs/latest/advanced/document-processing.md
+++ b/docs/latest/advanced/document-processing.md
--- a/docs/latest/advanced/misc.md
+++ b/docs/latest/advanced/misc.md
--- a/docs/latest/changelog/contributing.md
+++ b/docs/latest/changelog/contributing.md
@ -0,0 +1,125 @@
+# 参与贡献
+
+感谢所有贡献者的支持！
+
+<a href="https://github.com/xerrors/Yuxi-Know/contributors">
+    <img src="https://contributors.nn.ci/api?repo=xerrors/Yuxi-Know" alt="贡献者名单">
+</a>
+
+## 如何贡献
+
+### 1. Fork 项目
+
+在 GitHub 上 Fork 本项目到你的账户。
+
+### 2. 创建分支
+
+```bash
+git checkout -b feature/amazing-feature
+```
+
+### 3. 提交更改
+
+```bash
+git commit -m 'feat: Add some amazing feature'
+```
+
+### 4. 推送分支
+
+```bash
+git push origin feature/amazing-feature
+```
+
+### 5. 创建 PR
+
+在 GitHub 上创建 Pull Request，详细描述你的更改内容。
+
+## 开发指南
+
+### 代码规范
+
+- 遵循项目代码规范
+- Python 代码使用 `make format` 格式化
+- 使用 `make lint` 检查代码质量
+- 添加必要的测试用例
+- 更新相关文档
+
+### 提交规范
+
+使用清晰的提交信息：
+
+```
+feat: 添加新功能
+fix: 修复 bug
+docs: 更新文档
+style: 代码格式调整
+refactor: 代码重构
+test: 添加测试
+chore: 构建过程或辅助工具的变动
+```
+
+
+## 🐞 Bug 修复发布流程
+
+如果在发布 `v0.3.0` 后发现 bug：
+
+### ✅ 情况 1：main 上没有未完成的新功能
+
+直接在 main 修复并发布：
+
+```bash
+git commit -m "fix: resolve config parser crash"
+git tag -a v0.3.1 -m "Hotfix v0.3.1"
+git push origin main --tags
+```
+
+### ⚙️ 情况 2：main 上已有新功能未完成
+
+从上一个 tag 建立 hotfix 分支：
+
+```bash
+git checkout -b hotfix/0.3.1 v0.3.0
+# 修复问题
+git commit -m "fix: resolve config parser crash"
+git push origin hotfix/0.3.1
+
+# 测试后合并回 main 并打 tag
+git checkout main
+git merge --no-ff hotfix/0.3.1
+git tag -a v0.3.1 -m "Hotfix v0.3.1"
+git push origin main --tags
+
+# 删除临时分支
+git branch -d hotfix/0.3.1
+git push origin --delete hotfix/0.3.1
+```
+
+
+### 测试要求
+
+::: tip 测试
+- `make lint` / `make format` 保持代码整洁
+- `cp test/.env.test.example test/.env.test` 配置测试凭据
+- `make router-tests` 运行集成路由测试，支持 `PYTEST_ARGS="-k chat_router"`
+- `uv run --group test pytest test/api` 可直接运行 pytest（容器内）
+:::
+
+<details>
+<summary>常用命令</summary>
+
+```bash
+# 全量路由测试
+make router-tests
+
+# 仅运行知识库相关用例
+make router-tests PYTEST_ARGS="-k knowledge_router"
+
+# 不经过 Makefile，直接调用 pytest
+uv run --group test pytest test/api -vv
+```
+
+</details>
+
+## 许可证
+
+本项目基于 MIT License 开源，贡献的代码将遵循相同的许可证。
--- a/docs/latest/changelog/faq.md
+++ b/docs/latest/changelog/faq.md
@ -0,0 +1,41 @@
+# 常见问题
+
+以下为最常见的安装与使用问题，更多细节请参阅相应章节链接。
+
+- 首次运行如何创建管理员？
+  - Web 首次启动会引导初始化；也可调用 API：
+    - `GET /api/auth/check-first-run` → `first_run=true` 时
+    - `POST /api/auth/initialize` 提交 `user_id` 与 `password`
+  - 无默认账号，初始化后使用创建的超级管理员登录
+
+- 镜像拉取/构建失败？
+  - 可使用 `docker/pull_image.sh` 辅助拉取，或配置代理环境变量 `HTTP_PROXY/HTTPS_PROXY`
+  - 若已配置代理仍失败，可临时取消代理后重试
+  - 参考：介绍 → 快速开始 → 故障排除
+
+- 服务端口与访问地址？
+  - Web: `http://localhost:5173`；API 文档: `http://localhost:5050/docs`
+  - 端口一览与说明见：高级配置 → 其他配置 → 服务端口
+
+- Milvus/Neo4j 启动或连接失败？
+  - 重启：`docker compose up milvus -d && docker restart api-dev`
+  - Neo4j 默认：用户名 `neo4j`、密码 `0123456789`、管理界面 `http://localhost:7474`
+
+- OCR 模型或服务不可用？
+  - RapidOCR 本地模型：确保 `MODEL_DIR/SWHL/RapidOCR` 下存在 `PP-OCRv4` 模型
+  - MinerU/PaddleX：检查健康检查接口与 GPU/CUDA 版本
+  - 参考：高级配置 → 文档解析
+
+- 支持的文件类型与常见入库失败？
+  - 查询：`GET /api/knowledge/files/supported-types`
+  - 常见失败：不支持的扩展名、内容哈希重复（去重）、OCR 服务未就绪
+
+- 批量上传与转换示例？
+  - 上传入库：`uv run scripts/batch_upload.py upload --db-id <id> --directory <dir> --username <u> --password <p> --base-url http://127.0.0.1:5050/api`
+  - 参考：高级配置 → 文档解析
+
+- 登录失败被锁定？
+  - 多次失败会临时锁定账户，请根据提示等待后重试
+
+- 如何查看日志和状态？
+  - `docker ps` 查看整体；`docker logs api-dev -f`、`docker logs web-dev -f` 查看服务日志
--- a/docs/latest/changelog/roadmap.md
+++ b/docs/latest/changelog/roadmap.md
@ -0,0 +1,50 @@
+# 开发路线图
+
+路线图可能会经常变更，如果有强烈的建议，可以在 [issue](https://github.com/xerrors/Yuxi-Know/issues) 中提。
+
+
+## v0.4
+
+
+
+### 看板
+
+- 新建 DeepAgents 智能体（暂时没有场景）
+- 添加对于上传文件的支持
+- 统一图谱数据结构，优化可视化方式 [#298](https://github.com/xerrors/Yuxi-Know/issues/298) [#273](https://github.com/xerrors/Yuxi-Know/issues/273) <Badge type="info" text="0.4" />
+- 集成智能体评估，首先使用命令行来实现，然后考虑放在 UI 里面展示
+- 开发与生产环境隔离，构建生产镜像 <Badge type="info" text="0.4" />
+- 集成 LangFuse (观望) 添加用户日志与用户反馈模块，可以在 AgentView 中查看信息
+
+### Bugs
+- 部分异常状态下，智能体的模型名称出现重叠[#279](https://github.com/xerrors/Yuxi-Know/issues/279)
+- 消息中断没有达到预期效果，看不到截断的消息
+
+### 新增
+- 优化知识库详情页面，更加简洁清晰
+
+### 修复
+- 修复重排序模型实际未生效的问题
+
+
+## v0.3
+### Added
+- 添加测试脚本，覆盖最常见的功能（已覆盖API）
+- 新建 tasker 模块，用来管理所有的后台任务，UI 上使用侧边栏管理。Tasker 中获取历史任务的时候，仅获取 top100 个 task。
+- 优化对文档信息的检索展示（检索结果页、详情页）
+- 优化全局配置的管理模型，优化配置管理
+- 支持 MinerU 2.5 的解析方法 <Badge type="info" text="0.3.5" />
+- 修改现有的智能体Demo，并尽量将默认助手的特性兼容到 LangGraph 的 [`create_agent`](https://docs.langchain.com/oss/python/langchain/agents) 中
+- 基于 create_agent 创建 SQL Viewer 智能体 <Badge type="info" text="0.3.5" />
+- 优化 MCP 逻辑，支持 common + special 创建方式 <Badge type="info" text="0.3.5" />
+- LightRAG 知识库应该可以支持修改 LLM
+
+### Fixed
+- 修复本地知识库的 metadata 和 向量数据库中不一致的情况。
+- v1 版本的 LangGraph 的工具渲染有问题
+- upload 接口会阻塞主进程
+- LightRAG 知识库查看不了解析后的文本，偶然出现，未复现
+- 智能体的加载状态有问题：（1）智能体加载没有动画；（2）切换对话和加载中，使用同一个loading状态。
+- 前端工具调用渲染出现问题
+- 当前 ReAct 智能体有消息顺序错乱的 bug，且不会默认调用工具
+- 修复文件管理：（1）文件选择的时候会跨数据库；（2）文件校验会算上失败的文件；
--- a/docs/latest/intro/knowledge-base.md
+++ b/docs/latest/intro/knowledge-base.md
--- a/docs/latest/intro/model-config.md
+++ b/docs/latest/intro/model-config.md
--- a/docs/latest/intro/project-overview.md
+++ b/docs/latest/intro/project-overview.md
--- a/docs/latest/intro/quick-start.md
+++ b/docs/latest/intro/quick-start.md
--- a/docs/v0.3.0/advanced/agents-config.md
+++ b/docs/v0.3.0/advanced/agents-config.md
@ -0,0 +1,125 @@
+# 智能体
+
+## 智能体开发
+
+系统基于 [LangGraph](https://github.com/langchain-ai/langgraph) 并通过统一的 `AgentManager` 管理所有智能体。`src/agents/__init__.py` 会在启动时遍历 `src/agents` 目录，对每个包含 `__init__.py` 的子包执行自动发现：所有继承 `BaseAgent` 的类都会被注册并立即初始化，因此只要代码落位正确，就不需要再手动登记或修改管理器。
+
+仓库预置了若干可直接运行的智能体：`chatbot` 聚焦对话与动态工具调度，`mini_agent` 提供精简模板，`reporter` 演示报告类链路。这些目录展示了上下文类、Graph 构造方式、子智能体引用以及中间件组合的范例，新增功能时可以直接复用。
+
+### 智能体元数据配置
+
+每个智能体可以通过在智能体目录下创建 `metadata.toml` 文件来配置元数据信息。这个文件使用 TOML 格式，包含以下字段：
+
+- `name`: 智能体显示名称
+- `description`: 智能体功能描述
+- `examples`: 示例问题列表（数组格式）
+
+例如，`src/agents/chatbot/metadata.toml`：
+
+<<< @/../src/agents/chatbot/metadata.toml
+
+**注意**：`metadata.toml` 文件是可选的，如果没有提供，系统将使用智能体类的基本属性。
+
+### 创建新的智能体
+
+在 `src/agents` 下新建一个包，保持与现有目录一致的结构：放置 Graph 构造逻辑（通常命名为 `graph.py`），并在包内的 `__init__.py` 中暴露主类。
+
+智能体类必须继承 `src.agents.common.BaseAgent`，同时实现异步的 `get_graph` 方法来返回编译后的 LangGraph 实例，并配置好 `checkpointer`，否则无法从历史对话中恢复。
+
+需要额外上下文字段时，可继承 `BaseContext` 构建自己的配置表单，再把类绑定到 `context_schema`，平台会在 `saves/agents/<module>` 下生成默认配置。
+
+案例1 使用内置工具构建一个极简的智能体，可以动态选择 Prompt 和 LLM：
+
+<<< @/../src/agents/mini_agent/graph.py
+
+案例2 基于MySQL工具，以及自定义 MCP Server 的数据库报表助手。
+
+<<< @/../src/agents/reporter/graph.py
+
+
+
+智能体实例的生命周期交给管理器处理，会在自动发现时完成初始化并缓存单例，以便快速响应请求。在容器内热重载时，只要保存文件即可触发重新导入；需要强制刷新可调用 `agent_manager.get_agent(<id>, reload=True)`。
+
+更多动态工具选择与 MCP 注册的例子，见 `src/agents/chatbot/graph.py` 中的中间件组合。
+
+### 拓展现有智能体
+
+智能体保持为 LangGraph 的标准节点组合，因此可以在原有 `graph.py` 中添加节点、条件与消息转换器。复用现成上下文时，只需扩展当前 `context_schema` 的字段；若功能差异较大，可以创建新的上下文类并替换 `context_schema`。
+
+对工具、模型或提示语的调整建议封装到中间件或独立函数里，既方便多智能体共用，又能保持 `BaseAgent` 的基础接口稳定。变更提交后无需手动刷新注册表，只要确保包结构未改变，智能体会在热重载中自动更新。
+
+### 子智能体与中间件
+
+子智能体集中放在 `src/agents/common/subagents` 目录，典型例子是 `calc_agent`，它通过 LangChain 的 `create_agent` 构建计算器能力并以工具暴露给主图。新增子智能体时沿用这一结构：在目录内编写封装函数与 `@tool` 装饰器，导出后即可被任意智能体调用。
+
+中间件位于 `src/agents/common/middlewares`，包含上下文感知提示词、模型选择、动态工具加载以及附件注入等实现。如果需要编写新的中间件，请遵循 LangChain 官方文档中对 `AgentMiddleware`、`ModelRequest`、`ModelResponse` 等接口的定义，完成后在该目录的 `__init__.py` 暴露入口，主智能体即可在 `middleware` 列表中引用。
+
+#### 文件上传中间件
+
+文件上传功能通过 `inject_attachment_context` 中间件实现（位于 `src/agents/common/middlewares/attachment_middleware.py`）。该中间件基于 LangChain 1.0 的 `AgentMiddleware` 标准实现，具有以下特点：
+
+1. **状态扩展**：定义 `AttachmentState` 扩展 `AgentState`，添加可选的 `attachments` 字段
+2. **自动注入**：在模型调用前，从 `request.state` 中读取附件并转换为 `SystemMessage`
+3. **向后兼容**：不使用文件上传的智能体不受影响
+
+##### 为智能体启用文件上传
+
+只需两步：
+
+**步骤 1：声明能力**（让前端显示上传按钮）
+
+```python
+class MyAgent(BaseAgent):
+    capabilities = ["file_upload"]
+```
+
+**步骤 2：添加中间件**（让智能体能够处理附件内容）
+
+```python
+from src.agents.common.middlewares import inject_attachment_context
+
+async def get_graph(self):
+    graph = create_agent(
+        model=load_chat_model("..."),
+        tools=get_tools(),
+        middleware=[
+            inject_attachment_context,  # 添加附件中间件
+            context_aware_prompt,       # 其他中间件...
+            # ...
+        ],
+        checkpointer=await self._get_checkpointer(),
+    )
+    return graph
+```
+
+##### 工作流程
+
+1. **前端上传**：用户在聊天界面上传文档（txt、md、docx、html）
+2. **API 解析**：后端将文档转换为 Markdown 格式并存储到数据库（超过 32k 会被截断）
+3. **自动加载**：API 层在调用 agent 前从数据库加载附件数据
+4. **中间件注入**：`inject_attachment_context` 自动将附件内容注入为系统消息
+5. **模型处理**：LLM 接收到附件内容和用户问题，进行综合回答
+
+这种设计确保了附件功能的可选性和可扩展性，任何智能体都可以通过添加中间件快速启用文件上传能力。
+
+## 内置工具与 MCP 集成
+
+系统会根据配置自动组装工具集合，涵盖知识图谱查询、向量检索生成的动态工具、MySQL 只读查询能力、Tavily 搜索以及所有注册的 MCP 工具。
+
+工具的启用状态和描述由配置文件或环境变量决定，当依赖缺失时会被中间件自动忽略，从而避免在图中加载不可用能力。MCP Server 的接入方式保持不变，只需在 `src/agents/common/mcp.py` 的 `MCP_SERVERS` 中填入服务地址与 `transport` 类型，如需更多范式可参阅 LangChain 官方文档。
+
+### MySQL 数据库
+
+设置数据库连接时，在 `.env` 中提供以下字段：
+
+```env
+MYSQL_HOST=192.168.1.100
+MYSQL_USER=username
+MYSQL_PASSWORD=your_secure_password
+MYSQL_DATABASE=database_name
+MYSQL_DATABASE_DESCRIPTION=业务主库（可选提示）
+MYSQL_PORT=3306
+MYSQL_CHARSET=utf8mb4
+```
+
+所有查询限定在只读范围（SELECT、SHOW、DESCRIBE、EXPLAIN），请求会经过表名校验与超时控制，默认限制 60 秒与 100 行输出，并可通过配置调整上限。连接信息会反馈给 LangGraph，智能体可以自动陈述数据库用途并选择更准确的检索策略。
--- a/docs/v0.3.0/advanced/branding.md
+++ b/docs/v0.3.0/advanced/branding.md
@ -0,0 +1,49 @@
+# 品牌自定义
+
+系统支持完整的品牌信息自定义，包括 Logo、组织名称、版权信息等。
+
+## 配置方法
+
+### 1. 复制模板文件
+
+```bash
+cp src/config/static/info.template.yaml src/config/static/info.local.yaml
+```
+
+### 2. 编辑品牌信息
+
+在 `src/config/static/info.local.yaml` 中配置：
+
+<<< @/../src/config/static/info.template.yaml
+
+### 3. 环境变量配置
+
+在 `.env` 文件中指定配置文件路径：
+
+```bash
+YUXI_BRAND_FILE_PATH=src/config/static/info.local.yaml
+```
+
+::: tip 配置优先级
+`info.local.yaml` > `info.template.yaml`（默认）
+:::
+
+
+## 样式定制
+
+系统配色主要保存在 `web/src/assets/css/base.css` 中：
+
+- 替换 `--main-*` 相关变量即可改变配色
+- 支持主题色、辅助色等完整定制
+- 实时预览，无需重启服务
+
+**主要变量**:
+
+```css
+:root {
+  --main-color: #1890ff;        /* 主色调 */
+  --main-bg: #f0f2f5;          /* 背景色 */
+  --main-text: #262626;        /* 文字色 */
+  --main-border: #d9d9d9;      /* 边框色 */
+}
+```
--- a/docs/v0.3.0/advanced/configuration.md
+++ b/docs/v0.3.0/advanced/configuration.md
@ -0,0 +1,185 @@
+# 配置系统详解
+
+## 概述
+
+Yuxi-Know 从 v0.3.x 版本开始采用了全新的配置系统，基于 Pydantic BaseModel 和 TOML 格式，提供了类型安全、智能提示和选择性持久化等现代化特性。
+
+## 架构设计
+
+### 配置层次结构
+
+```
+配置系统架构
+├── 默认配置 (代码定义)
+│   ├── src/config/static/models.py (模型配置)
+│   └── src/config/app.py (应用配置)
+├── 用户配置 (TOML 文件)
+│   └── saves/config/base.toml (仅保存用户修改)
+└── 环境变量 (运行时覆盖)
+    └── .env 文件
+```
+
+### 核心组件
+
+#### 1. Config 类 (`src/config/app.py`)
+
+主配置类，继承自 Pydantic BaseModel，提供：
+
+- **类型验证**: 自动检查配置项类型
+- **默认值管理**: 内置合理的默认配置
+- **选择性持久化**: 仅保存用户修改的配置项
+- **向后兼容**: 支持旧的字典式访问方式
+
+```python
+class Config(BaseModel):
+    # 功能开关
+    enable_reranker: bool = Field(default=False, description="是否开启重排序")
+    enable_content_guard: bool = Field(default=False, description="是否启用内容审查")
+
+    # 模型配置
+    default_model: str = Field(default="siliconflow/deepseek-ai/DeepSeek-V3.2-Exp")
+    embed_model: str = Field(default="siliconflow/BAAI/bge-m3")
+
+    # 运行时状态 (不持久化)
+    model_provider_status: dict[str, bool] = Field(exclude=True)
+```
+
+#### 2. 模型配置类 (`src/config/static/models.py`)
+
+定义了三种类型的模型配置：
+
+- **ChatModelProvider**: 聊天模型提供商
+- **EmbedModelInfo**: 嵌入模型信息
+- **RerankerInfo**: 重排序模型信息
+
+```python
+class ChatModelProvider(BaseModel):
+    name: str = Field(..., description="提供商显示名称")
+    url: str = Field(..., description="提供商文档或模型列表 URL")
+    base_url: str = Field(..., description="API 基础 URL")
+    default: str = Field(..., description="默认模型名称")
+    env: str = Field(..., description="API Key 环境变量名")
+    models: list[str] = Field(default_factory=list, description="支持的模型列表")
+```
+
+添加配置：
+
+
+```python
+# 1. 在 DEFAULT_CHAT_MODEL_PROVIDERS 中添加
+"new-provider": ChatModelProvider(
+    name="新提供商",
+    url="https://provider.com/docs",
+    base_url="https://api.provider.com/v1",
+    default="default-model",
+    env="NEW_PROVIDER_API_KEY",
+    models=["model1", "model2"],
+),
+
+# 2. 在 .env 中配置 API Key
+# NEW_PROVIDER_API_KEY=your_api_key
+
+# 3. 重启服务或重新加载配置
+```
+
+## 配置管理特性
+
+系统只会保存用户修改过的配置项：
+
+```python
+# 用户只修改了 enable_reranker
+config.enable_reranker = True
+config.save()  # 只保存 enable_reranker 到 TOML 文件
+
+# TOML 文件内容
+# enable_reranker = true
+```
+
+### 默认模型配置 (`src/config/static/models.py`)
+
+包含所有支持的模型提供商的默认配置，开发者可以直接修改此文件添加新的模型：
+
+```python
+DEFAULT_CHAT_MODEL_PROVIDERS: dict[str, ChatModelProvider] = {
+    "siliconflow": ChatModelProvider(
+        name="SiliconFlow",
+        url="https://cloud.siliconflow.cn/models",
+        base_url="https://api.siliconflow.cn/v1",
+        default="deepseek-ai/DeepSeek-V3.2-Exp",
+        env="SILICONFLOW_API_KEY",
+        models=[
+            "deepseek-ai/DeepSeek-V3.2-Exp",
+            "Qwen/Qwen3-235B-A22B-Instruct-2507",
+            # ...
+        ],
+    ),
+    # 更多提供商...
+}
+```
+
+### 用户配置 (`saves/config/base.toml`)
+
+只包含用户修改过的配置项，使用 TOML 格式：
+
+```toml
+# 用户只修改了这些配置项
+enable_reranker = true
+default_agent_id = "MyCustomAgent"
+enable_content_guard = true
+
+# 模型配置修改
+[model_names.siliconflow]
+models = [
+    "deepseek-ai/DeepSeek-V3.2-Exp",
+    "custom-model-name",
+]
+```
+
+## 高级配置
+
+### 动态配置更新
+
+```python
+from src.config import config
+
+# 更新配置
+config.enable_reranker = True
+config.default_agent_id = "CustomAgent"
+
+# 更新模型列表
+config.model_names["siliconflow"].models.append("new-model")
+
+# 保存配置
+config.save()
+
+# 或者只保存特定提供商的模型配置
+config._save_models_to_file("siliconflow")
+```
+
+### 配置验证
+
+```python
+# 验证配置
+from src.config import config
+
+# 检查模型提供商可用性
+for provider, status in config.model_provider_status.items():
+    print(f"{provider}: {'✅' if status else '❌'}")
+
+# 获取可用模型列表
+available_models = config.get_model_choices()
+available_embed_models = config.get_embed_model_choices()
+available_rerankers = config.get_reranker_choices()
+```
+
+### 配置导出
+
+```python
+# 导出完整配置（包含运行时状态）
+full_config = config.dump_config()
+
+# 导出用户配置（仅保存到文件的部分）
+user_config = {
+    field: getattr(config, field)
+    for field in config._user_modified_fields
+}
--- a/docs/v0.3.0/advanced/document-processing.md
+++ b/docs/v0.3.0/advanced/document-processing.md
@ -0,0 +1,152 @@
+# 文档处理与 OCR
+
+系统提供 4 种文档处理选项：
+
+- **RapidOCR**: CPU 友好，无需 GPU，适合基础文字识别
+- **MinerU**: 本地化高精度 VLM 解析，适合复杂 PDF 和表格文档
+- **MinerU Official**: 官方云服务 API，无需本地部署，开箱即用
+- **PaddleX**: 结构化解析，适合表格、票据等特殊格式
+
+## 快速配置
+
+### 1. 基础 OCR (RapidOCR)
+
+```bash
+# 下载模型
+hf download SWHL/RapidOCR --local-dir ./models/SWHL/RapidOCR
+
+# 启动服务
+docker compose up -d api
+```
+
+### 2. 高精度 OCR (MinerU)
+
+需要配置：
+
+```bash
+MINERU_VL_SERVER=http://localhost:30000
+MINERU_API_URI=http://localhost:30001
+```
+
+然后启动相关服务
+
+```bash
+# 需要 GPU，启动 MinerU 服务
+docker compose up -d mineru-vllm-server mineru-api
+
+# 启动主服务
+docker compose up -d api
+```
+
+### 3. 官方云服务 (MinerU Official)
+
+
+API 密钥可以从 [MinerU 官网](https://mineru.net) 申请。
+
+```bash
+# 设置 API 密钥环境变量
+export MINERU_API_KEY="your-api-key-here"
+
+# 启动主服务
+docker compose up -d api
+```
+
+### 4. 结构化解析 (PaddleX)
+
+```bash
+# 需要 GPU，启动 PaddleX 服务
+docker compose up -d paddlex
+
+# 启动主服务
+docker compose up -d api
+```
+
+## 处理器选择
+
+| 处理器 | 适用场景 | 硬件要求 | 特点 |
+|--------|----------|------------|------|
+| **RapidOCR** | 基础文字识别 | CPU | 速度快，资源占用低 |
+| **MinerU** | 复杂 PDF、表格、公式 | GPU | 精度高，版面分析好 |
+| **MinerU Official** | 复杂文档解析（云服务） | 无特殊要求 | 官方云服务，开箱即用，有 API 配额 |
+| **PaddleX** | 表格、票据、结构化文档 | GPU | 专业版面解析 |
+
+## 参数说明
+
+### enable_ocr 选项
+- `disable`: 不启用 OCR（PDF 按文本提取，图片**必须选择 OCR 方式**）
+- `onnx_rapid_ocr`: RapidOCR 处理
+- `mineru_ocr`: MinerU HTTP API 处理
+- `mineru_official`: MinerU 官方云服务 API 处理
+- `paddlex_ocr`: PaddleX 处理
+
+### 注意事项
+- **图片文件必须启用 OCR**，否则无法提取内容
+- MinerU 和 PaddleX 需要 GPU 支持
+- MinerU Official 需要设置 `MINERU_API_KEY` 环境变量
+- RapidOCR 适合 CPU 环境和基础识别需求
+
+## 故障排除
+
+### 常见问题
+
+1. **RapidOCR 模型不存在**
+   ```bash
+   # 下载模型
+   huggingface-cli download SWHL/RapidOCR --local-dir ./models/SWHL/RapidOCR
+   ```
+
+2. **GPU 服务连接失败**
+   ```bash
+   # 检查服务状态
+   docker compose ps
+
+   # 查看日志
+   docker compose logs mineru
+   ```
+
+3. **健康检查**
+   ```bash
+   # 检查所有 OCR 服务状态
+   curl http://localhost:5050/system/health/ocr-services
+   ```
+
+## 批量处理脚本
+
+系统提供便捷的批量处理脚本，用于高效批量上传文档。
+
+### 文件上传脚本
+
+使用 `scripts/batch_upload.py` 批量上传文件到知识库：
+
+```bash
+# 批量上传文档（多种格式）
+uv run scripts/batch_upload.py \
+    --db-id kb_b2730ad6801b149694021106c7eddd38 \
+    --directory data.nogit/农业农村局 \
+    --pattern "*.docx" --pattern "*.txt" --pattern "*.html" \
+    --base-url http://172.19.13.6:5050/api \
+    --username admin \
+    --password admin123 \
+    --batch-size 20 \
+    --wait-for-completion \
+    --poll-interval 5 \
+    --recursive \
+    --enable-ocr mineru_ocr \ # mineru_official, paddlex_ocr, onnx_rapid_ocr
+    --record-file scripts/tmp/batch_processed_files_1029.txt
+```
+
+**参数说明**:
+- `--db-id`: 目标知识库 ID
+- `--directory`: 文件目录路径
+- `--pattern`: 文件匹配模式，可以多次指定以支持多种格式（例如：`--pattern "*.docx" --pattern "*.pdf" --pattern "*.html"`）
+- `--batch-size`: 每批处理的文件数量（默认20）
+- `--wait-for-completion`: 是否等待任务完成再处理下一批（默认开启）
+- `--poll-interval`: 任务状态检查间隔，单位秒（默认5秒）
+- `--recursive`: 递归处理子目录
+- `--record-file`: 处理记录文件路径
+
+**注意事项**:
+- 系统按"内容哈希"进行去重；同一知识库已存在相同内容的文件会被拒绝（409）
+- 建议根据系统性能调整批次大小
+- 大量文件处理时建议开启分批等待功能
+- 先上传后处理的机制更稳定，适合大批量文档导入
--- a/docs/v0.3.0/advanced/misc.md
+++ b/docs/v0.3.0/advanced/misc.md
@ -0,0 +1,53 @@
+# 其他配置
+
+## 内容安全
+
+系统内置内容审查机制（默认是关闭状态），保障服务内容的合规性。目前配置了关键词过滤以及 LLM 对内容进行审查。管理员可在 `设置` → `基本设置` 页面中进行配置并选择安全模型。
+
+检测流程为，接收到用户输入之后，就对用户的输入进行检测是否合规，同时在流式传输的过程中进行实时检测（仅关键词）。当流式输出结束之后，则开始检测整个内容。
+**注意**，使用 LLM 检测虽然可以大大缓解提示词注入带来的问题，但也会在用户交互上带来延迟影响，需要考虑是否启用。
+
+对于关键词检测，敏感词词库位于 `src/config/static/bad_keywords.txt` 文件，每行一个关键词，实时生效，无需重启服务。
+
+对于 LLM 检测，Prompt 可以看到 `src/plugins/guard.py`：
+
+<<< @/../src/plugins/guard.py#guard_prompt
+
+## 网页搜索
+
+系统内置了基于 Tavily 的联网搜索能力，配置完成后，大模型会自动在需要时调用 `enable_web_search` 对应的工具，为回答提供实时网页信息。
+
+
+1. 前往 [Tavily 官网](https://app.tavily.com/) 注册并在控制台创建 API Key。
+2. 在项目根目录的 `.env`（或 `docker-compose.yml` 中的对应环境变量段）写入：
+   ```env
+   TAVILY_API_KEY=sk-xxxxxxxxxxxxxxxx
+   ```
+3. 重新加载服务使密钥生效，推荐执行：
+   ```bash
+   docker compose up -d api-dev web-dev
+   ```
+   若服务已运行，则使用 `docker compose restart api-dev` 即可。
+
+完成以上步骤后，后端会自动将 `enable_web_search` 标记为启用，在智能体的工具配置区域即可看到这个工具，展示 Tavily 返回的实时结果。若需要关闭该能力，删除或清空 `TAVILY_API_KEY` 后再次重启服务即可。
+
+## 服务端口
+
+系统使用多个端口提供不同服务，以下是完整的端口映射：
+
+| 端口 | 服务 | 容器名称 | 说明 |
+|------|------|----------|------|
+| **5173** | Web 前端 | web-dev | 用户界面 |
+| **5050** | API 后端 | api-dev | 核心服务 |
+| **7474/7687** | Neo4j | graph | 图数据库 |
+| **9000/9001** | MinIO | milvus-minio | 对象存储 |
+| **19530/9091** | Milvus | milvus | 向量数据库 |
+| **30000** | MinerU | mineru | PDF 解析（可选）|
+| **8080** | PaddleX | paddlex-ocr | OCR 服务（可选）|
+| **8081** | vLLM | - | 本地推理（可选）|
+
+::: tip 端口访问
+- Web 界面: `http://localhost:5173`
+- API 文档: `http://localhost:5050/docs`
+- Neo4j 管理: `http://localhost:7474`
+:::
--- a/docs/v0.3.0/changelog/0.3-release-notes.md
+++ b/docs/v0.3.0/changelog/0.3-release-notes.md
@ -0,0 +1,106 @@
+# Yuxi-Know v0.3 更新说明
+
+## 概览
+
+Yuxi-Know v0.3 是一个重要的里程碑版本，包含了多项架构重构、功能增强和用户体验改进。本版本重点关注了系统架构的优化、数据存储的统一管理以及用户界面的现代化改进。
+
+## 🔄 重大变更 (Breaking Changes)
+
+### 环境配置文件位置调整
+- **变更内容**: 将 `.env` 文件从 `src/.env` 移动到项目根目录 `.env`
+- **影响**: 需要更新配置文件的复制命令和所有相关的文档引用
+- **迁移指南**:
+  ```bash
+  # 旧版本
+  cp src/.env.template src/.env
+
+  # 新版本
+  cp .env.template .env
+  ```
+
+### 配置文件管理调整
+
+配置系统从 YAML 格式迁移到了基于 Pydantic BaseModel + TOML 的现代化配置系统。
+
+| 项目 | v0.2.x | v0.3.x |
+|------|--------|--------|
+| 默认模型配置 | `src/config/static/models.yaml` | `src/config/static/models.py` |
+| 用户配置 | `saves/config/base.yaml` | `saves/config/base.toml` |
+| 配置格式 | YAML | Python 代码 + TOML |
+| 类型安全 | ❌ 无 | ✅ Pydantic 验证 |
+| IDE 支持 | ❌ 基础 | ✅ 完整智能提示 |
+| 持久化策略 | 全量保存 | 选择性保存 |
+
+
+示例：迁移自定义模型提供商
+
+假设你的旧 `models.yaml` 中有：
+
+```yaml
+# 旧的 models.yaml
+MODEL_NAMES:
+  custom-provider:
+    name: "My Custom Provider"
+    base_url: "https://api.custom.com/v1"
+    default: "custom-model"
+    env: "CUSTOM_API_KEY"
+    models:
+      - "custom-model"
+      - "another-model"
+```
+
+需要在新的 `src/config/static/models.py` 中添加：
+
+```python
+# 新的 models.py
+DEFAULT_CHAT_MODEL_PROVIDERS: dict[str, ChatModelProvider] = {
+    # ... 现有配置 ...
+
+    "custom-provider": ChatModelProvider(
+        name="My Custom Provider",
+        url="https://custom.com/docs",
+        base_url="https://api.custom.com/v1",
+        default="custom-model",
+        env="CUSTOM_API_KEY",
+        models=["custom-model", "another-model"],
+    ),
+}
+```
+
+
+### 数据库存储架构重构
+- **变更内容**: 重新实现了对话管理的存储与管理，不再依赖于 MemorySaver
+- **影响**: 使用新的存储结构，之前存储的历史记录无法直接迁移
+- **改进**: 所有对话记录统一保存到 `server.db` 中，提供更好的数据一致性和查询性能
+
+### 自定义模型支持移除
+- **变更内容**: 完全移除自定义模型支持功能
+- **替代方案**: 使用自定义 provider
+
+## ✨ 新增功能
+
+### 1. Dashboard 统计面板
+- **用户活跃度统计**: 提供用户使用情况的详细分析
+- **工具调用统计**: 实时监控各种工具的使用频率和效果
+- **知识库分析**: 展示知识库的使用情况和性能指标
+- **智能体分析**: 统计智能体的调用次数和成功率
+- **时间序列数据**: 支持历史趋势分析和可视化展示
+
+### 2. 消息反馈系统
+- **点赞点踩功能**: 用户可以对 AI 回复进行质量评价
+- **反馈数据收集**: 为模型优化提供有价值的数据支持
+- **管理员视图**: 管理员可以查看整体的反馈统计情况
+
+### 3. 用户资料增强
+- **用户名更新**: 支持用户修改显示名称
+- **头像管理**: 完善用户头像上传和管理功能
+- **账户安全**: 增强账户登录失败次数限制和锁定机制
+
+### 4. 文档系统
+- **VitePress 集成**: 添加完整的官方文档站点
+- **快速开始指南**: 优化新用户的上手体验
+- **配置文档**: 详细的环境配置和功能说明
+- **GitHub Actions**: 实现文档的自动部署
+
+
+**注意**: v0.3 版本包含多项重大变更，建议在升级前仔细阅读本文档并做好数据备份。如有问题，请通过 GitHub Issues 反馈。
--- a/docs/v0.3.0/changelog/contributing.md
+++ b/docs/v0.3.0/changelog/contributing.md
@ -0,0 +1,125 @@
+# 参与贡献
+
+感谢所有贡献者的支持！
+
+<a href="https://github.com/xerrors/Yuxi-Know/contributors">
+    <img src="https://contributors.nn.ci/api?repo=xerrors/Yuxi-Know" alt="贡献者名单">
+</a>
+
+## 如何贡献
+
+### 1. Fork 项目
+
+在 GitHub 上 Fork 本项目到你的账户。
+
+### 2. 创建分支
+
+```bash
+git checkout -b feature/amazing-feature
+```
+
+### 3. 提交更改
+
+```bash
+git commit -m 'feat: Add some amazing feature'
+```
+
+### 4. 推送分支
+
+```bash
+git push origin feature/amazing-feature
+```
+
+### 5. 创建 PR
+
+在 GitHub 上创建 Pull Request，详细描述你的更改内容。
+
+## 开发指南
+
+### 代码规范
+
+- 遵循项目代码规范
+- Python 代码使用 `make format` 格式化
+- 使用 `make lint` 检查代码质量
+- 添加必要的测试用例
+- 更新相关文档
+
+### 提交规范
+
+使用清晰的提交信息：
+
+```
+feat: 添加新功能
+fix: 修复 bug
+docs: 更新文档
+style: 代码格式调整
+refactor: 代码重构
+test: 添加测试
+chore: 构建过程或辅助工具的变动
+```
+
+
+## 🐞 Bug 修复发布流程
+
+如果在发布 `v0.3.0` 后发现 bug：
+
+### ✅ 情况 1：main 上没有未完成的新功能
+
+直接在 main 修复并发布：
+
+```bash
+git commit -m "fix: resolve config parser crash"
+git tag -a v0.3.1 -m "Hotfix v0.3.1"
+git push origin main --tags
+```
+
+### ⚙️ 情况 2：main 上已有新功能未完成
+
+从上一个 tag 建立 hotfix 分支：
+
+```bash
+git checkout -b hotfix/0.3.1 v0.3.0
+# 修复问题
+git commit -m "fix: resolve config parser crash"
+git push origin hotfix/0.3.1
+
+# 测试后合并回 main 并打 tag
+git checkout main
+git merge --no-ff hotfix/0.3.1
+git tag -a v0.3.1 -m "Hotfix v0.3.1"
+git push origin main --tags
+
+# 删除临时分支
+git branch -d hotfix/0.3.1
+git push origin --delete hotfix/0.3.1
+```
+
+
+### 测试要求
+
+::: tip 测试
+- `make lint` / `make format` 保持代码整洁
+- `cp test/.env.test.example test/.env.test` 配置测试凭据
+- `make router-tests` 运行集成路由测试，支持 `PYTEST_ARGS="-k chat_router"`
+- `uv run --group test pytest test/api` 可直接运行 pytest（容器内）
+:::
+
+<details>
+<summary>常用命令</summary>
+
+```bash
+# 全量路由测试
+make router-tests
+
+# 仅运行知识库相关用例
+make router-tests PYTEST_ARGS="-k knowledge_router"
+
+# 不经过 Makefile，直接调用 pytest
+uv run --group test pytest test/api -vv
+```
+
+</details>
+
+## 许可证
+
+本项目基于 MIT License 开源，贡献的代码将遵循相同的许可证。
--- a/docs/v0.3.0/changelog/faq.md
+++ b/docs/v0.3.0/changelog/faq.md
@ -0,0 +1,41 @@
+# 常见问题
+
+以下为最常见的安装与使用问题，更多细节请参阅相应章节链接。
+
+- 首次运行如何创建管理员？
+  - Web 首次启动会引导初始化；也可调用 API：
+    - `GET /api/auth/check-first-run` → `first_run=true` 时
+    - `POST /api/auth/initialize` 提交 `user_id` 与 `password`
+  - 无默认账号，初始化后使用创建的超级管理员登录
+
+- 镜像拉取/构建失败？
+  - 可使用 `docker/pull_image.sh` 辅助拉取，或配置代理环境变量 `HTTP_PROXY/HTTPS_PROXY`
+  - 若已配置代理仍失败，可临时取消代理后重试
+  - 参考：介绍 → 快速开始 → 故障排除
+
+- 服务端口与访问地址？
+  - Web: `http://localhost:5173`；API 文档: `http://localhost:5050/docs`
+  - 端口一览与说明见：高级配置 → 其他配置 → 服务端口
+
+- Milvus/Neo4j 启动或连接失败？
+  - 重启：`docker compose up milvus -d && docker restart api-dev`
+  - Neo4j 默认：用户名 `neo4j`、密码 `0123456789`、管理界面 `http://localhost:7474`
+
+- OCR 模型或服务不可用？
+  - RapidOCR 本地模型：确保 `MODEL_DIR/SWHL/RapidOCR` 下存在 `PP-OCRv4` 模型
+  - MinerU/PaddleX：检查健康检查接口与 GPU/CUDA 版本
+  - 参考：高级配置 → 文档解析
+
+- 支持的文件类型与常见入库失败？
+  - 查询：`GET /api/knowledge/files/supported-types`
+  - 常见失败：不支持的扩展名、内容哈希重复（去重）、OCR 服务未就绪
+
+- 批量上传与转换示例？
+  - 上传入库：`uv run scripts/batch_upload.py upload --db-id <id> --directory <dir> --username <u> --password <p> --base-url http://127.0.0.1:5050/api`
+  - 参考：高级配置 → 文档解析
+
+- 登录失败被锁定？
+  - 多次失败会临时锁定账户，请根据提示等待后重试
+
+- 如何查看日志和状态？
+  - `docker ps` 查看整体；`docker logs api-dev -f`、`docker logs web-dev -f` 查看服务日志
--- a/docs/v0.3.0/intro/knowledge-base.md
+++ b/docs/v0.3.0/intro/knowledge-base.md
@ -0,0 +1,137 @@
+# 知识库与知识图谱
+
+项目中的知识库与知识图谱，即是知识管理组织的方式，同时会被封装为工具供 AgenticRAG 系统调用。
+
+## 创建知识库
+
+系统支持多种知识库存储形式，满足不同场景需求：
+
+| 存储类型 | 特点 | 适用场景 |
+|----------|------|----------|
+| **Chroma** | 轻量级向量数据库 | 小型项目、快速原型、维护方便 |
+| **Milvus** | 高性能向量数据库 | 大规模生产环境、高性能查询 |
+| **LightRAG** | 图增强检索 | 复杂知识关系，构建成本较高 |
+
+访问 Web 界面：`http://localhost:5173`，进入"知识库管理"页面，点击"新建知识库"，填写知识库信息。
+
+这里需要**注意**的是，这里的知识库的标题和描述都会作为智能体选择工具的依据，因此尽量详尽的描述该知识库。
+
+
+### LightRAG 知识库说明
+
+在本项目中，系统支持基于 [LightRAG](https://github.com/HKUDS/LightRAG) 的知识图谱自动构建，能够从文档中自动提取实体和关系，构建结构化知识图谱。但是 LightRAG 所构建的知识图谱不作为全局的知识图谱来使用。只是将 LightRAG 作为知识的组织和检索形式。一方面是因为 LightRAG 构建的图谱的质量比较差，另一方面是不希望与全局的知识图谱弄混。
+
+LightRAG 知识库可在知识库详情中可视化，但不支持在侧边栏图谱中直接检索，图谱检索工具不支持 LightRAG 知识库，查询需要使用对应的知识库作为工具。
+
+在 Neo4j 的检索中可以看到，实际上 LightRAG 的节点和边依然是和知识图谱本身构建在了同一个 Neo4j 数据库中，但是使用了特殊的 tag 做区分。这点在后面介绍知识图谱的时候也会额外说明。
+
+
+系统默认使用 `siliconflow` 的 `Qwen/Qwen3-30B-A3B-Instruct-2507` 模型进行图谱构建。可通过环境变量自定义图谱构建模型：
+
+<<< @/../.env.template#lightrag{bash}
+
+
+## 文档管理
+
+本系统的“上传 → 解析入库 → 检索/可视化”流程既可通过 Web 界面完成，也可使用 API/脚本批量处理。
+
+**支持的文件类型**
+
+- 文本与文档：`.txt`、`.md`、`.doc`、`.docx`、`.pdf`
+- 网页与数据：`.html`、`.htm`、`.json`、`.csv`、`.xls`、`.xlsx`
+- 图片：`.jpg`、`.jpeg`、`.png`、`.bmp`、`.tiff`、`.tif`
+
+接口查询：`GET /api/knowledge/files/supported-types`
+
+**上传与入库**
+
+1) 上传文件（返回服务端保存路径）
+- `POST /api/knowledge/files/upload?db_id=<可选>`
+- 成功返回：`file_path`（后续入库使用）、`content_hash`（内容去重）
+
+2) 解析并入库（异步任务）
+- `POST /api/knowledge/databases/{db_id}/documents`
+- 返回：`status=queued` 与 `task_id`，可在任务中心查看进度
+
+去重策略：系统按“内容哈希”判断是否已存在相同文件，避免重复入库。
+
+### 批量脚本
+
+- 上传并入库：参见 `scripts/batch_upload.py upload`
+
+## 知识图谱
+
+本项目存在两类“图谱相关”能力：
+
+- 全局知识图谱（Neo4j）：用于智能体工具 `query_knowledge_graph` 的图实体查询；统一保存在 Neo4j 中，提供三元组检索和系统级可视化。
+- LightRAG 知识库内图谱：针对某个知识库由 LightRAG 自动抽取实体/关系，用于该库内的图增强检索与可视化；与全局图共享同一 Neo4j 实例，但通过特殊 tag 区分，不作为全局图谱使用。
+
+选择建议：
+- 更结构化的库内检索/可视化：优先使用 LightRAG（注意构建质量与成本）。
+- 统一的图查询/工具调用：依赖全局 Neo4j 图谱与工具 `query_knowledge_graph`。
+
+因此，侧边栏知识图谱页面展示的是 Neo4j 图数据库中符合以下规则的知识图谱信息。
+
+具体展示内容包括：
+
+- 带有 Entity 标签的节点
+- 带有 RELATION 类型的关系边
+
+注意：
+
+这里仅展示用户上传的实体和关系，不包含知识库中自动创建的图谱。
+查询逻辑基于 `graphbase.py` 中的 `get_sample_nodes` 方法实现：
+
+```SQL
+MATCH (n:Entity)-[r]->(m:Entity)
+RETURN
+    {id: elementId(n), name: n.name} AS h,
+    {type: r.type, source_id: elementId(n), target_id: elementId(m)} AS r,
+    {id: elementId(m), name: m.name} AS t
+LIMIT $num
+```
+
+如需查看完整的 Neo4j 数据库内容，请使用 "Neo4j 浏览器" 按钮访问 Neo4j 原生界面。
+
+通过网页上传的 `jsonl` 文件的图谱默认会符合上述条件。
+
+
+
+### 1. 以三元组形式导入
+
+
+系统支持通过网页导入 `jsonl` 格式的知识图谱数据：
+
+```jsonl
+{"h": "北京", "t": "中国", "r": "首都"}
+{"h": "上海", "t": "中国", "r": "直辖市"}
+{"h": "深圳", "t": "广东", "r": "省会"}
+```
+
+**格式说明**，每行一个三元组，系统自动验证数据格式，并自动导入到 Neo4j 数据库，添加 `Upload`、`Entity`、`Relation` 标签，会自动处理重复的三元组。
+
+Neo4j 访问信息可以参考 `docker-compose.yml` 中配置对应的环境变量来覆盖。
+
+- **默认账户**: `neo4j`
+- **默认密码**: `0123456789`
+- **管理界面**: `http://localhost:7474`
+- **连接地址**: bolt://localhost:7687
+
+::: tip 测试数据
+可以使用 `test/data/A_Dream_of_Red_Mansions_tiny.jsonl` 文件进行测试导入。
+:::
+
+### 2. 接入已有 Neo4j 实例
+
+如需接入已有的 Neo4j 实例，可修改 `.env` 中的配置：
+
+<<< @/../.env.template#neo4j{bash}
+
+同时记得注释掉下面的 neo4j 服务：
+
+<<< @/../docker-compose.yml#neo4j
+
+
+::: warning 注意事项
+确保每个节点都有 `Entity` 标签，每个关系都有 `RELATION` 类型，否则会影响图的检索与构建功能。
+:::
--- a/docs/v0.3.0/intro/model-config.md
+++ b/docs/v0.3.0/intro/model-config.md
@ -0,0 +1,198 @@
+# 模型配置
+
+## 对话模型
+
+系统支持多种大语言模型服务商，通过配置对应的 API 密钥即可使用：
+
+| 服务商 | 环境变量 | 特点 |
+|--------|----------|------|
+| [硅基流动](https://cloud.siliconflow.cn/i/Eo5yTHGJ) | `SILICONFLOW_API_KEY` | 🆓 免费额度，默认推荐 |
+| OpenAI | `OPENAI_API_KEY` | GPT 系列模型 |
+| DeepSeek | `DEEPSEEK_API_KEY` | 国产大模型 |
+| OpenRouter | `OPENROUTER_API_KEY` | 多模型聚合平台 |
+| 智谱清言 | `ZHIPUAI_API_KEY` | GLM 系列模型 |
+| 阿里云百炼 | `DASHSCOPE_API_KEY` | 通义千问系列 |
+
+其余还支持火山、Together、vLLM、Ollama 等。
+
+### 配置方法
+
+在 `.env` 文件中添加对应的环境变量：
+
+<<< @/../.env.template#model_provider{bash 2}
+
+### 默认对话模型格式
+
+系统的默认对话模型通过配置项 `default_model` 指定，格式统一为 `模型提供商/模型名称`，例如：
+
+```yaml
+default_model: siliconflow/deepseek-ai/DeepSeek-V3.2-Exp
+```
+
+在 Web 界面中选择模型时也会自动按照这一格式保存，无需手动拆分提供商和模型名称。
+
+
+::: tip 免费获取 API Key
+[硅基流动](https://cloud.siliconflow.cn/i/Eo5yTHGJ) 注册即送 14 元额度，支持多种开源模型。
+:::
+
+## 自定义模型供应商
+
+::: warning
+原本网页中的自定义模型已在 `0.3.x` 版本移除，请在 `src/config/static/models.py` 中按如下方式配置，并重启服务后选择并使用。此外，这里也推荐一下团队的另外一个小工具 [mvllm (Manage and Route vLLM Servers)](https://github.com/xerrors/mvllm)。
+:::
+
+::: tip 配置系统升级 (v0.3.x)
+从 `v0.3.x` 版本开始，模型配置系统已升级为基于 Pydantic BaseModel 的类型安全配置，支持 TOML 格式的用户配置文件。
+- **默认配置**: `src/config/static/models.py` (Python 代码)
+- **用户配置**: `saves/config/base.toml` (TOML 格式，仅保存用户修改)
+:::
+
+系统理论上兼容任何 OpenAI 兼容的模型服务，包括：
+
+- **vLLM**: 高性能推理服务
+- **Ollama**: 本地模型管理
+- **API 中转服务**: 各种代理和聚合服务
+
+如需添加新的模型供应商，请按以下步骤操作：
+
+### 1. 编辑模型配置文件
+
+**方式一：修改默认配置（推荐）**
+编辑 `src/config/static/models.py` 文件中的 `DEFAULT_CHAT_MODEL_PROVIDERS` 字典
+
+在 `src/config/static/models.py` 中添加新的模型供应商：
+
+```python
+DEFAULT_CHAT_MODEL_PROVIDERS: dict[str, ChatModelProvider] = {
+    # ... 现有配置 ...
+
+    "custom-provider": ChatModelProvider(
+        name="自定义提供商",
+        url="https://your-provider.com/docs",
+        base_url="https://api.your-provider.com/v1",
+        default="custom-model-name",
+        env="CUSTOM_API_KEY_ENV_NAME",
+        models=[
+            "supported-model-name",
+            "another-model-name",
+        ],
+    ),
+
+    # 本地 Ollama 服务
+    "local-ollama": ChatModelProvider(
+        name="Local Ollama",
+        url="https://ollama.com",
+        base_url="http://localhost:11434/v1",
+        default="llama3.2",
+        env="NO_API_KEY",  # 对于不需要API Key的服务，使用NO_API_KEY
+        models=["llama3.2", "qwen2.5"],
+    ),
+
+    # 本地 vLLM 服务
+    "local-vllm": ChatModelProvider(
+        name="Local vLLM",
+        url="https://docs.vllm.ai",
+        base_url="http://localhost:8000/v1",
+        default="Qwen/Qwen2.5-7B-Instruct",
+        env="NO_API_KEY",
+        models=[
+            "Qwen/Qwen2.5-7B-Instruct",
+            "Qwen/Qwen2.5-14B-Instruct",
+        ],
+    ),
+}
+```
+
+### 3. 配置环境变量
+
+在 `.env` 文件中添加对应的环境变量：
+```env
+CUSTOM_API_KEY_ENV_NAME=your_api_key_here
+```
+
+### 4. 重新部署
+
+```bash
+docker compose restart api-dev
+```
+
+## 嵌入模型和重排序模型
+
+::: warning 重要说明
+从 v0.2 版本开始，项目采用微服务架构，模型部署与项目本身完全解耦。如需使用本地模型，需要先通过 vLLM 或 Ollama 部署为 API 服务。
+:::
+
+### 本地模型部署
+
+#### 1. 配置模型信息
+
+在 `src/config/static/models.py` 中的默认配置部分添加：
+
+```python
+# 默认嵌入模型配置
+DEFAULT_EMBED_MODELS: dict[str, EmbedModelInfo] = {
+    # ... 现有配置 ...
+
+    "vllm/Qwen/Qwen3-Embedding-0.6B": EmbedModelInfo(
+        name="Qwen/Qwen3-Embedding-0.6B",
+        dimension=1024,
+        base_url="http://localhost:8000/v1/embeddings",
+        api_key="no_api_key",
+    ),
+}
+
+# 默认重排序模型配置
+DEFAULT_RERANKERS: dict[str, RerankerInfo] = {
+    # ... 现有配置 ...
+
+    "vllm/BAAI/bge-reranker-v2-m3": RerankerInfo(
+        name="BAAI/bge-reranker-v2-m3",
+        base_url="http://localhost:8000/v1/rerank",
+        api_key="no_api_key",
+    ),
+}
+```
+
+#### 2. 动态配置（可选）
+
+你也可以通过代码动态添加本地模型：
+
+```python
+from src.config import config
+from src.config.static.models import EmbedModelInfo, RerankerInfo
+
+# 添加本地嵌入模型
+config.embed_model_names["local/embed-model"] = EmbedModelInfo(
+    name="local-embed-model",
+    dimension=1024,
+    base_url="http://localhost:8000/v1/embeddings",
+    api_key="no_api_key",
+)
+
+# 添加本地重排序模型
+config.reranker_names["local/reranker-model"] = RerankerInfo(
+    name="local-reranker-model",
+    base_url="http://localhost:8000/v1/rerank",
+    api_key="no_api_key",
+)
+
+# 保存配置
+config.save()
+```
+
+#### 2. 启动模型服务
+
+```bash
+# 启动嵌入模型
+vllm serve Qwen/Qwen3-Embedding-0.6B \
+  --task embed \
+  --dtype auto \
+  --port 8000
+
+# 启动重排序模型
+vllm serve BAAI/bge-reranker-v2-m3 \
+  --task score \
+  --dtype fp16 \
+  --port 8000
+```
--- a/docs/v0.3.0/intro/project-overview.md
+++ b/docs/v0.3.0/intro/project-overview.md
@ -0,0 +1,37 @@
+# 项目简介
+
+Yuxi-Know（语析）是一个基于知识图谱和向量数据库的智能知识库系统，融合了 RAG（检索增强生成）技术与知识图谱技术，为用户提供智能问答和知识管理服务。
+
+特点是技术栈简单，易于上手，使用 MIT 开源协议，非常适合二次开发使用。
+
+### 技术栈选择
+
+- **后端服务**: [FastAPI](https://github.com/tiangolo/fastapi) + Python 3.12+
+- **前端界面**: [Vue.js 3](https://github.com/vuejs/vue) + [Ant Design Vue](https://github.com/vueComponent/ant-design-vue)
+- **数据库存储**: [SQLite](https://github.com/sqlite/sqlite) + [MinIO](https://github.com/minio/minio)
+- **知识存储**: [Milvus](https://github.com/milvus-io/milvus)、[Chroma](https://github.com/chroma-core/chroma)（向量数据库）+ [Neo4j](https://github.com/neo4j/neo4j)（图数据库）
+- **智能体框架**: [LangGraph](https://github.com/langchain-ai/langgraph)
+- **文档解析**: [LightRAG](https://github.com/HKUDS/LightRAG) + [MinerU](https://github.com/HKUDS/MinerU) + [PP-Structure-V3](https://github.com/PaddlePaddle/PaddleOCR)
+- **容器编排**: [Docker Compose](https://github.com/docker/compose)
+
+### 核心功能
+
+- **智能问答**: 支持多种大语言模型，提供智能对话和问答服务
+- **知识库管理**: 支持多种存储形式（Chroma、Milvus、LightRAG）
+- **知识图谱**: 自动构建和可视化知识图谱，支持图查询
+- **文档解析**: 支持 PDF、Word、图片等多种格式的智能解析
+- **权限管理**: 三级权限体系（超级管理员、管理员、普通用户）
+- **内容安全**: 内置内容审查机制，保障服务合规性
+
+## 演示视频
+
+<div align="center">
+  <a href="https://www.bilibili.com/video/BV1ETedzREgY/?share_source=copy_web&vd_source=37b0bdbf95b72ea38b2dc959cfadc4d8" target="_blank">
+    <img width="3651" height="1933" alt="视频演示缩略图" src="https://github.com/user-attachments/assets/eac4fa89-2176-46ae-a649-45a125cb6ed1" />
+  </a>
+  <p style="margin-top: 12px;">
+    <a href="https://www.bilibili.com/video/BV1ETedzREgY/?share_source=copy_web&vd_source=37b0bdbf95b72ea38b2dc959cfadc4d8" target="_blank" style="text-decoration: none; color: #23ade5; font-weight: 500;">
+      📽️ 点击查看视频演示 <i class="fa fa-external-link" style="margin-left: 4px;"></i>
+    </a>
+  </p>
+</div>
--- a/docs/v0.3.0/intro/quick-start.md
+++ b/docs/v0.3.0/intro/quick-start.md
@ -0,0 +1,135 @@
+# 快速开始指南
+
+::: tip 提示
+除了此文档网站外，小伙伴们还可以在 [Zread](https://zread.ai/xerrors/Yuxi-Know) 或 [DeepWiki](https://deepwiki.com/xerrors/Yuxi-Know) 平台查看自动生成的详细项目文档。
+:::
+
+
+## 快速开始
+
+
+### 安装步骤
+
+项目采用微服务架构，核心服务无需 GPU 支持。GPU 仅用于可选的 OCR 服务和本地模型推理，可通过环境变量配置外部服务。
+
+#### 1. 获取项目代码
+
+```bash
+# 克隆稳定版本
+git clone --branch v0.3.0 --depth 1 https://github.com/xerrors/Yuxi-Know.git
+cd Yuxi-Know
+```
+
+::: warning 版本说明
+- `v0.3.0`: 稳定版本
+- `v0.3.0`：最新的 Beta 测试版
+- `main`: 最新开发版本（不稳定，新特性可能会导致新 bug）
+:::
+
+#### 2. 配置环境变量
+
+复制环境变量模板并编辑：
+
+```bash
+cp .env.template .env
+```
+
+编辑 `.env` 文件，配置必需的 API 密钥：
+
+
+<<< @/../.env.template#model_provider{bash 2}
+
+
+::: tip 免费获取 API Key
+[硅基流动](https://cloud.siliconflow.cn/i/Eo5yTHGJ) 注册即送 14 元额度，支持多种开源模型。
+:::
+
+#### 3. 启动服务
+
+```bash
+# 构建并启动所有服务
+docker compose up --build
+
+# 后台运行（推荐）
+docker compose up --build -d
+```
+
+#### 4. 访问系统
+
+服务启动完成后，访问以下地址：
+
+- **Web 界面**: `http://localhost:5173`
+- **API 文档**: `http://localhost:5050/docs`
+
+#### 5. 停止服务
+
+```bash
+docker compose down
+```
+
+### 故障排除
+
+#### 查看服务状态
+
+```bash
+# 查看所有容器状态
+docker ps
+
+# 查看后端服务日志
+docker logs api-dev -f
+
+# 查看前端服务日志
+docker logs web-dev -f
+```
+
+#### 常见问题
+
+<details>
+<summary><strong>Docker 镜像拉取失败</strong></summary>
+
+如果拉取镜像失败，可以尝试手动拉取：
+
+```bash
+bash docker/pull_image.sh python:3.11-slim
+```
+
+**离线部署方案**：
+
+```bash
+# 在有网络的环境保存镜像
+bash docker/save_docker_images.sh  # Linux/macOS
+powershell -ExecutionPolicy Bypass -File docker/save_docker_images.ps1  # Windows
+
+# 传输到目标设备
+scp docker_images_xxx.tar <user>@<dev_host>:<path_to_save>
+
+# 在目标设备加载镜像
+docker load -i docker_images_xxx.tar
+```
+
+</details>
+
+<details>
+<summary><strong>构建失败</strong></summary>
+
+如果构建失败，通常是网络问题，可以配置代理：
+
+```bash
+export HTTP_PROXY=http://IP:PORT
+export HTTPS_PROXY=http://IP:PORT
+```
+
+如果已配置代理但构建失败，尝试移除代理后重试。
+
+</details>
+
+<details>
+<summary><strong>Milvus 启动失败</strong></summary>
+
+```bash
+# 重启 Milvus 服务
+docker compose up milvus -d
+docker restart api-dev
+```
+
+</details>