cg-code-graph — 改代码前先看完整影响面的本地依赖图（CLI + MCP）

技能简介

cg-code-graph（PyPI 包名 cg-code-graph，CLI 命令 cg）是一款纯本地的代码依赖图工具——把代码库里的 routes、calls、tables、config、作业、监听器全自动编织成一张确定性依赖图，每条边都带 file:line 证据。它既给开发者用（CLI + 视觉化网页），也给 AI 代理用（MCP server），让"这次改动影响哪些入口、哪些测试、哪些表"在按下回车前就被算清楚。整个图里没有 LLM，所有结论都是静态分析+确定性查询的结果——零幻觉、零外部 API、零云依赖。

核心能力

• 跨语言符号抽取：原生支持 Python（Django DRF / FastAPI / Flask / Celery）、TypeScript / JavaScript（Nuxt、NestJS、Next.js、Astro、Express、Fastify、Hono、Elysia、React Router、Remix）、PHP Laravel、Laravel + 队列/广播/路由属性、Dart / Flutter、Kotlin（Android / Spring / KMP）、Java Spring、Swift、SwiftPM、Rust/C/C++，可选接入 scip-java / scip-clang / rust-analyzer 升级为 exact 模式。Go 可通过 SCIP 索引接入。
• 一跳到 N 跳可达性查询：reaches / impact / path 三个核心查询，给定一张表、一个 config key、一个方法，跑出"谁会调用它 / 反向追溯到入口 / 上下游最短路径"。
• cg affected --base main：列出"main 之后这次改动会触及的所有测试 + 入口"，--quiet 直接喂测试 runner。
• 跨 repo link：cg link 自动匹配前端 HTTP 调用 → 后端路由（如 Nuxt 调 Laravel / Guzzle），并校验请求 schema（FormRequest / Elysia / Nuxt body 一致）。
• 路由守卫审计：cg routes --writes --unguarded 列出"会写数据但无 auth 守卫"的路由，Laravel 默认计数 action 内部守卫。
• 安全视图：cg surface 输出 inbound/outbound 攻击面 + 硬编码凭据 + 明文协议 + 未验证 webhook + 未鉴权处理器 + 全接口监听 + 禁用的 TLS/SSH 校验 + 明文 gRPC + 暴露 IPC + 用请求输入构造的出站 URL——文本 / JSON / SARIF 三种格式，CI 配 --fail-on。
• MCP server cg-mcp：让 Claude Code / Cursor / Codex 直接通过 MCP 查图，每个工具名稳定，结果含源 + 证据。
• 视觉化：cg serve 起本地 web；cg plan check 在计划分支上模拟整批改动的影响。
• 增量同步：哪些 repo 没改 / commit 没动 → 完全不重读，已有 memo / blob 复用，避免大仓 IO 风暴。

安装配置

环境前置：Python ≥ 3.11、pipx 或 uv。PHP / Dart / Flutter 项目额外需要对应 SDK。

# 1. 一行安装（pipx 推荐，隔离环境）
pipx install cg-code-graph
# 或者：uv tool install cg-code-graph

# 2. 为本仓库建图
cg index . --db out/graph.db

# 3. 给你的 IDE / Agent 注册 MCP server
cg install --host cursor      # 可选：claude / codex / vscode
# 这条会自动配置 MCP server + 一条"先用 cg"的代理规则

# 4. 试一条查询（用自带 Django sample）
cg reaches table:store_books --db out/graph.db

可选开关：cg install --exact（精确模式工具链，PHP 需 8.2+，可选 scip-java / rust-analyzer）、cg index --scip FILE（导入 Go 等其他语言 SCIP 索引）、cg doctor（看每种语言当前是 exact 还是 heuristic）。

使用步骤

