gograph

gograph

符号查询接受 path/to/file.go:Name，包括 path/to/file.go:Receiver.Method；短名称存在歧义时，也接受带导入限定的文件路径。 source 会为有歧义的匹配项打印精确选择器。 支持的声明工具和命名例外见 选择器契约。 查询包含结构体字段；query --no-tests 会排除测试文件中的行。 精确变更查询会恢复返回值中被赋值字段的类型。 路由会保留常量路径注册和未解析路径注册；精确构建会解析跨包常量，包括 net/http 方法模式。 tests --transitive --files-only 会打印不重复的文件路径，与 MCP 传递报告中的文件一致。

图状态输出和能力会公开 freshness_context：CLI 新鲜度检查使用发起查询进程的 Go 上下文，包括 GOFLAGS；MCP 使用启动时的上下文和显式标签。即使源代码字节未变化，上下文不匹配仍会被视为过期。不会打印任何环境值。 精确索引会在 usages 和 query 中包含包级常量引用，包括比较、switch 分支、复合值和函数参数。 类枚举常量会保留其声明身份；局部遮蔽的常量不会纳入。 query 会将这些引用位置标记为 usage 行。仅基于 AST 的图不会声称包含经过类型解析的常量用法。 review 使用与 context 相同的测试归属规则。升级后请重新构建。

review --uncommitted 会包含 changes --git HEAD 中已删除的声明，并明确不评估历史调用方、测试和风险。其他针对当前图的遍历命令仍会拒绝处理删除内容。构建过程会说明外层 Git 仓库何时忽略了所请求的目录。

未提交计划/审查在符号遍历时会跳过空标识符声明，例如 var _ I = (*T)(nil)。审查会保留其声明证据并说明限制；changes --git HEAD 仍会列出这些声明。

会话审计会将调用错误与操作失败分开列出，并且不会将调用错误计入合规评分。 可组合性衡量组合查询命令与原始查询命令的比例；它不衡量答案正确性或节省的 token 数量。

为 Go 编码 Agent 提供编译器感知的代码地图，助力更安全的重构。

gograph 会为你的 Go 仓库构建本地结构图，并可选择加入经过类型检查的 CHA/SSA 增强。其 CLI 和 MCP 工作流可帮助编码 Agent 追踪调用方和接口实现、规划变更影响并强制执行架构约束，无需嵌入向量或托管代码索引。

体验无需安装的交互式演示 · 查看可复现的基准测试

有关有界结果页、绑定快照的游标、精确/可能影响以及变更评估状态，请参阅 CLI/MCP 查询契约。 配套项目：Scrinium 为编码 Agent 提供由代码仓库所有、并有证据支持的知识；而 Rulefloor 则通过将代码仓库本地 不变量绑定到具体测试并检测偏移，保护这些不变量。它们是相互独立的可选工具：Scrinium 可以将 Gograph 的结构观察结果和 Rulefloor 的验证结果作为独立证据保留，而不会将任何一方视为无关行为或整个项目正确性的证明。

静态分析；不执行目标代码。 默认索引会在本地解析 Go 源代码，不会调用应用服务。对于 go/build 可识别扩展名的链接目录以及链接文件／特殊文件，索引会将其排除；扩展名不是 Go 的其他常规文件或悬空链接不是 Go 工具的输入，不会妨碍精确分析。由图指引的源文件读取始终限制在被分析代码仓库中的常规文件内；而链接／非常规的 Go 工具元数据（go.mod、go.sum、go.work、go.work.sum 和 vendor/modules.txt）会在调用工具链前被拒绝；显式指定为符号链接的代码仓库根目录仍受支持。适用的 go.work use 成员可以是最近的真实 Git 检出目录下的同级模块；如果没有此边界，它们则会被限制在工作区目录内。每个成员目录、go.mod 和可选的 go.sum 都会在 cmd/go 启动前进行验证。Gograph 还会读取 .gitignore、图／配置 JSON 和 Git 状态等项目元数据。索引会向已安装的 Go 工具链查询有效的构建／模块上下文；精确模式还会执行包类型加载，doc 会运行 go doc。这些操作遵循你配置的模块／缓存／网络策略。在加载代码仓库包或运行 go doc 之前，适用的本地模块／工作区源代码树会先进行预检，以检查 cmd/go 可能会访问的链接；.git 和 .gograph 子树除外。会话遥测数据保存在本地 .gograph/sessions/ 下；不会向 gograph 服务发送任何内容。

