docs: 更新智能体和文档处理相关文档，添加内置工具说明及支持的文件类型**

Author: xerrors

docs/advanced/agents.md

@@ -51,10 +51,24 @@ agent_manager.init_all_agents()
 
 ## 内置工具与 MCP 集成
 
-
-::: warning
-文档待完善
-:::
+系统默认会为对话/推理智能体注册一组“内置工具”，并根据配置动态启用：
+
+- 知识图谱查询：`query_knowledge_graph`
+  - 依赖 Neo4j 服务（见 docker-compose 中 `graph`）
+  - 返回包含三元组的结果，适合图谱关系类问题
+- 网页搜索：`TavilySearch`
+  - 需要设置 `TAVILY_API_KEY` 才会启用
+  - LLM 在需要时自动调用，提供实时网页信息
+- 知识库检索工具：按知识库动态生成
+  - 工具名称形如 `query_<db_id前缀>`；描述来自知识库名称与说明
+  - 在工具选择阶段，用描述帮助模型做针对性检索
+- MySQL 工具包：只读查询
+  - `mysql_list_tables`、`mysql_describe_table`、`mysql_query`
+  - 环境变量见下，具备超时/行数限制与注入防护
+
+MCP（Model Context Protocol）可接入外部可视化或其他工具能力：
+- 在 `src/agents/common/mcp.py` 的 `MCP_SERVERS` 添加配置；`transport` 字段名必须正确
+- 常见问题：无法列出工具多因服务不可达或配置错误；优先检查可达性与字段名
 
 
 ### 1. MySQL 数据库集成
