JohnXu22786/codegraph

English

代码知识图谱插件：把代码库解析成可查询的索引，让 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。