Kivgraph

Kivgraph

说明

Kivgraph 最初是一个研究项目。 它探索了本地语义代码图能否减少编码 Agent 需要检查的上下文量。

最终形成的工具仍适用于结构化代码导航、跨代码库关系和影响分析。不过，这项研究并未证明它能在长期端到端 Agent 对话中可靠地净节省 token。某些孤立查询相比 grep 加读取文件确实能显著减少 token 用量，但这些节省并未始终转化为现实的长期运行 Agent 工作流中的 token 用量降低。

基准测试结果及其局限性保存在 benchmarks/ 中，其中包括端到端 Agent 基准测试。

Kivgraph 是面向 AI 编码 Agent 的本地跨代码库代码智能 MCP 服务。它会在多个已注册代码库中构建规范化语义代码图，并回答有关符号、代码库关系、调用方、依赖项和变更影响的问题。

观看 Kivgraph UI 演示视频

kivgraph ui — 已发布图的只读 3D 视图。

它会为代码库建立一次索引，并提供不可变的图：边由 go/types、TypeScript 检查器和 rust-analyzer 解析，而非通过匹配名称得到。这就是它与搜索工具的区别，也让空结果具有意义——空引用列表表示没有任何地方调用它，而不是没有找到内容；grep 无法区分这两种情况。

Kivgraph 专注于语义代码关系，而非自动发现服务之间所有 HTTP、gRPC、Kafka 或数据库运行时流。

文档

请阅读 Kivgraph 用户文档，了解安装、MCP 客户端、代码智能、代码库关系和工作区代码图。本次检出中的 landing/src/content/docs 内容也来自这些页面，因此即使读者使用的是分支版本或无法联网，也能阅读文档。

每个工具回答什么问题

问题	工具
谁调用了它，哪些内容引用了它	find_references
谁实现了某个类型或方法	find_implementations
如果我更改它，会造成什么影响	get_blast_radius
它会向外依赖哪些内容	trace_dependencies
另一个仓库中的谁在使用它	find_cross_repo_consumers
它在哪里声明	find_symbol
我不知道它叫什么，要打开哪些文件	find_by_intent
这个包中声明了什么	get_file_outline
给我这些符号的代码	get_source
关于这个符号的所有信息	get_symbol
索引了什么，图是否为最新	list_repositories，graph_status
异步索引的进度如何	get_index_status

十三个只读工具，另有两个需经同意的变更操作（index_project 和 start_index_project），客户端必须先授权，才能通过任一操作注册仓库或 发布一个版本。

每条包含符号的结果都会附带其仓库、路径、限定名称和行范围，因此无需 再次调用即可打开；每个工具也都接受这组信息，以代替不透明的键。

不足之处。 在小型仓库中查找罕见名称，用 grep 更省事；索引小文件 的成本也高于直接读取。它在查找常见名称、分析传递影响、查找其他仓库中的 使用者以及证明某项内容不存在方面更胜一筹。在包含 37 个仓库的语料库中， 针对 29 个问题进行的测量结果如下 （benchmarks/graph-tools-comparison/results-all.json，提交 954b9eb， 分词器 o200k_base）：Kivgraph 消耗 35,961 个 token，而 grep 加读取 消耗 267,980 个 token；两者在 29 个问题中的 28 个上结果完全准确， 按问题计算的中位数显示，Kivgraph 更省 5.95x。其中有 5 个问题使用 grep 成本更低，且双方召回率均为 100%：T1_go_trivial 要查找一个在语料库 中声明了两次的名称，此时 grep 的成本仅为 Kivgraph 的 0.53x。

第二个测试工具 benchmarks/mcp-token-cost 会与主机自身逐字捕获的工具输出 进行比较，但它仅针对 Kivgraph 自身一个含 13,222 个符号的仓库运行：仅答案 本身的成本为 7.64x，整个会话的成本为 1.60x；源代码主体是两种方案都需 付出的成本，因此设定的下限为 2.41x。

状态

已发布并投入使用。kivgraph version 会报告已发布的版本；待办事项及每个 阶段的验收门槛见 TASKS.md。

