simplecore-inc/coregraph

# CoreGraph [](https://www.npmjs.com/package/@coregraph/cli) [](LICENSE)    针对多语言和 monorepo 代码库的单一可查询代码图——查找调用者、影响、死代码和跨文件不一致之处，每条关系都标记了您可以信任的程度。 CoreGraph 是一个 Rust CLI（`coregraph`，v0.1.3，MIT）。它对您的源代码进行一次性索引， 通过后台 daemon 提供图服务，并通过 IPC socket、面向 LLM agent 的 MCP 桥接、面向编辑器的 LSP 桥接以及可选的 HTTP API 来回答问题。因为每个答案都来自预先计算的图，而不是重新读取文件，所以结果精确、返回速度快，并且体积足够小，可以直接 交给 LLM——只需几百个 token，而 grep 和粘贴文件可能需要 花费数千个 token。 ## 什么是 CoreGraph CoreGraph 通过将两个分析层结合到一个单一结果中，为您的代码库构建了一个内存中的**符号图**： - **tree-sitter** 从每个文件中提取符号——函数、方法、结构体、类、 枚举、配置键、文档注释。 - **stack-graphs** 解析*跨文件*的名称——因此一个文件中的调用点 会链接到它在另一个文件中实际绑定的定义，而不仅仅是链接到任何 同名的内容。 两者都在一次 `coregraph index` 过程中运行——不需要语言服务器、构建系统 或编译器工具链。 图中的每条边都带有一个**置信度分数** (0.0–1.0)、产生它的**来源** （例如由 stack-graphs 解析还是语法匹配），以及一个 **信任模型**。这意味着消费者——无论是 LLM agent 还是人类——都可以将编译器级别的事实与启发式猜测区分开来，并在需要时通过 `--min-confidence` 进行过滤。 ## 核心亮点

