代码知识图谱 JohnXu22786/codegraph

CodeGraph

代码知识图谱插件：把代码库解析成可查询的索引，让 agent 能回答「谁调用了这个函数」「这个模块依赖什么」这类结构性问题。适合用来快速理解大型代码库，或作为改动前的风险排查工具。

自包含实现：Python 标准库 + SQLite，无强制第三方依赖。提供 CLI、Python API、以及一个 stdio 工具服务器（MCP 风格的 JSON-RPC 2.0），任何插件化 harness 都能以子进程方式加载它。

功能

- 调用关系：callers / callees —— 谁调用了某个函数/方法，它又调用了什么
- 依赖关系：deps / dependents —— 模块或文件导入了什么、被谁导入（区分内部解析与外部依赖）
- 全文搜索：search —— 对符号名、docstring、签名做本地全文检索（SQLite FTS5，无需外部服务）
- 影响面分析：impact —— 传递闭包，列出「这个符号改了会波及谁」
- 增量索引：按内容哈希比对，只重解析变化的文件，删除的文件自动清理
- 导出可视化：export dot|json —— Graphviz DOT / JSON，可直接丢进可视化工具
- 查询缓存：工具服务器对只读查询做 30 秒 TTL 缓存
- 两种解析引擎：tree-sitter（精确，可选安装）与正则扫描器（零依赖兜底），自动选择

工作原理

文件发现（include/exclude/大小上限） → 语法提取（符号、调用点、导入语句） → SQLite 存储（files / symbols / calls / imports + FTS5） → 跨文件解析（调用目标 → 符号，导入 → 文件） → 查询（CLI / 工具服务器 / Python API）

跨文件解析是启发式的，按优先级尝试：同文件精确匹配 → 导入可达文件 → 同包/同模块族 → 全局唯一名。解析失败的调用点保留原始文本并标记为 unresolved（外部代码、标准库、第三方包）。

安装

方式 A：安装为 Python 包（提供 codegraph 命令）
pip install -e .

可选：安装 tree-sitter 语法包，显著提升解析精度
pip install -e ".[treesitter]"

方式 B：不安装，直接从仓库运行（请在仓库根目录执行）。

Windows 命令提示符：

set "PYTHONPATH=%CD%\src"
python -m codegraph --help

Windows PowerShell：

$env:PYTHONPATH = Join-Path (Get-Location) "src"
python -m codegraph --help

Linux/macOS：

export PYTHONPATH="$(pwd)/src"
python -m codegraph --help

支持 Python ≥ 3.10。支持语言：Python、JavaScript、TypeScript、Go、Java、Rust。

快速开始

cd examples/demo

1. 建立索引（增量模式，之后可随时刷新）
python -m codegraph index
indexed 4 files (4 changed, 0 skipped, 0 removed) ... 6 symbols, 7 calls, 3 imports

2. 提问
python -m codegraph callers services.orders.create_order # 谁调用了 create_order → app.run
python -m codegraph callees app.run # app.run 调用了什么
python -m codegraph deps services.billing # billing 模块依赖什么
python -m codegraph dependents services.billing # 谁依赖 billing
python -m codegraph search "coupon" # 全文搜索
python -m codegraph impact services.billing.price # 影响面（传递调用者）
python -m codegraph status # 索引统计
python -m codegraph export dot -o graph.dot # 导出可视化

命令行

| 命令 | 说明 | 示例 |
| init | 在项目根写入 starter 配置 codegraph.json | codegraph init |
| index [--force] | 建立/刷新索引；--force 全量重解析 | codegraph index --force |
| status | 统计：文件/符号/调用/导入数、解析率、语言分布 | codegraph status |
| callers SYMBOL | 直接调用者 | codegraph callers pkg.cart.Cart.add |
| callees SYMBOL | 被调用者 | codegraph callees app.main |
| deps MODULE | 模块依赖 | codegraph deps web/index.ts |
| dependents MODULE | 反向依赖 | codegraph dependents pkg.pricing |
| impact SYMBOL [--depth N] | 传递调用者 | codegraph impact services.billing.price --depth 3 |
| search TEXT | 全文搜索 | codegraph search "shopping cart" |
| export dot\|json [-o FILE] | 导出图 | codegraph export json -o g.json |
| serve | 启动 stdio 工具服务器 | codegraph serve |

通用选项（可放在子命令前或后）：--root 项目根目录、--config 配置文件、--db 覆盖数据库路径、--json 机器可读输出。

工具接口（harness 集成）

codegraph serve 启动一个 stdio 工具服务器：从 stdin 读取换行分隔的 JSON-RPC 2.0 消息，向 stdout 写入响应，日志全部走 stderr。实现了 MCP 所需的握手子集（initialize、tools/list、tools/call、ping），对任何 MCP 客户端或直接对接 JSON-RPC 的 harness 均可用。

8 个工具（plugin.json 中附完整 JSON Schema）：

| 工具 | 参数 | 返回 |
| callers | symbol, limit | 直接调用者列表（符号、文件:行） |
| callees | symbol, limit | 被调用者列表（含 resolved/unresolved 标记） |
| deps | module, limit | 依赖列表（含解析到的文件路径） |
| dependents | module, limit | 反向依赖列表 |
| search | query, limit | 全文检索命中的符号 |
| impact | symbol, depth, limit | 传递调用者（含层级深度） |
| overview | — | 索引统计 |
| reindex | force | 刷新索引（唯一可写工具） |

