医生

Name: 医生
Author: sisig-ai

作者：sisig-ai460 星标更新：2025-05-24

项目介绍

<div align="center"> <picture> <img alt="Doctor Logo" src="doctor.png" height="30%" width="30%"> </picture> <br> <h2>🩺 Doctor</h2>

一个用于发现、爬取和索引网站的工具，将其作为MCP服务器暴露给LLM代理，以实现更准确和及时的推理和代码生成。

</div>

🔍 概述

Doctor 提供了一整套解决方案：

使用crawl4ai进行网页爬取，并跟踪层次结构
使用LangChain对文本进行分块
使用litellm通过OpenAI创建嵌入
在支持向量搜索的DuckDB中存储数据
通过FastAPI网络服务提供搜索功能
通过MCP服务器使这些能力可供LLM使用
使用分层站点地图浏览爬取的站点

🏗️ 核心基础设施

🗄️ DuckDB

存储文档数据和嵌入的数据库，具有向量搜索功能
由统一的Database类管理

📨 Redis

异步任务处理的消息代理

🕸️ 爬虫工作器

处理爬取任务
对文本进行分块
创建嵌入

🌐 网络服务器

FastAPI服务，公开端点
获取、搜索和查看数据
公开MCP服务器

💻 安装

⚙️ 预备条件

Docker 和 Docker Compose
Python 3.10+
uv（Python 包管理器）
OpenAI API 密钥

📦 安装步骤

克隆此仓库
设置环境变量：
```
export OPENAI_API_KEY=your-openai-key
```
运行堆栈：
```
docker compose up
```

👁 使用方法

访问 http://localhost:9111/docs 查看OpenAPI文档
查找 /fetch_url 端点并提供URL开始爬取任务
使用 /job_progress 查看当前任务状态
配置编辑器以使用 http://localhost:9111/mcp 作为MCP服务器

☁️ 网络API

核心端点

POST /fetch_url: 开始爬取URL
GET /search_docs: 搜索已索引的文档
GET /job_progress: 检查爬取任务进度
GET /list_doc_pages: 列出已索引的页面
GET /get_doc_page: 获取页面的全文

站点地图功能

地图功能提供了爬取网站的分层视图，便于导航和探索已索引站点的结构。

端点：

GET /map: 查看所有爬取站点的索引
GET /map/site/{root_page_id}: 查看特定站点的分层树结构
GET /map/page/{page_id}: 查看特定页面及其导航（父级、同级、子级）
GET /map/page/{page_id}/raw: 获取页面的原始Markdown内容

特性：

分层导航：页面维护父子关系，允许您在站点结构中导航
域分组：来自同一域的单独爬取页面自动分组在一起
自动标题提取：从HTML或Markdown内容中提取页面标题
面包屑导航：通过显示从根到当前页面路径的面包屑轻松导航
同级导航：快速访问层次结构中同一级别的页面
旧版页面支持：在层次结构跟踪之前爬取的页面按域分组，便于访问
无需JavaScript：所有导航仅使用纯HTML和CSS，以确保最大兼容性

使用示例：

使用 /fetch_url 端点爬取一个网站
访问 /map 查看所有爬取的站点
点击一个站点查看其分层结构
使用提供的链接浏览页面

🔧 MCP集成

确保您的Docker Compose堆栈正在运行，然后在Cursor或VSCode MCP服务器配置中添加：

"doctor": {
    "type": "sse",
    "url": "http://localhost:9111/mcp"
}

🧪 测试

运行测试

要运行所有测试：

# 运行所有测试并生成覆盖率报告
pytest

要运行特定测试类别：

# 只运行单元测试
pytest -m unit

# 只运行异步测试
pytest -m async_test

# 运行特定组件的测试
pytest tests/lib/test_crawler.py

测试覆盖率

项目配置为自动生成覆盖率报告：

# 运行测试并生成详细的覆盖率报告
pytest --cov=src --cov-report=term-missing

测试结构

tests/conftest.py: 所有测试的通用fixture
tests/lib/: 库组件的测试
- test_crawler.py: 爬虫模块的测试
- test_crawler_enhanced.py: 带层次跟踪的增强型爬虫的测试
- test_chunker.py: 分块模块的测试
- test_embedder.py: 嵌入模块的测试
- test_database.py: 统一的Database类的测试
- test_database_hierarchy.py: 数据库层次操作的测试
tests/common/: 公共模块的测试
tests/services/: 服务层的测试
- test_map_service.py: 地图服务的测试
tests/api/: API端点的测试
- test_map_api.py: 地图API端点的测试
tests/integration/: 集成测试
- test_processor_enhanced.py: 带层次跟踪的增强型处理器的测试

🐞 代码质量

提交前钩子

项目配置了提交前钩子，在每次提交前自动运行：

ruff check --fix: 检查代码并自动修复问题
ruff format: 根据项目风格格式化代码
移除尾随空格
修正文件末尾
YAML验证
大文件检查

设置提交前钩子

要设置提交前钩子：

# 安装pre-commit
uv pip install pre-commit

# 安装git钩子
pre-commit install

手动运行提交前钩子

您可以手动在所有文件上运行提交前钩子：

# 运行所有提交前钩子
pre-commit run --all-files

或者只在暂存文件上运行：

# 在暂存文件上运行
pre-commit run

⚖️ 许可证

本项目采用MIT许可证 - 详情见LICENSE.md文件。