# Repo Intelligence

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

- Skill: `gaoqiongxie/repo-intelligence` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gaoqiongxie/repo-intelligence`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gaoqiongxie/repo-intelligence/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: gaoqiongxie (https://skillmd.com/u/gaoqiongxie)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gaoqiongxie/repo-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 在需要时能找到最相关的代码、历史和意图，并把这些信息组织成你可以决策的形式。