除 reindex 外均为只读，且带 30 秒 TTL 查询缓存。未建索引时，只读工具返回 isError: true 的错误信息。

最小对话示例：

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"any-harness","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"callers","arguments":{"symbol":"pkg.pricing.price"}}}

在 DSH 中安装

dsh（DeepSeek Harness，插件化 agent harness）通过其内置 MCP 客户端加载本插件，一行命令即可安装：

dsh plugin --profile demo add github:JohnXu22786/codegraph

卸载：

dsh plugin --profile demo remove dsh-codegraph

详见 docs/dsh-integration.md。

本仓库还随附自包含的 Node 桥（index.js + dsh.bundle + cordis.patch.yml）：安装后 8 个 codegraph 工具会直接注册为 codegraph_callers / codegraph_callees / codegraph_deps / codegraph_dependents / codegraph_search / codegraph_impact / codegraph_overview / codegraph_reindex。Bridge 会为每个配置的代码库根目录保持一个常驻 Python stdio server，并向它发送 JSON 请求（默认取 dsh 进程当前目录，可用 root 参数按次覆盖）。
同一根目录的请求会串行执行，每次调用都支持超时和取消；若 server 无法启动则回退到一次性 Python CLI。
尚未建索引时先调用 codegraph_reindex——只读工具在此之前会返回可读的错误提示。

若其他 harness 直接启动 plugin.json 中的 Python 入口，需先将 CodeGraph 安装为 Python 包，或将 PYTHONPATH 指向本插件的 src 目录。DSH Node bridge 会自动设置该路径。

配置文件

codegraph.json（项目根目录，codegraph init 生成；以下为关键字段示例，exclude 默认值共 17 项，此处为节选）：

{
"root": ".",
"include": [],
"exclude": [".git", "node_modules", "dist", "build", "venv", "target", ".cg"],
"max_file_kb": 512,
"incremental": true,
"engine": "auto",
"language_map": {}
}

- include：非空时仅索引匹配的路径前缀/glob
- exclude：目录名或 glob 模式，walk 时剪枝
- max_file_kb：超过该大小的文件跳过（通常是大文件/生成文件）
- engine：auto（有语法包用 tree-sitter，否则正则）/ quick / deep
- language_map：自定义扩展名映射，如 {".md": "markdown"} 预留
- 数据库默认位于 <root>/.cg/cg.sqlite（该目录已被默认排除，不会索引到自身）

环境变量覆盖：CODEGRAPH_ROOT、CODEGRAPH_DB、CODEGRAPH_MAX_FILE_KB、CODEGRAPH_ENGINE。

增量索引

默认开启。每次 index 计算文件内容 SHA-256，与库中记录比对：未变文件直接跳过（秒级刷新），变更文件原子替换其全部行（一个事务内删除旧行、写入新行），已删除的文件从库中清除。--force 或 reindex force=true 强制全量重解析。

导出可视化

codegraph export dot -o graph.dot # Graphviz 格式：符号为节点、调用为实线边、未解析调用为虚线边、模块导入为文件间点线边 codegraph export json -o graph.json # 结构化数据：files/symbols/calls/imports/meta

已知限制

- 正则引擎（engine: quick）不做字符串/注释感知，字符串里的 foo( 可能被误记为调用点；签名只取单行
- tree-sitter 引擎（deep）对箭头函数常量、对象方法等少数节点形态暂不提取符号
- 跨文件调用解析是启发式：重名方法在全局不唯一时保持 unresolved；动态调用（反射、getattr、动态 import）无法解析
- 宏调用（如 println!）不记录为调用点
- 上述限制只在极端情况下影响精度，不影响核心查询路径；索引质量可通过安装 tree-sitter 语法包提升

目录结构

├── pyproject.toml # 打包与依赖声明 ├── plugin.json # 插件 manifest：入口、工具 schema、配置 schema ├── README.md ├── docs/ │ └── dsh-integration.md # harness 接入说明 ├── examples/demo/ # 可直接体验的示例项目 ├── src/codegraph/ │ ├── cli.py # 命令行入口 │ ├── config.py # 配置加载（文件 + 环境变量） │ ├── models.py # 数据模型（符号/调用/导入） │ ├── store.py # SQLite 存储层 + FTS5 │ ├── builder.py # 索引构建（增量） │ ├── resolver.py # 跨文件解析 │ ├── queries.py # 查询 API │ ├── exporter.py # DOT/JSON 导出 │ ├── cache.py # TTL 查询缓存 │ ├── scanner/ # 文件发现 + 两种解析引擎 │ │ ├── walk.py # 发现与忽略规则 │ │ ├── quick.py # 正则引擎（零依赖） │ │ └── deep.py # tree-sitter 引擎（可选） │ └── server/ # stdio 工具服务器 │ ├── handlers.py # 工具定义/执行/渲染 │ └── mcp.py # JSON-RPC 协议层 └── tests/ # 130 个单元/集成测试（另有 node:test 桥接用例）

测试

python -m unittest discover -s tests -t .

许可证

MIT — 见 LICENSE。