快速开始

# Install
brew install --cask ozgurcd/tap/gograph
# or: go install github.com/ozgurcd/gograph/cmd/gograph@latest

# Confirm which installation will run and detect PATH shadowing
gograph doctor --json

# Build a type-enriched precise graph, then verify it
gograph build . --precise
gograph stats

# Optional CI contract: fail when precise enrichment falls back
gograph build . --precise --strict

# Optional: prioritize lower heap use on constrained hosts
gograph build . --precise --memory-mode=low --max-memory=1GiB

# Optional: include integration-tagged files and tests in this graph
gograph build . --precise --tags=integration

# Optional: omit unrelated broken package directories
gograph build . --precise --strict --exclude-dirs=legacy,examples/broken

# Start with repository-wide results that require no guessed symbol
gograph summary
gograph hotspot --top 5
gograph flow --no-tests

Homebrew 和 go install 会安装常规的 gograph CLI。支持 MCP Bundles 的 MCP 客户端则可以在官方 MCP Registry中发现本地 stdio 服务，其名称为 io.github.ozgurcd/gograph。通过 Registry/MCPB 安装是单独的分发路径；它不会安装 Homebrew cask，也不会配置 Claude Code marketplace 插件。Registry 目前处于预览阶段。有关客户端支持、目标选择和当前限制，请参阅官方 MCP Registry 和 MCPB 安装。

从 summary、hotspot 或 gograph complexity 显示的函数或方法中选择一个真实名称，然后在下方替换为该名称：

gograph explore "YourSymbol" --compact # low-token discovery, identity/role, and complete evidence counts
gograph explore "YourSymbol"           # standard source + callers/callees + tests + exact identity impact
gograph explore "YourSymbol" --deep    # standard response + depth-3 exact evidence, package context, explanation
gograph context "YourSymbol" # source + callers + callees + tests

# For compilable repositories, enrich the graph before a major refactor
gograph build . --precise
gograph plan "YourSymbol"

构建产物会写入目标目录 .gograph/。如果存在外层 Git 仓库根目录，gograph 会将 .gograph/ 添加到该目录的 .gitignore；如果不在 Git 仓库中，则改为添加到构建目标的 .gitignore。如果没有找到 Go 文件，或没有任何源文件成功解析，gograph 会退出且不会替换现有产物。更新操作只接受不存在或为普通文件的 .gitignore；如果仓库提供的是链接，则会拒绝更新，也不会修改其目标。Go 构建约束、显式逗号分隔的 --tags（若未指定该标志，则使用继承的 GOFLAGS）、cmd/go 包目录规则、生成的源文件、模块模式忽略指令以及 Git 忽略规则，在构建、新鲜度检查和变更检测中使用相同的扫描策略。链接的 .go 文件、链接目录以及其他被识别为 Go 输入的非普通文件都会报告并排除。Go 工具预检会忽略扩展名不是 Go 扩展名的不相关普通文件和悬空链接（例如 YAML 配置或 TSV 测试数据）；在 gograph 或 Go 工具链读取 go.mod、go.sum、go.work、go.work.sum 和 vendor/modules.txt 条目之前，会拒绝其中适用的链接或非普通文件。适用的 go.work use 成员可以是最近真实 Git 检出目录下的同级模块。非 Git 布局仍受工作区目录范围限制，不会跨越嵌套的 Git 边界，并且会在 cmd/go 启动前验证每个成员目录、go.mod 和可选的 go.sum。.gograph 本身必须是真实目录，且 graph.json 必须是位于仓库范围内的普通文件。缺少范围限制策略标记或使用不受支持的标记的图，必须先用当前二进制重新构建，才能用于图驱动的命令。旧版二进制不会强制执行此边界，不应用于分析不受信任的仓库。