- **Token 高效——专为 LLM agent 打造。** 每个答案都来自 预先计算的图，因此 CoreGraph 返回问题涉及的*确切*符号和边， 而不是整个文件。`--output-format llm` 输出紧凑、结构化的 文本；结果根据 `--token-budget` 进行分页（默认 `8000`；`--fast` 将其限制为 `2000`，`--full` 将其提高至 `16000`），并带有实时的 `budget: used/total` 计数器；且 `--min-confidence` 会在低信任度噪音到达 模型之前将其过滤掉。原本需要粘贴多个文件的调用者查找， 现在只需几百个 token 即可完成。 - **快速，且保持快速。** 单次 `index` 即可构建整个图（在此仓库中约 280 个文件耗时约 2.3 秒），然后后台 daemon 会通过 IPC socket 从内存中为后续的每个查询提供服务——无需为每个命令重新索引。空闲项目会被 快照到磁盘，并在下次查询时**热加载**（跳过 tree-sitter 提取），除非源文件发生了更改，因此重复查询实际上是 瞬时的，并且永远不会过时。 - **多种语言，一个图。** Java、TypeScript、JavaScript、Python、Go、Rust 和 Kotlin 每一种都同时具备符号提取*和*跨文件名称解析， 此外还有配置（YAML/TOML/JSON）和 Markdown 层——所有这些都统一到一个索引中，无论使用何种语言，您的查询方式都完全相同。 - **原生 Monorepo。** 一个图即可同时覆盖仓库中的每个包、服务和语言： 跨越目录或语言边界的引用会解析到其真实的定义，因此跨包调用路径和共享 定义可以在单个查询中访问，而不是散落在各语言专属的索引中。daemon 使用带有 可选堆预算的 LRU 缓存多个项目，保持大型多语言仓库的响应速度。 ## 为什么选择 CoreGraph | 工具 | 它能提供什么 | 它缺少什么 | |------|-------------------|----------------| | `grep` / ripgrep | 快速的文本匹配 | 没有符号、没有调用边、没有跨文件解析 | | `ctags` | 符号索引 | 没有调用者/被调用者、没有影响分析、仅限单次运行 | | 单语言 LSP | 一种语言的丰富导航 | 一次只能处理一种语言；无法处理多语言 monorepo | | **CoreGraph** | 带有置信度标记的边的、有类型的、跨文件、多语言图 | — | CoreGraph 专为答案跨越文件和语言的代码库而构建： 映射到 Go 处理程序的 TypeScript 路由、由配置注入的 Spring bean、跨服务重复的 枚举值。它可以回答“谁调用这个”、“如果我更改这个会发生什么”、“什么是死代码”以及“哪里存在分歧”——一次性跨越 所有内容。 ## 快速开始 ``` # 从 npm 安装 CLI —— 将 `coregraph` 添加到你的 PATH npm install -g @coregraph/cli # ...稍后升级到最新版本： npm install -g @coregraph/cli@latest # ...或者在不安装的情况下运行： npx @coregraph/cli@latest # ...或者从源码构建： cargo build --release (二进制文件位于 target/release/) # 检查已安装的版本： coregraph --version # 索引当前项目（首次运行时会创建 .coregraph/config.toml） coregraph index --stats ``` ``` coregraph: skipped 1 minified/generated file(s) (e.g. ./vscode-extension/media/cytoscape.min.js) Index complete — 281 files, 3396 symbols, 21342 edges (2337ms) ``` 第一次查询会自动生成一个后台 daemon，并为 随后的每个命令重用缓存的图。 ### 查找谁调用了某个函数 ``` coregraph query compute_impact \ --direction incoming --edge-kind calls --hop-limit 1 ``` ``` ── query: compute_impact ────────────────────────────────── ✓ compute_impact [crates/query/src/impact.rs:27] kind: Function | package: query (cargo) Incoming (14): ├── calls ← run [Function] @ crates/cli/src/commands/diff.rs [0.85] ✓ ├── calls ← run [Function] @ crates/cli/src/commands/impact.rs [0.85] ✓ ├── calls ← cached_impact [Function] @ crates/cli/src/dispatch.rs [0.85] ✓ ├── calls ← api_impact [Function] @ crates/server/src/handlers.rs [0.85] ✓ └── ... (14 total) ✓ trust: all paths verified ── page 1/1 | 14 edges total | budget: 506/5600 tokens ── [n]ext page | [e]xpand | [f]ilter --edge-kind | [q]uit ``` 每条边上的 `[0.85] ✓` 是其置信度分数。 ### 查看变更的影响范围 ``` coregraph impact build_router --risk ``` ``` Impact of 'build_router': 1251 reachable symbols, 1251 edges, depth 3 Risk Score: 0.96 (Critical) Blast Radius: Critical (16 modules, 910 callers) Confidence-Weighted Impact: 653.500 Affected tests: 334 test_app (distance 2, path_confidence 0.90) — ./crates/server/src/handlers.rs create_app_returns_router (distance 2, path_confidence 0.90) — ./crates/server/src/lib.rs ... (more affected tests) ``` ### 查找死代码候选 ``` coregraph orphans --exclude-tests ``` ``` Orphan symbols (12): 7 likely dead, 5 library API surface, 0 test code as_kebab [Method] — crates/cli/src/commands/query.rs strip_api_path_prefix [Function] — crates/extractor/src/string_literal_extractor.rs [library API] unregister [Method] — crates/graph/src/hooks.rs [library API] outputChannel [Constant] — vscode-extension/src/extension.ts ... ``` 标记为 `[library API]` 的符号是公共接口——可以从 crate 外部访问， 因此与完全未被引用的符号相比，其置信度标记较低。 ### 检测跨文件不一致 ``` coregraph inconsistencies ``` ``` Inconsistencies (63): [enum-mismatch] 'admin' appears in: - Permission.ADMIN (./tests/e2e/golden/04-inconsistencies/src/permissions.ts) - Role.ADMIN (./tests/e2e/golden/04-inconsistencies/src/roles.ts) [api-path] /a.rs vs /b.rs ... ``` 使用 `--category ` 缩小报告范围。 检测器可以通过 `[inconsistencies]` 配置部分针对每个项目进行调优： `disable = ["api-path"]` 会在“运行所有分析”模式下关闭某个类别（在仅含前端、路由字面量没有 对应服务端的仓库中非常有用——显式的 `--category` 仍然会运行它），而 `api_path_min_segments`（默认为 `2`） 设定了近失匹配段数的下限。 ### 在不熟悉的代码库中确定方位 ``` coregraph stats --breakdown ``` ``` symbols: 4136 edges: 24993 ## Symbol 种类 Function 1480 DocComment 709 Method 473 ... ## 每个 package 的 symbol/edge 数量 package symbols edges (no package) 1391 8058 coregraph 736 5634 coregraph-extractor 510 3902 ... ## 被引用次数最多的前 20 个 symbol（in-degree；排除 containers） 250 SymbolId [Struct] @ ./crates/core/src/symbol.rs 149 clone [Method] @ ./crates/graph/src/bloom.rs 122 nodes [Method] @ ./crates/graph/src/symbol_graph.rs ... ## 按 symbol 数量排名前 20 的文件 133 ./crates/cli/src/dispatch.rs 116 ./crates/extractor/src/lib.rs 110 ./crates/graph/src/symbol_graph.rs ... ``` 包信息来自项目自身的清单（Cargo 工作区、npm/pnpm 工作区、Maven/Gradle 模块）；入度排名仅计算真实符号之间具有 实质性影响的边，因此文件容器和文档节点 不会淹没真正的核心枢纽。 在您不熟悉的仓库上从这里开始——被引用最多的符号和最密集的 文件正是架构实际所在之处。 ### 通过 `file:line` 查找符号 ``` coregraph inspect crates/query/src/impact.rs:33 ``` ``` ── inspect: crates/query/src/impact.rs:33 ── compute_impact [Function] bytes 1128..3581 doc::compute_impact [DocComment] bytes 531..1128 32 /// depends on (outgoing) does not break when X changes. → 33 pub fn compute_impact(graph: &SymbolGraph, seed_id: SymbolId, max_depth: usize) -> ImpactResult { 34 let mut visited: HashSet = HashSet::new(); ``` 解析位于光标位置的符号——其名称、种类、字节范围 以及周围的源代码（默认 5 行，`--context-lines`）。只有当查询位置落在文档注释自身的跨度内时，才会出现 `doc::… [DocComment]` 行（如上例所示）；检查符号体内的某一行不会拉取该符号的文档注释，并且 JSON 输出和 编辑器/IPC 的 `inspect` 路径不携带文档注释数据。 ### 查看函数依赖于什么 ``` coregraph query compute_impact \ --direction outgoing --edge-kind calls --hop-limit 1 ``` ``` ── query: compute_impact ────────────────────────────────── ✓ compute_impact [crates/query/src/impact.rs:27] kind: Function | package: query (cargo) Outgoing (3): ├── calls → incident_edges [Method] @ crates/graph/src/symbol_graph.rs [0.85] ✓ ├── calls → is_impact_bearing [Function] @ crates/query/src/impact.rs [0.85] ✓ └── calls → clone [Method] @ crates/graph/src/bloom.rs [0.85] ✓ ✓ trust: all paths verified ``` 与“谁调用了函数”的查询相同，只是方向相反：`--direction outgoing` 遍历到 被调用者/依赖项，`incoming` 遍历到调用者。 ### 将结果通过管道传递给脚本或您的 AI 助手 ``` coregraph query build_router --direction outgoing --edge-kind calls \ --output-format json | jq -r '.edges[] | "\(.other_name) [\(.current_confidence)]"' ``` ``` new [0.95] route [0.95] post [0.95] clone [0.95] dispatch [0.95] ... (22 total) ``` 每个分析命令（`query`、`impact`、`diff`、`orphans`、 `inconsistencies`、`stats`、`inspect`、`index`）都支持 `--output-format json`，因此 结果可以直接导入脚本和 CI 门禁（`llm` 由通过 LLM 渲染器路由的命令支持；`stats`/`inspect`/`index` 会为此回退到人类文本）。要进行实时的编辑器/agent 使用，请运行 `coregraph lsp` 或 `coregraph mcp`——请参阅[集成](#integrations)。 ## 核心功能 - **Token 预算控制，适配 LLM。** `--output-format llm` 输出紧凑的 结构化文本，每个结果都根据 `--token-budget` 进行分页， 并且 `--min-confidence` 会剔除低信任度的噪音——因此 agent 每个答案只需花费几百个 token，而不是摄取整个文件。 - **多语言，一个图。** 七种代码语言加上配置和 Markdown， 统一到一个索引中——专为 monorepo 构建。 - **跨文件名称解析。** stack-graphs 将引用绑定到 它们实际解析到的跨文件的定义上。 - **每条边都有置信度和信任度。** 每个关系都有评分和 来源标记；使用 `--min-confidence` 进行过滤（默认 `0.70`）。 - **影响和风险分析。** 传递可达性加上风险评分、 影响范围，以及变更影响的测试。 - **死代码检测。** 孤立符号，区分可能是死代码的符号与公共 库接口。 - **跨文件不一致性检查。** 枚举值不匹配、API 路径漂移、 配置键漂移以及文档漂移（`@param`/`:param` 命名了 签名中不再存在的参数——并会从实际签名中建议重命名候选者）。可以通过 `config.toml` 中的 `[inconsistencies]` 针对每个项目调整类别。 - **配置自调优。** `coregraph config recommend` 会测量已索引的 图并建议 `config.toml` 的调优（排除列表、字符串匹配上限、 类别禁用）；`--write` 会应用它而不会破坏注释。 - **后台 daemon。** 首次使用时自动生成，缓存图，并在 空闲时自动终止——重复查询速度快，未使用时无驻留开销。 - **内置集成。** 用于 LLM agent 的 MCP、用于编辑器的 LSP，以及 可选的 HTTP API。 - **3D 可视化。** `coregraph viz` 打开一个在浏览器内交互的 全图全景图，由 daemon 实时提供数据。 ## 可视化：coregraph atlas ``` coregraph viz # serves http://127.0.0.1:7321 and opens the browser coregraph viz --detach # same, in the background; logs to viz.log coregraph viz --stop # stop the detached server ``` `coregraph viz` 启动一个本地服务器（仅限 127.0.0.1，受 token 保护），提供 符号图的 3D 力导向视图，直接从 daemon 内存中读取——无需导出步骤。如果 daemon 没有运行，系统会为您启动它， 并且项目选择器会列出所有已加载的内容。`--detach` 运行 独立于终端会话外的服务器（在终端关闭后依然存活），并在 端口响应后返回；`--stop` 会终止上次 `--detach` 记录的实例。

