@mars167/git-ai

v2.4.3

Published

6 days ago

A git-compatible CLI with AI indexing/search and an MCP server.

0High
0Medium
0Low

git ai semantic-search mcp code-search code-understanding vector-search graph-database cli code-indexing knowledge-graph

git-ai

简体中文 | English

🚀 快速安装

AI Agent 技能安装 (Claude Code, Cursor, Windsurf 等)

npx skills add mars167/git-ai-cli/skills/git-ai-code-search

CLI 工具安装

npm install -g @mars167/git-ai

为代码库添加语义层，让 AI 从"读代码"进化到"懂代码"

代码的语义，应该像代码本身一样版本化、可追溯

git-ai 是一个本地代码理解工具，通过 DSR（确定性语义记录）和 Hyper RAG，为代码库构建可追溯的语义层，让 AI Agent 和开发者真正理解代码的演进与关系。

✨ 为什么选择 git-ai？

🔗 Hyper RAG：融合向量检索 + 图检索 + DSR，多维度语义理解
📜 版本化语义：每个提交都有语义快照，历史变更清晰可溯
🔄 随时可用：索引随代码走，checkout 即可用，无需重建
🤖 AI 原生：MCP Server 让 Claude、Trae 等 Agent 都能深度理解你的代码
🔒 完全本地：代码永不离开你的机器，安全无忧
⚡ 全流程支持：从开发到 Review 到重构，索引贯穿整个生命周期
📊 极速性能：10k 文件索引 < 30 秒，搜索响应 < 100ms

✨ 核心能力

1️⃣ 语义搜索

用自然语言找到代码，无需记忆文件名或函数名：

git-ai ai semantic "用户认证逻辑"
git-ai ai semantic "数据库连接池配置"
git-ai ai semantic "错误处理中间件"

2️⃣ 符号关系分析

理解代码之间的调用关系：

# 查找函数调用者
git-ai ai graph callers authenticateUser

# 查找函数调用的其他函数
git-ai ai graph callees authenticateUser

# 追踪完整调用链
git-ai ai graph chain authenticateUser --max-depth 3

3️⃣ 变更历史追溯

通过 DSR 追踪符号的历史演变：

# 查看函数的历史变更
git-ai ai dsr query symbol-evolution authenticateUser --limit 50

# 查看某个提交的完整语义快照
git-ai ai dsr context

4️⃣ 跨语言支持

支持多种主流编程语言：

| 语言 | 文件后缀 | |------|----------| | JavaScript | .js, .jsx | | TypeScript | .ts, .tsx | | Java | .java | | Python | .py | | Go | .go | | Rust | .rs | | C | .c, .h | | Markdown | .md, .mdx | | YAML | .yml, .yaml |

💡 设计理念

git-ai 不只是一个搜索工具，而是代码库的"语义时间线"：

DSR（Deterministic Semantic Record）

每个提交对应一份不可变的语义快照，记录当时的代码结构、符号关系、设计意图。代码的语义应该像代码本身一样版本化——可追溯、可比对、可演进。

Hyper RAG

融合多种检索方式，让理解更深入：

向量检索：语义相似度匹配
图检索：调用关系、继承关系分析
DSR 检索：历史演变追溯

去中心化语义

索引随代码走，不依赖中央服务器。checkout、branch、tag 都能立即使用一致的语义索引。

Server 模式

MCP Server 让任何 AI Agent 都能调用索引，实现真正的 AI 辅助开发。

🎯 使用场景

场景 1：新人快速理解大型项目

"刚加入团队，面对 10 万行代码，从哪里开始？"

# 1. 获取项目全局视图
git-ai ai repo-map --max-files 20

# 2. 搜索核心业务逻辑
git-ai ai semantic "订单处理流程"

# 3. 追踪关键函数调用链
git-ai ai graph chain processOrder --max-depth 5

从设计到开发，语义索引始终如一

场景 2：重构前的代码影响分析

"要重构这个函数，会影响哪些地方？"

# 查找所有调用者
git-ai ai graph callers deprecatedFunction

# 追踪历史变更，了解设计意图
git-ai ai dsr query symbol-evolution deprecatedFunction --all

DSR 追溯历史变更，理解设计意图

场景 3：Bug 定位和根因分析

"用户报告了一个错误，但不知道问题出在哪里"

# 搜索相关错误处理代码
git-ai ai semantic "用户登录失败处理"