每个索引源文件都会存储一个 SHA-256 内容摘要。重建时，会重新解析发生变更的包中所有已选文件，并复用未变更包的解析器记录；stats 会报告 reused_files 和 rebuilt_packages。精确构建会复用这些 AST 工作，但仍会重新计算整个仓库范围的类型、CHA 和 SSA 增强信息，以确保跨包分派保持正确。

低内存模式会保留这些图语义，同时采用更积极的垃圾回收，在生成分析与测试分析之间回收内存，并避免对 AST 图进行完整的 JSON 复制。--max-memory 接受 1GB 或 1GiB 这类整数表示的字节大小，并且必须与 --memory-mode=low 一起使用。这是 Go 运行时的软内存目标，而非 RSS 硬上限，因此内存映射文件、可执行文件和 Go 工具链子进程都可能导致进程内存超过请求值。积极的垃圾回收可能增加 CPU 时间；目标设得过低可能显著拖慢构建，甚至导致失败；Gograph 绝不会为了满足目标而悄悄降低精度。

为保持兼容性，精确回退默认仍会以零退出码结束，并记录在图元数据中。如果回退必须导致 CI 失败，请在使用 --precise 时添加 --strict；Gograph 仍会在返回非零状态码前发布或保留诊断产物。

如果精确构建受无关目录阻碍，请参阅目录排除。启动 gograph mcp 时也使用相同的 --exclude-dirs 选择；导入的依赖仍必须通过类型检查。对于符号链接技能，v1.7.2 支持 --exclude-dirs=.claude/skills：该真实目录下的目录链接会从 Go 加载过程中隐藏，且不会跟随其目标。链接的 Go 输入和元数据仍会受到保护。注册和验证方法请参阅 Codex MCP 设置指南。

可机器读取的结构验证

外部使用方无需解析面向用户的 CLI 输出，即可验证一个封闭的结构谓词：

gograph version --json
gograph validate --repo /work/project --binding-json '{"schema_version":"gograph.binding.v1","predicate":"symbol_exists","subject":{"language":"go","kind":"symbol","id":"example.com/project/internal/auth::Authorize"},"required_precision":"ast"}' --json

版本和结果架构分别为 gograph.version.v1 和 gograph.validation.v1；绑定使用 gograph.binding.v1。V1 仅支持 symbol_exists、package_imports、call_edge_exists 和 type_implements。 验证为只读操作，绝不会构建或刷新图。退出码 0 表示 pass，退出码 1 表示已明确评估为 fail，退出码 2 表示 cannot_evaluate 或请求无效。

否定结果需要满足特定谓词的完整性要求：要判定符号和直接导入不存在，需要当前且完整的 AST 图；要判定实现关系不存在，需要当前且精确完整的图；要判定调用关系不存在，还需要完整解析主体相关的调用边。证据缺失、过时、不完整、有歧义或未解析时，结果会降级为 cannot_evaluate；precise_fallback 图可用于确认 AST 中存在某项内容，但绝不能用于评估其不存在。

结果会绑定确切的图字节、所选源代码／构建上下文清单，以及带 SHA-256 指纹的规范绑定。

Gograph 验证所选构建上下文中的 Go 结构，不证明运行时行为或业务正确性。CHA 边表示可能的静态目标，不代表运行时分派的确定性。V1 不支持可达性、不稳定或外部符号标识、未命名类型以及非 Go 语言。请参阅机器验证约定。

适用的本地模块／工作区源代码根目录必须位于显式指定的 --repo 根目录之下；V1 不会扩大此权限，而是返回 cannot_evaluate。

默认情况下，MCP 刷新结果仅保存在内存中。若要为 CLI 使用者和后续服务进程发布每次成功刷新的结果，请显式使用以下命令启动服务：