• **语言：**Go、TypeScript、Rust、Python 和 Dart。Python 在回退模式下使用 随附的 AST 工作进程；这些推断出的引用标记为 CANDIDATE，绝不会标记为 EXACT。Python 精确模式使用随附的 Pyright LSP 适配器，并要求已安装 Pyright/BasedPyright 服务端。Dart 使用 Dart 或 Flutter SDK 提供的 Dart Analysis Server。
• **语义依赖：**当且仅当恰有一个已注册的提供方拥有所请求的包时，Python 和 Dart 导入可以发布包依赖；符号级跨仓库边则要求明确指定提供方身份。
• **接口：**通过 STDIO 提供十三个只读工具，另有两个需经同意的变更操作 （index_project 和 start_index_project）。接口约定见 docs/protocol/mcp-surface-v3.md。
• **存储：**LadybugDB 是权威存储；查询由不可变的 HotSnapshot 提供服务，该快照 以原子方式发布，查询绝不直接访问数据库。
• 平台：linux/amd64、darwin/arm64 和 windows/amd64。
• 查看器：kivgraph ui 会提供已发布图的只读 3D 视图。

安装

用一个脚本安装 MCP

安装程序会检测平台，为其下载最新发布的 MCP 版本，验证发布档案和软件包校验和，然后完成安装，无需 Go 或 pnpm。发布包包含 Go 服务、固定版本的 LadybugDB 库、TypeScript 工作线程、打包的 Python AST 工作线程、固定版本的 rust-analyzer、语法清单和 Web 查看器；查看器资源占软件包的 2.3 MB。需要不含查看器的软件包时，可运行 scripts/build-bundle.sh --mcp-only。对于要打包 .mcpb 的用户，--slim 会进一步精简：去掉固定版本的 rust-analyzer 和调试器会读取的所有符号，打包后大小为 24.9 MB，而非 46.3 MB。之后不会再下载任何内容，因此该软件包只有在机器的 PATH 中已有分析器时才能读取 Rust。

已发布的软件包：Linux amd64、macOS arm64 和 Windows amd64。

运行时要求：Linux 和 macOS 上需要 Bash，Windows 上需要 PowerShell 5.1 或更高版本；Node.js 22 或更高版本；索引 Python 时需要 Python 3.10 或更高版本；POSIX 平台上需要 curl、tar 和 sha256sum 或 shasum。软件包自带 rust-analyzer；索引 Rust 仓库还需要 PATH 中有 cargo，索引 Dart 则需要 Dart 或 Flutter SDK。在 Windows 上，安装程序还会安装 Visual C++ 可再发行组件，否则 kivgraph.exe 无法启动。

macOS 上的二进制文件未经公证。通过 curl 下载的发布版本不会被隔离，可以直接运行；通过浏览器下载的副本需要运行 xattr -dr com.apple.quarantine。请参阅 docs/development/macos.md。

用一条命令安装最新版本。在 Linux 和 macOS 上可以使用同一行命令，因为安装程序会读取 uname 并选择对应的档案：

curl -fsSL https://kivgraph.dev/install.sh | bash

在 Windows 上，由于没有 POSIX shell，无法运行 install.sh：

irm https://kivgraph.dev/install.ps1 | iex

install.ps1 是另一种实现，执行相同的解压前检查；如果任一脚本新增了另一方没有的检查，internal/release/install_parity_test.go 就会报错。将其传入 Invoke-Expression 会把 #Requires -Version 5.1 当作注释；请将其下载到文件后再运行，以保留该版本限制。

从检出目录中可直接运行任一安装程序：

./scripts/install.sh

要安装指定版本，而不是最新版本：

KIVGRAPH_VERSION=v0.9.10 ./scripts/install.sh

脚本会将软件包安装到 ~/.local/opt/kivgraph，并将启动器放入 ~/.local/bin；在 Windows 上，安装位置分别为 %LOCALAPPDATA%\Programs\kivgraph 和 %LOCALAPPDATA%\Programs\kivgraph-bin。它绝不会修改已注册的仓库、创建索引或替换配置文件。要使用其他位置，请设置 KIVGRAPH_INSTALL_ROOT 和 KIVGRAPH_BIN_DIR。

将启动器目录添加到当前 shell，并验证两种运行时：

export PATH="$HOME/.local/bin:$PATH"
kivgraph version
kivgraph-ts-worker <<'EOF'
hello
EOF

检查是否有更新版本，或更新已安装的软件包：

kivgraph update --check
kivgraph update

软件包会以原子方式替换，保留配置和图状态，验证发布版本和软件包校验和，并替换已安装的软件包。安装后的运行时刷新可能只完成部分操作后失败，并导致命令以非零状态退出。它还会重启已安装的受监管守护进程，并刷新由 Kivgraph 管理的用户钩子、技能和 MCP 注册项。过期的监管程序会返回错误，且不会重启。缺失的、由其他程序管理的以及项目级集成都会保持不变。客户端拥有的 serve 和 ui 进程仍需重启，或使用 --stop，才能使用新二进制文件。

