内容
# gitatlas
**存在于 Git 历史记录中的代码图 —— 只需构建一次，在每次提交时保持正确，由团队中的每个人、代理和机器人共享。**
`gitatlas` 将您的存储库索引到符号图（函数、类、方法、调用、继承、类型用法、导入），通过 Git 钩子使该图与提交保持同步，并通过标准 [模型上下文协议](https://modelcontextprotocol.io) 服务器将其提供给任何支持 MCP 的 AI 工具 — Claude Code、Cursor、Codex、Antigravity、Windsurf、Copilot。
```
┌─────────────┐ tree-sitter ┌──────────────────┐ MCP (stdio) ┌──────────────┐
│ 您的存储库 │ ───────────────► │ .gitatlas/ │ ────────────────► │ Claude Code │
│ │ │ graph.db │ │ Cursor │
│ Git 提交 │ ── post-commit ─►│ (SQLite, 本地) │ │ Codex, ... │
└─────────────┘ 增量更新 └──────────────────┘ └──────────────┘
```
## 为什么选择 Git 原生而非文件监视器？
大多数代码智能工具都会监视您的编辑器会话：操作系统文件监视器、去抖动计时器、连接时协调。这些方法在您的笔记本电脑上有效 — 但在其他地方无效。`gitatlas` 将所有内容都绑定到 Git：图是提交的纯函数，由钩子更新，通过内容哈希键控。这样您就可以获得监视器无法实现的功能：
- **CI 和云代理。** 文件监视器在 CI 和云编码代理中毫无用处。基于提交的图可以在 CI 中构建一次，通过 SHA 缓存，并由每个队友和机器人拉取。
- **在分支切换和变基过程中保持正确** — 内容哈希键控意味着检出只是缓存查找，而不是重新索引。
- **历史记录** （路线图）：因为图是提交的函数，所以“两版之前 X 的调用者是什么样子的？”是一个可以回答的问题。基于监视器的工具有没有过去。
以及一些实用基础：
- **零基础设施。** `.gitatlas/` 中只有一个 SQLite 文件，位于 `.git/` 旁边。无需守护进程，无需 Docker，无需服务。
- **快速。** 多服务存储库的完整索引时间约为 150ms；无操作增量更新时间约为 50ms。
- **语言：** TypeScript、JavaScript、JSX/TSX、Java、Python — 通过 tree-sitter WASM 语法分析，因此安装永远不需要 C++ 工具链。
- **尊重 .gitignore。** 发现使用 `git ls-files`；构建输出永远不会污染图。
## 设计上节省标记
AI 代理通过 grep 和读取整个文件来回答存储库问题。在一个真实的存储库（Java Spring 微服务 + Chrome 扩展）中，回答 8 个典型的开发人员问题所花费的代价是：
| 指标 | 使用 gitatlas | grep + 读取文件 |
|---|---|---|
| 代理必须读取的上下文标记 | **3,241** | 57,882 |
| 工具调用 | **8** | 23 |
| 搜索失败 | **0** | 1 |
这是一个 **17.9 倍的上下文减少** — 直接转换为成本、延迟和释放的模型注意力。方法如下：
- 真实任务嵌入标识 — “处理 `checkIsFse` 返回 false 的情况”。`find_context` 将它们检测为 **锚点**，并返回定义以及 **每个** 引用站点周围的 ±4 行窗口，而不是整个封闭函数（在代表性查询中，从 ~945 到 ~354 个标记，具有 *更好* 的覆盖率）。
- **同义词锚点**：开发人员通过将标识符分成单词来同义替换标识符，因此符号通过子标记覆盖率匹配 — “FSE 检查”找到 `checkIsFse`，“混杂性配置检查”找到 `isConfigured`。无需嵌入，无需模型下载。
- 列表结果按文件分组并折叠重复前缀；长列表以 `+N 更多` 开头；通用任务词（“处理”、“情况”、“错误”）被停用。
- `repo_map` 将代理定位在不熟悉的存储库中 — 大多数中心符号（PageRank），仅签名 — 仅需几百个标记。
## 安装
```bash
npm install -g gitatlas
```
或从源代码：
```bash
git clone https://github.com/bajpayeeritik/gitatlas.git
cd gitatlas && npm install && npm run build && npm link
```
需要 Node.js ≥ 20。
## 快速入门
```bash
cd your-repo
gitatlas index # 构建图 → .gitatlas/graph.db
gitatlas install-hook # 每次提交/合并/分支切换时自动更新
gitatlas stats # 查看已索引的内容
echo ".gitatlas/" >> .gitignore
```
## 连接您的 AI 工具
**Claude Code** — 存储库根目录中的 `.mcp.json`：
```json
{
"mcpServers": {
"gitatlas": {
"command": "gitatlas",
"args": ["serve", "--root", "."]
}
}
}
```
**Cursor** — `.cursor/mcp.json` 中具有相同的 JSON 形状。
**Codex CLI** — `~/.codex/config.toml`：
```toml
[mcp_servers.gitatlas]
command = "gitatlas"
args = ["serve", "--root", "."]
```
任何其他 stdio MCP 客户端都可以使用相同的 `command` + `args`。
### MCP 工具
| 工具 | 它能回答什么 |
|---|---|
| `repo_map` | 一次性定位：存储库中最中心的符号，按文件分组，仅显示签名 |
| `find_context` | 任务最相关的代码 — 标识符（及其同义词）被锚定为定义 + 使用窗口；其余按词法匹配 × PageRank 在标记预算下排名 |
| `usages` | 符号的定义以及每个引用站点周围的 ±4 行窗口 — 更改 X 在所有地方使用的最便宜的完整答案 |
| `who_calls` / `what_it_calls` | 符号的反向/正向依赖 |
| `impact_of_change` | 编辑文件（直接 + 1 跳依赖）的爆炸半径 |
| `file_outline` | 文件中的所有符号及其行范围 — 结构无需阅读 |
| `get_symbol` / `search_symbols` | 精确和模糊查找 |
| `graph_stats` / `reindex` | 新鲜度、大小、强制刷新 |
### CLI
每个工具也是一个 CLI 命令 — 无需 AI 客户端即可使用：
```bash
gitatlas symbol AnalysisService # 定义在哪里？
gitatlas callers UserCodingData # 谁使用它？
gitatlas callees AnalysisController # 它依赖于什么？
gitatlas usages isConfigured # 定义 + 每个用法站点的代码窗口
gitatlas outline src/service/Foo.java # 文件结构无需阅读
gitatlas impact src/service/Foo.java # 如果我更改它，会有什么影响？
gitatlas repo-map --budget 1200 # 整个存储库定位图
gitatlas context "重试机制如何工作" # 在标记预算下排名的片段
```
所有命令都接受 `--root <path>` （默认为当前目录）。
## 工作原理
1. **解析** — tree-sitter（WASM）提取定义、引用（调用、`extends`、`implements`、类型用法 — 包括 Spring 风格的 DI）和导入。
2. **存储** — SQLite（WAL），按内容哈希键控；删除文件会级联；提取器版本戳会自动使过时的解析无效。
3. **链接** — 引用在存储库中解析为定义，生成边表。
4. **更新** — Git 钩子（`post-commit`、`post-merge`、`post-checkout`）仅重新解析更改的文件。现有的钩子被追加，而不会被覆盖。
5. **服务** — 结构化查询直接来自 SQLite；排名将词法匹配与 PageRank 中心性融合。
## 比较，诚实地说
如果您想要具有捆绑二进制文件和文件监视器的 30 种语言的编辑器会话索引，[CodeGraph](https://github.com/colbymchenry/codegraph) 非常出色且更成熟。`gitatlas` 适用于问题的 Git 形状：一个提交固定的图，CI、云代理和整个团队可以共享，令牌成本作为一等公民。小型存储库，小型工具，刻意简化的内部实现。
## 限制（诚实的限制）
- **基于名称的链接。** 引用通过标识符名称解析，而不是完全类型解析 — 相同名称的符号会收到边。SCIP 精度解析是首要的路线图项目。
- 动态调度、反射和元编程是不可见的，就像每个静态索引一样。
- 接口上的 `who_calls` 返回实现者和用户（边的种类已存储但尚未可过滤）。
## 路线图
- [ ] PR 爆炸半径 GitHub Action（影响分析作为 PR 评论）
- [ ] 按 SHA 缓存的 CI 图：构建一次，分发给团队
- [ ] 基于 SCIP/LSP 的精确符号解析
- [ ] 图时间旅行：查询任意提交时的图；语义变更日志
- [ ] 嵌入融合以实现真正同义词查询（同义词已经通过子标记工作）
- [ ] 更多语言（Go、Rust、C#、Ruby）
## 贡献
欢迎提出问题和 PR。`src/indexer/`（tree-sitter 提取）、`src/graph/`（SQLite 存储、排名、格式化）、`src/mcp/`（服务器）、`src/cli.ts`。`npm run build` 然后 `node dist/cli.js index --root <some-repo>` 是整个开发循环。
## 许可证
MIT
