repo-intelligence

name	repo-intelligence
description	仓库智能：基于代码库上下文、提交历史、架构文档和依赖关系做检索增强分析，回答代码库问题、评估变更影响、还原架构意图。当用户说'仓库智能'、'代码库问答'、'Repository Intelligence'、'代码库理解'、'架构分析'、'提交历史分析'、'这个改动会影响哪些地方'、'这段代码为什么这么写'时触发。核心特点：多源索引、检索增强、影响链路可视化、与记忆系统联动。

来源: 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 在需要时能找到最相关的代码、历史和意图，并把这些信息组织成你可以决策的形式。