您可以在查看器中执行以下操作： - **探索** —— 模糊符号搜索，隔离周边节点（深度 1–3）， 检查任何符号及其关联边和源代码预览。 - **按单元聚类** —— 在半透明的边界球体内按模块/包/crate（源自 路径结构）对节点进行分组，如上所示。 - **在图上运行分析** —— 影响分析会将影响范围绘制为 跳跃距离渐变色，并显示风险分数和受影响的测试；死代码、 跨文件不一致、git-diff 影响以及两个符号之间的最短路径均只需 点击一下即可查看。 - **过滤** —— 符号/边类型、分析来源、最低置信度、 最小度和核心枢纽修剪，按类型/目录/单元着色。 - **分享与导出** —— 复制可恢复确切视图的链接，下载 PNG 截图或将可见子图导出为 json-graph。 - **保持新鲜** —— 查看器会轮询 daemon，并在 磁盘上的图发生变化时提供一键重新加载；它绝不会在您不知情的情况下重置您的镜头视角。

## 工作原理 ``` source files │ ▼ tree-sitter ──► symbols (functions, structs, config keys, doc comments, …) │ ▼ stack-graphs ─► cross-file name resolution (calls, imports, references) │ ▼ symbol graph (in memory) ──► confidence/trust-tagged edges │ ▼ background daemon ──► IPC socket │ MCP │ LSP │ HTTP ``` `coregraph index` 会在一次过程中运行两个分析层。生成的图由 后台 daemon 持有，该 daemon 会： - **自动启动** 在第一个瘦客户端命令（`query`、`stats`、`impact`、 `orphans`、`inconsistencies`、`lsp`、`mcp`）时。使用 `--no-auto-start（或 `COREGRAPH_NO_AUTO_START=1`）改为在进程内构建。 - **自动终止** 在完全空闲 `server start --auto-stop-minutes `（默认为 30） 分钟后；`0` 则禁用。 - **缓存多个项目** 在 LRU 下（`server.max_loaded_projects`， 默认 5），并带有可选的总堆字节预算 （`server.max_loaded_bytes`，`0` = 无限制）。 - **选择性提供 HTTP 服务** 通过 `coregraph server start --http`。 ### 内存图管理 daemon 仅在项目图有用时才将其保留在内存中， 因此空闲的工作站会自动回收内存： - **空闲卸载（持久化后释放）。** 空闲时间达到 `server.idle_unload_minutes`（默认 10）的项目将从内存中清除。在 释放之前——同样在 LRU 或字节预算驱逐它时——自上次 保存以来发生更改的图将被写入 `.coregraph/snapshot.bin`。写入 操作在缓存锁之外进行，因此它永远不会阻塞并发查询，并且 干净（未修改）的图会被跳过以避免多余的磁盘读写。 - **热重启。** 下一次查询卸载的项目时，会从磁盘**热加载** 快照，而不是重新运行 tree-sitter 提取——*除非*任何 源文件比快照记录的构建时间更新，在这种情况下它会 从源代码重建。因此，热加载速度很快，但绝不会提供过期的数据。 - **墓碑垃圾回收。** 被删除的符号会先被标记为墓碑，然后 一旦超过 5 分钟的宽限期，后台清理程序就会从每个 已加载的图中清除它们，回收它们的节点、边和索引条目。 - **紧凑存储。** 文件路径被驻留（`Arc`），因此同一个 文件中的每个符号在内存中共享一个路径分配，而不是持有私有 副本。快照本身在每个节点/边上存储路径，因此当快照重新加载到内存时，共享会被重新建立。 每个项目的图都经历一个简单的生命周期——按需加载， 从内存中提供服务，并在空闲后（在持久化之后）卸载： ``` graph LR U[Unloaded] -->|first query| A[Active] A -->|cache hit| A A -->|idle / evict| U A -->|all idle| S([Daemon stops]) ``` 其中 _首次查询_ 会热加载快照（或重建），_空闲/驱逐_ 在释放之前持久化已更改的图，而 _全部空闲_ 会自动停止 daemon——如上所述。

