JohnXu22786/codegraph

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：零安装直接使用（仓库内）
set PYTHONPATH=src        # Windows
export PYTHONPATH=src     # Linux/macOS
python -m codegraph --help

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

快速开始

cd examples/demo

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

2. 提问
codegraph callers services.orders.create_order     # 谁调用了 create_order → app.run
codegraph callees app.run                          # app.run 调用了什么
codegraph deps services.billing                    # billing 模块依赖什么
codegraph dependents services.billing              # 谁依赖 billing
codegraph search "coupon"                          # 全文搜索
codegraph impact services.billing.price            # 影响面（传递调用者）
codegraph status                                   # 索引统计
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 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"}}}
{"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——只读工具在此之前会返回可读的错误提示。

配置文件

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"} 预留
- 数据库默认位于 /.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。