开发构建使用独立的预发布渠道。显式安装一个版本，然后为后续检查选择该渠道：

release=vX.Y.Z-dev.N
curl -fsSL \
  "https://github.com/Luqueee/kivgraph/releases/download/$release/install.sh" |
  KIVGRAPH_VERSION="$release" bash
kivgraph update --channel dev

对于预发布二进制文件，省略 --channel 时默认使用 dev；稳定版安装仍会使用稳定渠道。也可以使用 KIVGRAPH_UPDATE_CHANNEL 代替该标志，包括用于交互式更新通知。

要移除已安装的软件包和启动器，同时保留配置、仓库注册项和图状态：

uninstall_url=https://github.com/Luqueee/kivgraph/releases/latest/download/uninstall.sh
curl -fsSL "$uninstall_url" -o /tmp/kivgraph-uninstall.sh
bash /tmp/kivgraph-uninstall.sh

如果需要以非交互方式卸载，请运行 bash /tmp/kivgraph-uninstall.sh --yes。 Windows 用户可以使用 PowerShell 运行对应的 uninstall.ps1。

在交互式终端中调用 kivgraph 时如果未指定命令，它会以 800 ms 超时检查是否有更新版本，并在平台缓存目录（Linux 上的 $XDG_CACHE_HOME，macOS 上的 $HOME/Library/Caches）中的 kivgraph/update-check.json 文件里缓存 24 小时。 网络不可用时，这项可选检查不会阻塞命令。

如果输出目标是终端，交互式命令输出会使用语义化 ANSI 颜色。设置 NO_COLOR 或重定向输出即可获得纯文本。

配置 Kivgraph 和编码 Agent

交互式安装版本后，安装程序会询问是否运行同一套引导式设置。也可以稍后运行，或直接在检出目录中运行：

kivgraph configure

configure 会打开一个选择器，列出在本机检测到的编码 Agent，并为每个所选 Agent 安装其支持的用户级配置。它还会为每个所选 Agent 添加用户级 Kivgraph 指令。必要时，它会初始化空的 Kivgraph 配置，但不会注册代码仓库或运行索引。脚本化设置时可重复使用 --target TARGET；省略该参数则会打开选择器。

使用 ↑/↓（或 j/k）移动，按 space 切换 Agent，按 a 全选，按 n 全不选，按 Enter 确认，按 q 或 Esc 取消。选择完成后会询问是否启用守护进程；--daemon 表示无需询问即启用，--stdio 则为每个客户端保留一个 serve 进程。--dry-run 会预览所有配置项，但不会写入。

支持的 MCP 目标包括 claude-code、claude-desktop、codex、opencode 和 oh-my-pi。支持的技能目标包括 claude-code、codex、opencode 和 oh-my-pi；Claude Desktop 没有本地技能目标。独立命令默认使用 user；使用 --scope project 可配置项目本地设置。使用 --dry-run 可在不写入的情况下检查计划。遇到现有的不兼容条目时会报错停止；要替换或移除条目，必须使用 --force。现有文件会以模式 0600 原子写入，并在替换或移除前备份为 *.kivgraph.bak。

工具调用前的拦截器支持 claude-code、claude-desktop、codex、opencode 和 oh-my-pi。用户级配置会在 ~/.omp/agent/extensions/ 下为 Oh My Pi 安装原生扩展，项目级配置则安装到 .omp/extensions/。如果无法获得图谱查询结果，拦截器会默认放行。以 rtk rg ... 或 rtk proxy rg ... 形式封装的搜索会按其内部命令分类，而 RTK 自身的命令则不受影响。

将 Kivgraph 添加到用户级 Agent 指令

将 Kivgraph 导航规则添加到编码 Agent 加载的用户上下文中：

kivgraph instructions install
# The selector can install one or more coding-agent destinations.
kivgraph instructions install --agent codex
kivgraph instructions install --agent claude
kivgraph instructions install --agent omp