详细流程 —— 加载路径、驱逐和清理器

**加载路径** —— 单个查询解析为的内容： ``` graph TD Q[Query] --> C{In cache?} C -->|hit| H[Serve from memory] C -->|quiescing| R[Revive] C -->|stale: source newer| E[Evict stale] C -->|miss| B{Snapshot fresh?} R --> H E --> B B -->|yes| W[Warm-load: skip extraction] B -->|no/missing| F[Rebuild: tree-sitter + stack-graphs] W --> H F --> H ``` **驱逐（持久化后释放）** —— 图如何在不丢失 更改或阻塞并发查询的情况下离开内存： ``` graph TD T[Trigger: idle / LRU / byte budget] --> M[Mark victims under lock] M --> P{Changed since save?} P -->|yes| W[Persist snapshot off-lock, atomic] P -->|no| K[Skip write] W --> RC{Still idle?} K --> RC RC -->|yes| D[Drop from cache, memory freed] RC -->|query arrived| RV[Revive, keep Active] ``` **后台清理器** —— 每 60 秒执行一次操作，完成三件事： ``` graph LR S[Sweeper tick every 60s] --> A[sweep_idle: unload idle projects] S --> G[gc_loaded: reap Gone nodes past 5min] S --> C{All idle past auto_stop?} C -->|yes| X[persist all dirty, then exit] C -->|no| N[wait next tick] ```