gograph mcp . --persist-refresh
# Keep MCP startup and every later refresh on the integration-tagged selection:
gograph mcp . --tags=integration
# Optional low-memory policy for startup analysis and later refreshes:
gograph mcp . --memory-mode=low --max-memory=1GiB

此选择启用的模式会在刷新确认最新后写入或覆盖 .gograph/graph.json 和九份 Markdown 报告。它不会修改 .gitignore；如有需要，请在启用前自行忽略 .gograph/。该目录仅保存最新发布状态，并非按分支缓存。如果不存在可用图（包括不安全或不受支持的产物），启动时自动构建的图会在开始服务前发布；若发布失败，则无法启动。之后，若由工具触发的发布失败，该工具会返回错误；服务器会在另一次支持刷新的调用中重试待处理的发布，而不会重新构建已是最新状态的内存图。写入方通过本地 .gograph/.artifacts.lock 文件协调；现有锁条目必须是普通文件，不得是链接或特殊文件。报告会先被替换，最后替换 graph.json，作为发布提交标记；这十个文件组成的完整套件并非单一原子文件系统事务。在类 Unix 系统上，同目录替换是原子的；Go 不保证在非 Unix 平台上具有原子重命名语义。除十个输出文件外，锁文件也会作为协调运行的状态保留。

持久化的图会绑定其有效的 Go 环境和构建选择。启动 MCP 时，请使用构建该图时相同的 GOWORK、GOFLAGS 和 --tags 上下文；上下文不匹配意味着图已过时，必须成功刷新，否则应返回诊断信息，而不能静默提供不兼容的事实。 gograph doctor --json 会报告该仓库诊断信息。

为什么选择 gograph？

较早版本 gograph 的某一时点输出对比示例 （随着仓库演进，计数会有所变化；这些命令返回的是不同类型 的证据）：

主要功能

面向机器和 Agent 的工作流 — explore 提供有界的首次发现能力，包含按排名排列的词法匹配、显式符号选择、源代码、调用方、被调用方、测试，以及通过精确身份解析得出的影响范围；同时还提供专用的调用方、被调用方、更广范围的影响分析、反向测试覆盖率、稳定身份、计划、审查、流程、验证和策略命令。MCP 服务注册了 68 个端点，其中包括四个会话生命周期工具。查看完整命令参考 →

联合工作区 — 通过独立建立指纹的仓库图和小型确定性跨仓库叠加层，对多个已检出的仓库建模。解析范围支持 OSS/CE 等备选代码库组合，无需合并仓库所有权。P0 可解析 Go 模块、普通跨仓库 Go 调用，以及一等 HTTP 合约，以支持工作区范围的状态、查询、路径和影响分析。四个只读工作区 MCP 工具返回与 CLI --json 相同的原生结果值。成员刷新和叠加层发布仍是显式的 CLI 变更操作。工作区指南 →

