RepoGraph
RepoGraph是一个本地存储库智能工具，用于构建和维护代码库的图形支持模型，用于代码理解、架构检查、影响分析和人工智能辅助的上下文收集。
RepoGraph首先是静态的，但是 repograph sync --full 是规范的全功率工作流程。完全同步总是首先重建静态图。当 auto_dynamic_analysis 启用后，RepoGraph会为当前仓库解析最安全的运行时路径：连接到符合条件的实时跟踪Python服务器，启动托管跟踪Python服务器、运行跟踪测试，或在新执行不可用时合并现有的运行时和覆盖率输入。 repograph sync --static-only 当您希望在没有自动运行时执行或覆盖合并的情况下进行重建时，它仍然是显式的纯静态路径。
已验证的测试基线：已签入的套件目前包含超过1.24k的测试，最新的完整套件运行为绿色。
RepoGraph涵盖了什么
- 构建一个包含文件、文件夹、符号、导入、调用、回调注册、继承链接、变量流和类型引用提示的存储库范围图
- 对可能的切入点进行评分，并为重要的执行流程组装路径文件
- 对死代码进行分类，检测重复符号，显示事件拓扑，并找到异步任务生成站点
- 显示实现关系、构造函数依赖关系、社区和git协同更改耦合的接口
- 生成模块摘要、配置注册表、不变量、文档引用警告、测试可达性映射和完整报告
- 运行需求侧分析器，用于私有表面访问、配置边界读取、数据库快捷方式、UI边界路径、架构一致性、类角色、配置流、模块信号和分解信号
- 将运行时覆盖、覆盖率覆盖、观察到的运行时发现和运行时质量诊断合并到同一存储库视图中
运行时和动态分析
RepoGraph的运行时感知完全同步是当前代码库中的一流功能。完整同步路径可以：
- 检测repo范围内的实时跟踪Python服务器，并在CLI中附加之前进行提示
- 从配置的设置启动托管跟踪Python服务器，等待准备就绪，并驱动场景URL或场景驱动程序命令
- 自动检测跟踪测试命令并在repo解释器下运行它
- 合并现有
.repograph/runtime/*.jsonl和coverage.json跳过新执行或不可用时的输入 - 将运行时来源、附加决策、场景活动、回退行为和覆盖准备状态持久化到
health.json,status,summary，以及report
静态分析仍然是基线。运行时间和覆盖率证据增强了图表；它们不会取代它。
语言和框架覆盖范围
- 解析器插件目前涵盖Python、JavaScript和TypeScript
- 框架适配器目前包括Flask、FastAPI、React和Next.js
- HTML文件也会被扫描以查找本地 `` 链接，以便浏览器加载的JavaScript可以连接回图中
- Shell、HTML和CSS文件仍然作为存储库文件进行索引，即使它们不是完整符号图的一部分，也会出现在结构输出中
快速开始
Repo本地引导程序：
./setup.sh
./run.sh sync --full
./run.sh summary这条路径为您提供了最安全的解释器行为，因为 ./setup.sh 准备本地回购 .venv，以及 ./run.sh 总是喜欢 .venv/bin/python 当存在时。
如果您更喜欢直接使用CLI：
python -m pip install -e ".[dev,community]"
repograph sync --full
repograph summary
repograph report如果你想要最广泛的经过验证的本地环境和最好的机会 与当前验证的基线相匹配 1.24k通过测试，更喜欢 这 全本地工作站 层改为：
python -m pip install -e ".[dev,community,mcp,templates,embeddings]"如果你打算运行可选的Pyright质量门，也可以安装Node.js。
要求：Python 3.11以上。 repograph init 是可选的；它只会创建 .repograph/ 提前布局。
典型工作流程
正常的工作流程是：
- 跑
repograph sync --full以重建图，并让RepoGraph为仓库解析最佳可用运行时路径。 - 使用
summary,report,modules,pathway,node,query，以及impact从不同角度检查存储库。 - 重新运行
sync随着代码库的变化，或使用watch在积极发展的过程中。
常规探索会话看起来像：
repograph sync --full
repograph summary
repograph modules --issues
repograph pathway list
repograph impact
repograph report如果您明确希望进行纯静态重建：
repograph sync --static-only接口
命令行界面
CLI是本地工作最广泛的日常界面。
- 存储库生命周期：
init,sync,status,watch,clean - 探索：
summary,report,modules,node,query,impact - 架构：
config,config-registry,invariants,test-map,events,interfaces,deps - 路径：
pathway list,pathway show,pathway update - 运行时诊断：
trace install,trace collect,trace report,trace clear - 集成和诊断：
mcp,export,doctor,test
完整命令和标志参考： docs/CLI_REFERENCE.md
repograph query 是CLI中更丰富的混合搜索界面。当嵌入可用时，它结合了关键字搜索、模糊名称匹配、路径匹配和可选语义排名。
Python API
Python API可用于脚本、测试和服务集成：
from repograph.surfaces.api import RepoGraph
with RepoGraph("/path/to/repo") as rg:
rg.sync(full=True)
print(rg.pathways())
print(rg.dead_code())
print(rg.full_report())RepoGraph 是共享空间上的薄立面 RepoGraphService，因此API、CLI和MCP服务器都位于同一个实现层上。 RepoGraph.sync(full=True) 在以下情况下，遵循与CLI相同的运行时感知编排路径 auto_dynamic_analysis 已启用，API调用方可以使用覆盖每个调用的附加行为 attach_policy.
表面细节： docs/SURFACES.md
MCP服务器
RepoGraph还可以为AI工具展示精心策划的MCP表面：
repograph mcp /path/to/repoMCP表面有意比CLI和Python API更窄。它侧重于读取/查询工作流、可观察性访问和设置检查，而不是公开每个操作命令。
交互菜单
如果你想使用引导终端而不是记忆命令：
repograph menu该菜单为主要工作流提供命令浏览、解释和运行预设。
架构概述
RepoGraph围绕一个共享服务层和一个写入图存储的管道进行组织。
RepoGraphService是CLI、Python API和MCP服务器使用的中心实现。- 核心管道阶段遍历存储库，构建文件和文件夹节点，解析支持的语言，解析导入和调用，检测回调注册，跟踪继承和变量，并通过以下步骤将图增量写入Kuzu
GraphStore. run_full_pipeline_with_runtime_overlay()在完整的静态重建路径之上添加运行时规划和执行。- 插件挂钩然后在同一存储上运行更高级的分析器、证据生产者、动态分析器和导出器。
- 健康、信任、运行时分析和就绪元数据被持久化，因此
status,summary,report，MCP消费者可以知道实际支持结果的证据是什么。
在实践中，这意味着该工具具有干净的分割：
- 管道构建并更新图形
- 运行时层在可用时用观察到的证据对其进行扩展
- 服务层通过不同的面向用户的表面公开结果
- 插件在不改变核心入口点的情况下扩展了分析和导出行为
文档地图
- 从这里开始：
docs/README.md - 设置和安装层：
docs/SETUP.md - CLI标志和示例：
docs/CLI_REFERENCE.md - API、CLI和MCP边界：
docs/SURFACES.md - 管道和运行时编排：
docs/PIPELINE.md - 精度和已知限值：
docs/ACCURACY.md - 配置所有权和生成的工件策略：
docs/CONFIG_HYGIENE.md - 贡献工作流程：
CONTRIBUTING.md - 测试布局和标记：
tests/README.md
许可证
RepoGraph的许可证为 GNU AGPL v3.0。参见 LICENSE.
______________________________________________________________________
开发说明
RepoGraph仍在积极开发中，因此贡献者应该期待一些内部细节和接口继续发展。如果文档和代码不一致，请处理当前代码， health.jsonCLI帮助，以及 status / summary / report 输出作为真理的来源。