Codedox

🚀 CodeDox - 文檔代碼提取與搜索

CodeDox 是一個強大的系統，可用於爬取文檔網站、提取代碼片段，並通過 MCP（模型上下文協議）集成提供快速搜索功能。

🚀 快速開始

前提條件

• Python 3.10 及以上版本
• PostgreSQL 12 及以上版本
• Playwright（會隨 crawl4ai 自動安裝）

安裝步驟

1. 克隆倉庫：

git clone https://github.com/yourusername/codedox.git
cd codedox

2. 創建虛擬環境：

uv venv
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate

3. 安裝依賴：

uv pip install -r requirements.txt

# 安裝 Playwright 瀏覽器（網頁爬取必需）
crawl4ai-setup

4. 配置 PostgreSQL：

# 創建數據庫
createdb codedox

# 初始化數據庫模式（僅首次需要）
python cli.py init

# 重置並重新創建所有表（警告：會刪除所有數據）
python cli.py init --drop

5. 配置環境：

cp .env.example .env
# 使用你的設置編輯 .env 文件

運行應用程序

快速啟動

# 創建並激活虛擬環境（如果尚未完成）
uv venv
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate

# 初始化數據庫（僅首次需要）
python cli.py init

# 啟動所有服務（API + 網頁界面）
python cli.py all

這將：

• ✅ 在 http://localhost:8000 啟動 API 服務器
• ✅ 在 http://localhost:5173 啟動網頁界面
• ✅ 在 http://localhost:8000/mcp 啟用 MCP 工具
• ✅ 為兩個服務啟用熱重載

注意：網頁界面為所有操作（包括爬取、搜索和監控）提供了用戶友好的界面，無需記憶 CLI 命令！

分別運行服務

# 僅啟動 API 服務器
python cli.py run

# 僅啟動網頁界面（在另一個終端中）
python cli.py ui

# 僅啟動 API 服務器（另一種方式）
python cli.py api

✨ 主要特性

• 可控網頁爬取：可手動爬取，深度可配置（0 - 3 級）
• 智能代碼提取：提取代碼塊的同時保留上下文
• 語言檢測：使用大語言模型（LLM）進行上下文感知的語言檢測
• 快速搜索：使用 PostgreSQL 全文搜索，響應時間小於 100 毫秒
• MCP 集成：通過模型上下文協議（MCP）將工具暴露給 AI 助手
• 源管理：跟蹤多個文檔源並提供統計信息
• 內容清理：集成 Crawl4AI 以移除導航欄、廣告和雜亂內容
• 現代網頁界面：基於 React 的儀表盤，用於管理爬取任務、搜索代碼和監控系統活動
• 自動網站內容去重：僅更新或添加有更改的內容

🔧 技術細節

架構

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│    Web UI       │────▶│   FastAPI       │────▶│   PostgreSQL    │
│ (React + Vite)  │     │   Server        │     │  (Full-Text)    │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                              │
┌─────────────────┐           │
│   MCP Client    │────▶│ MCP Tools │
│  (AI Assistant) │     │           │
└─────────────────┘     └───────────┘
                              │
                              ▼
                       ┌─────────────────┐
                       │   Crawl4AI      │
                       │  (Web Crawler)  │
                       └─────────────────┘

💻 使用示例

基礎用法

# 克隆倉庫
git clone https://github.com/yourusername/codedox.git
cd codedox

# 創建虛擬環境
uv venv
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate

# 安裝依賴
uv pip install -r requirements.txt
crawl4ai-setup

# 配置 PostgreSQL
createdb codedox
python cli.py init

# 配置環境
cp .env.example .env
# 編輯 .env 文件

# 啟動所有服務
python cli.py all

高級用法

# 分別啟動服務
# 啟動 API 服務器
python cli.py run

# 啟動網頁界面
python cli.py ui

📚 詳細文檔

MCP（模型上下文協議）集成

CodeDox 支持兩種 MCP 模式：

1. HTTP 模式（推薦） - 通過主 API 服務器上的 HTTP 端點暴露 MCP 工具
2. 標準輸入輸出模式 - 傳統的 MCP 服務器，用於直接與 AI 助手集成

