code-intel

# 🧠 代码智能 <div align="center"> **一款适用于 Delphi/Pascal 代码库以及其他约 45 种语言的本地优先、混合（语义 + 关键词）代码智能工具，带有 RAG 聊天面板和用于 AI 编码代理的 17 工具 MCP 服务器。** [](README.tr-TR.md) [](https://www.apache.org/licenses/LICENSE-2.0) [](https://www.python.org/) [](https://fastapi.tiangolo.com/) [](https://qdrant.tech/) [](https://ollama.com/) [](https://modelcontextprotocol.io/) [](https://claude.ai) *[Turkish](README.tr-TR.md) · [贡献](CONTRIBUTING.md) · [行为准则](CODE_OF_CONDUCT.md) · [安全](SECURITY.md) · [致谢](ACKNOWLEDGMENTS.md)*  </div> ## 📋 目录 - [Turkish-Türkçe](README.tr-TR.md) - [这是什么项目？](#-这是什么项目) - [为什么使用它？](#-为什么使用它) - [核心能力](#-核心能力) - [支持的语言](#-支持的语言) - [MCP 工具（用于 AI 代理）](#-mcp-工具用于-ai-代理) - [项目结构](#-项目结构) - [先决条件](#-先决条件) - [快速入门](#-快速入门) - [安全状况](#-安全状况) - [设计与哲学](#-设计与哲学) - [致谢](#-致谢) - [贡献](#-贡献) --- ## 💡 这是什么项目？ **CodeIntel** 不是一个 AI 行为规则包——它是一个正在运行的应用程序：一个 FastAPI 后端 + Qdrant 矢量数据库 + Ollama 本地 LLM，共同组成一个代码搜索和理解工具，该工具源于对大型 Delphi 库（UniDAC，约 25,000 个块）的索引，现在推广到数十种语言。 它回答了代码库搜索框通常无法回答的问题： - ✅ **混合搜索** — 通过 Qdrant 的 RRF 进行密集（语义）和稀疏（BM25 关键词）融合，带有名称匹配增强和可选的跨编码器重新排序 - ✅ **RAG 聊天与实际引用** — “Cevapla”模式从顶部 K 个匹配中回答；“Derin”（深度研究）模式提取主要符号及其调用者/被调用者/类型层次结构/单元依赖项到一个上下文包中，然后再回答 - ✅ **通过 MCP 准备好代理** — 17 个工具（搜索、解释、关系、影响分析、上下文包...）通过 stdio 和 LAN 公开的 Streamable HTTP 提供服务，因此 Claude Code/Codex CLI/Gemini CLI 可以查询与 Web 面板相同的索引 - ✅ **自我文档生成** — 为每个集合生成完整的 HTML/PDF/DOCX 手册，带有 AI 辅助的 TR/EN 翻译 > 再也不需要对 25,000 个块的 Delphi 代码库进行 `grep` 操作，或者让 AI 代理在没有上下文的情况下解释“这是什么”。 --- ## 🤔 为什么使用它？ | 没有 CodeIntel | 使用 CodeIntel | |---|---| | 只有 `grep`/全文搜索，没有语义匹配 | 混合密集 + 稀疏搜索，土耳其查询 ↔ 英语/Delphi 代码均可 | | AI 代理只能看到您粘贴的文件 | MCP 工具为其提供完整的调用图、类型层次结构和单元依赖项 | | “这 6 个近似重复的 `Split` 函数中哪一个最安全？” — 没有人知道，除非阅读所有 6 个 | 比较表要求 LLM 评估每个候选者的稳定性/性能，并附上一行理由 | | 重新阅读旧提交以了解 *为什么* 代码更改 | `analyze_impact` 将 diff 范围与受影响的块关联起来 | | 手动编写/维护开发人员文档 | `document_unit`/手册生成器生成并缓存它们，根据需要刷新 | --- ## 🌟 核心能力  - **混合 RRF 搜索**，可跨多个集合进行搜索，带有每种语言的过滤器、交叉编码器重新排序和“为什么排名在这里”的结果分解。 - **RAG 聊天** (`/api/ask`，`/api/ask/stream`) 和 **深度研究** (`/api/research/stream`，基于令牌预算的上下文包) — 两者都经过 SSE 流式传输，两者都经过缓存，两者都具有截断感知（显示 Ollama 自己的 `done_reason` 而不是静默返回截断的答案）。 - **函数比较表** (`/api/compare`) — 当查询显示多个实现执行相同的任务时，一个 LLM 调用评估每个实现的稳定性/性能，并附有一行理由。 - **符号图** — 继承、`find_references`、调用者/被调用者边，存储在其自己的内部集合中（不嵌入每个点的有效载荷中，因此它独立于代码集合的大小进行扩展）。 - **Git 源代码 + 影响分析** — 将提交范围与它们所触及的块关联起来。 - **自动生成的手册** — 每个集合的 HTML/PDF/DOCX 文档，可折叠的类树侧边栏，自我托管的语法高亮（无 CDN 依赖），AI 辅助的双语（TR/EN）翻译。 - **重复代码检测** — 基于阈值的相似性扫描已索引的嵌入（无需重新嵌入）。 - **原子、可恢复的索引** — 分段 + 别名生成模型（在单独的集合中重建索引，只有在完整且经过验证后才原子交换），持久的作业队列在中途重启后存活。 - **所有者/组注册、API 密钥，具有读取/管理角色分离、速率限制、审计日志** — 相同的面板支持单个操作员的本地使用和 LAN 共享的多密钥访问。 --- ## 🌐 支持的语言 一个通用的 Tree-sitter 引擎在结构上覆盖了 **约 45 种语言**；**8 种语言具有深度支持**（父/子 AST 分割用于嵌套类方法、`uses`/导入提取、单元头解析）：**Delphi/Pascal**、**Python**、**C#**、**C/C++**、**Java**、**JavaScript/TypeScript**、**Go**、**Rust**。 --- ## 🤖 MCP 工具（用于 AI 代理） `src/mcp_server.py` 通过 stdio（默认）和可选的 LAN 面向 Streamable HTTP 公开 17 个工具 — 每个工具还有一个 `/api/mcp/*` 下的 REST 测试端点（由 `tests/test_api.py::test_mcp_rest_parity` 强制执行），可以从 `static/api.html` 进行实时测试。 | 工具 | 用途 | |---|---| | `search_code` | 带有语言/类型/单元过滤器的混合搜索 | | `find_similar` | 给定块的最近邻 | | `read_unit` | 源文件（单元）的内容 | | `get_chunk` | 单个块的完整有效载荷 | | `get_relations` | 调用者/被调用者/同文件关系 | | `explain_chunk` | 快速或深入的 LLM 解释（缓存） | | `review_code` | 块的 LLM 代码审查 | | `propose_edit` | 仅显示 diff 建议（永不自动应用） | | `ask_domain_model` | 将问题路由到特定领域模型（例如 SQL） | | `get_type_hierarchy` | 类型的祖先/后代 | | `find_references` | 集合中对名称的所有引用 | | `analyze_impact` | 将 git diff 范围与受影响的块关联起来 | | `get_unit_deps` | 文件的 `uses`/导入依赖图 | | `get_context_pack` | 用于任务的基于令牌预算的多源上下文包 | | `document_unit` | 生成/获取文件的缓存文档 | | `list_domain_models` | 列出配置的特定领域模型 | | `list_collections` | 列出索引集合及其统计信息 | --- ## 📂 项目结构 ``` code-intel/ │ ├── src/ │ ├── retrieval.py # 核心搜索/RAG/解释逻辑 — 由面板和 mcp_server 共享，永不重复 │ ├── chunker.py # Tree-sitter 多语言分块 │ ├── manual.py # 文档生成器（HTML/PDF/DOCX，i18n） │ ├── mcp_server.py # 17 个 MCP 工具，stdio + Streamable HTTP │ ├── panel.py # FastAPI 应用入口 + security_guard 中间件 │ ├── api/ # 模块化路由器：搜索、索引、管理员、手动、mcp │ └── services/ # 共享状态、配置文件、API 密钥、备份、索引管道 │ ├── static/ │ ├── index.html # 搜索 + 聊天面板 │ ├── settings.html # 集合/索引管理 │ ├── api.html # REST + MCP 工具测试器 │ └── viewer.html # 独立文件查看器 │ ├── tests/ # pytest — 大多数测试需要一个 live Qdrant（@needs_qdrant，跳过不失败） ├── tools/ # start-system.ps1 / stop-system.ps1 / install-autostart.ps1 ├── qdrant-bin/ # Qdrant 二进制文件（Windows） ├── mcp-config.json # MCP 服务器默认值（Qdrant/Ollama URL，模型名称） ├── requirements.txt # 固定的依赖版本（参见 requirements.txt 中的 onnxruntime-gpu 注） └── pyproject.toml ``` > 不包括在此副本中：`data/`（Qdrant 存储 + 块缓存）、`.venv/`、`backups/`、`logs/` — 所有本地重新生成，所有 `.gitignore`d。 --- ## 🔧 先决条件 - **Python 3.12+** - **Qdrant**（`qdrant-bin/` 下的捆绑二进制文件，或运行您自己的） - **Ollama** — 用于聊天、深入研究、解释、翻译和比较表 - **PowerShell 7+ (`pwsh`)** — `tools/start-system.ps1`/`stop-system.ps1` 是 PowerShell 脚本（Windows-first；Python/FastAPI 核心本身是跨平台的） - 具有 CUDA 能力的 GPU 是可选的，但强烈建议用于嵌入吞吐量（参见 `requirements.txt` 中的 `onnxruntime-gpu` 固定注） --- ## ⚡ 快速入门 ```bash # 1. 安装依赖项（固定的版本 — 参见 requirements.txt 中的 onnxruntime-gpu 注） uv pip install -r requirements.txt --python .venv/Scripts/python.exe # 2. 启动 Qdrant + Ollama + 面板（Windows） pwsh tools/start-system.ps1 -NoBrowser ``` 然后打开 `http://127.0.0.1:8500` — 从设置中索引一个文件夹，然后从主页面搜索/聊天。要将其用作 MCP 服务器而不是（或与）面板一起使用，请将您的 AI CLI 的 MCP 配置指向 `src/mcp_server.py`（stdio）— 参见 `mcp-config.json` 以获取它读取的默认值（Qdrant/Ollama URL，快速/深度模型名称）。 ```bash pytest tests/ -q # 需要一个 live Qdrant（tools/start-system.ps1）才能进行大多数测试；其余测试干净地跳过 ``` --- ## 🔐 安全状况 默认绑定到 `127.0.0.1`；LAN 暴露是按需通过角色分离的 API 密钥（`read`/`admin`）开启的。有关完整的威胁模型，请参见 [SECURITY.md](SECURITY.md)，其中包括两个值得注意的修复程序：如果您正在审计此代码库，请查看 2026-07-25 添加的客户端控制的出站 URL（SSRF）限制以及同一日期的 HTML/JS 上下文感知转义修复（纯 `&<>` 转义在 `onclick="fn('...')"` 属性内是不够的 — 参见 `escJs()`/`_esc_js()`）。 --- ## 🎯 设计与哲学  **验证，而不是假设。** 此代码库的 git 历史记录中的每个修复程序 — SSRF 限制、转义修复、原子导入重设计、检查然后设置竞争条件修复 — 都通过测试得到验证，该测试会因旧代码失败而因新代码通过，而不是仅仅推理并未经测试。相同的纪律扩展到搜索排名（`tests/eval.py` 的黄金查询基准）和答案本身（两种聊天模式都报告 Ollama 自己的截断信号，而不是静默返回截断的答案作为完整）。刻意的权衡：与“看起来正确”相比，修复程序发布得较慢，以换取一个代码库，其中“测试通过”实际上意味着某些东西。 --- ## 🙏 致谢 参见 [ACKNOWLEDGMENTS.md](ACKNOWLEDGMENTS.md) / [ACKNOWLEDGMENTS.tr-TR.md](ACKNOWLEDGMENTS.tr-TR.md)，了解此工具所依赖的开源项目和模型。 --- ## 🤝 贡献 参见 [CONTRIBUTING.md](CONTRIBUTING.md) / [CONTRIBUTING.tr-TR.md](CONTRIBUTING.tr-TR.md)。 --- <div align="center"> 由 **Emrah BAŞPINAR** 和 **Recep Eymen BAŞPINAR** 制作。 *[贡献](CONTRIBUTING.md) · [行为准则](CODE_OF_CONDUCT.md) · [安全](SECURITY.md) · [致谢](ACKNOWLEDGMENTS.md)* </div>