用 AI 把代码仓库读薄：CodeBase-CR

开源地址：hanxiaoge08/CodeBase-CR: 基于LLM与代码库索引的AI代码仓库分析平台与Code Review工具

当我们接手一个不熟悉的代码仓库，最难的往往不是“能不能跑起来”，而是“怎么迅速读懂、评审到位、文档不再滞后”。CodeBase-CR 正是为此而生——一个面向工程团队的 AI 代码仓库分析与 PR 审查平台，帮助你把复杂仓库“读薄”，把知识“记住”，把审查“做准”。

本文是项目的首次开源发布介绍，涵盖能力全览、架构与流程、技术亮点、快速上手、实战示例、可观测性与路线图等，欢迎 star、试用与共建。

我们在解决什么问题

新成员上手慢：仓库背景不清晰、结构复杂、文档散落或过期。
评审成本高：PR 上下文零散、历史讨论难检索、规范难落地。
知识沉淀弱：项目知识难以结构化、不可检索、不可复用。

CodeBase-CR 提供什么

智能仓库分析与文档生成（Wiki）：克隆/解压仓库→生成文件树→LLM 生成目录与技术文档→Kafka 异步出文档→索引到记忆库（Mem0）→前端可视化。
PR 自动审查（Review）：接收 GitHub Webhook→拉取 Diff→结合 RAG（向量检索）找上下文→LLM 审查→自动评论。
记忆与知识中台（Memory）：文档/代码索引与检索，对外提供标准化 REST API，被 Wiki/Review 通过 OpenFeign/HTTP 消费。
现代化前端（React）：任务管理、目录树与 Markdown/Mermaid 渲染、进度与结果一站式展示。

模块划分：CodeBase-Wiki、CodeBase-Review、CodeBase-Memory、CodeBaseAI-frontend。

架构与核心流程

仓库分析/文档生成

graph TD A[创建任务] --> B{输入类型} B -->|Git URL| C[克隆仓库] B -->|ZIP 文件| D[解压文件] C --> E[生成文件树] D --> E E --> F[LLM 生成目录] F --> G[保存目录入库] G --> H[Kafka 异步生成文档] H --> I[更新文档内容/状态] I --> J[索引至 Mem0] J --> K[前端展示]

PR 自动审查

sequenceDiagram participant GH as GitHub participant R as Review Service participant M as Memory/RAG participant L as LLM GH->>R: Webhook PR Event R->>R: 验签/解析 R->>GH: 拉取 Diff R->>M: RAG 检索上下文 M-->>R: 返回相关文档/代码 R->>L: 提交审查 Prompt + 上下文 L-->>R: 生成审查意见 R->>GH: 自动评论

Kafka 重试/死信机制

graph LR P[Producer] --> Q[主队列 wiki-doc-generation] Q -- 失败 --> R[重试队列 wiki-doc-retry] R -- 超过 3 次 --> D[死信队列 wiki-doc-dlq] Q -->|成功| C[消费者处理成功] R -->|成功| C

技术亮点（为什么它有效）

Kafka 异步文档生成：主/重试/死信三段式容错；并发可控（信号量/线程池），大仓库也能稳态处理；AKHQ 帮你一眼看穿队列状态。
Mem0 + RAG 的上下文增强：文档与代码双向索引（含 metadata），PR 审查时按标题/描述/改动路径/新增代码组合查询，显著提升相关性与可解释性。
OpenFeign 微服务解耦：Wiki/Review 通过 HTTP 消费 Memory 中台 API，配合降级/超时策略，服务可独立启动与横向扩展。
Tool Calling 监控：AOP 切面拦截 @Tool 方法，记录参数/耗时/结果/错误，定位问题与性能瓶颈更直接。
缺陷治理经验沉淀：如 FileSystemTool 重复读取的 ThreadLocal 污染与缓存去重修复、任务删除一致性校验等，保障长期稳定运行。

快速上手（最短路径）

环境准备

Java 21+、Maven 3.8+
Node.js 16+、npm 8+
Docker（用于 Kafka，本地可选）

