内容
# RepoScope
**仓库智能引擎**，适用于大型语言模型（LLMs）和智能代理。
RepoScope 将 GitHub 或本地仓库转化为结构化的、基于证据的理解：
```
仓库
→ 抽象语法树（AST）+ 增量索引
→ 知识图谱（KnowledgeGraph） （结构）
→ 流追踪器（FlowTracer） （行为）
→ 架构分析器（ArchitectureAnalyzer） （设计）
→ MCP / HTTP API
```
它**不是**编码代理、聊天产品或自动拉取请求（PR）工具。它是为模型提供可靠的代码库世界模型的底层架构。
---
## 功能
| 功能 | 问题 | 输出 |
|---|---|---|
| **知识图谱** | 代码如何组织？ | 文件 / 类 / 函数 / 方法 + 导入/调用关系 |
| **流追踪器** | 一个流程如何运行？ | 基于证据的调用路径，包含文件和行号 + 角色 |
| **架构分析器** | 系统如何组织？ | 模块、模式、配置文件、耦合度发现 |
支持的栈（仍可用）：
- 混合检索增强生成（RAG）：稠密 + BM25 + 可选重排 / Qdrant
- LangGraph 研究工作流（`摘要` / `访谈` / `重构`）与引用审查
- FastAPI + MCP 工具表面，用于代理
---
## 产品边界
**范围内**
- 结构化的仓库理解
- 基于证据的发现（路径、符号、行号）
- 库 + MCP + 代理/工具的 HTTP API
**范围内（按设计）**
- 编码代理 / 自动代码编辑
- 聊天界面 / 多轮探索会话
- 无限代理编排
---
## 快速开始
```powershell
python -m venv .venv
.venv\Scripts\activate
pip install -e ".[dev]"
pytest -q
```
可选的检索模型/基础设施：
```powershell
pip install -e ".[dev,retrieval]"
docker compose up -d
# REPOSCOPE_VECTOR_BACKEND=qdrant
# REPOSCOPE_DATABASE_URL=postgresql://reposcope:reposcope@localhost:5432/reposcope
```
---
## 核心 API
### 知识图谱（摄入工件）
```python
from app.db import InMemoryFilesRepository, InMemoryReposRepository
from app.ingestion import IngestionPipeline
from app.intelligence import load_knowledge_graph
pipe = IngestionPipeline(
files_repo=InMemoryFilesRepository(),
repos_repo=InMemoryReposRepository(),
)
result = pipe.run("tests/fixtures/sample_repo")
kg = pipe.load_knowledge_graph(result.repo_id)
print(kg.stats.node_counts, kg.stats.edge_counts)
```
每个仓库的工件：`chunks.json`、`graph.json`、`definitions.json`、`knowledge_graph.json`。
### 流追踪
```python
from app.intelligence.flow_tracer import FlowTracer
from app.intelligence.flow_format import format_flow_markdown
trace = FlowTracer().trace(kg, "用户登录流程是什么？")
print(format_flow_markdown(trace))
```
HTTP:
```http
POST /trace
{ "repo_source": "<git-url-or-path>", "question": "用户登录流程是什么？" }
```
### 架构智能
```python
from app.intelligence.architecture import analyze_architecture_markdown
report, md = analyze_architecture_markdown(kg, workspace_root="path/to/repo")
print(report.primary_pattern, len(report.findings))
print(md)
```
HTTP:
```http
POST /architecture
{ "repo_source": "<git-url-or-path>" }
```
模块是具有诚实类型（`功能` / `层` / `技术` / `未知`）和 `boundary_confidence` 的路径集群 - 并非每个文件夹都被视为域模块。
---
## MCP 工具
```powershell
python -m app.mcp.server
```
| 工具 | 目的 |
|---|---|
| `get_repo_summary` | 基于引用的摘要（LangGraph 工作流） |
| `query_dependencies` | 调用者 / 被调用者 / 导入 |
| `suggest_refactor` | 具有证据的重构建议 |
| `trace_flow` | 流追踪（调用路径理解） |
| `analyze_architecture` | 模块 / 模式 / 耦合 / 配置文件 |
设置：[`docs/mcp_setup.md`](docs/mcp_setup.md)
还包括：
```powershell
uvicorn app.api.main:app --reload
# GET /health
# POST /analyze/stream
# POST /trace
# POST /architecture
```
如果没有 `REPOSCOPE_DATABASE_URL`，审计将在内存中进行，并在重启时丢失 - 在 `meta.warnings` 中显示。
---
## 研究工作流（可选）
LangGraph 报告式分析路径：
`route → repo_parse → planner → retrieve → analyze → review → finalize`
```powershell
copy .env.example .env
# REPOSCOPE_LLM_API_KEY=...
```
```python
from app.workflow import WorkflowInput, create_default_runner
runner = create_default_runner(use_hash_embedder=True)
result = runner.run(WorkflowInput(
question="Summarize the architecture",
repo_source="tests/fixtures/sample_repo",
intent_hint="summary",
))
print(result.report_markdown)
```
在需要结构化智能用于代理时，优先使用 **FlowTracer / ArchitectureAnalyzer**；在需要带有审查循环的叙述报告时，使用工作流。
---
## 检索和评估
- 混合 RAG：稠密 + BM25，RRF 默认，可选交叉编码器重排
- 配置：`config/retrieval.yaml`
- 评估工具：[`eval/README.md`](eval/README.md)
```powershell
python -m eval.run_retrieval_eval --compare-modes --hash-embedder
```
---
## 测试
```powershell
pytest -q
```
包括 `tests/fixtures/` 下的 Spring 和 FastAPI 登录流程的固定测试。
---
## 思维模型
```
RepoScope
|
仓库智能引擎
/ | \
知识图谱 流追踪器 架构分析器
结构 行为 设计
```
这是预期的核心。根据实际的代理/产品需求进行扩展，而不是通过转向聊天或自动编码来扩展。