如果未指定 --agent 或 --file，交互式选择器会让你选择一个或多个编码 Agent。每个安装都会在客户端配置旁创建一个 KIVGRAPH.md 提示词。Codex（~/.codex/AGENTS.md）、Claude Code/Desktop（~/.claude/CLAUDE.md）和 Oh My Pi（~/.omp/agent/AGENTS.md）只会收到指向 KIVGRAPH.md 的简短托管绝对路径引用。OpenCode 则会将其规范路径添加到 ~/.config/opencode/opencode.json 的原生 instructions 列表中；它不会修改 OpenCode 的 AGENTS.md。选择器会对共用的目标去重。现有指令会保留，托管引用具有幂等性，--dry-run 会预览变更。要替换已编辑的 Kivgraph 提示词或引用，必须使用 --force。保留 --file 是为了兼容性，该参数会选择所有匹配的全局客户端；编写新的自动化时，建议使用 --agent。此命令不会修改代码仓库指令。如果希望在一个流程中添加这些指令和兼容的客户端集成，请使用 configure；也可以继续使用各个独立命令进行明确变更。

设置 CODEX_HOME 后，它会替代 ~/.codex；设置 PI_CODING_AGENT_DIR 后，它会替代 ~/.omp/agent，与这些客户端使用的配置根目录保持一致。 显式检查或移除注册项：

kivgraph mcp status --target claude-code --scope user
kivgraph mcp remove --target claude-code --scope user
kivgraph skill status --target claude-code --scope user
kivgraph skill remove --target claude-code --scope user
kivgraph hook status --target claude-code --scope user
kivgraph hook remove --target claude-code --scope user

启动 MCP 服务前，先初始化并发布图谱：

kivgraph init \
  --repository project=/absolute/path/to/project \
  --languages go,typescript,rust
kivgraph doctor
kivgraph index --full

init 会写入一份独立完整的配置：如果 --config 指向其他位置，其状态、缓存和注册表都会位于该目录下，因此临时索引不会触及真实索引。index --full 会原子地重新发布——任何阶段发生故障，都会保留上一代图谱继续提供服务。已在运行的服务会自行跟进新一代图谱。

在单个项目中执行时，kivgraph index 会检测该项目支持的语言，创建或复用 .kivgraph/，在本地注册表中将当前项目注册为 project，并执行相同的完整重建。如果既未指定 --config，也未指定 --repositories，它不会更改共享用户注册表；这些选项用于有意指定要更新的配置和注册表。若要使用显式的已注册仓库工作流，请执行 kivgraph index --full；两种方式都遵循完整索引约定。 该命令不会隐式安装语言工具链；kivgraph doctor 会报告主机上缺少的任何前置条件。Kivgraph 也支持显式管理可选分析器：

kivgraph toolchain status
kivgraph toolchain install pyright
kivgraph index --full

toolchain install pyright 会将 Pyright 固定到特定版本并安装在 Kivgraph 的状态目录下，然后在所选配置中启用精确的 Python 分析。对于项目本地配置，请传入 --config .kivgraph/config.yaml。移除分析器需要显式确认；如果所选配置使用受管理的分析器，移除后会恢复捆绑的 Python 后备分析器：

kivgraph toolchain remove pyright --yes

首次安装需要 npm 和网络连接。之后的状态检查以及复用已安装版本均可离线进行。

该命令系列有意采用与语言无关的设计；更多受管理的分析器可以使用它，而无需让 index 修改主机或仓库。

日常使用：

kivgraph graph status      # what is published, and whether a tree has moved
kivgraph doctor            # toolchains, storage, and the type-checking ceiling
kivgraph ui                # read-only 3D viewer, default 0.0.0.0:7777
kivgraph logs --follow     # aligned history of what it indexed, served and queried
kivgraph tool-stats        # per-tool cost, calls, and failures
kivgraph stop              # terminate this user's serve and ui, never an index
kivgraph clean --keep-active

kivgraph ui 默认绑定非环回地址，因为图谱在仓库所在的位置建立索引，却会在其他地方查看；它没有身份验证，因此会准确记录其暴露的内容，而 --addr 可限制其访问地址。

logs 和 tool-stats 会读取状态目录中的仅追加记录，而不是向服务器查询，这也是它们能够提供结果的原因：serve 维护的各工具计数器在启动时创建，在停止时消失。 读取文件也能让结果涵盖曾经运行过的所有服务。

logs 会以固定列的表格呈现结果。工具行包含有界且经过允许列表筛选的查询摘要：find_by_intent 会记录其确切的 intent 和任何 keywords；不透明游标、同意标记、稳定键和绝对项目路径则不会写入记录。--json 会保留各条仅追加记录。 SYMBOL_NOT_FOUND 会呈现为中性的 NOT_FOUND 状态，结果数为零，而不会被视为运行故障。