# 查看错误传播路径
git-ai ai graph chain handleLoginError --direction upstream

全流程索引，快速定位问题根源

场景 4：AI Agent 辅助开发

"让 Claude Desktop 帮我理解这个项目"

在 Claude Desktop 中配置 git-ai MCP Server 后，你可以直接对话：

"帮我分析这个项目的架构，找出所有与支付相关的代码，并解释它们之间的关系"

Claude 会自动调用 git-ai 的工具，为你提供深入的分析。让 AI 从"读代码"进化到"懂代码"

🏗️ 系统架构

graph TB
    A[Git 仓库] -->|每次提交| B["DSR (Deterministic Semantic Record)"]
    B --> C[.git-ai/dsr/<commit>.json<br/>语义快照]
    C -->|索引重建| D[LanceDB 向量库]
    C -->|索引重建| E[CozoDB 图数据库]
    D --> F[MCP Server]
    E --> F
    F -->|工具调用| G["AI Agent<br/>Claude Desktop / Trae"]
    F -->|命令行| H[开发者]
    C -->|跨版本| I{"语义时间线<br/>可追溯、可比对、可演进"}
    
    style B fill:#e1f5ff
    style C fill:#e8f5e9
    style D fill:#fff4e1
    style E fill:#fff4e1
    style F fill:#e8f5e9
    style G fill:#f3e5f5
    style I fill:#fce4ec

核心组件：

DSR (Deterministic Semantic Record)：按提交存储的不可变语义快照，版本化语义
LanceDB + SQ8：高性能向量数据库，支持语义搜索
CozoDB：图数据库，支持 AST 级关系查询
MCP Server：标准协议接口，供 AI Agent 调用

📊 与其他工具对比

| 特性 | git-ai | GitHub Code Search | Sourcegraph | |------|--------|-------------------|-------------| | 本地运行 | ✅ | ❌ | ❌ | | AST 级分析 | ✅ | ❌ | ✅ | | 版本化语义 | ✅ | ❌ | ❌ | | 变更历史追溯 | ✅ | ❌ | ❌ | | AI Agent 集成 | ✅ | ❌ | ❌ | | 免费开源 | ✅ | ❌ | ❌ | | 语义搜索 | ✅ | ✅ | ✅ | | 调用链分析 | ✅ | ❌ | ✅ |

🚀 快速开始

1. 安装

npm install -g @mars167/git-ai

2. 初始化仓库

cd your-project
git-ai ai index --overwrite

3. 立即体验

# 用自然语言搜索代码
git-ai ai semantic "用户认证逻辑"

# 查看函数调用关系
git-ai ai graph callers authenticateUser

实际输出示例：

[
  {
    "file": "src/auth/service.ts",
    "line": 45,
    "symbol": "authenticateUser",
    "context": "async function authenticateUser(email: string, password: string)"
  },
  {
    "file": "src/controllers/auth.ts", 
    "line": 23,
    "symbol": "loginHandler",
    "context": "const user = await authenticateUser(req.body.email, req.body.password)"
  }
]

就这么简单！3 步上手，立即开始深度理解你的代码库。

从此，索引不再是"一次性产物"，而是随代码演进的"语义资产"。

⚙️ 配置

文件过滤

git-ai 遵循项目的忽略文件配置来控制哪些文件会被索引：

`.gitignore` - 标准 Git 忽略规则

默认情况下，匹配 .gitignore 中模式的文件会被排除在索引之外。

`.aiignore` - AI 专属排除规则（最高优先级）

在仓库根目录创建 .aiignore 文件，用于排除特定文件的索引，这些文件应该被 git-ai 忽略但不一定要被 Git 忽略：