原生 MCP 服务 — 所有 64 项仓库查询、分析和工作流功能均有对应的项目 MCP 功能，可供 Claude、Cursor、Copilot 和其他 MCP 客户端使用；另有四个端点用于会话生命周期（项目工具共 68 个）。独立的工作区服务提供状态、查询、路径和影响分析，返回与相应 CLI 操作相同的原生结果。通常，CLI <command> 对应 MCP gograph_<command>；contract、boundaries --create 和会话操作使用文档中说明的特殊映射。仅限 CLI 的进程／主机／制品操作包括：build、validate、doctor、gate、snapshot、插件／钩子安装、项目／工作区 MCP 启动、工作区构建／成员刷新，以及帮助。独立的 version 命令没有对应的 MCP 工具，但 gograph_capabilities 会报告正在运行的服务版本。适当情况下，传输层的呈现方式会有所不同，但成对操作的功能语义相同。完整 CLI/MCP 对照表 → 明确的时效性模型 — 基于 CLI 图的分析会读取最近一次可信的持久化图。其 JSON 信封包含 gograph.graph-state.v1，用于区分来源（persisted/in_memory）、时效性（current/stale）、完整性（complete/partial）、精度（ast/precise/fallback）、刷新结果和持久化结果；有界诊断信息保留在产生它们的操作中。文本 stats 和 stale 会报告相同的持久化状态。gograph stale 会比较所选源内容摘要和有效的构建/模块指纹；对于当前索引，修改时间仅作诊断用途。它是一个三态谓词：退出码 0 表示当前，2 表示过时，1 表示操作错误或 JSON 序列化错误；缺失或不受支持的源策略标记会明确要求以状态码 1 重建。MCP 源分析工具会在每次调用时检查相同的时效性，采用更新的持久化精确图，并使用最新请求的分析模式在内存中增量重建已更改的软件包 AST。基于刷新的工具会保留其兼容文本，并添加 gograph.mcp-result.v1 结构化内容（源代码/上下文则使用包含答案或拒绝信息的 gograph.read.v1），以及 _meta.gograph_graph_state。精确增强失败时，可以提供明确标记为当前内存回退的结果；普通刷新失败时，可以提供最近一次可信的过时图；这两种降级结果都不会被静默发布，而有效 Go 环境不匹配时仍会安全失败。MCP stale、默认的 changes 和 stats 会检查可信的持久化快照；若没有可用产物，则检查启动时自动构建的回退图。使用 --persist-refresh 时，成功刷新后该快照会更新；发布失败不会影响新鲜的内存图继续使用，并会明确报告 persistence.outcome=failed，同时提供持久化诊断信息以供重试。

精简的组合式工作流 — explore、context、plan 和 explain 会组合源代码与图证据，否则这些内容需要通过多次单独查询才能获取。explore 是增量功能：专用命令仍是针对聚焦分析的完整、稳定接口。实际节省的工具调用次数和令牌数取决于代码库和任务。

有意保持狭窄的范围 — 从不运行目标代码库的二进制文件或测试，也不会有意扫描 .env、密钥、证书或凭据文件。链接目录以及被识别为 Go 构建输入的链接/特殊文件会被排除；与 Go 无关的普通文件链接不在 Go 工具预检范围内。按需读取源代码和代码片段时，会使用以代码库根目录为界的文件系统句柄，并且只接受不含符号链接路径组件的普通 .go 文件。链接的/非普通文件形式的 Go 模块/工作区元数据、校验和文件以及 vendor/modules.txt 会在使用工具链前被拒绝。适用的 go.work 成员可以位于最近的真实 Git 检出目录中的同级目录，否则必须位于工作区目录之下；在调用 cmd/go 前，会对这些目录及模块元数据进行预检。默认/相对策略配置必须位于项目范围内；文档中说明的绝对配置/输出参数是操作人员明确选择的本地路径。AI 工作区目录（.claude/、.cursor/、.agents/）会被排除。索引期间，已安装的 Go 工具链会解析有效构建上下文；只有在预检通过后，才会进行精确的代码库软件包加载和外部 go doc 调用。预检会拒绝 cmd/go 可能检查的源代码树链接，范围包括所选根目录及其有效模块根目录，或工作区根目录及其成员树，但 .git 和 .gograph 除外。依赖项和工具链的解析仍会遵循用户 Go 环境的开放世界范围。

架构约束检查 — 边界规则、API 漂移检测、复杂度门槛、死代码扫描、巨型对象检测、耦合分析。在 CI 中运行 gograph gate。 安全流分析 — flow 会跟踪潜在 HTTP 请求、解码后的 JSON 和环境数据如何通过赋值与函数调用流向 SQL 查询文本、进程执行、文件系统路径和出站 HTTP 目标。发现结果包含严重性、置信度和源到汇的路径步骤；MCP 通过 gograph_flow 提供相同的分析。