配置任意 MCP 客户端通过 STDIO 启动服务：

{
  "mcpServers": {
    "kivgraph": {
      "command": "/home/user/.local/bin/kivgraph",
      "args": [
        "serve",
        "--config",
        "/home/user/.config/kivgraph/config.yaml"
      ]
    }
  }
}

kivgraph serve 可以在图谱尚未生成时启动：如果没有已发布的图谱版本，它会完成握手，不发布查询工具，并将重建命令写入 instructions。客户端会自行启动该进程，因此退出会被视为崩溃。它只通过 stdout 写入 MCP 帧，通过 stderr 写入日志。

要求

• 从源代码构建需要 Go 1.26 或更高版本。索引器会使用链接到二进制文件中的 go/types 进行类型检查，因此只能读取使用其自身语言版本或更早版本编写的仓库和依赖项；kivgraph doctor 会报告此版本上限。
• 索引 Rust 需要 cargo 和 rust-analyzer。发布包中包含分析器，但不包含 Rust 工具链。
• 索引 TypeScript 需要 Node.js 22 或更高版本来运行工作进程。
• 索引 Python 需要 Python 3.10 或更高版本来运行随附的工作进程。这是一种语法感知的回退方案，会明确报告动态或无法解析的名称；精确模式还需要兼容 Pyright 的语言服务器。
• 索引 Dart 需要 dart 可执行文件；Flutter 安装会提供它。加载器使用 Analysis Server 协议，不会修改 Flutter 项目。

图谱包含什么，以及它拒绝什么

只有在证据充分且来源正确时，边才会标记为 EXACT。边绝不会仅根据名称、路径、别名或单个候选项创建；无法解析的引用不会被丢弃，而是会连同原因、仓库和语言一起以 UNRESOLVED 状态发布。graph_status 会分别报告这两类引用。

因此，有些答案表现为缺失，而不是边。索引 Rust 标准库时，impl Add for u32 由宏生成，不存在于任何源代码范围中，因此每个符号只会报告一次 PROVIDER_DEFINITION_NOT_INDEXED，而不会创建无人能够打开的边。

Kivgraph 根据机器派生的提供方（目前是 Rust 标准库，按工具链版本命名为 rust:1.96.1）默认不会出现在读取结果中：一个工具链包含约两万个符号，搜索 Clone 时会返回 core。include_derived 可请求包含这些符号，而 graph_status 会单独列出它们的贡献，让总数保持清晰易读。

开发

make build
make test
make semantic-coverage
make test-ladybug

make test-ladybug 是运行链接固定版本原生库的标签的唯一受支持方式。贡献规范见 AGENTS.md，CLAUDE.md 中有指向该文件的链接。

make semantic-coverage 是 Go、TypeScript、Python 和 Dart 的发布门槛。它会验证 testdata/semantic-coverage/manifest.json 中的机器可读矩阵，运行精确 TypeScript、Go 和 Dart 测试套件，并要求兼容 Pyright 的语言服务器来运行精确 Python 测试套件。如果某项能力有测试样例，却没有可执行的回归测试，则该语言不会被视为已完成。

存储和图谱基准测试

LadybugDB 资格验证、合成语料生成器、加载和查询基准测试，以及 doctor、rebuild、rollback 和 snapshot 命令，均记录在 docs/development/storage-benchmarks.md 中。 文档最后给出结论 ACCEPT_LADYBUGDB_WITH_LIMITS。

公共网站

landing/ 包含着陆页和用户文档。它不会随任何发布包提供，可通过 make landing-check 和 make landing-build 验证，并在端口 6767 上提供服务。它发布的内容、MCP 参考资料的采集方式，以及仍待解决的问题，均记录在 docs/development/landing-site.md 中。

结构

cmd/kivgraph/   Main executable.
internal/        Kivgraph internal packages.
ts-worker/        TypeScript worker.
web/              Graph viewer served by `kivgraph ui`.
landing/          Landing page and documentation site (not part of any release).
testdata/         Test fixtures and corpora.
benchmarks/       Benchmark results.
docs/             Documentation and ADRs.
scripts/          Auxiliary automation.

许可证

Kivgraph 根据 Apache License 2.0 进行分发。

第三方许可证

随 Kivgraph 分发的依赖项的声明和许可证记录在 THIRD_PARTY_NOTICES.md 中。每当向可分发产品添加依赖项时，都会更新此列表。