goyal-harshit/codebase-intelligence-platform

# 企业级代码库智能平台 [](https://github.com/goyal-harshit/codebase-intelligence-platform/actions/workflows/ci.yml)      开源平台，能够接入任何 Git 仓库，构建代码的知识图谱 + 向量索引，并回答自然语言问题，检测架构风险，计算变更影响 / 爆炸半径，运行 SAST 安全扫描，推荐重构方案，以及自动生成文档 wiki —— 完全运行在免费、自托管的基础设施上（无需付费 API，无需付费云服务）。 请参阅 [PROJECT_PLAN.md](PROJECT_PLAN.md) 了解架构、功能矩阵和路线图（它取代了所有早期的计划文档）。发布版本是带有注释的 git tag，并在 [CHANGELOG.md](CHANGELOG.md) 中有相应的条目；贡献规范位于 [CONTRIBUTING.md](CONTRIBUTING.md) 中。 ## 截图 | 仪表盘 | 询问代码库 | |---|---| |  |  | | 安全 / SAST | 变更影响 | |---|---| |  |  | | 自动文档 wiki | 重构建议 | |---|---| |  |  | 更多内容请见 [docs/screenshots/](docs/screenshots/)。 ## 功能 - **仓库接入** — git clone 或归档上传，支持实时进度的持久化 Celery 任务，增量重新索引（基于 SHA，仅针对更改过的文件）。 - **知识图谱** — tree-sitter AST → ArcadeDB 图谱（文件/函数/类，调用/包含/继承/导入）+ NetworkX 分析。 - **混合搜索与问答** — LLM→Cypher 结构化查询，BGE 向量相似度 + BM25 词法融合（使用 RRF），通过本地 Ollama LLM 提供带有引用来源的、有依据的回答；支持对话历史。 - **分析套件** — 架构风险规则，变更影响 / 爆炸半径，热点热力图，SAST 安全仪表盘（内置扫描器 + Bandit + Ruff S），重构建议，AI 代码审查与摘要。 - **自动文档** — 从图谱生成的确定性逐模块 wiki，可选 LLM “目的”处理流程，可在 `/wiki` 浏览。 - **协作与运维** — JWT + GitHub OAuth + RBAC + 每用户 API 密钥，审计日志，评论/活动/通知，CSV/XLSX 导出，HTML/PDF 报告，速率限制，Prometheus 指标，健康检查。 - **一条命令部署** — Docker Compose 技术栈，包含首次启动时的演示数据播种。 ## 架构 ``` Next.js Frontend (:3100) │ FastAPI Gateway (:8001) JWT / OAuth / API keys / RBAC / rate limits │ ┌──────────────┬──────────┴─────────┬──────────────────┐ Ingestion Retrieval & Q&A Analysis Collaboration (upload/clone) (hybrid search+LLM) (risks/SAST/impact/ (comments, activity, │ │ hotspots/refactor) notifications+WS) tree-sitter Chroma + BGE │ │ GitPython BM25 + Ollama static analyzers Celery + Redis └──────────────┴──────────┬─────────┴──────────────────┘ │ PostgreSQL · Redis · ArcadeDB · ChromaDB · MinIO │ Docker Compose (one command) ``` 流水线：repo → clone → tree-sitter AST → 知识图谱 → 分块 → BGE embeddings → Chroma → 混合检索（图谱 + 向量 + 词法）→ 本地 LLM → 有依据的回答。完整详情请见 [docs/architecture.md](docs/architecture.md) 以及 [docs/adr/](docs/adr/) 下的 ADR。 ## 快速开始 一个安装器，一个启动器 —— 在 `git clone` 后立即可用： ``` # Linux / macOS # Windows (PowerShell) ./install.sh .\install.ps1 ./run.sh .\run.ps1 ``` `install` 会检查前置条件（Git, Python 3.11+, Node 20+, 可选 Docker），创建 `.venv`，安装后端和前端依赖，并根据 `.env.example` 写入 `.env`。`run` 会验证环境，自动选择可用端口，在 Docker 中启动 ArcadeDB + Chroma（如果可用），并启动后端和前端，日志保存在 `logs/` 下。`Ctrl+C` 会干净地关闭所有服务。 **Docker 中的完整类生产环境技术栈**（postgres, redis, minio, arcadedb, chroma, backend, worker, frontend）： ``` ./run.sh --docker # Windows: .\run.ps1 -Docker ``` 打开 http://localhost:3100。在首次启动时，后端会自动接入内置的 **PyShelf 演示仓库**（`backend/demo_repo/`），因此在你接入任何内容之前，仪表盘、图谱、风险、影响和安全页面就已经有数据了 —— 在 `.env` 中设置 `SEED_DEMO_REPO=false` 可改为空启动。在将此技术栈暴露给你的机器之外之前，请编辑 `.env` 以设置真实的 `AUTH_SECRET` / GitHub OAuth 密钥 / LLM 配置。数据持久化存储在指定的 Docker 卷中；`docker compose down` 会停止服务但不会触碰它们，`docker compose down -v` 会将它们清除。 **遇到问题了吗？** ``` ./run.sh --doctor # Windows: .\run.ps1 -Doctor ``` 它会诊断缺失的依赖、无法访问的服务和配置问题，并提供可操作的修复建议。 更喜欢在本地运行单个组件进行开发？请参阅下面的各个阶段部分。 ## 状态 | 阶段 | 组件 | 状态 | |---|---|---| | 1 | AST 解析引擎 | **已完成** | | 2 | 图数据库 | **已完成** | | 3 | 向量数据库 + embeddings | **已完成** | | 4 | 风险检测 | **已完成** | | 5 | 影响 / 爆炸半径 | **已完成** | | 6 | 混合检索 + LLM 问答 | **已完成** | | 7 | FastAPI 后端 | **已完成** | | 8 | Next.js 前端 | **已完成** | | 9 | Docker / 部署 | **已完成** | | 10 | 安全 / SAST 扫描器 | **已完成** | | 11 | 重构建议 | **已完成** | | 12 | GitHub OAuth 登录 | **已完成** | | 13 | v1.4 润色：演示数据播种、changelog + tags、截图 | **已完成** | 路线图已完成至 v1.4（参见 [CHANGELOG.md](CHANGELOG.md)）；`main` 分支上未发布的工作目前涵盖了统一的安装/运行启动器以及 CI 中的 Ruff lint 门控。 ### GitHub OAuth（可选） 在 github.com/settings/developers 创建一个免费的 OAuth App（回调 URL：你的后端 URL + `/auth/github/callback`，例如 `http://localhost:8000/auth/github/callback`），然后设置 `GITHUB_CLIENT_ID` 和 `GITHUB_CLIENT_SECRET`（例如在 `.env.local` 中）。配置后，登录页面会自动显示一个“Continue with GitHub”按钮；如果没有这些变量，邮箱/密码认证将继续工作，且按钮保持隐藏。 ## 阶段 1 — AST 解析器 语言无关的解析器，提取 `CodeEntity`（函数、类、方法）和 `CodeRelationship`（包含、调用、继承自、导入）对象。支持 Python, JS/TS, Go, Rust, Java 等。 ### 设置 使用虚拟环境 — 否则固定版本可能会与其他全局安装的工具发生冲突。 ``` python -m venv .venv .venv\Scripts\activate # Windows; source .venv/bin/activate on Unix pip install -r backend/requirements.txt ``` ### 在仓库上运行 ``` python scripts/parse_repo.py /path/to/repo --json out.json ``` ### 测试 ``` python -m pytest -q # from the repo root (pytest.ini sets paths) ``` ### 验证 在 0.28 秒内解析了 Flask（`src/`，24 个文件） — 388 个函数/方法，53 个类，与 `grep` 基准事实的误差在约 7% 以内。 ## 阶段 2 — 图数据库 将解析后的 `CodeEntity`/`CodeRelationship` 对象接入 ArcadeDB 图谱（`File`/`Function`/`Class`/`Interface`/`Module` 顶点；`CONTAINS`/`CALLS`/… 边）。接入使用参数化的 `UNWIND $rows` 批处理 — 没有通过字符串拼接构建的 Cypher — 并采用有类型的、由索引支持的边匹配。包括基于 SHA-256 的增量重新索引，该索引仅重新解析已更改的文件并清除已删除的文件。 ### 运行 ArcadeDB ``` docker run -d --name arcadedb -p 2480:2480 -p 2424:2424 \ -e JAVA_OPTS="-Xmx2g" -e arcadedb.server.rootPassword=ChangeMe123! \ -v arcadedb_data:/home/arcadedb/databases arcadedata/arcadedb:latest ``` 连接通过环境变量配置：`ARCADEDB_URL`（默认 `http://localhost:2480`），`ARCADEDB_DATABASE` (`codebase`)，`ARCADEDB_USER` (`root`)，`ARCADEDB_PASSWORD`。 ### 从仓库构建图谱 ``` python scripts/build_graph.py /path/to/repo # full ingest python scripts/build_graph.py /path/to/repo --reset # drop + rebuild python scripts/build_graph.py /path/to/repo --incremental # only changed files ``` ### 测试 ``` python -m pytest backend/tests/test_graph_db.py -q ``` 单元测试离线运行，使用记录的模拟客户端（无需服务器）。设置 `ARCADEDB_INTEGRATION=1` 并连接活跃的 ArcadeDB，即可同时运行往返测试。 ## 阶段 3 — 向量数据库与 Embeddings 使用 `BAAI/bge-small-en-v1.5` 对每个解析出的实体进行 embedding（感知 AST 的分块 — 每个函数/类/方法一个块），并将向量存储在 ChromaDB 中以进行语义搜索（“密码在哪里进行验证？”）。embedder 和 Chroma 集合都是可注入的，并且重型依赖（`chromadb`，`sentence-transformers`/torch）采用延迟加载，因此无需安装它们即可加载包 — 并运行其单元测试。重新接入时会跳过未更改的块（内容 SHA-1），将缓存的重新 embedding 时间缩短至远不及一分钟。 ### 运行 ChromaDB ``` docker run -d --name chroma -p 8000:8000 \ -v chroma_data:/chroma/chroma ghcr.io/chroma-core/chroma:latest ``` 通过 `CHROMA_HOST`（默认为 `localhost`）和 `CHROMA_PORT` (`8000`) 连接。 ### 对仓库进行 Embed ``` python scripts/embed_repo.py /path/to/repo python scripts/embed_repo.py /path/to/repo --query "validate user password" ``` 首次运行会将约 130MB 的 embedding 模型下载到 `~/.cache/huggingface`。 ### 测试 ``` python -m pytest backend/tests/test_vector_db.py -q ``` 默认离线运行（模拟 embedder + 模拟集合）。设置 `CHROMA_INTEGRATION=1` 并连接活跃的 Chroma，即可运行真实模型 + 语义搜索往返测试。 ## 阶段 4 — 风险检测引擎 在图谱上运行架构异味规则作为 Cypher 查询，并按严重程度对发现结果进行排序。每个发现为 `{type, severity, target, file, details}`；结果可作为 `SecurityIssue` 节点持久化回数据库，以便于查询。 | 规则 | 严重程度 | 有当前数据支持吗？ | |---|---|---| | God object（方法过多的类） | 高 | ✅ | | Dead code（无传入调用的函数） | 中 | ✅ | | 高圈复杂度 | 中 | ✅ | | 过长方法 | 低 | ✅ | | 散弹式修改（被多个文件调用） | 高 | ✅ | | 深层继承 | 中 | ✅ | | 循环依赖 | 高 | ⏳ 部分 — 见下文 | **`IMPORTS` / `INHERITS_FROM` 现已填充。** 解析器会提取基类（仓库内类之间的 `INHERITS_FROM`）和导入语句（`File-[:IMPORTS]->Module` 顶点）。这使得深层继承规则生效，并为继承的自然语言→Cypher 示例提供了支持。 **遗留缺口：** 循环依赖检测需要*模块到模块*的导入边，但目前的导入建模为 `File→Module`（外部模块名），这不会形成模块循环 — 因此在导入解析为仓库内模块之前，该规则将保持为空。死代码规则也会标记合法的入口点（图中没有调用者） — 在添加入口点标注之前，这是预期内的行为。 ### 运行 ``` python scripts/detect_risks.py # list risks python scripts/detect_risks.py --severity high # filter python scripts/detect_risks.py --persist # also write SecurityIssue nodes ``` ### 测试 ``` python -m pytest backend/tests/test_risk_detection.py -q ``` 默认离线运行（返回预设行的模拟图谱客户端）。设置 `ARCADEDB_INTEGRATION=1` 并连接活跃的图谱，即可针对实时数据运行。 ## 阶段 5 — 变更影响 / 爆炸半径 从文件（或单个实体）向后遍历 `CALLS` 图谱，找出受变更传递影响的每一个函数，按跳数距离（直接调用与传递调用，上限为 50）对它们进行分桶，并根据受影响的数量对爆炸半径进行 `low → critical` 的评分。 `find_affected_tests` 已实现，但需要 `COVERED_BY` 边（测试覆盖率接入，尚未构建） — 在此之前它将返回 `[]`。 ### 运行 ``` python scripts/blast_radius.py path/to/file.py --depth 5 ``` ### 测试 ``` python -m pytest backend/tests/test_impact.py -q ``` 默认离线运行。设置 `ARCADEDB_INTEGRATION=1` 并连接活跃的图谱，即可进行实时冒烟测试。 ## 阶段 6 — 混合检索 + LLM 问答 通过将每个问题路由到正确的后端来回答自然语言问题： - **结构化**问题（“谁调用了 X”，“什么依赖于 Y”） → LLM 将其翻译为 Cypher（few-shot）并在图谱上运行它们。 - **语义**问题（“在哪里处理”） → 向量相似度与 BM25 词法搜索融合（倒数排名融合）。 - 报错或未返回任何内容的结构化查询**回退**到语义搜索。 `QueryEngine.answer()` 是唯一的入口点（由阶段 7 使用）：它会进行检索，生成带有引用的回答，并返回 `{strategy, answer, sources, cypher}`。LLM 是一个可注入的协议（`OllamaClient`，默认模型 `qwen2.5-coder:7b`），因此整个流水线都可以通过模拟对象进行离线单元测试。 ### 运行 ``` python scripts/ask.py "what functions call validate_user?" ``` 需要已填充的图谱 + 向量存储 + 正在运行的 Ollama (`ollama pull qwen2.5-coder:7b`)。 通过共享的 `LLM_BASE_URL`（默认为 `http://localhost:11434`）和 `LLM_MODEL`（默认为 `qwen2.5-coder:7b`）进行配置；`OLLAMA_URL` / `OLLAMA_MODEL` 仍可作为备选项接受。基础 URL 上的尾部 `/v1` 会自动处理（无论哪种方式）。 ### 测试 ``` python -m pytest backend/tests/test_retrieval.py -q ``` 默认离线运行（模拟 LLM/图谱/向量）。设置 `OLLAMA_INTEGRATION=1` 并连接正在运行的 Ollama，即可进行实时的生成测试。 ## 阶段 7 — FastAPI 后端 将每一层连接在一起的 REST API — 在 `/api/v1` 下有 27 个带版本控制的路由器，受 JWT / OAuth / API 密钥以及 RBAC 和速率限制保护。应用**在没有后端运行的情况下启动** — `/health` 始终有效，在 ArcadeDB/Chroma/Ollama 启动之前，数据端点会返回明确的 `503`（而不是崩溃）。 核心端点： | 方法 | 路径 | 用途 | |---|---|---| | GET | `/health`, `/api/v1/health/services` | 存活状态 + 各服务健康状态 | | POST | `/api/v1/ingest` | 开始接入（`{repo_url}` 或 `{repo_path}`） | | POST | `/api/v1/ingest/upload` | 接入上传的归档文件（基于 MinIO） | | GET | `/api/v1/ingest/{job_id}` | 接入任务状态（通过 `/ingest` 列出） | | GET | `/api/v1/query?q=` | 自然语言问答 | | GET | `/api/v1/impact/{file_path}?depth=` | 爆炸半径 | | GET | `/api/v1/risks?severity=` | 架构风险 | | GET | `/api/v1/stats` | 代码库统计 | 核心之外：`auth`（JWT/OAuth/API 密钥），`conversations`，`summarize`，`review`，`security`（SAST），`refactor`，`hotspots`，`docgen`（wiki），`export`（CSV/XLSX），`report`（HTML/PDF），`graphify`（图谱可视化数据），`repos`/`files`，`comments`，`activity`，`notifications`，`llm-config` 和 `audit`。包含请求/响应示例的完整 API 概览请见 [docs/api-guide.md](docs/api-guide.md)，或访问 `/docs` 上的实时 Swagger UI。 接入作为持久化的 Celery 任务运行（Redis 作为 broker，在测试/开发中使用进程内 eager 模式），并带有任务状态存储（`queued → running[cloning→parsing→building_graph→embedding→risk_analysis] → complete/failed`）；过期任务会被自动清理。 ### 运行 ``` cd backend && uvicorn main:app --reload --port 8100 ``` Swagger UI 位于 http://localhost:8100/docs。（`run.sh` / `run.ps1` 会从 8100 开始选择第一个可用的端口，并相应地配置前端。） ### 测试 ``` python -m pytest backend/tests/test_api.py -q ``` 由 Starlette 的 `TestClient` 驱动；断言应用能否启动，列出所有路由，验证输入，并在没有后端时优雅降级为 `503`。 ## 阶段 8 — Next.js 前端 Next.js 14（App Router, TypeScript, Tailwind）与阶段 7 的 API 进行通信。每个页面都连接到真实的端点，并在后端宕机时优雅降级： | 路由 | 用途 | |---|---| | `/` | 接入仓库（克隆或上传）+ 实时任务状态轮询 | | `/dashboard` | 代码库统计、风险概览、热点热力图 | | `/query` | 带有引用来源的自然语言问答 | | `/graph` | 交互式知识图谱可视化 | | `/impact` | 文件/实体的爆炸半径力导向图 | | `/risks` | 架构风险，按严重程度过滤 | | `/security` | SAST 发现仪表盘 | | `/refactor` | 重构建议 | | `/wiki` | 自动生成的各模块文档 | | `/reports` | 叙述性 HTML/PDF 报告 + CSV/XLSX 导出 | | `/notifications` | 实时通知流 | | `/settings` | LLM 提供商/模型配置，API 密钥 | | `/login` | 邮箱/密码 + 可选的 GitHub OAuth | 图谱使用 `react-force-graph-2d` 渲染（动态导入，仅限客户端）。 ### 设置与运行 ``` cd frontend npm install cp .env.local.example .env.local # NEXT_PUBLIC_API_URL=http://localhost:8100 npm run dev # http://localhost:3000 ``` `npm run build` 已验证通过（所有路由编译成功，类型检查无误，ESLint 清洁）。 ## 阶段 9 — Docker 与部署 通过 [`docker-compose.yml`](docker-compose.yml) 实现的一键式技术栈，由 `./run.sh --docker`（Windows：`.\run.ps1 -Docker`）或直接使用 `docker compose up -d --build` 启动： | 服务 | 镜像 | 宿主机端口 | |---|---|---| | db (Postgres) | `postgres:16-alpine` | 5433 → 5432 | | redis | `redis:7-alpine` | 6380 → 6379 | | minio | `minio/minio` | 9000 (API) / 9001 (控制台) | | arcadedb | `arcadedata/arcadedb` | 2480 / 2424 | | chroma | `ghcr.io/chroma-core/chroma` | 8003 → 8000 | | backend | 由 `backend/Dockerfile` 构建 | 8001 → 8000 | | worker (Celery) | 与后端镜像相同 | — | | frontend | 由 `frontend/Dockerfile` 构建 | 3100 → 3000 | 服务主机名/凭证通过环境变量注入到后端和 worker 中（可通过根目录下的 `.env` 覆盖 — 参见 [`.env.example`](.env.example)）；前端的 `NEXT_PUBLIC_API_URL` 在构建时被硬编码为映射到宿主机的后端端口（`http://localhost:8001`）。后端在 `worker` 服务上运行 Celery 接入任务，并将克隆的仓库检点持久化存储在 `backend_data` 卷中，以便它们在容器重建后依然存在。 ``` ./run.sh --docker # build + start everything (Windows: .\run.ps1 -Docker) docker compose up -d --build # equivalent, any OS docker compose ps # status docker compose logs -f # logs docker compose down # stop (keeps data volumes) docker compose down -v # stop and WIPE all data volumes ``` 想要在免费层级上部署？请参见 [docs/deployment-free-tier.md](docs/deployment-free-tier.md)。 ## 测试 ``` python -m pytest -q # 256 passed, 5 skipped ``` 测试套件**默认离线运行**：图谱、向量和 LLM 客户端都是可注入的，并被模拟对象替换，因此运行它不需要任何服务（也不需要安装 torch/chromadb）。可选的集成测试通过 `ARCADEDB_INTEGRATION=1`、`CHROMA_INTEGRATION=1` 和 `OLLAMA_INTEGRATION=1` 针对实时服务运行。测试使用密封的一次性 SQLite 数据库和 eager Celery — 不会触碰真实数据。 ## 文档 | 文档 | 内容 | |---|---| | [docs/architecture.md](docs/architecture.md) | 系统图表，组件演练 | | [docs/api-guide.md](docs/api-guide.md) | 完整的 REST API 参考与示例 | | [docs/adr/](docs/adr/) | 5 个 ADR：零预算本地优先、选择 Chroma 而不是 Qdrant、选择 ArcadeDB 而不是 Neo4j、Ollama、FastAPI-Users | | [docs/deployment-free-tier.md](docs/deployment-free-tier.md) | 免费层级托管指南 | | [docs/index.md](docs/index.md) | 文档入口 | | [PROJECT_PLAN.md](PROJECT_PLAN.md) | 单一事实来源：技术栈、功能矩阵、路线图 | | [CHANGELOG.md](CHANGELOG.md) | 版本化发布说明（`v1.0.0`–`v1.4.0` 及未发布版本） | | [CONTRIBUTING.md](CONTRIBUTING.md) | 分支/提交规范，PR 核对清单 | ## 持续集成 [`.github/workflows/ci.yml`](.github/workflows/ci.yml) 在每次 push/PR 时运行三个作业：`lint`（针对 `backend` + `scripts` 运行 Ruff），`backend-tests`（针对 `backend/tests` 运行 pytest），以及 `frontend-build`（`npm ci && npm run lint && npm run build`）。

标签：AI风险缓解, MITM代理, 代码分析, 代码问答, 凭证管理, 技术栈:Next.js, 技术栈:Python, 搜索引擎查询, 架构风险检测, 测试用例, 请求拦截, 逆向工具, 静态应用安全测试