完整性感知索引 — 发布时会拒绝已链接或非目录形式的 .gograph；只有在成功解析后，才会暂存 graph.json 并将其作为最后一步替换（在类 Unix 系统上，同目录重命名是原子的）。索引会记录完整／部分构建健康状态以及 ast／precise／precise_fallback 分析状态，并通过 gograph stats 暴露这两项信息。gate 会拒绝评估过期的图谱。

Agent 合规审计 — 会话遥测会跟踪 Agent 是否在编辑前运行 plan、编辑后运行 review，并以 A–F 评级 Agent 行为，提供可执行的建议。

审计会话归属于明确的调用方。gograph session create task 会打印会话 ID；在后续 CLI 命令中通过 --session-id ID 或 GOGRAPH_SESSION=ID 传入该 ID。标志会覆盖环境变量。指定的分析命令仍要求提供 --intention，并保留现有审计评级。未指定选择器时，只读命令无需提供意图，也绝不会写入其他调用方的审计记录。不同调用方可以并发创建独立会话。当其他调用方拥有活动会话时，仓库写入以及会话结束／清理操作会被拒绝，并指出该会话。即使其他所有者仍有活动会话，也可以结束自己拥有的会话。结束会话后，请取消设置 GOGRAPH_SESSION。

MCP 工具接受每个请求各自提供的 session_id 和 intention。请使用 gograph_session_create 返回的 ID；所有者调用分析命令时必须提供理由。服务端不会继承 GOGRAPH_SESSION，因此共用一个 MCP 进程不会合并调用方。默认的内存刷新仍为只读；--persist-refresh 调用会按写入操作进行保护。会话 ID 是用于协作归因的选择器，不是凭据，也不是操作系统用户级别的安全边界。可以通过现有 ID 显式选择较早的活动会话。详见会话设计。

命令参考

查询和组合分析命令支持 --json；version --json 和 validate ... --json 使用各自专用的机器可读架构。精确的 --files-only 适用范围列于命令参考中。build、wiki、gate、snapshot、安装和帮助等运维命令使用文本输出；doctor 和工作区构建／状态／查询／路径／影响命令也接受 --json，而 session audit 还支持原始 JSON。CLI 的 --mermaid 会将 callers、callees、impact、endpoint、dependents、deps、path 和 coupling 渲染为围栏式 Mermaid。对应的 MCP 工具接受 mermaid=true，并返回相同的 Markdown 围栏式 Mermaid 文本；不使用该参数时，每个工具会保留其常规响应格式。

