ozgurcd/gograph

# gograph [](https://goreportcard.com/report/github.com/ozgurcd/gograph) [](https://opensource.org/licenses/MIT) `gograph` 是一个专为 AI 编程 Agent 设计的本地 AST/类型感知的 Go 仓库上下文索引器。 它构建了一个包含包、符号、调用、路由、配置读取、测试和代码质量信号的紧凑图谱，使 Agent 能够以更少的原始文件读取次数来导航 Go 仓库。 ## 功能特性 - **纯本地运行：** 图谱构建过程不执行任何网络调用，也不会将源代码发送到外部 API。MCP 集成是基于本地 stdio 实现的。 - **专注于 Go：** 使用标准 AST 映射 Go 项目结构、包和依赖关系。 - **定向聚焦：** 使用 `focus` 为单个包提取极具针对性的上下文，从而节省 LLM token。 - **节省 Token 的上下文包：** `context ` 替代了 4-5 次单独的工具调用——在一次响应中返回节点、源码、调用者、被调用者和测试。 - **热点排名：** `hotspot` 根据传入调用次数对函数进行排名，以便 Agent 知道应优先研究哪些函数。 - **代码质量分析：** 圈复杂度（`complexity`）、上帝对象检测（`godobj`）以及包耦合度/不稳定性（`coupling`）。 - **变更检测：** `changes` 无需重新读取源文件即可显示自上次构建以来新增/修改/删除的符号。 - **依赖树：** `deps [--transitive]` 显示任何包的直接或完整传递 import 闭包。 - **技术栈提取：** 自动解析 `go.mod` 以汇总外部依赖（如 `gin` 或 `pgx`），让 Agent 立即了解您的技术栈。 - **并发映射：** 检测整个代码库中的 goroutine 生成、channel 发送、mutex 锁定、WaitGroup 使用和 `sync.Once.Do` 调用。 - **接口满足：** 尽力而为的鸭子类型分析，告诉您任何结构体满足哪些接口——无需运行编译器。 - **测试覆盖率映射：** 尽力而为的映射，将 `Test*` 函数与它们可能测试的生产符号链接起来。 - **环境配置：** 显示每个带有文件、行号和封闭函数的 `os.Getenv` / `viper.Get*` 读取操作。 - **寻路：** `path ` 通过 BFS 查找任意两个符号之间的最短调用链。 - **死代码检测：** `orphans` 使用从入口点出发的完全可达性分析——比简单的 0 调用次数检查更严格。 - **干净的图谱（无生成文件）：** 使用严格的基于行的检测自动排除生成的文件，如 mock 或 protobuf。 - **快速：** 使用 Go 编写以确保高性能。 ## 非目标 - 不提供多语言解析。 - 不进行 AI/模型 API 调用。 - 不包含 Embedding。 - 不依赖 SaaS 后端。 - 不收集遥测数据。 - 不替代编译器/类型检查器的正确性。 - 不保证启发式提取器能找到每一个路由、SQL 查询、测试关系或动态调用。 ## 正确性模型 - **默认模式** 使用 Go AST 解析和尽力而为的启发式方法。它能够容忍不完整或无法编译的仓库。 - **精确模式** 使用类型检查丰富功能，并要求包必须可编译。 - 诸如路由、SQL、测试和错误映射之类的启发式提取器是导航辅助工具，而非权威的程序分析。 ## 安装 ``` go install github.com/ozgurcd/gograph@latest ``` ## 用法 **1. 生成图谱（在每次重大代码更改后运行此命令）：** ``` gograph build . # 或者用于更精确的 type-checked 分析（较慢，但提供准确的 dynamic dispatch 与 interface satisfaction 证明）： gograph build . --precise ``` *这将立即生成 `.gograph/graph.json` 和 `.gograph/GRAPH_REPORT.md`。* **2. 查询图谱（速度极快，无需重新解析）：** ``` gograph query "Auth" # Search for symbols, files, or packages gograph focus "internal/auth" # Generate a highly targeted context for one package gograph callers "ValidateToken" # See what functions call ValidateToken gograph callees "InitServer" # See what InitServer calls gograph implementers "AuthService" # See which structs implement an interface gograph interfaces "UserService" # See which interfaces a struct satisfies (type-checked if --precise was used) gograph fields "User" # Extract all fields and types of a struct gograph source "ValidateToken" # Extract the source code for a specific symbol gograph impact "ValidateToken" # View the full blast radius (all downstream callers) gograph impact --uncommitted # Calculate the blast radius of all your uncommitted code changes gograph orphans # List functions and methods with 0 explicit incoming calls gograph node "UserStruct" # Get detailed AST info about a specific node gograph routes # Extract all HTTP REST API routes (e.g. GET /api) gograph imports "redis" # Find all files that import a specific external package gograph sql # Extract database SQL queries from the AST gograph errors # Map every custom error and panic to its function gograph embeds "Mutex" # See which structs embed a target struct gograph public "internal/auth" # Filter graph to only show exported public symbols gograph envs # List every environment variable read in the codebase gograph concurrency # Map all goroutines, channels, mutexes, and sync primitives gograph tests "ValidateToken" # Find which test functions exercise a named symbol gograph path "CreateUser" "sql" # Shortest call chain between two symbols gograph stale # Check if graph.json is out of date vs source files gograph orphans # Symbols truly unreachable from any entry point gograph godobj # Find god-object struct candidates gograph godobj --methods 10 --fields 12 --calls 30 --top 5 # Custom thresholds gograph complexity # Cyclomatic complexity for all functions (highest first) gograph complexity "Run" # Complexity for a specific function gograph coupling # Package fan-in, fan-out, instability table gograph coupling "internal/auth" # Filter to a specific package # --- TOKEN SAVERS --- gograph context "ValidateToken" # Node + source + callers + callees + tests in ONE call gograph hotspot # Top 10 most-called functions (where to focus first) gograph hotspot --top 20 # Expand to top 20 gograph deps "internal/auth" # Direct import dependencies of a package gograph deps "internal/auth" --transitive # Full transitive closure gograph changes # New/modified/deleted symbols since last build gograph trace "parse failed" # Trace an error string backwards to entry points gograph mutate "User.Status" # Find functions that mutate a specific struct field gograph arity --min 5 # Find functions with many arguments (long parameter list smell) gograph skeleton # Output the whole repository's API signatures (bodies stripped) gograph constructors "User" # Find factory functions returning the named struct gograph schema "users" # Find structs mapped to a database table/schema via tags gograph globals "internal/auth" # Find package-level variables and functions mutating them gograph mocks "AuthService" # Find structs implementing an interface in test/mock files ``` **3. Agent JSON 集成：** 所有查询命令均支持 `--json` 标志，以返回稳定且可供机器解析的信封格式： ``` gograph callers "ValidateToken" --json ``` *返回结果：`{"schema_version": "1", "command": "callers", "status": "ok", "count": 2, "results": [...]}`* **4. 作为 MCP 服务器运行（适用于 AI Agent）：** 如果您想让您的 AI Agent 具备原生的工具执行能力，`gograph` 内置了一个 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 服务器。 ``` gograph mcp . ``` 您可以将其添加到您的 AI 客户端配置中（如 Claude Desktop 或 VS Code 扩展如 Cline），以便 AI 可以自主运行这些图谱查询！ ## 🤖 与 AI Agent 集成 为了从您的 AI 编程助手中获得绝对最佳的结果，您不再需要复制粘贴庞大的指令文件。只需将以下单行内容添加到您的 `.cursorrules`、`CLAUDE.md` 或 AI 系统指令中即可： ## 示例输出 当您运行 `gograph build .` 时，生成的 `GRAPH_REPORT.md` 会为您的 AI 提供一个浓缩的、高密度的上下文映射，如下所示： **外部依赖（技术栈）** | Module | Version | |--------|---------| | `github.com/gin-gonic/gin` | `v1.9.1` | | `github.com/jackc/pgx/v5` | `v5.5.5` | **重要符号（按传出调用次数排名的顶部）** | Symbol | Kind | File | Line | Calls out | |--------|------|------|------|-----------| | `(Server).Start` | method | `server.go` | 42 | 18 | | `ValidateAuth` | function | `auth.go` | 12 | 14 | ## 贡献 我们非常欢迎 Pull Request！有关如何构建、测试和贡献该项目的指南，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 文件。如果您要添加对一种新语言的支持，请先开启一个 Issue 以讨论相关设计。 ## 许可证 本项目基于 MIT 许可证授权 - 详情请参阅 [LICENSE](LICENSE) 文件。

标签：AI编程助手, AST解析, EVTX分析, Go语言, LLM上下文, MCP, SOC Prime, WebSocket, 上下文感知, 云安全监控, 代码分析, 代码图谱, 代码导航, 代码索引, 依赖分析, 凭证管理, 圈复杂度, 并发映射, 开发工具, 技术栈提取, 日志审计, 本地离线, 程序破解, 结构生成, 静态分析