HTTP 模式（內置於 API 服務器）

當運行 API 服務器（python cli.py api 或 python cli.py all）時，MCP 工具會通過 HTTP 端點自動可用，無需單獨的 MCP 服務器。

MCP 協議端點（推薦用於 AI 助手）：

• POST /mcp - 可流式傳輸的 HTTP 傳輸（MCP 2025 - 03 - 26 規範） - 最新且推薦
• POST /mcp/v1/sse - 服務器發送事件傳輸（舊版支持）

舊版 REST 端點：

• GET /mcp/health - 健康檢查
• GET /mcp/tools - 列出可用工具及其架構
• POST /mcp/execute/{tool_name} - 執行特定工具
• POST /mcp/stream - 用於簡單集成的流式端點

使用示例： 對於使用 MCP 協議（可流式傳輸的 HTTP - 推薦）的 AI 助手：

# 配置你的 AI 助手使用最新的可流式傳輸的傳輸方式：
# URL: http://localhost:8000/mcp
# 傳輸方式: 可流式傳輸的 HTTP
# 頭部信息: Accept: application/json, text/event-stream

對於使用 MCP 協議（SSE - 舊版）的 AI 助手：

# 配置你的 AI 助手使用 SSE 傳輸方式：
# URL: http://localhost:8000/mcp/v1/sse
# 傳輸方式: 服務器發送事件（SSE）

對於直接使用 API：

# 列出可用工具
curl http://localhost:8000/mcp/tools

# 從庫中獲取代碼片段（使用庫名）
curl -X POST http://localhost:8000/mcp/execute/get_content \
  -H "Content-Type: application/json" \
  -d '{"library_id": "nextjs", "query": "authentication"}'

# 或者使用 UUID
curl -X POST http://localhost:8000/mcp/execute/get_content \
  -H "Content-Type: application/json" \
  -d '{"library_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "query": "authentication"}'

標準輸入輸出模式（獨立的 MCP 服務器）

對於需要傳統基於標準輸入輸出的 MCP 通信的 AI 助手：

# 運行獨立的 MCP 服務器
python cli.py mcp

此模式僅適用於不支持 HTTP 端點的特定 AI 集成。

可用的 MCP 工具

1. init_crawl - 啟動文檔爬取任務

   • name：庫/框架名稱（可選 - 如果未提供則自動檢測）
   • start_urls：要爬取的 URL 列表
   • max_depth：爬取深度（0 - 3）
   • domain_filter：可選的域名限制
   • url_patterns：可選的要包含的 URL 模式列表（例如，["docs", "guide"]）
   • max_concurrent_crawls：最大併發頁面爬取數（默認：20）
   • metadata：附加元數據（可選）

2. search_libraries - 按名稱搜索可用庫

   • query：庫名稱的搜索查詢（例如，'react', 'nextjs', 'django'）
   • max_results：返回的最大結果數（1 - 50，默認：10）

3. get_content - 從庫中獲取代碼片段

   • library_id：庫 ID（UUID）或庫名稱（例如，'nextjs', 'react'）
   • query：可選的搜索詞，用於過濾結果
   • max_results：限制結果數量（1 - 50，默認：10）

4. get_snippet_details - 獲取特定代碼片段的詳細信息

   • snippet_id：代碼片段的 ID（來自 get_content 結果）

API 端點

爬取

• POST /crawl/init - 啟動新的爬取任務，可選擇進行 URL 模式過濾
• GET /crawl/status/{job_id} - 檢查爬取狀態
• POST /crawl/cancel/{job_id} - 取消正在運行的任務

搜索

• POST /search - 搜索代碼片段
• GET /search/languages - 列出可用語言
• GET /search/recent - 獲取最近的代碼片段

源

• GET /sources - 列出文檔源
• GET /snippets/{id} - 獲取特定代碼片段
• GET /export/{job_id} - 導出爬取結果

上傳

• POST /upload/markdown - 上傳 Markdown 內容
• POST /upload/file - 上傳 Markdown 文件

