gaoqiongxie 来源: Repository Intelligence 社区实践 + RAG over Codebase 研究 + 企业代码库治理经验
发布时间: 2026-08
理念: "让 AI 真正读懂你的代码库，而不是只读你粘贴进去的那几行。"
🧠 Repo Intelligence — 仓库智能
把代码库、提交历史、架构文档、Issue/PR 讨论等多源信息整合成 AI 可检索的知识图谱，实现代码库问答、变更影响分析和架构意图还原。
为什么需要仓库智能
| 问题 | 传统方式 | 仓库智能 |
|---|---|---|
| 新人上手慢 | 靠老员口头传授 + 文档散落各处 | 直接问 AI："用户登录流程涉及哪些模块？" |
| 改一处崩三处 | 靠全局搜索 + 人工推理影响范围 | AI 基于调用链和依赖图给出影响面 |
| 代码为什么这样写 | 翻 git blame、找历史 PR | AI 聚合提交信息、PR 描述、ADR 文档 |
| 上下文不够 | 每次把相关文件贴进对话 | AI 自动检索最相关的代码和文档 |
一句话：仓库智能让 AI 拥有「代码库长期记忆」，不再每次都从零开始理解项目。
核心技术栈
代码解析: tree-sitter / LSP / AST
向量检索: embeddings + vector DB (chroma / pgvector / qdrant)
图关系: 调用图、依赖图、模块图
文档源: README / ADR / OpenSpec / API 文档 / 提交信息
RAG 流程: 索引 → 检索 → 重排 → 生成
信息源分层
| 层级 | 信息源 | 作用 |
|---|---|---|
| 代码层 | 源代码、配置文件、测试文件 | 回答「是什么、在哪里」 |
| 依赖层 | import/call graph、package.json、pom.xml | 回答「影响范围」 |
| 历史层 | git log、blame、PR、Issue | 回答「为什么这样、谁改的」 |
| 文档层 | README、ADR、OpenSpec、Wiki | 回答「设计意图、业务背景」 |
| 运行时层 | 日志、监控、错误追踪 | 回答「线上表现如何」 |
工作流程
Step 1：建立代码库索引
1. 解析目录结构
2. 提取函数/类/接口定义
3. 构建调用关系图
4. 生成代码片段 embedding
5. 关联文档和历史提交
索引粒度建议：
- 函数级：用于精准问答
- 文件级：用于概览和导航
- 模块级：用于架构分析
Step 2：代码库问答
用户用自然语言提问，AI 在索引中检索相关上下文后回答：
用户："用户下单后，库存扣减是在哪个服务里处理的？"
AI:
1. 检索关键词：inventory、deduct、stock、order
2. 找到相关文件：order-service/InventoryClient.java、inventory-service/StockService.java
3. 结合调用图确认：order-service 调用 inventory-service 的 /deduct 接口
4. 返回：流程图 + 关键代码片段 + 涉及文件
Step 3：变更影响分析
给定一个改动，自动分析影响范围：
用户："我改了 UserService 里的 getUserById，会影响哪些地方？"
AI:
1. 找出 UserService.getUserById 的所有调用方
2. 分析调用链上游：Controller → Service → 缓存 → 前端
3. 检查相关测试用例
4. 识别潜在风险：缓存击穿、并发安全、API 契约变更
5. 输出：影响清单 + 建议测试覆盖点
Step 4：架构意图还原
通过聚合多源信息，还原「这段代码为什么这么设计」：
用户："为什么订单表要用雪花 ID，而不是自增 ID？"
AI:
1. 检索 ADR 文档：adr/007-order-id.md
2. 查看相关 PR 讨论：#234 "改用雪花 ID 支持分库分表"
3. 检查代码注释和提交信息
4. 输出：决策背景 + 备选方案 + 当前 trade-off
使用示例
示例 1：快速理解陌生模块
用户：给我讲一下 payment 模块的架构
AI:
1. 读取 payment/ 目录结构
2. 提取核心类：PaymentController、PaymentService、PaymentGateway
3. 构建调用关系图
4. 关联 README 中 payment 相关章节
5. 输出：
- 模块职责一句话
- 核心流程图
- 关键文件索引
- 常见改动点
示例 2：评估重构影响
用户：我想把 OrderService 里的同步调用改成异步，影响大吗？
AI:
1. 定位 OrderService 所有同步调用点
2. 分析调用方：Controller、Scheduler、其他 Service
3. 识别事务边界和回滚逻辑
4. 评估影响：
- 高：支付回调、库存扣减（需要最终一致性）
- 中：订单列表查询（可接受短暂延迟）
- 低：日志记录
5. 给出改造步骤和测试建议
示例 3：新需求影响面分析
用户：要在订单状态里加一个'部分退款'状态，需要改哪些地方？
AI:
1. 检索订单状态机的所有定义和使用点
2. 找到状态转换校验逻辑
3. 检查前端展示、后端校验、数据库枚举
4. 列出测试用例、文档、接口契约的变更点
5. 输出：变更清单 + 顺序建议
快速入口
"给我讲一下 xxx 模块" → 模块架构速览
"这段代码为什么这么写" → 架构意图还原
"改了这里会影响哪些地方" → 变更影响分析
"用户下单流程涉及哪些模块" → 跨模块调用链分析
"这个类是干什么的" → 代码库问答
"新需求要改哪些地方" → 影响面评估
与其他 Skill 的关系
| Skill | 关系 | 协作场景 |
|---|---|---|
| codebase-inventory-audit | 前置 | 先审计代码库结构/债务，再建立智能索引 |
| beads-memory | 上下文继承 | 把代码库上下文持久化到跨会话记忆中 |
| memory-hub | 统一路由 | 把仓库洞察沉淀为项目记忆和经验模式 |
| backend-change-flow | 下游 | 基于影响分析结果执行后端需求变更 |
| frontend-code-review | 下游 | 基于仓库上下文做更准确的前端审查 |
| openspec-sdd | 文档来源 | OpenSpec 作为仓库智能的重要文档层 |
| mcp-builder | 能力输出 | 把仓库智能封装为 MCP Resource 供 AI 调用 |
最佳实践链：
codebase-inventory-audit（了解代码库现状）
→ repo-intelligence（建立智能索引）
→ backend-change-flow / frontend-code-review（基于影响分析做变更）
→ beads-memory + memory-hub（沉淀经验和上下文）
一句话原则
仓库智能不是让 AI 替你读代码，而是让 AI 在需要时能找到最相关的代码、历史和意图，并把这些信息组织成你可以决策的形式。