Gograph

🧭 gograph

别再为 grep 烧 token 了，给你的 AI Agent 一张调用图。

gograph 会为你的 Go 仓库构建一个本地、AST 感知的调用图，并通过 CLI 和 MCP 暴露 50+ 查询工具，让编码 Agent 无需读取原始文件，即可导航包、符号、调用链、路由、SQL、环境变量和测试。

零网络。零执行。零密钥读取。 gograph 是纯静态分析 —— 它从不运行你的代码、发起 API 调用，也不会打开任何非 .go 文件。

🚀 快速开始

# 安装
brew install ozgurcd/tap/gograph

# 构建调用图
gograph build . --precise

# 试用一下 —— 谁调用了 ValidateToken？
gograph callers "ValidateToken"

# 一次调用获得完整上下文（节点 + 源码 + 调用方 + 被调用方 + 测试）
gograph context "ValidateToken"

# 编辑前的变更计划（调用方、测试、路由、SQL、环境风险）
gograph plan "ValidateToken"

💡 为什么选择 gograph？

基于 gograph 自身代码库的基准测试（70 个文件、518 个符号、16 个包）：

✨ 主要特性

• 🔍 50+ 查询工具 —— callers、callees、impact、context、plan、review、errorflow、orphans、hotspot、coupling 等等。查看完整的命令参考 →

• 🔌 原生 MCP 服务器 —— 所有工具都以 MCP 端点的形式提供，兼容 Claude、Cursor、Copilot 以及任何支持 MCP 的 Agent。一条命令完成配置：gograph add-claude-plugin

• 🪙 省 Token 的组合命令 —— context 可替代 5 次调用，plan 可替代 8 次，explain 可综合架构叙事。专为最大限度减少 Agent 往返而构建。

• 🛡️ 设计上安全 —— 无网络、无代码执行、无密钥、不读取 .env 文件。AI 工作树目录（.claude/、.cursor/、.agents/）自动排除。

• 🏛️ 架构约束 —— 边界规则、API 漂移检测、复杂度门禁、死代码清扫、上帝对象检测、耦合分析。可通过 gograph gate 在 CI 中运行。

• 📋 Agent 合规审计 —— 会话遥测会追踪 Agent 是否在编辑前运行 plan、编辑后运行 review，并以 A–F 等级评估 Agent 行为，附带可操作的建议。

📖 命令参考

所有命令都支持 --json（机器可读输出）和 --files-only（扁平文件列表）。

带示例的完整命令参考：gograph.identuum.ai/docs/command-reference

{
  "layers": [
    { "name": "domain", "packages": ["internal/domain/**"], "may_import": [] },
    { "name": "handler", "packages": ["internal/handler/**"], "may_import": ["internal/service/**", "internal/domain/**"] }
  ]
}

🤖 AI Agent 集成

一条命令完成配置（Claude Desktop + Claude Code）：

gograph add-claude-plugin

它会注册 MCP 服务器、注入 CLAUDE.md 引导规则，并安装一个 PreToolUse 钩子，将对 Go 符号的 grep 重定向到 gograph 工具。

替代方案 —— 通过 Claude Code 插件市场安装：

/plugin marketplace add ozgurcd/gograph
/plugin install gograph@gograph

通过 Claude Code 的插件市场发现 gograph，并附带一个在 Go 工作中自动激活的 SKILL.md，教导 Agent 执行强制工作流（capabilities → build → plan → context → review），并明确 grep/rg/find 不得用于 Go 符号搜索。

你仍需先安装 gograph 二进制文件（brew install ozgurcd/tap/gograph 或 go install github.com/ozgurcd/gograph@latest）。使用上面的 gograph add-claude-plugin 可获得完整的一键引导（MCP 接线 + CLAUDE.md 规则 + PreToolUse 钩子）。当你更希望在 Claude Code 插件界面内部发现并安装 gograph 时，请使用插件市场。

其他 Agent（Cursor、Copilot、Antigravity 等）：

gograph mcp .   # 以 stdio 方式作为 MCP 服务器运行

添加到你的 .cursorrules 或 AI 系统提示词中：

在回答架构或仓库相关问题之前，先检查可用的 gograph_* MCP 工具并使用它们，而不是 grep/find。先运行 gograph capabilities。

所有命令都支持 --json 以输出机器可读结果：

gograph callers "ValidateToken" --json
# → {"schema_version": "1", "command": "callers", "status": "ok", "count": 2, "results": [...]}

完整的集成指南，请参见 docs/coding-agent-usage.md。

用 llm-wiki/ 实现零成本定向： 每个会话运行一次 gograph wiki，即可生成一个面向机器的 markdown 页面目录 —— 概览、架构图、热点、路由、环境变量、错误位置、并发、逐包文档，以及完整的 API 表面。Agent 阅读这些页面，而无需发起数十次独立工具调用：

gograph build . --precise
gograph wiki                 # 写入 ./llm-wiki/
# 然后读取：llm-wiki/README.md → project.md → rules.md → agent-contract.md → overview.md

将 llm-wiki/ 加入 .gitignore —— 这些文件每次会话都会重新生成。

📊 输出示例

当你运行 gograph build . 时，生成的 GRAPH_REPORT.md 会为你的 AI 提供一份精简的上下文地图：

外部依赖（技术栈）

重要符号（按出向调用排序）

🆚 为什么不使用语言服务器（gopls）？

gopls 是为人类 IDE 优化的，而 gograph 是为基于终端的 LLM 优化的：

1. 协议不匹配 —— gopls 返回 file:line:col 坐标。Agent 随后必须消耗 token 运行 cat/sed 来读取实际代码。gograph 则直接提取精确的结构化切片，并将其格式化为 Markdown。

2. 图级诊断 —— gopls 提供悬停提示和跳转到定义。gograph 则在整个调用图上进行反向 BFS 错误追踪、完整爆炸半径分析和 PR 级变更规划。

3. 可组合的智能 —— gopls 一次回答一个问题。gograph context 在单次调用中打包节点 + 源码 + 调用方 + 被调用方 + 测试；gograph plan 将影响、路由、SQL、环境变量和测试风险聚合为一份清单。

🤝 参与贡献

欢迎提交 Pull Request！构建、测试和贡献指南请参见 CONTRIBUTING.md。

语言支持： gograph 目前仅解析 Go。其架构是可扩展的 —— 如果你想添加 Python、TypeScript、Rust 等语言支持，请先开一个 issue 讨论。

📄 许可证

MIT —— 详见 LICENSE。