SQL 提取包括直接字面量，以及可静态解析的局部或同文件包级 const/var 声明、直线赋值和有界字符串拼接。仍会排除运行时生成的 SQL。路由和 SQL 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/**"] }
  ]
}

{
  "sanitizers": [
    { "function": "security.CleanPath", "for": ["filesystem"] },
    { "function": "security.ValidateURL", "for": ["outbound_http"] }
  ]
}

**官方 MCP Registry（预览版）：**支持 MCPB 的客户端可以发现 io.github.ozgurcd/gograph。该捆绑包会询问 Go 项目的根目录，并使用等效于 gograph mcp <project-directory> 的独立参数启动捆绑的可执行文件。 发行版为 macOS、Linux 和 Windows 提供 amd64 和 arm64 捆绑包。当前 Registry 软件包架构无法按 CPU 架构选择， 因此请选取文件名与主机匹配的资源；不要假设客户端会自动选择。所有分析仍通过 stdio 在本地运行，不会使用托管的 gograph 服务或远程遥测。

Registry 捆绑包和安装程序生成的 MCP 注册有意省略 --persist-refresh，默认不启用磁盘发布。如需明确启用此行为，请使用自定义的本地 MCP 命令。

桌面配置、共享规则和 Claude Code hook 设置：

gograph add-claude-plugin

此操作会注册 Claude Desktop MCP 服务、注入共享的 CLAUDE.md 指导规则，并安装 Claude Code PreToolUse hook。该 hook 仅在有效搜索目标属于含有 .gograph 索引的代码库时，才会重定向 Go 符号搜索，因此多根工作区中未建立索引的文件夹不会受到影响。若要注册 Claude Code MCP 服务，还需运行安装程序打印的命令：claude mcp add gograph -- gograph mcp .。任何安装步骤失败时，安装程序都会以非零状态码退出。

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

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

通过 Claude Code 插件市场发现 gograph，并提供一个 SKILL.md，在处理 Go 项目时自动激活，向 Agent 介绍工作流（doctor --json → capabilities → stats → plan → context → 编辑 → review）、何时适合使用可生成持久且精确结果的 CLI 构建、何时使用结构化查询，以及何时通过 gopls 或针对性的文本／源码搜索进行验证。

你仍需安装 gograph 二进制文件（brew install --cask ozgurcd/tap/gograph 或 go install github.com/ozgurcd/gograph/cmd/gograph@latest）。使用 gograph add-claude-plugin 配置 Claude Desktop MCP 服务以及共享规则和 Claude Code hook；使用打印出的 claude mcp add 命令注册 Claude Code MCP 服务。如果你更倾向于通过 Claude Code 插件界面发现插件，请使用插件市场。

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

gograph mcp .                     # stdio server; refreshes stay in memory
gograph mcp . --persist-refresh   # opt in to publishing refreshed artifacts
gograph mcp . --tags=integration  # retain the same tagged context on every refresh
gograph mcp . --memory-mode=low --max-memory=1GiB  # same low-memory refresh policy as CLI builds

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

在回答架构或代码库相关问题之前，请检查可用的 gograph_* MCP 工具并运行 gograph capabilities。对于受支持的结构化查询，优先使用 gograph；当 结果不明确、精度回退或缺少已知源码调用时，请使用 gopls 或针对性的源码／文本搜索。

查询和组合分析命令支持 --json，可输出机器可读结果：

gograph callers "YourSymbol" --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                 # writes to ./llm-wiki/
# generated orientation starts at: llm-wiki/overview.md
# if maintained governance pages exist, read:
# llm-wiki/index.md → project.md → agent-rules.md → agent-contract.md

如果生成的 wiki 内容可以丢弃，请将其添加到 .gitignore。不要覆盖代码库中维护的或受 Scrinium 保护的 agent-rules.md；请按照该代码库中记录的工作流提出受治理的更改。 重新生成时，只会移除符合 Gograph 生成签名的过时软件包页面；自定义软件包页面和 packages/README.md 会保留。

示例输出

运行 gograph build . 后，生成的 GRAPH_REPORT.md 会为你的 AI 提供精简的上下文映射：

外部依赖（技术栈）

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

gograph 如何与 gopls 互补？

gopls 是 Go 项目基于编译器的语言服务端。它提供实时工作区诊断、导航、引用、实现、重构支持，以及实验性的 MCP 服务。对于编辑器和编译器感知型工作区操作，它仍应是首选。

gograph 为代码仓库和 Agent 工作流增添了不同的层次：

1. 持久化快照 — CLI 分析可以检查稳定的图谱构件，而 MCP 会刷新源代码分析状态并保留所请求的精度模式。
2. 代码仓库级分析 — 变更影响、可达性、路由、SQL、环境变量读取、安全流候选项、耦合关系和策略门禁会统一呈现。
3. 组合式响应 — context、plan、review 和 summary 会为 Agent 工作流整合相关证据，而不是每次只公开一种语言操作。

使用 gopls 进行基于实时编译器的导航和重构，使用 rg 进行文本和非 Go 搜索；当需要持久化的代码仓库图谱或组合式变更分析工作流时，则使用 gograph。请参阅基准测试指南，了解如何衡量这些不同的工作流，而不应假定某个工具可以直接替代另一个工具。

贡献

欢迎提交拉取请求！有关构建、测试和贡献指南，请参阅 CONTRIBUTING.md。

语言支持：gograph 目前仅解析 Go。其架构可扩展——如果你想添加 Python、TypeScript、Rust 等语言，请先提交 issue。

许可证

MIT — 详见 LICENSE。