網頁界面

CodeDox 包含一個基於 React 和 TypeScript 構建的現代響應式網頁界面。在運行開發服務器時，可通過 http://localhost:5173 訪問。

特性

• 儀表盤：即時統計信息、系統概述和最近活動監控
• 高級搜索：強大的代碼片段搜索功能，支持語言過濾和語法高亮
• 源管理：瀏覽和管理文檔源，並提供詳細統計信息
• 爬取監控：通過 WebSocket 即時跟蹤爬取任務的進度更新
• 設置：通過直觀的界面配置應用程序設置

技術棧

• 前端框架：React 18 搭配 TypeScript
• 構建工具：Vite 實現快速開發
• 樣式：Tailwind CSS 支持黑暗模式
• 狀態管理：React Query 實現高效數據獲取
• 即時更新：集成 WebSocket 實現即時爬取進度更新

網頁界面為所有主要操作提供了一個用戶友好的替代 CLI 的方式，無需記憶命令即可輕鬆管理文檔管道。

LLM 並行請求配置

為了與本地 LLM 服務器實現最佳性能，請在 .env 文件中配置並行請求設置：

# LLM 配置
LLM_ENDPOINT=http://localhost:8080
LLM_MODEL=gpt-4
LLM_API_KEY=your-api-key-here
LLM_MAX_TOKENS=1000
LLM_TEMPERATURE=0.1

# 並行請求設置（根據你的 LLM 服務器能力調整）
LLM_MAX_CONCURRENT_REQUESTS=20    # 向 LLM 發送的最大並行請求數
LLM_REQUEST_TIMEOUT=30.0          # 請求超時時間（秒）
LLM_RETRY_ATTEMPTS=3              # 失敗時的重試次數

尋找最佳值： 使用包含的配置測試來確定適合你 LLM 設置的最佳配置：

# 快速測試以找到最佳設置（推薦）
python scripts/test_llm_config.py

# 或者運行全面的性能分析
python tests/performance/test_llm_concurrency_performance.py
python tests/performance/visualize_concurrency_results.py

配置指南：

• 本地 LLM（如 Ollama 等）：從 LLM_MAX_CONCURRENT_REQUESTS = 5 - 10 開始
• GPU 服務器：根據 VRAM 情況，可處理 LLM_MAX_CONCURRENT_REQUESTS = 15 - 30
• 雲 API（如 OpenAI、Claude）：根據速率限制，使用 LLM_MAX_CONCURRENT_REQUESTS = 20 - 50
• 僅使用 CPU：保持 LLM_MAX_CONCURRENT_REQUESTS = 2 - 5 以避免系統過載

監控你的 LLM 服務器的資源使用情況並相應調整。更高的併發度可以提高爬取速度，但可能會增加延遲或導致超時。

語言支持

支持自動檢測以下語言：

• Python、JavaScript、TypeScript
• Java、Go、Rust、C/C++、C#
• Ruby、PHP、SQL、Bash
• HTML、CSS、YAML、JSON、XML

開發

項目結構

codedox/
├── src/
│   ├── api/          # FastAPI 端點
│   ├── crawler/      # 網頁爬取邏輯
│   ├── database/     # 模型和搜索
│   ├── language/     # 語言檢測
│   ├── mcp_server/   # MCP 服務器實現
│   └── parser/       # 代碼提取
├── tests/            # 測試套件
├── config.yaml       # 配置文件
└── requirements.txt  # 依賴項

運行測試

pytest tests/

性能

• 搜索速度：全文搜索響應時間小於 100 毫秒
• 存儲：每個帶上下文的代碼片段約 50KB

故障排除

常見問題

數據庫連接失敗

• 檢查 PostgreSQL 是否正在運行
• 驗證 .env 文件中的憑據

貢獻

1. 分叉倉庫
2. 創建功能分支（git checkout -b feature/amazing）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 推送分支（git push origin feature/amazing）
5. 打開拉取請求

作者

Chris Scott - 初始工作和開發

📄 許可證

本項目採用 MIT 許可證 - 有關詳細信息，請參閱 LICENSE 文件。