1. cg index . --db out/graph.db 对当前代码库生成持久化图；后续只增量更新。
2. cg reaches table:<table> 查"哪些入口/作业/路由会写到这张表"——返回 file:line:col 路径链 + 边类型（HANDLED_BY / WRITES_TABLE / DISPATCHES 等）。
3. cg impact --arg 'paths=["src/foo.py"]' 反向追溯——哪些入口函数、测试、job 会受影响。
4. cg affected --base main 列出 main 以来所有会受影响入口，配 --quiet 直接喂 pytest / jest。
5. cg link 跨仓库匹配 HTTP 端点，自动发现"前端调用但后端没找到对应路由"的 missing routes。
6. cg surface --format sarif --fail-on high 接 CI，PR 引入硬编码密钥 / 未鉴权路由直接 fail build。
7. cg serve 起本地 web 视图：选定节点看证据路径、源、计划变更覆盖图层。
8. cg-mcp MCP server：Claude Code / Cursor / Codex 直接调 cg_impact / cg_reaches / cg_node / cg_path。

适用场景

• 大型 monorepo 重构前审计：先跑 cg affected --base main 看会被波及的所有入口/测试。
• 新成员 onboarding：用 cg reaches 解释"这个订单表到底被哪些路径动过"。
• PR review：cg impact 检查"这次 PR 触达的入口是否需要同步改文档 / SOP / 监控告警"。
• 安全审计：cg surface 在 CI 流水线扫硬编码密钥 + 未鉴权路由 + 明文协议。
• AI 编码代理前置上下文：把 MCP server 接到 Claude Code / Cursor，代理改文件前自动 fetch 影响面。
• 跨前后端契约守护：cg link 自动校验前端请求 schema vs 后端 FormRequest / Elysia / NestJS DTO。
• 遗留系统探索：本地静态索引，不依赖 IDE / 在线服务；CI/CD 容器也能跑。

适用人群

• 后端架构师：在新代码入库前需要明确"这张表 / 这个 API 的全部调用方"。
• Tech Lead / 代码评审负责人：在 PR review 时自动暴露漏改的入口/测试。
• DevSecOps 工程师：CI 中跑 cg surface 拦截硬编码密钥 / 未鉴权写路由。
• AI 编码代理重度用户：在 Cursor / Claude Code / Codex 里改代码前自动查询影响面。
• 多语言团队：Django + Next.js + Laravel + Flutter 混合栈需要一张全局图。
• 个人独立开发者：想清理遗留系统但不想读所有代码——直接查图。

工作原理

cg-code-graph 走 静态分析 + 模式识别 + 跨语言可达性 三段式：

• 语法解析：Python 走 stdlib ast，TypeScript 走 TypeScript Compiler API，PHP 走 nikic/php-parser，Dart 走 Dart analyzer，Kotlin / Java / Swift / Rust 各有可选项；不需要运行时跑代码。
• 边抽取：识别路由属性、ORM 表声明、Celery/队列广播、Cypher dispatch、handler/listener 绑定、imports/inheritance、override、静态调用等模式，把代码语义翻译成"节点 + 边"。
• 图存储：本地 SQLite，附 provenance + revision；只重读增量变更，--verify --cold 重建 hash 前后一致确保确定性。
• 可达性查询：reaches 跑前向 BFS；impact 跑反向追溯，跨文件 import 推断；path 跑最短路径（带 trace 链条：requirement → step → code → test）；affected 跑 base commit diff 增量匹配。
• 安全视图：cg surface 把所有"开发不慎"模式（硬编码 PEM、provider key、未鉴权 handler、gRPC 明文、IPC 暴露）按 OAST 标准汇成 SARIF，方便 SARIF viewer / CodeQL / GitHub Code Scanning 集成。

官方链接

• PyPI 项目页：https://pypi.org/project/cg-code-graph/
• 下载统计：https://pepy.tech/project/cg-code-graph
• GitHub 仓库：https://github.com/cyberchronos00/code-graph
• 官方文档站：https://code-graph.cyberchronos00.workers.dev/
• 快速上手：https://code-graph.cyberchronos00.workers.dev/docs/quickstart
• CLI 参考：https://code-graph.cyberchronos00.workers.dev/docs/cli
• MCP 配置：https://code-graph.cyberchronos00.workers.dev/docs/mcp
• 变更日志：https://github.com/cyberchronos00/code-graph/blob/main/CHANGELOG.md
• 许可协议：MIT