# .aiignore 示例
test-fixtures/**
*.generated.ts
docs/api-reference/**

`.git-ai/include.txt` - 强制包含（覆盖 `.gitignore`）

有时您需要索引生成的代码或在 .gitignore 中但对代码理解很重要的文件。创建 .git-ai/include.txt 来强制索引特定模式：

# .git-ai/include.txt 示例
# 包含生成的 API 客户端
generated/api/**

# 包含特定的构建产物，其中包含重要的类型定义
dist/types/**

# 包含特定被忽略目录中的代码
vendor/important-lib/**

优先级顺序（从高到低）：

.aiignore - 显式排除规则始终生效
.git-ai/include.txt - 强制包含模式覆盖 .gitignore
.gitignore - 标准 Git 忽略模式

支持的模式语法：

** - 匹配任意数量的目录
* - 匹配目录内的任意字符
directory/ - 匹配整个目录（自动转换为 directory/**）
file.ts - 匹配特定文件
以 # 开头的行为注释

配置示例：

# .gitignore
dist/
generated/
*.log

# .git-ai/include.txt
generated/api/**
generated/types/**

# .aiignore (覆盖所有规则)
generated/test-data/**

此配置下：

✅ generated/api/client.ts - 被索引（通过 include.txt 包含）
✅ generated/types/models.ts - 被索引（通过 include.txt 包含）
❌ generated/test-data/mock.ts - 不被索引（.aiignore 优先级最高）
❌ dist/bundle.js - 不被索引（在 .gitignore 中，不在 include.txt 中）

🛠️ 故障排除

Windows 安装问题

git-ai 使用 CozoDB 来实现 AST 图查询功能。在 Windows 上，如果遇到 cozo-node 相关的安装错误，可以尝试以下解决方案：

方案一：使用 Gitee 镜像（推荐国内用户使用）

npm install -g @mars167/git-ai --cozo_node_prebuilt_binary_host_mirror=https://gitee.com/cozodb/cozo-lib-nodejs/releases/download/

方案二：配置 npm 代理

如果你在公司防火墙或代理后面：

npm config set proxy http://your-proxy:port
npm config set https-proxy http://your-proxy:port
npm install -g @mars167/git-ai

方案三：手动下载二进制文件

从 cozo-lib-nodejs releases 下载 Windows 二进制文件
找到 6-win32-x64.tar.gz（64 位 Windows）
解压到 node_modules/cozo-node/native/6/ 目录

验证安装：

git-ai ai status --path .

如果看到 graph 相关功能正常工作，说明安装成功。

其他原生依赖

git-ai 还使用了以下原生包，可能需要类似的故障排除：

onnxruntime-node - 用于语义向量生成
tree-sitter - 用于代码解析
@lancedb/lancedb - 用于向量数据库

大多数问题可以通过确保稳定的网络连接或使用镜像来解决。

🤖 AI Agent 集成

git-ai 提供标准的 MCP Server，可与以下 AI Agent 无缝集成：

Claude Desktop：最流行的本地 AI 编程助手
Cursor：AI 驱动的代码编辑器
Trae：强大的 AI 驱动 IDE
Continue.dev：VS Code AI 插件

单客户端模式（stdio，默认）

在 ~/.claude/claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "git-ai": {
      "command": "git-ai",
      "args": ["ai", "serve"]
    }
  }
}

多客户端模式（HTTP）

当你需要多个 AI Agent 同时连接时（如同时使用 Claude Code 和 Cursor）：

# 启动 HTTP 服务（支持多客户端）
git-ai ai serve --http --port 3000

然后配置每个 Agent 连接到 http://localhost:3000/mcp。

HTTP 模式特性：

支持多个并发会话
健康检查端点：http://localhost:3000/health
自动管理会话生命周期
通过 mcp-session-id 响应头实现 Session 持久化
完善的错误处理机制，返回正确的 HTTP 状态码
支持 SIGTERM/SIGINT 信号，实现优雅关闭
可选无状态模式，用于负载均衡场景：--stateless

然后重启 Claude Desktop，即可开始对话：

"帮我分析这个项目的架构，找出所有与支付相关的代码"

Claude 会自动调用 git-ai 的工具，为你提供深入的分析。

Agent Skills & Rules

我们提供了精心设计的 Agent 模版，帮助 AI 更好地使用 git-ai：

Skill 模版：指导 Agent 如何使用工具
Rule 模版：约束 Agent 的行为

Skills/Rules 文档（Markdown/YAML）会被纳入语义索引，便于通过 semantic_search 检索 MCP 指南。

一键安装到你的项目：

git-ai ai agent install

📚 文档

🔧 高级功能

Git Hooks 自动化

自动在提交前重建索引，push 前打包校验：

git-ai ai hooks install

pre-commit：自动增量索引 + 打包
pre-push：校验索引归档
post-checkout：自动解包索引

Git LFS 集成

推荐使用 Git LFS 管理索引归档：

git lfs track ".git-ai/lancedb.tar.gz"
git-ai ai pack --lfs

🤝 贡献

欢迎贡献代码、报告问题或提出建议！

📄 License

MIT

让 AI 从"读代码"进化到"懂代码" ⭐ Star us on GitHub!