快照是 bincode 二进制数据块（schema v6，携带图的构建时间）。 使用 `coregraph snapshot save --out ` / `coregraph snapshot load ` 手动保存和重新加载图，或者在索引时通过 `index --snapshot ` 附加一个。 ### 置信度与信任度 存储的边置信度为 `base(edge_kind) × base(origin)`，限制在 `[0,1]` 范围内 （在创建边时计算一次）。查询输出中显示的实时 `current_confidence` 是 `base(origin)` 经过每个过期证据项乘以 0.7 衰减后的结果——过期 衰减仅适用于来源基准，而不适用于存储的乘积。五种 分析来源，从高到低的基准置信度依次为： | 来源 | 基准 | 含义 | |--------|------|---------| | CompilerDerived | 0.99 | 编译器级别的事实 | | NameResolved | 0.95 | 由 stack-graphs 解析 | | SyntaxMatched | 0.85 | 语法匹配 (tree-sitter) | | PatternMatched | 0.60 | 通过已知框架模式匹配 | | ConventionInferred | 0.40 | 从命名/结构约定推断 | 边还携带四种信任模型之一——`SourceEvidenced`、 `ContractDependent`、`Bidirectional`、`ExternallyMediated`。请参阅 [`docs/confidence.md`](docs/confidence.md) 和 [`docs/graph-model.md`](docs/graph-model.md) 获取完整的 schema。 ## 语言支持 所有七种代码语言都具备**双重**符号提取和跨文件名称 解析功能。仅当语言没有规则，或解析未产生绑定时，名称解析才会退回到 tree-sitter 语法匹配。 | 语言 | 符号提取 (tree-sitter) | 名称解析 (stack-graphs) | |----------|:-------------------------------:|:------------------------------:| | Java | ✓ | ✓ (上游) | | TypeScript | ✓ | ✓ (上游) | | JavaScript | ✓ | ✓ (上游) | | Python | ✓ | ✓ (上游) | | Go | ✓ | ✓ (手工编写的 `.tsg`) | | Rust | ✓ | ✓ (手工编写的 `.tsg`) | | Kotlin | ✓ | ✓ (手工编写的 `.tsg`) | | YAML / TOML / JSON | ✓ (→ `ConfigKey` 节点) | — | | Markdown | ✓ (文档层) | — | CoreGraph 手工编写的规则位于 `crates/stack/rules/{go,rust,kotlin}.tsg` 中。 ## CLI 概览 `coregraph ` —— 运行 `coregraph --help` 获取完整的标志列表。 | 命令 | 用途 | |---------|---------| | `index` | 索引源文件并构建符号图 | | `query` | 查询符号（邻居、调用者、被调用者） | | `inspect` | 在 `FILE:LINE` 处检查符号及其源代码上下文 | | `stats` | 图统计信息（`--breakdown` 查看直方图） | | `orphans` | 列出孤立符号（死代码候选） | | `impact` | 某个符号的影响分析（`--risk` 添加评分） | | `diff` | git diff 的影响：变更会触及哪些符号 | | `review` | 自动对 GitHub PR 进行评论，附带差异影响摘要 | | `inconsistencies` | 检测枚举 / api-path / config-key / 文档漂移问题 | | `export` | 导出图 (`dot` \| `cypher` \| `json-graph`) | | `viz` | 在 `127.0.0.1:7321` 提供 3D 图查看器 (atlas) 服务 (`--detach` / `--stop`) | | `snapshot` | `save` / `load` 二进制快照 | | `config` | `init` / `show` / `unset` / `path` / `recommend` | | `server` | Daemon 管理：`start` / `stop` / `status` / `restart` / `install` / `uninstall` | | `lsp` | LSP stdio 桥接 | | `mcp` | MCP stdio 桥接 | | `watch` | 监视文件并重建图 | | `batch` | 从 JSON 文件运行多个查询 | | `plugin` | 管理插件钩子：`list` / `run` | 常用的全局选项适用于每个命令：`--output-format `、 `--min-confidence <0.0–1.0>`（默认 `0.70`）、`--hop-limit `（默认 `3`）、 `--token-budget `（默认 `8000`）、`-C/--project `，以及预设 `--fast` / `--standard` / `--full`。 请参阅 [`docs/cli.md`](docs/cli.md) 获取完整的参考手册。 ## 与 AI 编程 agent 配合使用 CoreGraph 提供了一个现成的工具包，以便任何 AI 编程 agent 都可以使用它——并且对于结构性问题（调用者、变更影响、死代码、跨文件 不一致），相比原始的 grep/read 扫描更倾向于使用它。所有内容都位于 [`agents/`](agents/README.md) 下：Claude Code 插件、一个您可以放入自己项目的 `AGENTS.md`，以及用于 Codex、Gemini CLI 和 opencode 的复制粘贴式 MCP 配置。所有这些都指向同一个指导来源——内置的 技能。 **Claude Code** —— 安装插件（注册技能和 `coregraph mcp` 服务器）。 通过其 `marketplace.json` URL 添加市场仅会下载小型目录——无需 克隆仓库——且插件是稀疏获取的（仅限 `agents/coregraph`）： ``` /plugin marketplace add https://raw.githubusercontent.com/simplecore-inc/coregraph/main/.claude-plugin/marketplace.json /plugin install coregraph@coregraph ``` **Codex / Gemini CLI / opencode** —— 注册 `coregraph mcp` 并使用 `AGENTS.md`。有关 特定于 agent 的确切设置，请参阅 [`agents/README.md`](agents/README.md)。 ## 集成 除了终端之外，CoreGraph 还支持三种机器协议。详情请参阅 [`docs/integrations.md`](docs/integrations.md)。 ### MCP —— `coregraph mcp` 为 LLM agent 提供的 stdio JSON-RPC 桥接，公开了六个工具（纯名称，无 前缀）： | 工具 | 输入 | 返回 | |------|-------|---------| | `query` | `{name}` | 跨项目匹配某个名称的符号 | | `impact` | `{name, transitive? = false, depth = 5}` | 某个符号的传递依赖项（如果它发生变化，谁会遭到破坏），直至 `depth`（默认为 5）；`transitive` 仅改变输出标签，因此传入 `depth: 1` 仅获取直接依赖项 | | `orphans` | `{}` | 死代码候选：没有传入或传出边的代码符号 | | `inconsistencies` | `{}` | 跨文件不一致：枚举 / api-path / config-key（文档漂移仅限 CLI） | | `stats` | `{}` | 图形摘要：符号计数和边计数 | | `recommend` | `{}` | 基于索引图推荐的 `.coregraph/config.toml` 调优：`[index]`/`[analysis]` 排除候选、字符串匹配上限、api-path 类别禁用（仅作建议——不会写入任何内容） | 使用 MCP 客户端（Claude Code `.mcp.json` 或 `claude_desktop_config.json`）注册它： ``` { "mcpServers": { "coregraph": { "command": "coregraph", "args": ["mcp"] } } } ``` ### LSP —— `coregraph lsp` 为编辑器提供的 stdio LSP 桥接。提供三种方法： - `textDocument/definition` - `textDocument/references` - `workspace/symbol` ### HTTP —— `coregraph server start --http` 可选的 REST API，默认绑定到 `127.0.0.1:27787`（使用 `--allow-external` 绑定非 localhost 地址）。 | 方法 | 路由 | 用途 | |--------|-------|---------| | GET | `/health` | 存活状态 + 版本 + 符号计数 | | POST | `/query` | 按名称查找符号 | | POST | `/batch` | 一次运行多个名称查询 | | GET | `/api/query` | 分页符号查询（`page`/`page_size`）；`budget` 参数作为元数据回显，但不会截断响应 | | GET | `/api/expand` | 展开节点的传入/传出边（返回所有边；其 `budget` 参数同样仅用于回显） | | GET | `/api/impact` | 某个符号的传递影响 | | GET | `/api/source` | `FILE:LINE` 周围的源代码片段 | ## 配置 首次索引时，会在 `/.coregraph/config.toml` 创建一个 针对每个项目的配置文件。使用 `coregraph config show` 查看有效配置： ``` limits.token_budget = 8000 [project] limits.hop_limit = 3 [project] limits.min_confidence = 0.7 [project] server.max_loaded_projects = 5 [project] server.graceful_shutdown_sec = 30 [project] server.idle_unload_minutes = 10 [project] server.max_loaded_bytes = 0 [project] ``` 所有 `server.*` 键都会在启动时被 daemon 读取（项目本地配置 会覆盖全局配置）。`config.toml` 示例： ``` [limits] hop_limit = 3 # query traversal depth min_confidence = 0.7 # minimum edge confidence to report token_budget = 8000 # LLM-mode page size [server] max_loaded_projects = 5 # daemon LRU cache size (project count) max_loaded_bytes = 0 # total heap budget across loaded graphs; 0 = unlimited idle_unload_minutes = 10 # unload (and snapshot) a project after this idle time graceful_shutdown_sec = 30 # in-flight grace before hard-exit [index] exclude = [] # gitignore-syntax patterns to skip during indexing string_match_max_files = 8 # skip cross-file StringMatch pairing for a string # found in more than N distinct files (convention # strings would otherwise emit O(k²) edges); 0 = unlimited [analysis] exclude = [] # files still parsed (their edges survive) but hidden from # dead-code (orphans) reports — for generated consumers [inconsistencies] disable = [] # categories to skip when running without --category, # e.g. ["api-path"] in a frontend-only repo api_path_min_segments = 2 # minimum non-empty path segments for an api-path # near-miss report ``` 配置会进行 lint 检查：`coregraph index` 会在 stderr 上发出警告（并且 `config show` 会在线标记）有关 TOML 语法错误、未知部分和未知键的信息， 而不是静默忽略它们，并且格式错误的 `exclude` 模式会 被跳过并发出警告，而不是禁用其他模式。索引 完成后，以数据符号（如 i18n 包、生成的文档）为主的文件会被 建议为人类可读输出中的 `[index].exclude` 候选项。 您还可以让系统为您测量调优：`coregraph config recommend` 会从索引图中得出 `[index].exclude`、`string_match_max_files`、 `[inconsistencies].disable` 和 `[analysis].exclude` 的建议值， 并将它们作为随时可粘贴的 TOML 块打印出来，每条建议都有一个理由。 `coregraph config recommend --write` 会将它们原地合并到 `config.toml` 中—— 和现有条目会被保留，数组会在不产生 重复项的情况下追加，并且如果文件无法解析，合并将中止（不写入任何内容）。 任何限制都可以在每次调用时通过 `--hop-limit`、 `--min-confidence` 或 `--token-budget` 进行覆盖。全局配置也位于 平台配置目录（`dirs::config_dir()`）中——在 Linux 上，这里遵循 `$XDG_CONFIG_HOME/coregraph/config.toml`，在 macOS 上则是 `~/Library/Application Support/coregraph/config.toml`（运行 `coregraph config path` 以打印确切位置）。 ## 故障排除 - **编辑文件后结果过期。** 重新运行 `coregraph index` —— 它总是会 从源代码重建图，并且从不重用现有的快照，因此 普通的重新索引已经是完全全新的构建。对于持续更新， `coregraph watch`（默认增量；`--no-incremental` 强制完全 重建）。 - **不想要后台 daemon。** 传入 `--no-auto-start`，或者设置 `COREGRAPH_NO_AUTO_START=1`，以便在进程内构建和回答。 - **Daemon 无法停止 / 已过期。** 执行 `coregraph server stop`，然后重新运行您的 命令以重生新的 daemon。检查 `coregraph server status`。 - **嘈杂的 `inconsistencies` 输出。** 仓库自身的测试夹具可能会产生 仅限夹具的噪音。使用 `--category ` 缩小范围， 在 `config.toml` 的 `[index]` 下添加 `exclude` 模式，或者通过 `[inconsistencies] disable = ["api-path"]` 为项目禁用在结构上无关的类别（提高 `api_path_min_segments` 以获得更宽松的过滤）。当少数数据文件在符号计数中占主导地位时，`coregraph index` 也会打印排除候选项的建议。 - **`orphans` 将公共 API 列为死代码。** 标记为 `[library API]` 的符号是 公共接口；使用 `--public-only=false` 来包含私有符号，或者 使用 `--exclude-tests` 丢弃测试代码。 - **无法从另一台主机访问 HTTP API。** 它默认绑定 localhost； 添加 `--allow-external`（并查阅 [`docs/security.md`](docs/security.md)）。 ## 文档 - [`docs/overview.md`](docs/overview.md) —— 项目意图和设计理念 - [`docs/architecture.md`](docs/architecture.md) —— Crate 布局和 runtime - [`docs/cli.md`](docs/cli.md) —— 完整的 CLI 参考 - [`docs/graph-model.md`](docs/graph-model.md) —— 节点/边 schema 和信任层级 - [`docs/confidence.md`](docs/confidence.md) —— 置信度和信任度数学原理 - [`docs/change-tracking.md`](docs/change-tracking.md) —— 文件监视和增量更新 - [`docs/integrations.md`](docs/integrations.md) —— MCP / LSP / HTTP 详情 - [`docs/security.md`](docs/security.md) —— 威胁模型和绑定控制 - [`docs/contributing/development.md`](docs/contributing/development.md) —— 从源码构建、本地安装和开发工作流 - [`docs/contributing/testing.md`](docs/contributing/testing.md) —— 测试策略、测试夹具和 e2e 套件 - [`docs/roadmap.md`](docs/roadmap.md) —— 状态和未来计划 - [`CHANGELOG.md`](CHANGELOG.md) —— 用户可见的更改 ## 许可证 MIT —— 详见 [`LICENSE`](LICENSE)。

标签：LLM集成, Rust, SOC Prime, tree-sitter, 代码搜索, 可视化界面, 开发工具, 网络流量审计, 通知系统, 错误基检测, 静态代码分析