@@ -115,5 +129,5 @@ MCP_SERVERS = {
 ```
 
 ::: warning 配置注意
-记得将 `type` 字段修改为 `transport`。
+记得将 `type` 字段修改为 `transport`，并确保服务可达。
 :::

docs/advanced/document-processing.md

@@ -51,6 +51,13 @@ docker compose up paddlex --build
 - **结构化文档**: PP-Structure-V3
 - **生产环境**: 根据硬件条件选择
 
+### `enable_ocr` 取值说明（入库参数）
+
+- `disable`：不启用 OCR（PDF 将按纯文本提取，图片会自动转为 `onnx_rapid_ocr` 提示）
+- `onnx_rapid_ocr`：CPU 友好，安装简单
+- `mineru_ocr`：GPU 加速，复杂文档效果好
+- `paddlex_ocr`：结构化表格/票据等场景
+
 ## 批量处理脚本
 
 系统提供便捷的批量处理脚本，支持文件上传和解析操作。
@@ -81,6 +88,8 @@ uv run scripts/batch_upload.py upload \
 - `--recursive`: 递归处理子目录
 - `--record-file`: 处理记录文件路径
 
+提示：系统按“内容哈希”进行去重；同一知识库已存在相同内容的文件会被拒绝（409）。
+
 ### 文件解析脚本
 
 使用 `scripts/batch_upload.py trans` 将文件解析为 Markdown：
@@ -108,3 +117,5 @@ uv run scripts/batch_upload.py trans \
 - **断点续传**: 支持中断后继续处理
 - **日志记录**: 详细记录处理过程
 - **结果统计**: 处理完成后显示统计信息
+
+更多关于“入库参数、导出数据、支持类型”等，请参阅：介绍 → 知识库与知识图谱 → 文档管理。

docs/changelog/faq.md

@@ -1,2 +1,42 @@
 # 常见问题
 
+以下为最常见的安装与使用问题，更多细节请参阅相应章节链接。
+
+- 首次运行如何创建管理员？
+  - 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`
+  - 转 Markdown：`uv run scripts/batch_upload.py trans --db-id <id> --directory <dir> --username <u> --password <p>`
+  - 参考：高级配置 → 文档解析
+
+- 登录失败被锁定？
+  - 多次失败会临时锁定账户，请根据提示等待后重试
+
+- 如何查看日志和状态？
+  - `docker ps` 查看整体；`docker logs api-dev -f`、`docker logs web-dev -f` 查看服务日志

docs/changelog/roadmap.md

@@ -12,6 +12,7 @@
 
 **Next**
 
+- [ ] 修改现有的 ReAct 智能体，并尽量将默认助手的特性兼容到 LangGraph 的 [`create_agent`](https://docs.langchain.com/oss/python/langchain/agents) 中
 - [ ] 添加对于上传文件的支持
 - [ ] 知识图谱的上传和可视化，支持属性，标签的展示 <Badge type="info" text="0.4" />
 - [ ] 集成智能体评估，首先使用命令行来实现，然后考虑放在 UI 里面展示

docs/index.md

@@ -38,4 +38,6 @@ features:
 
 ```sh
 docker compose up --build -d
-```
+```
+
+查看端口与服务说明：高级配置 → 其他配置 → 服务端口。

docs/intro/knowledge-base.md

@@ -33,15 +33,45 @@ LightRAG 知识库可在知识库详情中可视化，但不支持在侧边栏
 
 ## 文档管理
 
-::: danger
-待补充
-:::
+本系统的“上传 → 解析入库 → 检索/可视化”流程既可通过 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`
+- 转换为 Markdown：参见 `scripts/batch_upload.py trans`
 
 ## 知识图谱
 
-::: danger
-待补充关于知识图谱在项目中的定位
-:::
+本项目存在两类“图谱相关”能力：
+
+- 全局知识图谱（Neo4j）：用于智能体工具 `query_knowledge_graph` 的图实体查询；统一保存在 Neo4j 中，提供三元组检索和系统级可视化。
+- LightRAG 知识库内图谱：针对某个知识库由 LightRAG 自动抽取实体/关系，用于该库内的图增强检索与可视化；与全局图共享同一 Neo4j 实例，但通过特殊 tag 区分，不作为全局图谱使用。
+
+选择建议：
+- 更结构化的库内检索/可视化：优先使用 LightRAG（注意构建质量与成本）。
+- 统一的图查询/工具调用：依赖全局 Neo4j 图谱与工具 `query_knowledge_graph`。
+
+接入已有 Neo4j 实例、三元组导入方式与注意事项见下文说明；LightRAG 构建模型可通过 `.env` 中的 `LIGHTRAG_LLM_*` 变量覆盖。
 
 ### 1. 以三元组形式导入
 

docs/intro/quick-start.md

@@ -131,54 +131,3 @@ docker restart api-dev
 ```
 
 </details>
-
-
-## 常见问题
-
-### 服务管理
-
-**Q: 如何查看后端服务日志？**
-
-```bash
-# 查看后端日志
-docker logs api-dev -f
-
-# 查看前端日志
-docker logs web-dev -f
-
-# 查看所有服务状态
-docker ps
-```
-
-### OCR 服务
-
-**Q: RapidOCR 模型未找到怎么办？**
-
-确认以下文件存在：
-- `MODEL_DIR` 指向的目录存在 `SWHL/RapidOCR`
-- 包含 `PP-OCRv4` 下的 `det_infer.onnx` 和 `rec_infer.onnx` 文件
-
-**Q: MinerU/PaddleX 健康检查失败？**
-
-分别检查服务状态：
-- MinerU: `http://localhost:30000/health`
-- PaddleX: `http://localhost:8080/`
-
-确认 GPU/驱动与 CUDA 版本匹配。
-
-### 数据库连接
-
-**Q: Milvus 启动失败？**
-
-```bash
-# 重启 Milvus 服务
-docker compose up milvus -d
-docker restart api-dev
-```
-
-**Q: Neo4j 连接问题？**
-
-检查默认账户信息：
-- 用户名: `neo4j`
-- 密码: `0123456789`
-- 管理界面: `http://localhost:7474`