设置环境变量（二选一模型）

# 模型（阿里云/或 OpenAI）
export DASHSCOPE_API_KEY=your-dashscope-api-key
export OPENAI_API_KEY=your-openai-api-key

# GitHub PR 审查
export GITHUB_TOKEN=your-github-token
export GITHUB_WEBHOOK_SECRET=your-webhook-secret

# Mem0 记忆服务（可选）
export MEM0_API_URL=http://localhost:8100

启动 Kafka（可选但推荐）

cd CodeBase-Wiki
docker-compose up -d

启动后端（以 Wiki 为例）

mvn clean install
mvn spring-boot:run -pl CodeBase-Wiki

启动前端

cd CodeBaseAI-frontend
npm install
npm start

前端默认 API Base（可在 src/api/task.js 修改）：http://localhost:8085/api。

实战：从创建任务到可视化文档

1) 通过前端创建分析任务

进入管理后台 /admin/tasks → 新建任务
支持两种来源：Git 仓库 / ZIP 文件，提交后进入 Kafka 异步处理

2) 通过 API 创建（可用于 CI/脚本）

默认前端后端网关前缀：/api

# 从 Git 创建
curl -X POST "http://localhost:8085/api/task/create/git" \
  -H "Content-Type: application/json" \
  -d '{
    "projectName": "awesome-repo",
    "projectUrl": "https://github.com/org/repo",
    "branch": "main",
    "userName": "",
    "password": ""
  }'

# 分页查询任务
curl -X POST "http://localhost:8085/api/task/listPage" \
  -H "Content-Type: application/json" \
  -d '{ "pageIndex": 1, "pageSize": 10 }'

# 获取任务详情
curl "http://localhost:8085/api/task/detail?taskId=YOUR_TASK_ID"

# 获取目录树
curl "http://localhost:8085/api/task/catalogue/tree?taskId=YOUR_TASK_ID"

3) 可视化查看

首页 / 展示已完成任务卡片，点击进入 /repo/:taskId
左侧目录树，右侧 Markdown 内容（代码高亮与 Mermaid 图）

实战：PR 自动审查

在 GitHub 仓库设置 Webhook：
- Payload URL：/api/v1/github/events
- Content-Type：application/json
- Secret：同环境变量 GITHUB_WEBHOOK_SECRET
- Events：Pull requests
触发 PR 后：
- 服务拉取 Diff→RAG 检索上下文→LLM 审查→自动回帖
- 结合 Mem0 的文档/代码索引，提高建议的精准度与一致性

可观测性与运维建议

Tool 调用监控：开启 project.wiki.monitor.tool-calling=true，统计耗时/失败率；生产环境降低日志细度并启用滚动策略。
Kafka 观测：AKHQ 观察积压、重试/死信比例；配置 SLA（处理时延/成功率）。
指标与日志：Micrometer + Prometheus + Grafana 采集核心指标；ELK 聚合日志；对关键路径设置告警阈值。
容量与可靠性：限制并发、分批/流式处理大文件，确保内存稳态；为 Mem0/LLM 调用设置重试与退避。

路线图（Roadmap 摘要）

Mem0 深化：语义+关键词+AST 的混合检索；记忆生命周期/去重；多模态（图片/图表）；项目感知助手；缓存/批处理/分片性能优化。
微服务完善：服务发现（Consul/Eureka）、API 网关（Spring Cloud Gateway）、配置中心（Spring Cloud Config）、链路追踪（Sleuth/Zipkin）。
质量与体验：端到端集成/性能/安全测试；易用性打磨与企业级能力（权限/审计）。

参与共建

仓库与文档：阅读根 README 与 issues/CodeBase-CR项目梳理.md（蓝皮书）。
提交指南：Fork → 分支 → 提交 PR；提交信息与注释建议使用中文。
问题反馈：欢迎通过 Issues 提交问题/需求/建议。
许可证：MIT。

如果你也在为“让代码仓库更易懂、PR 更专业、知识更长久”而努力，欢迎加入我们一起把这件事做好。