scheidydude/codeindex
GitHub: scheidydude/codeindex
一款为 AI 辅助开发设计的时序代码知识图谱工具，通过爆炸半径评分、符号搜索和 Git 历史感知的依赖分析帮助开发者理解代码变更影响。
Stars: 260 | Forks: 35
# codeindex
**时序代码知识图谱**，具备爆炸半径影响评分、语义符号搜索以及具备 Git 历史感知的依赖分析功能 —— 专为 AI 辅助开发设计。
将其指向任何项目 —— Python、JavaScript/TypeScript、Go、Ruby、Rust、Java、PHP 等 —— 即可获得：
- 位于 `/.codeindex/index.db` 的持久化 **SQLite 图存储** —— 支持增量、可查询、时序
- 直接写入您仓库的 `codeindex.json` 依赖索引（为向后兼容而保留）
- 文件级别的爆炸半径评分（如果更改此文件，会有多少文件受影响），包括**历史时间点查询**
- `symbolindex.json` 符号映射表，让 AI 无需扫描每个文件即可找到任何函数/类
- 基于符号的**混合语义搜索**：自然语言查询与关键词及图扩展相融合
- **Git 历史回填** —— 通过提交历史构建时序图，无需触碰工作区
- 十种消费数据的方式：CLI、Markdown 报告、MCP server（10 种工具）、pre-commit hook、CLAUDE.md 注入
- 交互式可视化 UI（2D/3D 图谱、依赖矩阵、矩形树图）
无需构建步骤。无需 npm。零必需的运行时依赖 —— SQLite 属于标准库。
## 安装
```
pip install codeindex
```
或从源码安装：
```
git clone https://github.com/scheidydude/codeindex
cd codeindex
pip install -e .
```
## 快速开始
```
# 构建依赖索引（同时写入 .codeindex/index.db）
codeindex analyze ./myapp
# 构建符号索引（记录每个函数和类的位置）
codeindex symbols ./myapp
# 在修改文件之前查看其 blast radius
codeindex impact src/auth.py
# 使用自然语言搜索符号（无需 embedding 端点 — 回退至 FTS）
codeindex search "validate auth token"
# 查看自发布 tag 以来的更改
codeindex changed-since v1.2.0
# 启动可视化 UI
codeindex serve --viz --repo ./myapp
open http://localhost:8080
```
## 命令
### `codeindex analyze`
```
codeindex analyze [REPO_PATH] [--output PATH] [--watch]
```
分析仓库并将 `codeindex.json` 写入仓库根目录。自动检测 12 种以上的语言。
| 标志 | 默认值 | 描述 |
|------|---------|-------------|
| `REPO_PATH` | `.` | 仓库根目录路径 |
| `--output` | `/codeindex.json` | 覆盖输出路径 |
| `--watch` | 关闭 | 文件更改时重新索引（需要 `watchdog`） |
### `codeindex symbols`
```
codeindex symbols [REPO_PATH] [--output PATH] [--inline] [--index PATH]
[--claude-md] [--claude-md-path PATH] [--all-symbols]
```
构建符号索引 —— 将每个函数、类、结构和类型映射到其确切文件和行号的表。让 AI 工具（和人类）只需一次查找即可找到任何符号，而无需扫描整个仓库。
**模式：**
| 标志 | 描述 |
|------|-------------|
| _(无)_ | 写入独立的 `symbolindex.json` |
| `--inline` | 将符号嵌入到 `codeindex.json` 中的每个节点内 |
| `--claude-md` | 将压缩后的符号摘要追加到 `CLAUDE.md` |
`--inline` 和 `--claude-md` 可以在单次运行中组合使用。
**选项：**
| 标志 | 默认值 | 描述 |
|------|---------|-------------|
| `REPO_PATH` | `.` | 仓库根目录路径 |
| `--output` | `/symbolindex.json` | 输出路径（独立模式） |
| `--index` | 自动发现 | `codeindex.json` 的路径（用于 `--inline`） |
| `--claude-md-path` | `/CLAUDE.md` | 覆盖 CLAUDE.md 路径 |
| `--all-symbols` | 关闭 | 在 CLAUDE.md 中包含未导出的符号（默认：仅导出的符号） |
**示例：**
```
# 独立符号索引
codeindex symbols ./myapp
# 嵌入到 codeindex.json 中（一个文件用于 blast radius + 符号）
codeindex symbols ./myapp --inline
# 编写 CLAUDE.md 摘要，以便 Claude Code 自动加载符号
codeindex symbols ./myapp --claude-md
# 同时执行全部三项
codeindex symbols ./myapp --inline --claude-md
# 在代码更改时重新生成
codeindex symbols ./myapp --inline --claude-md
```
**重要性：** Claude Code 和其他 AI 工具通常会扫描每个文件以查找函数定义。借助符号索引，Claude 可以加载一个文件，进行 O(1) 查找，并仅打开相关文件 —— 在符号定位任务上减少 60–90% 的 token 消耗。
**CLAUDE.md 注入**是可选的，因为它会增加每次提示的基础上下文大小。当您的工作流程中符号查找非常频繁时使用它；对于简单的任务，如果开销大于收益，则跳过它。
### `codeindex impact`
```
codeindex impact FILE [--index PATH] [--out FILE] [--json] [--as-of REF]
```
显示特定文件的爆炸半径影响：直接依赖、传递依赖、爆炸评分和风险等级。
```
Impact: src/auth.py
Blast Score: 8.5 (2 direct · 7 transitive) [HIGH]
Direct dependents (2)
src/api.py
src/middleware.py
Transitive dependents (5 additional)
src/main.py ← src/api.py
src/app.py ← src/middleware.py
...
Risk: HIGH — affects 7/42 files (16.7% of codebase)
```
**爆炸评分公式：** `direct + (0.5 × transitive)`
| 标志 | 描述 |
|------|-------------|
| `--index PATH` | `codeindex.json` 的路径（如果省略则自动发现） |
| `--out FILE` | 将 Markdown 报告写入此文件 |
| `--json` | 输出原始 JSON |
| `--as-of REF` | 计算历史提交/引用处的爆炸半径，而不是 HEAD |
### `codeindex search`
```
codeindex search QUERY [--k N] [--as-of REF] [--db PATH] [--json]
```
混合语义 + 关键词 + 图符号搜索。无需知道确切的名称即可找到相关的函数和类。
**与倒数排名融合 (RRF) 结合的检索信号：**
1. **语义 KNN** —— embedding 相似度（需要 `codeindex[semantic]` + 已配置的 endpoint）
2. **FTS5 关键词** —— 对符号名称、签名和文档字符串进行全文搜索
3. **图扩展** —— 来自依赖/被依赖文件的结构相邻符号
优雅降级：如果未配置 embedding endpoint，则回退到 FTS + 图（无需崩溃，无需配置）。
```
# 关键词 + 图搜索（无需配置 embedding）
codeindex search "validate auth token"
# 完全语义搜索（需要 CODEINDEX_EMBEDDING_* 环境变量）
CODEINDEX_EMBEDDING_ENDPOINT=http://localhost:11434 \
CODEINDEX_EMBEDDING_MODEL=nomic-embed-text \
CODEINDEX_EMBEDDING_DIMS=768 \
codeindex search "validate auth token"
# 历史搜索 — 在发布 tag 时可见的符号
codeindex search "token validation" --as-of v1.2.0
```
| 标志 | 默认值 | 描述 |
|------|---------|-------------|
| `QUERY` | — | 自然语言或关键词查询 |
| `--k N` | `10` | 返回结果的数量 |
| `--as-of REF` | HEAD | 限制为在此提交/引用处可见的符号 |
| `--db PATH` | 自动发现 | `.codeindex/index.db` 的路径 |
| `--json` | 关闭 | 输出原始 JSON |
### `codeindex history`
```
codeindex history [REPO_PATH] [--since REF] [--max-commits N] [--json]
```
从 git 历史记录中回填时序图数据 —— 无需任何工作区检出。通过 `git cat-file --batch` 读取 blob，并在每个文件、边和符号上标记 `first_seen_commit` / `last_seen_commit`。
在初始设置后运行一次此命令，即可启用跨完整历史记录的 `--as-of` 查询。
```
# 回填最多 1000 个 commit（默认）
codeindex history .
# 仅回填最近的历史记录
codeindex history . --since v1.0.0 --max-commits 200
```
| 标志 | 默认值 | 描述 |
|------|---------|-------------|
| `REPO_PATH` | `.` | 仓库根目录路径 |
| `--since REF` | — | 仅处理此日期/引用之后的提交 |
| `--max-commits N` | `1000` | 最多处理的提交数 |
| `--json` | 关闭 | 输出 JSON 摘要 |
### `codeindex changed-since`
```
codeindex changed-since REF [--repo PATH] [--db PATH] [--json]
```
列出自某个提交、分支或标签以来添加或删除的文件和依赖边。
```
$ codeindex changed-since v1.2.0
Changes since v1.2.0:
Added files (2):
+ src/payments/stripe.py
+ src/payments/webhook.py
Removed edges (1):
- src/api.py → src/auth_v1.py [imports]
```
| 标志 | 默认值 | 描述 |
|------|---------|-------------|
| `REF` | — | 要比较的提交哈希、分支或标签 |
| `--repo PATH` | `.` | 仓库根目录（用于 git 操作） |
| `--db PATH` | 自动发现 | `.codeindex/index.db` 的路径 |
| `--json` | 关闭 | 输出原始 JSON |
### `codeindex db`
```
codeindex db status [--db PATH] [--json]
codeindex db migrate [--db PATH]
```
管理位于 `/.codeindex/index.db` 的 SQLite 存储。
```
$ codeindex db status
schema_version : 2
repo_root : /Users/alice/myapp
last_indexed_commit : a3f2e1c8
active_files : 142
active_edges : 387
active_symbols : 1204
embedding_model : nomic-embed-text
embedding_dims : 768
vec_symbols : enabled
```
`db migrate` 会自动应用任何待处理的 schema 迁移（在每次 `codeindex analyze` 时也会运行）。
### `codeindex serve`
```
codeindex serve --viz [--repo PATH] [--port PORT] [--watch]
codeindex serve --mcp
```
`--viz` 在您的浏览器中启动交互式可视化 UI（5 种模式：2D 力导向图、3D 网络图、依赖矩阵、矩形树图、基础设施图）。
`--mcp` 启动一个 stdio MCP server，将 codeindex 工具直接提供给 Claude 和其他 MCP 客户端使用。
**MCP 工具：**
| 工具 | 描述 |
|------|-------------|
| `analyze_repo` | 构建或刷新依赖索引 |
| `get_impact` | 某个文件的爆炸半径报告 |
| `get_dependencies` | 某个文件的 imports + imported-by |
| `get_high_blast_files` | 爆炸评分阈值以上的所有文件 |
| `build_symbol_index` | 构建或刷新符号索引 |
| `lookup_symbol` | 查找任何函数/类/类型的定义位置（文件 + 行号） |
| `semantic_search` | 混合语义 + 关键词 + 图符号搜索；在没有 embedding 时优雅降级 |
| `temporal_impact` | 历史提交/引用处的爆炸半径（`as_of` 参数） |
| `graph_query` | 某个文件的 k-hop 依赖邻域（`dependents`/`dependencies`/`both`） |
| `changed_since` | 自某个提交/引用以来添加或删除的文件和边 |
**Claude Code MCP 配置** (`.claude/settings.json`)：
```
{
"mcpServers": {
"codeindex": {
"command": "codeindex",
"args": ["serve", "--mcp"]
}
}
}
```
### `codeindex lookup`
```
codeindex lookup SYMBOL [--index PATH] [--json]
```
查找函数、类、结构或其他符号的定义位置。查询 SQLite 数据库（与 `search` 数据源相同），如果不存在数据库，则回退到 `symbolindex.json`。打印定义周围 5 行的源代码上下文。
```
$ codeindex lookup compute_blast_radius
codeindex/impact.py:6 compute_blast_radius (function)
> 6 | def compute_blast_radius(nodes: list[dict], links: list[dict]) -> dict[str, dict]:
7 | """..."""
8 | ...
$ codeindex lookup AuthService
src/auth.py:44 AuthService (class) methods: login, logout, refresh
> 44 | class AuthService:
45 | def login(self, ...):
```
如果未找到某个符号，它很可能是第三方导入项 —— 只有在仓库中定义的符号才会被索引。
| 标志 | 描述 |
|------|-------------|
| `--index PATH` | `symbolindex.json` 回退路径（如果省略则自动发现） |
| `--json` | 输出原始 JSON |
### `codeindex dependencies`
```
codeindex dependencies FILE [--index PATH] [--json]
```
显示文件导入了什么以及什么导入了它，以及它的爆炸评分。
```
$ codeindex dependencies src/auth.py
File: src/auth.py (blast score: 8.5)
Imports (3):
src/db.py
src/config.py
src/utils.py
Imported by (2):
src/api.py
src/middleware.py
```
| 标志 | 描述 |
|------|-------------|
| `--index PATH` | `codeindex.json` 的路径（如果省略则自动发现） |
| `--json` | 输出原始 JSON |
### `codeindex high-blast`
列出所有爆炸评分超过阈值的文件，按评分降序排列。用于在重构前识别风险最高的文件非常有用。
```
codeindex high-blast [--threshold N] [--index PATH] [--json]
```
`d` = 直接依赖 · `t` = 传递依赖
| 标志 | 默认值 | 描述 |
|------|---------|-------------|
| `--threshold N` | `5` | 包含在内的最小爆炸评分 |
| `--index PATH` | 自动发现 | `codeindex.json` 的路径 |
| `--json` | 关闭 | 输出原始 JSON |
### `codeindex symbol-blast`
某个文件中每个导出项的爆炸半径。列出每个导出符号以及按名称引用它的导入者的确切文件路径和数量。当某个文件导出许多符号而您只需要修改其中一个时非常有用 —— 它让您确认其他符号是安全的。
```
$ codeindex high-blast --threshold 5
Files with blast score ≥ 5.0 (3 found)
13.0 src/db.py (12d / 2t)
8.5 src/auth.py (3d / 7t)
5.5 src/config.py (5d / 1t)
```
`userSchema` 触及 8 个路由；`legacySchema` 仅触及 1 个 —— 可以安全地单独更改。
| 标志 | 描述 |
|------|-------------|
| `FILE` | 文件相对于仓库的路径（例如 `lib/db/schema.ts`） |
| `--json` | 输出包含每个符号完整 `used_by` 数组的原始 JSON |
### `codeindex install-hook`
安装一个 git pre-commit hook，当暂存文件的爆炸评分超过阈值时会发出警告。
| 标志 | 默认值 | 描述 |
|------|---------|-------------|
| `--threshold N` | `10` | 触发警告的最低爆炸评分 |
| `--strict` | 关闭 | 阻止提交而不仅仅是警告 |
| `--remove` | — | 卸载 hook |
## 在另一个仓库中使用 codeindex 与 Claude
三种工作流程，按自动化程度排序。
### 工作流程 1 — MCP server（推荐用于活跃编码）
Claude 会获取它自动调用的符号查找、依赖和影响工具。无需额外提示。
**一次性设置：**
```
codeindex symbol-blast FILE [--json]
```
使用 `claude mcp add` 向 Claude Code 注册 MCP server。使用 `--scope project` 将其限制在此仓库，或使用 `--scope global` 在任何地方使用它：
```
$ codeindex symbol-blast lib/db/schema.ts
Symbol-level blast radius: lib/db/schema.ts
5 exported symbol(s), 12 importer(s)
userSchema (const, line 8) → 8 user(s)
app/api/users/route.ts
app/api/profile/route.ts
...
legacySchema (const, line 42) → 1 user(s)
scripts/migrate.ts
sessionSchema (const, line 67) → 3 user(s)
...
```
使用 `which codeindex` 找到您的 codeindex 二进制文件的完整路径，然后将其替换到上面。
```
codeindex install-hook [--repo PATH] [--threshold N] [--strict] [--remove]
```
验证其是否注册成功：
```
cd /your/other/repo
codeindex analyze .
codeindex symbols .
```
Claude 现在在每次会话中都有全部 10 种 MCP 工具可用。当它需要查找 `processPayment` 时，它会调用 `lookup_symbol("processPayment")` 并一次性获取 `src/billing.py:142` —— 无需扫描文件。当它需要在不知道确切名称的情况下查找验证身份验证 token 的代码时，它会调用 `semantic_search("validate auth token")`。
**保持索引最新：**
```
# 项目级作用域（推荐 — 存储在 .claude/settings.json 中）
claude mcp add --scope project codeindex -- /path/to/codeindex serve --mcp
# 全局作用域（在所有 repo 中可用）
claude mcp add --scope global codeindex -- /path/to/codeindex serve --mcp
```
### 工作流程 2 — CLAUDE.md 注入（最适合您经常访问的仓库）
符号表被嵌入在 `CLAUDE.md` 中，因此它会自动加载到每次会话中 —— 完全不需要工具调用。
```
# 使用 conda install 的示例
claude mcp add --scope project codeindex -- /opt/homebrew/Caskroom/miniforge/base/bin/codeindex serve --mcp
```
这会将一个 `symbolindex` 代码块 upsert 到 `CLAUDE.md` 中。该仓库中的每次 Claude Code 会话都会在启动时加载它。Claude 可以仅凭文，在零工具调用的情况下回答“`X` 定义在哪里？”。
**权衡：** 根据仓库大小，会为每次提示增加约 500–2000 个 token。对于符号查找频繁的仓库非常值得；对于您主要编写新代码的仓库则跳过它。
**保持最新：**
```
claude mcp list
```
### 工作流程 3 — 混合（大型仓库）
对于 `--claude-md` 部分可能会太大的大型仓库，请使用 MCP server 进行查找，并在 `CLAUDE.md` 中添加简短提示，以便 Claude 首先使用该工具：
```
# 在文件更改时自动重建（在 terminal 中保持运行）
codeindex symbols . --watch
```
然后添加到 `CLAUDE.md`：
```
cd /your/other/repo
codeindex symbols . --claude-md
```
这几乎不消耗 token，但能让 Claude 优先使用索引，而不是默认使用 grep。
### 供人类使用的 CLI 快速参考
通过 MCP 提供的相同数据也可以直接通过终端访问：
```
# 在重大 refactor 之后重新运行
codeindex analyze . && codeindex symbols . --claude-md
```
### 选择哪种工作流程
| 场景 | 工作流程 |
|-----------|----------|
| 日常使用的仓库，活跃的功能开发 | MCP server |
| 中型仓库，频繁的符号查找 | CLAUDE.md 注入 |
| 大型仓库（1000+ 个文件） | MCP server + 简短的 CLAUDE.md 提示 |
| 在不熟悉的仓库中进行快速的一次性操作 | `codeindex symbols . --claude-md`，使用后删除 |
| 终端 / 脚本使用 | CLI 命令 (`lookup`, `dependencies`, `high-blast`) |
## 支持的语言
| 语言 | 依赖分析 | 符号提取 |
|----------|--------------------|--------------------|
| Python | AST imports，类型检测 | 函数、类、方法（AST 精确） |
| JavaScript / TypeScript | ES modules，`require()`，框架检测 | 导出的函数、类、类型、枚举、常量 |
| Vue | SFC `